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

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)