From e71bb603ba3980227022453b6d1776266aba1498 Mon Sep 17 00:00:00 2001 From: albert4719 Date: Mon, 21 Sep 2026 19:15:58 +0800 Subject: [PATCH] =?UTF-8?q?CI=20=E5=8A=A0=E4=B8=80=E4=B8=AA=E7=8B=AC?= =?UTF-8?q?=E7=AB=8B=E7=9A=84=E4=BA=A4=E5=8F=89=E5=BC=95=E7=94=A8=E6=A3=80?= =?UTF-8?q?=E6=9F=A5=20job=EF=BC=8C=E4=B8=8D=E9=98=BB=E5=A1=9E=E7=94=B5?= =?UTF-8?q?=E5=AD=90=E4=B9=A6=E5=8F=91=E5=B8=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/workflows/book.yml | 14 ++++++++++++++ CLAUDE.md | 2 +- 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/.github/workflows/book.yml b/.github/workflows/book.yml index 2c93e69..4a53b35 100644 --- a/.github/workflows/book.yml +++ b/.github/workflows/book.yml @@ -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: diff --git a/CLAUDE.md b/CLAUDE.md index c36fdb3..039b179 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 节两条互指的运动条各自指错)。写正文时顺手带上锚点即可,读者也不用跳转就知道指的是什么。