fix(tooling): 文档审计范围改为从目录派生,清单与磁盘不一致时判红 (#4851)

[xuyushun441-sys]

Fixes #4851

实情先行:议题说的是「11 条 objectos 路径」,实测烂得更彻底

议题正文的写法本身就是本单要防的东西,所以我没有信它,而是从仓库现状重新测量:

	数量	说明
清单条目	146	不是文件头注释里写的 147
指向 objectos/* 的死条目	10	不是 11(#4781 已删掉 runtime-capabilities.mdx)
全部死条目	16	除 objectos 那 10 条,还有 ai/chatbot-integration、deployment/cloud-artifact-api、getting-started/cli、getting-started/validating-metadata、permissions/roles、ui/role-based-interfaces
磁盘上存在但根本不在清单里的文档	48	含 protocol/kernel/** 全部 9 页、整个 content/docs/capabilities/ 目录、releases/v12–v17 等
实际手写文档总数	178

也就是说:一次打印 FULL audit (no args.docs given) 的运行,实际审的是 178 篇里的 130 篇。

议题只问了第一个方向(死条目),而 第二个方向(漏列)烂得多三倍,并且没有任何人问起过 —— 这正是「手写清单」的性质:它两个方向同时腐烂,且两个方向都不出声。

为什么这 16 条会烂,以及为什么烂了两个月没人知道

清单头上原本写着「Keep in sync with node scripts/docs-audit/affected-docs.mjs --all」—— 一句没有任何东西检查的承诺。目录改名(protocol/objectos/ → protocol/kernel/)是一次纯 content/** 的改动,不触发任何与该清单相关的门禁,清单就地失效。

失效之后没有任何信号,是因为审计 agent 拿到一条不存在的路径,读不到文件,返回 fixCount: 0 —— 在运行摘要里,这和「这篇审过了,没问题」长得一模一样。#4781(runtime-capabilities.mdx 整页教一个 #3605 已删的 schema)和 #4817(http-protocol.mdx 把 dispatcher 响应挂在 /api/v1/discovery 名下)两个真实失准就是这样在绿色的 full audit 底下活了约两个月。

清单能不能派生?能 —— 但不能在运行时派生

先回答议题里那个更根本的问题。答案分两半,分界线是工作流脚本的执行环境:

• 内容上完全可派生:审计范围就是 content/docs/**/*.mdx 减去 references/,没有任何人工挑选。这个定义已经存在于 affected-docs.mjs --all。
• 位置上不可派生:工作流脚本跑在一个 node:vm 上下文里,全局只有 log/phase/console/budget/定时器,加上 agent/parallel/pipeline/workflow/args,并且 codeGeneration 关闭 —— 没有 require、没有 import、没有文件系统、没有 eval。所以脚本既无法自己遍历 content/docs/,也无法去读一个 JSON 产物。清单必须内联。

结论:在生成时派生。清单改为一段生成产物,只是恰好住在一个手写文件里:

node scripts/docs-audit/check-audit-scope.mjs --write   # 从文件系统重新生成
pnpm check:docs-audit-scope                             # CI 门禁:两个方向都比

派生源刻意复用 affected-docs.mjs --all(子进程调用)而不是再写一遍目录遍历 —— 「手写文档」只能有一个定义;第二次遍历就是下一个会漂移的东西。

新校验的双向证明

绿(当前分支状态)

$ node scripts/docs-audit/check-audit-scope.mjs
✓ docs-accuracy-audit scope is in sync with content/docs/: 178 hand-written doc(s).
exit=0

红 #1 —— 把一条路径改回改名前的写法

$ node scripts/docs-audit/check-audit-scope.mjs
✗ .claude/workflows/docs-accuracy-audit.js: ALL_HANDWRITTEN has drifted from content/docs/.

  1 listed path(s) do not exist — an audit agent pointed at one reads
  nothing and reports "0 fixes", which in the run summary is indistinguishable
  from a doc that was checked and found accurate:
    - content/docs/protocol/objectos/http-protocol.mdx

  1 hand-written doc(s) exist but are not listed — a run that calls
  itself a "FULL audit" silently skips every one of them:
    + content/docs/protocol/kernel/http-protocol.mdx

  Fix: node scripts/docs-audit/check-audit-scope.mjs --write
exit=1

红 #2 —— 在磁盘上真的把目录改名回去(即 #4851 的原始机制本身)

$ git mv content/docs/protocol/kernel content/docs/protocol/objectos
$ node scripts/docs-audit/check-audit-scope.mjs
✗ … 9 listed path(s) do not exist:
    - content/docs/protocol/kernel/config-resolution.mdx
    - content/docs/protocol/kernel/error-handling.mdx
    … (9 条全部点名)
exit=1

红 #3 —— 把生成标记删掉(门禁找不到自己的审查对象)

✗ .claude/workflows/docs-accuracy-audit.js: could not find the generated scope block.
  Expected a region delimited by "// < generated:docs-audit-scope >" and "// < /generated:docs-audit-scope >".
  … do NOT hand-maintain the list.
exit=1

红 #4 —— 手工从清单里删掉一条(清单本身没有死条目,只是漏列)

✗ … 1 hand-written doc(s) exist but are not listed:
    + content/docs/index.mdx
exit=1

恢复后重新判绿,git status 干净。四种红都不是「跑完了报个漂亮的绿」,而是点名到具体条目。

CI 门禁只看得见默认清单 —— 所以另外补了两张网

args.docs 是这个工作流最常见的调用方式(affected-docs.mjs 的输出直接传进来),而没有任何 CI 门禁能看见调用方传了什么。一条坏路径在那里失败的方式,和 #4851 里那份烂清单完全一样。

1. 启动前置校验(Scope Preflight):解析出 DOCS 之后、进入昂贵的 pipeline 之前,先派一个 agent 机械地 ls 每一条路径,任何一条解析不到就 throw 并点名。这一步必须走 agent,因为 VM 没有文件系统 —— 也正因如此它是「报告」而不是「测量」,所以它自己的算术要被核对:返回的路径必须与 scope 不重不漏地一一对应,对不上就按「前置校验失败」处理,而不是当成通过。(自检本身没人检 = merge.os-regen.driver 指向「上一个装过依赖的 worktree」的绝对路径 —— 该 worktree 一删,全容器的生成物合并驱动就坏了 #4868。)
2. 真实读取路径上的 docExists:每个审计 agent 现在必须报告它到底有没有打开成文件,任何一条 false 都让整轮 throw。前置校验和真正读文件的不是同一条调用路径,而 merge.os-regen.driver 指向「上一个装过依赖的 worktree」的绝对路径 —— 该 worktree 一删,全容器的生成物合并驱动就坏了 #4868 的教训正是:跑在别处的自检,证明不了真实路径上的任何事。

于是三层各管一段:门禁管默认清单,前置校验管调用方的清单,真实读取路径两个都复核。

扫到 protocol/kernel 之后有没有发现真实失准

按 PM 要求不顺手修,只如实报告。我这边跑不了那个 LLM 工作流(Workflow 工具不在我的工具集里,且 9 页 ≈ 18 个 agent),所以做的是一轮机械抽查,不能替代真正的审计:

• 9 页里 HOUSE_FACTS 词表(os studio / client.ai.chat / /_studio / AUTH_SECRET / objectstack-ai/spec / …)零命中;
• 页面里出现的 @objectstack/* 包名逐一对照 workspace,3 处不存在的(@objectstack/service-ai、@objectstack/ui、@objectstack/testing)都带着显式的 "proposed / target / 不存在" 说明,不是失准;@objectstack/service-ai 那条更是与 packages/spec/src/system/core-services.zod.ts:142 逐字相符;
• objectos 残留:0。

结论:机械抽查未发现新的失准。 这不等于那 9 页干净 —— 真正的实现级审计还没跑过,建议合并后按正常流程跑一轮 scoped audit。

顺带发现(已按 Prime Directive #10 立单,未在本 PR 修)

#4920 —— 审计工作流的交付物是就地改写 mdx,而它的范围包含 content/docs/releases/**,与 AGENTS.md「releases 是 release-owned,禁止在代码 PR 中编辑」直接冲突。这不是本 PR 引入的(旧清单里已有 3 页 releases),但派生后从 3 页变成 9 页,第一次显眼。修它等于在本仓引入第二套「手写文档」定义,是需要维护者拍板的口径决定,故立单不改。

共享文件

本 PR 触到两个本仓最热的冲突点,均为新增一行/一步,无改写:

• package.json:新增 check:docs-audit-scope(合并 main 时与 fix(scripts): check:doc-authoring 覆盖 .claude 语料,worktrees 进 SKIP_PATHS (#4913) #4915 在相邻行冲突过,已保留对方的 --self-test 改动);
• .github/workflows/lint.yml:在 lint job 里新增一步。放这里是刻意的 —— 会打破这份清单的改动是一次文档改名,packages/** 的 paths filter 会让门禁恰好对自己的失效模式失明(.claude/skills/** 的 markdown 不被任何门禁扫描 —— check:nul-bytes 只看 JS/TS,check:doc-authoring 的 ROOTS 不含 .claude/ #4890 那一族)。

验证

$ pnpm check:docs-audit-scope
✓ affected-docs self-test: 32 cases pass.
✓ check-audit-scope self-test: 13 cases pass.
✓ docs-accuracy-audit scope is in sync with content/docs/: 178 hand-written doc(s).

$ pnpm lint      # eslint . --no-inline-config,2990 文件(含 .claude/workflows/*.js)
exit=0

$ pnpm check:doc-authoring
✓ doc authoring guard: 219 files clean.

新增的 --self-test 13 条用例是密封的(不依赖仓库状态),覆盖:标记缺失必须 throw、手写形态的数组必须 throw、渲染/解析往返、以及差异的两个方向各自单独钉住(议题只问了 dead,而 unlisted 才是三倍的洞)。

---

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)
objectstack	Ignored		Aug 3, 2026 4:18pm

[github-actions]

📓 Docs Drift Check

No hand-written docs reference the 0 changed package(s). ✅