docs: docs/ 里 13 条 cli.ts 行号引用改钉符号锚(22 → 9,改前 11/11 全错)

[vansin]

推进 #852。docs/ 下的 cli.ts 行号引用 22 → 9,13 条改钉符号锚。

为什么必须改

#852 量过:docs/ 下锚文本带符号名、因而可机器判定的引用有 11 条 ——
漂移 11 条,仍然对的 0 条。这批引用现有的任何一道门都照不到:

• ci(test831): 文档站行号 pin 的下限门(守住不再变多,不解决 #831) #843 那道门的扫描根是 DOC_ROOT = "docs-site",不覆盖 docs/;
• 就算扩了扫描根,它按「越界 / trivial-line」判,这类「行号在范围内、
  指着一行正常代码、只是不是声称的那个符号」只能碰到 2/11。

改法(照 #845 已确立的形状)

改前  [`cli.ts:228 loadProfile`](…/blob/main/agent-network/bin/cli.ts#L228)
改后  [`cli.ts`](…/blob/main/agent-network/bin/cli.ts) —— 搜 `function loadProfile(`

行号会漂,符号不会。读者用 git grep 一次定位。

改之前它们错到什么程度

符号	文档声称	origin/main 实际
adminUtokPath	28	138
saveGlobal	77-81	1000
saveServerConfig	89-95	1047
saveAdminUtok	105-111	1062
loadProfile	228	1208
saveProfile	246-273	1272
setupCommand	556	1860
ensureMcpJson	1644	4300
runCommand	2044	5641
renameCommand	2583 / 2629	6911

不是漂了几行,是差了几千行 —— 点进去看到的是完全无关的代码。

承重复核:每条新锚串在 cli.ts 里唯一

新锚串 13 条,非唯一 0 条

RuntimeName 那条故意没改:它在 cli.ts 里出现 13 次,做不出唯一锚。
与其钉一个含糊的锚(那正是 #845 踩过的坑:锚串确实存在,只是落在别的地方),
不如留着行号,等有人给它一个能唯一定位的写法。

剩下的 9 条:机械改不了,留给 #852

它们的锚文本里根本没有符号名:

docs/architecture.md:316   [cli.ts:1724](…#L1724)
docs/architecture.md:326   [cli.ts:1679-1680](…#L1679)
docs/architecture.md:328   [RuntimeName type cli.ts:145](…#L145)     ← 有名字但不唯一
docs/architecture.md:520   [`agent-network/bin/cli.ts:2386`](…#L2386)
docs/node-lifecycle.md:206 [cli.ts:2725-2750](…#L2725)
docs/node-lifecycle.md:213 [cli.ts:2831-2835](…#L2831)
docs/node-lifecycle.md:383 [`cli.ts:198`](…#L198)
docs/pitfalls.md:80        [`agent-network/bin/cli.ts:1658-1674`](…#L1658)
docs/rfcs/RFC-002-…:37     [`agent-network/bin/cli.ts:2685-2788`](…#L2685)

要修它们得人读源码,判断当初那段话想指的是什么 —— 没有机械办法。
这正是 #852 说的「剩下 9/11 要符号级校验」的那部分工作量。

顺带发现(不在本 PR 范围)

docs/qa/weekly/2026-W19.md 不是 UTF-8(position 2467 处 invalid continuation byte),
任何按 UTF-8 读全目录的脚本都会在它上面炸。本 PR 的处理是跳过它。

[vansin]

追加一个提交(025b461e):把「机械改不了、要人读源码」的那批也做掉了 —— docs/ 的 cli.ts 行号 pin 现在 22 → 3。

新修的 6 条,每条都是读上下文判出它当初想指什么、再去源码定位的:

位置	正文线索	新锚串
node-lifecycle.md:206	正文说 notifyServerOffline	async function notifyServerOffline(
node-lifecycle.md:213	正文说「确认流程」	This will delete "${displayName}" (node_id:
node-lifecycle.md:383	正文直接写了 resolveNodeRef	function resolveNodeRef(
architecture.md:316	正文说写 .mcp.json	.mcp.json: commhub → .anet/node-server.js
architecture.md:326	正文引了 compare-by-content	if (src !== dst)
architecture.md:328	RuntimeName type	🔴 见下

🔴 RuntimeName 那条不是行号漂移,是文件都换了。 文档写「RuntimeName type cli.ts:145」,但 cli.ts 里 type RuntimeName = 出现 0 次 —— 这个类型已经搬到 agent-network/src/normalize-runtime.ts:16。所以这条改的是链接目标,不只是锚。上一轮我把它当成「不唯一所以跳过」,那个判断本身就建立在错误前提上(以为它还在 cli.ts 里)。

「确认流程」那条差点选错锚:Run again with --force to confirm. 在 cli.ts 里出现 2 次 —— deleteCommand(8143)和 networkCommand(10173)。读上下文确认文档说的是节点删除,才选了 deleteCommand 段里唯一的那句。拿那个出现两次的串当锚,就会复现 #845 踩过的坑。

docs/node-lifecycle.md 的行号 pin 已归零。

剩余 3 条(锚文本无任何线索,连正文都没说它指什么函数):

docs/rfcs/RFC-002-channel-bind-cli.md:37   cli.ts#L2685   「参考实现」
docs/architecture.md:520                  cli.ts#L2386
docs/pitfalls.md:80                       cli.ts#L1658   「candidates 数组:源文件搜索顺序」

pitfalls 那条我已定位到候选:const candidates 在 cli.ts 里有 4 处(1024/1463/4333/…),其中 1024 与 4333 都是 node-server.js 解析顺序,要读 pitfalls 正文才能判是哪一个 —— 留到下一轮,不猜。

[vansin]

再追加一个提交(0b09dd5b):最后 3 条也收掉了 —— docs/ 下 blob/main 形式的 cli.ts 行号引用现在为 0(22 → 0)。

这 3 条锚文本里没有符号名,是逐条读正文判出来的:

• architecture.md:520 —— 正文自己就写着「sub === "dashboard" 分支」,所以链接去掉行号即可,锚已经在正文里(唯一,cli.ts:6092)。
• RFC-002:37 —— 「参考实现」指的是 anet channel add/ls → 搜 async function channelCommand((唯一,cli.ts:8159)。
• pitfalls.md:80 —— 「candidates 数组:源文件搜索顺序」。cli.ts 里 const candidates 有 4 处,其中 1024 与 4333 都是 node-server.js 解析顺序。判据是 4333 那处的注释 // dist/src/node-server.js（npm 包混淆后产物，优先） 与 pitfalls 正文第 1 条逐字对应,而 1024 那处的注释是 // installed npm package layout,对不上。所以选 4333。

这是这批里唯一一条两个候选都长得像的,如果按「找个差不多的就钉上」处理,就会钉错一个 —— 而钉错之后它仍然是「锚串存在、链接能开」,没有任何门会报。

仓内其余 8 条(不在本 PR 范围)

docs-site/docs/changelog.md:713      cli.ts#L61 / #L2589   ← PR #851 正在修
docs-site/docs/en/changelog.md:712   cli.ts#L61 / #L2589   ← 同上
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

#851 合了之后只剩 tests/qa-cli-*/README.md 那 4 条 —— 那个目录此前没有任何盘点覆盖到(#831 管 docs-site/、#852 管 docs/,都不含 tests/)。已在 #852 记一笔。

[vansin]

复核:本条结论仍成立,但范围之外还有同类的 6 条,全部也是错的

一、结论仍成立(2026-08-14 复核)

origin/main 上,docs/ 里指向 agent-network/bin/cli.ts 的行号引用仍是 22 条 ——
标题里的"改前 22"没有变,这个 PR/改动还没落地。

git grep -o 'blob/main/agent-network/bin/cli\.ts#L[0-9-]*' origin/main -- docs/ | wc -l
→ 22

🔴 二、我按更宽的范围数了一遍:docs/ 下的 cli.ts 引用其实是 28 条

22  agent-network/bin/cli.ts     ← 本条覆盖
 6  agent-node/src/cli.ts        ← 本条**不覆盖**

标题写的是「docs/ 里 13 条 cli.ts 行号引用」,但 agent-node/src/cli.ts 也叫 cli.ts。
按名字读会以为都算上了;实际那 6 条在范围之外。

三、那 6 条我逐条核了:6/6 全错,和本条要修的是同一种病

agent-node/src/cli.ts 现在 6133 行。逐条把「锚文本声称的符号」与「那一行实际内容」对照:

引用位置	声称	该行现在是什么	那个符号实际在第几行
docs/architecture.md:48	cli.ts:558-598 settingSources: []	// "Reached maximum number of turns (5)" …	2238
docs/message-lifecycle.md:41	cli.ts:864 msgType !== "task" …	inboxDir: string;	该表达式已不存在
docs/message-lifecycle.md:142	cli.ts:864 同上	inboxDir: string;	同上
docs/message-lifecycle.md:198	cli.ts:1102 ["new_task","broadcast"].includes(ev.type)	if (AUTH_TOKEN) headers["Authorization"] = …	5687
docs/message-lifecycle.md:199	cli.ts:836 shouldSkipMessage	warn(\cleared ${key} …`)`	4610 / 4695
docs/node-lifecycle.md:196	cli.ts:1159 心跳 setInterval	try {	1231 / 5942 / 5993

漂移幅度不小:settingSources 声称 558,实际 2238;includes(ev.type) 声称 1102,实际 5687。
其中 msgType !== "task" 这个表达式在当前代码里已经找不到了 ——
那两处引用不只是行号漂了,是它描述的判断本身可能已经改写,需要人看一眼再决定钉哪。

建议

不必扩大本条的范围(小范围是它能做完的原因),但标题/正文最好把范围写死成
「agent-network/bin/cli.ts 的 22 条」,否则读者会以为 docs/ 下的 cli.ts 引用都处理过了 ——
改一半比不改更糟,因为看起来像已经修过了。

那 6 条我不在这里动,建议另开一条跟踪(或在本条里显式写"不含 agent-node/src/cli.ts 的 6 条")。

(只读:全部读 origin/main,临时 worktree 用完即 remove;未改任何文档。)

[vansin]

核过了,合。前提比 PR 描述说得还严重,而新锚点我逐条验了。

① 旧行号 pin:我抽查的 13 条,13 条全错

拿 origin/main 的 agent-network/bin/cli.ts(13753 行)逐条对:

doc 写的	那一行实际是什么	符号真正在
cli.ts:228 loadProfile	const got = await tryOne(p);	1274
cli.ts:246-273 saveProfile	一句 capture-pane 的注释	1338
cli.ts:556 setupCommand	console.error(...identityPrep.remedy...)	1945
cli.ts:2044 runCommand	console.log("⚠ codex 需要登录")	5812
cli.ts:1644 ensureMcpJson	空行	4413
cli.ts:145 RuntimeName	function shellQuote(...)	已不在本文件
cli.ts:105 saveAdminUtok	formatSecretAssignment,	1128
cli.ts:89 saveServerConfig	grokBuildCliCreationFields,	1113
cli.ts:77 saveGlobal	} from "../src/opencode-package-binary";	1066
cli.ts:347 dashboardReleaseTag	}	1569

没有一条是「差几行」—— 全是指向完全无关的代码。 而它们都长得像有效引用(格式对、行号在文件范围内、点开能打开),所以读的人不会怀疑。

🔴 RuntimeName 那条尤其值得说:本 PR 发现它已经搬出 cli.ts 了,现在在 agent-network/src/normalize-runtime.ts。我验了 —— 该文件第 16 行 export type RuntimeName =。这不是修行号,这是修「文件都换了」。

② 新锚点:21 条,我逐条 grep 过

把 diff 里所有 搜 \…`的内容抽出来,在origin/main` 的源码里找:

21 条锚点 → 20 条在 cli.ts 里命中
剩 1 条(`export type RuntimeName =`)不在 cli.ts —— 因为它指的就是 normalize-runtime.ts,
已单独验过在第 16 行。

21/21 有效。 🔴 这一步不能省:把一个错的行号换成一个错的搜索串,读起来会更可信,坏得更彻底。

③ 一个这个 PR 没解决、也不该由它解决的问题

行号 pin 有 #843 那道门在数(守住不再变多)。符号锚点没有任何门在看。

它们确实不会因为「上面插了几行」而失效 —— 但会因为改名而失效,而且失效之后同样没有任何东西会喊。我上面那段 grep 就是一次性写的,不在仓里。

建议单开一道门:扫 docs/** 里所有 搜 \…`` 锚点,断言每一条在它自己点名的那个文件里存在。判据现成,今天这次的输出就是它的第一组期望值。这比继续数行号 pin 更有价值 —— 行号 pin 的数量在降,符号锚点的数量在升。

[vansin]

合并 main 之后 CI 全绿,已合。

八处冲突全是同一形状(本分支换成符号锚点 vs main 上 #869 改了同文件别处),一律取本分支侧。

核过没有连带丢东西:merged 与 origin/main 的逐行 diff = 12 删 / 12 增,每一条被删的 main 行都含 cli.ts 引用 —— #869 那次改的 runtime 表和目录树一个字都没动。