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

2025-12-19 06:06:51 +08:00
parent 37c434b92a
commit 4a0759e36c
8 changed files with 1011 additions and 464 deletions
--- a/.aide/branches.json
+++ b/.aide/branches.json
@@ -1,5 +1,5 @@
 {
-  "next_number": 25,
+  "next_number": 26,
  "branches": [
    {
      "number": 1,
@@ -282,6 +282,18 @@
      "status": "finished",
      "end_commit": "4fdf7664c19b276336970421e1788a27c19815d7",
      "finished_at": "2025-12-19T05:39:19+08:00"
+    },
+    {
+      "number": 25,
+      "branch_name": "aide/025",
+      "source_branch": "master",
+      "start_commit": "37c434b92ad2c8a7d0533ee2070e7ac36d232b6d",
+      "task_id": "2025-12-19T05-41-57",
+      "task_summary": "开始任务准备: 分析和优化 user-docs/user-graph 的分步执行能力",
+      "started_at": "2025-12-19T05:41:57+08:00",
+      "status": "finished",
+      "end_commit": "cb7e960a28a46b615b34ffc1dc4e74cc22e50584",
+      "finished_at": "2025-12-19T06:06:51+08:00"
    }
  ]
 }
--- a/.aide/branches.md
+++ b/.aide/branches.md
@@ -1,5 +1,16 @@
 # Git 分支概况

+## aide/025
+
+- **任务**: 开始任务准备: 分析和优化 user-docs/user-graph 的分步执行能力
+- **任务ID**: 2025-12-19T05-41-57
+- **源分支**: master
+- **起始提交**: 37c434b
+- **结束提交**: cb7e960
+- **状态**: finished
+- **起始时间**: 2025-12-19 05:41
+- **结束时间**: 2025-12-19 06:06
+
 ## aide/024

 - **任务**: 开始任务准备: 优化 finish 后提交信息中的任务名格式
