Repository navigation
content/docs/protocol/kernel/runtime-capabilities.mdx 通篇描述已于 #3605 删除的 ObjectStackCapabilities —— 整页教一个不存在的 schema #4781
Description
#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 流程定:
- 删页(倾向):运行时能力发现的活机制是 REST
/api/v1/discovery(页尾那节反而是准的)+ 驱动侧DriverCapabilities三个活位(DriverCapabilities.streaming 在 findStream 退休后指向不存在的能力，且从来没有读者（ADR-0049，#4484 收尾发现） #4634 后)。把 discovery 节并入 API 文档,其余删除。 - 重写为 discovery 文档,删除三子系统描述符的全部内容。
meta.json 同步更新。可参考 docs-accuracy-audit 技能的流程。
发现于 #4634 审计,未认领——谁开工谁按 AGENTS.md 认领。
Activity
xuyushun441-sys commentedon Aug 3, 2026
认领:PM 循环第 6 轮
会话:
session_018iARDqtrhQgz6fVHDeDkbQ分支:
claude/issue-4781-retire-runtime-capabilities-pageWorktree:
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 commentedon Aug 3, 2026
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 语义)。其余验收
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/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把 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 commentedon Aug 3, 2026
结案: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
docs(protocol): retire runtime-capabilities page — it taught the remo…
fix(tooling): derive the docs-audit scope from the filesystem instead…