# 小虾 SaaS 8 Agent Runbook

## 目的

本 Runbook 规定每个开发、修复、发布任务必须如何在 8 Agent 之间流转，避免临时散修、重复返工和生产上才暴露基础问题。

## 标准流转

```text
requirement_agent
  → arch_agent
  → code_dev_agent
  → lint_review_agent
  → test_agent
  → build_pack_agent
  → release_agent
  → ops_monitor_agent
```

## 1. requirement_agent

### 输入

- 老大的目标或问题反馈。
- 当前 Phase / 开发包文档。
- 生产现状和已知风险。

### 必须输出

- 本轮目标。
- 范围内事项。
- 范围外事项。
- 验收标准。
- 是否需要老大拍板。

### 阻止继续的条件

- 目标不清楚。
- 涉及费用、不可逆操作、产品方向变化。
- 验收标准不可验证。

## 2. arch_agent

### 输入

- requirement_agent 的目标和验收标准。
- 现有架构、数据流、权限边界、部署约束。

### 必须输出

- 根因分析或架构方案。
- 涉及模块清单。
- 数据流和失败路径。
- 风险和回滚方案。

### 阻止继续的条件

- 方案只是表面补丁，不能解释根因。
- 涉及生产高风险但无回滚方案。
- 跨模块影响未列出。

## 3. code_dev_agent

### 输入

- arch_agent 方案。
- 相关代码和测试。

### 必须输出

- 最小必要代码改动。
- 对应测试或测试待办。
- 数据修复脚本（如需要）。
- 不相关问题清单。

### 阻止继续的条件

- 改动超出需求范围。
- 未处理核心异常路径。
- 引入假成功、假入口或不可观测状态。

## 4. lint_review_agent

### 输入

- code_dev_agent 的 diff。
- 项目规范、权限边界、安全要求。

### 必须输出

- Review 结论：通过 / 需修改。
- 安全和权限风险。
- 回归风险。
- 是否允许进入测试。

### 阻止继续的条件

- 权限边界不清。
- 错误处理不明确。
- 生产配置或密钥风险。

## 5. test_agent

### 输入

- 已 review 的代码。
- 验收标准。

### 必须输出

- 单元测试结果。
- 集成/smoke 结果。
- Playwright E2E 结果（涉及 UI 时必须）。
- 失败截图、trace、日志（失败时）。

### 阻止继续的条件

- 相关测试失败。
- UI 流程未通过真实浏览器验证。
- 修复没有对应回归测试。

## 6. build_pack_agent

### 输入

- 测试通过的代码。
- 发布配置和构建脚本。

### 必须输出

- 前端 build 结果。
- runtime image / release artifact 校验。
- 构建环境确认。
- 产物版本确认。

### 阻止继续的条件

- 生产机需要构建 API/Worker。
- 产物缺失或版本不一致。
- 构建脚本与发布约束冲突。

## 7. release_agent

### 输入

- build_pack_agent 产物。
- release checklist。

### 必须输出

- commit / tag。
- 部署结果。
- `/health` 版本。
- 公网 smoke 结果。
- 回滚点。

### 阻止继续的条件

- 部署失败。
- health 版本不一致。
- 公网 smoke 失败。
- 回滚点缺失。

## 8. ops_monitor_agent

### 输入

- release_agent 的生产版本。
- 生产日志、资源、巡检报告。

### 必须输出

- Web/API/Worker/DB/Redis 状态。
- 4xx/5xx/499 新增异常。
- CPU/内存/磁盘/负载状态。
- 是否进入观察期或回滚。

### 阻止继续的条件

- 生产关键告警未解释。
- 资源不足影响可用性。
- 用户主流程仍失败。

## 自动重试规则

- 每个失败最多自动修复 3 轮。
- 每轮必须记录失败证据和修复动作。
- 第 3 轮后仍失败，暂停并向老大汇报。

## 每轮交付报告格式

```text
目标：...
版本/提交：...
8 Agent 状态：
- requirement_agent: ...
- arch_agent: ...
- code_dev_agent: ...
- lint_review_agent: ...
- test_agent: ...
- build_pack_agent: ...
- release_agent: ...
- ops_monitor_agent: ...
验证证据：...
遗留风险：...
下一步：...
```
