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)

208
aide-program/docs/README.md Normal file
View File

@@ -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 <command> [args]
# Windows
aide-program\aide.bat <command> [args]
```
### 6.2 通过 Python 模块
```bash
# 需要先激活虚拟环境或设置 PYTHONPATH
python -m aide <command> [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)

353
aide-program/docs/commands/decide.md Normal file
View File

@@ -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数据>'
```
**输入**：待定项 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 '<json>'
```
---
## 四、业务流程
### 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 '<json>'
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 待定项确认 │
│ 任务: <task> │
├─────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────┐ │
│ │ 1. <title> │ │
│ │ <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)

257
aide-program/docs/commands/env.md Normal file
View File

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

387
aide-program/docs/commands/flow.md Normal file
View File

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

221
aide-program/docs/commands/init.md Normal file
View File

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

176
aide-program/docs/formats/config.md Normal file
View File

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

360
aide-program/docs/formats/data.md Normal file
View File

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

293
discuss/05-文档拆分方案.md Normal file
View File

@@ -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/ 目录创建回复文档。

182
discuss/06-文档拆分完成报告.md Normal file
View File

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

121
docs/aide-overview.md Normal file
View File

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

6
reply/re-04.md Normal file
View File

@@ -0,0 +1,6 @@
五、待确认事项
1. 总导览放在当前项目的docs目录下
2. 原aide-requirements.md我会自行处理，你不用帮我做删除文档的事
3. commands和skills的设计文档（对人）可以和目标本体（对LLM）有重叠，但是aide program的设计文档，不允许在设计文档中直接给出代码实现、代码片段，最多只允许出现流程和结构：plantuml流程图用于表示业务、逻辑流，和伪代码表示数据结构、类型、方法签名原型
4. aide-program/docs/commands/ 下的文档用 "env.md" 即可