docs(scripts): 按真实机制改写两处 Lychee 门禁描述,并删掉 judgeHref 重复注释 (#3587) (#3648)

[yinlianghui]

Fixes #3587
Fixes #3648

纯注释改动,零行为变化,两文件三处。

前提复核(先按内容锚定,再改)

正文引的行号确已大漂,但三处失真都还在 origin/main(93c2619,含 #3649):

处	issue 说的行	今天实际	结论
#3587 spot 1	check-doc-links.mjs:157	仍是 :157	存在,未被改写
#3587 spot 2	check-doc-links.test.ts:853	漂到 :886	存在,未被改写
#3648 重复注释	check-doc-links.mjs:689-696	漂到 :764-771	存在,git blame 指向 0e4ea07(#3629)

.github/workflows/check-links.yml 现状我重测过,不是照抄正文:

• 第 77 行 fail: true;grep -rn 'continue-on-error' .github/ 在别的工作流(live-e2e / shadcn-check / performance-budget)有命中,check-links.yml 里一处都没有;
• on: 只有 workflow_dispatch 与 schedule: '17 4 * * 0';push: / pull_request: 在 :44-47 被注释掉,上面就是 ⛔ Do NOT enable(pnpm docs:check-links 在 main 上就退出 1,但没有任何工作流跑它(两个链接检查器都不拦 PR) #3213 ruling B)。

所以「gates nothing」这个结论对,机制反了。

改动一:机制正确的表述(#3587)

scripts/check-doc-links.mjs(§2 自仓 blob/tree URL 那段):

改前

 * thing that would resolve it — is a weekly cron with `continue-on-error`, so
 * it gates nothing.

改后

 * thing that would resolve it — is a `schedule` + `workflow_dispatch` workflow
 * with no PR trigger, so it blocks nobody. (It is `fail: true`, not a
 * soft-failing job: what keeps it off pull requests is the absent trigger, not
 * a tolerated failure. #3213 ruling B says keep it that way — uncommenting
 * `pull_request:` would turn it into a hard gate over the network.)

措辞对齐同一文件 :194 起已有的正确版本(#3589 写的头注释:"that workflow is schedule + workflow_dispatch only … so it blocks nobody")——同一文件里两种说法并存,本来就是下一个读者踩坑的地方。括号那句是 issue 的核心指控落地:按旧注释行事的人会去摘一行不存在的 continue-on-error,而真实风险方向相反。

scripts/__tests__/check-doc-links.test.ts:886,某断言上方的说明文字,只改文字,断言一行未动:

改前

    // scheme, and lychee (weekly cron, continue-on-error) gates nothing.

改后

    // scheme, and lychee (`schedule` + `workflow_dispatch`, no PR trigger) blocks
    // nobody.

改动二:删掉重复粘贴的 4 行(#3648)

judgeHref() 里 "A URL on this site is an internal route wearing an origin…" 那 4 行出现两遍、一字不差,删掉后一份。

先预测后验证

预测	改前实测	改后实测	结果
grep -rn 'continue-on-error' scripts/ 归零	2	0	✅
grep -rn 'weekly cron' scripts/ 归零	2	0	✅
重复注释特征行 2 → 1	2	1	✅
node scripts/check-doc-links.mjs 前后同输出	Links are valid across 7 scan roots. exit 0	同上,exit 0	✅ 行为零变化
vitest 前后同绿同数	82 passed	82 passed(连 check-links-workflow.test.ts 共 89 passed / 2 files)	✅
pnpm type-check:scripts 绿	exit 0	exit 0	✅
pnpm check:control-bytes 绿	—	OK (scanned 3661 tracked text file(s)),另加 grep -naP 自扫两文件干净	✅

一处没按预测走、如实记下:草稿里我曾在新注释中写 "carries no continue-on-error" 来正面否认旧说法,那会让 grep 'continue-on-error' 停在 1 而不是 0。改用 "not a soft-failing job" 表达同一个意思,既保留了防误读的价值,又让 grep 真正归零。

围栏

• content/docs/guide/ci-cd-pipeline.md 未动——它对该工作流的描述本身正确(issue 已确认)。
• .github/workflows/check-links.yml 未动——本单只修注释,不改门禁行为。
• 无 changeset:scripts/ 不是发布包,且改动纯注释、零用户可见变化。
• 与在途 i18n 门禁:en 文案变更时其余九包必须同批跟改(或显式挂账)——#3582/#3625 族缺陷缺的那道不变量 #3650(在 scripts/ 新增 en-drift 门禁文件)实测零相交。
• 仓内 prettier 说明:pnpm exec prettier --check 对这两文件报 warn,但改前的 origin/main 版本同样报(默认配置下 389 / 1646 行差异),仓内既无 prettier 配置也无任何工作流跑 prettier——非本 PR 引入,不处理。

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01GTRjn8xBqp75dk7kFupVRt

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectui	Ignored		Aug 7, 2026 5:33pm