agent-aide/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. 检测 aide 运行时环境（不依赖配置文件）
2. 初始化 .aide 目录和配置文件
3. 触发 LLM 对项目内容的主动认知
4. 检测项目开发环境并自动修复问题
5. 介绍 aide 流程体系和可用能力

**执行顺序**：
1. `aide env ensure --runtime` - 检查 aide 自身运行环境
2. `aide init` - 创建配置文件
3. 项目认知
4. `aide env ensure` - 检查项目环境

**特点**：
- 环境问题在此阶段解决，避免后续业务逻辑被打扰
- 沉没成本小：发现严重问题可重开对话

### 4.2 /aide:prep - 任务准备

**触发时机**：准备开始新任务时

**参数**：
- `[任务原文档路径]`（可选）：未传入时使用配置中的默认路径（通常为 task-now.md）

**职责**：
1. 启动流程追踪（`aide flow start task-optimize`）
2. 任务分析（理解目标、识别复杂度、分析环境）
3. 任务优化（准确性、简洁性、可执行性）
4. 待定项处理（通过 `aide decide` 程序化呈现）
5. 结果生成（LLM 自由发挥，产出 task-spec.md）

**核心原则**：
- 分析和优化阶段：指导 LLM 思考方向，让其竭尽全力发挥
- 待定项处理：程序化呈现，减少 token 污染
- 结果生成：不受格式限制，由用户直接审阅
- 流程管理：通过 `aide flow` 自动处理状态记录和 git 提交

**运行特点**：
- 使用 task-optimize 环节进行流程追踪
- LLM 不需要主动关注 git 操作和状态记录

### 4.3 /aide:exec - 任务执行

**触发时机**：任务准备完成，开始执行时

**参数**：
- `[任务细则文档路径]`（可选）：未传入时使用配置中的默认路径（通常为 task-spec.md）

**职责**：
1. 流程设计（理解细则、制定计划、环境准备）- flow-design 环节
2. 迭代实现（按计划执行、状态同步、阻塞处理）- impl 环节
3. 验证交付（对照标准、功能验证）- verify 环节
4. 文档更新（变更记录、版本发布）- docs 环节
5. 收尾（清理、总结）- 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 → 程序）**：

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