--- a/.aide/logs/2025-12-19T05-41-57-status.json
+++ b/.aide/logs/2025-12-19T05-41-57-status.json
@@ -0,0 +1,155 @@
+{
+  "task_id": "2025-12-19T05-41-57",
+  "current_phase": "finish",
+  "current_step": 18,
+  "started_at": "2025-12-19T05:41:57+08:00",
+  "history": [
+    {
+      "timestamp": "2025-12-19T05:41:57+08:00",
+      "action": "start",
+      "phase": "task-optimize",
+      "step": 1,
+      "summary": "开始任务准备: 分析和优化 user-docs/user-graph 的分步执行能力",
+      "git_commit": "d49d46fe850a8cc42d01664469e0e08d91a9ef94"
+    },
+    {
+      "timestamp": "2025-12-19T05:44:15+08:00",
+      "action": "next-step",
+      "phase": "task-optimize",
+      "step": 2,
+      "summary": "完成口语化内容解析和深度分析",
+      "git_commit": "35bbe6874a0c639dce92689289c3302bd0856865"
+    },
+    {
+      "timestamp": "2025-12-19T05:45:16+08:00",
+      "action": "next-step",
+      "phase": "task-optimize",
+      "step": 3,
+      "summary": "任务优化完成，识别待定项",
+      "git_commit": "2f1fbf5a1385f5fd6e4dc2812fd96632523d8c7c"
+    },
+    {
+      "timestamp": "2025-12-19T05:48:46+08:00",
+      "action": "next-step",
+      "phase": "task-optimize",
+      "step": 4,
+      "summary": "完成 docs.md 分析，更新任务范围",
+      "git_commit": "b9c5d32faade3c51f46c346a3b437f7abbe4a0bf"
+    },
+    {
+      "timestamp": "2025-12-19T05:52:53+08:00",
+      "action": "next-step",
+      "phase": "task-optimize",
+      "step": 5,
+      "summary": "任务细则已确认",
+      "git_commit": "f581fce69957585a0a09da5456aeb5a63b1dae56"
+    },
+    {
+      "timestamp": "2025-12-19T05:53:13+08:00",
+      "action": "next-part",
+      "phase": "flow-design",
+      "step": 6,
+      "summary": "进入流程设计环节",
+      "git_commit": "ab11105550972c46c6133abc9b253d10380a6c91"
+    },
+    {
+      "timestamp": "2025-12-19T05:54:10+08:00",
+      "action": "next-step",
+      "phase": "flow-design",
+      "step": 7,
+      "summary": "流程图设计完成",
+      "git_commit": "ed49d3c0a94369ff62191ce2fa5ebbc4e15422d5"
+    },
+    {
+      "timestamp": "2025-12-19T05:54:25+08:00",
+      "action": "next-part",
+      "phase": "impl",
+      "step": 8,
+      "summary": "流程设计完成，进入实现环节",
+      "git_commit": "d3433cc277ca9774d16c07308113e46f2e472571"
+    },
+    {
+      "timestamp": "2025-12-19T05:56:27+08:00",
+      "action": "next-step",
+      "phase": "impl",
+      "step": 9,
+      "summary": "完成 docs.md 修改",
+      "git_commit": "354b97583fc36df379a12417d153a12ef35fb860"
+    },
+    {
+      "timestamp": "2025-12-19T05:58:20+08:00",
+      "action": "next-step",
+      "phase": "impl",
+      "step": 10,
+      "summary": "完成 user-graph.md 修改",
+      "git_commit": "0c05c25ee65a23c547f6555ba2e05e9937c59fb0"
+    },
+    {
+      "timestamp": "2025-12-19T06:00:19+08:00",
+      "action": "next-step",
+      "phase": "impl",
+      "step": 11,
+      "summary": "完成 user-docs.md 修改",
+      "git_commit": "a2269e75f2075dbf2d4a2264ae293a8d30045da6"
+    },
+    {
+      "timestamp": "2025-12-19T06:01:29+08:00",
+      "action": "next-step",
+      "phase": "impl",
+      "step": 12,
+      "summary": "验证三个命令一致性通过",
+      "git_commit": "0de028f22727ea20fbcd70511344db2a2b46ab68"
+    },
+    {
+      "timestamp": "2025-12-19T06:01:58+08:00",
+      "action": "next-part",
+      "phase": "verify",
+      "step": 13,
+      "summary": "实现完成，进入验证环节",
+      "git_commit": "a1056d9047547a6c186c3a589610b4b687c18a35"
+    },
+    {
+      "timestamp": "2025-12-19T06:02:15+08:00",
+      "action": "next-step",
+      "phase": "verify",
+      "step": 14,
+      "summary": "验证完成: 所有成功标准满足",
+      "git_commit": "c80c7abec4c9b52e208a63aadb75d7720d9c6df5"
+    },
+    {
+      "timestamp": "2025-12-19T06:02:28+08:00",
+      "action": "next-part",
+      "phase": "docs",
+      "step": 15,
+      "summary": "验证通过，进入文档环节",
+      "git_commit": "a93ccbf0d7090f0f9cf1c64aa69deb4f3aaabee5"
+    },
+    {
+      "timestamp": "2025-12-19T06:04:18+08:00",
+      "action": "next-step",
+      "phase": "docs",
+      "step": 16,
+      "summary": "文档更新完成",
+      "git_commit": "9eae387e7fc5eafdb4a895dd5d1b77c1e65653fb"
+    },
+    {
+      "timestamp": "2025-12-19T06:04:31+08:00",
+      "action": "next-part",
+      "phase": "confirm",
+      "step": 17,
+      "summary": "文档更新完成，进入用户确认环节",
+      "git_commit": "1a5f84f1952820d35a71d4d123db746fb154d4d7"
+    },
+    {
+      "timestamp": "2025-12-19T06:06:51+08:00",
+      "action": "next-part",
+      "phase": "finish",
+      "step": 18,
+      "summary": "用户已确认，进入收尾环节",
+      "git_commit": "cb7e960a28a46b615b34ffc1dc4e74cc22e50584"
+    }
+  ],
+  "source_branch": "master",
+  "start_commit": "37c434b92ad2c8a7d0533ee2070e7ac36d232b6d",
+  "task_branch": "aide/025"
+}
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,41 @@

 ## 2025-12-19

