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

351
aide-marketplace/aide-plugin/commands/user-graph.md
View File

@@ -2,7 +2,30 @@
你正在执行 Aide 用户流程图生成流程。这个命令帮助用户创建面向用户的长期维护流程图系统。
此命令支持**分步执行**和**接续执行**，适用于大型项目。
## 分步执行机制
此命令支持**真正有效的分步执行和接续执行**，适用于任意规模项目。
### 设计原则
1. **索引式计划文档**：`plan.md` 只做索引，详细信息存在独立步骤文档中
2. **自包含步骤文档**：每个步骤包含执行所需的全部信息（已分析好的模块结构）
3. **粒度动态控制**：根据模块复杂度动态拆分步骤
4. **分析与执行分离**：分析阶段产出详细计划，执行阶段直接绘图
### 文档结构
```
docs/graph-guide/
├── plan.md # 计划文件（索引式）
├── steps/ # 步骤详情目录
│ ├── step-001.md # 步骤1详情
│ ├── step-002.md # 步骤2详情
│ └── ...
└── [区块目录]/ # 流程图目录
├── guide.puml
└── *.puml
```
这可能是一个非常长的任务，因此规划您的工作可能会很有益。**建议花费您的整个输出上下文来处理任务 - 只需确保您不会在有大量未提交的工作时用尽上下文。**继续系统地工作，直到您完成此任务。**您的上下文窗口将在接近其限制时自动压缩，允许您从中断的地方继续无限期地工作。因此，不要因为令牌预算问题而提前停止任务。**当您接近令牌预算限制时，在上下文窗口刷新前将您当前的进度和状态保存到内存中。始终尽可能坚持和自主，并完全完成任务，即使您的预算即将用尽。无论剩余上下文如何，永远不要人为地提前停止任何任务。
@@ -32,9 +55,12 @@ aide config get docs.path
```bash
aide config get user_docs.graph_plan_path
aide config get user_docs.graph_steps_path
```
读取配置的计划文件路径，检查文件是否存在。
如果未配置，使用默认值：
- 计划文件：`docs/graph-guide/plan.md`
- 步骤目录：`docs/graph-guide/steps`
**根据计划文件状态决定流程**：
@@ -45,7 +71,7 @@ aide config get user_docs.graph_plan_path
## 分析和计划阶段
当 `docs/graph-guide/plan.md` 不存在时执行此流程。
当 `plan.md` 不存在时执行此流程。
### 1. 加载项目文档
@@ -75,59 +101,163 @@ aide config get user_docs.graph_plan_path
| 前端 | UI 相关 | 组件结构、数据流 |
| 文档 | 纯文档项目 | 内容导航、学习路径 |
### 3. 复杂度分析
### 3. 复杂度分析与步骤拆分
**这是实现有效分步执行的核心阶段。**
#### 3.1 评估区块复杂度
对每个区块评估：
| 复杂度 | 特征 | 预估步骤数 |
|--------|------|-----------|
| 低 | 单模块，逻辑简单 | 2-3 |
| 中 | 多模块，有交互 | 4-6 |
| 高 | 复杂系统，多层次 | 7+ |
| 复杂度 | 特征 | 处理方式 |
|--------|------|----------|
| 小 | 单模块，逻辑简单 | 整个区块作为 1 个步骤 |
| 中 | 多模块，有交互 | 按模块拆分为 2-5 个步骤 |
| 大 | 复杂系统，多层次 | 按子模块拆分为 5-10 个步骤 |
| 超大 | 巨型模块 | 按功能点拆分为 10+ 个步骤 |
### 4. 生成计划文档
#### 3.2 生成步骤文档
在 `docs/graph-guide/` 目录创建 `plan.md`：
**为每个步骤生成独立的步骤文档**，存放在 `steps/` 目录。
**步骤文档格式**：
```markdown
# 步骤 XXX：[区块名] - [流程图名称]
## 元信息
| 属性 | 值 |
|------|-----|
| 状态 | pending / in_progress / completed |
| 所属区块 | [区块名] |
| 流程图类型 | guide / 模块图 |
| 预估工作量 | 小 / 中 / 大 |
| 依赖步骤 | [无 / step-XXX] |
## 任务描述
绘制 [区块名] 的 [流程图名称]，展示 [具体内容]。
## 模块结构（已分析）
以下是执行本步骤所需的全部模块信息，**已从项目文档和代码中提取整理**：
### 涉及文件
| 文件路径 | 职责 | 关键内容 |
|----------|------|----------|
| `path/to/file1.py` | 入口模块 | main() 函数 |
| `path/to/file2.py` | 核心逻辑 | Parser 类、Executor 类 |
| ... | ... | ... |
### 模块关系
```
[已分析好的模块调用关系，ASCII 图或文字描述]
例如：
main.py
└→ parser.py::parse()
└→ executor.py::execute()
└→ output.py::write()
```
### 数据流
```
[已分析好的数据流向]
例如：
输入(stdin) → Parser → AST → Executor → Result → 输出(stdout)
```
### 关键函数/类
| 名称 | 位置 | 说明 |
|------|------|------|
| `main()` | main.py:10 | 程序入口 |
| `Parser` | parser.py:25 | 解析输入 |
| `Executor` | executor.py:50 | 执行逻辑 |
## 输出要求
- 文件：`[区块目录]/[filename].puml`
- 类型：[活动图 / 组件图 / 序列图]
- 内容要求：
- [ ] 展示 [具体内容1]
- [ ] 展示 [具体内容2]
- [ ] 标注关键节点
## PlantUML 模板
```plantuml
@startuml [filename]
skinparam defaultFontName "PingFang SC"
skinparam dpi 300
scale 0.5
' TODO: 基于上述模块结构绘制流程图
@enduml
```
## 执行记录
（执行时填写）
| 时间 | 操作 | 备注 |
|------|------|------|
| | 开始执行 | |
| | 完成 | |
```
#### 3.3 生成计划文件（索引）
生成 `plan.md` 作为索引：
```markdown
# 用户流程图编写计划
> 最后更新：YYYY-MM-DD HH:MM
## 项目概述
{{基于项目文档的简要描述}}
## 区块划分
## 区块索引
| # | 区块名称 | 类型 | 复杂度 | 状态 |
|---|----------|------|--------|------|
{{BLOCKS_TABLE}}
| # | 区块名称 | 类型 | 步骤数 | 状态 | 步骤范围 |
|---|----------|------|--------|------|----------|
| 1 | api-lib | 库项目 | 3 | pending | 001-003 |
| 2 | api | 应用 | 5 | pending | 004-008 |
| ... | ... | ... | ... | ... | ... |
## 执行步骤
## 步骤索引
### 区块 1: {{BLOCK_1_NAME}}
| 步骤 | 所属区块 | 流程图 | 状态 |
|------|----------|--------|------|
| [001](steps/step-001.md) | api-lib | guide.puml | pending |
| [002](steps/step-002.md) | api-lib | core.puml | pending |
| [003](steps/step-003.md) | api-lib | parser.puml | pending |
| [004](steps/step-004.md) | api | guide.puml | pending |
| ... | ... | ... | ... |
- [ ] 步骤 1.1: 分析模块结构
- [ ] 步骤 1.2: 编写 guide.puml
- [ ] 步骤 1.3: 编写 {{module}}.puml
...
## 整体进度
### 区块 2: {{BLOCK_2_NAME}}
- 总步骤数：XX
- 已完成：0
- 进行中：0
- 待处理：XX
- [ ] 步骤 2.1: ...
...
## 执行日志
## 当前进度
- 当前区块：0（未开始）
- 当前步骤：-
- 最后更新：{{TIMESTAMP}}
## 备注
（执行过程中的记录）
| 时间 | 步骤 | 操作 | 备注 |
|------|------|------|------|
| | | | |
```
### 5. 创建目录结构
### 4. 创建目录结构
```bash
aide config get user_docs.graph_path
@@ -138,23 +268,24 @@ aide config get user_docs.graph_path
```
docs/graph-guide/
├── plan.md
└── {{block_name}}/ # 每个区块一个目录
├── steps/
└── [区块名]/
```
### 6. 用户确认
### 5. 用户确认
> 流程图编写计划已生成。
>
> **区块划分**：
> {{BLOCKS_SUMMARY}}
> **区块数**：X 个
> **总步骤数**：Y 个
>
> **预估步骤**：共 {{TOTAL_STEPS}} 步
> 步骤文档已生成，每个步骤包含已分析好的模块结构，执行时可直接绘图。
>
> 是否开始执行？
**选项**：
- **开始执行**（推荐）
- **调整计划**
- **查看计划详情**
- **稍后执行**
如选择开始执行，进入步骤执行流程。
@@ -163,23 +294,23 @@ docs/graph-guide/
## 接续执行阶段
当 `docs/graph-guide/plan.md` 存在时执行此流程。
当 `plan.md` 存在时执行此流程。
### 1. 读取计划文档
### 1. 读取计划文件
解析 plan.md 获取：
- 区块列表和状态
- 当前进度（区块和步骤）
- 历史备注
读取 plan.md 获取：
- 步骤索引
- 整体进度
- 执行日志
### 2. 显示进度
> **流程图编写进度**
>
> 当前区块：{{CURRENT_BLOCK}}
> 当前步骤：{{CURRENT_STEP}}
> 已完成步骤：{{COMPLETED_STEPS}}/{{TOTAL_STEPS}}
> 上次更新：{{LAST_UPDATE}}
> 总步骤数：XX
> 已完成：YY（ZZ%）
> 当前步骤：step-NNN
> 上次更新：YYYY-MM-DD HH:MM
### 3. 确认继续
@@ -189,7 +320,7 @@ docs/graph-guide/
**选项**：
- **继续执行**（推荐）
- **查看计划详情**
- **查看待处理步骤**
- **重新开始**（清空进度）
---
@@ -198,29 +329,35 @@ docs/graph-guide/
### 执行单个步骤
对于每个步骤：
1. **读取步骤文档**：
- 打开 `steps/step-XXX.md`
- 获取已分析好的模块结构
1. **显示当前任务**：
> 正在执行：{{STEP_DESCRIPTION}}
2. **绘制流程图**：
- 基于步骤文档中的模块结构直接绘图
- **无需重新分析代码**，信息已在步骤文档中
- 遵循 PlantUML 模板和内容要求
2. **执行步骤**：
- 分析相关代码/文档
- 生成/更新 puml 文件
3. **更新计划文档**：
- 标记步骤完成
- 更新当前进度
- 记录时间戳
4. **保存产出**：
3. **保存产出**：
- 写入 puml 文件
- 调用 PlantUML 生成 PNG（如配置）
- 生成 PNG（如配置了 PlantUML）
4. **更新步骤文档**：
- 标记步骤为 `completed`
- 填写执行记录
5. **更新计划文件**：
- 更新步骤状态
- 更新整体进度
- 添加执行日志
### 步骤间询问
每完成一个步骤后询问：
每完成一个步骤后：
> 步骤 {{STEP_ID}} 已完成。
> 步骤 XXX 已完成：[流程图名称]
>
> 已完成：YY/ZZ（进度 WW%）
>
> 是否继续下一步？
@@ -229,7 +366,7 @@ docs/graph-guide/
- **查看产出**
- **暂停（保存进度）**
如选择暂停，保存进度后结束本次执行。
如选择暂停，当前进度已保存，下次可直接接续。
---
@@ -263,28 +400,23 @@ docs/graph-guide/
5. **层次化组织**：
- 主流程图 + 详细子图
### PlantUML 模板
### PlantUML 配置
每个文件必须包含头部配置：
```bash
aide config get plantuml.font_name
aide config get plantuml.dpi
aide config get plantuml.scale
```
```plantuml
@startuml guide
!theme plain
skinparam backgroundColor #FFFFFF
@startuml [name]
skinparam defaultFontName "[font_name]"
skinparam dpi [dpi]
scale [scale]
title {{区块名称}} - 导览
' 模块定义
package "{{Module A}}" {
[Component 1]
[Component 2]
}
package "{{Module B}}" {
[Component 3]
}
' 关系
[Component 1] --> [Component 2]
[Component 2] --> [Component 3]
' 内容...
@enduml
```
@@ -297,13 +429,16 @@ package "{{Module B}}" {
```
docs/graph-guide/
├── plan.md # 计划和进度文档
├── guide.puml # 总导览流程图（可选）
├── {{block-1}}/ # 区块 1
│ ├── guide.puml # 区块导览
│ ├── module-a.puml # 模块 A 流程图
│ └── module-b.puml # 模块 B 流程图
├── {{block-2}}/ # 区块 2
├── plan.md # 计划文件（索引）
├── steps/ # 步骤详情目录
│ ├── step-001.md
│ ├── step-002.md
│ └── ...
├── api-lib/ # 区块 1
│ ├── guide.puml
│ ├── core.puml
│ └── parser.puml
├── api/ # 区块 2
│ ├── guide.puml
│ └── ...
└── ...
@@ -311,19 +446,37 @@ docs/graph-guide/
---
## 完成流程
当所有步骤完成时：
1. 确认所有步骤状态为 `completed`
2. 生成总导览流程图（如需要）
3. 向用户汇报完成情况
```
用户流程图已完成：
- 目录：docs/graph-guide/
- 区块数：N 个
- 总步骤数：M 个
- 流程图数：X 个
```
---
## 配置项
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `user_docs.graph_path` | `docs/graph-guide` | 流程图目录路径 |
| `user_docs.graph_plan_path` | `docs/graph-guide/plan.md` | 计划文件路径 |
| `user_docs.graph_steps_path` | `docs/graph-guide/steps` | 步骤文档目录 |
---
## 注意事项
1. **分步执行**：大型项目建议分多次对话完成
2. **进度持久化**：进度保存在 plan.md，可随时接续
3. **PNG 生成**：需要配置 PlantUML（参考 `[plantuml]` 配置）
4. **与项目文档关联**：依赖项目文档了解项目结构
5. **用户参与**：关键决策需用户确认
1. **分步执行**：每个步骤文档包含已分析好的模块结构，执行时无需重新分析
2. **进度持久化**：进度同时保存在步骤文档和计划文件中
3. **粒度可控**：大型模块自动拆分为多个步骤
4. **PNG 生成**：需要配置 PlantUML（参考 `[plantuml]` 配置）