# /aide:docs 命令设计文档 ## 一、概述 `/aide:docs` 是项目文档管理命令，用于创建和维护面向 LLM 的**完整深度**项目文档。 ### 1.1 设计目标 | 目标 | 说明 | |------|------| | 完全深度探索 | 对每个文件、每个目录（包括空目录）完全覆盖，不考虑效率 | | 独立运行 | 通常在需要时单独执行 | | 区块化 | 文档按区块组织，支持增量更新 | | 面向 LLM | 文档格式针对 LLM 理解优化 | | 多对话续接 | 大项目支持多次对话完成 | ### 1.2 核心原则 > **完全深度探索**：不考虑过度设计、开销、效率问题。对项目中的每一个文件、每一个目录（包括空目录）都要完全覆盖，不允许遗漏。 ### 1.3 新增命令 本命令是 v2.0.0 新增的独立命令。 --- ## 二、执行流程 ### 2.1 创建流程 ``` ┌─────────────────────────────────────────┐ │ /aide:docs │ │ (文档不存在时) │ └─────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ 完整目录扫描 │ │ (递归遍历所有目录和文件) │ │ - 读取 .gitignore 规则 │ │ - 记录每个文件/目录（含空目录） │ │ - 生成类似 tree 的目录结构 │ │ - 标注 [ignored] 和 [空目录] │ └─────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ 初步区块划分 │ │ (按目录结构和功能模块划分) │ │ - 包含空目录归入相应区块 │ └─────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ 区块验证 │ │ (确认没有遗漏任何文件或目录) │ └─────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ 逐区块完全深度探索 │ │ - 每个文件从头到尾完整阅读 │ │ - 二进制文件根据上下文推断概括 │ │ - 生成区块内完整 tree 结构 │ │ - 生成文件清单及概括 │ └─────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ 生成总导览 │ │ (简化版目录结构 + 区块索引) │ └─────────────────────────────────────────┘ ``` ### 2.2 更新流程 ``` ┌─────────────────────────────────────────┐ │ /aide:docs │ │ (文档已存在时) │ └─────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ 读取区块计划 │ │ (了解当前文档结构和完整目录树) │ └─────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ 重新扫描目录 │ │ (对比当前结构与文档记录的结构) │ │ - 识别新增、删除、移动的文件/目录 │ └─────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ 分区块验证 │ │ (完全重读有变化的文件) │ │ - 更新区块内目录树 │ └─────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ 增量更新 │ │ (更新区块文档 + 总导览) │ └─────────────────────────────────────────┘ ``` --- ## 三、文档结构 ### 3.1 目录结构 ``` .aide/project-docs/ ├── README.md # 总导览（含简化版目录结构） ├── block-plan.md # 区块计划（进度追踪） └── blocks/ # 子区块文档（含完整目录树） ├── core.md ├── api.md └── ... ``` ### 3.2 总导览格式 ```markdown # [项目名称] 项目导览 > 本文档面向 LLM，用于快速了解项目结构和脉络。 ## 项目简介 ## 技术栈 ## 项目结构（简化版） # 前两层目录，含空目录和忽略项标注 ## 架构概述 ## 区块索引 # 含文件数列 ## 快速导航 ## 统计信息 # 目录数、文件数、空目录数、被忽略项 ``` ### 3.3 子区块格式 ```markdown # [区块名称] > 路径：xxx/ ## 概述 ## 目录结构 # 区块内完整 tree 结构 ## 文件清单 # 每个文件一行概括，含类型列 ## 核心组件 ## 接口说明 ## 依赖关系 ## 注意事项 ``` --- ## 四、文件处理规则 | 文件类型 | 处理方式 | |----------|----------| | **源码文件** | 完整阅读，分析逻辑和结构，提取核心信息 | | **配置文件** | 完整阅读，记录关键配置项 | | **文档文件** | 完整阅读，提取主要内容 | | **二进制文件** | 根据文件名、大小、关联文件信息进行上下文推断概括 | | **被忽略文件** | 只记录文件名/目录名，标注 `[ignored]`，不分析内容 | | **空目录** | 记录目录名，标注 `[空目录]`，根据名称推断用途 | --- ## 五、职责边界 ### 5.1 本命令负责 - 递归遍历项目所有目录和文件 - 生成完整目录树结构 - 完全深度阅读每个文件 - 划分文档区块 - 创建和更新项目文档 - 维护区块计划（进度追踪） ### 5.2 本命令不负责 - 环境配置（由 `/aide:setup` 负责） - 项目文档载入（由 `/aide:load` 负责） - 任务准备和执行（由 `/aide:run` 负责） --- ## 六、区块划分规则 1. **按目录结构**：每个主要目录可作为一个区块 2. **按功能模块**：相关功能的文件归为一个区块 3. **包含空目录**：空目录也要归入相应区块 4. **低耦合**：区块间依赖关系尽量简单 > 注：v2.0.1 移除了"单个区块不超过 5000 行代码"的限制 --- ## 七、多对话续接 大项目可能需要多次对话完成： 1. 每次开始时读取区块计划 2. 找到未完成的区块 3. **完全深度探索**该区块（每个文件从头到尾） 4. 生成区块内完整目录树 5. 更新区块计划的进度 --- ## 八、相关文档 - [执行文件](../../commands/docs.md) - [/aide:load 命令](load.md) - [plugin 导览](../README.md) --- ## 九、版本信息 - 创建日期：2025-12-15 - v2.0.0 新增命令 - v2.0.1 强化完全深度探索要求，添加目录树结构展示