[aide] impl: 完成 docs.md 命令文件修改

2025-12-17 01:51:43 +08:00
parent 65c02dc797
commit dfe26eff43
3 changed files with 175 additions and 39 deletions
--- a/aide-marketplace/aide-plugin/commands/docs.md
+++ b/aide-marketplace/aide-plugin/commands/docs.md
@@ -1,6 +1,10 @@
 # Aide 项目文档管理

-你正在执行 Aide 项目文档管理流程。创建和维护面向 LLM 的项目文档。
+你正在执行 Aide 项目文档管理流程。创建和维护面向 LLM 的**完整深度**项目文档。
+
+## 核心原则
+
+> **完全深度探索**：不考虑过度设计、开销、效率问题。对项目中的每一个文件、每一个目录（包括空目录）都要完全覆盖，不允许遗漏。

 ## 前置准备

@@ -31,12 +35,60 @@ aide config get docs.block_plan_path

 ## 创建流程

-### 阶段 1：目录探索
+### 阶段 1：完整目录扫描

-1. 遍历项目目录结构
-2. 统计文件数量和大小
-3. 识别 `.gitignore` 排除项
-4. 记录关键文件（README、配置文件、入口文件等）
+**此阶段必须完整执行，不允许跳过任何目录或文件。**
+
+#### 1.1 读取忽略规则
+
+读取项目根目录的 `.gitignore` 文件，解析忽略规则。
+
+#### 1.2 递归遍历所有目录
+
+使用 `find` 或类似命令遍历项目所有目录和文件：
+
+```bash
+# 获取完整目录树（排除 .git）
+find . -not -path './.git/*' -not -name '.git' | sort
+```
+
+**必须记录的信息**：
+- 每个目录（包括空目录）
+- 每个文件的路径
+- 文件大小
+- 文件类型（源码/配置/文档/二进制/其他）
+
+#### 1.3 生成目录树结构
+
+生成类似 `tree` 命令输出的完整目录结构，对于 .gitignore 中的项目标注 `[ignored]`：
+
+```
+project/
+├── src/
+│   ├── main.py
+│   ├── utils/
+│   │   ├── helper.py
+│   │   └── config.py
+│   └── __init__.py
+├── tests/
+│   └── test_main.py
+├── docs/                    [空目录]
+├── cache/                   [ignored]
+├── node_modules/            [ignored]
+├── .gitignore
+├── README.md
+└── requirements.txt
+```
+
+#### 1.4 统计项目信息
+
+```
+- 总目录数：xx（含 xx 个空目录）
+- 总文件数：xx
+- 源码文件：xx
+- 被忽略项：xx
+- 代码行数：约 xxx 行
+```

 ### 阶段 2：初步区块划分

@@ -44,7 +96,7 @@ aide config get docs.block_plan_path

 1. **按目录结构**：每个主要目录可作为一个区块
 2. **按功能模块**：相关功能的文件归为一个区块
-3. **大小控制**：单个区块不超过 5000 行代码
+3. **包含空目录**：空目录也要归入相应区块
 4. **低耦合**：区块间依赖关系尽量简单

 生成初步区块计划：
@@ -55,14 +107,19 @@ aide config get docs.block_plan_path
 ## 项目概况
 - 项目名称：xxx
 - 主要语言：xxx
- 文件总数：xxx
+- 文件总数：xxx（含 xx 被忽略）
+- 空目录数：xxx
 - 代码行数：xxx

+## 完整目录树（简化版）
+[前两层目录结构]
+
 ## 区块划分

 ### 区块 1：[名称]
 - 路径：xxx/
 - 文件数：xx
+- 空目录：xx
 - 状态：待处理

 ### 区块 2：[名称]
@@ -77,45 +134,66 @@ aide config get docs.block_plan_path
 ### 阶段 3：区块验证

 对每个区块进行浅层探索：
-1. 阅读区块内的关键文件（入口、配置、README）
+1. 确认区块包含的所有文件和目录
 2. 验证区块划分是否合理
 3. 调整区块边界（如需要）
+4. 确保没有遗漏任何文件或目录

-### 阶段 4：逐区块深度了解
+### 阶段 4：逐区块完全深度探索

-对每个区块：
+**对每个区块，必须完整阅读该区块内的每一个文件，从头到尾，不允许遗漏任何一行。**

-1. **完整阅读**：阅读区块内所有文件
-2. **提取信息**：
-   - 模块职责
-   - 核心组件/类/函数
-   - 对外接口
-   - 依赖关系
-3. **生成文档**：按子区块文档格式生成
+#### 4.1 文件处理规则
+
+| 文件类型 | 处理方式 |
+|----------|----------|
+| **源码文件** | 完整阅读，分析逻辑和结构，提取核心信息 |
+| **配置文件** | 完整阅读，记录关键配置项 |
+| **文档文件** | 完整阅读，提取主要内容 |
+| **二进制文件** | 根据文件名、大小、关联文件信息进行上下文推断概括 |
+| **被忽略文件** | 只记录文件名/目录名，标注 `[ignored]`，不分析内容 |
+| **空目录** | 记录目录名，标注 `[空目录]`，根据名称推断用途 |
+
+#### 4.2 每个区块需要生成
+
+1. **区块内完整目录树**：类似 tree 输出，包含该区块内所有文件和子目录
+2. **文件清单及概括**：每个文件一行概括说明
+3. **核心组件说明**：重要类/函数/模块的详细说明
+4. **依赖关系**：与其他区块的依赖

 ### 阶段 5：生成总导览

 整合所有区块信息，生成总导览文档。

