501 lines
12 KiB
Markdown
501 lines
12 KiB
Markdown
# Aide 项目文档管理
|
||
|
||
你正在执行 Aide 项目文档管理流程。创建和维护面向 LLM 的**完整深度**项目文档。
|
||
|
||
## 核心原则
|
||
|
||
> **完全深度探索**：不考虑过度设计、开销、效率问题。对项目中的每一个文件、每一个目录（包括空目录）都要完全覆盖，不允许遗漏。
|
||
|
||
## 分步执行机制
|
||
|
||
此命令支持**真正有效的分步执行和接续执行**，适用于任意规模项目（包括百万行代码级别）。
|
||
|
||
### 设计原则
|
||
|
||
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 命令的使用方法。**
|
||
|
||
这是一个非常长的任务，因此规划您的工作可能会很有益。**建议花费您的整个输出上下文来处理任务 - 只需确保您不会在有大量未提交的工作时用尽上下文。**继续系统地工作，直到您完成此任务。**您的上下文窗口将在接近其限制时自动压缩，允许您从中断的地方继续无限期地工作。因此，不要因为令牌预算问题而提前停止任务。**当您接近令牌预算限制时，在上下文窗口刷新前将您当前的进度和状态保存到内存中。始终尽可能坚持和自主，并完全完成任务，即使您的预算即将用尽。无论剩余上下文如何，永远不要人为地提前停止任何任务。
|
||
|
||
---
|
||
|
||
## 开始
|
||
|
||
### 检查文档配置
|
||
|
||
```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`
|
||
|
||
### 检查文档状态
|
||
|
||
检查区块计划文件是否存在：
|
||
- **不存在** → 进入**创建流程**
|
||
- **已存在** → 进入**接续流程**
|
||
|
||
---
|
||
|
||
## 创建流程
|
||
|
||
### 阶段 1：完整目录扫描
|
||
|
||
**此阶段必须完整执行，不允许跳过任何目录或文件。**
|
||
|
||
#### 1.1 读取忽略规则
|
||
|
||
读取项目根目录的 `.gitignore` 文件，解析忽略规则。
|
||
|
||
#### 1.2 递归遍历所有目录
|
||
|
||
使用 `find` 或类似命令遍历项目所有目录和文件：
|
||
|
||
```bash
|
||
# 获取完整目录树（排除 .git）
|
||
find . -not -path './.git/*' -not -name '.git' | sort
|
||
```
|
||
|
||
**必须记录的信息**：
|
||
- 每个目录（包括空目录）
|
||
- 每个文件的路径
|
||
- 文件大小
|
||
- 文件类型（源码/配置/文档/二进制/其他）
|
||
|
||
#### 1.3 生成目录树结构
|
||
|
||
生成完整目录结构，对于 .gitignore 中的项目标注 `[ignored]`。
|
||
|
||
#### 1.4 统计项目信息
|
||
|
||
```
|
||
- 总目录数：xx（含 xx 个空目录）
|
||
- 总文件数：xx
|
||
- 源码文件：xx
|
||
- 被忽略项：xx
|
||
- 代码行数：约 xxx 行
|
||
```
|
||
|
||
### 阶段 2：区块划分
|
||
|
||
根据以下规则划分区块：
|
||
|
||
1. **按目录结构**：每个主要目录可作为一个区块
|
||
2. **按功能模块**：相关功能的文件归为一个区块
|
||
3. **包含空目录**：空目录也要归入相应区块
|
||
4. **低耦合**：区块间依赖关系尽量简单
|
||
5. **完整覆盖**：每个非忽略的子目录都必须归入某个区块
|
||
|
||
### 阶段 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 | core | src/core/ | 25 | 3 | pending | 001-003 |
|
||
| 2 | utils | src/utils/ | 45 | 5 | pending | 004-008 |
|
||
| ... | ... | ... | ... | ... | ... | ... |
|
||
|
||
## 步骤索引
|
||
|
||
| 步骤 | 所属区块 | 描述 | 状态 |
|
||
|------|----------|------|------|
|
||
| [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
|
||
|
||
## 执行日志
|
||
|
||
| 时间 | 步骤 | 操作 | 备注 |
|
||
|------|------|------|------|
|
||
| | | | |
|
||
```
|
||
|
||
### 阶段 4：用户确认
|
||
|
||
向用户展示计划摘要：
|
||
|
||
> 区块计划已生成。
|
||
>
|
||
> **区块数**：X 个
|
||
> **总步骤数**：Y 个
|
||
> **预估**：约需 Z 次对话完成
|
||
>
|
||
> 步骤文档已生成在 `steps/` 目录，每个步骤包含完整的执行信息。
|
||
>
|
||
> 是否开始执行？
|
||
|
||
**选项**：
|
||
- **开始执行**（推荐）
|
||
- **查看计划详情**
|
||
- **稍后执行**
|
||
|
||
---
|
||
|
||
## 接续流程
|
||
|
||
当区块计划已存在时执行此流程。
|
||
|
||
### 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]` |
|
||
| **空目录** | 记录目录名，标注 `[空目录]`，根据名称推断用途 |
|
||
|
||
### 步骤间询问
|
||
|
||
每完成一个步骤后：
|
||
|
||
> 步骤 XXX 已完成：[描述]
|
||
>
|
||
> 已完成：YY/ZZ（进度 WW%）
|
||
>
|
||
> 是否继续下一步？
|
||
|
||
**选项**：
|
||
- **继续**（推荐）
|
||
- **查看产出**
|
||
- **暂停（保存进度）**
|
||
|
||
如选择暂停，当前进度已保存在步骤文档和区块计划中，下次可直接接续。
|
||
|
||
---
|
||
|
||
## 区块文档格式
|
||
|
||
每个区块生成独立文档 `blocks/[区块名].md`：
|
||
|
||
```markdown
|
||
# [区块名称]
|
||
|
||
> 路径：xxx/
|
||
> 最后更新：YYYY-MM-DD
|
||
|
||
## 概述
|
||
|
||
[区块的职责和作用]
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
xxx/
|
||
├── module1/
|
||
│ ├── __init__.py
|
||
│ └── core.py
|
||
├── empty_dir/ [空目录]
|
||
└── README.md
|
||
```
|
||
|
||
## 文件清单
|
||
|
||
| 文件 | 类型 | 行数 | 说明 |
|
||
|------|------|------|------|
|
||
| module1/__init__.py | 源码 | 10 | 模块初始化 |
|
||
| module1/core.py | 源码 | 150 | 核心逻辑实现 |
|
||
| empty_dir/ | 目录 | - | [空目录] 用途推断 |
|
||
| ... | ... | ... | ... |
|
||
|
||
## 核心组件
|
||
|
||
### [组件/类/函数名]
|
||
|
||
- **职责**：xxx
|
||
- **位置**：`文件:行号`
|
||
- **关键方法**：
|
||
- `method1()` - 说明
|
||
- `method2()` - 说明
|
||
|
||
## 依赖关系
|
||
|
||
- 依赖：[其他区块名]
|
||
- 被依赖：[其他区块名]
|
||
```
|
||
|
||
---
|
||
|
||
## 总导览文档格式
|
||
|
||
所有区块完成后，生成/更新总导览 `README.md`：
|
||
|
||
```markdown
|
||
# [项目名称] 项目文档
|
||
|
||
> 面向 LLM 的项目文档，用于快速了解项目结构和脉络。
|
||
> 最后更新：YYYY-MM-DD
|
||
|
||
## 项目概述
|
||
|
||
[1-2 段简要描述]
|
||
|
||
## 技术栈
|
||
|
||
- 语言：xxx
|
||
- 框架：xxx
|
||
- 主要依赖：xxx
|
||
|
||
## 目录结构（简化版）
|
||
|
||
```
|
||
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. **完整性保证**：每个文件的处理状态都有记录
|