配置了 `api.apiPath` 时,rest 的 9 条 direct-mount 路由挂在 `{basePath}/{version}` 而不是 `{apiPath}`

[qq9340100]

out-of-scope 发现,来自 #5822(PR #6303)的实现过程,按 Prime Directive #10 单独立单。未认领。

事实

RestServer 用 getApiBasePath() 决定自己所有路由的前缀:

• packages/rest/src/rest-server.ts — return api.apiPath ?? ${''}${'$'}{api.basePath}/${'$'}{api.version}${''};

而 rest-api-plugin.ts 给两个 direct-mount registrar 算的 base 不读 apiPath:

• packages/rest/src/rest-api-plugin.ts — const basePath = config.api?.api?.basePath || '/api'; const version = config.api?.api?.version || 'v1'; const versionedBase = ${''}${'$'}{basePath}/${'$'}{version}${''};

apiPath 是 spec 里可声明的公开配置键(packages/spec/src/api/rest-server.zod.ts:
"Full API path (defaults to {basePath}/{version})",并已进 content/docs/references/api/rest-server.mdx)。

后果

部署一旦设置 api.apiPath(例如 /backend/api/v9):

• CRUD / metadata / reports / … 等全部 route-manager 路由挂在 /backend/api/v9/...;
• 而 packages.*(4 条)与 datasources/:name/external/*(5 条)仍然挂在 /api/v1/...。

即 SDK 的 packages.list / packages.get / packages.uninstall /
datasources.external.* 在该部署上打到 {apiPath}/packages 会 404,真正服务它们的是另一个前缀。
默认配置(不设 apiPath)两者相等,所以今天的 example / showcase 都撞不到 —— 仓库里没有任何
example 设置过 apiPath。

与 #5822 的关系(不是它引入的,但被它照出来)

#5822(PR #6303)让这 9 条对 RestServer.getRoutes() 可枚举。枚举面因此如实显示它们挂在
/api/v1/...;而 {apiPath} 那份 /openapi.json 会按 isUnderBase 把它们过滤掉 ——
文档没有说谎(它们确实不在那个 base 下),但这正好把前缀不一致变成可见现象。PR #6303
刻意没有顺手改前缀:改它会移动 9 条路由的线上 URL,属于独立的、需要评审的行为变更。

复现

defineStack({ /* … */ server: { api: { apiPath: '/backend/api/v9' } } })
// GET /backend/api/v9/data/:object  → 200(route-manager 路由跟随 apiPath)
// GET /backend/api/v9/packages      → 404
// GET /api/v1/packages              → 200(direct-mount 路由没跟随)

可能的处置(留给分诊,不预设)

1. 让 rest-api-plugin.ts 用与 RestServer.getApiBasePath() 同一个表达式(或直接把这个
   base 从 RestServer 暴露出来,单一真相源),9 条跟随 apiPath —— 行为变更:设置了
   apiPath 的部署上这 9 条 URL 会移动;
2. 或者裁定 apiPath 只管 route-manager 面,并把这个边界写进 apiPath 的 .describe() 与文档
   —— 但那等于承认一个部署里有两个 API 前缀;
3. 或者退役 apiPath(ADR-0049 enforce-or-remove 的形状:一个声明了却只被一半路由遵守的键)。

查重

origin/main 与 open issue 各搜过 apiPath / direct-mount / basePath 前缀,无同题单;
#5822 是发现现场(处置面不同,PR #6303 已写明为何不在其中修)。

[claude]

Triage: needs-user-decision + domain:cli + target:v17.

Both sides of the divergence verified on origin/main:

• packages/rest/src/rest-server.ts:2951 — ```js
  return api.apiPath ?? ${api.basePath}/${api.version}; // getApiBasePath()

  `apiPath` is threaded through at `:1484` / `:2890`.
- `packages/rest/src/rest-api-plugin.ts:379` — ```js
  const versionedBase = `${basePath}/${version}`;

consumed at :389, :393, :395 (packages routes) and :414 (external-datasource routes). apiPath appears nowhere in this file.

