docs/ 下的源码行号引用没有任何门覆盖:扩 DOC_ROOT 只解决 2/11,剩下 9 条要符号级校验

[vansin]

问题

docs/(不是 docs-site/)里按 blob/main/<file>#L<n> 钉的源码引用,有一批已经指错了,
而且现有的任何一道门都不覆盖它们。

数字(都是跑出来的,不是估的)

一、docs/ 完全不在 #843 那道门的范围内

scripts/check-doc-source-pins.py:54:

DOC_ROOT = "docs-site"

把它临时改成 "docs" 再跑同一个脚本:

pin_doc_pairs=37  unique_pins=36  broken_pins=8
FAIL: 7 个新的失效 pin(不在基线里)

7 条明细:

[trivial-line]       agent-network/bin/cli.ts#L1724   // 缺 bun/bunx 时直接 process.exit(1)…
[trivial-line]       agent-network/bin/cli.ts#L198    (空行)
[trivial-line]       agent-network/bin/cli.ts#L2044   });
[trivial-line]       agent-network/bin/cli.ts#L228    // Minimal WebSocket JSON-RPC thread creator…
[trivial-line]       agent-network/bin/cli.ts#L2725   (空行)
[trivial-line]       agent-node/src/cli.ts#L558       // "Reached maximum number of turns (5)"…
[line-out-of-range]  server/src/index.ts#L816         (行号 816,文件 16 行)

所以扩 DOC_ROOT 的代价是具体的、不大的:多 8 条失效 pin,其中 7 条要处理。
(我此前说过「会立刻多出一批」——那是没测过的话,实测是 8 条。)

二、扩了 DOC_ROOT 也只解决 2/11

另有一类更隐蔽的:行号在范围内、指着一行正常代码,但不是声称的那个符号。
我在 #850 量过,docs/ 下锚文本带符号名、可机器判定的引用有 11 条,漂移 11、仍对 0:

声称	origin/main 上第几行才是它	那个行号现在是什么
cli.ts:228 loadProfile	—	// Minimal WebSocket JSON-RPC thread creator…
cli.ts:246-273 saveProfile	—	const p = pending.get(msg.id);
cli.ts:556 setupCommand	—	"-e", \ANET_NODE_MARKER=${identityMarker}`,`
cli.ts:2044 runCommand	—	});
cli.ts:1644 ensureMcpJson	—	minor: Number.parseInt(match[2], 10),
cli.ts:105-111 saveAdminUtok	—	import {
cli.ts:89-95 saveServerConfig	—	grokBuildCliCreationFields,
cli.ts:77-81 saveGlobal	—	} from "../src/opencode-package-binary";
cli.ts:2629-2631 renameCommand	—	const resolved = resolveNodeRef(ref);
cli.ts:2583-2721 renameCommand	—	anet config [path|json] … 帮助文本
cli.ts:28 adminUtokPath	—	removeMarker as removeCopresenceMarker,

把这 11 条的行号,和「扩 DOC_ROOT 后会被判失效的 cli.ts 行」求交集:

我的 11 条:        [28, 77, 89, 105, 228, 246, 556, 1644, 2044, 2583, 2629]
扩后被判失效的:    [198, 228, 1724, 2044, 2725]
交集:              [228, 2044]   → 2 / 11
仍漏:              [28, 77, 89, 105, 246, 556, 1644, 2583, 2629]  → 9 / 11

被抓到的那 2 条是碰巧漂到了注释行/闭合括号上(trivial-line 判据);
其余 9 条漂到了正常代码行,那道门按设计就看不见 —— 它的文件头写着实测召回率 5/10。

要做两步,别混成一件事

