docs(cli): 兼容表两行失真 —— Node 行改指根 engines,删掉 CLI 并不依赖的 spec 兼容行

[yinlianghui]

Fixes #3689

单文件、净 -1 行:content/docs/utilities/cli.mdx 的 "Package information" 表。

前提复核:成立,且 Compatibility 行比 issue 正文重一档

issue 指的两行今天仍在 origin/main(切点 be9cd38ac),行号也没漂 —— 表正好是 277–283 行。全表五行逐行核实(不止 issue 点名的两行):

行	表里写的	仓库真相	判定
279	Name @object-ui/cli	packages/cli/package.json → "name": "@object-ui/cli"	✅ 真,留
280	Bin objectui	同文件 → "bin": { "objectui": "./dist/cli.js" }	✅ 真,留
281	License MIT	同文件 → "license": "MIT"	✅ 真,留
282	Node ≥ 18	根 package.json → {"node":">=22","pnpm":">=9"}	❌ 直接矛盾
283	Compatibility @objectstack/spec ^3.3.0	全仓 29 处声明全部为 ^17.0.0-rc.5;packages/*/package.json 里 ^3.3.0 命中 0	❌ 差一个大版本区间

Node 行的补充测量:39 个 packages/*/package.json 中带 engines 的只有 1 个(vscode-extension 的 {"vscode":"^1.85.0"},与 Node 无关),engines.node 为 0 个。即根 engines 是全仓唯一的 Node 下限声明。

Compatibility 行的补充测量,是本单相对 issue 正文的新事实:

$ node -e '读 packages/cli/package.json 的 dependencies/devDependencies/peerDependencies'
dependencies:    (none)
devDependencies: (none)
peerDependencies:(none)          ← 三类里都没有 @objectstack/spec

$ grep -rn "@objectstack/" packages/cli/src/
(零命中)                          ← 源码里也没有任何 @objectstack/* 引用

lockfile 侧交叉验证:pnpm-lock.yaml 里 30 个 importer 的 specifier: ^17.0.0-rc.5 / version: 17.0.0-rc.5(...) 完全一致,零个 ^3.3.0。

所以 283 行不只是版本陈旧,它在这一页上是幽灵行:@object-ui/cli 与 @objectstack/spec 没有直接依赖关系(只经由 @object-ui/{components,react,types} 三个 workspace 依赖间接触及)。这正是 PR #3688 里 @objectstack/client 那一类 —— 36 个 README 印了它,只有 1 个包真的依赖它。

处置:两行不同处置,依据实测而非统一口径

按 #3645 / PR #3688 的仓规「版本号入散文即漂移保证」,一律不改写成 ^17.0.0-rc.5 / >=22 —— 重写等于把同一台漂移机器重新上膛,下个 major 再错一遍。但两行的真相状况不同,处置因此不同:

• 282 Node 行 → 保留行,值改为指向真相位置。 真相存在、唯一、且由 pnpm 在安装期强制(根 engines)。表还剩三行真行,结构在,挂得住一个指针;删掉反而让读者失去一个我们确实知道答案的问题。
• 283 Compatibility 行 → 整行删。 这一行没有可指的真相位置 —— packages/cli/package.json 里没有这个依赖字段,指过去是指向空处。照 PR docs(packages): 退役 36 个包 README 里已死的 release-metadata §Compatibility 生成块 #3688 处理幽灵行的口径:删,不改写、不改指成「经由 @object-ui/* 间接依赖」(那会新增一条结构性声明,又是一个要维护的漂移面)。

表因此从 5 行变 4 行,每一行都是 packages/cli/package.json 里可逐字核对的事实。

前后对照

改前:

| **License** | MIT |
| **Node** | ≥ 18 |
| **Compatibility** | `@objectstack/spec` ^3.3.0 |

改后:

| **License** | MIT |
| **Node** | See the `engines` field in the repository's [root `package.json`](https://github.com/objectstack-ai/objectui/blob/main/package.json) |

措辞遵 #3656 规矩(不复植失真特征词),先量后改:

判据	修前	修后
grep -c '\^3\.3\.0' content/docs/utilities/cli.mdx	1	0 ✅
grep -c '≥ 18' content/docs/utilities/cli.mdx	1	0 ✅
grep -c 'rc\.5|>=22|>= 22|17\.0\.0' content/docs/utilities/cli.mdx(重新上膛检查)	0	0 ✅

反向验证:先定方向,再跑

新加的那条链接是 blob/main/ 自仓 URL,正好落在 check-doc-links.mjs §2 的可判定形状里(URL 里的那段路径必须存在于工作树)。预测:把路径改成不存在的,门禁必须变红并点名这一行 —— 只有红了,才证明修后的绿是真覆盖,而不是加了一条门禁根本不看的链接。

$ sed -i 's#blob/main/package\.json#blob/main/package.json.NOPE#' content/docs/utilities/cli.mdx
$ node scripts/check-doc-links.mjs
Found 1 broken link (1 distinct target):
- [self-repo-url] content/docs/utilities/cli.mdx:282 -> https://github.com/objectstack-ai/objectui/blob/main/package.json.NOPE
exit=1                      ← 与预测同向:红

还原后复跑 Links are valid across 7 scan roots. exit=0。链接形状本身在仓内已有先例(content/docs/utilities/runner.mdx:164 同款)。

门禁

门禁	修前	修后
node scripts/check-doc-links.mjs	Links are valid across 7 scan roots. exit=0	同上 exit=0(且经上面的反向验证证明确实读到了新链接)
node scripts/check-control-bytes.mjs	OK (scanned 3682 tracked text file(s); skipped 85 binary) exit=0	同上 exit=0
对改动文件自扫 [\x00-\x08\x0b\x0c\x0e-\x1f]	—	命中 0 行

本 PR 在 CI 上的预期:ci.yml 与 lint.yml 的 paths-ignore 都含 content/**,预期显示 skipping(按 AGENTS.md 那是跳过、不是失败);docs-links.yml 与 control-bytes.yml 无路径过滤,会真的跑 —— 这两条就是上表本地跑过的那两条。

无单测可加:仓内没有任何测试断言 content/docs 的正文内容(packages/cli/src/__tests__/cli-bin.test.ts:6 只在注释里提了本文件路径,不读它)。该面的强制力就是 check-doc-links,所以我用反向验证代替「新增测试」这一栏,据实记录,不编造。

changeset:不加(写明判断)

content/docs/** 只被 apps/site/source.config.ts:6 消费,不在任何包的 files 里(grep -rln '"content' packages/*/package.json 零命中)—— 它不是发布物,改它不产生任何用户可见的包变更。与 #3633 / #3646 / #3651 的站点文档先例一致。

