3 个 L1 套件(test686/765/766)不在 qa.yml 的 paths 里:改它们不会触发跑它们的门

[vansin]

现状:3 个 L1 套件改了不会触发跑它们的那道门

scripts/qa.sh 的 L1_TESTS 有 17 个套件,由 qa.yml 的 qa job 执行。
把这 17 个逐个与 qa.yml 的 paths: 过滤比对:

套件	paths 覆盖
qa-cli-01 … qa-node-03b(13 个)	✅ 被 tests/qa-*/** 覆盖
test746-setup-bun-pin	✅ paths 里显式列了
test686-rest-shape-golden	❌
test765-batch-runtime-gate	❌
test766-bunx-preflight	❌

qa.yml 的 paths: 原文(origin/main):

pull_request.paths:
  server/**
  agent-network/**
  agent-node/**
  tests/qa-*/**
  scripts/qa.sh
  docs/qa/**
  .github/workflows/qa.yml
  tests/test725-agent-node-unit-ci/**
  tests/test745-agent-network-unit-ci/**
  tests/test746-setup-bun-pin/**

显式列了 test725 / test745 / test746,唯独漏了这三个;也没有 tests/** 这类兜底。

没有别的 workflow 兜底

$ git grep -c 'test686\|test765\|test766' origin/main -- '.github/**'
（三个都是 0 个文件命中）

全部 workflow 里提到 qa.sh 或这三个套件的：只有 .github/workflows/qa.yml

所以这三个套件在整个 CI 配置里没有被任何 paths 提及过。

后果

一个只改 tests/test686-rest-shape-golden/**(或 765 / 766)的 PR,
不会触发 qa.yml —— 跑它们的那道门根本不启动。把这三个门本身改坏、
改成永远通过、甚至删掉它们的断言,PR 都会全绿,要等别的改动顺带触发才暴露。

对照:test725 / test745 有自己的 Docker job 并且在 paths 里,不存在这个问题。

这是同一形状的第三例

• ci: 元门 —— 新增测试文件不能落在所有聚合门的扫描范围之外(依赖 #798 #800) #801:run.sh 要求 TEST798_RUNSH_BLOB、Dockerfile 接了线,
  qa.yml 的 docker build 从没传 → ARG 空 → fail-closed。
• test(#823): 给 L1 并发上限闸门补 Docker 回归(含变异见证) #835:套件加进了 L1_TESTS,qa.sh 的逐套件白名单没登记 →
  TEST823_SOURCE_COMMIT 空串。
• 本条:套件加进了 L1_TESTS,qa.yml 的 paths 没登记 → 门不触发。

共同点是**「在一处注册,在另一处忘了登记」**,而两处之间没有任何机制保证同步。
#835 那次的修法是把成因去掉(逐套件白名单 → 按套件名推导),
这里同样可以根除,而不是再补三行:

• 加 tests/**(最省事,代价是任何 tests/ 改动都会触发整个 qa job);
• 或让 paths 由 L1_TESTS 生成 / 加一道门断言「L1_TESTS 里每个套件的目录都在 paths 里」
  —— 后者与 ci: 元门 —— 新增测试文件不能落在所有聚合门的扫描范围之外(依赖 #798 #800) #801 的元门(ci: 元门 —— 新增测试文件不能落在所有聚合门的扫描范围之外(依赖 #798 #800) #801 本身就是「新增测试文件不能落在所有聚合门的扫描范围之外」)是同一类思路。

本 issue 只记录,未改动任何文件。

顺带:一处 push / pull_request 不对称

pull_request.paths 里有 docs/qa/**,push.paths 里没有。
不影响本条结论,但同一个 workflow 的两个触发器过滤不一致,通常不是有意的。

复现(只读)

git show origin/main:scripts/qa.sh | sed -n '/^L1_TESTS=(/,/^)/p'
git show origin/main:.github/workflows/qa.yml   # 看 on.*.paths
git grep -c 'test686\|test765\|test766' origin/main -- '.github/**'

[vansin]

复核仍成立,并补一条可验收的完成标准

一、复核(2026-08-14,origin/main)

                                qa.sh 里出现   qa.yml 里出现
test686-rest-shape-golden            2 次          0 次
test765-batch-runtime-gate           2 次          0 次
test766-bunx-preflight               2 次          0 次

qa.yml 的 paths: 里与 tests/ 有关的条目只有 4 条(pull_request 与 push 各一份):

tests/qa-*/**
tests/test725-agent-node-unit-ci/**
tests/test745-agent-network-unit-ci/**
tests/test746-setup-bun-pin/**

正文结论仍然成立。

🔴 二、写判据时的一个坑:paths 是 glob,不能用字面匹配去核

我把 qa.sh 点名的 17 个套件逐个做 glob 展开后比对:

未被任何 path glob 覆盖的：3 个
  test686-rest-shape-golden   test765-batch-runtime-gate   test766-bunx-preflight

正好就是本条说的三个。但如果判据写成"套件名是否字面出现在 qa.yml 里",
会把 qa-* 那 14 个也报成未覆盖(它们靠 tests/qa-*/** 这条 glob 命中,名字并不出现)。
—— 一个更严的判据反而会给出更大的假阳性。做这条时请用 fnmatch,不要用 grep 名字。

