From 4cacd128ab6ab53874f66738768bee514fac77a7 Mon Sep 17 00:00:00 2001 From: "sayurinana(vm)" Date: Sat, 13 Dec 2025 22:22:01 +0800 Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20feat:=20=E5=AE=8C=E6=88=90=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E6=8B=86=E5=88=86?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- aide-marketplace/aide-plugin/docs/README.md | 156 +++++++ .../aide-plugin/docs/commands/exec.md | 324 ++++++++++++++ .../aide-plugin/docs/commands/init.md | 235 ++++++++++ .../aide-plugin/docs/commands/prep.md | 289 ++++++++++++ .../aide-plugin/docs/skill/aide.md | 415 ++++++++++++++++++ aide-program/docs/README.md | 208 +++++++++ aide-program/docs/commands/decide.md | 353 +++++++++++++++ aide-program/docs/commands/env.md | 257 +++++++++++ aide-program/docs/commands/flow.md | 387 ++++++++++++++++ aide-program/docs/commands/init.md | 221 ++++++++++ aide-program/docs/formats/config.md | 176 ++++++++ aide-program/docs/formats/data.md | 360 +++++++++++++++ discuss/05-文档拆分方案.md | 293 +++++++++++++ discuss/06-文档拆分完成报告.md | 182 ++++++++ docs/aide-overview.md | 121 +++++ reply/re-04.md | 6 + 16 files changed, 3983 insertions(+) create mode 100644 aide-marketplace/aide-plugin/docs/README.md create mode 100644 aide-marketplace/aide-plugin/docs/commands/exec.md create mode 100644 aide-marketplace/aide-plugin/docs/commands/init.md create mode 100644 aide-marketplace/aide-plugin/docs/commands/prep.md create mode 100644 aide-marketplace/aide-plugin/docs/skill/aide.md create mode 100644 aide-program/docs/README.md create mode 100644 aide-program/docs/commands/decide.md create mode 100644 aide-program/docs/commands/env.md create mode 100644 aide-program/docs/commands/flow.md create mode 100644 aide-program/docs/commands/init.md create mode 100644 aide-program/docs/formats/config.md create mode 100644 aide-program/docs/formats/data.md create mode 100644 discuss/05-文档拆分方案.md create mode 100644 discuss/06-文档拆分完成报告.md create mode 100644 docs/aide-overview.md create mode 100644 reply/re-04.md diff --git a/aide-marketplace/aide-plugin/docs/README.md b/aide-marketplace/aide-plugin/docs/README.md new file mode 100644 index 0000000..6e3aaa4 --- /dev/null +++ b/aide-marketplace/aide-plugin/docs/README.md @@ -0,0 +1,156 @@ +# Aide Plugin 设计文档 + +## 一、概述 + +aide-plugin 是 Claude Code 插件，提供 Aide 工作流体系的 Commands 和 Skill。 + +### 1.1 解决的问题 + +| 问题 | 解决方案 | +|------|----------| +| CLAUDE.md 信息过载 | 流程规则封装到 Commands，按需触发 | +| 操作指令分散 | 工具使用方法集中到 Skill | +| 流程遵循不一致 | Commands 定义明确的阶段和顺序 | + +### 1.2 组件关系 + +``` +┌─────────────────────────────────────────────────┐ +│ Commands │ +│ 定义"做什么"和"按什么顺序做" │ +│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ +│ │ init │ │ prep │ │ exec │ │ +│ └────┬────┘ └────┬────┘ └────┬────┘ │ +└───────┼────────────┼────────────┼───────────────┘ + │ │ │ + ▼ ▼ ▼ +┌─────────────────────────────────────────────────┐ +│ Skill │ +│ 定义"怎么调用工具" │ +│ ┌─────────────────────────────────────────┐ │ +│ │ aide skill │ │ +│ │ env | flow | decide | config | init │ │ +│ └─────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────┘ + │ + ▼ 调用 +┌─────────────────────────────────────────────────┐ +│ aide-program │ +│ 实际执行操作，返回精简结果 │ +└─────────────────────────────────────────────────┘ +``` + +--- + +## 二、Commands 索引 + +| Command | 设计文档 | 执行文件 | 职责 | +|---------|----------|----------|------| +| `/aide:init` | [commands/init.md](commands/init.md) | [../../commands/init.md](../commands/init.md) | 项目认知与环境初始化 | +| `/aide:prep` | [commands/prep.md](commands/prep.md) | [../../commands/prep.md](../commands/prep.md) | 任务准备流程 | +| `/aide:exec` | [commands/exec.md](commands/exec.md) | [../../commands/exec.md](../commands/exec.md) | 任务执行流程 | + +### 2.1 Commands 设计原则 + +**聚焦思考方法论，不涉及工具细节** + +Commands 只告诉 LLM： +- 怎么思考（分析方法、优化方向） +- 流程是什么（阶段划分、执行顺序） +- 决策边界（哪些自主完成，哪些需确认） + +具体工具调用由 Skill 负责说明。 + +### 2.2 工作流程 + +``` +/aide:init /aide:prep /aide:exec + │ │ │ + ▼ ▼ ▼ +┌────────┐ ┌──────────┐ ┌──────────┐ +│环境检测│ │ 任务分析 │ │ 流程设计 │ +│项目认知│ │ 任务优化 │ │ 迭代实现 │ +│介绍能力│ │ 待定项 │ │ 验证交付 │ +└────────┘ │ 生成细则 │ │ 文档更新 │ + └──────────┘ │ 收尾 │ + │ └──────────┘ + ▼ + task-spec.md ──────────────▶ +``` + +--- + +## 三、Skill 索引 + +| Skill | 设计文档 | 执行文件 | 职责 | +|-------|----------|----------|------| +| aide | [skill/aide.md](skill/aide.md) | [../../skills/aide/SKILL.md](../skills/aide/SKILL.md) | aide 命令行工具使用指南 | + +### 3.1 Skill 设计原则 + +**纯工具说明，便于快速查阅** + +Skill 只包含： +- 命令语法和参数 +- 输入输出格式 +- 典型使用示例 + +不包含流程指导和业务逻辑。 + +--- + +## 四、职责边界 + +### 4.1 需要程序约束的场景 + +| 场景 | 处理方式 | +|------|----------| +| 环境检测与修复 | `aide env ensure` | +| 待定项呈现与确认 | `aide decide` | +| 状态记录与 git 提交 | `aide flow` | +| 配置读写 | `aide config` | + +### 4.2 不需要程序约束的场景 + +| 场景 | 说明 | +|------|------| +| 任务分析思考 | LLM 自由发挥 | +| 任务优化思考 | LLM 自由发挥 | +| 业务决策判断 | LLM 自由发挥 | +| 任务细则编写 | LLM 自由发挥，产出 task-spec.md | +| 业务代码编写 | LLM 自由发挥 | + +--- + +## 五、修改指南 + +### 5.1 修改 Command + +1. 阅读对应的设计文档（如 `commands/init.md`） +2. 理解职责和流程 +3. 修改执行文件（如 `../commands/init.md`） +4. 更新设计文档（如有重大变更） +5. 更新本导览（如有新增/删除 Command） + +### 5.2 修改 Skill + +1. 阅读 [skill/aide.md](skill/aide.md) +2. 理解各子命令的接口 +3. 修改执行文件 `../skills/aide/SKILL.md` +4. 更新设计文档 +5. 如涉及 aide-program 变更，同步更新 [aide-program 文档](../../../aide-program/docs/README.md) + +### 5.3 新增 Command + +1. 在 `commands/` 下创建设计文档 +2. 在 `../commands/` 下创建执行文件 +3. 更新本导览的索引表 +4. 更新 [总导览](../../../docs/aide-overview.md) + +--- + +## 六、相关文档 + +- [总导览](../../../docs/aide-overview.md) +- [aide-program 导览](../../../aide-program/docs/README.md) +- [Claude Code 插件指南](../../../docs/03-插件指南.md) diff --git a/aide-marketplace/aide-plugin/docs/commands/exec.md b/aide-marketplace/aide-plugin/docs/commands/exec.md new file mode 100644 index 0000000..99007bd --- /dev/null +++ b/aide-marketplace/aide-plugin/docs/commands/exec.md @@ -0,0 +1,324 @@ +# /aide:exec 命令设计文档 + +## 一、背景 + +### 1.1 解决的问题 + +任务执行阶段面临的挑战： + +| 问题 | 影响 | +|------|------| +| 流程不完整 | 遗漏验证、文档更新等环节 | +| 状态难追踪 | 不清楚当前进度和历史 | +| git 操作分散 | 提交不规范，难以追溯 | +| 返工无记录 | 问题原因和解决方案丢失 | + +### 1.2 设计目标 + +提供**完整的任务执行闭环**： +- 明确的环节划分（流程设计→实现→验证→文档→收尾） +- 自动化的状态记录和 git 提交 +- 规范的问题处理和返工机制 + +--- + +## 二、职责 + +### 2.1 做什么 + +1. 读取任务细则，理解执行目标 +2. 设计执行流程（流程图、计划） +3. 按计划迭代实现 +4. 验证交付物满足成功标准 +5. 更新相关文档（README、CHANGELOG） +6. 清理收尾，汇报成果 + +### 2.2 不做什么 + +- 不进行任务分析和优化（那是 prep 的职责） +- 不主动关注 git 操作和状态记录（由 aide flow 自动处理） + +--- + +## 三、参数 + +| 参数 | 类型 | 说明 | +|------|------|------| +| `$ARGUMENTS` | 可选 | 任务细则文档路径 | + +**未传入参数时**：使用 `aide config get task.spec` 获取默认路径（通常为 task-spec.md） + +--- + +## 四、执行流程 + +``` +@startuml +skinparam defaultFontName "PingFang SC" + +start + +:确定任务细则路径; +note right: 使用参数或配置默认值 + +:读取任务细则; + +if (文档存在?) then (是) +else (否) + :提示先执行 /aide:prep; + stop +endif + +:aide flow next-part flow-design "进入流程设计环节"; + +partition "环节1: 流程设计 (flow-design)" { + :理解任务细则; + :分析项目环境; + :制定执行计划; + + if (需要流程图?) then (是) + :创建 PlantUML 流程图; + :aide flow next-step "流程图设计完成"; + endif + + :aide flow next-part impl "流程设计完成，进入实现环节"; +} + +partition "环节2: 迭代实现 (impl)" { + while (还有待实现步骤?) is (是) + :执行当前步骤; + :aide flow next-step "<完成内容>"; + + if (遇到问题?) then (是) + if (严重错误?) then (是) + :aide flow error "<描述>"; + :尝试解决 (最多3次); + if (解决成功?) then (是) + :在 discuss/ 创建分析文档; + else (否) + :停止并告知用户; + stop + endif + else (否) + :aide flow issue "<描述>"; + endif + endif + + if (需要回退?) then (是) + :aide flow back-step "<原因>"; + endif + endwhile (否) + + :aide flow next-part verify "实现完成，进入验证环节"; +} + +partition "环节3: 验证交付 (verify)" { + :对照任务细则验证; + :执行测试; + + if (验证通过?) then (是) + :aide flow next-step "验证完成"; + :aide flow next-part docs "验证通过，进入文档环节"; + else (否) + :aide flow back-part impl "验证失败: <原因>"; + endif +} + +partition "环节4: 文档更新 (docs)" { + :更新 README.md (如需要); + :更新 CHANGELOG.md; + :aide flow next-step "文档更新完成"; + :aide flow next-part finish "文档更新完成，进入收尾"; +} + +partition "环节5: 收尾 (finish)" { + :清理临时文件; + :检查遗漏 TODO; + :aide flow next-step "任务完成"; + :向用户汇报成果; +} + +stop +@enduml +``` + +--- + +## 五、环节详解 + +### 5.1 环节1：流程设计 (flow-design) + +**目标**：制定清晰的执行计划 + +**内容**： +- 理解任务目标和成功标准 +- 分析执行步骤和依赖关系 +- 识别技术决策和约束 +- 制定具体实现步骤和预期产出 + +**流程图**： +- 复杂任务建议创建 PlantUML 流程图 +- aide flow 会在此环节自动校验 PlantUML 语法 +- 进入下一环节时自动生成 PNG + +### 5.2 环节2：迭代实现 (impl) + +**目标**：按计划完成实际实现 + +**工作方式**： +- 逐步执行计划中的步骤 +- 每完成一个步骤调用 `aide flow next-step` +- 遇到问题及时记录和处理 + +**问题处理**： + +| 问题类型 | 处理方式 | +|----------|----------| +| 一般问题 | `aide flow issue "<描述>"` 记录后继续 | +| 严重错误 | `aide flow error "<描述>"` 尝试解决 | +| 需要回退 | `aide flow back-step "<原因>"` | +| 需要返回设计 | `aide flow back-part flow-design "<原因>"` | + +### 5.3 环节3：验证交付 (verify) + +**目标**：确保交付物满足要求 + +**验证内容**： +- 每个成功标准是否满足 +- 每个交付物是否完成 +- 功能是否正常工作 + +**验证失败**： +- 调用 `aide flow back-part impl "验证失败: <原因>"` +- 返回实现环节修复 + +### 5.4 环节4：文档更新 (docs) + +**目标**：更新相关文档 + +**必须更新**： +- CHANGELOG.md（aide flow 会校验） + +**按需更新**： +- README.md（如有用户可见变更） +- 其他相关文档 + +### 5.5 环节5：收尾 (finish) + +**目标**：清理和汇报 + +**清理内容**： +- 删除临时文件和调试代码 +- 确保代码格式规范 +- 检查遗漏的 TODO + +**汇报内容**： +- 完成了什么 +- 主要变更点 +- 遗留问题（如有） + +--- + +## 六、与 aide 程序的交互 + +### 6.1 aide flow next-part + +**调用时机**：进入新环节时 + +**命令**： +```bash +aide flow next-part <环节名> "<总结>" +``` + +**环节名**：flow-design / impl / verify / docs / finish + +### 6.2 aide flow next-step + +**调用时机**：完成一个步骤时 + +**命令**： +```bash +aide flow next-step "<完成内容简述>" +``` + +### 6.3 aide flow back-step / back-part + +**调用时机**：需要回退时 + +**命令**： +```bash +aide flow back-step "<原因>" +aide flow back-part <环节名> "<原因>" +``` + +### 6.4 aide flow issue / error + +**调用时机**：遇到问题时 + +**命令**： +```bash +aide flow issue "<问题描述>" +aide flow error "<错误描述>" +``` + +### 6.5 aide config get + +**调用时机**：未传入参数时 + +**命令**： +```bash +aide config get task.spec +``` + +--- + +## 七、注意事项 + +1. **不要主动提及 git 操作**：由 aide flow 自动处理 +2. **不要主动提及状态记录**：由 aide flow 自动处理 +3. **专注于任务实现**：这是 exec 的核心价值 + +--- + +## 八、依赖 + +| 依赖项 | 类型 | 说明 | +|--------|------|------| +| /aide:init | Command | 需要先完成环境初始化 | +| /aide:prep | Command | 需要先完成任务准备（产出 task-spec.md） | +| aide flow | aide 子命令 | 流程追踪 | +| aide config | aide 子命令 | 读取配置 | + +--- + +## 九、被依赖 + +无。exec 是工作流的最后一个命令。 + +--- + +## 十、修改指南 + +### 10.1 修改环节划分 + +1. 更新本文档的流程图和环节详解 +2. 修改执行文件 `../../commands/exec.md` +3. 同步更新 [aide flow 设计](../../../../aide-program/docs/commands/flow.md) 中的环节校验规则 + +### 10.2 修改问题处理机制 + +1. 更新本文档的"问题处理"部分 +2. 修改执行文件中的相关指导 + +### 10.3 修改汇报格式 + +1. 更新本文档的"收尾"章节 +2. 修改执行文件中的汇报模板 + +--- + +## 十一、相关文档 + +- [执行文件](../../commands/exec.md) +- [aide flow 设计](../../../../aide-program/docs/commands/flow.md) +- [plugin 导览](../README.md) diff --git a/aide-marketplace/aide-plugin/docs/commands/init.md b/aide-marketplace/aide-plugin/docs/commands/init.md new file mode 100644 index 0000000..2f1a379 --- /dev/null +++ b/aide-marketplace/aide-plugin/docs/commands/init.md @@ -0,0 +1,235 @@ +# /aide:init 命令设计文档 + +## 一、背景 + +### 1.1 解决的问题 + +在开始项目工作前，需要解决以下问题： + +| 问题 | 影响 | +|------|------| +| 环境不就绪 | 后续命令执行失败，打断业务流程 | +| 项目认知缺失 | LLM 不了解项目结构，决策质量下降 | +| 配置未初始化 | aide 程序无法正常工作 | + +### 1.2 设计目标 + +将环境问题**前置解决**，在业务流程开始前确保一切就绪： +- 沉没成本小：发现严重问题可重开对话 +- 环境问题不会打断后续业务逻辑 + +--- + +## 二、职责 + +### 2.1 做什么 + +1. 检测 aide 运行时环境（Python、uv 等） +2. 初始化 `.aide/` 目录和配置文件 +3. 触发 LLM 对项目内容的主动认知 +4. 检测项目开发环境并自动修复问题 +5. 介绍 aide 流程体系和可用能力 + +### 2.2 不做什么 + +- 不修改任何业务代码 +- 不执行任务分析或优化 +- 不启动流程追踪（flow） + +--- + +## 三、执行流程 + +``` +@startuml +skinparam defaultFontName "PingFang SC" + +start + +:aide env ensure --runtime; +note right: 检查 aide 自身运行环境\n不依赖配置文件 + +if (运行时环境就绪?) then (是) +else (否) + :输出错误信息; + :告知用户修复方法; + stop +endif + +:aide init; +note right: 创建 .aide/ 目录\n生成默认配置\n更新 .gitignore + +:项目认知; +note right: 阅读 README.md\n阅读 CLAUDE.md\n浏览目录结构\n识别技术栈 + +:aide env ensure; +note right: 读取配置文件\n检查项目环境\n输出配置信息 + +if (项目环境就绪?) then (是) +else (否) + if (可自动修复?) then (是) + :自动修复; + else (否) + :告知用户; + if (3次尝试失败?) then (是) + stop + endif + endif +endif + +:汇报就绪状态; +note right: 项目概况\n环境状态\n可用命令 + +stop +@enduml +``` + +### 3.1 步骤详解 + +| 步骤 | 操作 | aide 命令 | 说明 | +|------|------|-----------|------| +| 1 | 运行时环境检测 | `aide env ensure --runtime` | 不依赖配置文件 | +| 2 | 初始化配置 | `aide init` | 创建 .aide/ 和配置 | +| 3 | 项目认知 | 无 | LLM 自主阅读项目文件 | +| 4 | 项目环境检测 | `aide env ensure` | 读取配置，检查项目环境 | +| 5 | 汇报状态 | 无 | LLM 向用户汇报 | + +--- + +## 四、与 aide 程序的交互 + +### 4.1 aide env ensure --runtime + +**调用时机**：步骤 1 + +**输入**：无 + +**输出示例**： +``` +✓ 运行时环境就绪 (python:3.12, uv:0.4.0) +``` + +**错误处理**： +- `✗ Python 版本不足` → 告知用户安装要求 +- `✗ 未检测到 uv` → 告知用户安装 uv + +### 4.2 aide init + +**调用时机**：步骤 2 + +**输入**：无 + +**输出示例**： +``` +✓ 已创建默认配置 .aide/config.toml +✓ 初始化完成，.aide/ 与默认配置已准备就绪 +``` + +**行为**： +- 创建 `.aide/` 目录 +- 生成 `config.toml` 默认配置 +- 检查并更新 `.gitignore` + +### 4.3 aide env ensure + +**调用时机**：步骤 4 + +**输入**：无（读取 `.aide/config.toml`） + +**输出示例**： +``` +→ 任务原文档: task-now.md +→ 任务细则文档: task-spec.md +✓ 环境就绪 (python:3.12, uv:0.4.0, venv:.venv) +``` + +**行为**： +- 读取配置文件 +- 检查/创建虚拟环境 +- 安装依赖 +- 输出任务文档路径配置 + +--- + +## 五、项目认知阶段 + +### 5.1 认知内容 + +| 内容 | 来源 | 目的 | +|------|------|------| +| 项目概述 | README.md | 理解项目目标和功能 | +| 开发约定 | CLAUDE.md | 了解项目特定规则 | +| 目录结构 | 文件系统 | 理解模块划分 | +| 技术栈 | package.json/requirements.txt 等 | 了解使用的技术 | + +### 5.2 认知输出 + +向用户汇报项目概况（3-5句话），包括： +- 项目是什么 +- 主要功能/模块 +- 使用的技术栈 + +--- + +## 六、汇报格式 + +``` +项目概况：[来自项目认知的概要] + +环境状态：✓ 环境就绪 (python:3.12, ...) + +项目配置： +- 任务原文档：task-now.md +- 任务细则：task-spec.md + +Aide 已就绪，可用命令： +- /aide:prep [文档路径] - 任务准备 +- /aide:exec [文档路径] - 任务执行 +``` + +--- + +## 七、依赖 + +| 依赖项 | 类型 | 说明 | +|--------|------|------| +| aide env | aide 子命令 | 环境检测 | +| aide init | aide 子命令 | 配置初始化 | + +--- + +## 八、被依赖 + +| 依赖方 | 说明 | +|--------|------| +| /aide:prep | 依赖 init 完成环境准备 | +| /aide:exec | 依赖 init 完成环境准备 | + +--- + +## 九、修改指南 + +### 9.1 修改执行流程 + +1. 更新本文档的流程图和步骤详解 +2. 修改执行文件 `../../commands/init.md` +3. 如涉及新的 aide 子命令，同步更新 [aide skill 设计文档](../skill/aide.md) + +### 9.2 修改项目认知内容 + +1. 更新本文档的"项目认知阶段"章节 +2. 修改执行文件中的认知步骤 + +### 9.3 修改汇报格式 + +1. 更新本文档的"汇报格式"章节 +2. 修改执行文件中的汇报模板 + +--- + +## 十、相关文档 + +- [执行文件](../../commands/init.md) +- [aide env 设计](../../../../aide-program/docs/commands/env.md) +- [aide init 设计](../../../../aide-program/docs/commands/init.md) +- [plugin 导览](../README.md) diff --git a/aide-marketplace/aide-plugin/docs/commands/prep.md b/aide-marketplace/aide-plugin/docs/commands/prep.md new file mode 100644 index 0000000..f4005cb --- /dev/null +++ b/aide-marketplace/aide-plugin/docs/commands/prep.md @@ -0,0 +1,289 @@ +# /aide:prep 命令设计文档 + +## 一、背景 + +### 1.1 解决的问题 + +用户提供的任务描述通常存在以下问题： + +| 问题 | 影响 | +|------|------| +| 表述模糊 | 执行方向不明确 | +| 存在歧义 | 可能产生错误理解 | +| 缺少细节 | 执行时需要频繁确认 | +| 多种方案 | 需要用户决策 | + +### 1.2 设计目标 + +将任务描述转化为**清晰、可执行的任务细则**： +- 消除歧义和模糊 +- 明确执行步骤和验证标准 +- 处理待定项，获取用户决策 +- 产出 task-spec.md 供执行阶段使用 + +--- + +## 二、职责 + +### 2.1 做什么 + +1. 启动流程追踪（task-optimize 环节） +2. 深度分析任务内容 +3. 优化任务表述（准确性、简洁性、可执行性） +4. 处理待定项，获取用户确认 +5. 生成任务细则（task-spec.md） + +### 2.2 不做什么 + +- 不执行实际的任务实现 +- 不编写业务代码 +- 不主动关注 git 操作和状态记录（由 aide flow 自动处理） + +--- + +## 三、参数 + +| 参数 | 类型 | 说明 | +|------|------|------| +| `$ARGUMENTS` | 可选 | 任务原文档路径 | + +**未传入参数时**：使用 `aide config get task.source` 获取默认路径（通常为 task-now.md） + +--- + +## 四、执行流程 + +``` +@startuml +skinparam defaultFontName "PingFang SC" + +start + +:aide flow start task-optimize "开始任务准备: <任务简述>"; + +:确定任务文档路径; +note right: 使用参数或配置默认值 + +:读取任务文档; + +if (文档存在?) then (是) +else (否) + :询问用户提供任务内容; + stop +endif + +partition "阶段1: 任务分析" { + :深度理解任务; + note right: 核心目标\n交付物\n成功标准\n涉及模块\n技术难点 + + :分析项目环境; + note right: 阅读相关代码/文档\n理解与现有结构的关系 + + :aide flow next-step "任务分析完成"; +} + +partition "阶段2: 任务优化" { + :准确性优化; + note right: 识别歧义\n识别隐含假设\n明确边界 + + :简洁性优化; + note right: 识别冗余\n区分真冗余与必要强调 + + :可执行性优化; + note right: 抽象→具体步骤\n明确输入/输出/验证标准 + + :生成待定项; + + :aide flow next-step "任务优化完成，生成待定项"; +} + +partition "阶段3: 待定项处理" { + if (有待定项?) then (是) + :aide decide ''; + :告知用户访问链接; + :aide decide result; + :aide flow next-step "用户完成待定项确认"; + else (否) + endif +} + +partition "阶段4: 结果生成" { + :整合生成任务细则; + :aide flow next-step "生成任务细则，等待用户确认"; + + :展示给用户确认; + + if (用户确认?) then (是) + :保存为 task-spec.md; + :aide flow next-step "用户确认任务细则"; + else (否) + :根据反馈调整; + note right: 返回相应阶段 + endif +} + +:aide flow next-step "任务准备完成"; + +:提示用户执行 /aide:exec; + +stop +@enduml +``` + +--- + +## 五、阶段详解 + +### 5.1 阶段1：任务分析 + +**核心问题**： +- 任务要解决什么问题？ +- 最终交付物是什么？ +- 成功的标准是什么？ +- 涉及哪些模块/系统？ +- 是否有技术难点？ + +**复杂任务处理**： +- 多子目标、多方案对比时，建议使用 sequential-thinking 进行结构化分析 + +### 5.2 阶段2：任务优化 + +| 优化维度 | 关注点 | +|----------|--------| +| 准确性 | 歧义、不明确之处、隐含假设、任务边界 | +| 简洁性 | 冗余表述、区分真冗余与必要强调 | +| 可执行性 | 抽象→具体步骤、输入/输出/验证标准、替代方案 | + +### 5.3 阶段3：待定项处理 + +**待定项类型**： +- 存在多种可行方案 +- 有歧义需要澄清 +- 需要用户确认的决策 + +**处理流程**： +1. 准备待定项 JSON 数据 +2. 调用 `aide decide ''` 启动 Web 服务 +3. 告知用户访问链接进行确认 +4. 调用 `aide decide result` 获取决策结果 + +### 5.4 阶段4：结果生成 + +**任务细则结构**： +```markdown +# 任务细则 + +## 任务目标 +[清晰描述任务要达成的目标] + +## 成功标准 +[明确的、可验证的成功标准] + +## 执行步骤 +1. [步骤1] +2. [步骤2] +... + +## 技术决策 +[已确认的技术选型] + +## 约束与边界 +[任务范围边界] +``` + +--- + +## 六、与 aide 程序的交互 + +### 6.1 aide flow start + +**调用时机**：命令开始时 + +**命令**： +```bash +aide flow start task-optimize "开始任务准备: <任务简述>" +``` + +### 6.2 aide flow next-step + +**调用时机**：每个阶段完成时 + +**命令**： +```bash +aide flow next-step "<完成内容简述>" +``` + +### 6.3 aide config get + +**调用时机**：未传入参数时 + +**命令**： +```bash +aide config get task.source +``` + +### 6.4 aide decide + +**调用时机**：有待定项需要用户确认时 + +**命令**： +```bash +aide decide '' +aide decide result +``` + +--- + +## 七、注意事项 + +1. **不要主动提及 git 操作**：由 aide flow 自动处理 +2. **不要主动提及状态记录**：由 aide flow 自动处理 +3. **专注于任务分析和优化**：这是 prep 的核心价值 + +--- + +## 八、依赖 + +| 依赖项 | 类型 | 说明 | +|--------|------|------| +| /aide:init | Command | 需要先完成环境初始化 | +| aide flow | aide 子命令 | 流程追踪 | +| aide decide | aide 子命令 | 待定项处理 | +| aide config | aide 子命令 | 读取配置 | + +--- + +## 九、被依赖 + +| 依赖方 | 说明 | +|--------|------| +| /aide:exec | 使用 prep 产出的 task-spec.md | + +--- + +## 十、修改指南 + +### 10.1 修改分析/优化流程 + +1. 更新本文档的阶段详解 +2. 修改执行文件 `../../commands/prep.md` + +### 10.2 修改任务细则格式 + +1. 更新本文档的"结果生成"章节 +2. 修改执行文件中的模板 + +### 10.3 修改待定项处理 + +1. 更新本文档的"待定项处理"章节 +2. 如涉及数据格式变更，同步更新 [数据格式文档](../../../../aide-program/docs/formats/data.md) + +--- + +## 十一、相关文档 + +- [执行文件](../../commands/prep.md) +- [aide flow 设计](../../../../aide-program/docs/commands/flow.md) +- [aide decide 设计](../../../../aide-program/docs/commands/decide.md) +- [数据格式规范](../../../../aide-program/docs/formats/data.md) +- [plugin 导览](../README.md) diff --git a/aide-marketplace/aide-plugin/docs/skill/aide.md b/aide-marketplace/aide-plugin/docs/skill/aide.md new file mode 100644 index 0000000..864f841 --- /dev/null +++ b/aide-marketplace/aide-plugin/docs/skill/aide.md @@ -0,0 +1,415 @@ +# Aide Skill 设计文档 + +## 一、背景 + +### 1.1 解决的问题 + +LLM 在执行任务时需要调用各种工具，但： + +| 问题 | 影响 | +|------|------| +| 命令语法分散 | 每次都要回忆或查找 | +| 输出格式不明确 | 难以正确解析结果 | +| 使用场景模糊 | 不知道何时该用什么命令 | + +### 1.2 设计目标 + +提供**统一的工具使用指南**： +- 所有 aide 子命令的语法和参数 +- 输入输出格式说明 +- 典型使用示例 + +--- + +## 二、职责 + +### 2.1 做什么 + +告诉 LLM： +- aide 有哪些子命令可用 +- 每个子命令怎么调用 +- 调用后会得到什么结果 + +### 2.2 不做什么 + +- 不涉及流程指导（那是 Commands 的职责） +- 不涉及业务逻辑 +- 不涉及决策判断 + +--- + +## 三、子命令索引 + +| 子命令 | 用途 | 详细设计 | +|--------|------|----------| +| `aide env` | 环境检测与修复 | [env.md](../../../../aide-program/docs/commands/env.md) | +| `aide flow` | 进度追踪与 git 集成 | [flow.md](../../../../aide-program/docs/commands/flow.md) | +| `aide decide` | 待定项 Web 确认 | [decide.md](../../../../aide-program/docs/commands/decide.md) | +| `aide config` | 配置读写 | [config.md](../../../../aide-program/docs/formats/config.md) | +| `aide init` | 初始化 .aide 目录 | [init.md](../../../../aide-program/docs/commands/init.md) | + +--- + +## 四、输出格式规范 + +### 4.1 前缀符号 + +| 前缀 | 含义 | 处理方式 | +|------|------|----------| +| `✓` | 成功 | 继续执行 | +| `⚠` | 警告（可继续） | 记录后继续 | +| `✗` | 错误（需处理） | 按提示处理或告知用户 | +| `→` | 进行中/信息 | 读取信息 | + +### 4.2 静默原则 + +**无输出 = 正常完成** + +只有在需要反馈信息时才会有输出。 + +--- + +## 五、子命令接口规格 + +### 5.1 aide env ensure + +**用途**：检测并修复开发环境 + +**语法**： +``` +aide env ensure [--runtime] +``` + +**参数**： + +| 参数 | 说明 | +|------|------| +| `--runtime` | 仅检查 aide 运行时环境，不依赖配置文件 | + +**输出**： + +``` +# 成功 +✓ 环境就绪 (python:3.12, uv:0.4.0) + +# 成功（完整检查） +→ 任务原文档: task-now.md +→ 任务细则文档: task-spec.md +✓ 环境就绪 (python:3.12, uv:0.4.0, venv:.venv) + +# 自动修复 +⚠ 已修复: 创建虚拟环境 .venv +✓ 环境就绪 (python:3.12) + +# 失败 +✗ Python 版本不满足要求 (需要 >=3.10, 当前 3.8) + 建议: 安装 Python 3.10+ 或使用 pyenv 管理版本 +``` + +### 5.2 aide init + +**用途**：初始化 .aide 目录和默认配置 + +**语法**： +``` +aide init +``` + +**行为**： +1. 创建 `.aide/` 目录 +2. 生成默认 `config.toml` +3. 检查并更新 `.gitignore` + +**输出**： +``` +✓ 已创建默认配置 .aide/config.toml +✓ 初始化完成，.aide/ 与默认配置已准备就绪 +``` + +### 5.3 aide flow + +**用途**：进度追踪 + Git 自动提交 + 流程校验 + +#### aide flow start + +**语法**： +``` +aide flow start <环节名> "<总结>" +``` + +**参数**： + +| 参数 | 说明 | +|------|------| +| `<环节名>` | task-optimize / flow-design / impl / verify / docs / finish | +| `<总结>` | 本次操作的简要说明 | + +**示例**： +```bash +aide flow start task-optimize "开始任务准备: 实现用户登录功能" +aide flow start flow-design "开始任务: 实现用户认证模块" +``` + +#### aide flow next-step + +**语法**： +``` +aide flow next-step "<总结>" +``` + +**示例**： +```bash +aide flow next-step "完成数据库模型设计" +``` + +#### aide flow back-step + +**语法**： +``` +aide flow back-step "<原因>" +``` + +**示例**： +```bash +aide flow back-step "发现字段命名不符合规范，需要调整" +``` + +#### aide flow next-part + +**语法**： +``` +aide flow next-part <环节名> "<总结>" +``` + +**示例**： +```bash +aide flow next-part impl "流程设计完成，开始实现" +aide flow next-part verify "实现完成，开始验证" +``` + +#### aide flow back-part + +**语法**： +``` +aide flow back-part <环节名> "<原因>" +``` + +**示例**： +```bash +aide flow back-part flow-design "实现中发现设计遗漏，需要补充" +``` + +#### aide flow issue + +**语法**： +``` +aide flow issue "<描述>" +``` + +**示例**： +```bash +aide flow issue "测试覆盖率较低，后续需要补充" +``` + +#### aide flow error + +**语法**： +``` +aide flow error "<描述>" +``` + +**示例**： +```bash +aide flow error "数据库连接失败，无法继续" +``` + +#### 环节名称与使用场景 + +| 环节名 | 说明 | 使用场景 | +|--------|------|----------| +| `task-optimize` | 任务优化 | prep 阶段 | +| `flow-design` | 流程设计 | exec 阶段 | +| `impl` | 迭代实现 | exec 阶段 | +| `verify` | 验证交付 | exec 阶段 | +| `docs` | 文档更新 | exec 阶段 | +| `finish` | 收尾 | exec 阶段 | + +#### Git 集成 + +每次调用 aide flow 命令都会自动执行： +1. `git add .` +2. `git commit -m "[aide] <环节>: <总结>"` + +#### 流程校验 + +aide flow 会自动校验环节跳转是否合理： +- `flow-design` → `impl` ✓ +- `impl` → `verify` ✓ +- `impl` → `flow-design` ✓（回退） +- `flow-design` → `finish` ✗（跳过环节） + +### 5.4 aide decide + +**用途**：通过 Web 界面处理待定项确认 + +#### aide decide（提交数据） + +**语法**： +``` +aide decide '' +``` + +**输入格式**：见 [数据格式文档](../../../../aide-program/docs/formats/data.md) + +**输出**： +``` +→ Web 服务已启动 +→ 请访问: http://localhost:3721 +→ 等待用户完成决策... +``` + +#### aide decide result + +**语法**： +``` +aide decide result +``` + +**输出格式**： +```json +{ + "decisions": [ + {"id": 1, "chosen": "option_a"}, + {"id": 2, "chosen": "option_b", "note": "用户的补充说明"} + ] +} +``` + +> 注：`note` 字段仅在用户添加备注时出现 + +### 5.5 aide config + +**用途**：配置读写 + +#### aide config get + +**语法**： +``` +aide config get +``` + +**参数**： +- ``：使用点号分隔的键名，如 `task.source` + +**示例**： +```bash +aide config get task.source +# 输出: → task.source = 'task-now.md' + +aide config get flow.phases +# 输出: → flow.phases = ['task-optimize', 'flow-design', 'impl', 'verify', 'docs', 'finish'] +``` + +#### aide config set + +**语法**： +``` +aide config set +``` + +**示例**： +```bash +aide config set task.source "my-task.md" +# 输出: ✓ 已更新 task.source = 'my-task.md' +``` + +--- + +## 六、典型使用场景 + +### 6.1 init 阶段 + +```bash +# 检查运行时环境 +aide env ensure --runtime + +# 初始化配置 +aide init + +# 检查项目环境 +aide env ensure +``` + +### 6.2 prep 阶段 + +```bash +# 开始任务准备 +aide flow start task-optimize "开始任务准备: 实现用户认证模块" + +# 记录进度 +aide flow next-step "任务分析完成" +aide flow next-step "任务优化完成，生成待定项" + +# 处理待定项 +aide decide '{"task":"...", "items":[...]}' +aide decide result + +aide flow next-step "用户完成待定项确认" +aide flow next-step "任务准备完成" +``` + +### 6.3 exec 阶段 + +```bash +# 进入流程设计 +aide flow next-part flow-design "进入流程设计环节" + +# 记录设计进度 +aide flow next-step "流程图设计完成" + +# 进入实现 +aide flow next-part impl "流程设计完成，开始实现" + +# 记录实现进度 +aide flow next-step "完成 User 模型定义" +aide flow next-step "完成密码加密工具" + +# 记录问题 +aide flow issue "部分边界情况未覆盖测试" + +# 进入验证 +aide flow next-part verify "实现完成，开始验证" + +# 进入文档 +aide flow next-part docs "验证通过，更新文档" + +# 收尾 +aide flow next-part finish "文档更新完成，收尾" +aide flow next-step "任务完成" +``` + +--- + +## 七、修改指南 + +### 7.1 修改子命令接口 + +1. 更新本文档对应章节 +2. 修改执行文件 `../../skills/aide/SKILL.md` +3. 同步更新 [aide-program 对应文档](../../../../aide-program/docs/README.md) + +### 7.2 新增子命令 + +1. 在本文档添加接口规格 +2. 在执行文件添加使用说明 +3. 更新子命令索引表 +4. 在 aide-program 添加对应设计文档 + +--- + +## 八、相关文档 + +- [执行文件](../../skills/aide/SKILL.md) +- [aide-program 导览](../../../../aide-program/docs/README.md) +- [数据格式规范](../../../../aide-program/docs/formats/data.md) +- [plugin 导览](../README.md) diff --git a/aide-program/docs/README.md b/aide-program/docs/README.md new file mode 100644 index 0000000..48afb64 --- /dev/null +++ b/aide-program/docs/README.md @@ -0,0 +1,208 @@ +# Aide Program 设计文档 + +## 一、概述 + +aide-program 是 Aide 工作流体系的命令行工具，为 aide-plugin 提供底层支持。 + +### 1.1 解决的问题 + +| 问题 | 解决方案 | +|------|----------| +| 操作不确定性 | 程序化封装，固定输入输出 | +| 输出信息冗余 | 精简输出，静默即成功 | +| git 操作分散 | 集成到 flow 命令，自动提交 | +| 状态难追踪 | 统一的状态文件和日志 | + +### 1.2 与 aide-plugin 的关系 + +``` +┌─────────────────────────────────────────────────┐ +│ aide-plugin │ +│ Commands: 定义流程（做什么、按什么顺序） │ +│ Skill: 定义工具使用方法（怎么调用） │ +└─────────────────────────────────────────────────┘ + │ + ▼ 调用 +┌─────────────────────────────────────────────────┐ +│ aide-program │ +│ 实际执行操作，返回精简结果 │ +│ │ +│ ┌────────┐ ┌────────┐ ┌────────┐ │ +│ │ env │ │ flow │ │ decide │ │ +│ └────────┘ └────────┘ └────────┘ │ +│ ┌────────┐ ┌────────┐ │ +│ │ config │ │ init │ │ +│ └────────┘ └────────┘ │ +└─────────────────────────────────────────────────┘ +``` + +--- + +## 二、子命令索引 + +| 子命令 | 设计文档 | 实现状态 | 职责 | +|--------|----------|----------|------| +| `aide init` | [commands/init.md](commands/init.md) | ✅ 已实现 | 初始化 .aide 目录 | +| `aide env` | [commands/env.md](commands/env.md) | ✅ 已实现 | 环境检测与修复 | +| `aide config` | [formats/config.md](formats/config.md) | ✅ 已实现 | 配置读写 | +| `aide flow` | [commands/flow.md](commands/flow.md) | ⏳ 待实现 | 进度追踪与 git 集成 | +| `aide decide` | [commands/decide.md](commands/decide.md) | ⏳ 待实现 | 待定项 Web 确认 | + +--- + +## 三、目录结构 + +``` +aide-program/ +├── aide.sh # Linux/Mac 入口脚本 +├── aide.bat # Windows 入口脚本 +├── docs/ # 设计文档（本目录） +│ ├── README.md # 导览（本文件） +│ ├── commands/ # 子命令设计文档 +│ │ ├── env.md +│ │ ├── flow.md +│ │ ├── decide.md +│ │ └── init.md +│ └── formats/ # 数据格式文档 +│ ├── config.md +│ └── data.md +└── aide/ # Python 代码 + ├── __init__.py + ├── __main__.py # 支持 python -m aide + ├── main.py # CLI 解析与命令分发 + ├── core/ + │ ├── __init__.py + │ ├── config.py # 配置读写 + │ └── output.py # 输出格式（✓/⚠/✗/→） + ├── env/ + │ ├── __init__.py + │ └── ensure.py # 环境检测与修复 + ├── flow/ # 待实现 + │ ├── __init__.py + │ ├── tracker.py # 进度追踪 + │ ├── git.py # git 自动提交 + │ └── validator.py # 流程校验 + └── decide/ # 待实现 + ├── __init__.py + ├── server.py # HTTP 服务 + └── web/ # 静态前端 +``` + +--- + +## 四、输出规范 + +### 4.1 前缀符号 + +| 前缀 | 函数 | 用途 | +|------|------|------| +| `✓` | `output.ok()` | 成功 | +| `⚠` | `output.warn()` | 警告（可继续） | +| `✗` | `output.err()` | 失败 | +| `→` | `output.info()` | 进行中/信息 | +| `[n/m]` | `output.step()` | 步骤进度 | + +### 4.2 静默原则 + +**无输出 = 正常完成** + +只有在需要反馈信息时才输出。 + +### 4.3 输出示例 + +```bash +# 成功 +✓ 环境就绪 (python:3.12, uv:0.4.0) + +# 警告 +⚠ 已修复: 创建虚拟环境 .venv + +# 错误 +✗ Python 版本不满足要求 (需要 >=3.10, 当前 3.8) + 建议: 安装 Python 3.10+ 或使用 pyenv 管理版本 + +# 信息 +→ 任务原文档: task-now.md +``` + +--- + +## 五、数据存储 + +### 5.1 存储位置 + +所有 aide 数据文件存放在项目根目录的 `.aide/` 下： + +``` +.aide/ +├── config.toml # 项目配置 +├── flow-status.json # 当前任务进度状态 +├── decisions/ # 待定项决策记录 +│ └── {timestamp}.json +└── logs/ # 操作日志 +``` + +### 5.2 .gitignore 处理 + +- `aide init` 时自动检查 `.gitignore` +- 默认添加 `.aide/` 为忽略项 + +--- + +## 六、运行方式 + +### 6.1 通过入口脚本 + +```bash +# Linux/Mac +./aide-program/aide.sh [args] + +# Windows +aide-program\aide.bat [args] +``` + +### 6.2 通过 Python 模块 + +```bash +# 需要先激活虚拟环境或设置 PYTHONPATH +python -m aide [args] +``` + +### 6.3 依赖要求 + +- Python >= 3.11 +- uv（用于虚拟环境和依赖管理） +- tomli-w（TOML 写入） + +--- + +## 七、开发指南 + +### 7.1 添加新子命令 + +1. 在 `docs/commands/` 创建设计文档 +2. 在 `aide/` 下创建对应模块目录 +3. 在 `aide/main.py` 添加 CLI 路由 +4. 更新本导览的子命令索引 +5. 更新 [aide skill 设计文档](../../aide-marketplace/aide-plugin/docs/skill/aide.md) + +### 7.2 修改现有子命令 + +1. 阅读对应的设计文档 +2. 修改代码实现 +3. 更新设计文档（如有接口变更） +4. 同步更新 aide skill 文档 + +### 7.3 代码规范 + +- 所有输出使用 `core/output.py` 中的函数 +- 配置操作使用 `core/config.py` 中的 `ConfigManager` +- 遵循静默原则：成功时尽量少输出 + +--- + +## 八、相关文档 + +- [总导览](../../docs/aide-overview.md) +- [aide-plugin 导览](../../aide-marketplace/aide-plugin/docs/README.md) +- [aide skill 设计文档](../../aide-marketplace/aide-plugin/docs/skill/aide.md) diff --git a/aide-program/docs/commands/decide.md b/aide-program/docs/commands/decide.md new file mode 100644 index 0000000..5a336b2 --- /dev/null +++ b/aide-program/docs/commands/decide.md @@ -0,0 +1,353 @@ +# aide decide 子命令设计文档 + +## 一、背景 + +### 1.1 解决的问题 + +| 问题 | 影响 | +|------|------| +| 待定项呈现繁琐 | LLM 输出大量文本描述选项 | +| 用户确认不便 | 在终端中逐项确认效率低 | +| 决策记录分散 | 难以追溯历史决策 | + +### 1.2 设计目标 + +提供**程序化的待定项确认机制**： +- LLM 传入精简 JSON 数据 +- 程序启动 Web 服务，提供可视化界面 +- 用户在 Web 界面操作 +- LLM 读取精简决策结果 + +--- + +## 二、职责 + +### 2.1 做什么 + +1. 接收待定项 JSON 数据 +2. 启动 HTTP 服务 +3. 提供 Web 界面供用户操作 +4. 存储用户决策 +5. 返回决策结果 + +### 2.2 不做什么 + +- 不分析待定项内容 +- 不做决策建议 +- 不修改业务代码 + +--- + +## 三、接口规格 + +### 3.1 aide decide（提交数据） + +**用途**：提交待定项数据并启动 Web 服务 + +**语法**： +``` +aide decide '' +``` + +**输入**：待定项 JSON 数据（见数据格式章节） + +**输出**： +``` +→ Web 服务已启动 +→ 请访问: http://localhost:3721 +→ 等待用户完成决策... +``` + +### 3.2 aide decide result + +**用途**：获取用户决策结果 + +**语法**： +``` +aide decide result +``` + +**输出**： +```json +{ + "decisions": [ + {"id": 1, "chosen": "option_a"}, + {"id": 2, "chosen": "option_b", "note": "用户的补充说明"} + ] +} +``` + +**错误情况**： +``` +✗ 尚无决策结果，请等待用户完成操作 +``` + +``` +✗ 未找到待定项数据，请先执行 aide decide '' +``` + +--- + +## 四、业务流程 + +### 4.1 整体流程 + +``` +@startuml +skinparam defaultFontName "PingFang SC" + +participant LLM +participant "aide decide" as Decide +participant "Web Server" as Web +participant User + +LLM -> Decide : aide decide '' +Decide -> Decide : 解析 JSON +Decide -> Decide : 保存待定项数据 +Decide -> Web : 启动 HTTP 服务 +Decide --> LLM : 输出访问链接 + +LLM -> User : 告知访问链接 + +User -> Web : 访问页面 +Web -> User : 渲染待定项界面 +User -> Web : 选择选项、添加备注 +User -> Web : 提交决策 +Web -> Web : 保存决策结果 + +LLM -> Decide : aide decide result +Decide -> Decide : 读取决策结果 +Decide --> LLM : 返回 JSON 结果 + +@enduml +``` + +### 4.2 Web 服务流程 + +``` +@startuml +skinparam defaultFontName "PingFang SC" + +start + +:接收 JSON 数据; + +:解析并验证格式; +if (格式有效?) then (是) +else (否) + :输出错误信息; + stop +endif + +:保存到 .aide/decisions/pending.json; + +:启动 HTTP 服务; +note right: 默认端口 3721 + +:输出访问链接; + +:等待用户操作; + +:用户提交决策; + +:保存决策结果; +note right: .aide/decisions/{timestamp}.json + +:关闭 HTTP 服务; + +stop +@enduml +``` + +--- + +## 五、数据结构 + +### 5.1 输入格式（LLM → 程序） + +``` +DecideInput: + task: str # 任务简述 + source: str # 来源文档 + items: list[DecideItem] # 待定项列表 + +DecideItem: + id: int # 待定项 ID + title: str # 问题标题 + location: Location | None # 原文位置（可选） + context: str | None # 详细说明（可选） + options: list[Option] # 选项列表 + recommend: str | None # 推荐选项的 value（可选） + +Location: + file: str # 文件路径 + start: int # 起始行 + end: int # 结束行 + +Option: + value: str # 选项标识 + label: str # 选项描述 + score: int | None # 评分（可选） + pros: list[str] | None # 优点列表（可选） + cons: list[str] | None # 缺点列表（可选） +``` + +### 5.2 输出格式（程序 → LLM） + +``` +DecideOutput: + decisions: list[Decision] # 决策列表 + +Decision: + id: int # 待定项 ID + chosen: str # 选中的选项 value + note: str | None # 用户备注（可选） +``` + +### 5.3 方法签名原型 + +``` +class DecideServer: + root: Path + port: int # 默认 3721 + pending_path: Path # .aide/decisions/pending.json + decisions_dir: Path # .aide/decisions/ + + submit(json_data: str) -> bool + # 提交待定项数据，启动服务 + + get_result() -> DecideOutput | None + # 获取决策结果 + + _parse_input(json_data: str) -> DecideInput + # 解析输入 JSON + + _validate_input(data: DecideInput) -> bool + # 验证输入格式 + + _start_server() -> None + # 启动 HTTP 服务 + + _stop_server() -> None + # 停止 HTTP 服务 + + _save_pending(data: DecideInput) -> None + # 保存待定项数据 + + _save_result(result: DecideOutput) -> None + # 保存决策结果 + + _load_result() -> DecideOutput | None + # 加载决策结果 +``` + +### 5.4 Web 界面组件 + +``` +DecideApp: + # React 前端应用 + + state: + items: list[DecideItem] # 待定项列表 + decisions: dict[int, str] # 当前选择 + notes: dict[int, str] # 用户备注 + + methods: + loadItems() -> None # 加载待定项 + selectOption(id, value) -> None # 选择选项 + addNote(id, note) -> None # 添加备注 + submit() -> None # 提交决策 +``` + +--- + +## 六、Web 界面设计 + +### 6.1 页面结构 + +``` +┌─────────────────────────────────────────────────┐ +│ Aide 待定项确认 │ +│ 任务: │ +├─────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────────────────────────────┐ │ +│ │ 1. │ │ +│ │ <context> │ │ +│ │ │ │ +│ │ ○ <option_a.label> [推荐] │ │ +│ │ 优点: ... 缺点: ... │ │ +│ │ │ │ +│ │ ○ <option_b.label> │ │ +│ │ 优点: ... 缺点: ... │ │ +│ │ │ │ +│ │ 备注: [________________] │ │ +│ └─────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────┐ │ +│ │ 2. <title> │ │ +│ │ ... │ │ +│ └─────────────────────────────────────────┘ │ +│ │ +│ [提交决策] │ +└─────────────────────────────────────────────────┘ +``` + +### 6.2 交互流程 + +1. 页面加载时从后端获取待定项数据 +2. 用户点击选项进行选择 +3. 用户可选择性添加备注 +4. 点击"提交决策"按钮 +5. 前端发送决策到后端 +6. 后端保存结果并关闭服务 +7. 页面显示"决策已提交" + +--- + +## 七、依赖 + +| 依赖项 | 类型 | 说明 | +|--------|------|------| +| output | 内部模块 | 输出格式化 | +| http.server | 标准库 | HTTP 服务 | +| json | 标准库 | JSON 解析 | + +--- + +## 八、被依赖 + +| 依赖方 | 说明 | +|--------|------| +| /aide:prep | 调用 decide 处理待定项 | + +--- + +## 九、修改指南 + +### 9.1 修改输入/输出格式 + +1. 更新本文档的数据结构章节 +2. 修改代码实现 +3. 同步更新 [数据格式文档](../formats/data.md) +4. 同步更新 [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md) + +### 9.2 修改 Web 界面 + +1. 更新本文档的界面设计章节 +2. 修改 `aide/decide/web/` 下的前端代码 + +### 9.3 修改端口配置 + +1. 在配置文件中添加端口配置项 +2. 修改 `DecideServer` 读取配置 +3. 更新 [配置格式文档](../formats/config.md) + +--- + +## 十、相关文档 + +- [program 导览](../README.md) +- [数据格式文档](../formats/data.md) +- [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md) +- [/aide:prep 命令设计](../../../aide-marketplace/aide-plugin/docs/commands/prep.md) diff --git a/aide-program/docs/commands/env.md b/aide-program/docs/commands/env.md new file mode 100644 index 0000000..d9e7750 --- /dev/null +++ b/aide-program/docs/commands/env.md @@ -0,0 +1,257 @@ +# aide env 子命令设计文档 + +## 一、背景 + +### 1.1 解决的问题 + +| 问题 | 影响 | +|------|------| +| 环境不一致 | 命令执行失败，打断业务流程 | +| 手动检查繁琐 | 每次都要检查 Python、虚拟环境、依赖 | +| 修复方式不统一 | 不同人有不同的修复习惯 | + +### 1.2 设计目标 + +提供**统一的环境检测与修复**： +- 自动检测环境问题 +- 能修复的自动修复 +- 不能修复的给出明确建议 + +--- + +## 二、职责 + +### 2.1 做什么 + +1. 检测 Python 版本是否满足要求 +2. 检测 uv 是否可用 +3. 检测/创建虚拟环境 +4. 安装依赖 +5. 输出项目配置信息 + +### 2.2 不做什么 + +- 不修改业务代码 +- 不执行业务逻辑 +- 不进行流程追踪 + +--- + +## 三、接口规格 + +### 3.1 命令语法 + +``` +aide env ensure [--runtime] +``` + +### 3.2 参数 + +| 参数 | 类型 | 说明 | +|------|------|------| +| `--runtime` | 可选 | 仅检查 aide 运行时环境，不依赖配置文件 | + +### 3.3 输出 + +**成功（runtime 模式）**： +``` +✓ 运行时环境就绪 (python:3.12, uv:0.4.0) +``` + +**成功（完整模式）**： +``` +→ 任务原文档: task-now.md +→ 任务细则文档: task-spec.md +✓ 环境就绪 (python:3.12, uv:0.4.0, venv:.venv) +``` + +**自动修复**： +``` +→ 创建虚拟环境: .venv +✓ 已创建虚拟环境 +⚠ 未找到 requirements.txt，已创建空文件 +→ 安装依赖（uv pip install -r requirements.txt） +✓ 环境就绪 (python:3.12, uv:0.4.0, venv:.venv) +``` + +**失败**： +``` +✗ Python 版本不足，要求>=3.11，当前 3.9 +``` + +``` +✗ 未检测到 uv，请先安装（FileNotFoundError） +``` + +--- + +## 四、业务流程 + +``` +@startuml +skinparam defaultFontName "PingFang SC" + +start + +if (--runtime 参数?) then (是) + :required_py = "3.11" (硬编码); +else (否) + :从配置文件读取 required_py; +endif + +:检查 Python 版本; +if (版本满足?) then (是) +else (否) + :输出错误信息; + stop +endif + +:检查 uv 可用性; +if (uv 可用?) then (是) +else (否) + :输出错误信息; + stop +endif + +if (--runtime 参数?) then (是) + :输出运行时环境就绪; + stop +endif + +:读取配置文件; +:确保 .gitignore 包含 .aide/; + +:读取 venv 路径配置; +if (虚拟环境存在?) then (是) +else (否) + :使用 uv venv 创建; + if (创建成功?) then (是) + else (否) + :输出错误信息; + stop + endif +endif + +:读取 requirements 路径配置; +if (requirements.txt 存在?) then (是) +else (否) + :创建空文件; + :输出警告; +endif + +:使用 uv pip install 安装依赖; +if (安装成功?) then (是) +else (否) + :输出错误信息; + stop +endif + +:输出任务文档路径配置; +:输出环境就绪; + +stop +@enduml +``` + +--- + +## 五、数据结构 + +### 5.1 配置依赖 + +从 `.aide/config.toml` 读取： + +``` +[runtime] +python_min # Python 最低版本要求 + +[env] +venv # 虚拟环境路径 +requirements # 依赖文件路径 + +[task] +source # 任务原文档路径 +spec # 任务细则文档路径 +``` + +### 5.2 方法签名原型 + +``` +class EnvManager: + root: Path # 项目根目录 + + ensure(runtime_only: bool, cfg: ConfigManager) -> bool + # 主入口，返回是否成功 + + _get_required_python(cfg: ConfigManager, runtime_only: bool) -> str + # 获取 Python 版本要求 + + _parse_version(version: str) -> tuple[int, ...] + # 解析版本号字符串 + + _check_python_version(required: str) -> bool + # 检查 Python 版本 + + _check_uv() -> str | None + # 检查 uv，返回版本号或 None + + _ensure_venv(venv_path: Path) -> bool + # 确保虚拟环境存在 + + _ensure_requirements_file(req_path: Path) -> None + # 确保 requirements.txt 存在 + + _install_requirements(venv_path: Path, req_path: Path) -> bool + # 安装依赖 +``` + +--- + +## 六、依赖 + +| 依赖项 | 类型 | 说明 | +|--------|------|------| +| ConfigManager | 内部模块 | 配置读写 | +| output | 内部模块 | 输出格式化 | +| uv | 外部工具 | 虚拟环境和依赖管理 | + +--- + +## 七、被依赖 + +| 依赖方 | 说明 | +|--------|------| +| /aide:init | 调用 env ensure --runtime 和 env ensure | +| aide init | 内部可能调用 env 检查 | + +--- + +## 八、修改指南 + +### 8.1 修改检测逻辑 + +1. 更新本文档的业务流程图 +2. 修改 `aide/env/ensure.py` +3. 如有新的输出，更新输出示例 + +### 8.2 添加新的检测项 + +1. 在本文档添加检测项说明 +2. 在 `EnvManager` 添加对应方法 +3. 在 `ensure()` 中调用 +4. 更新 [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md) + +### 8.3 修改配置依赖 + +1. 更新本文档的"配置依赖"章节 +2. 修改代码实现 +3. 同步更新 [配置格式文档](../formats/config.md) + +--- + +## 九、相关文档 + +- [program 导览](../README.md) +- [配置格式文档](../formats/config.md) +- [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md) +- [/aide:init 命令设计](../../../aide-marketplace/aide-plugin/docs/commands/init.md) diff --git a/aide-program/docs/commands/flow.md b/aide-program/docs/commands/flow.md new file mode 100644 index 0000000..491489b --- /dev/null +++ b/aide-program/docs/commands/flow.md @@ -0,0 +1,387 @@ +# aide flow 子命令设计文档 + +## 一、背景 + +### 1.1 解决的问题 + +| 问题 | 影响 | +|------|------| +| 状态记录分散 | 难以追踪任务进度 | +| git 提交不规范 | 提交信息不一致，难以追溯 | +| 流程跳跃 | 遗漏重要环节 | +| 返工无记录 | 问题原因和解决方案丢失 | + +### 1.2 设计目标 + +提供**统一的进度追踪与版本控制**： +- 自动记录状态变化 +- 自动执行 git add + commit +- 校验流程跳转合理性 +- 环节特定行为（如 PlantUML 校验） + +--- + +## 二、职责 + +### 2.1 做什么 + +1. 记录任务执行状态（环节、步骤） +2. 自动执行 git add . && git commit +3. 校验环节跳转是否符合预期流程 +4. 在特定环节执行特定行为（如校验 PlantUML） + +### 2.2 不做什么 + +- 不执行业务逻辑 +- 不进行任务分析 +- 不修改业务代码 + +--- + +## 三、接口规格 + +### 3.1 aide flow start + +**用途**：开始新任务 + +**语法**： +``` +aide flow start <环节名> "<总结>" +``` + +**参数**： + +| 参数 | 说明 | +|------|------| +| `<环节名>` | task-optimize / flow-design | +| `<总结>` | 本次操作的简要说明 | + +**输出**： +``` +✓ 任务开始: <环节名> +``` + +### 3.2 aide flow next-step + +**用途**：记录小步骤前进 + +**语法**： +``` +aide flow next-step "<总结>" +``` + +**输出**：静默（成功无输出） + +### 3.3 aide flow back-step + +**用途**：记录小步骤回退 + +**语法**： +``` +aide flow back-step "<原因>" +``` + +**输出**：静默（成功无输出） + +### 3.4 aide flow next-part + +**用途**：进入下一个大环节 + +**语法**： +``` +aide flow next-part <环节名> "<总结>" +``` + +**输出**： +``` +✓ 进入环节: <环节名> +``` + +**特殊行为**： +- 离开 `flow-design` 时：校验 PlantUML 语法，生成 PNG +- 进入 `docs` 时：提示更新 CHANGELOG +- 离开 `docs` 时：校验 CHANGELOG 是否已更新 + +### 3.5 aide flow back-part + +**用途**：回退到之前的大环节 + +**语法**： +``` +aide flow back-part <环节名> "<原因>" +``` + +**输出**： +``` +⚠ 回退到环节: <环节名> +``` + +### 3.6 aide flow issue + +**用途**：记录一般问题（不阻塞继续） + +**语法**： +``` +aide flow issue "<描述>" +``` + +**输出**：静默（成功无输出） + +### 3.7 aide flow error + +**用途**：记录严重错误（需要解决） + +**语法**： +``` +aide flow error "<描述>" +``` + +**输出**： +``` +✗ 错误已记录: <描述> +``` + +--- + +## 四、业务流程 + +### 4.1 状态记录流程 + +``` +@startuml +skinparam defaultFontName "PingFang SC" + +start + +:接收命令和参数; + +:读取当前状态; +note right: .aide/flow-status.json + +:校验操作合法性; +if (合法?) then (是) +else (否) + :输出错误信息; + stop +endif + +:更新状态文件; + +:执行 git add .; + +:生成提交信息; +note right: [aide] <环节>: <总结> + +:执行 git commit; + +if (环节特定行为?) then (是) + :执行特定行为; +endif + +:输出结果; + +stop +@enduml +``` + +### 4.2 流程校验规则 + +``` +@startuml +skinparam defaultFontName "PingFang SC" + +[*] --> task_optimize : start (prep阶段) +[*] --> flow_design : start (exec阶段) + +task_optimize --> task_optimize : next-step +task_optimize --> [*] : 完成prep + +flow_design --> flow_design : next-step +flow_design --> impl : next-part + +impl --> impl : next-step +impl --> flow_design : back-part +impl --> verify : next-part + +verify --> verify : next-step +verify --> impl : back-part +verify --> docs : next-part + +docs --> docs : next-step +docs --> verify : back-part +docs --> finish : next-part + +finish --> finish : next-step +finish --> [*] : 完成exec + +@enduml +``` + +**校验规则**： +- `next-part` 只能前进到相邻环节或回退 +- 不允许跳过环节（如 flow-design → finish） +- `back-part` 可以回退到任意之前的环节 + +--- + +## 五、数据结构 + +### 5.1 状态文件格式 + +位置：`.aide/flow-status.json` + +``` +FlowStatus: + task_id: str # 任务标识（时间戳） + current_phase: str # 当前环节名 + current_step: int # 当前步骤序号 + started_at: str # 开始时间（ISO格式） + history: list[HistoryEntry] # 历史记录 + +HistoryEntry: + timestamp: str # 时间戳 + action: str # 操作类型（start/next-step/next-part/...） + phase: str # 环节名 + step: int # 步骤序号 + summary: str # 总结/原因 + git_commit: str | None # git commit hash +``` + +### 5.2 方法签名原型 + +``` +class FlowTracker: + root: Path + status_path: Path # .aide/flow-status.json + + start(phase: str, summary: str) -> bool + # 开始新任务 + + next_step(summary: str) -> bool + # 记录步骤前进 + + back_step(reason: str) -> bool + # 记录步骤回退 + + next_part(phase: str, summary: str) -> bool + # 进入下一环节 + + back_part(phase: str, reason: str) -> bool + # 回退到之前环节 + + issue(description: str) -> bool + # 记录一般问题 + + error(description: str) -> bool + # 记录严重错误 + + _load_status() -> FlowStatus | None + # 加载状态文件 + + _save_status(status: FlowStatus) -> None + # 保存状态文件 + + _validate_transition(from_phase: str, to_phase: str) -> bool + # 校验环节跳转 + + _git_commit(message: str) -> str | None + # 执行 git add + commit，返回 commit hash + + _run_phase_hooks(phase: str, entering: bool) -> None + # 执行环节特定行为 +``` + +### 5.3 Git 集成 + +``` +class GitIntegration: + root: Path + + add_all() -> bool + # git add . + + commit(message: str) -> str | None + # git commit -m "..."，返回 commit hash + + get_status() -> str + # git status -sb +``` + +### 5.4 流程校验 + +``` +class FlowValidator: + PHASE_ORDER: list[str] # 环节顺序定义 + VALID_TRANSITIONS: dict # 有效跳转映射 + + validate_start(phase: str) -> bool + # 校验 start 操作 + + validate_next_part(from_phase: str, to_phase: str) -> bool + # 校验 next-part 操作 + + validate_back_part(from_phase: str, to_phase: str) -> bool + # 校验 back-part 操作 +``` + +--- + +## 六、环节特定行为 + +| 触发时机 | 行为 | +|----------|------| +| 离开 flow-design | 校验 PlantUML 语法，生成 PNG | +| 进入 docs | 输出提示：请更新 CHANGELOG | +| 离开 docs | 校验 CHANGELOG 是否已更新 | + +--- + +## 七、依赖 + +| 依赖项 | 类型 | 说明 | +|--------|------|------| +| ConfigManager | 内部模块 | 读取配置 | +| output | 内部模块 | 输出格式化 | +| git | 外部工具 | 版本控制 | +| plantuml | 外部工具 | 流程图生成（可选） | + +--- + +## 八、被依赖 + +| 依赖方 | 说明 | +|--------|------| +| /aide:prep | 调用 flow start、next-step | +| /aide:exec | 调用 flow next-part、next-step、issue、error | + +--- + +## 九、修改指南 + +### 9.1 修改环节定义 + +1. 更新本文档的流程校验规则图 +2. 修改 `FlowValidator.PHASE_ORDER` 和 `VALID_TRANSITIONS` +3. 同步更新 [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md) + +### 9.2 添加环节特定行为 + +1. 在本文档添加行为说明 +2. 在 `_run_phase_hooks()` 中实现 +3. 更新相关 Command 设计文档 + +### 9.3 修改状态文件格式 + +1. 更新本文档的数据结构章节 +2. 修改代码实现 +3. 同步更新 [数据格式文档](../formats/data.md) + +--- + +## 十、相关文档 + +- [program 导览](../README.md) +- [数据格式文档](../formats/data.md) +- [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md) +- [/aide:prep 命令设计](../../../aide-marketplace/aide-plugin/docs/commands/prep.md) +- [/aide:exec 命令设计](../../../aide-marketplace/aide-plugin/docs/commands/exec.md) diff --git a/aide-program/docs/commands/init.md b/aide-program/docs/commands/init.md new file mode 100644 index 0000000..37d9c5e --- /dev/null +++ b/aide-program/docs/commands/init.md @@ -0,0 +1,221 @@ +# aide init 子命令设计文档 + +## 一、背景 + +### 1.1 解决的问题 + +| 问题 | 影响 | +|------|------| +| 配置文件缺失 | 其他 aide 命令无法正常工作 | +| 目录结构不存在 | 状态文件、决策记录无处存放 | +| .gitignore 未配置 | aide 数据文件被提交到仓库 | + +### 1.2 设计目标 + +提供**一键初始化**： +- 创建 .aide/ 目录结构 +- 生成默认配置文件 +- 配置 .gitignore + +--- + +## 二、职责 + +### 2.1 做什么 + +1. 创建 `.aide/` 目录 +2. 创建 `.aide/decisions/` 子目录 +3. 创建 `.aide/logs/` 子目录 +4. 生成默认 `config.toml` +5. 检查并更新 `.gitignore` + +### 2.2 不做什么 + +- 不检测环境（那是 env 的职责） +- 不执行业务逻辑 +- 不修改业务代码 + +--- + +## 三、接口规格 + +### 3.1 命令语法 + +``` +aide init +``` + +### 3.2 参数 + +无参数。 + +### 3.3 输出 + +**首次初始化**： +``` +✓ 已创建默认配置 .aide/config.toml +✓ 初始化完成，.aide/ 与默认配置已准备就绪 +``` + +**已存在时**： +``` +✓ 初始化完成，.aide/ 与默认配置已准备就绪 +``` + +--- + +## 四、业务流程 + +``` +@startuml +skinparam defaultFontName "PingFang SC" + +start + +:创建 .aide/ 目录; +note right: 如已存在则跳过 + +:创建 .aide/decisions/ 目录; + +:创建 .aide/logs/ 目录; + +if (config.toml 存在?) then (是) + :加载现有配置; +else (否) + :生成默认配置; + :写入 config.toml; + :输出创建提示; +endif + +:检查 .gitignore; +if (.aide/ 已在忽略列表?) then (是) +else (否) + :添加 .aide/ 到 .gitignore; +endif + +:输出初始化完成; + +stop +@enduml +``` + +--- + +## 五、数据结构 + +### 5.1 目录结构 + +``` +.aide/ +├── config.toml # 项目配置 +├── flow-status.json # 当前任务进度（由 flow 创建） +├── decisions/ # 待定项决策记录 +│ └── {timestamp}.json +└── logs/ # 操作日志 +``` + +### 5.2 默认配置内容 + +```toml +# Aide 默认配置（由 aide init 生成） +# runtime: aide 自身运行要求 +# task: 任务文档路径 +# env: 虚拟环境与依赖配置 +# flow: 环节名称列表，供流程校验使用 + +[runtime] +python_min = "3.11" +use_uv = true + +[task] +source = "task-now.md" +spec = "task-spec.md" + +[env] +venv = ".venv" +requirements = "requirements.txt" + +[flow] +phases = ["task-optimize", "flow-design", "impl", "verify", "docs", "finish"] +``` + +### 5.3 方法签名原型 + +``` +class ConfigManager: + root: Path + aide_dir: Path # .aide/ + config_path: Path # .aide/config.toml + decisions_dir: Path # .aide/decisions/ + logs_dir: Path # .aide/logs/ + + ensure_base_dirs() -> None + # 创建基础目录结构 + + ensure_gitignore() -> None + # 确保 .gitignore 包含 .aide/ + + ensure_config() -> dict + # 确保配置文件存在，返回配置内容 + + load_config() -> dict + # 加载配置文件 + + get_value(key: str) -> Any + # 获取配置值（点号分隔的键） + + set_value(key: str, value: Any) -> None + # 设置配置值 +``` + +--- + +## 六、依赖 + +| 依赖项 | 类型 | 说明 | +|--------|------|------| +| output | 内部模块 | 输出格式化 | +| tomllib | 标准库 | TOML 读取 | +| tomli_w | 第三方库 | TOML 写入 | + +--- + +## 七、被依赖 + +| 依赖方 | 说明 | +|--------|------| +| /aide:init | 调用 aide init 初始化配置 | +| aide env ensure | 依赖配置文件存在 | +| aide flow | 依赖目录结构存在 | +| aide decide | 依赖 decisions/ 目录存在 | + +--- + +## 八、修改指南 + +### 8.1 修改默认配置 + +1. 更新本文档的"默认配置内容"章节 +2. 修改 `ConfigManager` 中的 `DEFAULT_CONFIG` +3. 同步更新 [配置格式文档](../formats/config.md) + +### 8.2 修改目录结构 + +1. 更新本文档的"目录结构"章节 +2. 修改 `ensure_base_dirs()` 方法 +3. 同步更新相关文档 + +### 8.3 添加新的初始化步骤 + +1. 在本文档添加步骤说明 +2. 在 `ensure_config()` 或新方法中实现 +3. 更新业务流程图 + +--- + +## 九、相关文档 + +- [program 导览](../README.md) +- [配置格式文档](../formats/config.md) +- [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md) +- [/aide:init 命令设计](../../../aide-marketplace/aide-plugin/docs/commands/init.md) diff --git a/aide-program/docs/formats/config.md b/aide-program/docs/formats/config.md new file mode 100644 index 0000000..c15b97c --- /dev/null +++ b/aide-program/docs/formats/config.md @@ -0,0 +1,176 @@ +# 配置文件格式规范 + +## 一、概述 + +aide 使用 TOML 格式的配置文件，位于 `.aide/config.toml`。 + +配置文件采用**自文档化**设计，包含详细注释说明各字段用途。 + +--- + +## 二、文件位置 + +``` +.aide/ +└── config.toml +``` + +--- + +## 三、完整配置结构 + +```toml +# Aide 默认配置（由 aide init 生成） + +# runtime: aide 自身运行要求 +[runtime] +python_min = "3.11" # Python 最低版本要求 +use_uv = true # 是否使用 uv 管理依赖 + +# task: 任务文档路径 +[task] +source = "task-now.md" # 任务原文档默认路径 +spec = "task-spec.md" # 任务细则文档默认路径 + +# env: 虚拟环境与依赖配置 +[env] +venv = ".venv" # 虚拟环境路径 +requirements = "requirements.txt" # 依赖文件路径 + +# flow: 流程配置 +[flow] +phases = ["task-optimize", "flow-design", "impl", "verify", "docs", "finish"] +``` + +--- + +## 四、字段详解 + +### 4.1 [runtime] 运行时配置 + +| 字段 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `python_min` | string | `"3.11"` | Python 最低版本要求 | +| `use_uv` | bool | `true` | 是否使用 uv 管理虚拟环境和依赖 | + +**使用场景**： +- `aide env ensure --runtime` 使用硬编码的 `"3.11"` +- `aide env ensure` 读取 `python_min` 进行检查 + +### 4.2 [task] 任务文档配置 + +| 字段 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `source` | string | `"task-now.md"` | 任务原文档默认路径 | +| `spec` | string | `"task-spec.md"` | 任务细则文档默认路径 | + +**使用场景**： +- `/aide:prep` 未传参数时，使用 `source` 作为默认路径 +- `/aide:exec` 未传参数时，使用 `spec` 作为默认路径 +- `aide env ensure` 输出这两个路径供 LLM 记录 + +### 4.3 [env] 环境配置 + +| 字段 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `venv` | string | `".venv"` | 虚拟环境目录路径 | +| `requirements` | string | `"requirements.txt"` | 依赖文件路径 | + +**使用场景**： +- `aide env ensure` 检查/创建虚拟环境 +- `aide env ensure` 安装依赖 + +### 4.4 [flow] 流程配置 + +| 字段 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `phases` | array | `["task-optimize", "flow-design", "impl", "verify", "docs", "finish"]` | 环节名称列表 | + +**使用场景**： +- `aide flow` 校验环节跳转合法性 +- 定义有效的环节名称 + +--- + +## 五、配置读写接口 + +### 5.1 读取配置 + +```bash +aide config get <key> +``` + +**示例**： +```bash +aide config get task.source +# 输出: → task.source = 'task-now.md' + +aide config get flow.phases +# 输出: → flow.phases = ['task-optimize', 'flow-design', 'impl', 'verify', 'docs', 'finish'] + +aide config get runtime.python_min +# 输出: → runtime.python_min = '3.11' +``` + +### 5.2 设置配置 + +```bash +aide config set <key> <value> +``` + +**示例**： +```bash +aide config set task.source "my-task.md" +# 输出: ✓ 已更新 task.source = 'my-task.md' + +aide config set runtime.python_min "3.12" +# 输出: ✓ 已更新 runtime.python_min = '3.12' +``` + +**值类型自动解析**： +- `true` / `false` → bool +- 纯数字 → int +- 带小数点的数字 → float +- 其他 → string + +--- + +## 六、配置访问规则 + +### 6.1 LLM 不直接读取配置文件 + +**原则**：LLM 不允许直接读取 `.aide/config.toml` 文件内容，避免污染上下文。 + +**正确做法**：通过 `aide config get <key>` 读取需要的配置值。 + +### 6.2 配置缺失处理 + +- 配置文件不存在时，`aide config get` 输出警告并返回空 +- 配置项不存在时，`aide config get` 输出警告 +- 建议先执行 `aide init` 确保配置文件存在 + +--- + +## 七、扩展配置 + +### 7.1 添加新配置项 + +1. 在本文档添加字段说明 +2. 更新 `ConfigManager` 中的 `DEFAULT_CONFIG` +3. 在相关代码中读取新配置 +4. 更新相关设计文档 + +### 7.2 配置项命名规范 + +- 使用小写字母和下划线 +- 使用点号分隔层级：`section.key` +- 保持语义清晰 + +--- + +## 八、相关文档 + +- [program 导览](../README.md) +- [aide init 设计](../commands/init.md) +- [aide env 设计](../commands/env.md) +- [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md) diff --git a/aide-program/docs/formats/data.md b/aide-program/docs/formats/data.md new file mode 100644 index 0000000..85ff856 --- /dev/null +++ b/aide-program/docs/formats/data.md @@ -0,0 +1,360 @@ +# 数据格式规范 + +## 一、概述 + +本文档定义 aide 系统中使用的各种数据格式，包括： +- 待定项数据格式（aide decide） +- 流程状态格式（aide flow） +- 决策记录格式 + +--- + +## 二、待定项数据格式 + +### 2.1 输入格式（LLM → aide decide） + +LLM 调用 `aide decide '<json>'` 时传入的数据格式。 + +``` +DecideInput: + task: string # 任务简述 + source: string # 来源文档路径 + items: DecideItem[] # 待定项列表 + +DecideItem: + id: number # 待定项 ID（唯一标识） + title: string # 问题标题 + location?: Location # 原文位置（可选） + context?: string # 详细说明（可选） + options: Option[] # 选项列表（至少2个） + recommend?: string # 推荐选项的 value（可选） + +Location: + file: string # 文件路径 + start: number # 起始行号 + end: number # 结束行号 + +Option: + value: string # 选项标识（用于返回结果） + label: string # 选项描述（显示给用户） + score?: number # 评分 0-100（可选） + pros?: string[] # 优点列表（可选） + cons?: string[] # 缺点列表（可选） +``` + +**示例**： + +```json +{ + "task": "实现用户认证模块", + "source": "task-now.md", + "items": [ + { + "id": 1, + "title": "认证方式选择", + "location": { + "file": "task-now.md", + "start": 5, + "end": 7 + }, + "context": "任务描述中未明确指定认证方式，需要确认", + "options": [ + { + "value": "jwt", + "label": "JWT Token 认证", + "score": 85, + "pros": ["无状态", "易于扩展", "跨域友好"], + "cons": ["Token 无法主动失效", "需要处理刷新"] + }, + { + "value": "session", + "label": "Session 认证", + "score": 70, + "pros": ["实现简单", "可主动失效"], + "cons": ["需要存储", "扩展性差"] + } + ], + "recommend": "jwt" + }, + { + "id": 2, + "title": "密码加密算法", + "context": "选择密码存储的加密算法", + "options": [ + { + "value": "bcrypt", + "label": "bcrypt", + "score": 90, + "pros": ["安全性高", "自带盐值"], + "cons": ["计算较慢"] + }, + { + "value": "argon2", + "label": "Argon2", + "score": 95, + "pros": ["最新标准", "抗GPU攻击"], + "cons": ["库支持较少"] + } + ], + "recommend": "bcrypt" + } + ] +} +``` + +### 2.2 输出格式（aide decide result → LLM） + +LLM 调用 `aide decide result` 时返回的数据格式。 + +``` +DecideOutput: + decisions: Decision[] # 决策列表 + +Decision: + id: number # 待定项 ID + chosen: string # 选中的选项 value + note?: string # 用户备注（可选，仅在用户填写时出现） +``` + +**示例**： + +```json +{ + "decisions": [ + {"id": 1, "chosen": "jwt"}, + {"id": 2, "chosen": "bcrypt", "note": "团队更熟悉 bcrypt"} + ] +} +``` + +--- + +## 三、流程状态格式 + +### 3.1 状态文件格式 + +位置：`.aide/flow-status.json` + +``` +FlowStatus: + task_id: string # 任务标识（时间戳格式） + current_phase: string # 当前环节名 + current_step: number # 当前步骤序号 + started_at: string # 开始时间（ISO 8601 格式） + history: HistoryEntry[] # 历史记录 + +HistoryEntry: + timestamp: string # 时间戳（ISO 8601 格式） + action: string # 操作类型 + phase: string # 环节名 + step: number # 步骤序号 + summary: string # 总结/原因 + git_commit?: string # git commit hash（可选） +``` + +**操作类型（action）**： +- `start` - 开始任务 +- `next-step` - 步骤前进 +- `back-step` - 步骤回退 +- `next-part` - 环节前进 +- `back-part` - 环节回退 +- `issue` - 记录问题 +- `error` - 记录错误 + +**示例**： + +```json +{ + "task_id": "2025-01-15T10-30-00", + "current_phase": "impl", + "current_step": 5, + "started_at": "2025-01-15T10:30:00+08:00", + "history": [ + { + "timestamp": "2025-01-15T10:30:00+08:00", + "action": "start", + "phase": "flow-design", + "step": 1, + "summary": "开始任务: 实现用户认证模块", + "git_commit": "a1b2c3d" + }, + { + "timestamp": "2025-01-15T10:45:00+08:00", + "action": "next-step", + "phase": "flow-design", + "step": 2, + "summary": "流程图设计完成", + "git_commit": "e4f5g6h" + }, + { + "timestamp": "2025-01-15T11:00:00+08:00", + "action": "next-part", + "phase": "impl", + "step": 3, + "summary": "流程设计完成，开始实现", + "git_commit": "i7j8k9l" + }, + { + "timestamp": "2025-01-15T11:30:00+08:00", + "action": "issue", + "phase": "impl", + "step": 4, + "summary": "测试覆盖率较低，后续需要补充", + "git_commit": "m0n1o2p" + }, + { + "timestamp": "2025-01-15T12:00:00+08:00", + "action": "next-step", + "phase": "impl", + "step": 5, + "summary": "完成用户模型定义", + "git_commit": "q3r4s5t" + } + ] +} +``` + +--- + +## 四、决策记录格式 + +### 4.1 存储位置 + +``` +.aide/ +└── decisions/ + ├── pending.json # 当前待处理的待定项 + └── 2025-01-15T10-30-00.json # 历史决策记录 +``` + +### 4.2 待处理文件格式 + +位置：`.aide/decisions/pending.json` + +内容：与输入格式相同（DecideInput） + +### 4.3 历史记录格式 + +位置：`.aide/decisions/{timestamp}.json` + +``` +DecisionRecord: + input: DecideInput # 原始输入 + output: DecideOutput # 决策结果 + completed_at: string # 完成时间（ISO 8601 格式） +``` + +**示例**： + +```json +{ + "input": { + "task": "实现用户认证模块", + "source": "task-now.md", + "items": [...] + }, + "output": { + "decisions": [ + {"id": 1, "chosen": "jwt"}, + {"id": 2, "chosen": "bcrypt", "note": "团队更熟悉 bcrypt"} + ] + }, + "completed_at": "2025-01-15T10:35:00+08:00" +} +``` + +--- + +## 五、Git 提交信息格式 + +### 5.1 自动提交格式 + +aide flow 自动生成的提交信息格式： + +``` +[aide] <环节>: <总结> +``` + +**示例**： +``` +[aide] flow-design: 开始任务: 实现用户认证模块 +[aide] flow-design: 流程图设计完成 +[aide] impl: 流程设计完成，开始实现 +[aide] impl: 完成用户模型定义 +[aide] verify: 验证通过 +[aide] docs: 更新 CHANGELOG +[aide] finish: 任务完成 +``` + +### 5.2 问题/错误记录 + +``` +[aide] <环节> issue: <描述> +[aide] <环节> error: <描述> +``` + +### 5.3 回退记录 + +``` +[aide] <环节> back-step: <原因> +[aide] <环节> back-part: <原因> +``` + +--- + +## 六、时间格式 + +所有时间字段使用 **ISO 8601** 格式： + +``` +YYYY-MM-DDTHH:mm:ss+HH:00 +``` + +**示例**： +``` +2025-01-15T10:30:00+08:00 +``` + +文件名中的时间戳使用简化格式（避免特殊字符）： + +``` +YYYY-MM-DDTHH-mm-ss +``` + +**示例**： +``` +2025-01-15T10-30-00 +``` + +--- + +## 七、修改指南 + +### 7.1 修改待定项格式 + +1. 更新本文档的"待定项数据格式"章节 +2. 修改 `aide/decide/` 相关代码 +3. 同步更新 [aide decide 设计](../commands/decide.md) +4. 同步更新 [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md) + +### 7.2 修改流程状态格式 + +1. 更新本文档的"流程状态格式"章节 +2. 修改 `aide/flow/` 相关代码 +3. 同步更新 [aide flow 设计](../commands/flow.md) + +### 7.3 添加新的数据格式 + +1. 在本文档添加新章节 +2. 定义数据结构 +3. 提供示例 +4. 更新相关设计文档 + +--- + +## 八、相关文档 + +- [program 导览](../README.md) +- [aide flow 设计](../commands/flow.md) +- [aide decide 设计](../commands/decide.md) +- [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md) diff --git a/discuss/05-文档拆分方案.md b/discuss/05-文档拆分方案.md new file mode 100644 index 0000000..c66ddab --- /dev/null +++ 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/ 目录创建回复文档。 diff --git a/discuss/06-文档拆分完成报告.md b/discuss/06-文档拆分完成报告.md new file mode 100644 index 0000000..100bd93 --- /dev/null +++ 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 看 diff --git a/docs/aide-overview.md b/docs/aide-overview.md new file mode 100644 index 0000000..2e34e68 --- /dev/null +++ b/docs/aide-overview.md @@ -0,0 +1,121 @@ +# Aide 系统概述 + +## 一、系统简介 + +Aide 是一套面向 Claude Code 的工作流辅助体系，旨在解决 AI 辅助开发中的信息过载、操作不确定性和流程耦合问题。 + +系统通过 **Command + Skill + 专用程序** 的架构，将原本堆积在 CLAUDE.md 中的规则和流程转化为按需触发的模块化单元，实现： + +- **CLAUDE.md 精简化**：仅保留项目结构说明，不再堆积规则和流程 +- **流程按需触发**：通过 Command 主动触发流程指导 +- **操作确定性封装**：通过 Skill + 程序简化操作，减少不确定性 + +--- + +## 二、核心设计原则 + +| 原则 | 说明 | +|------|------| +| **渐进式披露** | 信息按需加载，用户/LLM 主动调用时才加载相关指引 | +| **确定性封装** | 将可变过程转化为固定接口，只暴露程序和参数 | +| **信息隔离** | LLM 只传核心语义数据，程序负责格式化和渲染 | +| **核心与形式分离** | 核心信息（分析、决策）由 LLM 发挥，形式问题（状态记录、环境配置）由程序处理 | + +--- + +## 三、系统架构 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 用户 │ +└─────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ aide-plugin │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ +│ │ /aide:init │ │ /aide:prep │ │ /aide:exec │ Commands │ +│ └─────────────┘ └─────────────┘ └─────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────┐ │ +│ │ aide skill │ Skill │ +│ │ (aide 命令使用指南) │ │ +│ └─────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────┘ + │ + ▼ 调用 +┌─────────────────────────────────────────────────────────────┐ +│ aide-program │ +│ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │ +│ │ init │ │ env │ │ flow │ │ decide │ 子命令 │ +│ └────────┘ └────────┘ └────────┘ └────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────┐ │ +│ │ .aide/ 数据目录 │ │ +│ │ config.toml | flow-status.json | decisions/ │ │ +│ └─────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────┘ +``` + +**组件关系**： +- **Commands**：定义流程（做什么、按什么顺序做），指导 LLM 的思考方向 +- **Skill**：定义工具使用方法（怎么调用 aide 程序），纯工具说明 +- **Program**：执行具体操作（环境检测、进度追踪、待定项处理），返回精简结果 + +--- + +## 四、子区块索引 + +### 4.1 aide-plugin 区块 + +| 文档 | 位置 | 说明 | +|------|------|------| +| **导览** | [aide-plugin/docs/README.md](../aide-marketplace/aide-plugin/docs/README.md) | plugin 整体介绍和索引 | +| init 命令 | [aide-plugin/docs/commands/init.md](../aide-marketplace/aide-plugin/docs/commands/init.md) | 项目认知与环境初始化 | +| prep 命令 | [aide-plugin/docs/commands/prep.md](../aide-marketplace/aide-plugin/docs/commands/prep.md) | 任务准备流程 | +| exec 命令 | [aide-plugin/docs/commands/exec.md](../aide-marketplace/aide-plugin/docs/commands/exec.md) | 任务执行流程 | +| aide skill | [aide-plugin/docs/skill/aide.md](../aide-marketplace/aide-plugin/docs/skill/aide.md) | aide 命令使用指南 | + +### 4.2 aide-program 区块 + +| 文档 | 位置 | 说明 | +|------|------|------| +| **导览** | [aide-program/docs/README.md](../aide-program/docs/README.md) | program 整体介绍和索引 | +| env 子命令 | [aide-program/docs/commands/env.md](../aide-program/docs/commands/env.md) | 环境检测与修复 | +| flow 子命令 | [aide-program/docs/commands/flow.md](../aide-program/docs/commands/flow.md) | 进度追踪与 git 集成 | +| decide 子命令 | [aide-program/docs/commands/decide.md](../aide-program/docs/commands/decide.md) | 待定项 Web 确认 | +| init 子命令 | [aide-program/docs/commands/init.md](../aide-program/docs/commands/init.md) | 初始化 .aide 目录 | +| 配置格式 | [aide-program/docs/formats/config.md](../aide-program/docs/formats/config.md) | config.toml 规范 | +| 数据格式 | [aide-program/docs/formats/data.md](../aide-program/docs/formats/data.md) | 待定项、流程状态等格式 | + +--- + +## 五、快速导航 + +### 想了解/修改 Commands 或 Skill + +→ 阅读 [aide-plugin 导览](../aide-marketplace/aide-plugin/docs/README.md) + +### 想了解/修改 aide 程序 + +→ 阅读 [aide-program 导览](../aide-program/docs/README.md) + +### 想了解完整工作流程 + +``` +/aide:init → /aide:prep → /aide:exec + │ │ │ + ▼ ▼ ▼ +项目认知 任务准备 任务执行 +环境检测 任务分析 流程设计 + 任务优化 迭代实现 + 待定项处理 验证交付 + 生成细则 文档更新 +``` + +--- + +## 六、版本信息 + +- 当前版本：1.0.0 +- 文档拆分自：aide-requirements.md diff --git a/reply/re-04.md b/reply/re-04.md new file mode 100644 index 0000000..bab0910 --- /dev/null +++ b/reply/re-04.md @@ -0,0 +1,6 @@ +五、待确认事项 + +1. 总导览放在当前项目的docs目录下 +2. 原aide-requirements.md我会自行处理，你不用帮我做删除文档的事 +3. commands和skills的设计文档（对人）可以和目标本体（对LLM）有重叠，但是aide program的设计文档，不允许在设计文档中直接给出代码实现、代码片段，最多只允许出现流程和结构：plantuml流程图用于表示业务、逻辑流，和伪代码表示数据结构、类型、方法签名原型 +4. aide-program/docs/commands/ 下的文档用 "env.md" 即可 \ No newline at end of file