changelog 里两条「行号在范围内但已经指错」的源码引用(#834 的判据抓不到这一类)

[vansin]

问题

docs-site/docs/changelog.md 与 docs-site/docs/en/changelog.md 的第 713 行,有两条
按 blob/main/…#L<n> 钉的源码引用已经指错了,但因为行号没有越界,看上去仍然是活的。

#834 修的是同一段里第三条(server/src/index.ts#L253,指向一个 15 行文件的第 253 行)——
那条越界,一眼可见。这两条不越界,所以那次没被抓到。

证据(对 origin/main)

changelog 声称	origin/main 上它真的在第几行	该行号现在实际是什么
agent-network/bin/cli.ts:61 = PINNED_SERVER_VERSION	791:const PINNED_SERVER_VERSION = "0.9.0-preview.29";	} from "../src/opencode-preset";
agent-network/bin/cli.ts:2589 = bunx --bun @sleep2agi/commhub-server@… 的启动点	5765:const serverArgs = ["--bun", ...]	anet opencode auth-login <n> --provider <anthropic|openai> 的帮助文本

复现:

git fetch origin main
git show origin/main:agent-network/bin/cli.ts | sed -n '61p;2589p'
git show origin/main:agent-network/bin/cli.ts | grep -n 'PINNED_SERVER_VERSION'
git show origin/main:docs-site/docs/changelog.md | sed -n '713p'

为什么值得单独记一条

「越界」是个能自动判的信号,「在范围内但指错」不是 —— 后者需要知道那一行本应是什么。
同一段落里三条引用、三条都坏了,只有越界那条会被看见。

顺带:PINNED_SERVER_VERSION 那条正文写「仍 hardcode 0.8.0」,而 main 上现在是
0.9.0-preview.29。这不是正文错了 —— 它是历史记录,本就该定格在当时的值,
这正是应该钉当时提交而不是钉 main 的理由。

建议改法

与 #834 一致:把这两条也钉到当时的提交 SHA。挑 SHA 的判据可以照 #834 的做法 ——
选那条 changelog 条目对应的那次改动的提交,并确认它是 origin/main 的祖先
(git merge-base --is-ancestor <sha> origin/main),否则 GitHub 上链接可能开不出来。

相关:#834。

[vansin]

已开 PR #851 修这两条 —— 钉在 3a387204(v0.10.1 hotfix 的父提交,PINNED_SERVER_VERSION 值就是正文说的 0.8.0,L61 / L2589 都精确命中,且是 origin/main 祖先、blob 链接实打 HTTP 200)。

另外在 PR 里量了这类问题的规模:docs/ 下按 blob/main 钉 cli.ts 行号的引用共 15 条,其中锚文本带符号名、可机器判定的 11 条 —— 漂移 11 条,仍然对的 0 条。手改不解决问题,建议本 issue 保持开着,等 #843 的 check-doc-source-pins.py 落地后按它的输出批量处理。

[vansin]

更正我上一条留言里的一句话。

我说过「等 #843 的 check-doc-source-pins.py 落地后按它的输出批量处理」—— 这句是错的。今天跑变异时发现 check-doc-source-pins.py:54 写着 DOC_ROOT = "docs-site",而本 issue 涉及的 4 个文件(docs/architecture.md / docs/node-lifecycle.md / docs/design-auth-network.md / docs/pitfalls.md)全在扫描根之外,那道门一条都照不到。

两个方向都不成立:范围上 docs/ 不在内;类别上这 11 条属于「行号在范围内但指错符号」,而 #843 的文件头已写明它抓不到这一类(实测召回率 5/10)。

