`@objectstack/client` 的 `packages.*` 与 `datasources.external.*` 无法跟随非默认 API base:external 面硬编码 `/api/v1`,rest 面 discovery 也从不通告 `routes.packages`

[os-project-manager]

out-of-scope 发现,来自 #6306 的 dispatch gate-1(SDK 配对验证)。按 Prime Directive #10 单独立单,未认领。

事实(全部实测,origin/main = e39dd66e7 时点)

1. datasources.external.* 五个方法硬编码 /api/v1,没有任何 discovery 机制。
   packages/client/src/index.ts ~:1065-1113,五处均为
   `${this.baseUrl}/api/v1/datasources/${...}/external/...` 的模板字符串。即使 discovery 通告了别的 base,它们也不读。

2. packages.* 走 getRoute('packages'):优先 discoveryInfo.routes.packages,fallback 硬编码 /api/v1/packages(packages/client/src/index.ts ~:4743-4783 的 routeMap)。机制存在,但——

3. rest 面(@objectstack/rest)的 discovery 从不通告 routes.packages。
   packages/metadata-protocol/src/protocol.ts :2768-2798:serviceToRouteKey 没有 packages 项,routes 字面量只有 data/metadata + optionalRoutes;
   packages/rest/src/rest-server.ts registerDiscoveryEndpoints(:3198-3251)只 override data/metadata/ui/mcp/auth。
   所以对 rest 面部署,SDK 的 packages.* 实际永远落到硬编码 fallback。route 已 mount 而 discovery 不通告,是 ADR-0076 D12「advertise everything mounted」的另一半缺失(D12 文字禁止的是通告未挂载;这里是挂载了不通告,后果是 SDK 被钉死在 convention 上)。

4. 探针输出(mock fetch 驱动真实 ObjectStackClient,baseUrl=https://host.example):

   • 未 connect(纯 convention):packages.list → /api/v1/packages;external.listTables → /api/v1/datasources/pg_main/external/tables
   • 已 connect,discovery 按 rest 面实际内容(routes 只有 data/metadata/ui,均已 rebase 到 /backend/api/v9,无 packages 键):两者 URL 不变,仍 /api/v1/...
   • 反事实:discovery 若通告 routes.packages: '/backend/api/v9/packages',packages.list 会跟随(→ /backend/api/v9/packages),但 external.listTables 仍 /api/v1/...

后果

任何非默认 base 的部署(设置 apiPath,或程序化改 basePath/version),SDK 这两个面都打错前缀。并且 #6306 的 maintainer ruling(Option 1:9 条 direct-mount 跟随 apiPath)一旦按现 scope 落地,这两个面在设置 apiPath 的部署上会从「碰巧能用」(双方共享同一个硬编码)变成 404 —— 这正是 #6306 dispatch 的 gate-1 stop 条件,该卡已停工上报,等待重新裁定顺序。

方向(留给分诊,不预设)

a. rest 面 discovery 通告 routes.packages(mounted ⇒ advertised),SDK packages.* 即可跟随;
b. client 的 datasources.external.* 改为从 discovery/可配置 base 派生(词表可能需要新增 datasources 路由键 —— spec 变更,需单独裁定);
c. 与 #6306 的落地顺序编排(先 a+b 后移路由,或同 release 内成组落地)。

查重

open issues 已搜 apiPath / datasources external SDK / routes.packages discovery / client hardcode route,无同题。相关:#6306(现场)、#5822 / PR #6303(枚举面)。

[os-project-manager]

维护者裁定 + 分诊(2026-08-08,cli 席):路线 B 的前置卡,转可派。Blocks: #6306。

• 裁定:配置了 api.apiPath 时,rest 的 9 条 direct-mount 路由挂在 {basePath}/{version} 而不是 {apiPath} #6306 停机闸触发后,维护者选 B(先补本卡,再移 9 条路由)。本卡实施方向 a + b + c 全取:rest 面 discovery 通告 routes.packages(mounted ⇒ advertised,即 ADR-0076 D12 缺的另一半)+ client 的 datasources.external.* 从 discovery 派生 base;使能件 spec ApiRoutes 路由键与 protocol serviceToRouteKey 映射均在维护者批准范围内。
• 标签:pm:queue + domain:cli + target:v17(承继 配置了 api.apiPath 时,rest 的 9 条 direct-mount 路由挂在 {basePath}/{version} 而不是 {apiPath} #6306 的 release 排期;落标为维护者裁定的代执行)。
• 跨席:spec-surface 席([PM seat] domain:spec-surface — 🟢 os-project-manager #6298 评论 5225247046)与 metadata 席([PM seat] domain:metadata — 🟢 os-zhuang #6367 评论 5225247338)已发预派发声明,否决窗口开放;两席均在任。
• 关键设计约束(验收线):通告必须与挂载同源派生 —— 一条「advertised == mounted」的端到端奇偶钉,使未来任何只动一侧的改动(包括 配置了 api.apiPath 时,rest 的 9 条 direct-mount 路由挂在 {basePath}/{version} 而不是 {apiPath} #6306 的移路由)必红。

---

Generated by Claude Code

[os-project-manager]

CLAIM — session session_017uFVNMmTxLpmfQYiuKM1Yx, branch claude/issue-6633-sdk-follows-discovered-base.

按 2026-08-08 维护者裁定(路线 B,见上评)实施:spec ApiRoutes 新增 packages/datasources 路由键 → protocol serviceToRouteKey 映射 → rest 面 discovery 同源通告(advertised == mounted 奇偶钉)→ client datasources.external.* 从 discovery 派生 base。四阶段各一 commit。跨席预派发声明(#6298 c5225247046 / #6367 c5225247338)否决窗口已确认开放,开工前后将复读本单评论。

---

Generated by Claude Code