483 lines
11 KiB
Markdown
483 lines
11 KiB
Markdown
# Aide 用户流程图生成
|
||
|
||
你正在执行 Aide 用户流程图生成流程。这个命令帮助用户创建面向用户的长期维护流程图系统。
|
||
|
||
## 分步执行机制
|
||
|
||
此命令支持**真正有效的分步执行和接续执行**，适用于任意规模项目。
|
||
|
||
### 设计原则
|
||
|
||
1. **索引式计划文档**：`plan.md` 只做索引，详细信息存在独立步骤文档中
|
||
2. **自包含步骤文档**：每个步骤包含执行所需的全部信息（已分析好的模块结构）
|
||
3. **粒度动态控制**：根据模块复杂度动态拆分步骤
|
||
4. **分析与执行分离**：分析阶段产出详细计划，执行阶段直接绘图
|
||
|
||
### 文档结构
|
||
|
||
```
|
||
docs/graph-guide/
|
||
├── plan.md # 计划文件（索引式）
|
||
├── steps/ # 步骤详情目录
|
||
│ ├── step-001.md # 步骤1详情
|
||
│ ├── step-002.md # 步骤2详情
|
||
│ └── ...
|
||
└── [区块目录]/ # 流程图目录
|
||
├── guide.puml
|
||
└── *.puml
|
||
```
|
||
|
||
这可能是一个非常长的任务，因此规划您的工作可能会很有益。**建议花费您的整个输出上下文来处理任务 - 只需确保您不会在有大量未提交的工作时用尽上下文。**继续系统地工作，直到您完成此任务。**您的上下文窗口将在接近其限制时自动压缩，允许您从中断的地方继续无限期地工作。因此，不要因为令牌预算问题而提前停止任务。**当您接近令牌预算限制时，在上下文窗口刷新前将您当前的进度和状态保存到内存中。始终尽可能坚持和自主，并完全完成任务，即使您的预算即将用尽。无论剩余上下文如何，永远不要人为地提前停止任何任务。
|
||
|
||
---
|
||
|
||
## 前置准备
|
||
|
||
**首先检查项目文档是否存在。**
|
||
|
||
```bash
|
||
aide config get docs.path
|
||
```
|
||
|
||
如果项目文档目录（`.aide/project-docs/`）不存在：
|
||
|
||
> 用户流程图依赖项目文档来了解项目结构。建议先执行 `/aide:docs` 和 `/aide:load`。
|
||
|
||
使用 AskUserQuestion 询问：
|
||
- **先执行 /aide:docs**（推荐）
|
||
- **继续（基于代码分析）**
|
||
|
||
---
|
||
|
||
## 开始
|
||
|
||
### 检查计划文件
|
||
|
||
```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`
|
||
|
||
**根据计划文件状态决定流程**：
|
||
|
||
- **计划文件不存在** → 进入**分析和计划阶段**
|
||
- **计划文件存在** → 进入**接续执行阶段**
|
||
|
||
---
|
||
|
||
## 分析和计划阶段
|
||
|
||
当 `plan.md` 不存在时执行此流程。
|
||
|
||
### 1. 加载项目文档
|
||
|
||
读取 `.aide/project-docs/` 下的项目文档：
|
||
|
||
1. 读取总导览（`README.md`）获取：
|
||
- 项目类型（文档/程序/混合）
|
||
- 子项目/模块列表
|
||
- 技术栈信息
|
||
|
||
2. 阅读相关区块文档了解详细结构
|
||
|
||
### 2. 区块划分
|
||
|
||
**划分原则**（与项目文档不同）：
|
||
|
||
- 目标是呈现**整体形式**
|
||
- 按**业务逻辑**或**独立开发项目**划分
|
||
- 不追求深度全覆盖
|
||
|
||
**区块类型**：
|
||
|
||
| 类型 | 说明 | 典型内容 |
|
||
|------|------|----------|
|
||
| 库项目 | 独立的库/工具包 | API 设计、核心逻辑 |
|
||
| 应用 | 可运行的程序 | 启动流程、业务逻辑 |
|
||
| 前端 | UI 相关 | 组件结构、数据流 |
|
||
| 文档 | 纯文档项目 | 内容导航、学习路径 |
|
||
|
||
### 3. 复杂度分析与步骤拆分
|
||
|
||
**这是实现有效分步执行的核心阶段。**
|
||
|
||
#### 3.1 评估区块复杂度
|
||
|
||
对每个区块评估：
|
||
|
||
| 复杂度 | 特征 | 处理方式 |
|
||
|--------|------|----------|
|
||
| 小 | 单模块，逻辑简单 | 整个区块作为 1 个步骤 |
|
||
| 中 | 多模块，有交互 | 按模块拆分为 2-5 个步骤 |
|
||
| 大 | 复杂系统，多层次 | 按子模块拆分为 5-10 个步骤 |
|
||
| 超大 | 巨型模块 | 按功能点拆分为 10+ 个步骤 |
|
||
|
||
#### 3.2 生成步骤文档
|
||
|
||
**为每个步骤生成独立的步骤文档**，存放在 `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
|
||
|
||
## 项目概述
|
||
|
||
{{基于项目文档的简要描述}}
|
||
|
||
## 区块索引
|
||
|
||
| # | 区块名称 | 类型 | 步骤数 | 状态 | 步骤范围 |
|
||
|---|----------|------|--------|------|----------|
|
||
| 1 | api-lib | 库项目 | 3 | pending | 001-003 |
|
||
| 2 | api | 应用 | 5 | pending | 004-008 |
|
||
| ... | ... | ... | ... | ... | ... |
|
||
|
||
## 步骤索引
|
||
|
||
| 步骤 | 所属区块 | 流程图 | 状态 |
|
||
|------|----------|--------|------|
|
||
| [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 |
|
||
| ... | ... | ... | ... |
|
||
|
||
## 整体进度
|
||
|
||
- 总步骤数：XX
|
||
- 已完成：0
|
||
- 进行中：0
|
||
- 待处理：XX
|
||
|
||
## 执行日志
|
||
|
||
| 时间 | 步骤 | 操作 | 备注 |
|
||
|------|------|------|------|
|
||
| | | | |
|
||
```
|
||
|
||
### 4. 创建目录结构
|
||
|
||
```bash
|
||
aide config get user_docs.graph_path
|
||
```
|
||
|
||
创建流程图目录和子目录：
|
||
|
||
```
|
||
docs/graph-guide/
|
||
├── plan.md
|
||
├── steps/
|
||
└── [区块名]/
|
||
```
|
||
|
||
### 5. 用户确认
|
||
|
||
> 流程图编写计划已生成。
|
||
>
|
||
> **区块数**：X 个
|
||
> **总步骤数**：Y 个
|
||
>
|
||
> 步骤文档已生成，每个步骤包含已分析好的模块结构，执行时可直接绘图。
|
||
>
|
||
> 是否开始执行？
|
||
|
||
**选项**：
|
||
- **开始执行**（推荐）
|
||
- **查看计划详情**
|
||
- **稍后执行**
|
||
|
||
如选择开始执行，进入步骤执行流程。
|
||
|
||
---
|
||
|
||
## 接续执行阶段
|
||
|
||
当 `plan.md` 存在时执行此流程。
|
||
|
||
### 1. 读取计划文件
|
||
|
||
读取 plan.md 获取：
|
||
- 步骤索引
|
||
- 整体进度
|
||
- 执行日志
|
||
|
||
### 2. 显示进度
|
||
|
||
> **流程图编写进度**
|
||
>
|
||
> 总步骤数：XX
|
||
> 已完成：YY（ZZ%）
|
||
> 当前步骤：step-NNN
|
||
> 上次更新：YYYY-MM-DD HH:MM
|
||
|
||
### 3. 确认继续
|
||
|
||
使用 AskUserQuestion：
|
||
|
||
> 是否从当前进度继续执行？
|
||
|
||
**选项**：
|
||
- **继续执行**（推荐）
|
||
- **查看待处理步骤**
|
||
- **重新开始**（清空进度）
|
||
|
||
---
|
||
|
||
## 步骤执行流程
|
||
|
||
### 执行单个步骤
|
||
|
||
1. **读取步骤文档**：
|
||
- 打开 `steps/step-XXX.md`
|
||
- 获取已分析好的模块结构
|
||
|
||
2. **绘制流程图**：
|
||
- 基于步骤文档中的模块结构直接绘图
|
||
- **无需重新分析代码**，信息已在步骤文档中
|
||
- 遵循 PlantUML 模板和内容要求
|
||
|
||
3. **保存产出**：
|
||
- 写入 puml 文件
|
||
- 生成 PNG（如配置了 PlantUML）
|
||
|
||
4. **更新步骤文档**：
|
||
- 标记步骤为 `completed`
|
||
- 填写执行记录
|
||
|
||
5. **更新计划文件**：
|
||
- 更新步骤状态
|
||
- 更新整体进度
|
||
- 添加执行日志
|
||
|
||
### 步骤间询问
|
||
|
||
每完成一个步骤后：
|
||
|
||
> 步骤 XXX 已完成：[流程图名称]
|
||
>
|
||
> 已完成：YY/ZZ（进度 WW%）
|
||
>
|
||
> 是否继续下一步？
|
||
|
||
**选项**：
|
||
- **继续**（推荐）
|
||
- **查看产出**
|
||
- **暂停（保存进度）**
|
||
|
||
如选择暂停，当前进度已保存，下次可直接接续。
|
||
|
||
---
|
||
|
||
## 流程图内容规范
|
||
|
||
### 总导览流程图（guide.puml）
|
||
|
||
每个区块的 guide.puml 应包含：
|
||
- 模块概览
|
||
- 调用关系
|
||
- 数据流向
|
||
|
||
### 详细流程图（module.puml）
|
||
|
||
#### 不含程序的项目
|
||
|
||
- 内容导航图
|
||
- 学习路径图
|
||
- 概念关系图
|
||
|
||
#### 含程序的项目
|
||
|
||
参考 `/aide:run` 中的程序逻辑流图规范：
|
||
|
||
1. **入口点**：从程序入口开始
|
||
2. **控制结构**：体现顺序、分支、循环
|
||
3. **语义化抽象**：人类可理解的业务描述
|
||
4. **模块化表示**：
|
||
- 函数/模块表示为"盒子"
|
||
- 标注输入输出
|
||
5. **层次化组织**：
|
||
- 主流程图 + 详细子图
|
||
|
||
### PlantUML 配置
|
||
|
||
每个文件必须包含头部配置：
|
||
|
||
```bash
|
||
aide config get plantuml.font_name
|
||
aide config get plantuml.dpi
|
||
aide config get plantuml.scale
|
||
```
|
||
|
||
```plantuml
|
||
@startuml [name]
|
||
skinparam defaultFontName "[font_name]"
|
||
skinparam dpi [dpi]
|
||
scale [scale]
|
||
|
||
' 内容...
|
||
|
||
@enduml
|
||
```
|
||
|
||
---
|
||
|
||
## 目录结构
|
||
|
||
最终生成的目录结构：
|
||
|
||
```
|
||
docs/graph-guide/
|
||
├── plan.md # 计划文件（索引）
|
||
├── steps/ # 步骤详情目录
|
||
│ ├── step-001.md
|
||
│ ├── step-002.md
|
||
│ └── ...
|
||
├── api-lib/ # 区块 1
|
||
│ ├── guide.puml
|
||
│ ├── core.puml
|
||
│ └── parser.puml
|
||
├── api/ # 区块 2
|
||
│ ├── guide.puml
|
||
│ └── ...
|
||
└── ...
|
||
```
|
||
|
||
---
|
||
|
||
## 完成流程
|
||
|
||
当所有步骤完成时：
|
||
|
||
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. **进度持久化**：进度同时保存在步骤文档和计划文件中
|
||
3. **粒度可控**：大型模块自动拆分为多个步骤
|
||
4. **PNG 生成**：需要配置 PlantUML（参考 `[plantuml]` 配置）
|