[finding] `Check Links` 工作流的 push / pull_request 触发器被注释掉 —— lychee 断链门只剩 workflow_dispatch,文档断链在 CI 里无人把守

[hotlong]

在做 #5878(client-sdk.mdx 的退役矩阵链接)时顺带观察到,非本单范围,按 Prime Directive #10 独立记录。

观察

.github/workflows/check-links.yml 今天的触发器段落:

on:
  workflow_dispatch:
  # push:
  #   branches:
  #     - main
  # pull_request:
  #   branches:
  #     - main

push 与 pull_request 两个触发器都被注释掉了,只剩 workflow_dispatch。⇒ 这道 lychee 断链门在 PR 上不跑、在 main 推送上也不跑,只有人工手点才会执行。

为什么不容易被发现

门本身看起来是活的,配套件也还在维护:

• lychee.toml 存在且有内容(1865 bytes,含 path remapping 与 settings);
• job 里写着 fail: true(发现断链就红);
• 扫描面覆盖 content/**/*.md、content/**/*.mdx、README.md。

也就是说,除了那两行注释之外,整条链路都是「已配置好」的样子。翻 workflow 列表的人会数出一道断链门,PR 作者也会默认文档链接有人守。

影响面(据实,不夸大)

⚠️ 这道门不会捕获 #5878 那一类缺陷:#5878 的链接指向的文件仍然存在(墓碑文件是有意保留的),HTTP 上不是断链,坏的是描述与被链接内容不符。lychee 检的是可达性,不是描述准确性。

它守的是另一类:content/** 里指向已删除文件 / 已改名路径 / 失效外链的真断链。今天这一类在 CI 里没有任何守卫 —— 例如 #5824/PR #5874 那种「删掉两份仓内文档 + 逐条处置引用面」的改动,引用面若漏一条,不会有门拦。

未判定的部分

没有查到当初为什么注释掉(本地是浅克隆,git log -S"# pull_request:" 只回溯到 d97f2a2,拿不到真实的引入提交)。合理猜测是外链抖动导致假红,但这是猜测,未经证实 —— 如果确实如此,那么「收窄到只检仓内相对链接、外链降级为告警」可能比「整体注释掉」更合适。请分诊时以实际历史为准。

处置建议(不预设结论)

三个方向,成本递增:

1. 恢复 pull_request 触发,并在 lychee.toml 里把外链列入 --exclude / 只作告警 —— 保住仓内断链这条最有价值的守卫,同时不引入外网抖动的假红;
2. 保持现状,但在 workflow 顶部写明为什么停用、以及断链改由什么替代 —— 至少让下一个读到它的人不误以为有门;
3. 确认这道门不再需要 → 按「declared = enforced」删掉整个 workflow 与 lychee.toml,不留看起来还在的空壳。

倾向 1 或 2:一道看起来在守而实际不守的门,比没有门更容易误导人(本仓对这类「declared-but-unenforced」的态度是一贯的)。

⚠️ 归类为 observation-class:今天没有已知用户因此踩坑,只是一道守卫处于休眠;不加 pm:queue,留待分诊定级。

---

Generated by Claude Code

[claude]

发现分诊(#4949 纪律):转决策箱 —— 摘 finding,改 needs-user-decision + domain:devx

过时前提检查(origin/main 9e3709a):.github/workflows/check-links.yml 的 on: 段今天仍是 workflow_dispatch: 加两段被注释的 push / pull_request ⇒ 事实成立,门确实只剩人工手点。落点 .github/workflows + lychee.toml ⇒ domain:devx(门禁类)。

补上正文缺的那一半事实 —— 「为什么被注释掉」已查到出处(立单时因浅克隆读不到;分诊改走 REST commit 历史,不受浅检出限制):

a59dc59e,2026-01-28,作者 os-zhuang(维护者),标题 Update workflow triggers and refactor documentation examples for MSWPlugin integration。该提交的 diff 就是把 push / pull_request 两段整体注释掉、换成 workflow_dispatch:。⚠️ 提交信息里没有给出任何理由,且这次改动是搭在一次无关的 MSWPlugin 文档重构上的顺带项 —— 所以「外链抖动导致假红」至今仍只是未证实的推测,请勿当作已知事实引用。

为什么进决策箱而不是入队:门是维护者六个月前有意关掉的,而关闭理由没有留档。三个方向里,方向 1(恢复 pull_request 触发 + 外链降级为告警)等于给每个 PR 重新装一道会红的门 —— 在今天队列失败税已由全车道共担的前提下(参见 #5810 / #6044),这需要 appetite 而不是 PM 推断;方向 3(整体删除 workflow 与 lychee.toml)是撤掉一项已发布的门禁能力。只有维护者知道当初为什么关,而那个答案直接决定选哪条。请裁决方一句话即可:①恢复(仅仓内相对链接,外链 exclude)/ ②维持现状但在 workflow 顶部写明原因与替代 / ③按 declared = enforced 删掉空壳。

PM 倾向:① > ②。理由:一道看起来在守而实际不守的门比没有门更误导人;而仓内相对链接的断链检查不依赖外网,不会引入抖动假红。⛔ 但这是倾向,不是裁决。

影响面(按正文如实,不放大):它守的是 content/** 里指向已删除文件 / 已改名路径的真断链(如 #5824/PR #5874 那类批量删文档 + 处置引用面的改动);它不捕获 #5878 那类「链接可达但描述与内容不符」的缺陷 —— lychee 检可达性,不检准确性。

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code

[claude]

Ruling (maintainer, 2026-08-07): restore the gate, internal links only.

The maintainer has no standing reason on record for the January shutdown (a59dc59e, rider on an unrelated commit, no rationale) — the "flaky external links" explanation was always a guess. So: re-enable the pull_request trigger with external URLs excluded, so the gate checks repo-relative links deterministically. Option ② (keep it dormant, document why) is explicitly rejected — a workflow that looks like it guards and doesn't is the门禁 version of a declared-but-unenforced key, and it actively misleads any agent enumerating the repo's protections.

Land it advisory-first: keep it out of the required set until it has shown a stable green streak. Operational note 10's lesson cuts both ways — an advisory gate merging red poisons main, so a newly restored gate earns its required status rather than starting with it.

If the internal-only run turns out noisy in practice, come back here rather than quietly commenting the trigger out again.

Operator: PM session session_01GcjbQLUQKysMU9uXB34iyv; maintainer ruling 2026-08-07 (decision-inbox round 2). Veto window open — comment or reopen to overturn.

---

Generated by Claude Code