+### 重大优化
+
+**三个命令的分步执行机制重构（docs / user-graph / user-docs）**
+
+针对大型项目（百万行代码级别）的分步执行和接续执行需求，对三个命令进行了根本性重构：
+
+**核心改进**：
+- **索引式计划文档**：计划文件只做索引，详细信息存在独立步骤文档（`steps/step-XXX.md`）
+- **自包含步骤文档**：每个步骤包含执行所需的全部信息，接续执行无需重新分析
+- **粒度动态控制**：根据复杂度评估动态拆分步骤，确保单次对话可完成
+- **分析与执行分离**：分析阶段产出详细计划，执行阶段直接产出
+
+**docs.md（项目文档管理）**：
+- 新增"步骤生成"阶段：为每个区块生成详细步骤文档（包含文件清单、已知上下文）
+- 区块计划升级为索引式：`block-plan.md` 只做索引，`steps/` 目录存详情
+- 支持区块内细粒度进度追踪：大型区块自动拆分为多个步骤
+- 新增配置项 `docs.steps_path`（默认 `.aide/project-docs/steps`）
+
+**user-graph.md（用户流程图生成）**：
+- 步骤文档包含已分析好的模块结构（涉及文件、模块关系、数据流、关键函数）
+- 执行阶段直接基于模块结构绘图，无需重新分析代码
+- 新增配置项 `user_docs.graph_steps_path`（默认 `docs/graph-guide/steps`）
+
+**user-docs.md（用户文档生成）**：
+- 步骤文档包含已提取的源信息（项目基础信息、相关模块、关键代码摘要）
+- 执行阶段直接基于源信息生成文档
+- 新增配置项 `user_docs.docs_steps_path`（默认 `docs/steps`）
+
+**解决的问题**：
+- 原有"分步"是形式上的分步（基于逻辑单元），对大型项目无效
+- 每次对话需重新"理解"项目，消耗大量上下文
+- 单个区块/文档可能需要多次对话才能完成，但无法追踪内部进度
+
+---
+
 ### 优化

 **user-docs 分步执行和接续执行能力**
--- a/aide-marketplace/aide-plugin/commands/docs.md
+++ b/aide-marketplace/aide-plugin/commands/docs.md
@@ -6,13 +6,38 @@

 > **完全深度探索**：不考虑过度设计、开销、效率问题。对项目中的每一个文件、每一个目录（包括空目录）都要完全覆盖，不允许遗漏。

+## 分步执行机制
+
+此命令支持**真正有效的分步执行和接续执行**，适用于任意规模项目（包括百万行代码级别）。
+
+### 设计原则
+
+1. **索引式计划文档**：`block-plan.md` 只做索引，详细信息存在独立步骤文档中
+2. **自包含步骤文档**：每个步骤包含执行所需的全部信息，接续执行无需重新分析
+3. **粒度动态控制**：根据区块大小动态拆分步骤，确保单次对话可完成
+4. **分析与执行分离**：分析阶段产出详细计划，执行阶段直接产出
+
+### 文档结构
+
+```
+.aide/project-docs/
+├── README.md              # 总导览
+├── block-plan.md          # 区块计划（索引式）
+├── steps/                 # 步骤详情目录
+│   ├── step-001.md        # 步骤1详情
+│   ├── step-002.md        # 步骤2详情
+│   └── ...
+└── blocks/                # 区块文档
+    ├── block-1.md
+    └── ...
+```
+
 ## 前置准备

 **首先触发 `aide` skill 学习 aide 命令的使用方法。**

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

-
 ---

 ## 开始
@@ -22,17 +47,19 @@
 ```bash
 aide config get docs.path
 aide config get docs.block_plan_path
+aide config get docs.steps_path
 ```

 如果未配置，使用默认值：
 - 文档目录：`.aide/project-docs`
 - 区块计划：`.aide/project-docs/block-plan.md`
+- 步骤目录：`.aide/project-docs/steps`

 ### 检查文档状态

-检查文档目录是否存在及其内容：
- 不存在或为空 → 进入**创建流程**
- 已存在 → 进入**更新流程**
+检查区块计划文件是否存在：
+- **不存在** → 进入**创建流程**
+- **已存在** → 进入**接续流程**

 ---

