sayurinana/agent-aide

Fork 0

Files

sayurinana(vm) d2161690a1 完成：aide/023 - 开始任务准备: 为 user-docs 添加分步执行和接续执行能力

2025-12-19 05:17:07 +08:00

9.0 KiB

Raw Blame History

Aide 用户文档生成

你正在执行 Aide 用户文档生成流程。这个命令帮助用户在 docs 目录下创建面向用户的详细文档。

此命令支持分步执行和接续执行，适用于大型项目。

这可能是一个非常长的任务，因此规划您的工作可能会很有益。**建议花费您的整个输出上下文来处理任务 - 只需确保您不会在有大量未提交的工作时用尽上下文。**继续系统地工作，直到您完成此任务。**您的上下文窗口将在接近其限制时自动压缩，允许您从中断的地方继续无限期地工作。因此，不要因为令牌预算问题而提前停止任务。**当您接近令牌预算限制时，在上下文窗口刷新前将您当前的进度和状态保存到内存中。始终尽可能坚持和自主，并完全完成任务，即使您的预算即将用尽。无论剩余上下文如何，永远不要人为地提前停止任何任务。

前置准备

首先触发 readme-templates skill 学习模板使用方法。

开始

检查计划文件

aide config get user_docs.docs_plan_path

读取配置的计划文件路径，检查文件是否存在。

根据计划文件状态决定流程：

计划文件不存在 → 进入分析和计划阶段
计划文件存在 → 进入接续执行阶段

分析和计划阶段

当计划文件不存在时执行此流程。

1. 检查前置条件

1.1 检查 README 规范文件

aide config get user_docs.rules_path

如果规范文件不存在：

检测到 README 编写规范（make-readme-rules.md）不存在。

建议先执行 /aide:readme 创建规范文件。规范文件定义了项目的文档风格，用户文档应与 README 保持一致的风格。

使用 AskUserQuestion 询问：

先执行 /aide:readme（推荐）
继续生成文档（使用默认风格）

1.2 检查项目文档

aide config get docs.path

如果项目文档目录（.aide/project-docs/）不存在：

检测到面向 LLM 的项目文档（.aide/project-docs/）不存在。

建议先执行 /aide:docs 和 /aide:load 创建项目文档。项目文档可以帮助生成更准确、更完整的用户文档。

使用 AskUserQuestion 询问：

先执行 /aide:docs（推荐）
继续生成文档（基于代码分析）

2. 分析项目

2.1 读取项目信息

优先级：

项目文档（如果存在）：
- 读取 .aide/project-docs/README.md 获取项目概述
- 阅读相关区块文档了解详细信息
README（如果存在）：
- 读取 README.md 了解项目定位
代码分析：
- 分析配置文件（package.json、Cargo.toml、pyproject.toml 等）
- 分析目录结构
- 识别主要功能模块

2.2 确定项目类型

类型	特征
纯文档/材料	主要是 markdown 文件，无代码
单体程序	单一主项目，可能有子模块
多项目仓库	包含多个独立子项目

3. 规划文档结构

根据项目类型选择文档结构模板：

3.1 纯文档/材料类项目

docs/
├── overview.md          # 内容概述
├── navigation.md        # 导航指南
└── topics/              # 主题分类
    ├── topic-1.md
    └── topic-2.md

3.2 单体程序项目

docs/
├── getting-started.md   # 快速开始
├── installation.md      # 安装指南
├── usage.md             # 使用说明
├── configuration.md     # 配置说明（如有配置）
├── api/                 # API 文档（如有）
│   ├── index.md
│   └── ...
└── guides/              # 使用指南
    └── ...

3.3 多项目仓库

docs/
├── overview.md          # 仓库概述
├── projects/            # 各项目文档
│   ├── project-a/
│   │   ├── README.md
│   │   └── ...
│   └── project-b/
│       ├── README.md
│       └── ...
└── shared/              # 共享文档
    └── ...

4. 生成计划文档

在配置的路径创建计划文件：

aide config get user_docs.docs_plan_path

计划文档格式：

# 用户文档生成计划

## 项目概述

{{基于项目文档/分析的简要描述}}

## 项目类型

{{纯文档/单体程序/多项目仓库}}

## 文档结构


## 执行步骤