So the two prefixes are computed from different expressions, and they coincide only while apiPath is unset. Repro in the body is sound.

Why the decision inbox, not the queue. All three dispositions the body lists are contract answers, and the cheapest-looking one is a behaviour change:

1. Single-source the base ⇒ 9 route URLs move on any deployment that sets apiPath. That is a breaking change to live URLs, not a bug fix.
2. Rule that apiPath governs the route-manager surface only ⇒ formally blesses two API prefixes in one deployment, and the boundary has to be written into the key's .describe() and the reference docs.
3. Retire apiPath under ADR-0049 ⇒ removes a shipped, documented, declarable spec key.

Nothing in the code answers which one is right; this is appetite and compatibility, which is the maintainer's call (step 8), not the routing question (which is settled below and was never escalated).

Domain: packages/rest sits in the domain:cli package family, and the fix — under any of the three answers — lands in packages/rest/src/rest-api-plugin.ts and/or packages/spec's rest-server.zod.ts describe text. Labelled to the primary landing site; if the answer is (3), the spec-side removal transfers to domain:spec under "shared contract surfaces have one owner".

Release board (target:v17): criterion ② — apiPath is a declarable, documented public config key (packages/spec/src/api/rest-server.zod.ts, published to content/docs/references/api/rest-server.mdx) that is honoured by only part of the server. A key that half the routes obey is a schema that lies. Flagged so the release list shows it needs adjudication before GA rather than surfacing as a support case. It is on the board pending a decision, not pending a fix — the needs-user-decision label remains the operative state.

Not stale, and not #5822's doing. rest-api-plugin.ts has taken no change since 1363084; the divergence predates PR #6303, which deliberately left the prefix alone (moving 9 live URLs is not a rider). #6303 only made the inconsistency visible by enumerating the routes.

Dedup: all 463 open issues and PRs paginated. No duplicate. Neighbours: #5822 / PR #6303 (the discovery site, different disposition surface, explicitly documented as out of scope there) and #5969 (components.schemas unreferenced in the served OpenAPI — same document, different defect).

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[os-project-manager]

Maintainer ruling — 2026-08-07. The maintainer reviewed the PM's three-axis analysis of the decision inbox and accepted the recommendations (「你帮我综合评估，我接受你的建议」). Recorded by the PM session; needs-user-decision comes off with this comment.

Decision: Option 1 — single source of truth for the API base. Expose the base computation from RestServer.getApiBasePath() (or an equivalent shared helper) and make rest-api-plugin.ts consume it, so all 9 direct-mount routes (packages.*, datasources/:name/external/*) follow apiPath.

Rationale: default deployments are unchanged (apiPath unset ⇒ identical prefixes); the only behavior change lands on deployments that set apiPath — exactly the ones currently split-brained, and fixing them is the point. Option 2 (documenting two prefixes per deployment) is a standing trap for every future author; Option 3 (retiring apiPath) pays a removal ceremony for a legitimately useful reverse-proxy key.

Acceptance: with apiPath set, the repro in the body flips — {apiPath}/packages answers 200 and the old /api/v1/packages no longer double-serves; /openapi.json under {apiPath} lists all 9.

---

Generated by Claude Code

[os-project-manager]

认领 — dev agent 开始实现。

• Session ID: session_017uFVNMmTxLpmfQYiuKM1Yx
• Branch: claude/issue-6306-direct-mount-follows-apipath
• 依据 2026-08-07 maintainer ruling(Option 1,单一真相源):direct-mount registrar 复用 RestServer.getApiBasePath() 的同一 base 表达式,9 条路由跟随 apiPath。不做兼容双挂载。

---

Generated by Claude Code

[os-project-manager]

继续实现（同一会话的 re-dispatch,前一个 dev agent 在写码前因 API session-limit 中断）。

• Session ID: session_017uFVNMmTxLpmfQYiuKM1Yx（与上一条认领相同）
• Branch: claude/issue-6306-direct-mount-follows-apipath(复用已有 worktree)

---

Generated by Claude Code