agent-aide/aide-marketplace/aide-plugin/commands/user-graph.md

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

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

---

前置准备

首先检查项目文档是否存在。

aide config get docs.path

如果项目文档目录（.aide/project-docs/）不存在：

用户流程图依赖项目文档来了解项目结构。建议先执行 /aide:docs 和 /aide:load。

使用 AskUserQuestion 询问：

• 先执行 /aide:docs（推荐）
• 继续（基于代码分析）

---

开始

检查计划文件

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/ 目录。

步骤文档格式：

# 步骤 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. 创建目录结构

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 配置

每个文件必须包含头部配置：

aide config get plantuml.font_name
aide config get plantuml.dpi
aide config get plantuml.scale

@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] 配置）