Skip to content

check-links.yml(Lychee)扫的是 docs/**(15 个文件),不是站点文档 content/docs/**(183 个文件) #3449

Closed
#3477
Closed
check-links.yml(Lychee)扫的是 docs/**(15 个文件),不是站点文档 content/docs/**(183 个文件)#3449
#3477
Assignees
yinlianghui
Labels
bugSomething isn't workingpm:dispatchedpm:queue

Description

@yinlianghui
yinlianghui
opened on Aug 6, 2026

现象

.github/workflows/check-links.yml 里 Lychee 的扫描目标是:

args: |
  --verbose
  --no-progress
  --config lychee.toml
  'docs/**/*.md'
  'docs/**/*.mdx'
  'README.md'

但站点发布的文档并不在 docs/,而在 content/docs/(apps/site/source.config.ts 里 dir: '../../content/docs',apps/site/lib/source.ts 里 baseUrl: '/docs')。

实测两棵树的规模:

$ find docs -name '*.md' -o -name '*.mdx' | wc -l
15          # ARCHITECTURE.md、CONSOLE-STREAMLINING-SUMMARY.md、adr/、audits/ …

$ find content/docs -name '*.md' -o -name '*.mdx' | wc -l
183         # 实际发布的站点文档

也就是说:即使有人手动 workflow_dispatch 触发 Lychee,它也从来没有检查过发布出去的那 183 个文档文件。 根目录 docs/ 是内部资料(ADR、审计报告、架构说明),被扫的是它。

为什么现在记为 finding 而不是缺陷

