# copse 接入 agent 循环的规则

产品负责人 2026-10-13 决定：Java 测试以 Grok 的结果为准；循环里允许数据库迁移但必须过严格检查；Claude 验收通过后自动合并 PR。通用流程与护栏见 `docs/agents/agent-loop-playbook.md`（Jyotisha 仓库）。本文件只写 copse 不同的地方，两侧 `/loop` 每轮都先读它。

## 仓库事实

- Gitea `root/copse`，**私有**；默认分支 `main`。工具调用一律带仓库参数：Linux `GITEA_REPO=root/copse ~/.local/share/jyotisha-agent/bin/gitea.sh ...`；Windows `gitea.ps1 ... -Repo root/copse`。
- 合进 `main` 会触发 `copse-test.yml`，自动发布到 test 环境（k3s）。**生产发布（`yudao-k3s-prod`）永远由产品负责人手动触发**，循环不碰。
- 项目规则：仓库根 `AGENTS.md`（Flyway 迁移约定、新模型完整生命周期准则、禁止的架构回退）、`tests/AGENTS.md`（契约测试约定）。每单开工前读与本单相关的章节。
- 技术栈：JDK 21 + Maven 多模块（`yudao-*`）、前端 `yudao-ui/draw2video-admin`、`yudao-ui/draw2video-client`（pnpm）、根目录 `tests/` 的 Python 契约测试、`script/db/check_migrations.py`。

## 一单怎么走（与 Jyotisha 的差别）

1. **Claude 规划**：从 `origin/main` 建分支 `codex/<主题>-<YYYYMMDD>`，第一个提交是任务书 `docs/tasks/TASK-<主题>-<YYYYMMDD>.md`，推这个分支（不开 PR、不推 main）。评论首行：`<!-- agent:claude plan brief=<任务书> branch=<分支> base=<origin/main sha> -->`。
2. **Grok 执行**：在该分支上实现、自测、推送；分支还没有 PR 就开一个（`gitea.ps1 create-pr <分支> <标题> <正文文件> -Repo root/copse`，标题用 copse 现有的 `fix(模块): 中文说明` 风格）。评论首行：`<!-- agent:grok report branch=<分支> sha=<远端 head> pr=<PR 号> -->`。
3. **Claude 验收**：只验回报的 SHA，并核对 PR 的 head 就是它、`mergeable` 为真。通过就合并（下文「合并」），评论首行 `<!-- agent:claude review sha=<head> verdict=pass pr=<号> merge=<合并提交 40 位> -->`，标签换 `agent/部署中`。不通过：把修复单 `docs/tasks/TASK-<主题>-fix-<YYYYMMDD>.md` 作为新提交推到**同一分支**，评论 `<!-- agent:claude review sha=<head> verdict=fail brief=<修复单> branch=<分支> -->`，标签换回 `agent/待执行`。
4. **部署核对**：`gitea.sh runs <合并提交>` 里 `copse-test.yml` 为 `success` → `agent/待真机` 并 @jesse；`failure` → `agent/需拍板`，评论写 run 号；超过 3 小时仍未完成 → `agent/需拍板`。

## 测试分工

| 检查 | Grok（Windows）必跑并在回报里贴命令与数字 | Claude（Linux，无 JDK）验收 |
| --- | --- | --- |
| Java 编译与模块测试 `mvn --no-transfer-progress -pl <改到的模块> -am test` | **必跑，以 Grok 为准** | 跑不了：核对 Grok 贴的命令覆盖了所有改到的模块、测试数与失败数；没贴或覆盖不全即 `fail` |
| 相关 Python 契约测试 `python -m pytest tests/<相关文件> -q` | 必跑 | 复验；另外 grep 改到的文件路径，找出按源码断言的契约测试一起跑 |
| 迁移检查（改了任何迁移 SQL 时）`python script/db/check_migrations.py --release-base origin/main` | 必跑 | **必须复验通过** |
| 前端（改了 `yudao-ui/**` 时）该应用目录下 `pnpm lint` 与 `pnpm build` | 必跑 | 依赖装得上就复验，装不上记环境缺口 |

## 数据库迁移（允许，但严格）

- 只能**新增**迁移文件，命名 `VYYYYMMDDNNNN__description.sql`，同库版本号唯一，按根 `AGENTS.md`「Flyway Feature 迁移约定」与「标准流程」做完（含 verify SQL）。
- 任何已存在的迁移文件被修改、删除、改名：直接 `fail`（Claude 用 `git diff --name-status origin/main...<sha>` 核对，迁移目录下只允许 `A`）。
- `check_migrations.py` 不过：`fail`。
- 合并前再基于最新 `origin/main` 确认没有同库版本号冲突；有冲突要求 Grok 重新编号（尚未进 test 的才能改号）。

## 合并

```
GITEA_REPO=root/copse ~/.local/share/jyotisha-agent/bin/gitea.sh merge-pr <PR 号> <验收过的 40 位 SHA>
```

`head_commit_id` 锁住验收过的提交：验收期间分支又被推了新提交，Gitea 会拒绝合并，此时不重试，留言后下一轮重验。合并后读 `merge_commit` 填进评论标记。

## 不进循环（遇到就 `agent/需拍板`）

生产发布与 `yudao-k3s-prod`、`.gitea/workflows/**`、k3s 生产清单、密钥与渠道凭据、计费单价与销售报价（会直接影响收入）、删除或退役模块。