417 lines
11 KiB
Markdown
Executable File
417 lines
11 KiB
Markdown
Executable File
# Aide 系统需求规格
|
||
|
||
## 一、项目背景
|
||
|
||
### 1.1 现状问题
|
||
|
||
原有 `ai-agent-memory/` 体系存在以下问题：
|
||
|
||
| 问题类型 | 具体表现 |
|
||
|---------|---------|
|
||
| 信息过载 | CLAUDE.md 包含完整流程规范，每次对话都需加载 |
|
||
| 操作繁琐 | CSV 状态需手动编辑、PlantUML 命令冗长、Git 多步操作 |
|
||
| 输出冗余 | 命令执行输出大量日志，无论成功失败 |
|
||
| 流程耦合 | AB 部分虽拆分但仍需手动切换和阅读大量文档 |
|
||
|
||
### 1.2 转型目标
|
||
|
||
将原有内容体系转化为 Command + Skill 体系：
|
||
|
||
- **CLAUDE.md 精简化**：仅保留项目文件结构说明，不再指导规则和流程
|
||
- **流程按需触发**：通过 Command 主动触发流程指导和规则启示
|
||
- **操作确定性封装**：通过 Skill + 定制脚本简化操作，减少不确定性
|
||
|
||
---
|
||
|
||
## 二、核心设计原则
|
||
|
||
### 2.1 渐进式披露
|
||
|
||
- 按需调用、触发
|
||
- 不在 CLAUDE.md 中堆积所有规则
|
||
- 用户/LLM 主动调用时才加载相关指引
|
||
|
||
### 2.2 确定性封装
|
||
|
||
- 将可变过程转化为固定接口
|
||
- 只暴露脚本程序和参数信息
|
||
- 内部处理流程固定化，减少多余输出
|
||
|
||
### 2.3 信息隔离
|
||
|
||
- LLM 只传核心语义数据
|
||
- 程序负责格式化、渲染、美化
|
||
- 返回结果极简，只含决策所需信息
|
||
|
||
### 2.4 核心与形式分离
|
||
|
||
| 类型 | 定义 | 处理方式 |
|
||
|------|------|----------|
|
||
| 核心信息 | 分析思考、优化思考、业务决策 | LLM 自由发挥，不受限制 |
|
||
| 形式问题 | 待定项呈现、状态记录、环境配置 | 程序封装，减少 token 污染 |
|
||
|
||
---
|
||
|
||
## 三、组件职责定义
|
||
|
||
### 3.1 Command（命令）
|
||
|
||
**本质**：对 LLM 的要求和规则
|
||
|
||
**内容焦点**：
|
||
- 思考方法论：怎么分析、怎么优化、怎么执行
|
||
- 流程指导：阶段划分、核心必做、质量要求
|
||
- 决策边界：哪些由 LLM 自主完成，哪些需要用户确认
|
||
|
||
**设计要求**：
|
||
- 聚焦核心思考，不涉及工具调用细节
|
||
- 指导方向而非限制形式
|
||
- 结果输出不受格式约束，让 LLM 竭尽全力发挥
|
||
|
||
### 3.2 Skill（技能）
|
||
|
||
**本质**：告诉 LLM 有什么工具可用
|
||
|
||
**内容焦点**：
|
||
- 工具使用说明：命令、参数、输出格式
|
||
- 调用示例：典型场景的命令示例
|
||
- 输出解读：各种输出前缀的含义
|
||
|
||
**设计要求**：
|
||
- 纯工具说明，不涉及流程指导
|
||
- 精简明确，便于快速查阅
|
||
- 封装形式问题，减少 LLM 认知负担
|
||
|
||
---
|
||
|
||
## 四、命令清单
|
||
|
||
### 4.1 /aide:init - 认知初始化
|
||
|
||
**触发时机**：进入项目开始工作时
|
||
|
||
**职责**：
|
||
1. 介绍 aide 流程体系
|
||
2. 列出可用能力（Skills）
|
||
3. 说明环境和版本控制约定
|
||
|
||
**特点**：
|
||
- 不执行实际操作
|
||
- 提供认知框架
|
||
|
||
### 4.2 /aide:prep - 任务准备
|
||
|
||
**触发时机**：准备开始新任务时
|
||
|
||
**职责**：
|
||
1. 任务分析（理解目标、识别复杂度、分析环境）
|
||
2. 任务优化（准确性、简洁性、可执行性）
|
||
3. 待定项处理（通过 aide 程序化呈现）
|
||
4. 结果生成（LLM 自由发挥，产出 task-spec.md）
|
||
|
||
**核心原则**：
|
||
- 分析和优化阶段：指导 LLM 思考方向，让其竭尽全力发挥
|
||
- 待定项处理：程序化呈现，减少 token 污染
|
||
- 结果生成：不受格式限制，由用户直接审阅
|
||
|
||
**运行特点**：
|
||
- 轻量化：不创建工作目录、不记录状态、不 git 提交
|
||
|
||
### 4.3 /aide:exec - 任务执行
|
||
|
||
**触发时机**：任务准备完成，开始执行时
|
||
|
||
**职责**：
|
||
1. 流程规划（理解细则、制定计划、环境准备）
|
||
2. 迭代实现（按计划执行、状态同步、阻塞处理）
|
||
3. 验证交付（对照标准、功能验证）
|
||
4. 文档收尾（变更记录、版本发布）
|
||
|
||
**核心原则**：
|
||
- 业务代码编写：LLM 自由发挥，不加程序约束
|
||
- 状态管理、版本控制：通过 aide 程序处理，避免信息污染
|
||
|
||
---
|
||
|
||
## 五、技能清单
|
||
|
||
### 5.1 aide-env - 环境管理
|
||
|
||
**用途**：检测和修复项目开发环境
|
||
|
||
**核心命令**：
|
||
- `aide env check` - 检测环境（只读）
|
||
- `aide env ensure` - 检测并修复
|
||
|
||
**设计要点**：
|
||
- 成功时输出极简：`✓ 环境就绪 (python:3.12)`
|
||
- 自动修复小问题时简短提示
|
||
- 仅无法修复时才需要 LLM 关注
|
||
|
||
### 5.2 aide-undetermined - 待定项处理
|
||
|
||
**用途**：程序化呈现待定项，获取用户确认
|
||
|
||
**核心命令**：
|
||
- `aide undetermined add '<json>'` - 添加待定项
|
||
- `aide undetermined confirm` - 生成确认报告（给用户）
|
||
- `aide undetermined result` - 获取结果（给 LLM）
|
||
|
||
**设计要点**：
|
||
- LLM 传入精简 JSON 数据
|
||
- 程序渲染美化界面给用户
|
||
- 返回精简决策结果给 LLM
|
||
|
||
### 5.3 aide-workspace - 工作目录管理
|
||
|
||
**用途**：管理任务工作目录
|
||
|
||
**核心命令**：
|
||
- `aide workspace init <name>` - 创建工作目录
|
||
- `aide workspace clean --keep=N` - 清理旧目录
|
||
|
||
### 5.4 aide-progress - 进度管理
|
||
|
||
**用途**：记录任务执行状态
|
||
|
||
**核心命令**：
|
||
- `aide progress init <name>` - 初始化状态
|
||
- `aide progress update <phase> <status>` - 更新状态
|
||
|
||
**设计要点**：
|
||
- 替代手动编辑 CSV
|
||
- 提供动态反馈和步骤引导
|
||
- 避免 LLM "跑飞"
|
||
|
||
### 5.5 aide-version - 版本控制
|
||
|
||
**用途**：管理 CHANGELOG 和 Git 操作
|
||
|
||
**核心命令**：
|
||
- `aide version add <type> "<desc>"` - 添加变更
|
||
- `aide version commit "<msg>"` - Git 提交
|
||
- `aide version release [level]` - 发布版本
|
||
|
||
**设计要点**：
|
||
- 封装 Git 操作，减少情况分析复杂度
|
||
- 通过有限参数控制不同需求
|
||
|
||
### 5.6 aide-build - 构建工具
|
||
|
||
**用途**：编译 PlantUML 等
|
||
|
||
**核心命令**：
|
||
- `aide build plantuml <src>` - 编译
|
||
- `aide build plantuml <src> -c` - 语法检查
|
||
|
||
**设计要点**：
|
||
- 集成语法检查、编译、简要输出
|
||
- 替代冗长的 java -jar 命令
|
||
|
||
---
|
||
|
||
## 六、信息流设计
|
||
|
||
### 6.1 待定项处理流程
|
||
|
||
```
|
||
LLM 程序 用户
|
||
│ │ │
|
||
│ JSON (精简数据) │ │
|
||
│─────────────────────→│ │
|
||
│ │ 渲染美化界面 │
|
||
│ │─────────────────────→│
|
||
│ │ │
|
||
│ │ 用户选择 │
|
||
│ │←─────────────────────│
|
||
│ JSON (决策结果) │ │
|
||
│←─────────────────────│ │
|
||
```
|
||
|
||
### 6.2 输出精简原则
|
||
|
||
| 场景 | 输出策略 |
|
||
|------|----------|
|
||
| 成功 | 极简确认：`✓ 操作完成` |
|
||
| 自动修复 | 简短提示：`✓ 已修复: xxx` |
|
||
| 警告 | 告知但可继续：`⚠ 警告内容` |
|
||
| 失败 | 详细原因：`✗ 失败原因及建议` |
|
||
|
||
---
|
||
|
||
## 七、LLM 自由发挥边界
|
||
|
||
### 7.1 需要程序约束的场景
|
||
|
||
- 环境检测与修复
|
||
- 待定项呈现与确认
|
||
- 状态记录与更新
|
||
- 版本控制操作
|
||
- 构建工具调用
|
||
|
||
### 7.2 不需要程序约束的场景
|
||
|
||
- 任务分析思考
|
||
- 任务优化思考
|
||
- 业务决策判断
|
||
- 任务细则编写（task-spec.md）
|
||
- 业务代码编写
|
||
- 结果文档产出
|
||
|
||
---
|
||
|
||
## 八、数据格式规范
|
||
|
||
### 8.1 待定项数据格式
|
||
|
||
**输入格式（LLM → 程序）**：
|
||
|
||
```json
|
||
{
|
||
"items": [
|
||
{
|
||
"id": "唯一标识符",
|
||
"question": "问题标题",
|
||
"description": "详细说明（可选）",
|
||
"options": [
|
||
{"value": "程序值", "label": "显示文本", "score": 0-100}
|
||
],
|
||
"recommend": "推荐选项的 value",
|
||
"reason": "推荐理由"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**输出格式（程序 → LLM）**：
|
||
|
||
```json
|
||
{
|
||
"decisions": [
|
||
{"id": "标识符", "chosen": "选择的 value", "custom": "自定义内容或 null"}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 8.2 输出前缀规范
|
||
|
||
| 前缀 | 函数 | 用途 |
|
||
|------|------|------|
|
||
| ✓ | `ok` | 成功 |
|
||
| ⚠ | `warn` | 警告（可继续） |
|
||
| ✗ | `err` | 失败 |
|
||
| → | `info` | 进行中 |
|
||
| [n/m] | `step` | 步骤进度 |
|
||
|
||
### 8.3 配置文件 aide.toml
|
||
|
||
```toml
|
||
[env]
|
||
modules = ["python", "uv"]
|
||
|
||
[env.python]
|
||
version = ">=3.10"
|
||
venv = ".venv"
|
||
requirements = "requirements.txt"
|
||
|
||
[workspace]
|
||
output = "ai-agent-output"
|
||
format = "{timestamp}_{name}"
|
||
|
||
[progress]
|
||
phases = ["规划", "实现", "验证", "文档", "收尾"]
|
||
|
||
[version]
|
||
changelog = "CHANGELOG.md"
|
||
```
|
||
|
||
---
|
||
|
||
## 九、实施结构
|
||
|
||
### 9.1 插件目录结构
|
||
|
||
```
|
||
aide-plugin/
|
||
├── .claude-plugin/
|
||
│ └── plugin.json
|
||
├── commands/
|
||
│ ├── init.md
|
||
│ ├── prep.md
|
||
│ └── exec.md
|
||
└── skills/
|
||
├── aide-env/SKILL.md
|
||
├── aide-undetermined/SKILL.md
|
||
├── aide-workspace/SKILL.md
|
||
├── aide-progress/SKILL.md
|
||
├── aide-version/SKILL.md
|
||
└── aide-build/SKILL.md
|
||
```
|
||
|
||
### 9.2 运行时脚本结构
|
||
|
||
```
|
||
aide/
|
||
├── aide.sh # 统一入口
|
||
├── lib/
|
||
│ ├── output.sh # 输出函数（ok/warn/err/info/step）
|
||
│ └── config.py # 配置读取
|
||
├── env/
|
||
│ └── check.py # 环境检测
|
||
├── undetermined/
|
||
│ └── handler.py # 待定项处理
|
||
├── workspace/
|
||
│ └── manager.py # 工作目录管理
|
||
├── progress/
|
||
│ └── tracker.py # 进度管理
|
||
├── version/
|
||
│ ├── changelog.py # CHANGELOG 管理
|
||
│ └── git.sh # Git 操作
|
||
└── build/
|
||
└── plantuml.sh # PlantUML 编译
|
||
```
|
||
|
||
### 9.3 安装方式
|
||
|
||
```bash
|
||
export AIDE_ROOT="/path/to/aide"
|
||
ln -s "$AIDE_ROOT/aide.sh" ~/.local/bin/aide
|
||
```
|
||
|
||
---
|
||
|
||
## 十、实施检查清单
|
||
|
||
### 10.1 插件部分
|
||
|
||
- [ ] plugin.json 元数据
|
||
- [ ] commands/init.md - 认知初始化
|
||
- [ ] commands/prep.md - 任务准备方法论
|
||
- [ ] commands/exec.md - 任务执行方法论
|
||
- [ ] skills/aide-env/SKILL.md
|
||
- [ ] skills/aide-undetermined/SKILL.md
|
||
- [ ] skills/aide-workspace/SKILL.md
|
||
- [ ] skills/aide-progress/SKILL.md
|
||
- [ ] skills/aide-version/SKILL.md
|
||
- [ ] skills/aide-build/SKILL.md
|
||
|
||
### 10.2 运行时部分
|
||
|
||
- [ ] aide.sh 入口脚本
|
||
- [ ] lib/output.sh 输出函数
|
||
- [ ] lib/config.py 配置读取
|
||
- [ ] env/check.py 环境检测
|
||
- [ ] undetermined/handler.py 待定项处理
|
||
- [ ] workspace/manager.py 工作目录
|
||
- [ ] progress/tracker.py 进度管理
|
||
- [ ] version/changelog.py CHANGELOG
|
||
- [ ] version/git.sh Git 操作
|
||
- [ ] build/plantuml.sh PlantUML
|
||
|
||
### 10.3 验收标准
|
||
|
||
1. 三个 Command 能正确触发对应流程
|
||
2. 六个 Skill 的 aide 命令能正常执行
|
||
3. 待定项能正确渲染和返回结果
|
||
4. 输出符合精简原则
|