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

# /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 新增命令