CI 加一个独立的交叉引用检查 job,不阻塞电子书发布

This commit is contained in:
albert4719
2026-09-21 19:15:58 +08:00
parent fb118a7751
commit e71bb603ba
2 changed files with 15 additions and 1 deletions
+14
View File
@@ -41,6 +41,20 @@ env:
TYPST_VERSION: '0.15.1'
jobs:
# 交叉引用检查。单独一个 job,不挂在 build 里:锚点没补好不该连累 EPUB、PDF 和
# 离线单文件的发布,那是两回事。PR 上照样红,main 上该发的还是发出去。
# 本地那条链路(sync-stats.ps1)只在 Windows 上跑,而且找不到 node 时会静默跳过,
# 外部 PR 更是完全跑不到,所以这道检查得在 CI 里有一份。零依赖,几秒钟。
refs:
name: 交叉引用检查
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- run: node tools/check-refs.mjs --check
build:
runs-on: ubuntu-latest
steps:
+1 -1
View File
@@ -53,7 +53,7 @@
- 收益量级尽量按阈值从条目自己的「收益」栏机械套,不凭感觉:死亡率口径看相对降幅(≥20% 大 / 10–20% 中 / <10% 或只有替代终点 小);金钱看金额(万元级 大 / 数百到数千 中 / 几十元 小);自由看后果(避免刑责 大 / 避免拘留或行政处罚 中 / 避免民事纠纷 小);时间看节省量(每天小时级 大 / 每周小时级 中 / 一次性 小)。数字不足以判定时才用判断,并在核实记录里写明凭什么定的。
- 条目数、A 级条数变了要同步四处:README(正文数字与两个徽章)、index.html(五处描述、numberOfPages、页头条目数)、CLAUDE.md 的目录简介,以及 **tools/og.html + 重新截图 og.png**(命令写在 og.html 文件头注释里,链接数的口径是 book/ 下所有「- 来源:」和「- 备注:」行里的 http(s) 总数)。跑 `powershell -ExecutionPolicy Bypass -File tools\sync-stats.ps1` 一键完成:它重算条目数、A/B/C 数、争议数、TODO 数、链接数和性价比三档,回写 README 的八处、index.html 的三类位置、tools/og.html 的三个数字,再用全新的 user-data-dir 重出 og.png(`-NoScreenshot` 可只改数字)。**CLAUDE.md 的目录简介脚本不碰,仍要手工改。**性价比档的规则和 index.html 的 COST_W、e.ratio 两行绑定,那两行改了脚本会直接报错要求同步。**每次改完条目就跑一次,和正文改动一起提交**(2026-09-18 用户定;当天早些时候的「等我说改完了再改」已作废——脚本把一次同步的开销压到几百 token,不必再攒着)。跑完不用打开 og.png:脚本自己校验图是本次写入、大小在 120KB 到 400KB,只有改过 tools/og.html 版式时才值得看一眼。汇报里也不必再写「待同步」,直接给同步后的数字。
- **插入或删除条目之后,必须扫一眼 `docs/引用对照.md` 的 diff**(2026-09-19 用户问「怎么防范引用错位」时定的)。正文里 257 处「第 X 条」引用只记条号不记内容,插一条进去后面的条号集体顺延,引用却留在原地——而顺延后的条号通常**仍在范围内**,查越界一条也抓不到(第 7 节曾有 6 处指错:医疗救助指到低保、救助站指错条,全是这么来的)。`sync-stats.ps1` 末尾会自动跑 `tools/check-refs.mjs`,把每处引用**实际指向的条目标题**连同引用处的上下文写进 `docs/引用对照.md`,该文件入库。**判据:条号没变而「指向的条目」那列变了,就是被撞歪的引用**;表里还带着引用处前十几个字,和标题一对就知道指没指对。CI 用 `node tools/check-refs.mjs --check`(有问题则退出码 1)。
- **插入或删除条目之后,必须扫一眼 `docs/引用对照.md` 的 diff**(2026-09-19 用户问「怎么防范引用错位」时定的)。正文里 257 处「第 X 条」引用只记条号不记内容,插一条进去后面的条号集体顺延,引用却留在原地——而顺延后的条号通常**仍在范围内**,查越界一条也抓不到(第 7 节曾有 6 处指错:医疗救助指到低保、救助站指错条,全是这么来的)。`sync-stats.ps1` 末尾会自动跑 `tools/check-refs.mjs`,把每处引用**实际指向的条目标题**连同引用处的上下文写进 `docs/引用对照.md`,该文件入库。**判据:条号没变而「指向的条目」那列变了,就是被撞歪的引用**;表里还带着引用处前十几个字,和标题一对就知道指没指对。CI 用 `node tools/check-refs.mjs --check`(有问题则退出码 1),它是 `book.yml` 里名为「交叉引用检查」的独立 job,**故意不挂在 build 里**:锚点没补好不该连累 EPUB、PDF 和离线单文件的发布,PR 上照样红、main 上该发的还是发出去。这个 job 是 2026-09-21 补的——在那之前 CLAUDE.md 写着「CI 用」但 workflow 里其实没有这一步,全靠本地 `sync-stats.ps1`,而那条链路只在 Windows 上跑、找不到 node 时还会静默跳过(脚本里就是打一句「跳过引用对照表」然后继续),外部 PR 更是完全跑不到。
- **每处引用都要带锚点**(2026-09-19 同一轮定的):引用的前后文里必须有一个词和目标条目标题对得上——「医疗救助见第 11 条」里的「医疗救助」就是锚点;实在没有就显式写成「见第 16 条(借条和担保)」,括号里的词从目标标题里取。**裸条号一律不允许**(「实际算法可以看第 34 条」「和第 4 条二选一」这种),因为它被顺延撞歪之后,连对照表的 diff 都看不出异常——条号没变、指向的标题变了,可那处引用本来就没说自己要指什么。`--check` 会把裸条号判为失败并列出位置,`--suspect` 看完整清单。**相对指路同样禁用**(2026-09-20 加):「见下一条」「罚则见上一条」「按前一条的渠道走」这类不带条号,插条目时跟着整体平移,撞歪了对照表 diff 也看不出来,裸条号检查更扫不到它。当天一次扫描就查出三处早就指错的——HPV 疫苗条的「见下一条」指到乳腺癌筛查(该指宫颈癌筛查)、扬言条的「罚则见上一条」指到自己冒出念头那条、失业登记条的「上一条不签主动辞职」指到存证据条,全书 19 处已逐一改成「第 N 条(锚点词)」,`--check` 现在把它判为失败。当天把全书 309 处引用逐一补齐锚点,从 75 处裸条号清到 0;补的过程中又揪出两处错位(第 9 节第 6 条把「替人取现转账」指到了「黄色视频自己看归自己」,第 2 节两条互指的运动条各自指错)。写正文时顺手带上锚点即可,读者也不用跳转就知道指的是什么。