Jyotisha/tools/agent-loop/projects/copse/RULES.md

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 生产清单、密钥与渠道凭据、计费单价与销售报价（会直接影响收入）、删除或退役模块。