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 00:35:36 +08:00
parent 3c05d54303
commit 3628971a6e
13 changed files with 1130 additions and 172 deletions
Download Patch File Download Diff File Expand all files Collapse all files

416
aide-requirements.md
View File

@@ -1,416 +0,0 @@
# 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. 输出符合精简原则