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

Aide 项目文档管理

你正在执行 Aide 项目文档管理流程。创建和维护面向 LLM 的完整深度项目文档。

核心原则

完全深度探索：不考虑过度设计、开销、效率问题。对项目中的每一个文件、每一个目录（包括空目录）都要完全覆盖，不允许遗漏。

前置准备

首先触发 aide skill 学习 aide 命令的使用方法。

---

开始

检查文档配置

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 或类似命令遍历项目所有目录和文件：

# 获取完整目录树（排除 .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/ 等）同样必须作为区块进行覆盖，不能因为"非核心代码"而跳过。

生成初步区块计划：

# 区块计划

## 项目概况
- 项目名称：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. 确保没有遗漏任何文件或目录

强制完整性检查：

# 列出根目录下所有子目录（排除 .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. 更新区块计划的时间戳

---

文档格式规范

总导览文档格式

# [项目名称] 项目导览

> 本文档面向 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 行

子区块文档格式

# [区块名称]

> 路径：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. 运行目录完整性最终检查：

   # 列出根目录下所有子目录
   ls -d */ 2>/dev/null | sort
   

   逐一核对每个子目录，确认都出现在项目文档中（区块覆盖或标记 [ignored]）
6. 向用户汇报完成情况

项目文档已更新：
- 总导览：.aide/project-docs/README.md
- 区块数：N 个
- 总目录数：xx（含 xx 个空目录）
- 总文件数：xx
- 被忽略项：xx
- 本次更新：[新增/更新的区块列表]