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

556
aide-marketplace/aide-plugin/commands/docs.md
View File

@@ -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. **完整性保证**：每个文件的处理状态都有记录