docs(agents): 把 AGENTS.md 的合并指引改写为合并队列的真实路径 (#3243)

[yinlianghui]

Fixes #3243

纯文档。只改 AGENTS.md §多 agent 协作纪律 里的合并/分支两条,其余小节一字未动。

为什么

旧的两条指引在今天的仓库规则下必然失败,而失败信息不会告诉 agent 文档过期了 —— 它更可能怀疑自己权限不足,或空等人工审批。

改了什么(逐条前后对照)

1. 直接合并 → 405(旧文没有这条,新增)

旧(隐含在下面第 3 条里):gh pr merge --squash --delete-branch 是收尾动作。

新:开篇点明本仓由 ruleset 强制合并队列,并原样引用 #3243 里对 PR #3241(15/15 全绿、mergeable_state: clean、非 draft)的实测响应体:405 Repository rule violations found / Changes must be made through the merge queue。补一句「撞上这个 405 不是你权限不够 —— 别去试更强的手段、也别以为要等人工审批」。

2. 「绝不 auto-merge」的禁令 → 反转

旧(原第 216 行):

合并前必须等远端 CI 全绿,绝不 gh pr merge --auto —— auto-merge 可能把还红着的 PR 落到共享 main 上,弄脏所有并行 agent 的基线。串行合并;合下一个前先 rebase 其他在途分支。注意 path-filter 跳过的检查(显示 skipping)配合 mergeStateStatus:CLEAN 即算全绿,不是失败。

新:该禁令防的风险正是队列现在替你防住的事(队列在当前 main 上重建、不绿就踢出队列),而在强制队列的仓库里 enable auto-merge 就是入队的标准手段。skipping + mergeStateStatus: CLEAN 那句原样保留(仍然成立)。仓内佐证一并写进去:.github/workflows/dependabot-auto-merge.yml:60 对 Dependabot PR 跑的正是 gh pr merge --auto --squash —— 仓库自己的自动化早就在用旧文禁止的那条命令行。

3. 收尾动作 → ready + 挂 auto-merge

旧(原第 217 行):

CI 全绿即自行合并,不必等维护者确认 —— …待测试/CI 全部通过后直接 gh pr merge --squash --delete-branch。

新:「不必等维护者确认」的授权语义原样保留(明写「授权语义没变,变的只是动作」),「只提交你任务改动的文件、绝不 git add -A」也原样保留;把动作换成 draft PR → CI 绿 → gh pr ready → gh pr merge --squash --auto --delete-branch,并给出 MCP 等价物。

4. 新增:auto-merge 会被静默丢弃

已两次踩实(先例 PR #3458):PR 变成 conflicting、或被(重新)标记为 draft 时,已挂的 auto-merge 会消失且无任何通知;解完冲突 / gh pr ready 之后不重挂,PR 就一直停在那里看着"全绿待合"。给了复查命令(gh pr view 取 isDraft,mergeStateStatus,autoMergeRequest,后者为 null 即掉了)。

5. 「合下一个前先 rebase 其他在途分支」→ 删,但保留语义冲突警告

队列自己会重建,串行 rebase 编排已是历史(而且它与同节「绝不 force push」本就别扭)。但队列只拦得住文本冲突和 CI 看得见的破坏:两个各自全绿的 PR 仍可能语义冲突。这层警告改挂到「动共享面时合并前扫一眼 gh pr list,有交叠就在 PR 正文写清交叠点与取并集办法」上(先例:PR #3458 对 #3456 同文件交叠的说明)。

6. 新增:证据边界

末尾一条明写 ruleset 的具体配置(谁可绕过、required checks 清单)本文不写、从仓内读不到、别照抄推断 —— 正是 #3243 自己的告诫。上面几条只写实测到的可观测行为。

验证(方向先判后跑)

预判:纯文档,且仓内没有任何测试读 AGENTS.md 的内容,所以不应有任何测试发生位移 —— 这一点跑之前先核过:grep -rn "AGENTS\.md'" 在全仓 .ts/.mjs/.js(除 node_modules)零命中,scripts/__tests__ 里那两处 AGENTS.md 全是注释引用。结果与预判一致。

• node scripts/check-control-bytes.mjs → check-control-bytes: OK (scanned 3690 tracked text file(s); skipped 85 binary).
• 越出门禁的自扫(本次改动提到了控制字符以外的内容,仍按纪律扫):grep -naP 对 [\x00-\x08\x0b\x0c\x0e-\x1f] 扫 AGENTS.md → 零命中。
• node scripts/check-doc-links.mjs → Docs links are valid.,但这对本 PR 是零覆盖:该脚本的扫描根写死在 path.resolve('content/docs')(check-doc-links.mjs:213),AGENTS.md 在它的扫描面之外。列在这里是为了说明它跑过且绿,不是为了暗示它覆盖了本次改动 —— 根级 .md 的内链目前没有门禁。
• git diff --stat → AGENTS.md | 23 +++--,1 file changed, 21 insertions(+), 2 deletions(-)。文件面零越界。
• 改后把整节从头到尾重读了一遍与 AGENTS.md 其余部分对表:同节「一个任务一个分支 + 一个 PR」「绝不 force push / 绝不推 main」与新文一致(删掉 rebase 编排反而消除了与 force-push 禁令的张力);§版本号策略里「ci.yml/lint.yml 把 **/*.md 列进 paths-ignore」与保留下来的 skipping 说明一致。全文再无第二处讲合并动作。

未做的事

• 无 changeset:根级文档,不影响任何包的产物。
• 未碰 content/docs/releases/。
• 同族陈述在别处的落点(只报告,未改动):sibling 仓 ../objectstack 的 AGENTS.md 第 164 行与第 676 行仍写着 Never gh pr merge --auto(第 168 行已有一句「once the repo's merge queue is enabled, add to queue IS the sanctioned path」的条件式说法)。那是另一个仓、另一套 ruleset,本 PR 的文件面之外,也不能拿 objectui 的实测去替它下结论 —— 建议单独立单核实。本仓 CLAUDE.md 与 .claude/ 下没有复述这两条。

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectui	Ignored		Aug 7, 2026 2:22am

[yinlianghui]

补一个自查更正(第 2 个 commit 00120cb,证据纪律相关):

第一版在 405 那条里写了「不带 --auto 的 gh pr merge --squash --delete-branch 打的是同一个 REST 端点,同样 405」。端点映射这一层我没有实测过 —— 这正是 #3243 自己告诫的那种推断,而且 gh 在 base 分支挂了合并队列时的行为随版本变。

已改为只写观测得到的部分:实测发起面是 REST;405 正文 Changes must be made through the merge queue 拒绝的是「直接合并」这个动作本身而非某个客户端,故旧文那条收尾路径同样不成立;并明写「gh 具体报什么文案随版本变,别按文案去猜,认准入队路径」。结论没变,依据收紧到实测面。

CI(两条无路径过滤的门禁,ci.yml/lint.yml 因 paths-ignore: **/*.md 未启动,与预判一致):Control Byte Scan ✓、Internal Docs Link Check ✓、label ✓。

---

Generated by Claude Code

---

Generated by Claude Code