8.8 KiB
8.8 KiB
/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 总导览格式
# [项目名称] 项目导览
> 本文档面向 LLM，用于快速了解项目结构和脉络。
## 项目简介
## 技术栈
## 项目结构（简化版） # 前两层目录，含空目录和忽略项标注
## 架构概述
## 区块索引 # 含文件数列
## 快速导航
## 统计信息 # 目录数、文件数、空目录数、被忽略项
3.3 子区块格式
# [区块名称]
> 路径：xxx/
## 概述
## 目录结构 # 区块内完整 tree 结构
## 文件清单 # 每个文件一行概括，含类型列
## 核心组件
## 接口说明
## 依赖关系
## 注意事项
四、文件处理规则
| 文件类型 | 处理方式 |
|---|---|
| 源码文件 | 完整阅读，分析逻辑和结构，提取核心信息 |
| 配置文件 | 完整阅读，记录关键配置项 |
| 文档文件 | 完整阅读，提取主要内容 |
| 二进制文件 | 根据文件名、大小、关联文件信息进行上下文推断概括 |
| 被忽略文件 | 只记录文件名/目录名，标注 [ignored]，不分析内容 |
| 空目录 | 记录目录名，标注 [空目录]，根据名称推断用途 |
五、职责边界
5.1 本命令负责
- 递归遍历项目所有目录和文件
- 生成完整目录树结构
- 完全深度阅读每个文件
- 划分文档区块
- 创建和更新项目文档
- 维护区块计划（进度追踪）
5.2 本命令不负责
- 环境配置（由
/aide:setup负责） - 项目文档载入（由
/aide:load负责） - 任务准备和执行（由
/aide:run负责）
六、区块划分规则
- 按目录结构：每个主要目录可作为一个区块
- 按功能模块：相关功能的文件归为一个区块
- 包含空目录：空目录也要归入相应区块
- 低耦合：区块间依赖关系尽量简单
注：v2.0.1 移除了"单个区块不超过 5000 行代码"的限制
七、多对话续接
大项目可能需要多次对话完成：
- 每次开始时读取区块计划
- 找到未完成的区块
- 完全深度探索该区块（每个文件从头到尾）
- 生成区块内完整目录树
- 更新区块计划的进度
八、相关文档
九、版本信息
- 创建日期：2025-12-15
- v2.0.0 新增命令
- v2.0.1 强化完全深度探索要求，添加目录树结构展示