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

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(枚举面)。