diff --git a/docs/agents/agent-loop-playbook.md b/docs/agents/agent-loop-playbook.md
new file mode 100644
index 00000000..12fa4585
--- /dev/null
+++ b/docs/agents/agent-loop-playbook.md
@@ -0,0 +1,76 @@
+# 双 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/*` 分支、回报 | 推测试或生产分支；删分支；自己做产品决定 |
+
+## 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` | **待定**（test 环境的版本接口，或 `copse-test` 运行结果） |
+| 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 这台机器跑得了吗 | 能 | **不能跑 Java**：没装 JDK 21 / Maven |
+| 8 | Grok 的 Windows 跑得了吗 | 能（T1 已测，13 条已知失败） | **待测**：JDK 21、Maven、pnpm、Docker |
+| 9 | 什么不进循环 | 动表、发布、改 workflow | 发布、改 workflow；**数据库迁移待定** |
+| 10 | 任务书放哪 | `docs/tasks/` | **待定**（copse 现在用 `docs/<主题>` 分支和 `docs/features/`） |
+
+接入步骤：定好上表 → 建同一套 `agent/*` 标签 → 两边各开一个该项目专用的 `/loop` 会话（**一个项目一个会话**，不混在一起）→ 先跑一单试点。
+
+## 6. 日常怎么用
+
+- **小 bug**：自己在 Gitea 开 issue，写清「在哪 / 做了什么 / 看到什么 / 期望什么」，打 `agent/待规划`（试点期加 `agent/试点`）。
+- **新需求、大一点的改动**：先和 Claude 聊，Claude 拆成几个小 issue 并写明先后顺序，给你过目后提交。
+- **维护**：两边的 `/loop` 7 天过期，每周重开会话、重新粘贴一次；机器重启或会话关闭后也要重开。
+- **每晚**：花几分钟看 `docs/agents/LESSONS.md` 里「待拍板升级」的条目，再处理真机验收时发现的体验问题。