Uh oh!
There was an error while loading. Please reload this page.
ci(check-links): 恢复 pull_request 断链门,仅检仓内链接、advisory-first (#6028) - #6304
Merged
Conversation
按维护者 2026-08-07 裁决恢复 `Check Links`:重新启用 `pull_request` 触发(branches: main),保留 `workflow_dispatch`,`fail: true` 不变; 方向②(留空壳写注释)已被否决,故被注释掉的 `push:` 残骸按 「declared = enforced」直接删除,而不是留在文件里继续误导读者。 ⛔ advisory-first:不进 required 集,也不加 `merge_group` —— advisory 车道不该消耗合并队列容量。日后若晋级 required,必须按 #6121 的教训在 同一次改动里补上 `merge_group`,否则队列会卡在一个永不上报的必需检查上。 仅检仓内链接的机制选 `--offline`,写在调用处而不是 lychee.toml: 实测 `offline = true` 这个配置键在 lychee 0.19.1 上被静默忽略、在 action 当前钉住的 0.24.2 上才生效,确定性保证不能取决于 action 恰好 装了哪个版本。`^https?://` 这类 exclude 也不够 —— 它要逐个枚举远程 scheme,漏一个就重新引入外网依赖。 门休眠半年期间配置已经漂移到跑不起来,这次一并修好(否则恢复触发器 只会让门以 exit 3 直接死掉,连链接都不检): - `follow_redirects` 在 0.24.2 上根本不是合法键 —— 硬解析错误; - `include_fragments` 已从 bool 变成枚举,裸 `false` 同样硬报错, 改为 `"none"` 保持原语义(不检 fragment)。 root-relative 链接是 content/** 的主力写法,而 lychee 在没有 root-dir 时对它们直接报错。补 `--root-dir <workspace>/content` + `--fallback-extensions mdx,md` 之后,1286 条此前完全没被检查的 `/docs/*` 链接首次纳入检查面(134 → 1476 条被检)。原来的 `remap` 块一次都没生效过(URI 构造在 remap 之前就失败),已按 declared = enforced 删除,能力由真正生效的 root-dir 承接。 修掉门首次真正运行后暴露的 22 条既有真断链(仅改链接目标,不改散文): - 14 条 ADR 链接归一到仓内既有约定(29 处在用的 GitHub blob URL): `/adr/*` 站点路由并不存在,apps/docs 只有 /[lang]/docs 与 /[lang]/blog 两条路由,也没有任何 /adr 重定向 —— 这些链接在线上 就是 404; - quick-reference 三行指向已退役 schema 的表项删除(audit.zod 按 ADR-0056 移除、registry.zod 按 #4939 退役、graphql.zod 全仓无踪), 并同步修正两处小节计数;connector-auth 有 schema 无页面,改为不带 链接保留信息;plugin-security 页面在 references/kernel 而非 cloud; - README 两处:`@objectstack/account` 已迁到 packages/apps/account; `service-feed` 已在 #1955 删除,整行移除。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BDmDsu2575gDxeMCxXhDE3
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
`content/docs/references/**` 是 `packages/spec` 的生成物(文件头写着 AUTO-GENERATED — DO NOT EDIT),上一个 commit 只改了生成出来的 state-machine.mdx,下一次 `gen:docs` 就会把它冲掉 —— 由 os-regen pre-commit 钩子当场拦下。 按 contract-first 修在生产者:`packages/spec/src/automation/state-machine.zod.ts` 的 JSDoc 里那条 ADR 链接原本写作 `../../../docs/adr/0020-...md`,从 `packages/spec/src/automation/` 出发解析到 `packages/docs/adr/...` —— 这个 目录并不存在,所以源头本身就是断的,生成物只是忠实地把它复制了出来。 改为仓内既有约定的 GitHub blob URL(全仓 29 处在用),它与文件位置无关, 生成到任何深度的目录都成立。 重新生成后 `content/docs/references/automation/state-machine.mdx` 与本次 生成输出完全一致(regen 后工作树对该文件零 diff),生成物与源头就此对齐。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BDmDsu2575gDxeMCxXhDE3
声明 B(咬合面)的红段:预期本次 push 让 Check Links 变红,且报错点名 content/docs/kernel/services-checklist.mdx:188 指向的 ./services-probe-6028-does-not-exist.mdx。下一个 commit 会 git revert 本提交,预期转绿;最终该文件相对 origin/main 净零 diff。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BDmDsu2575gDxeMCxXhDE3
…tore-check-links-gate
main 带来了 docs 生成器改动(changeset `docs-gen-description-line-layout-and-nested-links`:去掉逐行空行布局、 不再把行内代码路径转成嵌套链接)。该参考页是生成物,两边都改过, 文本合并的结果并不等于生成器的输出 —— os-regen 钩子说的正是这种 「被合并但没有真正重新生成」的状态。 `gen:schema && gen:docs` 后仅此一个文件有 diff(232 个生成文件里的 1 个),内容即新生成器的输出;本单在源头 JSDoc 里改的 ADR-0020 链接 原样保留。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BDmDsu2575gDxeMCxXhDE3
Contributor
📓 Docs Drift CheckThis PR changes 1 package(s): 112 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
This reverts commit 34b5d9f.
hotlong
marked this pull request as ready for review
August 7, 2026 14:31
This was referenced Aug 7, 2026
Uh oh!
There was an error while loading. Please reload this page.
This was referenced Aug 7, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes#6028
按维护者 2026-08-07 裁决恢复
Check Links断链门。裁决原文与本 PR 的逐条对应见下。一、裁决 → 实现的逐条对应
pull_requesttrigger".github/workflows/check-links.yml恢复pull_request(branches: main),workflow_dispatch保留--offline(理由见第三节),外链一律 EXCLUDED、零网络请求push:残骸按「declared = enforced」直接删除,不留空壳merge_groupCheck Documentation Links绿,1697 条链接 0 error(第六节)fail: true原样保留。二、触发器 diff(before / after)
before:
after:
push:两行注释残骸没有被"恢复",而是被删除 —— push 触发不在裁决范围内,如需恢复请另议。裁决只点名了pull_request,而方向②被明确否决之后,把一段注释掉的触发器继续留在文件里就是它反对的那种空壳。三、仅检仓内链接的机制:选
--offline,且写在调用处裁决允许机制自选。选
--offline而不是exclude = ["^https?://"],并且写在 workflow 的args:里而不是lychee.toml,两个选择都由实测决定:为什么是
--offline而不是 exclude pattern —— exclude 要逐个枚举远程 scheme,漏一个(ftp:、协议相对//host/path、将来任何新 scheme)就重新引入外网依赖;--offline是"不发任何网络请求"的硬保证,结构上做不到漏。为什么写在调用处而不是配置文件 —— 实测
offline = true这个配置键:lycheeverse/lychee-action@v2当前lycheeVersion默认值):生效。一个"确定性"保证不能取决于 action 恰好装了哪个版本 —— 一旦 action 改了默认版本,配置键式的写法会静默退回联网。写在调用处则两个版本都生效。
四、门休眠半年,配置已经漂移到跑不起来(裁决没预料到的部分)
这是本 PR 比"取消两行注释"多出来的工作量,也是必需的:只恢复触发器的话,门会以 exit 3 直接死掉,一条链接都不检。
lychee.toml里有两个键在 action 钉住的 0.24.2 上是硬解析错误:follow_redirects—— 在 0.24.2 上根本不是合法键;include_fragments = false—— 已从 bool 改成枚举none | anchor-only | text-only | full,裸false同样硬报错。改为"none",保持原语义(不检 fragment)。半年没人跑,所以半年没人发现。这正是"看起来在守而实际不守"的代价。旁证:该 workflow 最后几次真实运行(2026-01-28,即触发器被注释掉的当天)全部 failure;此后唯一一次
pull_request运行是 2026-07-17 的docs/generator-fixes分支,4 次全红。另外,
content/**里的主力内部链接写法是 root-relative 站点路由(/docs/permissions这种),而 lychee 在没有--root-dir时对它们直接报错("Cannot resolve root-relative link ... provide a root dir")。补上--root-dir ${{ github.workspace }}/content+--fallback-extensions mdx,md之后:原来的
remap块声称把/docs/*映射到content/docs/*.mdx,一次都没生效过(root-relative 链接在 remap 之前就 URI 构造失败)。按 declared = enforced 删除,能力由真正生效的--root-dir承接。同时删掉一条file://**/content/docs/**的 exclude:它实测匹配不到任何东西 —— 而这恰恰是门还剩一点覆盖的唯一原因,它要是真按字面生效,会把整个扫描面排除掉。--exclude '^/'(把 root-relative 链接整体排除)。在 0.24.2 上无效 —— 这类链接在 exclude 匹配之前就已解析失败,实测仍报 1348 个 error。所以--root-dir不是"顺手加的",而是这道门能跑绿的唯一路径。五、既有断链修复清单(22 条,仅改链接目标,不改散文)
ADR 链接归一(14 条) —
/adr/*站点路由根本不存在:apps/docs只有/[lang]/docs/[[...slug]]与/[lang]/blog/[[...slug]]两条路由,apps/docs/redirects.mjs里也没有任何/adr重定向 ⇒ 这些链接在线上就是 404。仓内既有约定是 GitHub blob URL(29 处在用 vs 坏写法 13 处),故归一到多数约定;12 个目标文件已逐一验证存在于docs/adr/。content/docs/permissions/authorization.mdx× 11content/docs/permissions/attachments-access.mdx× 1content/docs/ai/connect-mcp.mdx× 1state-machine参考页 × 1 —— 修在生产者:content/docs/references/**是packages/spec的生成物(文件头有 AUTO-GENERATED 标记),第一版误改了生成物,被 os-regen pre-commit 钩子当场拦下;已按 contract-first 改到源头packages/spec/src/automation/state-machine.zod.ts的 JSDoc。该链接原写作../../../docs/adr/0020-...md,从packages/spec/src/automation/出发解析到packages/docs/adr/...—— 源头本身就是断的,生成物只是忠实复制。quick-reference.mdx(6 条)
audit.zod已按 ADR-0056 移除(packages/spec/src/system/index.ts有明确记录);registry.zod已在ApiRegistry/api-registryplugin 只在packages/core/examples/里被装配,无任何真实 composition 挂载 ——ApiEndpointRegistrationSchema因此整面零执行 #4939 按 ADR-0049 退役(packages/spec/src/api/index.ts有明确记录);graphql.zod.ts/GraphQLConfig/FederationEntity全仓无踪;packages/spec/src/shared/connector-auth.zod.ts)但参考页从未写过 ⇒ 保留行、去掉死链,信息不丢;references/kernel/而非references/cloud/⇒ 纯改链接目标。README.md(2 条)
@objectstack/account已迁到packages/apps/account⇒ 改路径;@objectstack/service-feed已在 refactor(audit): retire service-feed; sys_comment canonical (ADR-0052 §5) #1955(ADR-0052 §5)删除 ⇒ 整行移除。content/blog(1 条)
/docs/specifications页面不存在 ⇒ 改指/docs/references(参考索引页)。⛔ 未触碰
content/docs/kernel/runtime-services/data-service.mdx(#6002 面锁),该文件也未出现在任何断链里。六、反向验证(三段预期均在执行前写下)
声明 A(触发面) — 预期:PR 开出后
Check Links必须作为 check 出现并跑完。结果:成立。
Check Linksrun #554(31183937132),event: pull_request,关联 PR #6304。mergeable_state = "dirty"—— GitHub 建不出 merge ref,而pull_request事件的 workflow 正是跑在 merge ref 上,于是一个 run 都不产生(不是 queued,是根本不存在)。git merge origin/main解掉之后,6 个 workflow 立刻全部入队。"PR 上没有 check"和"触发器没生效"是两件事,别把前者读成后者。声明 B(咬合面) — 预期:探针 commit 把
content/docs/kernel/services-checklist.mdx:188的相对链接./services.mdx改指不存在路径 ⇒ 红且报错点名该链接;git revert后 ⇒ 绿;最终该文件对origin/main净零 diff。结果:三段全部成立。
34b5d9f(探针)6a25d48(revert)红段报错正是探针那一条,别无其他:
净零证明:
git diff origin/main -- content/docs/kernel/services-checklist.mdx输出 0 行。声明 C(确定性面) — 预期:B 的失败输出来自相对路径解析,而非任何 HTTP 请求。
结果:成立。 红段 run 的统计表:
报错是
file://URI 的File not found(本地路径解析),Timeouts 与 Redirected 双 0,而 221 条外链无一例外都是[EXCLUDED] ... | This is due to your 'exclude' values—— 从未发出请求。另一项确定性证据:CI 的这组数字与本地用同版本 lychee(0.24.2)跑出来的完全一致(1697 / 744 / 1475 / 221 / 1),即同一份配置在本地与 CI 得到同一结论,可复现。整个 job 耗时 1.4 秒。七、不在本 PR 里
merge_group触发:未加 —— advisory 车道不该消耗合并队列容量。日后若晋级 required,必须在同一次改动里补上merge_group,否则队列会卡在一个永不上报的必需检查上(objectui-pin-freshness.yml 的注释在邀请把Console Pin Freshness加进 required 集,而它没有merge_group触发器——照做即合并队列全死锁(observation) #6121 的教训),届时另单。push:触发:不在裁决范围内,如需恢复另议。skip-changeset标签(CI 上Check Changeset已 skipped)。quick-reference.mdx的协议索引与packages/spec现状漂移:三处小节计数不符 + connector-auth 有 schema 无参考页 #6319:quick-reference.mdx的三处小节计数与实际行数不符(Kernel 17/15、Cloud 5/6、Shared 5/12,均为本 PR 之前就存在),以及connector-auth有 schema 无参考页。