Repository navigation
注释失真:两处称 Lychee 是「weekly cron with continue-on-error」,实际工作流是 fail: true 且根本没有 PR 触发器 #3587
Description
Activity
认领(PM 派发)。
- Session:
session_01GTRjn8xBqp75dk7kFupVRt - 分支:
claude/issue-3587-lychee-comment-truth - 文件面:
scripts/check-doc-links.mjs+scripts/__tests__/check-doc-links.test.ts两文件的注释行。前置:PR fix(docs,scripts): 清掉 9 条包 README 死链,并让链接门禁认站内绝对 URL (#3603) #3629/feat(scripts): check-doc-links 扫描面第四扩 packages/*/README.md,并付清入场价的 11 条死链 (#3622) #3649 已连改本文件两轮(第 2 层解析 + 第四扩),正文行号 :157/:853 必已大漂 — 按内容锚定,且先复核两处失真句在 feat(scripts): check-doc-links 扫描面第四扩 packages/*/README.md,并付清入场价的 11 条死链 (#3622) #3649 之后是否仍存在(feat(scripts): check-doc-links 扫描面第三扩 CONTRIBUTING/ROADMAP/docs (#3572) #3589 只订正过它自己新写的那句)。 - 并卡裁决:本单同时关 check-doc-links.mjs 的 judgeHref() 里有一段 4 行注释被逐字复制了两遍(PR #3629 引入) #3648(同文件,fix(docs,scripts): 清掉 9 条包 README 死链,并让链接门禁认站内绝对 URL (#3603) #3629 引入的 judgeHref 内重复 4 行注释)— 同为注释级清理,一 PR 双 Fixes,避免再串行一轮。
- 修法按 issue 建议:机制正确的表述(schedule + workflow_dispatch、无 PR 触发器、
fail: true,取消注释 pull_request 即成pnpm docs:check-links在 main 上就退出 1,但没有任何工作流跑它(两个链接检查器都不拦 PR) #3213 明令不要的硬门禁 — 措辞可取 fix(i18n,app-shell): 补齐 8 处无兜底裸 key 调用点的十语言包文案 (#3546 切片一) #3583 头注释的写法);ci-cd-pipeline.md 对该工作流的描述本身正确,不动。
Generated by Claude Code
- Session:
验收 ACCEPT → PR #3656(session_01GTRjn8xBqp75dk7kFupVRt),并卡同关 #3648。
已核:2 文件 +11/−10 零代码行;门禁/vitest/type-check 修前修后逐字节同输出(注释级零行为的完整佐证);CI 16 项 0 失败。
裁决记录:
- 前提复核规范(spot1 blame 到 feat(scripts): check-doc-links 两向扩展 —— 扫描面扩到 examples/** 与根 README,自仓 GitHub URL 离线校验 #3542 未漂、spot2 漂 33 行、重复注释 blame 确证 fix(docs,scripts): 清掉 9 条包 README 死链,并让链接门禁认站内绝对 URL (#3603) #3629 合并粘贴)+ workflow 三条独立重测 — 不照抄正文的纪律完整。
- 措辞自洽自查记入方法库:正面否认句「carries no continue-on-error」会自己种回特征 token 使 grep 停在 1 — 改用「not a soft-failing job」同义表达。修注释失真时,新注释不得复植失真特征词。
- 顺带统一了同文件 feat(scripts): check-doc-links 扫描面第三扩 CONTRIBUTING/ROADMAP/docs (#3572) #3589 写的正确表述与旧失真并存的问题,好。
- 新发现 prettier 是未接线的 devDependency:无配置、无 lint 集成、无工作流,
prettier --check对全仓假红 #3657 入池(prettier 未接线:无配置、无 workflow、eslint 不引 —--check默认值对 main 原始内容假红 389/1646 行,「看起来像自己闯的祸」型陷阱,下一个 agent 顺手 --write 就是几千行无关重排)— observation 定级正确,这个陷阱值得进 AGENTS.md 候选池。
Generated by Claude Code
观察类发现,PR #3583(#3572 扫描面第三扩)途中撞到,未在该 PR 内修复——它是 #3536 写下的既有注释,不属于 #3572 的改动面。
事实
两处注释把 Lychee「gates nothing」的机制说错了:
scripts/check-doc-links.mjs:157—— "lychee … is a weekly cron withcontinue-on-error, so it gates nothing"scripts/__tests__/check-doc-links.test.ts:853—— "lychee (weekly cron, continue-on-error) gates nothing"而
.github/workflows/check-links.yml的实际状态:fail: true—— 工作流里没有任何continue-on-error;on:只有workflow_dispatch+schedule(17 4 * * 0);push:与pull_request:被注释掉,并附⛔ Do NOT enable的说明(pnpm docs:check-links在 main 上就退出 1,但没有任何工作流跑它(两个链接检查器都不拦 PR) #3213 ruling B:外链检查走网络,一个 502 会把作者无能为力的 PR 弄红)。为什么结论对、理由错
「gates nothing」这个结论没错,但原因是它压根不在 PR 上跑(无
pull_request/push触发器),不是「跑了但不 fail」。这两件事的运维含义相反:continue-on-error摘掉就能让它变成门禁 —— 而那行不存在,摘不掉;fail: true,一旦有人取消注释pull_request:就会立刻变成硬门禁,正是pnpm docs:check-links在 main 上就退出 1,但没有任何工作流跑它(两个链接检查器都不拦 PR) #3213 ruling B 明令不要的结果。照错误理由行事的人会往反方向走。
影响
零用户可见影响,纯注释失真;但这两句正是后来者判断「这一面有没有门禁」的依据,#3536 与 #3572 的头注释都据此论证扫描面为何要扩。归为 observation-class。
建议修法(一行级)
把两处改成机制正确的表述,例如「a
schedule+workflow_dispatchworkflow with no PR trigger, so it blocks nobody」。content/docs/guide/ci-cd-pipeline.md对该工作流的描述(「It is deliberately not a PR gate」)本身是对的,无需改。参考:PR #3583 的新增头注释已按正确机制书写,可直接取用其措辞。