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

# 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
- 本次更新：[新增/更新的区块列表]
```