围栏

• content/docs/guide/release-notes.md 一行未动。除 issue 已点名的 :41(Bump every ... to ^3.3.0,历史升级动作叙述)外,我另量到 :58 的 | Node.js | ≥ 18 | —— 它在 ## v3.3.0 — 2026-04-17 这个版本标题下的 ### Compatibility Matrix 里,是那一次发布当时的兼容矩阵,与 :41 同性质,同样不改。一并记下,免得后来者误伤。
• 顺带扫了全站:content/docs 里再无同款失真。ci-cd-pipeline.md:82 的 "Node 22.x" 我核过,与 14 处 workflow node-version: '22.x' 一致,是真的。
• 只此一页有这张表:content/docs/utilities/ 下另外 4 个 utilities 页面均无 "Package information" 表,无需同步。
• packages/**、任何 package.json 均未触碰。暂存区文件数 1。

越界发现

• 已另立 观察记录:文档散文里的版本宣称无门禁可守 —— #3688 + #3689 把它清到零之后,没有任何东西阻止下一个作者写回去 #3697(观察类,finding,不入 pm:queue,未指派):文档散文里的版本宣称无门禁可守 —— 本 PR 与 PR docs(packages): 退役 36 个包 README 里已死的 release-metadata §Compatibility 生成块 #3688 把这一族清到零,但没有任何门禁守得住这个零。与 观察记录:release-metadata 发布期生成器已死(两仓零引用),PR #3688 删掉最后痕迹后该机制在全仓归零 —— 若重建须取真值而非入散文 #3692 相邻但不同:观察记录:release-metadata 发布期生成器已死(两仓零引用),PR #3688 删掉最后痕迹后该机制在全仓归零 —— 若重建须取真值而非入散文 #3692 记的是「生成器已死、若重建须取真值」(约束一个不存在的生成器),观察记录:文档散文里的版本宣称无门禁可守 —— #3688 + #3689 把它清到零之后,没有任何东西阻止下一个作者写回去 #3697 记的是「今天没有任何东西阻止下一次手写把版本号重新写进文档散文」(约束日常编辑)。观察记录:文档散文里的版本宣称无门禁可守 —— #3688 + #3689 把它清到零之后,没有任何东西阻止下一个作者写回去 #3697 里也写明了它不是一行 grep 就能做的原因:门禁必须放过 release-notes.md 那种版本标题下的历史叙述。
• 本 PR 未做任何越界修改;上述发现只记录、不顺手修。

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01GTRjn8xBqp75dk7kFupVRt

---

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)
objectui	Ignored		Aug 7, 2026 9:56pm