| # | 步骤描述 | 状态 |
|---|----------|------|
| 1 | 创建目录结构 | - |
| 2 | 生成 {{doc-1}}.md | - |
| 3 | 生成 {{doc-2}}.md | - |
| ... | ... | - |
| N | 更新 README 链接 | - |

## 当前进度

- 当前步骤：0（未开始）
- 已完成：0 / {{TOTAL_STEPS}}
- 最后更新：{{TIMESTAMP}}

## 备注

（执行过程中的记录）

5. 用户确认

向用户展示规划的文档结构：

根据项目分析，建议创建以下文档结构：
{{PLANNED_STRUCTURE}}
预估步骤：共 {{TOTAL_STEPS}} 步

是否按此结构生成文档？

选项：

开始执行（推荐）
调整结构（自定义）
稍后执行

如用户选择调整，通过对话确认最终结构后更新计划文档。

如选择开始执行，进入步骤执行流程。

接续执行阶段

当计划文件存在时执行此流程。

1. 读取计划文档

解析计划文件获取：

项目概述和类型
文档结构
执行步骤列表和状态
当前进度
历史备注

2. 显示进度

用户文档生成进度

项目类型：{{PROJECT_TYPE}} 当前步骤：{{CURRENT_STEP}} 已完成步骤：{{COMPLETED_STEPS}}/{{TOTAL_STEPS}} 上次更新：{{LAST_UPDATE}}

3. 确认继续

使用 AskUserQuestion：

是否从当前进度继续执行？

选项：

继续执行（推荐）
查看计划详情
重新开始（清空进度）

如选择重新开始，删除计划文件后进入分析和计划阶段。

步骤执行流程

执行单个步骤

对于每个步骤：

显示当前任务：

正在执行：{{STEP_DESCRIPTION}}
执行步骤：

步骤类型 A：创建目录结构
- 检查 docs 目录是否存在
- 创建必要的子目录
步骤类型 B：生成文档文件
- 分析相关代码/文档
- 根据模板生成内容
- 写入文件
步骤类型 C：更新 README 链接
- 检查 README 中的文档链接部分
- 更新链接指向新生成的文档
更新计划文档：
- 标记步骤完成（✓）
- 更新当前进度
- 记录时间戳
保存产出：
- 写入生成的文档文件

步骤间询问

每完成一个步骤后询问：

步骤 {{STEP_ID}} 已完成：{{STEP_DESCRIPTION}}

是否继续下一步？

选项：

继续（推荐）
查看产出
暂停（保存进度）

如选择暂停，保存进度后结束本次执行。

文档内容规范

文档文件结构

每个文档文件应包含：

# 文档标题

<!-- AUTO-GENERATED: This section is automatically maintained -->

{{自动生成内容}}

<!-- USER-EDIT: DO NOT MODIFY ABOVE -->
<!-- You can add custom content below -->

{{用户自定义内容区域}}

各类文档内容要求

getting-started.md（快速开始）

最小可运行示例
简洁的步骤说明
链接到详细文档

installation.md（安装指南）

系统要求
多种安装方式
安装验证步骤
常见问题

usage.md（使用说明）

基本用法
常用命令/操作
参数说明

configuration.md（配置说明）

配置文件位置
配置项详解
配置示例

api/（API 文档）

按模块组织
函数签名
参数说明
使用示例

完成流程

当所有步骤完成时：

更新计划文档：
- 标记所有步骤完成
- 记录完成时间
显示完成提示：
用户文档已生成：{{DOCS_PATH}}/

生成的文档： {{GENERATED_FILES_LIST}}

建议：
- 检查生成的内容是否准确
- 在  标记下方添加自定义内容
- 自定义内容不会被后续更新覆盖
如需重新生成，可删除计划文件后再次运行 /aide:user-docs。

配置项

配置项	默认值	说明
`user_docs.docs_path`	`docs`	用户文档目录路径
`user_docs.docs_plan_path`	`docs/user-docs-plan.md`	计划文件路径
`user_docs.rules_path`	`make-readme-rules.md`	README 规范文件路径

注意事项

分步执行：大型项目建议分多次对话完成
进度持久化：进度保存在计划文件，可随时接续
保留用户编辑：使用标记区分自动生成和用户编辑的内容
风格一致：文档风格与 README 保持一致
增量更新：多次运行不会覆盖用户自定义内容
链接同步：README 中的文档链接自动更新

9.0 KiB Raw Blame History Unescape Escape