docs(protocol): http-protocol 的 API Discovery 拆成两段式 —— REST 形状与 dispatcher 形状分开 (#4817)

[xuyushun441-sys]

Fixes #4817

问题

content/docs/protocol/kernel/http-protocol.mdx 的 API Discovery 一节此前写着「/.well-known/objectstack 和版本化的 /api/v1/discovery 路由都直接返回 discovery 文档 —— 两者之间没有 HTTP 重定向」,随后给出一份响应示例。

那份示例其实是 dispatcher 的形状(name / environment / locale),却被标注成两条路径共同的返回体。在挂了 @objectstack/rest 的常规组合里,两条路径返回的不是同一形状。locale 更是读者会直接拿去初始化 i18n 的字段 —— 从 /api/v1/discovery 读它永远读不到。

改动

按 issue 的建议处置,改成与 content/docs/api/index.mdx(#4816 刚核实过)一致的两段式,用的是同一套措辞而不是第二种说法:

1. GET /api/v1(与 GET /api/v1/discovery) —— REST 形状:version / apiName / routes / services / capabilities,外加 rest-server 追加的 scoping。并明写三条易错点:version 是 api.version 覆盖后的路径段("v1",不是 2.1.0 这类语义版本);这里没有 name / environment / locale;scoping 由 REST 层追加。
2. GET /.well-known/objectstack —— dispatcher 形状:{ "data": ... } 包裹,含 name / environment / features / locale,并说明它没有 capabilities、routes 另有 endpoints 兼容别名。
3. 「两条路径同文档」被限定为 REST-less 组合才成立,并点名 ADR-0076 D11 单一 owner 规则(REST 挂上后 dispatcher 让出 ${prefix}/discovery);裸 /api/v1 只有 REST 会注册。

不再有混合示例。

每个字段的来源(逐一读过实现后写的)

示例字段	追溯到
version / apiName / routes / services / capabilities	ObjectStackProtocolImplementation.getDiscovery() 的 return(packages/metadata-protocol/src/protocol.ts)
version 被覆盖成 "v1"	registerDiscoveryEndpoints 里 discovery.version = this.config.api.version(packages/rest/src/rest-server.ts)
capabilities.transactionalBatch 的 description	同上,rest-server 里的字面量
scoping.{enabled,resolution,scoped,environmentId}	同上;默认值 false / 'auto' 取自 RestServerConfig 的 zod default
name: "ObjectOS" / version: "1.0.0" / environment / features / locale / endpoints	HttpDispatcher.getDiscoveryInfo() 的 return(packages/runtime/src/http-dispatcher.ts)
{ "data": ... } 包裹	res.json({ data: await dispatcher.getDiscoveryInfo(prefix) })(packages/runtime/src/dispatcher-plugin.ts)
services.*.message 文案	serviceUnavailableMessage() / REMEDY_DETAIL(packages/spec/src/system/core-services.zod.ts)
routes 的键集合	ApiRoutesSchema(packages/spec/src/api/discovery.zod.ts)

git grep graphql -- packages/spec/src/api/ 为空 —— 两份示例都没有 "graphql" 或任何无 schema/handler 支撑的字段。

验证

• node scripts/check-doc-authoring.mjs → 215 files clean
• node scripts/check-role-word.mjs → OK (43 baselined file(s), no new occurrences)
• pnpm --filter @objectstack/spec check:docs → 246 generated files in sync with packages/spec
• pnpm check:release-notes / pnpm check:nul-bytes → OK
• 单文件 MDX 编译通过(@mdx-js/mdx compile)

Docs-only,changeset 用空 frontmatter 形式(releases nothing),沿用 .changeset/retire-runtime-capabilities-doc-page.md 的先例。content/docs/releases/ 未触碰。

范围

只改这一节。issue 末尾「顺带」提到的 .claude/workflows/docs-accuracy-audit.js 路径失效(仍指向改名前的 protocol/objectos/*)按派发要求未并入,另行分诊。

🤖 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:54am