agent-aide/discuss/06-文档拆分完成报告.md

# 文档拆分完成报告

## 一、完成概述

已将 `aide-requirements.md` 拆分为 **13 个独立文档**，分布在 3 个区块中。

---

## 二、文档清单

### 2.1 总导览（1个）

| 文档 | 位置 | 说明 |
|------|------|------|
| aide-overview.md | `docs/aide-overview.md` | 系统概述、架构图、子区块索引 |

### 2.2 aide-plugin 区块（5个）

| 文档 | 位置 | 说明 |
|------|------|------|
| README.md | `aide-marketplace/aide-plugin/docs/README.md` | plugin 导览 |
| init.md | `aide-marketplace/aide-plugin/docs/commands/init.md` | /aide:init 命令设计 |
| prep.md | `aide-marketplace/aide-plugin/docs/commands/prep.md` | /aide:prep 命令设计 |
| exec.md | `aide-marketplace/aide-plugin/docs/commands/exec.md` | /aide:exec 命令设计 |
| aide.md | `aide-marketplace/aide-plugin/docs/skill/aide.md` | aide skill 设计 |

### 2.3 aide-program 区块（7个）

| 文档 | 位置 | 说明 |
|------|------|------|
| README.md | `aide-program/docs/README.md` | program 导览 |
| env.md | `aide-program/docs/commands/env.md` | env 子命令设计 |
| flow.md | `aide-program/docs/commands/flow.md` | flow 子命令设计 |
| decide.md | `aide-program/docs/commands/decide.md` | decide 子命令设计 |
| init.md | `aide-program/docs/commands/init.md` | init 子命令设计 |
| config.md | `aide-program/docs/formats/config.md` | 配置文件格式规范 |
| data.md | `aide-program/docs/formats/data.md` | 数据格式规范 |

---

## 三、目录结构

```
项目根目录/
├── docs/
│   └── aide-overview.md              # 总导览
│
├── aide-marketplace/
│   └── aide-plugin/
│       ├── docs/                     # 设计文档（给人看）
│       │   ├── README.md
│       │   ├── commands/
│       │   │   ├── init.md
│       │   │   ├── prep.md
│       │   │   └── exec.md
│       │   └── skill/
│       │       └── aide.md
│       ├── commands/                 # 执行文件（给 LLM 看）
│       │   ├── init.md
│       │   ├── prep.md
│       │   └── exec.md
│       └── skills/
│           └── aide/
│               └── SKILL.md
│
└── aide-program/
    ├── docs/                         # 设计文档
    │   ├── README.md
    │   ├── commands/
    │   │   ├── env.md
    │   │   ├── flow.md
    │   │   ├── decide.md
    │   │   └── init.md
    │   └── formats/
    │       ├── config.md
    │       └── data.md
    └── aide/                         # 代码实现
```

---

## 四、设计特点

### 4.1 子区块信息完整独立

每个子区块文档包含：
- **背景**：为什么需要这个组件
- **职责**：做什么、不做什么
- **接口**：输入、输出、参数
- **行为**：详细流程（PlantUML 流程图）
- **数据结构**：伪代码表示的类型和方法签名
- **依赖/被依赖**：与其他组件的关系
- **修改指南**：修改时需要同步更新的内容

### 4.2 设计文档与执行文件分离

| 类型 | 位置 | 受众 | 内容 |
|------|------|------|------|
| 设计文档 | `docs/` | 人类开发者 | 完整上下文、设计意图、流程图 |
| 执行文件 | `commands/`、`skills/` | LLM | 执行指令、参数说明 |

### 4.3 导览只做索引

- 总导览：系统概述 + 子区块索引
- 区块导览：组件关系 + 文档索引
- 详细规格全在子区块文档中

### 4.4 遵循约束

- aide-program 设计文档不包含代码实现
- 仅使用 PlantUML 流程图表示业务/逻辑流
- 仅使用伪代码表示数据结构、类型、方法签名

---

## 五、使用场景验证

### 场景1：调整 /aide:init 命令

**阅读路径**：
1. `docs/aide-overview.md` → 找到 aide-plugin 区块
2. `aide-plugin/docs/README.md` → 找到 init 命令
3. `aide-plugin/docs/commands/init.md` → 完整了解 init 设计

**修改范围**：
- `aide-plugin/docs/commands/init.md`（设计文档）
- `aide-plugin/commands/init.md`（执行文件）
- 如有重大变更，更新导览

### 场景2：调整 aide env 子命令

**阅读路径**：
1. `docs/aide-overview.md` → 找到 aide-program 区块
2. `aide-program/docs/README.md` → 找到 env 子命令
3. `aide-program/docs/commands/env.md` → 完整了解 env 设计

**修改范围**：
- `aide-program/docs/commands/env.md`（设计文档）
- `aide-program/aide/env/ensure.py`（代码实现）
- `aide-plugin/docs/skill/aide.md`（如接口变更）

### 场景3：新增 aide 子命令

**步骤**：
1. 在 `aide-program/docs/commands/` 创建设计文档
2. 在 `aide-program/aide/` 创建代码模块
3. 更新 `aide-program/docs/README.md` 索引
4. 更新 `aide-plugin/docs/skill/aide.md` 接口说明
5. 更新 `aide-plugin/skills/aide/SKILL.md` 执行文件

---

## 六、后续建议

### 6.1 原文档处理

`aide-requirements.md` 可以：
- 移动到 `archive/` 目录保留
- 或直接删除（你已表示会自行处理）

### 6.2 文档维护

- 修改组件时，同步更新对应设计文档
- 重大变更时，更新导览文档
- 保持设计文档与执行文件的一致性

### 6.3 待实现功能

根据 `aide-program/docs/README.md` 中的状态：
- ✅ 已实现：init、env、config
- ⏳ 待实现：flow、decide

---

## 七、总结

文档拆分已完成，实现了：

1. **子区块信息完整独立**：新人可仅通过导览找到相关文档，完全掌握该区块
2. **修改范围最小化**：调整功能只需更新相关子区块和导览
3. **导览轻量化**：导览只做索引，详细规格在子区块中
4. **设计与执行分离**：设计文档给人看，执行文件给 LLM 看