186 lines
6.2 KiB
Markdown
186 lines
6.2 KiB
Markdown
# /aide:docs 命令设计文档
|
||
|
||
## 一、概述
|
||
|
||
`/aide:docs` 是项目文档管理命令，用于创建和维护面向 LLM 的项目文档。
|
||
|
||
### 1.1 设计目标
|
||
|
||
| 目标 | 说明 |
|
||
|------|------|
|
||
| 独立运行 | 通常在需要时单独执行 |
|
||
| 区块化 | 文档按区块组织，支持增量更新 |
|
||
| 面向 LLM | 文档格式针对 LLM 理解优化 |
|
||
| 多对话续接 | 大项目支持多次对话完成 |
|
||
|
||
### 1.2 新增命令
|
||
|
||
本命令是 v2.0.0 新增的独立命令。
|
||
|
||
---
|
||
|
||
## 二、执行流程
|
||
|
||
### 2.1 创建流程
|
||
|
||
```
|
||
┌─────────────────────────────────────────┐
|
||
│ /aide:docs │
|
||
│ (文档不存在时) │
|
||
└─────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────┐
|
||
│ 目录探索 │
|
||
│ (遍历结构、统计文件、识别忽略项) │
|
||
└─────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────┐
|
||
│ 初步区块划分 │
|
||
│ (按目录结构和功能模块划分) │
|
||
└─────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────┐
|
||
│ 区块验证 │
|
||
│ (浅层探索验证划分合理性) │
|
||
└─────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────┐
|
||
│ 逐区块深度了解 │
|
||
│ (完整阅读、提取信息、生成文档) │
|
||
└─────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────┐
|
||
│ 生成总导览 │
|
||
│ (整合所有区块信息) │
|
||
└─────────────────────────────────────────┘
|
||
```
|
||
|
||
### 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/
|
||
|
||
## 概述
|
||
## 文件清单
|
||
## 核心组件
|
||
## 接口说明
|
||
## 依赖关系
|
||
## 注意事项
|
||
```
|
||
|
||
---
|
||
|
||
## 四、职责边界
|
||
|
||
### 4.1 本命令负责
|
||
|
||
- 探索项目目录结构
|
||
- 划分文档区块
|
||
- 创建和更新项目文档
|
||
- 维护区块计划（进度追踪）
|
||
|
||
### 4.2 本命令不负责
|
||
|
||
- 环境配置（由 `/aide:setup` 负责）
|
||
- 项目文档载入（由 `/aide:load` 负责）
|
||
- 任务准备和执行（由 `/aide:run` 负责）
|
||
|
||
---
|
||
|
||
## 五、区块划分规则
|
||
|
||
1. **按目录结构**：每个主要目录可作为一个区块
|
||
2. **按功能模块**：相关功能的文件归为一个区块
|
||
3. **大小控制**：单个区块不超过 5000 行代码
|
||
4. **低耦合**：区块间依赖关系尽量简单
|
||
|
||
---
|
||
|
||
## 六、多对话续接
|
||
|
||
大项目可能需要多次对话完成：
|
||
|
||
1. 每次开始时读取区块计划
|
||
2. 找到未完成的区块
|
||
3. 继续处理
|
||
4. 更新区块计划的进度
|
||
|
||
---
|
||
|
||
## 七、相关文档
|
||
|
||
- [执行文件](../../commands/docs.md)
|
||
- [/aide:load 命令](load.md)
|
||
- [plugin 导览](../README.md)
|
||
|
||
---
|
||
|
||
## 八、版本信息
|
||
|
||
- 创建日期：2025-12-15
|
||
- v2.0.0 新增命令
|