@@ -63,34 +90,7 @@ find . -not -path './.git/*' -not -name '.git' | sort

 #### 1.3 生成目录树结构

-生成类似 `tree` 命令输出的完整目录结构，对于 .gitignore 中的项目标注 `[ignored]`：
-
-**目录树必须完整**：
- 根目录下的**所有**子目录都必须列出（包括非代码目录如 docs/、assets/、discuss/ 等）
- 每个目录至少有简短说明
- 被忽略的目录也要列出并标注 `[ignored]`
-
-```
-project/
-├── src/                     源码目录
-│   ├── main.py
-│   ├── utils/
-│   │   ├── helper.py
-│   │   └── config.py
-│   └── __init__.py
-├── tests/                   测试目录
-│   └── test_main.py
-├── docs/                    项目文档目录
-│   ├── design.md
-│   └── api.md
-├── discuss/                 讨论记录目录
-├── assets/                  [空目录] 资源文件
-├── cache/                   [ignored]
-├── node_modules/            [ignored]
-├── .gitignore
-├── README.md
-└── requirements.txt
-```
+生成完整目录结构，对于 .gitignore 中的项目标注 `[ignored]`。

 #### 1.4 统计项目信息

@@ -102,7 +102,7 @@ project/
 - 代码行数：约 xxx 行
 ```

-### 阶段 2：初步区块划分
+### 阶段 2：区块划分

 根据以下规则划分区块：

@@ -110,193 +110,253 @@ project/
 2. **按功能模块**：相关功能的文件归为一个区块
 3. **包含空目录**：空目录也要归入相应区块
 4. **低耦合**：区块间依赖关系尽量简单
-5. **完整覆盖**：根目录下每个非忽略的子目录都必须归入某个区块
+5. **完整覆盖**：每个非忽略的子目录都必须归入某个区块

-> **强制规则**：非代码目录（如 `docs/`、`assets/`、`discuss/` 等）同样必须作为区块进行覆盖，不能因为"非核心代码"而跳过。
+### 阶段 3：步骤生成（关键阶段）

-生成初步区块计划：
+**这是实现有效分步执行的核心阶段。**
+
+#### 3.1 评估区块复杂度
+
+对每个区块评估：
+
+| 复杂度 | 文件数 | 代码行数 | 处理方式 |
+|--------|--------|----------|----------|
+| 小 | <20 | <2000 | 整个区块作为 1 个步骤 |
+| 中 | 20-100 | 2000-10000 | 按子目录拆分为 2-5 个步骤 |
+| 大 | 100-500 | 10000-50000 | 按文件组拆分为 5-15 个步骤 |
+| 超大 | >500 | >50000 | 按单文件或小文件组拆分 |
+
+#### 3.2 生成步骤文档
+
+**为每个步骤生成独立的步骤文档**，存放在 `steps/` 目录。
+
+**步骤文档格式**：
+
+```markdown
+# 步骤 XXX：[区块名] - [子任务描述]
+
+## 元信息
+
+| 属性 | 值 |
+|------|-----|
+| 状态 | pending / in_progress / completed |
+| 所属区块 | [区块名] |
+| 预估工作量 | 小 / 中 / 大 |
+| 依赖步骤 | [无 / step-XXX] |
+
+## 任务描述
+
+完全深度探索以下文件/目录，生成/更新区块文档中的相应部分。
+
+## 目标文件清单
+
+| 文件路径 | 类型 | 大小 | 状态 |
+|----------|------|------|------|
+| `path/to/file1.py` | 源码 | 150行 | - |
+| `path/to/file2.py` | 源码 | 200行 | - |
+| `path/to/subdir/` | 目录 | 5文件 | - |
+| ... | ... | ... | ... |
+
+## 已知上下文
+
+（在分析阶段填写，供执行时参考）
+
+### 目录结构
+```
+[该步骤涉及的目录结构]
+```
+
+### 关键信息
+- [已知的模块职责]
+- [已知的依赖关系]
+- [需要特别注意的点]
+
+## 输出要求
+
+- 更新文件：`blocks/[区块名].md`
+- 更新内容：
+  - [ ] 文件清单中的文件概述
+  - [ ] 核心组件说明
+  - [ ] 目录树对应部分
+
+## 执行记录
+
+（执行时填写）
+
+| 时间 | 操作 | 备注 |
+|------|------|------|
+| | 开始执行 | |
+| | 完成 | |
+```
+
+#### 3.3 生成区块计划（索引）
+
+生成 `block-plan.md` 作为索引：

 ```markdown
 # 区块计划