所以这 11 条目前没有机械解。要有,需要两步独立改动:把 DOC_ROOT 扩到 docs/(会立刻多出一批失效 pin 进基线),以及做符号级校验(#844/#845 那条 check-doc-symbol-anchors.py 的路子,但那份只针对 mcp-tools.md 的章节结构)。我另开跟踪。

[vansin]

把「那道门照不到」量成了数字 —— 根外 61 条,可判的 39 条里 37 条是坏的

先更正一个更基本的前提:上一条留言说 check-doc-source-pins.py:54 的
DOC_ROOT = "docs-site" 让 docs/ 出了扫描范围。范围这件事是对的,但还差一层:

git ls-tree -r --name-only origin/main | grep check-doc-source-pins   → 空

这个检查器在 origin/main 上根本不存在,它只在未合并分支 ci/doc-source-pin-guard 上,
#843 也仍是 OPEN。所以当前状态不是"门的扫描根太窄",而是门还没上线;
扫描根太窄是它上线之后紧接着的第二个问题。

数字一:扫描根内外的 pin 分布(origin/main 全部 .md)

扫描根内 docs-site/    141 条 pin   分布 10 个文件
🔴 扫描根外             61 条 pin   分布 16 个文件      ← 占全部的 30%

根外 top:

15  docs/architecture.md
 9  docs/node-lifecycle.md
 8  docs/message-lifecycle.md
 4  tests/qa-hub-09-task-state-machine/README.md
 2  docs/design-auth-network.md

数字二:根外那批烂得比根内还彻底

用与上一条留言相同的判据(锚文本里带符号名 ⇒ 可机器判定):

扫描根外:  命中 2  /  漂移 32  /  越界 5  ；不可判 21

⇒ 可判的 39 条里 37 条是坏的(95%)。
(对照:上一条留言量的 docs-site 是"可判 11 条,漂移 11,仍然对的 0"。)

手核两条,确认不是我的判据太严

声称 cli.ts:228 = loadProfile
  该行实际是   // Minimal WebSocket JSON-RPC thread creator against a running `codex…
  loadProfile  真正在 1208 行

声称 cli.ts:556 = setupCommand
  该行实际是   "-e", `ANET_NODE_MARKER=${identityMarker}`,
  setupCommand 真正在 1860 行

两条都是行号在范围内、但指向完全无关的内容 —— 正是本 issue 说的那一类,
一眼看上去还是"活的链接"。

对下一步的影响

• 门本身要先落地(ci(test831): 文档站行号 pin 的下限门(守住不再变多,不解决 #831) #843),再把扫描根从 docs-site/ 扩到全仓 .md;
  否则 30% 的 pin 天然在门外,而那 30% 恰恰是坏得最狠的一块。
• 判据可以直接用锚文本里的符号名:这批 pin 大多自带 cli.ts:NNN symbolName 形式的锚文本,
  不需要额外元数据就能判"这一行现在还是不是那个符号"。
• 越界的 5 条可以立刻修(它们连"看起来活着"都做不到)。

[vansin]

修掉 9 处指向 server/src/index.ts 的引用(fix/850-out-of-range-index-pins @ a2228c67)

根因不是行号漂移,是文件被掏空

server/src/index.ts 现在只有 16 行 —— #438 整改之后它是个 run-entry 壳,
文件头自己就写着:

All real code lives in ./server.ts … Do NOT import this module to "get at the server"

真正的 3373 行在 server/src/server.ts。所以我上一条说的「5 条越界 pin」不是各自漂移,
是同一件事的 5 个投影。

修完之后发现:同类问题还有 4 处,而且那 4 处任何检查器都报不出来

一、越界（5 处）   行号 98 / 138 / 771 / 788 / 816，全都超出 16 行 —— 一眼可见
二、🔴 不带行号（4 处）  blob/main/server/src/index.ts —— 解析得到（壳确实存在），
                        链接检查器不会报，但指向的文件里根本没有锚文本描述的东西

第二类正是本 issue 说的「在范围内但已经指错」,只是粒度在文件级而不是行级。
它比越界那类更隐蔽:越界的至少还能被"行号超出文件长度"抓到,而这一类看起来完全正常。

🔴 我第一版差点造出自己刚批评过的缺陷

第一版我只改了链接目标,锚文本仍写着 index.ts L98-122、index.ts /api/task 处理器。
那会让文字和目标不一致 —— 正是我在 RFC-006 那条里指出过的形态
(路径被写成链接文字、说明被写成目标)。锚文本已一并改成 server.ts,
并去掉已经失效的行号 —— 行号会再次漂移,而"server.ts 的 /api/task 处理器"不会。

验证

改前：指向 server/src/index.ts 的 md 链接 9 处（其中越界 5 处）
改后：0 处；锚文本仍写 index.ts 的 0 处
check-no-memory-slugs.py：改动树上仍 OK

🔴 check-doc-relative-links.py 在改动树上报 38/288 RED —— 那是既有状态,不是本次引入:
在 origin/main 的干净检出上跑同一道门,同样是 38/288。
(本次只动绝对 GitHub URL,一条相对链接都没碰。改动之后报红,先跑基线再下结论。)