27 个 PR 没有深审,且它们彼此冲突:mergeable=MERGEABLE 是误导(附实测冲突图与合并顺序)

[vansin]

🔴 正文有两条推断已被实测证伪(2026-08-14)

下面第 30 行起的「#843×#845 合起来红」与第 50 行起的「取并集会出空壳 job」,
我后来真合了一次并跑了门自己的脚本,两条都不成立。原文保留不动,
但读到那两节请先看更正:#856 (comment)
用 merge-tree 跑出来的那张「6/10 对冲突」实测图仍然成立。

现状

gh pr list --state open = 31 个,其中 27 个没有任何深审(只有 codex bot 的模板评论),
且全部是同一天、同一个作者开的。

瓶颈不在产出,在评审。继续开 PR 只会让这堆变大。

🔴 mergeable=MERGEABLE 在这里是误导

GitHub 的 mergeable 只回答「今天能不能并进 main」。31 个里 30 个都是 MERGEABLE
(唯一 CONFLICTING 的是 #460)。但它们彼此冲突。

git merge-tree --write-tree(干跑,不改任何东西)对 qa.yml 那一簇两两求交:

#798 × #801  ❌     #798 × #803  ❌     #798 × #843  ❌     #798 × #846  干净
#801 × #803  ❌     #801 × #843  ❌     #801 × #846  干净
#803 × #843  ❌     #803 × #846  干净
#843 × #846  干净

10 对里 6 对冲突。第一个落地之后,其余四个的 MERGEABLE 会立刻变成 CONFLICTING。

单测门那一簇同样:

#800 × #801  ❌     #800 × #854  ❌     #801 × #854  ❌

🔴 更危险的一类:merge-tree 看不见的语义冲突 ← 已证伪,实测两个合并顺序都绿

文档 pin 那一簇 #843 / #844 / #845 两两文本干净,但合起来会让门变红:

• #845 把 mcp-tools.md(ZH+EN)的行号 pin 从 44 + 44 清到 0,共移除 43 个唯一 pin;
• 其中 18 个正是 #843 基线文件里的条目;
• 而 #843 那道门的判据之一就是「基线里不能有已经不再被引用的残留」——
  它会打印 FAIL: N 个基线条目对应的引用已经不在文档里了,请从基线里删掉 并 exit 1。

所以 #843 与 #845 谁后合,谁就得先缩基线。两个 PR 各自都绿、两两也不冲突,合起来红。

复现:

git merge-tree --write-tree <843-head> <845-head>     # 干净
# 但:
git show <843-head>:docs/doc-source-pins-baseline.txt          # 基线条目
git show <845-head>:docs-site/docs/api/mcp-tools.md | grep -c 'blob/main/[^)#]*#L'   # 0

🔴 qa.yml 那一簇尤其要小心怎么解冲突 ← 已证伪,10 对+五全合一个空壳 job 都没有

.github/workflows/qa.yml 被 5 个 PR 同时改(#798 #801 #803 #843 #846)。
这个文件上「按冲突块取并集」会产出:

doc-source-pins:
  name: doc source-pin floor (Docker)     ← 到此为止,没有 runs-on、没有 steps
doc-claims:
  name: doc claim freshness (Docker)
  runs-on: ubuntu-latest
  steps: …

这是合法 YAML,GitHub 接受它,job 名字出现在检查列表里并显示绿色 ——
一道从不执行的门和一道执行且通过的门,在 PR 页面上长得一模一样。
成因是两个 job 的 runs-on / timeout-minutes / steps: / - uses: actions/checkout@v4
逐字相同,被 git 判成公共上下文只留一份。

正确解法不是取并集,是把属于同一个 job 的碎片拼回完整块:
每个 job = 自己的头 + 公共块(各复制一份)+ 自己的体。

(#848 那道 workflow 结构门就是为挡这个而开的 —— 它自己也还没合。)

建议的合并顺序

按「冲突面从小到大」,每合一个就重跑下一个的 merge 检查:

1. 无冲突的先走:docs: 留一份「陈旧 issue 怎么复核」的做法(四次实核提炼) #846、docs(changelog): RFC-014 那条的源码引用钉到当时的提交(现在指向一个 15 行文件的第 253 行) #834、docs(changelog): v0.10.1 那两条 cli.ts 引用钉到当时的提交(行号在范围内但已经指错) #851、chore: 删掉 test682 这道过时的门,以及 #698 废弃设计留下的两个死模块 (#804) #855、docs: 英文 troubleshooting 把 latest 的现状写成了历史;并更正 RELEASE-SOP 一句不成立的话 #807、docs: record GrokTUI dog node recovery #808、docs: 节点存活判据 —— 看产物推进,不看进程数/started 行 #812、docs(CLAUDE.md): Dashboard 那行指向的不是产品形态(能打开、标题也对,所以更难发现) #833、docs: record communication dog live TUI UAT #837、chore(deps): agent-network lockfile 把 hono 推过修复线(4.12.25 → 4.13.1,清 6 条告警) #842 等
   只碰自己文件的。
2. qa.yml 簇:挑一个先合(建议 test(ci): 给 server 补上聚合单测门(69 个单测此前 CI 只跑 6 个) #798,它是其余几个的依赖),
   然后逐个 rebase 其余四个 —— 不要并行合。解冲突时照上面那条规则。
3. 单测门簇:test(ci): 让 test725/test745 覆盖 tests/ 目录(两个门自称 complete 却漏了 25 个文件) #800 → test(ci): 给 src/ 补绝对下限 —— 两道门都放行「大量删除测试文件」(#817) #854 → ci: 元门 —— 新增测试文件不能落在所有聚合门的扫描范围之外(依赖 #798 #800) #801(ci: 元门 —— 新增测试文件不能落在所有聚合门的扫描范围之外(依赖 #798 #800) #801 自称依赖 test(ci): 给 server 补上聚合单测门(69 个单测此前 CI 只跑 6 个) #798 test(ci): 让 test725/test745 覆盖 tests/ 目录(两个门自称 complete 却漏了 25 个文件) #800)。
4. 文档 pin 簇:先 docs(mcp-tools): 章节源码链接改钉符号 —— 实测 17 处行号锚点 17 处全错 #844 / docs(mcp-tools): 正文行号引用改钉符号 —— 两版行号 pin 归零 #845(它们缩小 pin 集合),再合 ci(test831): 文档站行号 pin 的下限门(守住不再变多,不解决 #831) #843 并同步缩基线;
   反过来的话 ci(test831): 文档站行号 pin 的下限门(守住不再变多,不解决 #831) #843 合完就会被 docs(mcp-tools): 正文行号引用改钉符号 —— 两版行号 pin 归零 #845 弄红。

我为什么开这条

我是上面大部分 PR 的作者。自己写的自己批没有意义,所以我能做的是把这堆的
依赖和冲突关系算清楚,让接手评审/合并的人不必一个个撞。

这一轮我没有再开新的功能 PR。

[vansin]

「可先走」那批已经验完:8 个,可依次全部落地

按本 issue 的第 1 步,把「文件与任何其他 PR 都不重叠」的挑出来,逐条验:

PR	mergeable	CI	标题
#805	MERGEABLE	✅ 9 绿	写明单测的两条 DB 契约
#807	MERGEABLE	✅ 2 绿	英文 troubleshooting 把 latest 现状写成历史
#812	MERGEABLE	✅ 7 绿	节点存活判据
#815	MERGEABLE	✅ 2 绿	开 PR 前的自查清单
#833	MERGEABLE	✅ 2 绿	CLAUDE.md 里 Dashboard 那行
#841	MERGEABLE	✅ 7 绿	agent-node lockfile + npm ci
#848	MERGEABLE	✅ 5 绿	workflow 结构门
#855	MERGEABLE	⏳ 跑中	删 test682 + 两个死模块

不是只看「文件不重叠」——做了真合并

在一棵临时 worktree 里按上表顺序依次 git merge(不碰任何共享分支,做完已删):

✅ #805 → ✅ #807 → ✅ #812 → ✅ #815 → ✅ #833 → ✅ #841 → ✅ #848 → ✅ #855
26 files changed, 3416 insertions(+), 503 deletions(-)
零冲突

也验了「合完还绿不绿」

这是 #843 × #845 栽过的那一格 —— 各自绿、两两不冲突、合起来红。
所以在八个都合完的那棵树上直接跑 #848 新加的门:

workflows_scanned=8
jobs_checked=15
problems=0
OK: 8 个 workflow / 15 个 job,每个都有可执行的内容。   退出码 0

顺带确认 #855 删干净了:合并树里 tests/ 下 test682 目录数 = 0。

另外排掉一个我担心的语义地雷

#803 的标题是「注册三个从没进 CI 的 Docker 门(第四个已过时,另开 issue)」——
那「第四个」正是 #855 要删的 test682。核过 #803 的 qa.yml,它注册的是
test224 / test597 / test679 / test725 / test745 / test746,没有 test682,
其改动的其它文件也零引用。所以 #803 与 #855 不冲突,顺序随意。

结论

这 8 个可以现在就合,顺序随意(#855 等它的 CI 跑完)。
合完之后再动 qa.yml 簇和单测门簇 —— 那两簇必须逐个 rebase,不能并行,原因见本 issue 正文。

[vansin]

第 2 步验完:qa.yml 那一簇按 #798 → #801 → #803 → #843 → #846 可以全部落地

在临时 worktree 里真合了一遍(不碰任何共享分支,做完已删):

#798  ✅ 干净                        qa.yml jobs: 3 → 4
#801  ❌ 冲突 → 解 → ✅               jobs 4,全部 runs-on + steps
#803  ❌ 冲突 → 解 → ✅               jobs 5
#843  ❌ 冲突 → 解 → ✅               jobs 6
#846  ✅ 干净(与所有人都干净,如预测) jobs 7

最终结构自检(用 #848 新加的那道门跑):

workflows_scanned=8   jobs_checked=19   problems=0
qa.yml jobs = 7
  doc-claims          runs-on=ubuntu-latest  steps=3
  agent-network-unit  runs-on=ubuntu-latest  steps=3
  server-unit         runs-on=ubuntu-latest  steps=3
  agent-node-unit     runs-on=ubuntu-latest  steps=3
  recovered-suites    runs-on=ubuntu-latest  steps=8
  qa                  runs-on=ubuntu-latest  steps=6
  doc-source-pins     runs-on=ubuntu-latest  steps=3

没有出现空壳 job。 并且在这棵「五个都合完」的树上,两道新门自己也是绿的:

scripts/check-doc-source-pins.py  → broken_pins=32 baseline=32  OK  退出码 0
scripts/check-doc-claims.py       → claims_failed=0             OK  退出码 0

🔴 更正我在本 issue 正文里写的一句话

我写过「正确解法不是取并集」。这句太绝对了,实测下来要分两种:

• paths: 列表的冲突 → 取并集就是对的。 这一簇的全部 4 处冲突都在
  on.pull_request.paths / on.push.paths 上:一边新增 test798/test601,
  另一边新增 test224/test597/test679/tests/lib,再一边新增 docs-site/test831 ——
  三边各自要监听的路径都该保留,并集是唯一正确的解。
  (#798 × #801 那两处更轻:两边是同一段注释的不同折行,取哪边都行。)

• job 块的冲突 → 取并集会出事。 危险仅存在于两个相邻 job 共享逐字相同的
  runs-on / timeout-minutes / steps: / - uses: actions/checkout@v4 时,
  git 把公共部分只留一份,前一个 job 就只剩 name。那才是「合法 YAML、
  显示绿色、永不执行」。

这一簇实际没有踩到第二种 —— 因为几个 job 的插入点被有意错开了。
但 #848 那道门仍然该合:它是这类错误的自动兜底,而这次是靠人肉确认的。

目前的完整落地路线(两步都已实测)

1. 第一批,顺序随意:docs(server): 写明单测的两条 DB 契约(第二条此前只存在于 qa.sh 里) #805 docs: 英文 troubleshooting 把 latest 的现状写成了历史;并更正 RELEASE-SOP 一句不成立的话 #807 docs: 节点存活判据 —— 看产物推进,不看进程数/started 行 #812 docs: 开 PR 前的自查清单(钉 2026-08-13 当天的真实翻车案例) #815 docs(CLAUDE.md): Dashboard 那行指向的不是产品形态(能打开、标题也对,所以更难发现) #833 ci(test725): agent-node 依赖钉死 —— 提交 lockfile 并改用 npm ci(需要改一行 .gitignore) #841 ci: 加一道 workflow 结构门 —— 挡住「job 名字在、但什么都不会做」 #848 chore: 删掉 test682 这道过时的门,以及 #698 废弃设计留下的两个死模块 (#804) #855
   (已验:依次全合零冲突,合完 #848 的门 problems=0)
2. qa.yml 簇,按序逐个:test(ci): 给 server 补上聚合单测门(69 个单测此前 CI 只跑 6 个) #798 → ci: 元门 —— 新增测试文件不能落在所有聚合门的扫描范围之外(依赖 #798 #800) #801 → ci: 注册三个从没进 CI 的 Docker 门,build-arg 改推导(第四个已过时,另开 issue) #803 → ci(test831): 文档站行号 pin 的下限门(守住不再变多,不解决 #831) #843 → docs: 留一份「陈旧 issue 怎么复核」的做法(四次实核提炼) #846
   (本条,已验;每步解冲突后都跑一次结构自检)
3. 单测门簇:test(ci): 让 test725/test745 覆盖 tests/ 目录(两个门自称 complete 却漏了 25 个文件) #800 → test(ci): 给 src/ 补绝对下限 —— 两道门都放行「大量删除测试文件」(#817) #854 → ci: 元门 —— 新增测试文件不能落在所有聚合门的扫描范围之外(依赖 #798 #800) #801 —— 注意 #801 同时属于第 2 步,
   两条线交汇在它身上,它应当最后合并并重新 rebase。
4. 文档 pin 簇:先 docs(mcp-tools): 章节源码链接改钉符号 —— 实测 17 处行号锚点 17 处全错 #844 / docs(mcp-tools): 正文行号引用改钉符号 —— 两版行号 pin 归零 #845,再 ci(test831): 文档站行号 pin 的下限门(守住不再变多,不解决 #831) #843 并同步缩基线
   —— 但 #843 也在第 2 步里。若按第 2 步先合了 #843,之后合 #845 会让它变红
   (18 条基线条目会失去引用),届时必须在 #845 里同步缩基线。这是本 issue
   正文那条语义冲突的具体后果,别忘。

[vansin]

第 3 步验完:单测门簇 #800 → #854 → #801 可以落地,但这一簇踩到了危险形态

同样在临时 worktree 里真合(做完已删):

#800  ✅ 干净                → 两条 tests/ floor 就位(5 / 15)
#854  ❌ 冲突(仅 test725,1 块) → 解 → ✅
#801  ❌ 冲突(仅 report txt,22 块,门本身零冲突) → 解 → ✅

最终:两个 run.sh 都 bash -n 退出码 0,四条 floor 全部幸存:

AGENT_NODE_SRC_FLOOR=80      AGENT_NODE_TESTS_FLOOR=5
AGENT_NETWORK_SRC_FLOOR=40   AGENT_NETWORK_TESTS_FLOOR=15

真实计数都在下限之上:agent-network/src 46>40、agent-node/src 91>80、
agent-network/tests 19>15、agent-node/tests 6>5。

🔴 #800 × #854 这处冲突,和 qa.yml 那簇性质不同 —— 别照搬解法

两侧都在同一个锚点(grep -Eq '^0 fail$' ... })之后插入新块,而两侧的块都被冲突
截断在 || { 中间 —— 下方那两行

  exit 1
}

是公共上下文,同时属于双方。所以:

• 取并集 → 两个 || { } 块被套在一起,少一个收尾。实测 bash -n:
  syntax error: unexpected end of file。
• 取一侧 → 直接丢掉另一侧的整块(要么没了 tests/ 的 floor,要么没了
  executed >= discovered),而且语法完全正常,不会有任何报错。

正确解法:给先出现的那一块补一份自己的 exit 1 },后一块沿用公共上下文。
解完两边都完整,bash -n 退出码 0,四条 floor 都在。

和 YAML 那次的关键差别

	盲目取并集的后果
qa.yml 的 job 块	静默合法 —— job 出现在检查列表里、显示绿色、永不执行
run.sh 的 || { } 块	语法错误 —— 当场炸,不会静默

bash 这次是「响的」,YAML 那次是「哑的」。真正要防的是取一侧:
它在两种语言里都不报错,只是悄悄少一道门。

一处我自己的测量错误(记下来)

我第一次判并集结果时写的是

bash -n /tmp/naive725.sh 2>&1 | head -3 | sed 's/^/    /' && echo "语法通过"

&& 接的是 sed 管道的退出码,不是 bash -n 的 —— 于是明明报了语法错误,
我这行还打印了「语法通过」。改成单独跑 bash -n 才拿到真结果。
(和 pipefail/tee 吞退出码是同一类。)

四步全部实测完毕

1. 第一批顺序随意:docs(server): 写明单测的两条 DB 契约(第二条此前只存在于 qa.sh 里) #805 docs: 英文 troubleshooting 把 latest 的现状写成了历史;并更正 RELEASE-SOP 一句不成立的话 #807 docs: 节点存活判据 —— 看产物推进,不看进程数/started 行 #812 docs: 开 PR 前的自查清单(钉 2026-08-13 当天的真实翻车案例) #815 docs(CLAUDE.md): Dashboard 那行指向的不是产品形态(能打开、标题也对,所以更难发现) #833 ci(test725): agent-node 依赖钉死 —— 提交 lockfile 并改用 npm ci(需要改一行 .gitignore) #841 ci: 加一道 workflow 结构门 —— 挡住「job 名字在、但什么都不会做」 #848 chore: 删掉 test682 这道过时的门,以及 #698 废弃设计留下的两个死模块 (#804) #855 ✅
2. qa.yml 簇:test(ci): 给 server 补上聚合单测门(69 个单测此前 CI 只跑 6 个) #798 → ci: 元门 —— 新增测试文件不能落在所有聚合门的扫描范围之外(依赖 #798 #800) #801 → ci: 注册三个从没进 CI 的 Docker 门,build-arg 改推导(第四个已过时,另开 issue) #803 → ci(test831): 文档站行号 pin 的下限门(守住不再变多,不解决 #831) #843 → docs: 留一份「陈旧 issue 怎么复核」的做法(四次实核提炼) #846 ✅
3. 单测门簇:test(ci): 让 test725/test745 覆盖 tests/ 目录(两个门自称 complete 却漏了 25 个文件) #800 → test(ci): 给 src/ 补绝对下限 —— 两道门都放行「大量删除测试文件」(#817) #854 → ci: 元门 —— 新增测试文件不能落在所有聚合门的扫描范围之外(依赖 #798 #800) #801 ✅(本条)
4. 文档 pin 簇:docs(mcp-tools): 章节源码链接改钉符号 —— 实测 17 处行号锚点 17 处全错 #844 / docs(mcp-tools): 正文行号引用改钉符号 —— 两版行号 pin 归零 #845 与 ci(test831): 文档站行号 pin 的下限门(守住不再变多,不解决 #831) #843 的基线语义冲突 —— 已量化(18 条),未实合

#801 同时出现在第 2、3 步:两条线交汇在它身上,它应当最后合并并重新 rebase。
另外 #801 与 #800 的冲突全在 docs/tests/report-pkg-tests-dir-gate.txt ——
那是运行记录,合并后两侧都不再准确,正解是重跑生成而不是挑一边。

[vansin]

🔴 更正:我在本 issue 正文里写的那条「文档 pin 簇语义冲突」是错的

我在正文写过:

#845 移除的 43 个 pin 里,18 个正是 #843 基线文件里的条目……
所以 #843 与 #845 谁后合,谁就得先缩基线。两个 PR 各自都绿、两两也不冲突,合起来红。

这句不成立。 第 4 步实合下来,两种顺序都是绿的:

顺序 A:#843 → #844 → #845
  合 #843 后   broken_pins=32  baseline=32   OK  退出码 0
  合 #844 后   broken_pins=23  baseline=23   OK  退出码 0
  合 #845 后   broken_pins=5   baseline=5    OK  退出码 0

顺序 B:#845(含 #844)→ #843
  合 #845 后   基线条目=5
  合 #843      干净,合并后基线条目仍为 5
  门           broken_pins=5   baseline=5    OK  退出码 0

我错在哪

#844 和 #845 各自都带着缩好的基线:

#843 基线 pin 条目 = 32
#844 基线 pin 条目 = 23     （diff 里确实改了 docs/doc-source-pins-baseline.txt）
#845 基线 pin 条目 = 5      （同上）

它们是叠着做的,移除 pin 和缩基线在同一个 PR 里同步发生。所以合并之后
两边天然对齐,根本不会出现「基线里有已失去引用的残留」。

我当时只做了一侧的检查:「#845 移除的 pin 里,有多少在 #843 的基线里?」——
算出 18,就下了结论。我没有问另一侧:「#845 是不是也同时缩了基线?」
而这个问题的答案(是,32→23→5)直接推翻了结论。

教训:跨 PR 的交互有两侧。只查一侧就断言「合起来会红」,那不是证据,是猜测。
这和我一直在别人 PR 上强调的「断前提、别断结论」是同一条,这次栽在自己身上。

修正后的第 4 步结论

文档 pin 簇 #843 / #844 / #845 顺序随意,合完门自己是绿的。
它可以并入第 1 批(顺序随意那一批)一起走。

正文里那段「语义冲突」的描述请以本条为准。作为一般性风险它仍然存在
(基线型的门,pin 与基线必须同步缩),只是这三个 PR 恰好都做对了。

[vansin]

🔴 更正:我给的合并路线只验了「能不能合」,没验「合进去是不是绿的」

我在本 issue 里分四步验过合并顺序,用的是 git merge-tree / 真合 + 结构自检。那些验证回答的是能不能合进去。

今天扫全部 open PR 的 CI,发现 5 个 PR 的 CI 是红的,其中两个就在我给的路线里:

#801  server unit (Docker, non-root)     FAILURE   ← 在「qa.yml 簇」路线里
#803  recovered suites (Docker)          FAILURE   ← 同上
#845  L0 + L1 (report-only)              FAILURE
#835  L0 + L1 (report-only)              FAILURE
#460  no bare rm -rf $VAR                FAILURE

「mergeable + 能按序合入 + 结构自检过」不等于「CI 绿」。 我那四步都没查 check 状态,这是路线本身的一个缺口,不是执行时的疏忽 —— 判据里就没有这一项。

#801 的根因我已诊断并写在那条 PR 上(#801 的评论):run.sh 要求 TEST798_RUNSH_BLOB、Dockerfile 接了线,但 qa.yml 的 docker build 从没传这个 build-arg,ARG 取空 → fail-closed。门是对的,缺的是供给那一行。

修正后的路线判据应当是三项齐备:① 能合(merge-tree/真合)② 合后结构自检过 ③ 该 PR 自身 CI 绿。目前第 ③ 项上,qa.yml 簇的 #801/#803 未过。

另:open PR 已从 29 增到 33,有非 bot 评审的仍只有 3 个(#800/#834/#841,且都是我自己写的评审)。

[vansin]

三处更正(都是我自己的错,逐条给出实测)

一、🔴「评审端 0 进展」是我量错了字段,不成立

我上一条写过「33 个 PR,只有 3 个有非 bot 评审,且都是我自己写的」。错的。

我用的是 gh pr view --json reviews —— 那只返回 GitHub 的 formal review。
而独立深审是以 PR comment 形式发的,那个查询结构上就看不到。实测:

#846 / #851 / #854 / #855 / #798 / #848 的 reviews 字段：全是 0
同一批 PR 的 comments 字段：逐条都在，时间戳集中在 08-13 15:35–16:19，
                            标题都写着「独立深审结论」

已完成的深审结论(comment 里):
CLEAN — #800 / #846 / #851 / #854 / #855;
BLOCKER — #801 / #803;MAJOR — #798 / #848。

共 9 条。 我那句「0 进展」作废。
拿一个看不到目标对象的字段去量,得到的是零信息结论 —— 这条我在别人 PR 上强调过很多次。

二、合并路线缺一项判据(已在上一条提过,这里给结果)

路线只验了「能不能合」,没验「CI 是否绿」。补验后 5 个红,其中两个已修:

#801  server unit (Docker, non-root)   FAILURE → 修复 cb2c6aab → **现在 SUCCESS**
#803  recovered suites (Docker)        FAILURE → 修复 134af215 → 跑中
#845 / #835  L0 + L1 (report-only)     仍红,未诊断
#460  no bare rm -rf $VAR              仍红,未诊断

#801 的根因是 qa.yml 的 docker build 从没传 RUNSH_BLOB(run.sh 要求、Dockerfile 接线、
workflow 不供给);#803 是 root 容器写的产物 mode 0600,upload-artifact 以 runner 用户
打包时 EACCES —— 门全绿,红在上传。两条根因各自写在对应 PR 上。

三、🔴 文档簇不是「三个独立 PR」,是一个栈

我在本 issue 写过「#843/#844/#845 顺序随意」。结论没错,但说法有误导 ——
它们根本不是三个可以独立排序的 PR。实测:

git merge-base --is-ancestor <843-head> <844-head>   → 是
git merge-base --is-ancestor <844-head> <845-head>   → 是
git merge-base --is-ancestor <843-head> <845-head>   → 是（栈顶含全部）

#843 ⊂ #844 ⊂ #845。所以「顺序随意」的真实原因是:合栈顶 #845 就把三个都带进来了,
根本不存在排序问题。正确的说法是 审/合栈顶 #845 即可,不是「挑一个先合再逐个 rebase」。

这也让我更早那条「#843 与 #845 有语义冲突」错得更彻底:不只是因为 #845 同步缩了基线,
更因为 #843 的内容本来就在 #845 里面。

---

综上,本 issue 正文里那份「四步落地路线」在两处需要修订(加 CI 判据、文档簇改为审栈顶),
「27/30 个 PR 零深审」那个数也不成立。正文我不改(保留原始判断以便追溯),以本条为准。

[vansin]

补一条:新开的 PR #863(修四个 qa-hub 套件)与现有动 tests/ 的 PR 两两都不冲突,单独并入 main 也干净。

#863 × #800  干净        #863 × #854  干净
#863 × #835  干净        #863 × #803  干净
#863 → main  干净

原因是它只改 tests/qa-hub-1{0,1,2,3}/run.sh 四个文件,而那四个文件没有任何其他 open PR 碰过 —— 这也是它们成为孤儿的另一面:没人动它们,自然也不会冲突。

按本 issue 的判据(① 能合 ② 合后结构自检 ③ 该 PR 自身 CI 绿),#863 目前:

• ① 干净;
• ③ 6 绿 / 3 跑中 / 0 红(含 L0 + L1、两个 Docker 单测门、no hardcoded from_session)。

所以它可以并入本 issue 的**「顺序随意」第一批**,不需要排在任何簇里。

[vansin]

合并顺序:合并清单(2026-08-14 02:37 CST 逐条复核过状态)

前面几条评论是分批验的,这里合并成一份。每一行的 mergeable/CI 状态都是刚查的,不是凭记忆。

当前 34 个 open PR 里,与本 issue 相关的 21 个:20 个 MERGEABLE 且全绿,1 个(#460)CONFLICTING 且红。

第 1 批 —— 顺序随意,可立即合(已实测:依次合入零冲突,合后结构自检 problems=0)

#805  #807  #812  #815  #833  #841  #848  #855

加两个后来验的,同样零重叠、全绿:

#863  （只改 tests/qa-hub-1{0,1,2,3}/run.sh —— 无任何其他 open PR 碰过这四个文件）
#858  （只改 docs/qa/weekly/2026-W19.md）

→ 第 1 批共 10 个。

第 2 批 —— qa.yml 簇,必须按序、逐个 rebase

#798 → #801 → #803 → #843 → #846

已实测走通(临时 worktree 真合,每步解完跑一次结构自检)。四处冲突全在 on.*.paths 列表上,
取并集是正确解;#846 与所有人都干净。
🔴 注意 job 块的冲突不能取并集(会产出「合法 YAML、显示绿色、永不执行」的空壳 job),
本簇实际没踩到,因为几个 job 的插入点被有意错开了。

第 3 批 —— 单测门簇

#800 → #854 → #801

#801 同时属于第 2、3 批 —— 它应当最后合并并重新 rebase。
🔴 #800 × #854 的冲突要小心:两侧的块都被截断在 || { 中间,下方的 exit 1 } 属于双方。
取并集 → bash 语法错(会响);取一侧 → 悄悄少一道门(不会响)。
正解:给先出现那块补一份自己的 exit 1 }。

第 4 批 —— 文档 pin 栈

#843 ⊂ #844 ⊂ #845   （实测：三次 merge-base --is-ancestor 全为真）

它们是一个栈,不是三个独立 PR。审/合栈顶 #845 即可,会把三个都带进来。
(注意 #843 也出现在第 2 批 —— 若第 2 批已按序合过它,这里就只剩 #844/#845 的增量。)

被阻塞的

#460  CONFLICTING + CI 红（no bare rm -rf $VAR，5 处，确由该 PR 引入）
      需作者 rebase + 改用 safe_rm_rf；诊断已在该 PR 上。

与 PR 无关但有顺序要求的一条

#858（编码修复）必须早于 #852 的「把 DOC_ROOT 扩到 docs/」

实测:docs-site/ 106 个文件 0 个盲区;docs/ 181 个文件 1 个会被 checker 静默跳过 ——
就是 #858 修的那个。先扩范围就等于带着一个看不见的洞。

判据说明

本清单的每一行都满足三项(这三项是本 issue 早前更正过的判据):

1. 能合 —— git merge-tree 干跑 / 临时 worktree 真合;
2. 合后自检 —— 结构门 problems=0;
3. 该 PR 自身 CI 绿 —— 刚逐条查过。

第 3 项是我最初漏掉的一项,补上之后才发现 #801/#803 当时是红的(现已修复转绿)。

[vansin]

🔴 更正我在正文里的一条推断,并补一类正文没写到、数量是冲突三倍的风险

我把正文里那张冲突图重新用真合并验了一遍(临时 worktree,合完即删)。
一条更正、一个新发现。

---

一、更正:「#843 与 #845 合起来会红」——实测是绿的

正文里我写:

文档 pin 那一簇 #843 / #844 / #845 两两文本干净,但合起来会让门变红
…… 谁后合,谁就得先缩基线。

这条是错的。 我真按顺序合了,并跑了那道门自己的 checker(不是我另写的等价物):

main ← #843 ← #844 ← #845     三次 merge 全部干净
python3 scripts/check-doc-source-pins.py
  broken_pins=5   baseline_entries=5
  OK: 失效 pin 5 个,基线 5 条 —— 没有新增,也没有该清的残留。      退出码 0

反序 main ← #845 ← #844 ← #843   同样全干净
  broken_pins=5   baseline_entries=5   退出码 0

两个顺序都绿,与合并顺序无关。

我当初为什么会算错:我做的是静态求交 ——「#845 移除 43 个 pin,其中 18 个在 #843 的基线里
→ #843 的门会报『基线里有残留』」。这个推理默认了基线文件在合并后还是 #843 那一份。
但 docs/doc-source-pins-baseline.txt 本身就同时被 #843/#844/#845 三个 PR 改,
它在合并里一起被合掉了:合成后是 5 条,不是 #843 的 32 条,正好对上合成后的 5 个失效 pin。

预测两个 PR 的语义冲突时,不能把一方的文件按住不动 —— 如果另一方也改了那个文件,
它会跟着一起变。唯一可靠的做法是真合一次,然后跑那道门自己的判据。

---

二、新发现:内容分歧却不冲突的文件有 45 处,是可见冲突(15)的三倍

正文只统计了「merge-tree 报冲突」的对。但更该担心的是另一类:
两个 PR 把同一个文件改成了不同内容,git 却不报冲突,直接合成一个谁都没审过的版本。

对全部 34 个 open PR 的 29 个共改文件、33 组 PR 对逐一实测:

两 PR 改成完全一样            1 处
内容不同、会冲突（会被看见）  15 处
🔴 内容不同、**不冲突**       45 处   ← 静默混合

集中在这些文件(括号是 PR 对):

.github/workflows/qa.yml                    (798,846) (801,846) (803,846) (843,846)
tests/test745-…-unit-ci/run.sh              (800,801) (800,854) (801,854)
tests/test831-doc-source-pins/run.sh        (843,844) (843,845) (844,845)
tests/test725-…-unit-ci/run.sh              (800,801)
tests/test798-server-unit-ci/run.sh + Dockerfile   (798,801)
scripts/qa.sh                               (803,823) (823,835)
scripts/check-doc-source-pins.py            (843,845)
agent-node/src/cli.ts                       (825,826) (825,836) (826,836)   ← 产品代码
agent-node/src/runtime/grok-copresence/*.ts (826,830) (826,836) (830,836)   ← 产品代码
docs-site/docs/{,en/}api/rest.md            (809,810) (809,845) (810,845)

门的执行脚本、门的容器、门的 checker、门的基线,四类全在里面。

我逐个把高风险的真合出来看了,结论是目前都碰巧是自洽的

scripts/qa.sh  #823×#835   248 行  bash -n 通过
   · 我加的 no-git 兜底 `git rev-parse HEAD 2>/dev/null || true` 还在 (:185)
   · #823 的并发上限注释与实现也还在 (:210)      → 两边的意图都保住了

test831 run.sh 三方           321 行  bash -n 通过,基线校验 17 处
test798 run.sh #798×#801      RUNSH_BLOB 命中 5 处,与 qa.yml:95 的 build-arg 对得上

但「碰巧自洽」不是保证。 scripts/qa.sh 那一处尤其:#835 那次修的正是
「无 git 环境下 set -euo pipefail 直接中止 → 峰值采成 0」的静默失败。
同一个文件被另外两个 PR 各改各的、还不冲突 —— 这一行兜底要是在某次合并里被吃掉,
症状是门"绿着但没测",不是报错。

建议(比正文的合并顺序更根本)

1. 正文那份合并顺序照旧有用,但判据要换:不是「merge-tree 干净就放行」,
   而是合完真跑一次那道门自己的脚本。上面的更正就是这么被抓出来的。
2. 对上面 45 处里落在 tests/**/run.sh、scripts/*.sh|*.py、.github/workflows/*、
   agent-node/src/** 的那部分,合并前通读一遍合成体再点 merge。
3. 这类风险 CI 天然看不见:每个 PR 单独跑绿,合成体从来没被任何一次 CI 执行过。

(全部只读:两个临时 worktree 已 git worktree remove 清理;未改任何 PR、未 approve、未 merge。
scripts/qa.sh 里那条兜底是我在 #835 加的,此处只陈述它在合成体里的存续状态。)

[vansin]

🔴 再更正一条:正文里那个「取并集会合出空壳 job」的例子,实测复现不出来

上一条我更正了「#843×#845 合起来会红」(实测绿)。这次把正文另一条静态推断也跑了 ——
同样不成立。两条都错在一件事上:我在推理,没有真合。

正文的原话

.github/workflows/qa.yml 上「按冲突块取并集」会产出:

doc-source-pins:
  name: doc source-pin floor (Docker)     ← 到此为止,没有 runs-on、没有 steps

这是合法 YAML,GitHub 接受它,job 名字出现在检查列表里并显示绿色。

实测:10 对两两组合 + 五个全合,一个空壳都没有

临时 worktree,从 origin/main 起,冲突一律按并集解(脚本自动去 marker、两边都留),
然后跑 #848 那道结构门自己的脚本:

#798×#801 冲突→并集   4 job  空壳=无  缺runs-on=无   门 OK
#798×#803 冲突→并集   5 job  空壳=无  缺runs-on=无   门 OK
#798×#843 冲突→并集   5 job  空壳=无  缺runs-on=无   门 OK
#801×#803 冲突→并集   5 job  空壳=无  缺runs-on=无   门 OK
#801×#843 冲突→并集   5 job  空壳=无  缺runs-on=无   门 OK
#803×#843 冲突→并集   5 job  空壳=无  缺runs-on=无   门 OK
#798×#846 静默合并    5 job  空壳=无  缺runs-on=无   门 OK
#801×#846 静默合并    5 job  空壳=无  缺runs-on=无   门 OK
#803×#846 静默合并    5 job  空壳=无  缺runs-on=无   门 OK
#843×#846 静默合并    5 job  空壳=无  缺runs-on=无   门 OK

五个顺序全合(798→801→803→843→846,冲突一律并集)也一样:

job 数 7
  doc-claims           steps=3  runs-on=True
  agent-network-unit   steps=3  runs-on=True
  server-unit          steps=3  runs-on=True
  agent-node-unit      steps=3  runs-on=True
  recovered-suites     steps=9  runs-on=True
  qa                   steps=6  runs-on=True
  doc-source-pins      steps=3  runs-on=True
OK: 8 个 workflow / 19 个 job,每个都有可执行的内容。

顺带修正一个事实错误:正文把 doc-source-pins 和 doc-claims 说成会互相截断的两个块,
但 doc-claims 是 #846 引入的,而 #846 与 #843 在 qa.yml 上根本不冲突(静默合并),
所以那两个块之间压根不会产生需要"取并集"的冲突 —— 我举的例子里那对组合不存在。

但「门是不是瞎的」我也验了 —— 它会红

"到处都 OK" 有两种可能:门有效,或门根本抓不到。所以我把正文描述的那个形态真造出来:

在 jobs: 下注入
  doc-source-pins:
    name: doc source-pin floor (Docker)      # 只有 name

FAIL: [no-runs-on] .github/workflows/qa.yml :: doc-source-pins
FAIL: [bad-steps]  .github/workflows/qa.yml :: doc-source-pins ——
      steps 必须是非空列表(收到 NoneType),这个 job 什么都不会做
problems=2                                                        退出码 1

所以结论要分成两半,别混着说:

• ✅ 那个危险形态是真的,而且 ci: 加一道 workflow 结构门 —— 挡住「job 名字在、但什么都不会做」 #848 那道门确实抓得到(上面是见证到的真红);
• ❌ 但本仓库这五个 PR 的任何组合都产不出它 —— 我把一个"可能的形态"写成了"会发生的结果"。

我两条推断都错的共同原因

我写的	实测	错因
#843×#845 合起来门会红	两个顺序都绿(5/5,退出码 0)	静态求交时按住了基线文件不动,而它被三家同时改
qa.yml 取并集会出空壳 job	10 对 + 五全合,一个都没有	把门能抓的形态当成了合并会产出的结果

正文里那张「6/10 对冲突」的实测图仍然成立(那是 merge-tree 跑出来的)。
错的是所有基于它往下的推论。 判两个 PR 能不能一起合,只有一条路:
真合一次,跑那道门自己的脚本。

(全部只读:worktree 用完即 git worktree remove;未改任何 PR、未 approve、未 merge。)

[vansin]

收口:这堆 PR 到底该怎么验才算验过(四轮实测汇总)

正文写的是「哪些会冲突」。四轮下来我发现那不是真正的风险点,
而且我基于它做的两条推断都被自己的实测推翻了。这条把结论收干净,给接手合并的人一份能照做的东西。

一、真正的风险点:分歧但不冲突,数量是可见冲突的三倍

	处数
两个 PR 改成完全一样	1
内容不同、会冲突(会被人看见)	15
🔴 内容不同、不冲突(静默合成一个没人审过的版本)	45

落点覆盖 .github/workflows/qa.yml、四个门的 run.sh、门的 Dockerfile、
scripts/qa.sh、check-doc-source-pins.py,以及 agent-node/src/cli.ts 和
grok-copresence/*.ts(产品代码)。

CI 天然看不见这一类:每个 PR 各自跑绿,合成体从来没被任何一次 CI 执行过。

二、这 45 处我逐组验完了 —— 目前没有一处产出坏合成体

组	怎么验的	结果
qa.yml 五个 PR	10 对两两 + 五个顺序全合,冲突一律按并集解,跑 #848 结构门	空壳 job 0,门全 OK
文档 pin 三方 (#843/#844/#845)	正反两个合并顺序,跑 check-doc-source-pins.py	都绿,broken=5 baseline=5,与顺序无关
test798 run.sh (#798×#801)	读合成体 + 核 build-arg 链	RUNSH_BLOB / ARG / qa.yml:95 三层对得上
产品代码 5 组 (#825/#826/#830/#836)	真合 + Docker 门 test725	1284 pass 0 fail RESULT: PASS

所以结论要说准:风险是过程性的(没人审过合成体),不是已发生的缺陷。

三、门不是瞎的 —— 见证过真红

"到处都 OK" 有两种可能:门有效,或门根本抓不到。所以我把正文描述的危险形态真造出来:

在 jobs: 下注入   doc-source-pins:  name: doc source-pin floor (Docker)   # 只有 name

FAIL: [no-runs-on] .github/workflows/qa.yml :: doc-source-pins
FAIL: [bad-steps]  steps 必须是非空列表(收到 NoneType),这个 job 什么都不会做
problems=2                                                          退出码 1

→ 那个形态是真的、#848 抓得到;但本仓库这五个 PR 的任何组合都产不出它。

四、给接手合并的人:三步

1. 别用 merge-tree 干净当放行判据。 它只回答"会不会有冲突标记",
   不回答"合出来的东西对不对"。
2. 真合一次(临时 worktree),然后跑那道门自己的脚本。
   两条被推翻的推断都是死在这一步上 —— 我推理了,没有跑。
3. 落在这些路径上的静默混合,合并前通读合成体:
   tests/**/run.sh、tests/**/Dockerfile、scripts/*、.github/workflows/*、*/src/**。
   其中 scripts/qa.sh 最值得看一眼:它里面那行
   git rev-parse HEAD 2>/dev/null || true 是为了防"无 git 环境下 set -euo pipefail
   直接中止 → 峰值采成 0"的静默失败。这行要是在某次合并里被吃掉,
   症状是门『绿着但没测』,不报错。(实测目前还在,:185。)

五、附:本机跑单测不能用来判断产品代码那几组

同一棵合成体:宿主 bun test src/ = 42 红,进 Docker = 0 红。
42 条全部落在 runtime.test.ts(39)+ grok-build-cli-home.test.ts(3),
原因是单测去抢本机真实节点持有的 /tmp 全局锁(35 条)、以及 socket 路径超长(换 TMPDIR 后 40 条)。
细节与建议已单独立为 #865。

这一点直接影响本 issue 的用法:任何"我在本机跑过,没新增失败"的说法,
在 grok-copresence 那块是无效证据。 那块只有 Docker 门算数。

我怎么会错两次

我写的	实测	错因
#843×#845 合起来门会红	两序都绿	静态求交时按住了基线文件不动,而它被三家同时改,会跟着一起合
qa.yml 取并集会出空壳 job	10 对+五全合都没有	把门能抓的形态当成了合并会产出的结果

两次都是"没真合就下结论"。正文那张 merge-tree 冲突图仍然有效,错的是所有基于它往下的推论。

(全部只读:所有临时 worktree 已 remove,自建镜像已 rmi;未改任何 PR、未 approve、未 merge。)