+> 最后更新：YYYY-MM-DD HH:MM
+
 ## 项目概况
+
 - 项目名称：xxx
 - 主要语言：xxx
 - 文件总数：xxx（含 xx 被忽略）
 - 空目录数：xxx
 - 代码行数：xxx

-## 完整目录树（简化版）
+## 目录树（简化版）
+
+```
 [前两层目录结构]
-
-## 区块划分
-
-### 区块 1：[名称]
- 路径：xxx/
- 文件数：xx
- 空目录：xx
- 状态：待处理
-
-### 区块 2：[名称]
-...
-
-### 区块 N：项目文档与资源
- 路径：docs/, assets/, discuss/, statements/
- 文件数：xx
- 空目录：xx
- 状态：待处理
- 说明：非代码资源文件（文档、讨论记录、声明等）
-
-> 注：即使是非代码目录，也必须作为区块进行完整深度探索
-
-## 进度追踪
- [ ] 区块 1
- [ ] 区块 2
-...
 ```

-### 阶段 3：区块验证
+## 区块索引

-对每个区块进行浅层探索：
-1. 确认区块包含的所有文件和目录
-2. 验证区块划分是否合理
-3. 调整区块边界（如需要）
-4. 确保没有遗漏任何文件或目录
+| # | 区块名 | 路径 | 文件数 | 步骤数 | 状态 | 步骤范围 |
+|---|--------|------|--------|--------|------|----------|
+| 1 | core | src/core/ | 25 | 3 | pending | 001-003 |
+| 2 | utils | src/utils/ | 45 | 5 | pending | 004-008 |
+| ... | ... | ... | ... | ... | ... | ... |

-**强制完整性检查**：
+## 步骤索引

-```bash
-# 列出根目录下所有子目录（排除 .git）
-ls -d */ 2>/dev/null | sort
+| 步骤 | 所属区块 | 描述 | 状态 |
+|------|----------|------|------|
+| [001](steps/step-001.md) | core | 分析 core 主模块 | pending |
+| [002](steps/step-002.md) | core | 分析 core/parser | pending |
+| [003](steps/step-003.md) | core | 分析 core/executor | pending |
+| [004](steps/step-004.md) | utils | 分析 utils/helper | pending |
+| ... | ... | ... | ... |
+
+## 整体进度
+
+- 总步骤数：XX
+- 已完成：0
+- 进行中：0
+- 待处理：XX
+
+## 执行日志
+
+| 时间 | 步骤 | 操作 | 备注 |
+|------|------|------|------|
+| | | | |
 ```

-对照检查结果，确认：
- 每个子目录都出现在某个区块中，或被标记为 `[ignored]`
- 如有未归属的目录，必须补充区块或归入现有区块
- 运行以下验证：`所有区块覆盖的目录 ∪ 被忽略的目录 = 根目录下所有子目录`
+### 阶段 4：用户确认

-### 阶段 4：逐区块完全深度探索
+向用户展示计划摘要：

-**对每个区块，必须完整阅读该区块内的每一个文件，从头到尾，不允许遗漏任何一行。**
+> 区块计划已生成。
+>
+> **区块数**：X 个
+> **总步骤数**：Y 个
+> **预估**：约需 Z 次对话完成
+>
+> 步骤文档已生成在 `steps/` 目录，每个步骤包含完整的执行信息。
+>
+> 是否开始执行？

