Jyotisha/docs/agents/agent-loop-playbook.md

# 双 agent 自动循环：流程与接入手册

2026-10-13 定稿。适用于 Jyotisha，以及按第 5 节接入的其他项目（首个是 copse）。实现细节在 `tools/agent-loop/README.md`，决策过程在 `docs/tasks/TASK-agent-loop-pilot-20261013.md`。

## 1. 一句话

**产品负责人只做两件事：说清要什么、在真机上点一遍。** 中间的诊断、写任务书、改代码、测试、验收、上测试环境，由两个 agent 通过 Gitea issue 自己交接完成。

参照的是 yetone/magpie：他在 Claude Code 会话里并行跑几个 `/loop`，加一段大白话提示词，没有别的魔法。我们在此基础上多了一道交叉审查：**Grok 写代码，Claude 验收**，写和审不是同一个 agent。

## 2. 三个角色

| 角色 | 在哪 | 做什么 | 不做什么 |
| --- | --- | --- | --- |
| 产品负责人 | 任何地方 | 提需求或 bug（或和 Claude 聊完由它提）、拍板、真机验收、发生产 | 传话、催进度、读代码 |
| Claude | Linux 机器上的常开会话，`/loop 30m` | 和产品负责人聊需求并提 issue；诊断写任务书；独立复验 Grok 的提交；合入测试环境；核对部署；每晚复盘 | 写业务代码；推生产分支；改 CI 流程 |
| Grok Build | 产品负责人 Windows 上的常开会话，`/loop 15m` | 按任务书实现、自测、推 `codex/*` 分支、回报 | 推测试或生产分支；删分支；自己做产品决定 |

**账号**：两个 agent 各用一个 Gitea 账号发言——`Claude`、`Grok`，看评论就知道是谁说的（2026-10-13 产品负责人决定）。两个工具只信任 `jesse`、`Claude`、`Grok` 三个账号写的内容，其他人写的不交给模型。两个账号都要加为各项目仓库的协作者（写权限）；令牌各存在自己那台机器的 `~/.config/jyotisha-agent/gitea-token`。

## 3. 一单怎么走

```
你提 issue（或 Claude 聊完代提，提交前给你过目）
  标签：agent/待规划
     │  Claude：查 Bug 历史 → 读代码找根因 → 写任务书
     ▼
  agent/待执行 ──────────────┐ 需要你决定 → agent/需拍板 → 你回复后改回原标签
     │  Grok：照任务书改、自测、推 codex 分支、回报提交号
     ▼
  agent/待验收
     │  Claude：只验回报的那个提交号；逐行看改动；跑测试
     ├─ 不通过 → 写修复单 → 回到 agent/待执行（第 2 次打回就停下 @你）
     ▼ 通过
  合入测试环境 → agent/部署中
     │  Claude：核对测试环境已部署这次改动
     ▼
  agent/待真机 → @你 去点一遍 → 没问题就关 issue；有问题写下来改回 agent/待规划
```

处理中会挂锁标签（`规划中 / 执行中 / 验收中`），避免两边抢同一单。试点期还要求同时带 `agent/试点`。

## 4. 安全护栏（为什么敢让它自己跑）

| 风险 | 护栏 |
| --- | --- |
| 陌生人在 issue 里写指令诱导 agent | 只认标签触发（只有有写权限的人能打）；只读产品负责人账号写的正文和评论 |
| agent 推到不该推的分支 | 推送前钩子：Grok 只能推 `codex/*`，Claude 不能推生产分支，谁都不能删分支 |
| agent 越权执行命令 | 两边都用白名单 + `dontAsk`，白名单外自动拒绝；不放行任意 shell |
| 验收验的不是实际要合的代码 | 验收锁提交号：只验 Grok 回报的那个；验完后分支又有新提交就重验 |
| 两个 agent 来回扯皮 | 同一单打回 2 次、连续出错 3 次，就停下 @产品负责人 |
| 泄露隐私 | 评论与任务书不写用户资料；Jyotisha 仓库对外公开，尤其注意 |
| 越跑越乱 | 每晚复盘写 `LESSONS.md`，同一教训出现 3 天提议升级为硬规则，由产品负责人拍板 |
| 生产事故 | 生产发布不进循环，永远由产品负责人手动触发 |

## 5. 接入一个新项目的清单

| # | 要定的事 | Jyotisha 的答案 | copse 的答案 |
| --- | --- | --- | --- |
| 1 | Gitea 仓库、是否公开 | `root/Jyotisha`，公开 | `root/copse`，私有 |
| 2 | 改动怎么进测试环境 | 快进推 `staging`，门禁通过后自动部署 | **开 PR 合进 `main`**，合并后 `copse-test` 自动发布到 test 环境（k3s） |
| 3 | 生产怎么发 | 产品负责人提升 `main` | 产品负责人手动跑 `yudao-k3s-prod` |
| 4 | 怎么确认测试环境部署了 | `/api/health` 的 `deployment.gitCommit` | 合并提交的 `copse-test.yml` 运行为 success（`gitea.sh runs <sha>`） |
| 5 | 项目规则文件 | `AGENTS.md`、`CLAUDE.md`、`docs/BUG_HISTORY.md` | `AGENTS.md`（含 Flyway 迁移约定、新模型接入准则）、`tests/AGENTS.md` |
| 6 | 验收要跑的测试 | tsc、lint、npm test、Python 快速门；Windows 跑 `test:db` | Python 契约测试 `pytest tests/`、`script/db/check_migrations.py`、Maven 编译与模块测试、前端 `draw2video-*` 构建 |
| 7 | Claude 这台机器跑得了吗 | 能 | Python 契约测试、迁移检查、前端能跑；**Java 不跑，以 Grok 为准**（产品负责人决定），覆盖不全即打回 |
| 8 | Grok 的 Windows 跑得了吗 | 能（T1 已测，13 条已知失败） | 待测：JDK 21、Maven、pnpm、Docker、copse 检出位置 |
| 9 | 什么不进循环 | 动表、发布、改 workflow | 发布、改 workflow、计费单价、密钥；**迁移允许**，但只能新增、必须过 `check_migrations.py` |
| 10 | 任务书放哪 | `docs/tasks/`，推 staging | 作为 `codex/*` 分支的第一个提交，随 PR 合进 `main` |
| 11 | 谁合并 | Claude 快进推 staging | Claude 用 `merge-pr` 锁定验收过的提交号合并 PR（产品负责人决定） |
| 12 | 规则与提示词 | `tools/agent-loop/prompts/` | `tools/agent-loop/projects/copse/`（`RULES.md`、两份 loop 提示词、白名单） |

接入步骤：定好上表 → 建同一套 `agent/*` 标签 → 两边各开一个该项目专用的 `/loop` 会话（**一个项目一个会话**，不混在一起）→ 先跑一单试点。

## 6. 日常怎么用

- **小 bug**：自己在 Gitea 开 issue，写清「在哪 / 做了什么 / 看到什么 / 期望什么」，打 `agent/待规划`（试点期加 `agent/试点`）。
- **新需求、大一点的改动**：先和 Claude 聊，Claude 拆成几个小 issue 并写明先后顺序，给你过目后提交。
- **维护**：两边的 `/loop` 7 天过期，每周重开会话、重新粘贴一次；机器重启或会话关闭后也要重开。
- **每晚**：花几分钟看 `docs/agents/LESSONS.md` 里「待拍板升级」的条目，再处理真机验收时发现的体验问题。