sayurinana/agent-aide
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
sayurinana(vm)
2025-12-19 05:17:07 +08:00
parent d2842d46db
commit d2161690a1
7 changed files with 343 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
.aide/branches.json
View File

@@ -1,5 +1,5 @@
{
"next_number": 23,
"next_number": 24,
"branches": [
{
"number": 1,
@@ -258,6 +258,18 @@
"status": "finished",
"end_commit": "76026e4b62996b667b2f788a2cf6e34cc79cebfb",
"finished_at": "2025-12-19T04:50:04+08:00"
},
{
"number": 23,
"branch_name": "aide/023",
"source_branch": "master",
"start_commit": "d2842d46dbef9b7fe9f85749a9d2c8feae4ee528",
"task_id": "2025-12-19T05-00-29",
"task_summary": "开始任务准备: 为 user-docs 添加分步执行和接续执行能力",
"started_at": "2025-12-19T05:00:29+08:00",
"status": "finished",
"end_commit": "91c9bca5d5356e7c06d018fab0138152ab96c56a",
"finished_at": "2025-12-19T05:17:07+08:00"
}
]
}

11
.aide/branches.md
View File

@@ -1,5 +1,16 @@
# Git 分支概况
## aide/023
- **任务**: 开始任务准备: 为 user-docs 添加分步执行和接续执行能力
- **任务ID**: 2025-12-19T05-00-29
- **源分支**: master
- **起始提交**: d2842d4
- **结束提交**: 91c9bca
- **状态**: finished
- **起始时间**: 2025-12-19 05:00
- **结束时间**: 2025-12-19 05:17
## aide/022
- **任务**: 开始任务准备: 调整 aide 体系的 finish 清理、提交信息和 decide 界面

3
.aide/config.toml
View File

@@ -193,6 +193,9 @@ diagram_path = ".aide/diagrams"
# 支持绝对路径或相对于 aide-program 目录的相对路径
# 默认使用 aide-program/lib/plantuml.jar
jar_path = "lib/plantuml.jar"
font_name = "PingFang SC"
dpi = 300
scale = 0.5
# Java 命令路径（可选）
# 默认使用系统 PATH 中的 java

115
.aide/logs/2025-12-19T05-00-29-status.json Normal file
View File

@@ -0,0 +1,115 @@
{
"task_id": "2025-12-19T05-00-29",
"current_phase": "finish",
"current_step": 13,
"started_at": "2025-12-19T05:00:29+08:00",
"history": [
{
"timestamp": "2025-12-19T05:00:29+08:00",
"action": "start",
"phase": "task-optimize",
"step": 1,
"summary": "开始任务准备: 为 user-docs 添加分步执行和接续执行能力",
"git_commit": "6bae19a71c609d86f2da23c28cf2385402c49f5d"
},
{
"timestamp": "2025-12-19T05:04:30+08:00",
"action": "next-step",
"phase": "task-optimize",
"step": 2,
"summary": "任务细则已确认",
"git_commit": "8cd54588b37ef771b1e2ac61a328b1565c7c93b1"
},
{
"timestamp": "2025-12-19T05:09:48+08:00",
"action": "next-part",
"phase": "flow-design",
"step": 3,
"summary": "进入流程设计环节",
"git_commit": "009e1733196dcba594b5916ad3887846d616c795"
},
{
"timestamp": "2025-12-19T05:10:49+08:00",
"action": "next-step",
"phase": "flow-design",
"step": 4,
"summary": "流程图设计完成",
"git_commit": "a466de3d80e5e25fdda9b7f16063d464101480fe"
},
{
"timestamp": "2025-12-19T05:11:10+08:00",
"action": "next-part",
"phase": "impl",
"step": 5,
"summary": "流程设计完成，进入实现环节",
"git_commit": "2f8de410688c7de42c4799779e377fafe3b86a52"
},
{
"timestamp": "2025-12-19T05:12:49+08:00",
"action": "next-step",
"phase": "impl",
"step": 6,
"summary": "完成 user-docs.md 重构",
"git_commit": "ee4c1f2e6a675d3021c84e2a9523a2dddcc0afe5"
},
{
"timestamp": "2025-12-19T05:13:24+08:00",
"action": "next-part",
"phase": "verify",
"step": 7,
"summary": "实现完成，进入验证环节",
"git_commit": "5692f32827531de7059df393b0270eb169f35557"
},
{
"timestamp": "2025-12-19T05:14:04+08:00",
"action": "next-step",
"phase": "verify",
"step": 8,
"summary": "验证完成: 所有标准通过",
"git_commit": "167eb17787dcc5ca775a20d2efd2049df6b81c75"
},
{
"timestamp": "2025-12-19T05:14:38+08:00",
"action": "next-part",
"phase": "docs",
"step": 9,
"summary": "验证通过，进入文档环节",
"git_commit": "30ae787d5009708fccd8eb30bfddbc9f9c7f4be7"
},
{
"timestamp": "2025-12-19T05:15:24+08:00",
"action": "next-step",
"phase": "docs",
"step": 10,
"summary": "文档更新完成",
"git_commit": "bf829bc5cae3a264118d34bd1194799b94b6c579"
},
{
"timestamp": "2025-12-19T05:15:38+08:00",
"action": "next-part",
"phase": "confirm",
"step": 11,
"summary": "文档更新完成，进入用户确认环节",
"git_commit": "b2588d1b761956d0584ff292ff854ff7fa535f1c"
},
{
"timestamp": "2025-12-19T05:16:50+08:00",
"action": "next-step",
"phase": "confirm",
"step": 12,
"summary": "用户确认通过",
"git_commit": "d58f754bf01b9e8396b084fcacc1557b6cb33a89"
},
{
"timestamp": "2025-12-19T05:17:07+08:00",
"action": "next-part",
"phase": "finish",
"step": 13,
"summary": "用户确认通过，进入收尾",
"git_commit": "91c9bca5d5356e7c06d018fab0138152ab96c56a"
}
],
"source_branch": "master",
"start_commit": "d2842d46dbef9b7fe9f85749a9d2c8feae4ee528",
"task_branch": "aide/023"
}

9
CHANGELOG.md
View File

@@ -6,6 +6,15 @@
### 优化
**user-docs 分步执行和接续执行能力**
- 重构 `commands/user-docs.md`，添加与 `user-graph.md` 相同的分步执行机制
- 新增"分析和计划阶段"：首次运行时分析项目、规划结构、生成计划文档
- 新增"接续执行阶段"：后续运行时读取计划、显示进度、支持接续
- 新增"步骤执行流程"：每步完成后更新计划、支持暂停保存进度
- 新增配置项 `user_docs.docs_plan_path`（默认 `docs/user-docs-plan.md`）
- 适用于大型项目的文档生成，支持分多次对话完成
**finish 清理代码移除**
- 移除 `run.md` 和 `auto-run.md` 中的"清理临时文件"指令和 `aide flow next-step "任务完成"` 命令

253
aide-marketplace/aide-plugin/commands/user-docs.md
View File

@@ -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 中的文档链接自动更新

5
task-now.md
View File

@@ -1,5 +0,0 @@
我之前有一次任务的内容，我把它的节选保存在了 @cache/old-task.md 文件中，
现在那部分内容已经被实现为了commands下的readme.md、user-docs.md和user-graph.md，
我现在想要做的是，让user-docs具有和user-graph一样的**分步执行**和**接续执行**能力，