From 461dd1f2656823ec0ad74231665bf93b9f77dca4 Mon Sep 17 00:00:00 2001
From: t <internlmorg@gmail.com>
Date: Tue, 18 Aug 2026 22:01:05 +0800
Subject: [PATCH] =?UTF-8?q?ci(doc-symbol-pins):=20=E4=BB=8E=20qa.yml=20?=
 =?UTF-8?q?=E6=8B=86=E6=88=90=E6=97=A0=20paths=20=E7=9A=84=E7=8B=AC?=
 =?UTF-8?q?=E7=AB=8B=20workflow=20=E2=80=94=E2=80=94=20=E5=AE=83=E4=BB=8E?=
 =?UTF-8?q?=E6=9D=A5=E4=B8=8D=E5=9C=A8=E8=AF=A5=E8=A7=A6=E5=8F=91=E7=9A=84?=
 =?UTF-8?q?=E6=97=B6=E5=80=99=E8=A7=A6=E5=8F=91?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

#1001 里报的那个结构性缺口，按当时说的方向②做，单独一条。

这道门原来是 `qa.yml` 的一个 step（qa.yml:309）。而 qa.yml 的 paths 是：

    server/** · docs/stale-issue-review.md · scripts/check-doc-claims.py ·
    tests/test846-doc-claims/** · agent-network/** · agent-node/** ·
    tests/qa-*/** · scripts/qa.sh · docs/qa/** · .github/workflows/qa.yml

**`docs/architecture.md` 不在里面。** 于是改 architecture.md 的 PR 从来不跑这道
pin 门，那个文件里的行号锚点可以自由漂 —— #1001 一次就抓到三处
（URL 写 `cli.ts#L1569`、锚文本写 `cli.ts:347`、真值 1585；另一处写 `cli.ts:2386`
声称是 `sub === "dashboard"` 分支，真值 6279）。

它只在**被指向的文件**（`agent-network/**`）变动时才有机会红，而那时红的是别人的
PR、理由却在 architecture.md 里。**门存在、也挂上了，但不在该触发的时候触发。**

拆出来而不是往 qa.yml 的 paths 里加 `docs/**`，两个理由：
  - qa.yml 很重（跑多个 docker 构建的测试套件），为一个几百毫秒的 python 检查
    把它整个拉起来不划算；
  - **带 paths 的 workflow 在不匹配的 PR 上不产生 check-run，永远做不了
    required check**（卡在 Expected — Waiting for status）。这道门应当能进 required。
和 no-memory-slugs / public-script-safety 这些守卫保持同构。

验证：
  绿起点   python3 scripts/check-doc-symbol-pins.py .   rc=0
           SYMBOL-PIN: OK（扫到 15 个 pin，判定 5 个，跳过 10 个，漂移 0 个）
  见红     把 #1001 修的那三处退回（git show 8937065f^:docs/architecture.md）
           SYMBOL-PIN: RED（… 漂移 1 个）   rc=1
  还原后   rc=0

qa.yml 那一步摘除后留了去向注释，不是静默删掉。
workflow-structure / action-pins / qa-trigger-coverage / l1-paths-sync /
no-escaped-comments 全部 rc=0；job name `doc-symbol-pins` 经核全仓唯一。

覆盖面净增：原来只有命中那 10 条 paths 的 PR 才跑，现在每个 PR 都跑。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .github/workflows/doc-symbol-pins.yml | 42 +++++++++++++++++++++++++++
 .github/workflows/qa.yml              |  5 ++--
 2 files changed, 45 insertions(+), 2 deletions(-)
 create mode 100644 .github/workflows/doc-symbol-pins.yml

diff --git a/.github/workflows/doc-symbol-pins.yml b/.github/workflows/doc-symbol-pins.yml
new file mode 100644
index 000000000..6223192a3
--- /dev/null
+++ b/.github/workflows/doc-symbol-pins.yml
@@ -0,0 +1,42 @@
+# 符号级行号 pin：锚文本里点了名的符号，必须真的在钉住的那一行。
+#
+# 这道门原来是 qa.yml 里的一个 step。2026-08-18 发现它**不会在该触发的时候触发**：
+#
+#   qa.yml 的 paths 是 server/** · agent-network/** · agent-node/** · docs/qa/** …
+#   **`docs/architecture.md` 不在里面。**
+#
+# 于是「改 architecture.md 的 PR 从来不跑这道 pin 门」，那个文件里的行号锚点可以
+# 自由漂移。实测漂了三处（#1001）：URL 写 cli.ts#L1569、锚文本写 cli.ts:347、
+# 真值 1585；另一处写 cli.ts:2386 声称是 `sub === "dashboard"` 分支，真值 6279。
+# 它只在**被指向的文件**（agent-network/**）变动时才有机会红，而那时红的是别人的
+# PR、理由却在 architecture.md 里 —— 门存在、也挂上了，但不在该触发的时候触发。
+#
+# 拆出来而不是往 qa.yml 的 paths 里加 `docs/**`：qa.yml 很重（跑 docker 构建的
+# 多个测试套件），为一个几百毫秒的 python 检查把它拉起来不划算；而且**带 paths 的
+# workflow 在不匹配的 PR 上不产生 check-run，永远做不了 required check**
+# （会卡在 Expected — Waiting for status）。和 no-memory-slugs / public-script-safety
+# 这些守卫保持同构。
+
+name: lint (doc symbol pins)
+
+on:
+  # 刻意不加 paths —— 这道门要防的就是「锚点漂了而改动落在过滤之外」。
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  doc-symbol-pins:
+    # 全仓唯一的 job name —— 分支保护里的 required check 只能按这个名字写。
+    name: doc-symbol-pins
+    runs-on: ubuntu-latest
+    timeout-minutes: 3
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      # 参数 `.` 与它在 qa.yml 里的原调用一致（脚本用 argv[1] 定位仓根）。
+      # 它同时打印**跳过了多少** —— 一个只说「0 处漂移」不说「跳过 10 处」的门，
+      # 读起来像「全都查过了」。
+      - run: python3 scripts/check-doc-symbol-pins.py .
diff --git a/.github/workflows/qa.yml b/.github/workflows/qa.yml
index 8a0b10ece..61b474941 100644
--- a/.github/workflows/qa.yml
+++ b/.github/workflows/qa.yml
@@ -305,8 +305,9 @@ jobs:
       #    读者点进去连怀疑都不会产生。四处已在同一个 PR 里改对,这一步因此起点是绿的。
       #    它同时打印**跳过了多少** —— 一个只说「0 处漂移」不说「跳过 10 处」的门,
       #    读起来像「全都查过了」。
-      - name: 符号级行号 pin（#852，补 source-pin 抓不到的那一类）
-        run: python3 scripts/check-doc-symbol-pins.py .
+      # 🔴 这一步已搬到 .github/workflows/doc-symbol-pins.yml（无 paths 过滤）。
+      #    留在这里跑不到该跑的时候：qa.yml 的 paths 里没有 docs/architecture.md，
+      #    而那正是行号漂得最多的文件（#1001 一次抓到三处）。
       - name: Build test831-doc-source-pins
         run: |
           docker build \