# 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 ''` - 提交待定项数据，启动 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 ` 读取配置 - 每次设置/获取都集成验证 --- ## 十、实施结构 ### 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 界面设计 - [ ] 配置文件完整字段定义