+**总导览使用简化版目录结构**（前两层），详细结构在各区块文档中展示。
+
 ---

 ## 更新流程

 ### 阶段 1：读取区块计划

-读取现有的区块计划文档，了解当前文档结构。
+读取现有的区块计划文档，了解当前文档结构和完整目录树。

-### 阶段 2：分区块验证
+### 阶段 2：重新扫描目录
+
+1. 重新执行完整目录扫描
+2. 对比当前目录结构与文档中记录的结构
+3. 识别新增、删除、移动的文件和目录
+
+### 阶段 3：分区块验证

 对每个区块：
-1. 对比文档与当前代码
+1. **完全重读**有变化的文件（从头到尾）
 2. 识别差异（新增、删除、修改）
+3. 更新区块内目录树

-### 阶段 3：增量更新
+### 阶段 4：增量更新

 1. 更新有变化的区块文档
-2. 更新总导览（如需要）
-3. 更新区块计划的时间戳
+2. 更新区块内完整目录树
+3. 更新总导览的简化目录树（如有结构变化）
+4. 更新区块计划的时间戳

 ---

@@ -139,21 +217,44 @@ aide config get docs.block_plan_path
 - 框架：xxx
 - 主要依赖：xxx

+## 项目结构（简化版）
+
+[展示前两层目录结构，包含空目录和忽略项标注]
+
+```
+project/
+├── src/                     源码目录
+├── tests/                   测试目录
+├── docs/                    [空目录]
+├── cache/                   [ignored]
+├── .gitignore
+└── README.md
+```
+
+> 详细结构见各区块文档
+
 ## 架构概述

 [简要描述项目架构，可包含简单的 ASCII 图]

 ## 区块索引

-| 区块 | 路径 | 说明 |
-|------|------|------|
-| [区块名](./blocks/xxx.md) | xxx/ | 简要说明 |
-| ... | ... | ... |
+| 区块 | 路径 | 文件数 | 说明 |
+|------|------|--------|------|
+| [区块名](./blocks/xxx.md) | xxx/ | xx | 简要说明 |
+| ... | ... | ... | ... |

 ## 快速导航

 - 想了解 xxx → 查看 [区块名](./blocks/xxx.md)
 - 想修改 xxx → 查看 [区块名](./blocks/xxx.md)
+
+## 统计信息
+
+- 总目录数：xx（含 xx 个空目录）
+- 总文件数：xx
+- 被忽略项：xx
+- 代码行数：约 xxx 行
 ```

 ### 子区块文档格式
@@ -168,12 +269,33 @@ aide config get docs.block_plan_path

 [区块的职责和作用]

+## 目录结构
+
+[区块内完整目录树，类似 tree 输出]
+
+```
+xxx/
+├── module1/
+│   ├── __init__.py
+│   ├── core.py
+│   └── utils.py
+├── module2/
+│   ├── __init__.py
+│   └── handler.py
+├── empty_dir/               [空目录]
+└── README.md
+```
+
 ## 文件清单

-| 文件 | 说明 |
-|------|------|
-| xxx.py | 简要说明 |
-| ... | ... |
+| 文件 | 类型 | 说明 |
+|------|------|------|
+| module1/__init__.py | 源码 | 模块初始化 |
+| module1/core.py | 源码 | 核心逻辑实现 |
+| module1/utils.py | 源码 | 工具函数 |
+| empty_dir/ | 目录 | [空目录] 用途推断 |
+| data.bin | 二进制 | [根据上下文推断的说明] |
+| ... | ... | ... |

 ## 核心组件

@@ -207,8 +329,9 @@ aide config get docs.block_plan_path

 1. 每次开始时读取区块计划
 2. 找到未完成的区块
-3. 继续处理
-4. 更新区块计划的进度
+3. **完全深度探索**该区块（每个文件从头到尾）
+4. 生成区块内完整目录树
+5. 更新区块计划的进度

 ---

@@ -217,12 +340,17 @@ aide config get docs.block_plan_path
 文档创建/更新完成后：

 1. 确认所有区块已处理
-2. 确认总导览已更新
-3. 向用户汇报完成情况
+2. 确认每个区块都有完整目录树
+3. 确认总导览包含简化版目录结构
+4. 确认没有遗漏任何文件或目录（包括空目录）
+5. 向用户汇报完成情况

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