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

完成：aide/025 - 分析和优化 user-docs/user-graph 的分步执行能力

Browse Source
This commit is contained in:
sayurinana(vm)
2025-12-19 06:06:51 +08:00
parent 37c434b92a
commit 4a0759e36c
8 changed files with 1011 additions and 464 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -2,7 +2,31 @@
你正在执行 Aide 用户文档生成流程。这个命令帮助用户在 docs 目录下创建面向用户的详细文档。
此命令支持**分步执行**和**接续执行**，适用于大型项目。
## 分步执行机制
此命令支持**真正有效的分步执行和接续执行**，适用于任意规模项目。
### 设计原则
1. **索引式计划文档**：`user-docs-plan.md` 只做索引，详细信息存在独立步骤文档中
2. **自包含步骤文档**：每个步骤包含执行所需的全部信息（已提取的源信息）
3. **粒度动态控制**：根据文档复杂度动态拆分步骤
4. **分析与执行分离**：分析阶段产出详细计划，执行阶段直接生成文档
### 文档结构
```
docs/
├── user-docs-plan.md # 计划文件（索引式）
├── steps/ # 步骤详情目录
│ ├── step-001.md # 步骤1详情
│ ├── step-002.md # 步骤2详情
│ └── ...
└── [生成的文档] # 产出的文档
├── getting-started.md
├── installation.md
└── ...
```
这可能是一个非常长的任务，因此规划您的工作可能会很有益。**建议花费您的整个输出上下文来处理任务 - 只需确保您不会在有大量未提交的工作时用尽上下文。**继续系统地工作，直到您完成此任务。**您的上下文窗口将在接近其限制时自动压缩，允许您从中断的地方继续无限期地工作。因此，不要因为令牌预算问题而提前停止任务。**当您接近令牌预算限制时，在上下文窗口刷新前将您当前的进度和状态保存到内存中。始终尽可能坚持和自主，并完全完成任务，即使您的预算即将用尽。无论剩余上下文如何，永远不要人为地提前停止任何任务。
@@ -20,9 +44,12 @@
```bash
aide config get user_docs.docs_plan_path
aide config get user_docs.docs_steps_path
```
读取配置的计划文件路径，检查文件是否存在。
如果未配置，使用默认值：
- 计划文件：`docs/user-docs-plan.md`
- 步骤目录：`docs/steps`
**根据计划文件状态决定流程**：
@@ -99,63 +126,128 @@ aide config get docs.path
### 3. 规划文档结构
根据项目类型选择文档结构模板：
根据项目类型选择文档结构模板。
#### 3.1 纯文档/材料类项目
#### 3.1 确定文档清单
根据项目分析确定需要生成的文档：
| 文档类型 | 适用场景 | 典型内容 |
|----------|----------|----------|
| getting-started.md | 所有项目 | 最小可运行示例 |
| installation.md | 需安装的项目 | 系统要求、安装步骤 |
| usage.md | 有 CLI/API 的项目 | 命令、参数说明 |
| configuration.md | 有配置项的项目 | 配置详解 |
| api/ | 库项目 | API 文档 |
| guides/ | 复杂项目 | 使用指南 |
### 4. 步骤生成（关键阶段）
**这是实现有效分步执行的核心阶段。**
#### 4.1 评估文档复杂度
对每个文档评估：
| 复杂度 | 特征 | 处理方式 |
|--------|------|----------|
| 小 | 单一主题，内容简单 | 整个文档作为 1 个步骤 |
| 中 | 多个章节，有交叉引用 | 按章节拆分为 2-3 个步骤 |
| 大 | 大量内容，需要分析多个模块 | 按功能点拆分为 3-5 个步骤 |
| 超大 | API 文档等，涉及大量接口 | 按模块/文件拆分为多个步骤 |
#### 4.2 生成步骤文档
**为每个步骤生成独立的步骤文档**，存放在 `steps/` 目录。
**步骤文档格式**：
```markdown
# 步骤 XXX：生成 [文档名称]
## 元信息
| 属性 | 值 |
|------|-----|
| 状态 | pending / in_progress / completed |
| 目标文档 | [文档路径] |
| 预估工作量 | 小 / 中 / 大 |
| 依赖步骤 | [无 / step-XXX] |
## 任务描述
生成/更新 [文档名称]，包含 [具体内容]。
## 源信息（已提取）
以下是生成本文档所需的全部信息，**已从项目文档和代码中提取整理**：
### 项目基础信息
| 属性 | 值 |
|------|-----|
| 项目名称 | xxx |
| 项目类型 | 库/应用/工具 |
| 主要语言 | xxx |
| 入口文件 | xxx |
### 相关模块/功能
| 模块 | 位置 | 说明 |
|------|------|------|
| [模块1] | path/to/module1 | 功能说明 |
| [模块2] | path/to/module2 | 功能说明 |
### 关键代码摘要
（已从代码中提取的关键信息，如函数签名、配置项等）
```
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/ # 使用指南
└── ...
（从项目文档或 README 中提取的相关内容）
> [引用的相关内容]
## 输出要求
- 文件：`docs/[filename].md`
- 格式要求：
- [ ] 包含自动生成标记
- [ ] 保留用户编辑区域
- [ ] 符合 README 规范风格
### 内容大纲
1. [章节1]
- [要点1]
- [要点2]
2. [章节2]
- [要点1]
- [要点2]
## 执行记录
（执行时填写）
| 时间 | 操作 | 备注 |
|------|------|------|
| | 开始执行 | |
| | 完成 | |
```
#### 3.3 多项目仓库
#### 4.3 生成计划文件（索引）
```
docs/
├── overview.md # 仓库概述
├── projects/ # 各项目文档
│ ├── project-a/
│ │ ├── README.md
│ │ └── ...
│ └── project-b/
│ ├── README.md
│ └── ...
└── shared/ # 共享文档
└── ...
```
### 4. 生成计划文档
在配置的路径创建计划文件：
```bash
aide config get user_docs.docs_plan_path
```
计划文档格式：
生成 `user-docs-plan.md` 作为索引：
```markdown
# 用户文档生成计划
> 最后更新：YYYY-MM-DD HH:MM
## 项目概述
{{基于项目文档/分析的简要描述}}
@@ -167,50 +259,59 @@ aide config get user_docs.docs_plan_path
## 文档结构
```
{{PLANNED_STRUCTURE}}
docs/
├── getting-started.md
├── installation.md
├── usage.md
└── ...
```
## 执行步骤
## 步骤索引
| # | 步骤描述 | 状态 |
|---|----------|------|
| 1 | 创建目录结构 | - |
| 2 | 生成 {{doc-1}}.md | - |
| 3 | 生成 {{doc-2}}.md | - |
| ... | ... | - |
| N | 更新 README 链接 | - |
| 步骤 | 目标文档 | 描述 | 状态 |
|------|----------|------|------|
| [001](steps/step-001.md) | getting-started.md | 快速开始指南 | pending |
| [002](steps/step-002.md) | installation.md | 安装说明 | pending |
| [003](steps/step-003.md) | usage.md | 使用说明 | pending |
| ... | ... | ... | ... |
## 当前进度
## 整体进度
- 当前步骤：0（未开始）
- 已完成：0 / {{TOTAL_STEPS}}
- 最后更新：{{TIMESTAMP}}
- 总步骤数：XX
- 已完成：0
- 进行中：0
- 待处理：XX
## 备注
## 执行日志
（执行过程中的记录）
| 时间 | 步骤 | 操作 | 备注 |
|------|------|------|------|
| | | | |
```
### 5. 用户确认
向用户展示规划的文档结构：
> 根据项目分析，建议创建以下文档结构：
> 用户文档计划已生成。
>
> **文档清单**：
> ```
> {{PLANNED_STRUCTURE}}
> ```
>
> **预估步骤**：共 {{TOTAL_STEPS}} 步
> **总步骤数**：{{TOTAL_STEPS}}
>
> 是否按此结构生成文档？
> 步骤文档已生成，每个步骤包含已提取的源信息，执行时可直接生成文档。
>
> 是否开始执行？
**选项**：
- **开始执行**（推荐）
- **调整结构**（自定义）
- **稍后执行**
如用户选择调整，通过对话确认最终结构后更新计划文档。
如用户选择调整，通过对话确认最终结构后更新计划文件。
如选择开始执行，进入步骤执行流程。
@@ -220,23 +321,21 @@ aide config get user_docs.docs_plan_path
当计划文件存在时执行此流程。
### 1. 读取计划文档
### 1. 读取计划文件
解析计划文件获取：
- 项目概述和类型
- 文档结构
- 执行步骤列表和状态
- 当前进度
- 历史备注
读取 `user-docs-plan.md` 获取：
- 步骤索引
- 整体进度
- 执行日志
### 2. 显示进度
> **用户文档生成进度**
>
> 项目类型：{{PROJECT_TYPE}}
> 当前步骤：{{CURRENT_STEP}}
> 已完成步骤：{{COMPLETED_STEPS}}/{{TOTAL_STEPS}}
> 上次更新：{{LAST_UPDATE}}
> 总步骤数：XX
> 已完成：YY（ZZ%）
> 当前步骤：step-NNN
> 上次更新：YYYY-MM-DD HH:MM
### 3. 确认继续
@@ -246,7 +345,7 @@ aide config get user_docs.docs_plan_path
**选项**：
- **继续执行**（推荐）
- **查看计划详情**
- **查看待处理步骤**
- **重新开始**（清空进度）
如选择重新开始，删除计划文件后进入分析和计划阶段。
@@ -257,39 +356,35 @@ aide config get user_docs.docs_plan_path
### 执行单个步骤
对于每个步骤：
1. **读取步骤文档**：
- 打开 `steps/step-XXX.md`
- 获取已提取的源信息和内容大纲
1. **显示当前任务**：
> 正在执行：{{STEP_DESCRIPTION}}
2. **生成文档**：
- 基于步骤文档中的源信息直接生成
- **无需重新分析代码/项目文档**，信息已在步骤文档中
- 遵循内容大纲和格式要求
2. **执行步骤**：
3. **保存产出**：
- 写入文档文件
- 使用自动生成标记区分自动内容和用户编辑区域
**步骤类型 A：创建目录结构**
- 检查 docs 目录是否存在
- 创建必要的子目录
4. **更新步骤文档**：
- 标记步骤为 `completed`
- 填写执行记录
**步骤类型 B：生成文档文件**
- 分析相关代码/文档
- 根据模板生成内容
- 写入文件
**步骤类型 C：更新 README 链接**
- 检查 README 中的文档链接部分
- 更新链接指向新生成的文档
3. **更新计划文档**：
- 标记步骤完成（`✓`）
- 更新当前进度
- 记录时间戳
4. **保存产出**：
- 写入生成的文档文件
5. **更新计划文件**：
- 更新步骤状态
- 更新整体进度
- 添加执行日志
### 步骤间询问
每完成一个步骤后询问：
> 步骤 {{STEP_ID}} 已完成：{{STEP_DESCRIPTION}}
> 步骤 XXX 已完成：{{STEP_DESCRIPTION}}
>
> 已完成：YY/ZZ（进度 WW%）
>
> 是否继续下一步？
@@ -298,7 +393,7 @@ aide config get user_docs.docs_plan_path
- **查看产出**
- **暂停（保存进度）**
如选择暂停，保存进度后结束本次执行。
如选择暂停，当前进度已保存，下次可直接接续。
---
@@ -361,23 +456,26 @@ aide config get user_docs.docs_plan_path
当所有步骤完成时：
1. **更新计划文档**：
- 标记所有步骤完成
- 记录完成时间
1. 确认所有步骤状态为 `completed`
2. 更新 README 中的文档链接（如需要）
3. 向用户汇报完成情况
2. **显示完成提示**：
```
用户文档已生成：docs/
> 用户文档已生成：`{{DOCS_PATH}}/`
>
> 生成的文档：
> {{GENERATED_FILES_LIST}}
>
> 建议：
> - 检查生成的内容是否准确
> - 在 `<!-- USER-EDIT -->` 标记下方添加自定义内容
> - 自定义内容不会被后续更新覆盖
>
> 如需重新生成，可删除计划文件后再次运行 `/aide:user-docs`。
生成的文档：
- getting-started.md
- installation.md
- usage.md
- ...
建议：
- 检查生成的内容是否准确
- 在 <!-- USER-EDIT --> 标记下方添加自定义内容
- 自定义内容不会被后续更新覆盖
如需重新生成，可删除计划文件后再次运行 /aide:user-docs。
```
---
@@ -387,15 +485,15 @@ aide config get user_docs.docs_plan_path
|--------|--------|------|
| `user_docs.docs_path` | `docs` | 用户文档目录路径 |
| `user_docs.docs_plan_path` | `docs/user-docs-plan.md` | 计划文件路径 |
| `user_docs.docs_steps_path` | `docs/steps` | 步骤文档目录 |
| `user_docs.rules_path` | `make-readme-rules.md` | README 规范文件路径 |
---
## 注意事项
1. **分步执行**：大型项目建议分多次对话完成
2. **进度持久化**：进度保存在计划文件，可随时接续
1. **分步执行**：每个步骤文档包含已提取的源信息，执行时无需重新分析
2. **进度持久化**：进度同时保存在步骤文档和计划文件中
3. **保留用户编辑**：使用标记区分自动生成和用户编辑的内容
4. **风格一致**：文档风格与 README 保持一致
5. **增量更新**：多次运行不会覆盖用户自定义内容
6. **链接同步**：README 中的文档链接自动更新