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

2025-12-19 05:17:07 +08:00
parent d2842d46db
commit d2161690a1
7 changed files with 343 additions and 67 deletions
--- a/aide-marketplace/aide-plugin/commands/user-docs.md
+++ b/aide-marketplace/aide-plugin/commands/user-docs.md
@@ -2,6 +2,10 @@

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

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

 ## 前置准备
@@ -12,6 +16,25 @@

 ## 开始

+### 检查计划文件
+
+```bash
+aide config get user_docs.docs_plan_path
+```
+
+读取配置的计划文件路径，检查文件是否存在。
+
+**根据计划文件状态决定流程**：
+
+- **计划文件不存在** → 进入**分析和计划阶段**
+- **计划文件存在** → 进入**接续执行阶段**
+
+---
+
+## 分析和计划阶段
+
+当计划文件不存在时执行此流程。
+
 ### 1. 检查前置条件

 #### 1.1 检查 README 规范文件
@@ -48,11 +71,9 @@ aide config get docs.path
 - **先执行 /aide:docs**（推荐）
 - **继续生成文档**（基于代码分析）

---
+### 2. 分析项目

-## 2. 分析项目
-
-### 2.1 读取项目信息
+#### 2.1 读取项目信息

 **优先级**：

@@ -68,7 +89,7 @@ aide config get docs.path
   - 分析目录结构
   - 识别主要功能模块

-### 2.2 确定项目类型
+#### 2.2 确定项目类型

 | 类型 | 特征 |
 |------|------|
@@ -76,11 +97,11 @@ aide config get docs.path
 | 单体程序 | 单一主项目，可能有子模块 |
 | 多项目仓库 | 包含多个独立子项目 |

---
+### 3. 规划文档结构

-## 3. 规划文档结构
+根据项目类型选择文档结构模板：

-### 3.1 纯文档/材料类项目
+#### 3.1 纯文档/材料类项目

 ```
 docs/
@@ -91,7 +112,7 @@ docs/
    └── topic-2.md
 ```

-### 3.2 单体程序项目
+#### 3.2 单体程序项目

 ```
 docs/
@@ -106,7 +127,7 @@ docs/
    └── ...
 ```

-### 3.3 多项目仓库
+#### 3.3 多项目仓库

 ```
 docs/
@@ -122,11 +143,57 @@ docs/
    └── ...
 ```

---
+### 4. 生成计划文档

-## 4. 向用户确认结构
+在配置的路径创建计划文件：

-向用户展示规划的文档结构，使用 AskUserQuestion 确认：
+```bash
+aide config get user_docs.docs_plan_path
+```
+
+计划文档格式：
+
+```markdown
+# 用户文档生成计划
+
+## 项目概述
+
+{{基于项目文档/分析的简要描述}}
+
+## 项目类型
+
+{{纯文档/单体程序/多项目仓库}}
+
+## 文档结构
+
+```
+{{PLANNED_STRUCTURE}}
+```
+
+## 执行步骤
+
+| # | 步骤描述 | 状态 |
+|---|----------|------|
+| 1 | 创建目录结构 | - |
+| 2 | 生成 {{doc-1}}.md | - |
+| 3 | 生成 {{doc-2}}.md | - |
+| ... | ... | - |
+| N | 更新 README 链接 | - |
+
+## 当前进度
+
+- 当前步骤：0（未开始）
+- 已完成：0 / {{TOTAL_STEPS}}
+- 最后更新：{{TIMESTAMP}}
+
+## 备注
+
+（执行过程中的记录）
+```
+
+### 5. 用户确认
+
+向用户展示规划的文档结构：

 > 根据项目分析，建议创建以下文档结构：
 >
