✨ feat: 完成文档拆分

2025-12-13 22:22:01 +08:00
parent f535707657
commit 4cacd128ab
16 changed files with 3983 additions and 0 deletions
--- a/discuss/05-文档拆分方案.md
+++ b/discuss/05-文档拆分方案.md
@@ -0,0 +1,293 @@
+# aide-requirements.md 文档拆分方案
+
+## 一、需求理解
+
+### 1.1 核心目标
+
+将完整的 `aide-requirements.md` 拆分为**总导览 + 多个子区块文档**，实现：
+
+1. **子区块信息完整独立**：新人仅依赖子区块文档即可完全了解该区块
+2. **修改范围最小化**：调整某功能只需更新相关子区块和导览，无需了解全部内容
+3. **导览轻量化**：导览远比全部完整信息轻量
+
+### 1.2 用户场景验证
+
+| 场景 | 阅读路径 | 修改范围 |
+|------|----------|----------|
+| 调整 commands/init 业务细节 | 总导览 → plugin导览 → init设计文档 | init设计文档 + 对应command文件 |
+| 调整 aide env 子命令功能 | 总导览 → program导览 → env设计文档 | env设计文档 + 对应代码 |
+| 新增一个 command | 总导览 → plugin导览 → 参考现有command文档 | 新建command设计文档 + command文件 + 更新导览 |
+
+---
+
+## 二、拆分方案
+
+### 2.1 核心设计原则
+
+1. **区分设计文档与执行文件**
+   - 设计文档（docs/）：给人类开发者看，包含完整上下文和设计意图
+   - 执行文件（commands/、skills/）：给 LLM 看，聚焦执行指令
+
+2. **子区块自包含**
+   - 每个子区块文档包含：背景、职责、接口、行为、依赖关系
+   - 新人看完一个子区块文档，无需阅读其他文档即可理解该组件
+
+3. **导览只做索引**
+   - 导览文档只包含概述和索引
+   - 详细规格全部放在子区块文档中
+
+### 2.2 目录结构
+
+```
+项目根目录/
+├── aide-overview.md              # 总导览（系统概述 + 子区块索引）
+│
+├── aide-marketplace/
+│   └── aide-plugin/
+│       ├── docs/                 # plugin 设计文档区块
+│       │   ├── README.md         # plugin 导览
+│       │   ├── commands/
+│       │   │   ├── init.md       # init 命令设计文档
+│       │   │   ├── prep.md       # prep 命令设计文档
+│       │   │   └── exec.md       # exec 命令设计文档
+│       │   └── skill/
+│       │       └── aide.md       # aide skill 设计文档
+│       ├── commands/             # 实际 command 文件（给 LLM）
+│       │   ├── init.md
+│       │   ├── prep.md
+│       │   └── exec.md
+│       └── skills/               # 实际 skill 文件（给 LLM）
+│           └── aide/
+│               └── SKILL.md
+│
+└── aide-program/
+    ├── docs/                     # program 设计文档区块
+    │   ├── README.md             # program 导览
+    │   ├── commands/
+    │   │   ├── env.md            # env 子命令设计
+    │   │   ├── flow.md           # flow 子命令设计
+    │   │   ├── decide.md         # decide 子命令设计
+    │   │   └── init.md           # init 子命令设计
+    │   └── formats/
+    │       ├── config.md         # 配置文件格式规范
+    │       └── data.md           # 数据格式规范（待定项、流程状态等）
+    └── aide/                     # 实际代码
+```
+
+### 2.3 文档内容规划
+
+#### 总导览 (aide-overview.md)
+
+```markdown
+# Aide 系统概述
+
+## 系统简介
+[1-2段话描述 aide 是什么、解决什么问题]
+
+## 核心设计原则
+- 渐进式披露
+- 确定性封装
+- 信息隔离
+- 核心与形式分离
+
+## 系统架构
+[简图：plugin ↔ program 关系]
+
+## 子区块索引
+
+| 区块 | 位置 | 职责 |
+|------|------|------|
+| aide-plugin | aide-marketplace/aide-plugin/docs/ | Commands 和 Skill 定义 |
+| aide-program | aide-program/docs/ | 命令行工具实现 |
+
+## 快速导航
+- 想了解/修改 commands → [aide-plugin 导览](...)
+- 想了解/修改 aide 程序 → [aide-program 导览](...)
+```
+
+#### plugin 导览 (aide-plugin/docs/README.md)
+
+```markdown
+# Aide Plugin 设计文档
+
+## 概述
+aide-plugin 是 Claude Code 插件，提供 Aide 工作流的 Commands 和 Skill。
+
+## 组件关系
+- Commands：定义流程（init/prep/exec）
+- Skill：定义工具使用方法（aide 命令）
+
+## Commands 索引
+
+| Command | 文档 | 职责 |
+|---------|------|------|
+| /aide:init | [init.md](commands/init.md) | 项目认知与环境初始化 |
+| /aide:prep | [prep.md](commands/prep.md) | 任务准备流程 |
+| /aide:exec | [exec.md](commands/exec.md) | 任务执行流程 |
+
+## Skill 索引
+
+| Skill | 文档 | 职责 |
+|-------|------|------|
+| aide | [aide.md](skill/aide.md) | aide 命令行工具使用指南 |
+```
+
+#### 子区块文档模板
+
+每个子区块文档应包含：
+
+```markdown
+# [组件名称]
+
+## 背景
+[为什么需要这个组件，解决什么问题]
+
+## 职责
+[这个组件做什么、不做什么]
+
+## 接口
+[输入、输出、参数]
+
+## 行为
+[详细的执行逻辑/流程]
+
+## 依赖
+[依赖哪些其他组件，简要说明]
+
+## 被依赖
+[被哪些组件使用]
+
+## 修改指南
+[修改此组件时需要同步更新的内容]
+```
+
+---
+
+## 三、内容分配
+
+### 3.1 从 aide-requirements.md 提取的内容分配
+
+| 原章节 | 目标位置 |
+|--------|----------|
+| 一、项目背景 | aide-overview.md（精简版） |
+| 二、核心设计原则 | aide-overview.md（列表形式） |
+| 三、组件职责定义 | aide-plugin/docs/README.md |
+| 四、命令清单 | aide-plugin/docs/commands/*.md |
+| 五、技能清单 | aide-plugin/docs/skill/aide.md + aide-program/docs/commands/*.md |
+| 六、信息流设计 | aide-program/docs/formats/data.md |
+| 七、LLM 自由发挥边界 | aide-plugin/docs/README.md |
+| 八、数据格式规范 | aide-program/docs/formats/data.md |
+| 九、数据存储 | aide-program/docs/formats/config.md |
+| 十、实施结构 | aide-overview.md（架构部分） |
+
+### 3.2 新增内容
+
+| 文档 | 新增内容 |
+|------|----------|
+| aide-program/docs/README.md | program 整体介绍、目录结构、开发指南 |
+| aide-program/docs/commands/flow.md | flow 子命令完整设计（当前未实现） |
+| aide-program/docs/commands/decide.md | decide 子命令完整设计（当前未实现） |
+
+---
+
+## 四、实施计划
+
+### 4.1 步骤
+
+1. **创建目录结构**
+   - aide-marketplace/aide-plugin/docs/commands/
+   - aide-marketplace/aide-plugin/docs/skill/
+   - aide-program/docs/commands/
+   - aide-program/docs/formats/
+
+2. **编写总导览**
+   - 创建 aide-overview.md
+
+3. **编写 aide-plugin 文档**
+   - aide-plugin/docs/README.md
+   - aide-plugin/docs/commands/init.md
+   - aide-plugin/docs/commands/prep.md
+   - aide-plugin/docs/commands/exec.md
+   - aide-plugin/docs/skill/aide.md
+
+4. **编写 aide-program 文档**
+   - aide-program/docs/README.md
+   - aide-program/docs/commands/env.md
+   - aide-program/docs/commands/flow.md
+   - aide-program/docs/commands/decide.md
+   - aide-program/docs/commands/init.md
+   - aide-program/docs/formats/config.md
+   - aide-program/docs/formats/data.md
+
+5. **处理原文档**
+   - 将 aide-requirements.md 移动到 archive/ 或删除
+
+### 4.2 文档数量统计
+
+| 区块 | 文档数量 |
+|------|----------|
+| 总导览 | 1 |
+| aide-plugin | 5 |
+| aide-program | 7 |
+| **合计** | **13** |
+
+---
+
+## 五、待确认事项
+
+1. **总导览位置**：放在项目根目录（aide-overview.md）还是其他位置？
+
+2. **原 aide-requirements.md 处理**：
+   - 选项A：移动到 archive/ 目录保留
+   - 选项B：直接删除
+
+3. **设计文档与执行文件的关系**：
+   - 当前 commands/*.md 和 SKILL.md 是给 LLM 的执行指令
+   - 新增的 docs/ 是给人类的设计文档
+   - 两者内容会有重叠，是否可接受？
+
+4. **文档命名**：
+   - aide-program/docs/commands/ 下的文档是否用 "env.md" 还是 "aide-env.md"？
+
+---
+
+## 六、预期效果
+
+### 6.1 新人上手流程
+
+```
+想了解 aide 系统
+    ↓
+阅读 aide-overview.md（5分钟）
+    ↓
+确定要修改的区块
+    ↓
+阅读对应区块导览（5分钟）
+    ↓
+阅读具体组件文档（10分钟）
+    ↓
+开始修改
+```
+
+### 6.2 修改影响范围
+
+| 修改类型 | 影响文档 |
+|----------|----------|
+| 调整 init 命令流程 | init设计文档 + init.md执行文件 |
+| 新增 aide 子命令 | program导览 + 新子命令设计文档 + SKILL.md + 代码 |
+| 修改数据格式 | formats/data.md + 相关代码 |
+| 调整设计原则 | aide-overview.md |
+
+---
+
+## 七、总结
+
+本方案将 aide-requirements.md 拆分为 13 个文档，分布在 3 个区块：
+
+1. **总导览**：系统概述和索引
+2. **aide-plugin 区块**：Commands 和 Skill 的设计文档
+3. **aide-program 区块**：程序子命令和数据格式的设计文档
+
+每个子区块文档自包含，新人可以仅通过导览找到相关文档，完全掌握该区块信息后进行修改，无需了解整个系统的全部细节。
+
+请审阅此方案，如有调整意见请在 reply/ 目录创建回复文档。
--- a/discuss/06-文档拆分完成报告.md
+++ b/discuss/06-文档拆分完成报告.md
@@ -0,0 +1,182 @@
+# 文档拆分完成报告
+
+## 一、完成概述
+
+已将 `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 看