agent-aide/reply/aide-requirements.md

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 → 程序）：

{
  "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 最终产出

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 界面设计
• 配置文件完整字段定义