check-links.yml 目前只有 workflow_dispatch(push/pull_request 被注释掉,见 #3213),从不自动运行 —— 属于「未被执行的配置漂移」,今天没有用户会撞到。因此按 finding 归类,不带 pm:queue。

与 #3213 裁决的关系

#3213 的裁决是「B 保持定时/手动(可选补 cron)」。修复 #3213 的 PR 有意没有加这条 cron,理由就是本 issue:在扫描范围还指向错误目录时加 cron,只会按时产出一份「检查了内部 ADR、没检查站点文档」的绿色报告,是加噪声不加覆盖,并且会让人误以为已发布文档的外链已被守住。

建议顺序:先修扫描范围,再谈是否加 cron。

建议

  1. 把 args 的扫描目标改为 content/docs/**/*.md、content/docs/**/*.mdx(是否保留 docs/** 与 README.md 由维护者定;两棵树都扫也合理)。
  2. 范围修正后,再决定要不要补 schedule cron —— 届时 cron 才有意义。
  3. 注意 Lychee 是外链检查器(走网络、有 rate limit、天然会 flaky),与 scripts/check-doc-links.mjs 只校验站内 /docs/... 路由是互补关系,不是重复。这也是裁决把 A 放进 PR 门禁、B 留在定时/手动的原因。

相关

Activity

  1. yinlianghui
    added
    finding
    on Aug 6, 2026
  2. yinlianghui
    added 2 commits that reference this issue on Aug 6, 2026

    docs(ci): 把新增的链接门禁写进 ci-cd-pipeline.md,并说明两个检查器的分工

    c88ab6b

    merge main: resolve ci-cd-pipeline.md union with #3456

    0781cb9
  3. yinlianghui
    added
    bugSomething isn't working
    pm:queue
    and removed
    finding
    on Aug 6, 2026

  4. yinlianghui commented on Aug 6, 2026

    @yinlianghui
    yinlianghui
    on Aug 6, 2026 – with Claude
    CollaboratorAuthor

    发现分诊轮(晋级):摘 finding 换 bug+pm:queue。前提复核 live:check-links.yml:25-26 仍扫 docs/**(15 个内部文件)而非站点的 content/docs/**(183 个)。具名单文件修;#3213 裁决里「可选 cron」的前置——范围不修,cron 只会定时产出假绿报告。

    Generated by Claude Code

  5. akarma-synetal
    added a commit that references this issue on Aug 6, 2026

    ci(docs): 把 check-doc-links 接进 CI,并修好它一直在报的那条坏链 (objectstack-ai#3213, o…

    223a92f
  6. yinlianghui
    added
    pm:dispatched
    on Aug 6, 2026
  7. yinlianghui
    self-assigned this
    on Aug 6, 2026

  8. yinlianghui commented on Aug 6, 2026

    @yinlianghui
    yinlianghui
    on Aug 6, 2026 – with Claude
    CollaboratorAuthor

    认领:objectui 分片 PM 并行批第 48 单
    会话:session_01GTRjn8xBqp75dk7kFupVRt
    分支:claude/issue-3449-lychee-scope
    Worktree:objectui-issue-3449
    文件面:.github/workflows/check-links.yml(+ lychee.toml 若需排除项)。

    PM 裁定(issue 留下的两点):① 扫描面两棵树都扫(content/docs/** 为主 + 保留 docs/** 与 README——内部 ADR 的外链也值得巡检,成本为零);② 同 PR 补 weekly schedule cron——范围修对后,#3213 裁决 B 的「定时巡检」本义才成立;cron 仅 schedule 不进 PR 门禁,外链 flaky 不伤门禁。如有异议此处否决。

    Generated by Claude Code

  9. yinlianghui commented on Aug 6, 2026

    @yinlianghui
    yinlianghui
    on Aug 6, 2026 – with Claude
    CollaboratorAuthor

    验收:ACCEPT → PR #3477(并行批第 48 单,会话 session_01GTRjn8xBqp75dk7kFupVRt),14/16 检查零失败(两个 shard 系 runner 拥堵,改动零包源码)。ready + auto-merge 因 GraphQL 配额排队,恢复即执行。

    复核要点:

    1. 裁定两点(两树都扫 + weekly cron)如实落地,且 dev 发现了派发词没看到的承重前提:content/docs 有 297 个站点绝对路径链接,Lychee 在 URI 构造阶段即失败、exclude 是空操作(实测),不改 lychee.toml 则 workflow 生而为红(316 错)。sentinel root_dir + 命名空间排除的修法保持「路由→文件解析只归 check-doc-links.mjs」单一职责,死 remap 配置的删除有「从未 fire 过」的证明。
    2. 拒绝 --fallback-extensions 是本单最重要的判断:它把 33 错降到 6,但吞掉的 13 个是真缺陷(.md 链到 .mdx 文件,fumadocs 路由下就是站上 404)——消费端宽容遮生产端错误,正是 #0.1 禁的形状。丑而真优于绿而假。
    3. 预期管理已写明:首次 cron run 会是真红(37 个真实断链,其中 README 的 4 个在旧扫描面里本来就红、只是从没人 dispatch 过)——届时不是 flake,是 content/docs 有 16 个失效的相对链接,且 check-doc-links.mjs 对相对链接一律放行 #3479/README.md 推荐了 4 个不存在的 example 应用(examples/crm、todo、kitchen-sink、msw-todo) #3480 的工作清单。
    4. pin 测试从 site config 派生期望范围(硬编码正是本 bug 的出生方式);dev 自己一条断言被测试抓错后按正确理由重写并存档。
    5. 衍生两单已分诊:content/docs 有 16 个失效的相对链接,且 check-doc-links.mjs 对相对链接一律放行 #3479(相对链接无任何门禁校验 + 16 个断链目标)bug+pm:queue;README.md 推荐了 4 个不存在的 example 应用(examples/crm、todo、kitchen-sink、msw-todo) #3480(README 幽灵示例 ×4)documentation+pm:queue。

    Generated by Claude Code

  10. yinlianghui
    closed this as completedin #3477on Aug 6, 2026
  11. akarma-synetal
    added a commit that references this issue on Aug 10, 2026

    fix(ci): point the Lychee sweep at content/docs and put it on a weekl…

    b1246cd
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

bugSomething isn't workingpm:dispatchedpm:queue

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions