agent-aide/aide-marketplace/aide-plugin/commands/docs.md

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