-#### 4.1 文件处理规则
+**选项**：
+- **开始执行**（推荐）
+- **查看计划详情**
+- **稍后执行**
+
+---
+
+## 接续流程
+
+当区块计划已存在时执行此流程。
+
+### 1. 读取区块计划
+
+读取 `block-plan.md` 获取：
+- 步骤索引
+- 整体进度
+- 执行日志
+
+### 2. 显示进度
+
+> **项目文档进度**
+>
+> 总步骤数：XX
+> 已完成：YY（ZZ%）
+> 当前步骤：step-NNN
+> 上次更新：YYYY-MM-DD HH:MM
+
+### 3. 确认继续
+
+使用 AskUserQuestion：
+
+> 是否从当前进度继续执行？
+
+**选项**：
+- **继续执行**（推荐）
+- **查看待处理步骤**
+- **重新开始**（清空进度）
+
+---
+
+## 步骤执行流程
+
+### 执行单个步骤
+
+1. **读取步骤文档**：
+   - 打开 `steps/step-XXX.md`
+   - 获取目标文件清单和已知上下文
+
+2. **完全深度探索**：
+   - 按清单逐个阅读文件（从头到尾，不遗漏任何一行）
+   - 应用文件处理规则（见下文）
+
+3. **生成/更新区块文档**：
+   - 更新 `blocks/[区块名].md` 的相应部分
+   - 更新文件清单中的文件状态
+
+4. **更新步骤文档**：
+   - 标记步骤为 `completed`
+   - 填写执行记录
+
+5. **更新区块计划**：
+   - 更新步骤状态
+   - 更新整体进度
+   - 添加执行日志
+
+### 文件处理规则

 | 文件类型 | 处理方式 |
 |----------|----------|
 | **源码文件** | 完整阅读，分析逻辑和结构，提取核心信息 |
 | **配置文件** | 完整阅读，记录关键配置项 |
 | **文档文件** | 完整阅读，提取主要内容 |
-| **二进制文件** | 根据文件名、大小、关联文件信息进行上下文推断概括 |
-| **被忽略文件** | 只记录文件名/目录名，标注 `[ignored]`，不分析内容 |
+| **二进制文件** | 根据文件名、大小、关联文件信息进行上下文推断 |
+| **被忽略文件** | 只记录文件名/目录名，标注 `[ignored]` |
 | **空目录** | 记录目录名，标注 `[空目录]`，根据名称推断用途 |

-#### 4.2 每个区块需要生成
+### 步骤间询问

-1. **区块内完整目录树**：类似 tree 输出，包含该区块内所有文件和子目录
-2. **文件清单及概括**：每个文件一行概括说明
-3. **核心组件说明**：重要类/函数/模块的详细说明
-4. **依赖关系**：与其他区块的依赖
+每完成一个步骤后：

-### 阶段 5：生成总导览
+> 步骤 XXX 已完成：[描述]
+>
+> 已完成：YY/ZZ（进度 WW%）
+>
+> 是否继续下一步？

-整合所有区块信息，生成总导览文档。
+**选项**：
+- **继续**（推荐）
+- **查看产出**
+- **暂停（保存进度）**

-**总导览使用简化版目录结构**（前两层），详细结构在各区块文档中展示。
+如选择暂停，当前进度已保存在步骤文档和区块计划中，下次可直接接续。

 ---

-## 更新流程
+## 区块文档格式

