183 lines
5.7 KiB
Markdown
183 lines
5.7 KiB
Markdown
# 文档拆分完成报告
|
||
|
||
## 一、完成概述
|
||
|
||
已将 `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 看
|