398 lines
11 KiB
Markdown
Executable File
398 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. 触发 LLM 对项目内容的主动认知
|
||
2. 检测开发环境并自动修复问题
|
||
3. 介绍 aide 流程体系和可用能力
|
||
|
||
**特点**：
|
||
- 环境问题在此阶段解决，避免后续业务逻辑被打扰
|
||
- 沉没成本小：发现严重问题可重开对话
|
||
|
||
### 4.2 /aide:prep - 任务准备
|
||
|
||
**触发时机**：准备开始新任务时
|
||
|
||
**职责**：
|
||
1. 任务分析（理解目标、识别复杂度、分析环境）
|
||
2. 任务优化（准确性、简洁性、可执行性）
|
||
3. 待定项处理（通过 `aide decide` 程序化呈现）
|
||
4. 结果生成（LLM 自由发挥，产出 task-spec.md）
|
||
|
||
**核心原则**：
|
||
- 分析和优化阶段：指导 LLM 思考方向，让其竭尽全力发挥
|
||
- 待定项处理：程序化呈现，减少 token 污染
|
||
- 结果生成：不受格式限制，由用户直接审阅
|
||
|
||
**运行特点**：
|
||
- 轻量化：不创建工作目录、不记录状态、不 git 提交
|
||
|
||
### 4.3 /aide:exec - 任务执行
|
||
|
||
**触发时机**：任务准备完成，开始执行时
|
||
|
||
**职责**：
|
||
1. 流程规划（理解细则、制定计划、环境准备）
|
||
2. 迭代实现（按计划执行、状态同步、阻塞处理）
|
||
3. 验证交付（对照标准、功能验证）
|
||
4. 文档收尾（变更记录、版本发布）
|
||
|
||
**核心原则**：
|
||
- 业务代码编写：LLM 自由发挥，不加程序约束
|
||
- 状态管理、版本控制：通过 `aide flow` 程序处理，避免信息污染
|
||
|
||
---
|
||
|
||
## 五、技能清单
|
||
|
||
### 5.1 aide flow - 进度追踪
|
||
|
||
**用途**：记录任务执行状态 + Git 自动提交 + 流程校验
|
||
|
||
**核心命令**：
|
||
- `aide flow start <环节名> <总结>` - 新任务开始
|
||
- `aide flow next-step <总结>` - 小步骤前进
|
||
- `aide flow back-step <总结>` - 小步骤回退
|
||
- `aide flow next-part <环节名> <总结>` - 大环节前进
|
||
- `aide flow back-part <环节名> <总结>` - 大环节回退
|
||
- `aide flow issue <描述>` - 记录问题
|
||
- `aide flow error <描述>` - 记录严重错误
|
||
|
||
**设计要点**：
|
||
- 集成 git 操作：每次步骤变化自动 `git add . && git commit`
|
||
- 流程校验：检测环节跳转是否符合预期流程
|
||
- 环节特定行为：
|
||
- flow-design 环节：检验 PlantUML 语法
|
||
- docs-upgrade 环节：检验 CHANGELOG 更新
|
||
- 静默原则：无输出 = 正常
|
||
|
||
### 5.2 aide decide - 待定项确认
|
||
|
||
**用途**：程序化呈现待定项，通过 Web 界面获取用户确认
|
||
|
||
**核心命令**：
|
||
- `aide decide '<json>'` - 提交待定项数据，启动 Web 服务
|
||
- `aide decide result` - 获取用户决策结果
|
||
|
||
**设计要点**：
|
||
- LLM 传入精简 JSON 数据
|
||
- 程序启动 Web 服务，输出访问链接
|
||
- Web 界面渲染原文高亮、选项卡片
|
||
- 用户操作后存储决策
|
||
- LLM 读取精简决策结果
|
||
|
||
### 5.3 aide env - 环境管理
|
||
|
||
**用途**：检测并修复项目开发环境
|
||
|
||
**核心命令**：
|
||
- `aide env ensure` - 检测环境并自动修复
|
||
|
||
**设计要点**：
|
||
- 成功时输出极简：`✓ 环境就绪 (python:3.12)`
|
||
- 自动修复小问题时简短提示
|
||
- 仅无法修复时才需要 LLM 关注
|
||
|
||
---
|
||
|
||
## 六、信息流设计
|
||
|
||
### 6.1 待定项处理流程
|
||
|
||
```
|
||
LLM 程序 用户
|
||
│ │ │
|
||
│ JSON (精简数据) │ │
|
||
│─────────────────────→│ │
|
||
│ │ 启动Web服务 │
|
||
│ │ 输出访问链接 │
|
||
│ │─────────────────────→│
|
||
│ │ │
|
||
│ │ Web界面交互 │
|
||
│ │←─────────────────────│
|
||
│ JSON (决策结果) │ │
|
||
│←─────────────────────│ │
|
||
```
|
||
|
||
### 6.2 输出精简原则
|
||
|
||
| 场景 | 输出策略 |
|
||
|------|----------|
|
||
| 成功 | 极简确认：`✓ 操作完成` |
|
||
| 自动修复 | 简短提示：`✓ 已修复: xxx` |
|
||
| 警告 | 告知但可继续：`⚠ 警告内容` |
|
||
| 失败 | 详细原因：`✗ 失败原因及建议` |
|
||
|
||
### 6.3 错误恢复机制
|
||
|
||
| 级别 | 处理方式 |
|
||
|------|----------|
|
||
| ⚠ 警告 | 记录，分析是否影响继续，记录"继续-xxx"或"解决阻塞-xxx" |
|
||
| ✗ 错误 | 必须先记录并解决。默认自行取最优解，3次尝试失败则停止等待用户。成功解决时在 discuss/ 创建分析文档 |
|
||
|
||
---
|
||
|
||
## 七、LLM 自由发挥边界
|
||
|
||
### 7.1 需要程序约束的场景
|
||
|
||
- 环境检测与修复
|
||
- 待定项呈现与确认
|
||
- 状态记录与更新（含 git 提交）
|
||
|
||
### 7.2 不需要程序约束的场景
|
||
|
||
- 任务分析思考
|
||
- 任务优化思考
|
||
- 业务决策判断
|
||
- 任务细则编写（task-spec.md）
|
||
- 业务代码编写
|
||
- 结果文档产出
|
||
|
||
---
|
||
|
||
## 八、数据格式规范
|
||
|
||
### 8.1 待定项数据格式
|
||
|
||
**输入格式（LLM → 程序）**：
|
||
|
||
```json
|
||
{
|
||
"task": "任务简述",
|
||
"source": "now-task.md",
|
||
"items": [
|
||
{
|
||
"id": 1,
|
||
"title": "问题标题",
|
||
"location": {
|
||
"file": "now-task.md",
|
||
"start": 5,
|
||
"end": 7
|
||
},
|
||
"context": "详细说明（可选）",
|
||
"options": [
|
||
{
|
||
"value": "option_a",
|
||
"label": "选项A描述",
|
||
"score": 85,
|
||
"pros": ["优点1", "优点2"],
|
||
"cons": ["缺点1"]
|
||
}
|
||
],
|
||
"recommend": "option_a"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**输出格式（程序 → LLM）**：
|
||
|
||
```json
|
||
{
|
||
"decisions": [
|
||
{"id": 1, "chosen": "option_a"},
|
||
{"id": 2, "chosen": "option_b", "note": "用户备注"}
|
||
]
|
||
}
|
||
```
|
||
|
||
> 注：`note` 字段仅在用户有备注时出现
|
||
|
||
### 8.2 输出前缀规范
|
||
|
||
| 前缀 | 函数 | 用途 |
|
||
|------|------|------|
|
||
| ✓ | `ok` | 成功 |
|
||
| ⚠ | `warn` | 警告（可继续） |
|
||
| ✗ | `err` | 失败 |
|
||
| → | `info` | 进行中 |
|
||
| [n/m] | `step` | 步骤进度 |
|
||
|
||
---
|
||
|
||
## 九、数据存储
|
||
|
||
### 9.1 存储位置
|
||
|
||
所有 aide 自动创建和管理的数据文件统一存放在项目路径下的 `.aide/` 目录：
|
||
|
||
```
|
||
.aide/
|
||
├── config.toml # 项目配置（自文档化，带注释）
|
||
├── flow-status.json # 当前任务进度状态
|
||
├── decisions/ # 待定项决策记录
|
||
│ └── {timestamp}.json
|
||
└── logs/ # 操作日志
|
||
```
|
||
|
||
### 9.2 .gitignore 处理
|
||
|
||
- `aide init` 时自动检查 `.gitignore`
|
||
- 默认添加 `.aide/` 为忽略项
|
||
- 可在配置中指定不忽略
|
||
|
||
### 9.3 配置机制
|
||
|
||
- 配置文件不存在时输出 `⚠ 配置文件不存在，使用默认配置`
|
||
- `aide init` 时自动创建默认配置
|
||
- 配置文件自带详细注释（自文档化）
|
||
- **LLM 不允许直接读取配置文件**（避免污染上下文）
|
||
- 通过 `aide config get <key>` 读取配置
|
||
- 每次设置/获取都集成验证
|
||
|
||
---
|
||
|
||
## 十、实施结构
|
||
|
||
### 10.1 最终产出
|
||
|
||
1. **README.md** - 用户入口文档
|
||
2. **插件市场目录** - 可快速安装的 Claude Code 插件
|
||
3. **aide 程序目录** - 运行时脚本系统
|
||
|
||
### 10.2 插件目录结构
|
||
|
||
```
|
||
aide-marketplace/
|
||
├── .claude-plugin/
|
||
│ └── marketplace.json
|
||
└── aide-plugin/
|
||
├── .claude-plugin/
|
||
│ └── plugin.json
|
||
├── commands/
|
||
│ ├── init.md
|
||
│ ├── prep.md
|
||
│ └── exec.md
|
||
└── skills/
|
||
└── aide/
|
||
└── SKILL.md
|
||
```
|
||
|
||
### 10.3 程序目录结构
|
||
|
||
```
|
||
aide/
|
||
├── aide.sh # Linux/Mac 入口
|
||
├── aide.bat # Windows 入口
|
||
├── main.py # Python 主入口
|
||
├── core/
|
||
│ ├── config.py # 配置读写
|
||
│ └── output.py # 输出格式（✓/⚠/✗）
|
||
├── flow/ # aide flow
|
||
│ ├── tracker.py # 进度追踪
|
||
│ ├── git.py # git 自动提交
|
||
│ └── validator.py # 流程校验
|
||
├── decide/ # aide decide
|
||
│ ├── server.py # HTTP 服务
|
||
│ └── web/ # 静态 React 前端
|
||
└── env/
|
||
└── ensure.py # 环境检测修复
|
||
```
|
||
|
||
### 10.4 分发方式
|
||
|
||
初期：打包压缩包分享，验证可用后考虑远程仓库 + 包托管
|
||
|
||
---
|
||
|
||
## 十一、待设计内容
|
||
|
||
以下内容将在后续讨论中逐步细化：
|
||
|
||
- [ ] Commands 详细内容（init.md / prep.md / exec.md）
|
||
- [ ] SKILL.md 详细内容
|
||
- [ ] aide flow 子命令详细设计
|
||
- [ ] aide decide Web 界面设计
|
||
- [ ] 配置文件完整字段定义
|