docs(#850): 9 处文档还指着一个 15 行的空壳文件 server/src/index.ts（清单第 7 条）

[vansin]

Refs #850。#856 清单里 fix/850-out-of-range-index-pins 的前两个提交(第三、四条属于 #887/#834,不在本 PR)。

前提我在今天的 main 上核过,而且它比标题更刺眼

$ git show origin/main:server/src/index.ts | wc -l     →    15
$ git show origin/main:server/src/server.ts | wc -l    →  3374

server/src/index.ts 现在是一个 15 行的空壳,真正的东西在 server.ts(3374 行)。 而文档里还有一批引用指着那个空壳 —— 点进去看到 15 行,读者会以为自己点错了,或者以为这个项目的 server 只有 15 行。

本 PR 改掉其中 9 处(7 个文件),把它们指向 server.ts。

🔴 顺带被我自己刚落地的那道门抓了一次

改完跑 scripts/check-doc-symbol-pins.py(#987,今天刚合):

🔴 docs/architecture.md  锚文本点名 `dashboardReleaseTag`，钉在 agent-network/bin/cli.ts#L347，
   但那一行是: …
SYMBOL-PIN: RED（扫到 15 个 pin，判定 5 个，跳过 10 个，漂移 1 个）

那是这条两天前的旧提交里带进来的一个行号 pin,它当时可能是对的,今天不是了。grep -n "function dashboardReleaseTag" 实查 → 1569 行(不是 347)。改掉之后:

SYMBOL-PIN: OK（扫到 15 个 pin，判定 5 个，跳过 10 个，漂移 0 个）

一条今天上午还不存在的门,当天下午就抓住了一条我正要合进去的过期引用。 这也是我这几轮反复说的那件事的又一个例子:旧分支带的不只是代码,还带着它当时的事实。

冲突处理

docs/architecture.md 有一处冲突,是同一行里 index.ts → server.ts 的那处改动本身。取 theirs —— 因为那正是这个提交的目的。

🔴 我没有用 git checkout --theirs <file> —— 今晚早些时候我用它整份取旧版,git diff --stat 显示 96 insertions(+), 398 deletions(-),差点静默删掉 main 后来加的一整个 helper。这次是按 hunk 取的,最终净改动:

7 files changed, 9 insertions(+), 9 deletions(-)   ← 纯替换，无删除块

本地全绿

doc-symbol-anchors · docs-integrity · no-memory-slugs · home-path-baseline
doc-source-pins · doc-claims · doc-symbol-pins · mcp-tool-anchors     全部 rc=0

还剩多少

git grep -c "server/src/index.ts" -- docs docs-site 仍有若干处(docs/analysis/… 3、docs/architecture.md 6 等)。本 PR 只改这条旧提交覆盖的那 9 处,没有顺手扩大范围 —— 剩下的属于同一类,可以另开一条按同样方式清。

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[vansin]

🔴 更正我自己在 PR 正文末尾写的那句

我写的是:

还剩多少 …… 剩下的属于同一类,可以另开一条按同样方式清。

那句是错的。我去逐条核了,剩下的绝大多数不该改 —— 按同样方式清会把正确的文档和历史记录一起改坏。

逐条分类

① 它们是对的 —— agent-network/src/server.ts 真的在 import index.ts

docs/architecture.md:31 / 179 / 344 / 360 说 agent-network/src/server.ts 动态 import ../../server/src/index.ts。实查:

// agent-network/src/server.ts:26-27
// Dynamic import to avoid loading server code when only using client
await import("../../server/src/index.js");

这不是遗留,是设计。 server/src/index.ts 自己的文件头写得很清楚:

// Run-entry shim (#438 corrective, 方案 C per 通信龙).
// Running this module IS running the hub: `bun run src/index.ts` keeps
// working for the 50+ e2e/dev scripts that boot the hub that way. All
// real code lives in ./server.ts, which is side-effect-free to import …
// Do NOT add logic here, and do NOT import this module to "get at the
// server" — that starts one.

⇒ 「指向 index.ts」在这几处是正确的,因为那几处讲的正是「谁去 run 它」。 把它们改成 server.ts 会把一句对的话改成错的 —— 而且改完之后,import server.ts 和 import index.ts 的根本区别(前者无副作用、后者直接起一个 hub) 就在文档里消失了。

② 它们是记录 —— 改了等于篡改证据

docs/analysis/hub-per-node-endpoints-2026-07-31.md:213-214
    Root cause: the enumeration ran against `server/src/index.ts` …
    `server/src/index.ts` = **11-line shim**
docs/open-source-quality-review.md:310 / 335 / 392   带行号的历史审查（:80、:234-243、1189 行）
docs/claude-code-cleanup-review.md:56                同类
docs-site/docs/changelog.md 等                        带日期的变更条目

这些是「某年某月我在那个文件里看到什么」。 那时 index.ts 确实是 1189 行。把路径改掉,那条记录就不再是那次实测的记录了。

(第一条尤其反讽:hub-per-node-endpoints 那份分析的根因就是「枚举跑错了文件,跑到了 index.ts 这个 shim 上」——它记录的正是这个坑本身。)

所以本 PR 改的那 9 处和剩下的不是同一类

改的那 9 处是当前事实断言,而且断言的对象已经搬走了(/dashboard 路由、addNetworkScope 等实际在 server.ts)。剩下的是「谁 run 谁」的正确描述,或者带日期的记录。

⇒ 不建议另开一条清剩下的。 如果真要动,判据不是「路径里有没有 index.ts」,而是**「这句话是在说现在,还是在说当时/在说 run-entry」** —— 那需要逐条读,不是一次替换。

这条更正本身也是复核出来的

我原本准备下一轮就去「按同样方式清剩下的」。是先去核了 agent-network/src/server.ts 到底 import 谁,才发现那几处是对的。

如果我照自己写的那句去做,会亲手把一批正确的文档改错,而且没有任何门会拦我 —— 路径存在、链接可解析、所有检查都会绿。