sayurinana/agent-aide
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

✨ feat: 完成文档拆分

Browse Source
This commit is contained in:
sayurinana(vm)
2025-12-13 22:22:01 +08:00
parent f535707657
commit 4cacd128ab
16 changed files with 3983 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

156
aide-marketplace/aide-plugin/docs/README.md Normal file
View File

@@ -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)

324
aide-marketplace/aide-plugin/docs/commands/exec.md Normal file
View File

@@ -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)

235
aide-marketplace/aide-plugin/docs/commands/init.md Normal file
View File

@@ -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)

289
aide-marketplace/aide-plugin/docs/commands/prep.md Normal file
View File

@@ -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 '<json>';
:告知用户访问链接;
: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 '<json>'` 启动 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 '<json数据>'
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)

415
aide-marketplace/aide-plugin/docs/skill/aide.md Normal file
View File

@@ -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 '<json数据>'
```
**输入格式**：见 [数据格式文档](../../../../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 <key>
```
**参数**：
- `<key>`：使用点号分隔的键名，如 `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 <key> <value>
```
**示例**：
```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)