229 lines
4.1 KiB
Markdown
229 lines
4.1 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. 遍历项目目录结构
|
|||
|
|
2. 统计文件数量和大小
|
|||
|
|
3. 识别 `.gitignore` 排除项
|
|||
|
|
4. 记录关键文件（README、配置文件、入口文件等）
|
|||
|
|
|
|||
|
|
### 阶段 2：初步区块划分
|
|||
|
|
|
|||
|
|
根据以下规则划分区块：
|
|||
|
|
|
|||
|
|
1. **按目录结构**：每个主要目录可作为一个区块
|
|||
|
|
2. **按功能模块**：相关功能的文件归为一个区块
|
|||
|
|
3. **大小控制**：单个区块不超过 5000 行代码
|
|||
|
|
4. **低耦合**：区块间依赖关系尽量简单
|
|||
|
|
|
|||
|
|
生成初步区块计划：
|
|||
|
|
|
|||
|
|
```markdown
|
|||
|
|
# 区块计划
|
|||
|
|
|
|||
|
|
## 项目概况
|
|||
|
|
- 项目名称：xxx
|
|||
|
|
- 主要语言：xxx
|
|||
|
|
- 文件总数：xxx
|
|||
|
|
- 代码行数：xxx
|
|||
|
|
|
|||
|
|
## 区块划分
|
|||
|
|
|
|||
|
|
### 区块 1：[名称]
|
|||
|
|
- 路径：xxx/
|
|||
|
|
- 文件数：xx
|
|||
|
|
- 状态：待处理
|
|||
|
|
|
|||
|
|
### 区块 2：[名称]
|
|||
|
|
...
|
|||
|
|
|
|||
|
|
## 进度追踪
|
|||
|
|
- [ ] 区块 1
|
|||
|
|
- [ ] 区块 2
|
|||
|
|
...
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 阶段 3：区块验证
|
|||
|
|
|
|||
|
|
对每个区块进行浅层探索：
|
|||
|
|
1. 阅读区块内的关键文件（入口、配置、README）
|
|||
|
|
2. 验证区块划分是否合理
|
|||
|
|
3. 调整区块边界（如需要）
|
|||
|
|
|
|||
|
|
### 阶段 4：逐区块深度了解
|
|||
|
|
|
|||
|
|
对每个区块：
|
|||
|
|
|
|||
|
|
1. **完整阅读**：阅读区块内所有文件
|
|||
|
|
2. **提取信息**：
|
|||
|
|
- 模块职责
|
|||
|
|
- 核心组件/类/函数
|
|||
|
|
- 对外接口
|
|||
|
|
- 依赖关系
|
|||
|
|
3. **生成文档**：按子区块文档格式生成
|
|||
|
|
|
|||
|
|
### 阶段 5：生成总导览
|
|||
|
|
|
|||
|
|
整合所有区块信息，生成总导览文档。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 更新流程
|
|||
|
|
|
|||
|
|
### 阶段 1：读取区块计划
|
|||
|
|
|
|||
|
|
读取现有的区块计划文档，了解当前文档结构。
|
|||
|
|
|
|||
|
|
### 阶段 2：分区块验证
|
|||
|
|
|
|||
|
|
对每个区块：
|
|||
|
|
1. 对比文档与当前代码
|
|||
|
|
2. 识别差异（新增、删除、修改）
|
|||
|
|
|
|||
|
|
### 阶段 3：增量更新
|
|||
|
|
|
|||
|
|
1. 更新有变化的区块文档
|
|||
|
|
2. 更新总导览（如需要）
|
|||
|
|
3. 更新区块计划的时间戳
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 文档格式规范
|
|||
|
|
|
|||
|
|
### 总导览文档格式
|
|||
|
|
|
|||
|
|
```markdown
|
|||
|
|
# [项目名称] 项目导览
|
|||
|
|
|
|||
|
|
> 本文档面向 LLM，用于快速了解项目结构和脉络。
|
|||
|
|
> 最后更新：YYYY-MM-DD
|
|||
|
|
|
|||
|
|
## 项目简介
|
|||
|
|
|
|||
|
|
[1-2 段简要描述项目目的和核心功能]
|
|||
|
|
|
|||
|
|
## 技术栈
|
|||
|
|
|
|||
|
|
- 语言：xxx
|
|||
|
|
- 框架：xxx
|
|||
|
|
- 主要依赖：xxx
|
|||
|
|
|
|||
|
|
## 架构概述
|
|||
|
|
|
|||
|
|
[简要描述项目架构，可包含简单的 ASCII 图]
|
|||
|
|
|
|||
|
|
## 区块索引
|
|||
|
|
|
|||
|
|
| 区块 | 路径 | 说明 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| [区块名](./blocks/xxx.md) | xxx/ | 简要说明 |
|
|||
|
|
| ... | ... | ... |
|
|||
|
|
|
|||
|
|
## 快速导航
|
|||
|
|
|
|||
|
|
- 想了解 xxx → 查看 [区块名](./blocks/xxx.md)
|
|||
|
|
- 想修改 xxx → 查看 [区块名](./blocks/xxx.md)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 子区块文档格式
|
|||
|
|
|
|||
|
|
```markdown
|
|||
|
|
# [区块名称]
|
|||
|
|
|
|||
|
|
> 路径：xxx/
|
|||
|
|
> 最后更新：YYYY-MM-DD
|
|||
|
|
|
|||
|
|
## 概述
|
|||
|
|
|
|||
|
|
[区块的职责和作用]
|
|||
|
|
|
|||
|
|
## 文件清单
|
|||
|
|
|
|||
|
|
| 文件 | 说明 |
|
|||
|
|
|------|------|
|
|||
|
|
| xxx.py | 简要说明 |
|
|||
|
|
| ... | ... |
|
|||
|
|
|
|||
|
|
## 核心组件
|
|||
|
|
|
|||
|
|
### [组件/类/函数名]
|
|||
|
|
|
|||
|
|
- **职责**：xxx
|
|||
|
|
- **位置**：`文件:行号`
|
|||
|
|
- **关键方法**：
|
|||
|
|
- `method1()` - 说明
|
|||
|
|
- `method2()` - 说明
|
|||
|
|
|
|||
|
|
## 接口说明
|
|||
|
|
|
|||
|
|
[对外暴露的接口、API、命令等]
|
|||
|
|
|
|||
|
|
## 依赖关系
|
|||
|
|
|
|||
|
|
- 依赖：[其他区块名]
|
|||
|
|
- 被依赖：[其他区块名]
|
|||
|
|
|
|||
|
|
## 注意事项
|
|||
|
|
|
|||
|
|
[开发时需要注意的点]
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 多对话续接
|
|||
|
|
|
|||
|
|
如果项目过大，可能需要多次对话完成：
|
|||
|
|
|
|||
|
|
1. 每次开始时读取区块计划
|
|||
|
|
2. 找到未完成的区块
|
|||
|
|
3. 继续处理
|
|||
|
|
4. 更新区块计划的进度
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 完成
|
|||
|
|
|
|||
|
|
文档创建/更新完成后：
|
|||
|
|
|
|||
|
|
1. 确认所有区块已处理
|
|||
|
|
2. 确认总导览已更新
|
|||
|
|
3. 向用户汇报完成情况
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
项目文档已更新：
|
|||
|
|
- 总导览：.aide/project-docs/README.md
|
|||
|
|
- 区块数：N 个
|
|||
|
|
- 本次更新：[新增/更新的区块列表]
|
|||
|
|
```
|