docs(changelog): RFC-014 那条的源码引用钉到当时的提交(现在指向一个 15 行文件的第 253 行) - #834
docs(changelog): RFC-014 那条的源码引用钉到当时的提交(现在指向一个 15 行文件的第 253 行)#834vansin wants to merge 1 commit into
Conversation
changelog 中英两处都指向 blob/main/server/src/index.ts#L253。这个链接 现在指到一个只有 15 行的文件的第 253 行 —— 因为 #438 把 index.ts 改成了 run-entry shim,真实代码搬到了 server.ts: // Run-entry shim (#438 corrective). // All real code lives in ./server.ts … 改钉 22ed188(写这条 changelog 的那次提交)。核过:那时 index.ts 有 1623 行,:253 正是这条 changelog 描述的 disk 告警逻辑 (disk_avail_gb < 1 → red),:253-326 区间里 disk_*_gb 出现 6 次。 病因不是"行号漂了",是 ref 选错了:changelog 条目描述的是一个冻结的 历史时刻,却指向会移动的 main —— 这样的链接必然烂,而且是无声地烂。 换成当时的 SHA 之后,它永远成立。 这与参考页(api/rest.md 等)的修法不同:那边该改钉符号,因为它描述的是 "现在的行为";changelog 描述的是"当时发生了什么",该钉当时的 commit。 把两者混为一谈会修错 —— 给 changelog 更新行号,下次重构又坏。 详见 #831。
|
Codex Review: Didn't find any major issues. Breezy! Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
|
@codex review 本 PR 至今零审查记录(自动审查器只在开 PR / 草稿转就绪 / 显式 @ 时触发,push 不触发)。这是第二次请求。 |
|
Codex Review: Didn't find any major issues. Swish! Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
提醒:这个 PR 与 #843(文档行号 pin 的下限门)有一处硬耦合我在 #843 里加了 这个 PR 恰好会让基线里的条目消失:
所以合并顺序上有一个动作项:
我在 #845 的树上模拟跑过,完整输出贴在 #843 的这条评论。 不做的话,表现是「一个只改文档的 PR 把 CI 弄红了」,而红的原因看起来跟它毫无关系 —— 这条提醒的价值就在这里。 |
上一轮我在 #843/#810/#834 上贴了一条跨 PR 耦合提醒:那两个 PR 一合,基线里 对应的条目会变 stale,门就红在「请从基线里删掉」。提醒是散文,执行的人还是 得自己去数该删哪几条 —— 把一个机械操作交给了记忆力。 这一轮把它变成一条命令: python3 scripts/check-doc-source-pins.py . --write-baseline 🔴 这个开关离「一键把门变绿」只差一个条件判断,所以它**只许缩小**: 重算若会引入基线里没有的条目(= 出现了新的失效 pin),它拒绝写并退出非零。 新失效该做的是把链接改对,不是追认进基线。 L7 两个方向都断言,不只测它能用: ① 干净树:不改写,报「基线已经是最新的」,且文件字节未动 ② 注入一个新失效 pin:必须拒绝(rc≠0),且**确认基线没被写** —— 只断言"它红了"不够,要断言"它红了而且没写" ③ 造一个「引用消失」场景(把某条 pin 的引用改钉不可变 SHA): 必须删对、条数变小、表头注释保留、门随后转绿 顺带在门红的提示里直接给出这条命令,不让人再去翻文档。 验证(容器内,--network none): [L7] ① 干净树:不改写,报「已是最新」 MUTATION_RED write-baseline-refuses-new-failure rc=1 ③ 引用消失时删对了(5 → 4),表头保留,门转绿 复原后回绿 ✓ RESULT: PASS 退出码 0 一处说明:这个改动逻辑上属于 #843 的脚本,但落在链尾(#845)。理由是 #843 → #844 → #845 是一条依赖链,改在链首要把两级重新合并重跑一遍;而三个 PR 是按序 合进 main 的,落在链尾到达 main 的时间相同。写在这里免得有人以为放错了地方。
|
补充上一条提醒:现在不用手工数该删哪几条了 —— 合并后跑 |
vansin
left a comment
vansin
left a comment
There was a problem hiding this comment.
结论:改对了,建议合并。下面是我逐条核过的证据,外加一处同类漏网(不挡这次合并)
前提属实
origin/main 上 server/src/index.ts 只有 15 行 —— #438 之后它变成了 run-entry shim
(process.env.COMMHUB_SERVER = "1" + 动态 import ./server.js)。所以 #L253 确实是死指针。
新 pin 精准
22ed1886可达,且 是origin/main的祖先(git merge-base --is-ancestor通过),
所以 GitHub 上这个 blob 链接不会 404 —— 我实打了一次:HTTP 200。- 该 SHA 日期
2026-05-17,与这条 v0.10.2 changelog 同期。 - 该 SHA 上
server/src/index.ts有 1623 行,253-258实际内容:
253: if (typeof row?.disk_avail_gb === "number" && row.disk_avail_gb < 1) alerts.push(...)
254: if (alerts.length > 0) return { level: "red", alerts };
256: if (pct !== null && pct >= 60) alerts.push(`cpu ${pct}%`);
257: if (typeof row?.mem_avail_gb === "number" && row.mem_avail_gb < 1) alerts.push(...)
258: if (typeof row?.disk_avail_gb === "number" && row.disk_avail_gb < 5) alerts.push(...)
和正文那句「alert_level 加 disk < 1GB critical / < 5GB warn 触发」逐字对得上。
顺带一提,22ed1886 自己的提交信息里就写着
verify server/src/index.ts:253-326 —— 选的正是当时那次改动的提交,溯源很干净。
范围也是对的
我把两份 changelog 里所有 blob/main/…#L<n> 都抽出来,按「main 上该文件的行数 vs 引用行号」判死活:
✓ agent-network/bin/cli.ts L61 (共 13399 行)
✓ agent-network/bin/cli.ts L2589 (共 13399 行)
❌ server/src/index.ts L253 (只有 15 行)
越界的就这一条,这个 PR 修的正是它,没有漏。
🔴 同类漏网:两条「在范围内但已经指错」的引用(建议后续单开,不挡这次)
「行号在范围内」不等于「指对了」。上面那两条 cli.ts 引用都在 changelog 同一行(713 行),
按 main 的行号钉,现在都已经静默漂移:
| changelog 声称 | origin/main 上第几行真的是它 |
该行号现在实际是什么 |
|---|---|---|
cli.ts:61 = PINNED_SERVER_VERSION |
791 (const PINNED_SERVER_VERSION = "0.9.0-preview.29";) |
} from "../src/opencode-preset"; |
cli.ts:2589 = bunx --bun @sleep2agi/commhub-server@… |
5765 (const serverArgs = ["--bun", ...]) |
anet opencode auth-login <n> --provider <anthropic|openai> 的帮助文本 |
这两条和本 PR 修的是同一种失效,只是因为没越界所以看上去还活着 —— 越界那条会被一眼看出来,
这两条不会。同一段落里三条引用、三条都坏了,只是坏法不同。
改法和本 PR 一致:钉到当时的提交(而不是 main)。
另外 PINNED_SERVER_VERSION 那条正文说「仍 hardcode 0.8.0」,而 main 上现在是
0.9.0-preview.29 —— 那是历史记录、本就该定格在当时,这也正是钉 SHA 的理由。
钉到哪个 commit,是查出来的,不是猜的(
|
2 participants
修 #831 里确定失效的那两处(唯一与判据无关、可 100% 断定坏掉的两条)。
问题
中英 changelog 都指向
blob/main/server/src/index.ts#L253。$ git show origin/main:server/src/index.ts | wc -l 15#438把index.ts改成了 15 行的 run-entry shim(「All real code lives in ./server.ts」),所以这个链接指到一个不含任何逻辑的文件末尾之外 238 行。改法:钉当时的提交,不是更新行号
改为
blob/22ed1886/server/src/index.ts#L253。写之前先验了它指得到(这正是 #831 要说的事,不能自己再造一个坏指针):
正是这条 changelog 描述的内容(disk 三字段 + alert)。而
22ed1886的提交信息里自己就写着verify server/src/index.ts:253-326—— 当时确实在那里。为什么是「换 ref」而不是「换行号」
病因不是行号漂了,是 ref 选错了。
changelog 条目描述的是一个冻结的历史时刻,却指向会移动的
main。这样的链接必然烂,而且无声地烂。换成当时的 SHA 之后,它永远成立。这与参考页(
api/rest.md等)的修法相反:那边该改钉符号,因为它描述的是「现在的行为」;changelog 描述的是「当时发生了什么」,该钉当时的 commit。把两者混为一谈会修错 —— 给 changelog 更新行号,下次重构又坏。
范围
只动两个 changelog 文件各一行,与 #810 无文件重叠(那条动的是
api/rest.md)。#831 里其余那批(72 处判为漂,集中在tools.ts/api/rest.md)不在本 PR,它们属于「改钉符号」那一类,且会与 #810 冲突,应在 #810 收口后一并处理。