-### 阶段 1：读取区块计划
-
-读取现有的区块计划文档，了解当前文档结构和完整目录树。
-
-### 阶段 2：重新扫描目录
-
-1. 重新执行完整目录扫描
-2. 对比当前目录结构与文档中记录的结构
-3. 识别新增、删除、移动的文件和目录
-
-### 阶段 3：分区块验证
-
-对每个区块：
-1. **完全重读**有变化的文件（从头到尾）
-2. 识别差异（新增、删除、修改）
-3. 更新区块内目录树
-
-### 阶段 4：增量更新
-
-1. 更新有变化的区块文档
-2. 更新区块内完整目录树
-3. 更新总导览的简化目录树（如有结构变化）
-4. 更新区块计划的时间戳
-
---
-
-## 文档格式规范
-
-### 总导览文档格式
-
-```markdown
-# [项目名称] 项目导览
-
-> 本文档面向 LLM，用于快速了解项目结构和脉络。
-> 最后更新：YYYY-MM-DD
-
-## 项目简介
-
-[1-2 段简要描述项目目的和核心功能]
-
-## 技术栈
-
- 语言：xxx
- 框架：xxx
- 主要依赖：xxx
-
-## 项目结构（简化版）
-
-[展示前两层目录结构，**必须包含所有顶层子目录**，包含空目录和忽略项标注]
-
-```
-project/
-├── src/                     源码目录
-├── tests/                   测试目录
-├── docs/                    项目文档目录
-├── discuss/                 讨论记录目录
-├── assets/                  [空目录] 资源文件
-├── cache/                   [ignored]
-├── .gitignore
-└── README.md
-```
-
-> 详细结构见各区块文档
-> **注意**：此处必须列出根目录下的所有子目录，不能遗漏非代码目录
-
-## 架构概述
-
-[简要描述项目架构，可包含简单的 ASCII 图]
-
-## 区块索引
-
-| 区块 | 路径 | 文件数 | 说明 |
-|------|------|--------|------|
-| [区块名](./blocks/xxx.md) | xxx/ | xx | 简要说明 |
-| ... | ... | ... | ... |
-
-## 快速导航
-
- 想了解 xxx → 查看 [区块名](./blocks/xxx.md)
- 想修改 xxx → 查看 [区块名](./blocks/xxx.md)
-
-## 统计信息
-
- 总目录数：xx（含 xx 个空目录）
- 总文件数：xx
- 被忽略项：xx
- 代码行数：约 xxx 行
-```
-
-### 子区块文档格式
+每个区块生成独立文档 `blocks/[区块名].md`：

 ```markdown
 # [区块名称]
@@ -310,31 +370,23 @@ project/

 ## 目录结构

-[区块内完整目录树，类似 tree 输出]
-
 ```
 xxx/
 ├── module1/
 │   ├── __init__.py
-│   ├── core.py
-│   └── utils.py
-├── module2/
-│   ├── __init__.py
-│   └── handler.py
+│   └── core.py
 ├── empty_dir/               [空目录]
 └── README.md
 ```

 ## 文件清单

-| 文件 | 类型 | 说明 |
-|------|------|------|
-| module1/__init__.py | 源码 | 模块初始化 |
-| module1/core.py | 源码 | 核心逻辑实现 |
-| module1/utils.py | 源码 | 工具函数 |
-| empty_dir/ | 目录 | [空目录] 用途推断 |
-| data.bin | 二进制 | [根据上下文推断的说明] |
-| ... | ... | ... |
+| 文件 | 类型 | 行数 | 说明 |
+|------|------|------|------|
+| module1/__init__.py | 源码 | 10 | 模块初始化 |
+| module1/core.py | 源码 | 150 | 核心逻辑实现 |
+| empty_dir/ | 目录 | - | [空目录] 用途推断 |
+| ... | ... | ... | ... |

 ## 核心组件

@@ -346,57 +398,103 @@ xxx/
  - `method1()` - 说明
  - `method2()` - 说明

-## 接口说明
-
-[对外暴露的接口、API、命令等]
-
 ## 依赖关系

 - 依赖：[其他区块名]
 - 被依赖：[其他区块名]
-
-## 注意事项
-
-[开发时需要注意的点]
 ```

 ---

-## 多对话续接
+## 总导览文档格式

-如果项目过大，可能需要多次对话完成：
+所有区块完成后，生成/更新总导览 `README.md`：

-1. 每次开始时读取区块计划
-2. 找到未完成的区块
-3. **大小控制**：单个区块不超过 5000 行代码
-4. **完全深度探索**该区块（每个文件从头到尾）
-5. 生成区块内完整目录树
-6. 更新区块计划的进度
+```markdown
+# [项目名称] 项目文档

---
+> 面向 LLM 的项目文档，用于快速了解项目结构和脉络。
+> 最后更新：YYYY-MM-DD

-## 完成
+## 项目概述

-文档创建/更新完成后：
+[1-2 段简要描述]

-1. 确认所有区块已处理
-2. 确认每个区块都有完整目录树
-3. 确认总导览包含简化版目录结构
-4. 确认没有遗漏任何文件或目录（包括空目录）
-5. **运行目录完整性最终检查**：
-   ```bash
-   # 列出根目录下所有子目录
-   ls -d */ 2>/dev/null | sort
-   ```
-   逐一核对每个子目录，确认都出现在项目文档中（区块覆盖或标记 [ignored]）
-6. 向用户汇报完成情况
+## 技术栈
+
+- 语言：xxx
+- 框架：xxx
+- 主要依赖：xxx
+
+## 目录结构（简化版）

 ```
