403 lines
11 KiB
Markdown
403 lines
11 KiB
Markdown
# Aide 项目文档管理
|
||
|
||
你正在执行 Aide 项目文档管理流程。创建和维护面向 LLM 的**完整深度**项目文档。
|
||
|
||
## 核心原则
|
||
|
||
> **完全深度探索**：不考虑过度设计、开销、效率问题。对项目中的每一个文件、每一个目录（包括空目录）都要完全覆盖，不允许遗漏。
|
||
|
||
## 前置准备
|
||
|
||
**首先触发 `aide` skill 学习 aide 命令的使用方法。**
|
||
|
||
这是一个非常长的任务，因此规划您的工作可能会很有益。**建议花费您的整个输出上下文来处理任务 - 只需确保您不会在有大量未提交的工作时用尽上下文。**继续系统地工作，直到您完成此任务。**您的上下文窗口将在接近其限制时自动压缩，允许您从中断的地方继续无限期地工作。因此，不要因为令牌预算问题而提前停止任务。**当您接近令牌预算限制时，在上下文窗口刷新前将您当前的进度和状态保存到内存中。始终尽可能坚持和自主，并完全完成任务，即使您的预算即将用尽。无论剩余上下文如何，永远不要人为地提前停止任何任务。
|
||
|
||
|
||
---
|
||
|
||
## 开始
|
||
|
||
### 检查文档配置
|
||
|
||
```bash
|
||
aide config get docs.path
|
||
aide config get docs.block_plan_path
|
||
```
|
||
|
||
如果未配置，使用默认值：
|
||
- 文档目录：`.aide/project-docs`
|
||
- 区块计划：`.aide/project-docs/block-plan.md`
|
||
|
||
### 检查文档状态
|
||
|
||
检查文档目录是否存在及其内容：
|
||
- 不存在或为空 → 进入**创建流程**
|
||
- 已存在 → 进入**更新流程**
|
||
|
||
---
|
||
|
||
## 创建流程
|
||
|
||
### 阶段 1：完整目录扫描
|
||
|
||
**此阶段必须完整执行，不允许跳过任何目录或文件。**
|
||
|
||
#### 1.1 读取忽略规则
|
||
|
||
读取项目根目录的 `.gitignore` 文件，解析忽略规则。
|
||
|
||
#### 1.2 递归遍历所有目录
|
||
|
||
使用 `find` 或类似命令遍历项目所有目录和文件：
|
||
|
||
```bash
|
||
# 获取完整目录树（排除 .git）
|
||
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
|
||
```
|
||
|
||
#### 1.4 统计项目信息
|
||
|
||
```
|
||
- 总目录数：xx（含 xx 个空目录）
|
||
- 总文件数：xx
|
||
- 源码文件：xx
|
||
- 被忽略项：xx
|
||
- 代码行数：约 xxx 行
|
||
```
|
||
|
||
### 阶段 2：初步区块划分
|
||
|
||
根据以下规则划分区块：
|
||
|
||
1. **按目录结构**：每个主要目录可作为一个区块
|
||
2. **按功能模块**：相关功能的文件归为一个区块
|
||
3. **包含空目录**：空目录也要归入相应区块
|
||
4. **低耦合**：区块间依赖关系尽量简单
|
||
5. **完整覆盖**：根目录下每个非忽略的子目录都必须归入某个区块
|
||
|
||
> **强制规则**：非代码目录（如 `docs/`、`assets/`、`discuss/` 等）同样必须作为区块进行覆盖，不能因为"非核心代码"而跳过。
|
||
|
||
生成初步区块计划：
|
||
|
||
```markdown
|
||
# 区块计划
|
||
|
||
## 项目概况
|
||
- 项目名称：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. 确保没有遗漏任何文件或目录
|
||
|
||
**强制完整性检查**：
|
||
|
||
```bash
|
||
# 列出根目录下所有子目录（排除 .git）
|
||
ls -d */ 2>/dev/null | sort
|
||
```
|
||
|
||
对照检查结果，确认：
|
||
- 每个子目录都出现在某个区块中，或被标记为 `[ignored]`
|
||
- 如有未归属的目录，必须补充区块或归入现有区块
|
||
- 运行以下验证：`所有区块覆盖的目录 ∪ 被忽略的目录 = 根目录下所有子目录`
|
||
|
||
### 阶段 4：逐区块完全深度探索
|
||
|
||
**对每个区块，必须完整阅读该区块内的每一个文件，从头到尾，不允许遗漏任何一行。**
|
||
|
||
#### 4.1 文件处理规则
|
||
|
||
| 文件类型 | 处理方式 |
|
||
|----------|----------|
|
||
| **源码文件** | 完整阅读，分析逻辑和结构，提取核心信息 |
|
||
| **配置文件** | 完整阅读，记录关键配置项 |
|
||
| **文档文件** | 完整阅读，提取主要内容 |
|
||
| **二进制文件** | 根据文件名、大小、关联文件信息进行上下文推断概括 |
|
||
| **被忽略文件** | 只记录文件名/目录名，标注 `[ignored]`，不分析内容 |
|
||
| **空目录** | 记录目录名，标注 `[空目录]`，根据名称推断用途 |
|
||
|
||
#### 4.2 每个区块需要生成
|
||
|
||
1. **区块内完整目录树**：类似 tree 输出，包含该区块内所有文件和子目录
|
||
2. **文件清单及概括**：每个文件一行概括说明
|
||
3. **核心组件说明**：重要类/函数/模块的详细说明
|
||
4. **依赖关系**：与其他区块的依赖
|
||
|
||
### 阶段 5：生成总导览
|
||
|
||
整合所有区块信息，生成总导览文档。
|
||
|
||
**总导览使用简化版目录结构**（前两层），详细结构在各区块文档中展示。
|
||
|
||
---
|
||
|
||
## 更新流程
|
||
|
||
### 阶段 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 行
|
||
```
|
||
|
||
### 子区块文档格式
|
||
|
||
```markdown
|
||
# [区块名称]
|
||
|
||
> 路径：xxx/
|
||
> 最后更新：YYYY-MM-DD
|
||
|
||
## 概述
|
||
|
||
[区块的职责和作用]
|
||
|
||
## 目录结构
|
||
|
||
[区块内完整目录树，类似 tree 输出]
|
||
|
||
```
|
||
xxx/
|
||
├── module1/
|
||
│ ├── __init__.py
|
||
│ ├── core.py
|
||
│ └── utils.py
|
||
├── module2/
|
||
│ ├── __init__.py
|
||
│ └── handler.py
|
||
├── empty_dir/ [空目录]
|
||
└── README.md
|
||
```
|
||
|
||
## 文件清单
|
||
|
||
| 文件 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| module1/__init__.py | 源码 | 模块初始化 |
|
||
| module1/core.py | 源码 | 核心逻辑实现 |
|
||
| module1/utils.py | 源码 | 工具函数 |
|
||
| empty_dir/ | 目录 | [空目录] 用途推断 |
|
||
| data.bin | 二进制 | [根据上下文推断的说明] |
|
||
| ... | ... | ... |
|
||
|
||
## 核心组件
|
||
|
||
### [组件/类/函数名]
|
||
|
||
- **职责**：xxx
|
||
- **位置**：`文件:行号`
|
||
- **关键方法**：
|
||
- `method1()` - 说明
|
||
- `method2()` - 说明
|
||
|
||
## 接口说明
|
||
|
||
[对外暴露的接口、API、命令等]
|
||
|
||
## 依赖关系
|
||
|
||
- 依赖：[其他区块名]
|
||
- 被依赖：[其他区块名]
|
||
|
||
## 注意事项
|
||
|
||
[开发时需要注意的点]
|
||
```
|
||
|
||
---
|
||
|
||
## 多对话续接
|
||
|
||
如果项目过大，可能需要多次对话完成：
|
||
|
||
1. 每次开始时读取区块计划
|
||
2. 找到未完成的区块
|
||
3. **大小控制**：单个区块不超过 5000 行代码
|
||
4. **完全深度探索**该区块（每个文件从头到尾）
|
||
5. 生成区块内完整目录树
|
||
6. 更新区块计划的进度
|
||
|
||
---
|
||
|
||
## 完成
|
||
|
||
文档创建/更新完成后：
|
||
|
||
1. 确认所有区块已处理
|
||
2. 确认每个区块都有完整目录树
|
||
3. 确认总导览包含简化版目录结构
|
||
4. 确认没有遗漏任何文件或目录（包括空目录）
|
||
5. **运行目录完整性最终检查**：
|
||
```bash
|
||
# 列出根目录下所有子目录
|
||
ls -d */ 2>/dev/null | sort
|
||
```
|
||
逐一核对每个子目录，确认都出现在项目文档中（区块覆盖或标记 [ignored]）
|
||
6. 向用户汇报完成情况
|
||
|
||
```
|
||
项目文档已更新：
|
||
- 总导览：.aide/project-docs/README.md
|
||
- 区块数：N 个
|
||
- 总目录数：xx（含 xx 个空目录）
|
||
- 总文件数：xx
|
||
- 被忽略项：xx
|
||
- 本次更新：[新增/更新的区块列表]
|
||
```
|