12 KiB
Executable File
12 KiB
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 - 认知初始化
触发时机：进入项目开始工作时
职责：
- 检测 aide 运行时环境（不依赖配置文件）
- 初始化 .aide 目录和配置文件
- 触发 LLM 对项目内容的主动认知
- 检测项目开发环境并自动修复问题
- 介绍 aide 流程体系和可用能力
执行顺序：
aide env ensure --runtime- 检查 aide 自身运行环境aide init- 创建配置文件- 项目认知
aide env ensure- 检查项目环境
特点：
- 环境问题在此阶段解决，避免后续业务逻辑被打扰
- 沉没成本小：发现严重问题可重开对话
4.2 /aide:prep - 任务准备
触发时机：准备开始新任务时
参数：
[任务原文档路径]（可选）：未传入时使用配置中的默认路径（通常为 task-now.md）
职责：
- 启动流程追踪（
aide flow start task-optimize） - 任务分析（理解目标、识别复杂度、分析环境）
- 任务优化（准确性、简洁性、可执行性）
- 待定项处理（通过
aide decide程序化呈现） - 结果生成（LLM 自由发挥，产出 task-spec.md）
核心原则：
- 分析和优化阶段：指导 LLM 思考方向，让其竭尽全力发挥
- 待定项处理：程序化呈现，减少 token 污染
- 结果生成：不受格式限制，由用户直接审阅
- 流程管理：通过
aide flow自动处理状态记录和 git 提交
运行特点：
- 使用 task-optimize 环节进行流程追踪
- LLM 不需要主动关注 git 操作和状态记录
4.3 /aide:exec - 任务执行
触发时机：任务准备完成，开始执行时
参数：
[任务细则文档路径]（可选）：未传入时使用配置中的默认路径（通常为 task-spec.md）
职责：
- 流程设计（理解细则、制定计划、环境准备）- flow-design 环节
- 迭代实现（按计划执行、状态同步、阻塞处理）- impl 环节
- 验证交付（对照标准、功能验证）- verify 环节
- 文档更新（变更记录、版本发布）- docs 环节
- 收尾（清理、总结）- finish 环节
核心原则：
- 业务代码编写：LLM 自由发挥，不加程序约束
- 状态管理、版本控制：通过
aide flow程序处理，避免信息污染 - 流程管理：通过
aide flow自动处理状态记录和 git 提交
运行特点：
- LLM 不需要主动关注 git 操作和状态记录
- 专注于任务实现本身
五、技能清单
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 语法，生成 PNG 流程图
- docs 环节：检验 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- 检测项目环境并自动修复aide env ensure --runtime- 仅检测 aide 运行时环境（不依赖配置文件）
设计要点：
--runtime参数用于 init 阶段，在配置文件创建前检查 aide 自身运行环境- 成功时输出极简：
✓ 环境就绪 (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 → 程序）：
{
"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）：
{
"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 最终产出
- README.md - 用户入口文档
- 插件市场目录 - 可快速安装的 Claude Code 插件
- 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 界面设计
- 配置文件完整字段定义