docs(protocol): 删除 runtime-capabilities 页 —— 整页教已于 #3605 删除的 ObjectStackCapabilities (#4781)

[xuyushun441-sys]

Fixes #4781

按 issue 作者与 PM 裁定的方案 1(删页)执行:删除 content/docs/protocol/kernel/runtime-capabilities.mdx,只把其中经核实确实准确的 discovery 内容并入 API 文档。

为什么删

该页从头到尾教 ObjectStackCapabilities(data / ui / system 三子系统描述符),含两个完整的 const capabilities: ObjectStackCapabilities = {...} 示例和一个 hasCapability() 辅助函数。这个 schema 已在 #3605 删除:

• import type { ObjectStackCapabilities } from '@objectstack/spec' 是 TS2305,照抄的读者第一行就编译失败;
• 页内表格的键(queryDistinct / queryHaving / queryJoins / geoSpatial ……)不属于任何现存 schema;
• 页面自己把「AI Agents: Understanding platform constraints for code generation」列为受众 —— 我们在把一个不存在的能力协商面教给代码生成器。

运行时能力发现的活机制是 REST discovery 端点 + 驱动侧 DriverCapabilities(#4634 之后)。

页尾那节 discovery,核实结果是「也不准」

Issue 说页尾 discovery 那节「反而是准的」。照实现核对后,不成立 —— 所以没有原样搬走,否则只是把缺陷换个地方放:

页面写的	实现是什么
GET /api/v1/discovery 返回体含 name / environment / locale	ObjectStackProtocolImplementation.getDiscovery()(packages/metadata-protocol/src/protocol.ts)返回 { version, apiName, routes, services, capabilities } —— 三个字段一个都没有。它们属于 dispatcher 服务的 /.well-known/objectstack(packages/runtime/src/http-dispatcher.ts 的 getDiscoveryInfo),而 content/docs/api/index.mdx 早已把这两者的差别写对了
routes 里有 "graphql": "/graphql"	ApiRoutesSchema(packages/spec/src/api/discovery.zod.ts)没有 graphql 键,serviceToRouteKey 也从不映射它 —— 纯属虚构
"version": "1.0.0"	REST 处理器用 config.api.version 覆盖(v1)
「response follows the DiscoverySchema」	REST 实际返回体缺 DiscoverySchema 的必填 name / environment / locale,并不满足该 schema

并入 API 文档的部分(逐条对实现核实过)

content/docs/api/index.mdx 的 ## Discovery 一节补两点,都是删页里唯一站得住、且 API 文档此前没有明说的事实:

1. GET /api/v1 与 GET /api/v1/discovery 是同一个 handler 注册在两个路径上(registerDiscoveryEndpoints,packages/rest/src/rest-server.ts)—— 不是重定向,也不是两种形状。REST 插件挂载时 dispatcher 会把 <basePath>/discovery 让给它(单一 owner,ADR-0076 D11),只有 REST-less 组合里 dispatcher 才是该路由的 fallback owner。
2. capabilities 映射与 transactionalBatch(discovery 广播「跨对象原子 batch」能力位(让客户端声明式协商,取代 404/405/501 运行时探测) #3298 / ADR-0034):当且仅当 POST {basePath}/batch 已挂载且引擎能承担事务时为 true(protocol 由 engine.transaction 推导,rest-server 再与 api.enableBatch 相与)—— declared === enforced,客户端可在 connect 时一次谈妥,不必用 404/405/501 探测。

删页后遗症清理

• content/docs/protocol/kernel/meta.json 移除导航项;
• 两处入链改指:content/docs/automation/index.mdx → HTTP API,content/docs/kernel/index.mdx → 移除该项;
• scripts/role-word-baseline.json 按棘轮下调(check-role-word 在被基线登记的文件消失时会报错,要求 ratchet DOWN)。

全仓搜过 runtime-capabilities、Runtime Capabilities、/docs/protocol/kernel/runtime-capabilities、ObjectStackCapabilities、hasCapability,覆盖 content/docs/**、skills/**、apps/**、docs/**、.github/**、README.md:零活链接残留。唯一命中是 docs/audits/2026-06-handwritten-docs-accuracy-followups.md 里的历史审计记录(用的还是重命名前的 protocol/objectos/ 路径),属存档记录,不动。

skills/objectstack-platform/SKILL.md 提到 ObjectStackCapabilities 一次,是准确的历史说明(说明 FeatureFlagSchema 及其协议归宿都已死、活的是 GET /api/v1/discovery),不是在教用法,保留。

门禁

$ pnpm --filter @objectstack/spec check:docs
✅ import examples resolve against api-surface.json (137 accepted gap(s) in the baseline)
✅ 246 generated files in sync with packages/spec

$ node scripts/check-role-word.mjs
check-role-word: OK (43 baselined file(s), no new occurrences).

$ node scripts/check-doc-authoring.mjs
✓ doc authoring guard: 215 files clean — no bare metadata literals.

纯文档改动,不发布任何包 —— 按仓库惯例给了空 frontmatter changeset(Check Changeset 要求每个 PR 都新增一个 changeset,空 frontmatter 是「本 PR 不发布」的官方写法)。

🤖 Generated with Claude Code

https://claude.ai/code/session_018iARDqtrhQgz6fVHDeDkbQ

---

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 8:27am