content/docs/protocol/kernel/runtime-capabilities.mdx 通篇描述已于 #3605 删除的 ObjectStackCapabilities —— 整页教一个不存在的 schema

[os-zhuang]

#4634(DriverCapabilities 活性审计)扫描 hand-written docs 时发现,顺带记录,不在该 PR 范围内修。

现象

content/docs/protocol/kernel/runtime-capabilities.mdx(hand-written 区)整页教读者使用 ObjectStackCapabilities(data / ui / system 三子系统能力描述符),包括两个完整的 const capabilities: ObjectStackCapabilities = {...} 示例和 hasCapability() 用法。

但该 schema 已不存在:

• packages/spec/src/kernel/index.ts:19 注释明言 ObjectStackCapabilities.system.features 描述符「was itself removed as dead (feat(spec)!: remove the dead static capabilities-descriptor cluster #3605)」;
• 全仓 grep ObjectStackCapabilities 只剩注释引用(kernel/index.ts、stack.zod.ts:255),api-surface.json 无此导出;
• 页内表格的键(queryDistinct、queryHaving、queryJoins、geoSpatial……)与任何现存 schema 都对不上——它们既不是 DriverCapabilities 的键,也不是别处的。

import type { ObjectStackCapabilities } from '@objectstack/spec' 是 TS2305,照抄示例的读者(尤其 AI)会在第一行编译失败;更糟的是页面声称「AI Agents: Understanding platform constraints for code generation」——教 AI 用一个不存在的能力协商面。

建议处置

二选一,按 docs-accuracy 流程定:

1. 删页(倾向):运行时能力发现的活机制是 REST /api/v1/discovery(页尾那节反而是准的)+ 驱动侧 DriverCapabilities 三个活位(DriverCapabilities.streaming 在 findStream 退休后指向不存在的能力，且从来没有读者（ADR-0049，#4484 收尾发现） #4634 后)。把 discovery 节并入 API 文档,其余删除。
2. 重写为 discovery 文档,删除三子系统描述符的全部内容。

meta.json 同步更新。可参考 docs-accuracy-audit 技能的流程。

发现于 #4634 审计,未认领——谁开工谁按 AGENTS.md 认领。

[xuyushun441-sys]

认领:PM 循环第 6 轮
会话:session_018iARDqtrhQgz6fVHDeDkbQ
分支:claude/issue-4781-retire-runtime-capabilities-page
Worktree:objectstack-issue-4781

车道:落点 content/docs/**,属本会话车道(维护者裁定,登记 #4604)。

发版前处理的理由:文档随版本一起发布。这一页不是「有点旧」,是整页教一个已删除的 schema —— 照抄第一行 import type { ObjectStackCapabilities } from '@objectstack/spec' 就是 TS2305。而页面自己声称受众包含「AI Agents: Understanding platform constraints for code generation」:我们正在把一个不存在的能力协商面教给 AI。发版把它一起发出去,等于把这个错误固化成「官方文档这么说的」。

处置取方案 1(删页),与 issue 作者的倾向一致。理由:运行时能力发现的活机制是 REST /api/v1/discovery(页尾那节反而是准的)加驱动侧的 DriverCapabilities(#4634 之后);把准确的那节并入 API 文档、其余删除,比重写一页去描述一个不存在的三子系统描述符更诚实。这属 PM 可自决范围(不改公开契约形状、不涉及存储迁移)。

派发时会一并要求:meta.json 同步、全仓搜残留链接(删页最常见的后遗症是别处还链着它)、并核实页尾 discovery 那节在并入前确实与当前 REST 实现一致(不要把一段同样过期的内容搬去 API 文档 —— 那只是把错误换个地方放)。

---

Generated by Claude Code

[xuyushun441-sys]

PM 复核:通过(ACCEPT),等 CI 全绿后进合并队列

PR:#4816(草稿,base main,body 首行 Fixes objectstack-ai/objectstack#4781,6 个文件,未触碰 content/docs/releases/)

派发时那道防线起作用了 —— 页尾那节也是过期的

我派发时明确要求:issue 说页尾 discovery 节「反而是准的」,不许照单全收,并入 API 文档前必须对着当前 REST 实现核实。dev 照做了,结论是它同样过期,因此没有搬:

• getDiscovery() 返回 { version, apiName, routes, services, capabilities },没有 name / environment / locale —— 那三个字段属于 dispatcher 提供的 /.well-known/objectstack;
• 样例里的 "graphql": "/graphql" —— ApiRoutesSchema 里根本没有 graphql 这个键;
• version 被 config.api.version 覆盖成 v1,不是样例写的 1.0.0。

我独立核了第二条:git grep graphql -- packages/spec/src/api/ 零命中,那份路由样例是编出来的。

如果照 issue 的字面说法搬运,就会把一段同样过期的内容原封不动挪进 API 文档 —— 只是把缺陷换个地方放,而这正是本 issue 自己描述的病。只搬了两条实际验证成立的事实(GET /api/v1 与 /api/v1/discovery 是同一个 handler 的两个路径、ADR-0076 D11 的 dispatcher 让路规则;以及 transactionalBatch 的 #3298 / ADR-0034 语义)。

其余验收

• 页面已删(536 行);meta.json 条目已移除,无悬空导航;
• 两处活的入站链接已改指(automation/index.mdx → HTTP API;kernel/index.mdx → 条目删除);grep 面覆盖 runtime-capabilities / slug / ObjectStackCapabilities / hasCapability,横跨 content/docs、skills、apps、docs、scripts、packages、.github、README —— 唯一残留是 docs/audits/2026-06-*.md 这份归档审计记录,用的是改名前的路径,保留原样是对的(改动史料没有意义);
• changeset 用空 frontmatter 形式(docs-only 不发任何包)。我核过先例 .changeset/adr-0104-design-doc-only.md 确在 main 上,是仓内认可的写法,不是临时发明。

一处越出 content/docs/** 的改动,我认可

scripts/role-word-baseline.json 删了一行。理由成立且 dev 主动报备:check-role-word.mjs 在被基线记录的文件消失时会报错并要求 ratchet down,不改这一行 CI 必红。它不属于任何其它 PM 的包路径(不是 packages/spec|objectql|metadata*|plugins|services|runtime|cli|rest),dev 对那些包只读未写。删页必然连带基线,属于「不做就红」的必要改动,不是范围蔓延。

衍生

• content/docs/protocol/kernel/http-protocol.mdx 的 discovery 响应示例把 dispatcher 形状挂在 /api/v1/discovery 名下 —— 字段与 REST 实际返回体对不上 #4817 —— content/docs/protocol/kernel/http-protocol.mdx 把 dispatcher 的响应样例(带 name / version: "2.1.0" / environment / locale)当成 /.well-known/objectstack 与 /api/v1/discovery 共用的响应体,而 REST 挂载时后者根本不是这个形状。与本 issue 同一类缺陷,隔壁一页,已独立立单。
• 同单内还记了一条:.claude/workflows/docs-accuracy-audit.js 的 ALL_HANDWRITTEN 列表仍用改名前的 content/docs/protocol/objectos/* 路径,11 条全部指向不存在的文件,于是内部审计脚本静默跳过整个 protocol/kernel 目录 —— 这解释了为什么这一页能烂到今天没被发现。

---

Generated by Claude Code

[xuyushun441-sys]

结案:PR #4816 已合入 main,issue 由 Fixes 自动关闭

取方案 1(删页)。content/docs/protocol/kernel/runtime-capabilities.mdx(536 行)已删除 —— 它整页教 ObjectStackCapabilities,一个在 #3605 就被删掉的 schema,两个完整示例加一个 hasCapability() 辅助函数,照抄第一行就是 TS2305。而这一页自称受众包含「AI Agents: Understanding platform constraints for code generation」。发版会把文档一起发出去,这一条赶在切版前清掉了。

派发时设的那道防线,拦住了本该拦的东西

issue 说页尾的 discovery 节「反而是准的」。我要求不许照单全收,并入 API 文档前对着当前 REST 实现核实 —— 核出来的结论是它同样过期,因此没有搬:

• getDiscovery() 不返回 name / environment / locale(那三个属于 dispatcher 的 /.well-known/objectstack);
• version 被 config.api.version 覆盖成 v1,不是样例写的 1.0.0;
• 样例里的 "graphql": "/graphql" —— ApiRoutesSchema 里根本没有这个键。我独立 grep 过 packages/spec/src/api/,零命中。

照字面搬运的话,就会把一段同样过期的内容原封不动挪进 API 文档 —— 只是把缺陷换个地方放,而这正是本 issue 描述的病。最后只并入两条实测成立的事实:GET /api/v1 与 /api/v1/discovery 是同一个 handler 的两个路径(ADR-0076 D11 的 dispatcher 让路规则),以及 transactionalBatch 的 #3298 / ADR-0034 语义。

收尾

meta.json 已同步无悬空导航;两处活的入站链接已改指;grep 面覆盖 runtime-capabilities / slug / ObjectStackCapabilities / hasCapability,横跨 content/docs、skills、apps、docs、scripts、packages、.github、README —— 唯一残留是一份归档审计记录用改名前的路径,保留原样(改动史料没有意义)。scripts/role-word-baseline.json 连带 ratchet 一行:check-role-word.mjs 在被基线记录的文件消失时会报错,不改必红,属「不做就红」的必要改动。

衍生:#4817(同类缺陷,隔壁一页)

content/docs/protocol/kernel/http-protocol.mdx 把 dispatcher 的响应样例(带 name / version: "2.1.0" / environment / locale)当成 /.well-known/objectstack 与 /api/v1/discovery 共用的响应体,而 REST 挂载时后者根本不是这个形状。与本 issue 同一类缺陷,本会话车道内,即将派发 —— 而且现在有了现成范本:本 PR 改好的 content/docs/api/index.mdx 已经把这两个端点的区别写对了。

同单还记了一条解释性的发现:.claude/workflows/docs-accuracy-audit.js 的 ALL_HANDWRITTEN 列表仍用改名前的 content/docs/protocol/objectos/* 路径,11 条全部指向不存在的文件,于是内部文档审计脚本静默跳过整个 protocol/kernel 目录。这解释了为什么这一页能烂到今天 —— 不是没人查,是查它的脚本以为那个目录不存在。又一条「闸门看起来在跑、实际什么都没查」。

---

Generated by Claude Code