1. 扩 DOC_ROOT 到 docs/:代价已量化(8 条失效 pin),做法和 ci(test831): 文档站行号 pin 的下限门(守住不再变多,不解决 #831) #843 一致
   (进基线 + 基线只许缩小)。收益 2/11。
2. 符号级校验:断言「锚点那一行确实包含锚文本里写的那个符号」。
   docs(mcp-tools): 正文行号引用改钉符号 —— 两版行号 pin 归零 #845 的 scripts/check-doc-symbol-anchors.py 是这个路子,但它只针对
   mcp-tools.md 的 ### <tool_name> 章节结构,套不到 docs/ 这些散文档上。
   这一步才是剩下 9/11 的解,也是工作量真正所在。

🔴 记一条我自己的错

我在上一轮说过「#843 是那 11 条漂移唯一的机械解」,后来又更正成「范围和类别两个方向都不成立」。
第二句也说过头了:类别上它并非一条都抓不到,trivial-line 判据能碰到 2 条。
准确的说法是:范围上完全不覆盖;扩范围后覆盖 2/11。

相关:#843(那道门本身)、#850(changelog 里的同类)、#851(已修的两条)、#831。

[vansin]

已开 PR #857 推进这条:docs/ 下 cli.ts 行号引用 22 → 9,13 条改钉符号锚(照 #845 的形状)。

改前的错法比预想严重 —— 不是漂了几行,是差了几千行:

符号	文档声称	main 实际
adminUtokPath	28	138
loadProfile	228	1208
ensureMcpJson	1644	4300
runCommand	2044	5641
renameCommand	2583 / 2629	6911

每条新锚串都核过在 cli.ts 里唯一(13 条,非唯一 0 条)。RuntimeName 那条故意没改 —— 它出现 13 次,做不出唯一锚,与其钉个含糊的不如留着行号。

剩下 9 条锚文本里没有符号名(形如 [cli.ts:1724](…#L1724)),机械改不了,要人读源码判断当初想指什么。本 issue 保持开着追这 9 条。

顺带:docs/qa/weekly/2026-W19.md 不是 UTF-8(position 2467 invalid continuation byte),按 UTF-8 读全目录的脚本会在它上面炸。本次跳过了它。

[vansin]

PR #857 已把 docs/ 下的 cli.ts 行号引用清到 0(22 → 0),包含本 issue 说的「9 条机械改不了、要人读源码」的那批,全部收完。

新发现一个此前没被盘点覆盖的目录:

tests/qa-cli-02-network-create/README.md:44,54   cli.ts#L3166 / #L3055
tests/qa-cli-01-hub-start/README.md:37,56        cli.ts#L1893 / #L1925

#831 的范围是 docs-site/,本 issue 的范围是 docs/,tests/ 下的 README 两边都不含。#843 那道门的 DOC_ROOT 也只扫 docs-site/。所以这 4 条目前同样没有任何门覆盖。

本 issue 可在 #857 合并后关闭;tests/ 那 4 条建议并入 #831 的范围一起处理(它才是「行号 pin 大面积失效」的总账)。

[vansin]

给「把 DOC_ROOT 扩到 docs/」这一步补一个精确的前置条件。

check-doc-source-pins.py 对读不出的文件是静默跳过的(except (OSError, UnicodeDecodeError): continue)。实测两个扫描根的盲区:

docs-site/（现状）  扫描面 106 个文件   UTF-8 解码失败 0 个
docs/（提议扩到）   扫描面 181 个文件   UTF-8 解码失败 1 个 → docs/qa/weekly/2026-W19.md

所以扩范围会恰好引入 1 个盲区:那个文件里若有失效的行号 pin,永远不会被检查到,而门照报绿。

PR #858 修的就是这个文件(它自诞生起就不是合法 UTF-8,三处汉字被按字节截断)。

→ 顺序上:#858 应当排在本 issue 的扩范围动作之前。先修编码,再扩 DOC_ROOT,否则扩完就是带着一个看不见的洞。

(另外建议扩范围时顺手让 checker 打印 skipped=N —— 否则下次再有文件读不出,同样是静默的。)

[vansin]

关联:#872 —— 同一族问题的路径层面

刚开了 #872:docs/qa/weekly/2026-W19.md 的 24 条相对链接全部失效,单一根因是目录深度算错一级(../../ 应为 ../../../),失效目标(tests/qa-cli-01-hub-start/、server/src/auth-tokens.test.ts 等)在 main 上都存在,纯粹路径写错。

与本条的关系:本条讲文档里的行号引用无门覆盖,#872 讲路径本身无门覆盖。实测仓里没有任何文档链接检查:

git ls-tree -r origin/main | grep -iE 'link.*(check|lint)|lychee|markdown-link'  → 0
.github/workflows/ 里提到 link/lychee 的                                          → 0

路径校验比行号校验基础得多、也便宜得多(解析 markdown 链接 + normpath + 查存在性,几十行),建议两件事一起规划:先立路径门,再谈行号门 —— 否则行号对了、路径错了,同样点不进去。

[vansin]

前提复核:那个脚本在 origin/main 上还不存在 —— 本 issue 的路径依赖比正文写的更强

2026-08-15 在 origin/main@034f0064 复核。本 issue 正文引用:

scripts/check-doc-source-pins.py:54
    DOC_ROOT = "docs-site"

我去跑它,报 No such file or directory。枚举 main 上 scripts/ 里所有 check/verify:

$ git ls-tree -r --name-only origin/main -- scripts/ | grep -E 'check|verify'
scripts/verify-published-pins.sh
scripts/verify-release-tag.sh

main 上没有任何文档 pin 的门。 那个脚本活在 PR #843(OPEN,非 draft,MERGEABLE,开了 1 天)里:

scripts/check-doc-source-pins.py        +249/-0
docs/doc-source-pins-baseline.txt        +47/-0
.github/workflows/qa.yml                 +30/-0
tests/test831-doc-source-pins/{Dockerfile,run.sh}

这对本 issue 意味着什么

正文的说法是「现有的任何一道门都不覆盖它们」+「扩 DOC_ROOT 只解决 2/11」。
按字面读,容易被理解成:门已经在了,只是范围没圈进 docs/,把常量改一下再补 9 条符号级校验即可。

实际状态更强一档:门本身还没落地。所以本 issue 的修复路径是串行的 ——

PR #843 合并（门落地，范围 = docs-site）
        ↓
再谈把范围扩到 docs/（本 issue 的前半:2/11）
        ↓
再谈剩下 9 条要的符号级校验（本 issue 的后半）

在 #843 落地之前,「扩 DOC_ROOT」这个动作没有可扩的对象。

顺带:这也解释了 #831 和本 issue 的关系

两条不是重复,是同一缺陷类的两个不相交范围:

	范围	现状
#831	docs-site/(70 个唯一 pin / 141 处引用)	PR #843 的门正是为它写的,尚未合并
#852	docs/	完全在那道门的范围之外,且门本身未落地

我没有断言的事

• 没有判断 PR ci(test831): 文档站行号 pin 的下限门(守住不再变多,不解决 #831) #843 该不该合、有没有问题 —— 我只核了它的存在与状态。
• 正文里「2/11」「9 条要符号级校验」这两个数我没有重算(需要在 ci(test831): 文档站行号 pin 的下限门(守住不再变多,不解决 #831) #843 的脚本上跑),
  这里只更正"门是否已存在"这一个前提。

[vansin]

那道"符号级校验"做出来了,并且顺手在 docs-site/ 里也量到了 27 条

分支 feat/852-symbol-pin-gate @ d2b9955c(从 ci/doc-source-pin-guard 切,本地,未推、未开 PR)

🔴 先说一处会影响复现的事实

本 issue 引的是 scripts/check-doc-source-pins.py:54。那个文件不在 origin/main 上 ——
它在未合并的分支 ci/doc-source-pin-guard(behind=0 / ahead=4)。
照 issue 在 main 上找这个文件会一无所获。所以我把新门切在那条分支上,而不是 main。

做的事

check-doc-source-pins.py 在自己文件头里就承认了这个盲区:

抓不到的:锚点指着一行长得很正常的代码,只是不是它声称的那一行。

它那三条判据(文件不存在 / 行号越界 / 平凡行)问的都是"这一行看起来对不对"。
而重构之后最常见的形态是:那一行完全正常,只是不再是被描述的那段代码 —— 读者没有理由去怀疑。

新门补的是其中可机器判定的一块:锚文本点了名的符号,必须出现在钉住行的 ±2 行内。

今天的数

docs/       37 个 pin,判定 16,跳过 21,漂移 16,对 0
docs-site/ 141 个 pin,判定 27,跳过 114,漂移 27,对 0

docs/ 那组和本 issue 自己数的一致(你用另一套抽取规则得到 11,同样是"对 0")。
docs-site/ 那 27 条是新的 —— #843 的门覆盖那棵树而且在那里是绿的,
因为这 27 条正好全是它说自己看不见的那一类。

🔴 跳过的数会打印,而且明写"不是通过"

一道只说"0 处漂移"、不说"另有 114 处根本没看"的门,读起来像"全都查过了"。

两类误报是测出来改的,不是猜的

• 第一版在 docs/ 报了 26 条。其中一多半是把 agent、channel 当成了符号 ——
  它们来自锚文本里照抄的路径 agent-network/bin/cli.ts。
  stopword 表治不了这个(路径里出现什么词随仓库变),所以改成从被引用的路径自己推出排除集。
• 一个在目标文件里出现 165 次、351 次的标识符定位不到任何行;超过 20 次就不拿它下判断。

两个方向都验了

临时造了一份探针文档,里面对同一个符号放一条正确 pin 和一条故意钉错的 pin:
只有钉错那条被报出来。探针已删除,git status 复核过。

没做的:接进 CI

两棵树今天都是红的。先修哪些、要不要用基线属于取舍,不是机械步骤,留给 owner。

[vansin]

2026-08-18 · 同一个根因的第三种形态:门覆盖到了,但它的红没有区分度

这条 issue 说的是「docs/ 里的行号 pin 没有门覆盖」。今天撞到的是同一根线上的另一段:有门,而且它红了 —— 但红得没法直接读。

docs/stale-issue-review.md 里有一份 doc-claims 清单,tests/test846-doc-claims 会逐条打开那一行、确认它含声称的子串。格式是 文件 :: 行号 :: 子串:

agent-node/src/cli.ts :: 3468 :: video_gen
agent-node/src/cli.ts :: 4291 :: Expose CURRENT_TASK_ID
agent-node/src/cli.ts :: 2388 :: total_cost_usd

我在 #950 里往 agent-node/src/cli.ts 的 ~:462 插了 12 行(一段错误消息的特判),这三条立刻红:

FAIL: [drifted] agent-node/src/cli.ts:3468 不含 «video_gen»
       实际: if (/error|fail|cannot|denied|enoent|not found/i.test(line)) {
claims_checked=8  claims_failed=3

🔴 我这次能一眼断定是「位移」,是巧合

3468 → 3480     4291 → 4303     2388 → 2400

三个偏移量都恰好是 +12,等于我刚插入的行数。 所以我敢直接改行号。

换一个场景这个巧合就没了 —— 比如一次改动在上方一处 +8、另一处 −3,偏移量互不相同,那时我就分不出「行号漂了」和「文档本来就说错了」,而这两者:

• 修法完全相反(前者改数字、后者要改结论);
• 而它们的输出逐字相同,都是 [drifted] 不含 «X»。

所以这条 issue 主张的「符号级校验」,在这里同样成立,而且更省事

#857 已经在 docs-site/ 那边把行号 pin 换成了符号锚点(搜 \X`),.github/scripts/check-doc-symbol-anchors.py在守。**方案已经有了,只是没推广到这份doc-claims` 清单上。**

改法上它比 #852 正文里那 9 条更简单 —— doc-claims 的格式本来就已经带着子串了:

   现在:  agent-node/src/cli.ts :: 3468 :: video_gen
   可以:  agent-node/src/cli.ts ::  —  :: video_gen        ← 行号那一格作废

判据从「第 3468 行含 video_gen」变成「文件里存在 video_gen」。行号那一格本来就没有承担任何判据 —— 它只是让门知道去哪一行找,而找不到时它给出的信息量还是负的。

代价:video_gen 这类短串在大文件里可能多处命中,需要各条 claim 自己保证唯一(与 check-doc-symbol-anchors.py 面临的是同一个问题,那边已经在跑,可以照抄它的处理)。

本次我只改了三个数字(#950 里),没有动 tests/test846-doc-claims 的判据 —— 判据改动影响面更大,不该夹在一个「红了又修」的 PR 里悄悄带过。并在清单上方留了注释,免得下一个撞上的人以为是自己写错了文档。