三、完成标准

① 修法:把三条加进 qa.yml 的 paths:(pull_request 与 push 两处都要,现在是各一份):

      - 'tests/test686-rest-shape-golden/**'
      - 'tests/test765-batch-runtime-gate/**'
      - 'tests/test766-bunx-preflight/**'

② 见证:改了这三个套件之一,qa workflow 必须真的被触发

在一个 PR 里只改 tests/test686-rest-shape-golden/run.sh（比如加一行注释），
然后看 Actions：`anet QA (v0)` 应当出现在该 PR 的 checks 里。
修之前它不会出现 —— 这一红一绿都要贴。

只贴"我把三行加进去了"不算 —— paths 写错缩进/写错目录名都不会报错,只会静默不触发。

③ 防回归(建议,和 #861 的门可以合并):一条判据断言
「scripts/qa.sh 的 L0/L1 列表里每个套件,都必须被 qa.yml 的某条 path glob 覆盖」,
实现用 fnmatch(见上面第二节)。这样以后新增 L1 套件忘了加 path 会直接红。

这条判据本身也要见证红:临时从 paths 里删掉 tests/test725-.../** → 期望 FAIL。

四、为什么值得做

这三个套件的现状是:它们在 CI 里跑得到,但改它们不会触发跑它们的那条 workflow。
也就是说,有人改坏 test686 的判据、CI 不会立刻告诉他;
要等下一次有人碰了 server/** 或 qa.sh 才顺带跑到。
"门存在"和"门在你改它的时候会跑"是两件事。

(扫描范围:origin/main 的 scripts/qa.sh 与 .github/workflows/qa.yml;
glob 展开用 fnmatch。未改任何文件。)

[vansin]

复核:在 origin/main@034f0064 上完全一致

程序化比对 scripts/qa.sh 的 L1_TESTS 与 .github/workflows/qa.yml 的 pull_request.paths:

L1_TESTS            17 个   ← 与正文一致
paths 条目          10 条
  ✅ 被覆盖         14
  🔴 未覆盖          3   test686-rest-shape-golden
                        test765-batch-runtime-gate
                        test766-bunx-preflight

与正文点名的三个完全相同,无增无减。这条 issue 在当前 main 上仍然成立。

[vansin]

补一个正文没覆盖的点:qa.yml 有两个 paths 列表,缺的是同样 3 个

正文引的是 pull_request.paths。实际 qa.yml 里有两个 paths 列表:

on.pull_request.paths          10 条  → 未覆盖 3: test686 / test765 / test766
on.push(branches:[main]).paths  9 条  → 未覆盖 3: 同样这 3 个

只补 pull_request.paths 会让 main 推送那条继续瞎。 已做变异验证:
只补第一个列表时,检查器仍然报 RED(paths[1] 未覆盖 3)。

顺带发现两个列表本身还不一致:pull_request 多一条 docs/qa/**,push 没有。
不属于本 issue 范围,单独记一笔。

最小补丁(两个列表各补 3 行,已 patch --dry-run 干净应用到 origin/main@034f0064)

@@ -22,6 +22,9 @@
        - 'tests/test746-setup-bun-pin/**'
+      - 'tests/test686-rest-shape-golden/**'
+      - 'tests/test765-batch-runtime-gate/**'
+      - 'tests/test766-bunx-preflight/**'
   push:
@@ -34,6 +37,9 @@
        - 'tests/test746-setup-bun-pin/**'
+      - 'tests/test686-rest-shape-golden/**'
+      - 'tests/test765-batch-runtime-gate/**'
+      - 'tests/test766-bunx-preflight/**'

补完 yaml.safe_load 仍能解析,jobs 3 个不变,两个列表变成 13 / 12 条。
补丁形态与已有的 test725/745/746 三行完全一致,不引入新写法。

顺手做了一道防复发的不变量检查(待落地,未开 PR)

判据:scripts/qa.sh 的 L1_TESTS 里每个套件,必须被 qa.yml 的每一个 paths 列表覆盖。
「每一个」是重点 —— 就是上面那个只补一半的坑。

退出码 0 通过 / 1 真问题 / 2 判不了,并打结论行 L1PATHS: GREEN|RED|UNKNOWN。
六条路径都走过:

场景	结果
origin/main 原样	RED — 两个列表各缺 3,共 6 处
打完上面的补丁	GREEN
只补 pull_request、不补 push	RED — 证明「每一个」不是摆设
qa.sh 里没有 L1_TESTS=(...)	UNKNOWN L1-TESTS-NOT-FOUND
L1_TESTS 为空	UNKNOWN L1-TESTS-EMPTY（空集合必然全覆盖,不是绿）
qa.yml 里解析不到任何 paths	UNKNOWN NO-PATHS-BLOCK（「没写 paths=全触发」和「解析失败」结论相反,分不出来就不报绿）

已知边界:覆盖判定用 fnmatch 近似 GitHub 的 glob(** → *),
对 tests/<suite>/** 这种形态够用,别拿它去判更刁钻的 glob。

[vansin]

落地顺序的前提核实:这道门在合并这件事上没有任何强制力

上一轮我给的建议是「先修 #862 再接门,否则给自己造一道永久红的门」。
核实了一下这道门到底能不能挡合并 —— 结论是挡不了,所以那条顾虑要下调。

对 sleep2agi/agent-network,三条独立口径:

① 经典分支保护   GET /repos/.../branches/main        → protected: false
② 新版 ruleset   GET /repos/.../rulesets             → 有一条名为 "main" 的
                                                        enforcement: **disabled**
                                                        rules: [deletion, non_fast_forward]（无 required checks）
③ 实际生效规则   GET /repos/.../rules/branches/main  → **[]**（空）

与 qa.yml 自己头部的声明一致:

Non-blocking: failures show as a red ✕ on the PR but do NOT prevent merge
unless someone explicitly adds this check to branch protection.

没有人加过。 所以:

• 把 test686/765/766 补进 paths(3 个 L1 套件(test686/765/766)不在 qa.yml 的 paths 里:改它们不会触发跑它们的门 #860 的补丁)不可能挡住任何合并,风险只有「PR 上多一个红 ✕」;
• 同理,两个为发版事故写的校验脚本零自动执行:有工具、有 SOP,但只在人记得时才跑 #862 那道 release-guards 门即使一上来就红,也只是噪音,不是阻塞。
  先修再接的顺序仍然更好(红门会被习惯性忽略),但它不是硬前提。

顺带量了一下这道门实际跑的频率

最近 20 个已合并 PR:

agent-network unit (Docker, non-root)   4/20
agent-node unit (Docker, non-root)      7/20
L0 + L1 (report-only)                   7/20   ← 真正跑 scripts/qa.sh 的是它

7/20 是 paths 过滤的结果(没碰那些路径的 PR 不触发),这本身是设计如此,不是缺陷。
但它给 #860 提供了一个量化背景:那 3 个套件目前落在这 7 次之外的概率是 100% ——
它们不在任何 paths 列表里,所以改它们自己时一次都不会触发。

🔴 记一笔我核这件事时踩的坑:第一遍我用 test("QA|qa") 过滤 checks,得到「qa check 一个都没有」。
那是过滤器错了 —— checks 里显示的是 job 名(L0 + L1 (report-only)),不是 workflow 名(anet QA (v0))。
第二遍我只看了 3 个 PR 就写下「一次都没出现」,扩到 20 个才是 7 次。
窄过滤器 + 小样本,两个错叠在一起会给出一个很有说服力的错误结论。

[vansin]

待落地的完整接入清单(#860 的 3 个 + #861 第一批 9 个)

基线 origin/main@034f0064,两个补丁都已 patch -p1 --dry-run 干净应用。未开 PR,等授权。

🔴 必须两处都改 —— 这是 #860 和 #861 合起来才看得清的一点

#860 的 3 个   已在 L1_TESTS，只漏在 qa.yml 的 paths 外   → 只改 qa.yml
#861 的 9 个   孤儿：L1_TESTS 和 paths 都没有             → **两处都要加**

只加 paths 不会让它们跑(runner 遍历的是 L1_TESTS);
只加 L1_TESTS 会让它们「改了自己却不触发」—— 那正是 #860 的毛病。

变异验证过:把 9 个加进 L1_TESTS 但 paths 一个不加 →
不变量检查器报 L1PATHS: RED,两个列表各 12 处未覆盖,共 24 处。这道门抓得住这个错。

补丁内容

scripts/qa.sh              L1_TESTS 17 → 26（+9）
.github/workflows/qa.yml   两个 paths 列表各 +12（3 个来自 #860，9 个来自这里）

选这 9 个的理由不是「最重要」,而是耗时边际影响最小 ——
它们静态等待为 0,耗时几乎全等于 qa.sh:156 那次 docker build 本身。
先接它们是为了验证「接门」这条路走不走得通,不是为了覆盖率。

验证

不变量检查器          L1PATHS: GREEN   L1_TESTS 26，两个列表(22/21 条)全覆盖
bash -n scripts/qa.sh 通过
yaml.safe_load        通过，jobs 仍是 3
变异（只改 qa.sh）    L1PATHS: RED，24 处未覆盖
patch --dry-run       两个补丁都干净

落地后必须实测的一件事(这份清单的最大局限)

以上全部是静态判定,没有真跑过任何一个套件。落地后第一次 CI 跑起来要看:
① 这 9 个在 CI 容器里是否真能跑通(本地能跑 ≠ CI 能跑);
② 实际耗时(静态下界不含 docker build,而那很可能是主导项);
③ 有没有 flake。

任何一个跑不通就从 L1_TESTS 撤回,别留着让门长期红 ——
红门会被习惯性忽略,那比没有门更糟。

风险边界:已核实这道门当前挡不住任何合并
(protected:false / ruleset enforcement:disabled / /rules/branches/main 为 []),
即使这批全红也只是 PR 上多个红 ✕,不阻塞任何人。

[vansin]

🔴 这条与 #818 是同一个缺陷 —— 建议合并,别并行推进

对照两条的正文:

             #818（2026-08-13 03:35Z）      #860（2026-08-13 16:58Z）
点名的套件    test686 / test765 / test766   test686 / test765 / test766   ← 完全相同
引用的清单    qa.yml PR 触发路径 10 条      qa.yml pull_request.paths 10 条 ← 同一份
根因          它们自己的目录不在触发路径里   同上
后果          改它们自己不触发跑它们的门     同上

#818 更早 —— 同一天,早约 13 小时(03:35:54Z vs 16:58:46Z,gh issue view --json createdAt 实测)。

🔴 更正记录:我先前在这条评论里写过 #818（2026-08-11）(没核就写的日期),
随后又发过一次「订正:#860 反而早 5 分钟」—— 那次订正本身是错的,
我把 #861 的 17:03Z 当成了 #818 的。以实测时间戳为准:#818 早 13 小时,
最初的判断是对的。留痕在此,不掩盖。 我在复核 #860 时逐项验证了它在 main 上仍然成立,
但没有验证它是不是新的 —— 这是我的疏漏:
「这条 issue 说得对吗」和「这条 issue 是不是已经有人说过」是两个问题,我只做了前一个。

建议

后续分析都堆在 #860 上了(两个 paths 列表、最小补丁、不变量检查器、
与 #861 合并的接入清单),所以建议把 #818 作为重复关掉并指向 #860,
而不是反过来 —— 否则要搬运的东西更多。

不过 #818 有一处 #860 没写到、值得搬过去的观察:

这三道恰好都是带 mutation 的门,也就是最不该在无人验证下被改的那类。

这句给出了优先级理由:不是「有 3 个套件漏了」,而是「漏掉的恰好是那三道
用变异自证有效性的门」——改松它们(把 expect_red 改成 expect_green)
不会被任何门发现。这条比单纯的覆盖缺口严重。

处置权在 owner,我不自行关闭任何一条。