@@ -134,41 +201,110 @@ docs/
 > {{PLANNED_STRUCTURE}}
 > ```
 >
+> **预估步骤**：共 {{TOTAL_STEPS}} 步
+>
 > 是否按此结构生成文档？

 **选项**：
- **确认生成**（推荐）
+- **开始执行**（推荐）
 - **调整结构**（自定义）
+- **稍后执行**

-如用户选择调整，通过对话确认最终结构。
+如用户选择调整，通过对话确认最终结构后更新计划文档。
+
+如选择开始执行，进入步骤执行流程。

 ---

-## 5. 生成文档
+## 接续执行阶段

-### 5.1 检查现有文档
+当计划文件存在时执行此流程。

-```bash
-aide config get user_docs.docs_path
-```
+### 1. 读取计划文档

-检查 docs 目录是否存在以及包含的内容。
+解析计划文件获取：
+- 项目概述和类型
+- 文档结构
+- 执行步骤列表和状态
+- 当前进度
+- 历史备注

-### 5.2 处理现有内容
+### 2. 显示进度

-**首次生成**：直接创建所有文档
+> **用户文档生成进度**
+>
+> 项目类型：{{PROJECT_TYPE}}
+> 当前步骤：{{CURRENT_STEP}}
+> 已完成步骤：{{COMPLETED_STEPS}}/{{TOTAL_STEPS}}
+> 上次更新：{{LAST_UPDATE}}

-**增量更新**（docs 目录已存在）：
+### 3. 确认继续

-对于每个文档文件：
+使用 AskUserQuestion：

-1. **新文件**：直接创建
-2. **已存在的文件**：
-   - 检查是否有 `<!-- USER-EDIT: DO NOT MODIFY ABOVE -->` 标记
-   - 保留标记以上的用户编辑内容
-   - 更新标记以下的自动生成内容
+> 是否从当前进度继续执行？

-### 5.3 文档内容规范
+**选项**：
+- **继续执行**（推荐）
+- **查看计划详情**
+- **重新开始**（清空进度）
+
+如选择重新开始，删除计划文件后进入分析和计划阶段。
+
+---
+
+## 步骤执行流程
+
+### 执行单个步骤
+
+对于每个步骤：
+
+1. **显示当前任务**：
+   > 正在执行：{{STEP_DESCRIPTION}}
+
+2. **执行步骤**：
+
+   **步骤类型 A：创建目录结构**
+   - 检查 docs 目录是否存在
+   - 创建必要的子目录
+
+   **步骤类型 B：生成文档文件**
+   - 分析相关代码/文档
+   - 根据模板生成内容
+   - 写入文件
+
+   **步骤类型 C：更新 README 链接**
+   - 检查 README 中的文档链接部分
+   - 更新链接指向新生成的文档
+
+3. **更新计划文档**：
+   - 标记步骤完成（`✓`）
+   - 更新当前进度
+   - 记录时间戳
+
+4. **保存产出**：
+   - 写入生成的文档文件
+
+### 步骤间询问
+
+每完成一个步骤后询问：
+
+> 步骤 {{STEP_ID}} 已完成：{{STEP_DESCRIPTION}}
+>
+> 是否继续下一步？
+
+**选项**：
+- **继续**（推荐）
+- **查看产出**
+- **暂停（保存进度）**
+
+如选择暂停，保存进度后结束本次执行。
+
+---
+
+## 文档内容规范
+
+### 文档文件结构

 每个文档文件应包含：

@@ -185,7 +321,7 @@ aide config get user_docs.docs_path
 {{用户自定义内容区域}}
 ```

-### 5.4 生成各文档
+### 各类文档内容要求

 #### getting-started.md（快速开始）

@@ -221,35 +357,27 @@ aide config get user_docs.docs_path

 ---

-## 6. 更新 README
+## 完成流程

-如果 README 中有文档链接部分，更新链接指向新生成的文档：
+当所有步骤完成时：

-```markdown
-## 文档
+1. **更新计划文档**：
+   - 标记所有步骤完成
+   - 记录完成时间

- [快速开始](docs/getting-started.md)
- [安装指南](docs/installation.md)
- [使用说明](docs/usage.md)
- [配置说明](docs/configuration.md)
- [API 文档](docs/api/index.md)
-```
+2. **显示完成提示**：

---
-
-## 7. 完成提示
-
-> 用户文档已生成：`{{DOCS_PATH}}/`
->
-> 生成的文档：
-> {{GENERATED_FILES_LIST}}
->
-> 建议：
-> - 检查生成的内容是否准确
-> - 在 `<!-- USER-EDIT -->` 标记下方添加自定义内容
-> - 自定义内容不会被后续更新覆盖
->
-> 如需重新生成，可再次运行 `/aide:user-docs`。
+   > 用户文档已生成：`{{DOCS_PATH}}/`
+   >
+   > 生成的文档：
+   > {{GENERATED_FILES_LIST}}
+   >
+   > 建议：
+   > - 检查生成的内容是否准确
+   > - 在 `<!-- USER-EDIT -->` 标记下方添加自定义内容
+   > - 自定义内容不会被后续更新覆盖
+   >
+   > 如需重新生成，可删除计划文件后再次运行 `/aide:user-docs`。

 ---

@@ -258,13 +386,16 @@ aide config get user_docs.docs_path
 | 配置项 | 默认值 | 说明 |
 |--------|--------|------|
 | `user_docs.docs_path` | `docs` | 用户文档目录路径 |
+| `user_docs.docs_plan_path` | `docs/user-docs-plan.md` | 计划文件路径 |
 | `user_docs.rules_path` | `make-readme-rules.md` | README 规范文件路径 |

 ---

 ## 注意事项

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