-项目文档已更新：
- 总导览：.aide/project-docs/README.md
- 区块数：N 个
+project/
+├── src/                     源码目录
+├── tests/                   测试目录
+├── docs/                    [空目录] 文档目录
+├── cache/                   [ignored]
+└── README.md
+```
+
+> 详细结构见各区块文档
+
+## 区块索引
+
+| 区块 | 路径 | 文档 | 说明 |
+|------|------|------|------|
+| core | src/core/ | [查看](blocks/core.md) | 核心逻辑 |
+| utils | src/utils/ | [查看](blocks/utils.md) | 工具函数 |
+| ... | ... | ... | ... |
+
+## 快速导航
+
+- 想了解 xxx → 查看 [区块名](blocks/xxx.md)
+- 想修改 xxx → 查看 [区块名](blocks/xxx.md)
+
+## 统计信息
+
 - 总目录数：xx（含 xx 个空目录）
 - 总文件数：xx
 - 被忽略项：xx
- 本次更新：[新增/更新的区块列表]
+- 代码行数：约 xxx 行
 ```
+
+---
+
+## 完成流程
+
+当所有步骤完成时：
+
+1. 确认所有步骤状态为 `completed`
+2. 生成/更新总导览文档
+3. 运行完整性检查
+4. 向用户汇报完成情况
+
+```
+项目文档已完成：
+- 总导览：.aide/project-docs/README.md
+- 区块数：N 个
+- 总步骤数：M 个
+- 总目录数：xx（含 xx 个空目录）
+- 总文件数：xx
+```
+
+---
+
+## 配置项
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `docs.path` | `.aide/project-docs` | 文档目录 |
+| `docs.block_plan_path` | `.aide/project-docs/block-plan.md` | 区块计划文件 |
+| `docs.steps_path` | `.aide/project-docs/steps` | 步骤文档目录 |
+
+---
+
+## 注意事项
+
+1. **分步执行**：每个步骤文档包含完整执行信息，接续执行无需重新分析
+2. **进度持久化**：进度同时保存在步骤文档和区块计划中
+3. **粒度可控**：大型区块自动拆分为多个步骤
+4. **完整性保证**：每个文件的处理状态都有记录
--- a/aide-marketplace/aide-plugin/commands/user-docs.md
+++ b/aide-marketplace/aide-plugin/commands/user-docs.md
@@ -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 中的文档链接自动更新
--- a/aide-marketplace/aide-plugin/commands/user-graph.md
+++ b/aide-marketplace/aide-plugin/commands/user-graph.md
@@ -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]` 配置）
--- a/task-now.md
+++ b/task-now.md
@@ -1,15 +0,0 @@
-我之前有一次任务的内容，我把它的节选保存在了 @cache/old-task.md 文件中，
-
-现在那部分内容已经被实现为了commands下的readme.md、user-docs.md和user-graph.md，
-
-我现在想要做的是，
-
-首先，分析当前的user-graph和user-docs是否真的具备我原本所期望的那种的**分步执行**和**接续执行**能力，
-
-他们的分步计划执行的是真正有意义的有效的分步吗？还是只是形式上的分步？
-
-如果是一个小项目，原本一次就能完成全部内容的任务，它是分两步还是分五步其实没什么区别，
-
-但如果是一个100万行代码的大型项目，它可能只有七八个模块组成但是模块毕竟庞大，这样的项目就算分8步也是没办法在一次上下文消耗的限额内完成其中的任何一部的，而一旦超出限额出发上下文压缩就会导致损失大量有效信息，这不是我想要的
-
-所以，它们现在的“分步”真的有用吗？是我要的分步吗？怎么修正？