@acosmi/sdk-ts 2.2.0 → 2.3.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to `@acosmi/sdk-ts` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.3.0] - 2026-05-30 — `apiBaseURL` 可配置网关 base（additive，零回归）
+
+Additive minor。新增一个可选 client 配置项，让浏览器侧 `/api/v4` 网关调用（managed-model / agent-run / **casehall**）可经**同源代理**转发，规避非网关同源域名（如 `sign.zhonglvbao.com`）下 acosmi.com 对带 `Origin` 跨域浏览器请求的 403。
+
+### Added
+
+- **`ClientConfig.apiBaseURL?: string`** — `/api/v4` 网关调用的 base 覆盖。未配置时 `apiURL()` 仍用 `serverURL`（**既有行为逐字节不变**，全部既有消费方 tk-dist-web / acosmi-web / CrabCode / 桌面不受影响）。与 `complianceBaseURL` 同构（compliance 走 `/admin-api`，本字段走 `/api/v4`），尾随 `/` 自动 trim，`apiURL()` 仍按需追加 `/api/v4` 不重复。
+
+### 用法（浏览器经同源代理接 casehall，规避跨域 403）
+
+1. 部署域名 nginx 加 `location /api/v4/ { proxy_pass https://acosmi.com/api/v4/; proxy_set_header Host acosmi.com; proxy_set_header Origin ""; proxy_set_header Authorization $http_authorization; }`（**仅 `/api/v4/`，不要用 `/api/`**——否则会劫持应用自身的 `/api/*` Route Handler）。
+2. **浏览器端** client 配 `apiBaseURL: window.location.origin`。同源 GET 无 `Origin` 头 → nginx 服务端转发 acosmi.com → 不触跨域 403。
+3. **服务端**（Route Handler）client **不设**本字段，直连 `serverURL`（服务端到 acosmi.com 无跨域）。
+
+从 v2.2.x 升级无需任何 review：不传 `apiBaseURL` 即维持原状。
+
+## [2.2.1] - 2026-05-29 — README 字段名修正（docs-only patch）
+
+纯文档修正，无源码 / 类型 / 方法签名改动。修复 v2.2.0 README「图片/视频生成」示例中把能力字段误写为 camelCase（`supportsImageGeneration`）的问题——`ModelCapabilities` 是 wire snake_case 对象，正确字段为 `capabilities.supports_image_generation` / `supports_video_generation`（`listModels` 对 `capabilities` 对象原样透传，不归一化）。补充说明：这两个字段随 catalog 下发、为可选（缺省按 false）、且**无专用 catalog helper**（需直接读字段筛模型）。从 v2.2.0 升级无需任何 review。
+
 ## [2.2.0] - 2026-05-29 — 托管模型图片/视频生成
 
 Additive minor。公开类型 / 方法签名零移除、零改名。图片/视频生成与文本模型同属托管模型网关（同 `Client`、同 `models:chat` 鉴权面），仅 `capabilities.supports_image_generation` / `supports_video_generation` 的模型可用。计费结算在营销系统，SDK / 网关只负责调用与用量上报。

package/README.md

@@ -122,10 +122,12 @@ if (err) {
 
 ```ts
 const models = await client.listModels();
-const imageModel = models.find((m) => m.capabilities?.supportsImageGeneration);
-const videoModel = models.find((m) => m.capabilities?.supportsVideoGeneration);
+const imageModel = models.find((m) => m.capabilities?.supports_image_generation);
+const videoModel = models.find((m) => m.capabilities?.supports_video_generation);
 ```
 
+> 这两个能力字段随 catalog 下发：`capabilities` 是 `ManagedModel` 的必填字段，`listModels` 对 `capabilities` 对象**原样透传**（保持 wire snake_case，不归一化为 camelCase）。字段为可选——上游未声明时为 `undefined`（按 false 处理），**严禁用模型名 substring 推断**。注意目前**没有**图片/视频生成的专用 catalog helper（不像 `inputModalities` 那条线有 `modelSupportsImageInput` 等），按上面直接读字段筛即可。
+
 ### 图片生成（同步）
 
 `generateImage` 一次调用直接拿图（内部超时与 chat 同级 11min，容纳上游耗时；DashScope 万相图片在网关内部建任务并轮询到终态后同步返回，对 SDK 仍是一次调用）。
@@ -433,7 +435,7 @@ const client = new Client({ serverURL: process.env.ACOSMI_SERVER_URL!, store: ne
 | ------------ | ------------------------------------------------------------------------------------ |
 | **Client 构造** | `new Client(cfg)`（同步），`Client.create(cfg)`（async；预加载已有 TokenStore）            |
 | **Chat**     | `chat`, `chatStream`, `chatStreamWithUsage`, `chatMessages`, `chatMessagesStream`, `buildChatRequest` |
-| **图片 / 视频生成**（v2.2.0+） | `generateImage`（同步）, `generateVideo`（建异步任务）, `pollVideoTask`（轮询）；仅 `capabilities.supportsImageGeneration` / `supportsVideoGeneration` 模型可用 |
+| **图片 / 视频生成**（v2.2.0+） | `generateImage`（同步）, `generateVideo`（建异步任务）, `pollVideoTask`（轮询）；仅 `capabilities.supports_image_generation` / `supports_video_generation` 模型可用 |
 | **Agent Runs** | `agentRuns.create`, `agentRuns.stream`, `agentRuns.run`, `agentRuns.cancel`, `agentRuns.get`, `agentRuns.listArtifacts`, `agentRuns.downloadArtifact`, `agentRuns.submitLocalToolResult`, `agentRuns.runWithLocalTools` |
 | **Agent Runs — 远程控制**（v2.1） | `agentRuns.createRemoteRun`, `agentRuns.streamRemoteControl`；helper：`parseRemoteControlEvent`, `isTerminalRemoteEvent`；scope：`remoteControlScopes()` / `ScopeRemoteControl`（不进 `allScopes()`） |
 | **Chat Bridge**（v2.1 · types-only） | 无 client 方法（Phase 7B 后端落地）；导出类型守卫 `isPlatform`, `isRegion`, `isIntegrationStatus`, `isChannelInboundEvent`, `asCredentialRef` |
@@ -918,7 +920,8 @@ npm run docs    # 经 TypeDoc 生成 API 参考到 docs/api/
 
 | 版本 | 状态 | 概要 |
 | --- | --- | --- |
-| 2.2.0 | **当前稳定版（npm latest）** | **托管模型图片/视频生成（2026-05-29）**。图片/视频生成与文本模型同属托管模型网关（同 `Client`、同 `models:chat` 鉴权面），仅 `capabilities.supports_image_generation` / `supports_video_generation` 的模型可用；计费结算在营销系统，SDK / 网关只负责调用与用量上报。新增 `client.generateImage(modelID, req, signal?)`（同步，`POST /managed-models/:id/images/generations`）/ `client.generateVideo(modelID, req, signal?)`（建异步任务，返回 `taskId`）/ `client.pollVideoTask(modelID, taskID, durationSeconds?, signal?)`（轮询，`durationSeconds` 透传给网关在 `completed` 时上报视频秒数）；新增 `ImageGenerationRequest`/`ImageGenerationResponse`/`VideoGenerationRequest`/`VideoTaskResponse` 类型 + `ModelCapabilities.supportsImageGeneration`/`supportsVideoGeneration` 标志。网关适配 OpenAI 兼容图片 + 火山引擎（即梦/豆包）视频 + DashScope 通义万相（wanx）原生异步任务（图片+视频）。公开类型 / 方法签名零移除、零改名（additive minor）。 |
+| 2.2.1 | **当前稳定版（npm latest）** | **README 字段名修正（docs-only patch，2026-05-29）**。修复 v2.2.0 README 示例把能力字段误写为 camelCase（`supportsImageGeneration`）；正确为 wire snake_case `capabilities.supports_image_generation` / `supports_video_generation`（`listModels` 对 `capabilities` 对象原样透传）。补充：字段随 catalog 下发、可选（缺省 false）、无专用 catalog helper。无源码改动，从 2.2.0 升级无需 review。 |
+| 2.2.0 | 稳定版 | **托管模型图片/视频生成（2026-05-29）**。图片/视频生成与文本模型同属托管模型网关（同 `Client`、同 `models:chat` 鉴权面），仅 `capabilities.supports_image_generation` / `supports_video_generation` 的模型可用；计费结算在营销系统，SDK / 网关只负责调用与用量上报。新增 `client.generateImage(modelID, req, signal?)`（同步，`POST /managed-models/:id/images/generations`）/ `client.generateVideo(modelID, req, signal?)`（建异步任务，返回 `taskId`）/ `client.pollVideoTask(modelID, taskID, durationSeconds?, signal?)`（轮询，`durationSeconds` 透传给网关在 `completed` 时上报视频秒数）；新增 `ImageGenerationRequest`/`ImageGenerationResponse`/`VideoGenerationRequest`/`VideoTaskResponse` 类型 + `ModelCapabilities.supports_image_generation`/`supports_video_generation` 标志（wire snake_case，`capabilities` 对象透传不归一化）。网关适配 OpenAI 兼容图片 + 火山引擎（即梦/豆包）视频 + DashScope 通义万相（wanx）原生异步任务（图片+视频）。公开类型 / 方法签名零移除、零改名（additive minor）。 |
 | 2.1.0 | 稳定版 | **远程控制 CrabCode 多接入面（2026-05-28）**。`serverURL`/`baseURL`/`baseUrl` Gateway URL 公共契约 + `normalizeGatewayBaseURL`（仅 http/https，拒 ws/wss）；`agentRuns.createRemoteRun` / `streamRemoteControl` + 11 事件 `RemoteControlEvent` union + `parseRemoteControlEvent` / `isTerminalRemoteEvent`；`AdapterKind`(6) / `RunnerKind`(3) / `PermissionPolicy` / `WorkspacePolicy`；专用 `remote_control` scope（不进 `allScopes()`，`remoteControlScopes()`）；`chatbridge` 第三方聊天平台类型骨架（types-only，无 client 方法，Phase 7B 后端落地）；`subscription.getPlanByCode`。wire 约定按平面分（远控 snake_case + 毫秒整数 / chatbridge camelCase，契约 §12-§14）。公开类型 / 方法签名零移除、零改名（additive minor）。 |
 | 2.0.1 | 稳定版 | **Packaging fix — 纯发布元数据，无源码改动**。`package.json.files` 数组补 `docs/pii-role-matrix.md` + `docs/开发与发布手册.md` 两项，让 v2.0.0 引入的 PII 角色矩阵与开发手册随 npm tarball 一并下发。从 v2.0.0 升级到 v2.0.1 无需任何 review。 |
 | 2.0.0 | **BREAKING** | **Phase 3 复核 + 全量根治（2026-05-25）**。主仓 9 commit 闭环 20 P0（RBAC 表达式统一 / PII 真落盘加密链 / K7 视频 webhook 幂等 / K8 OCR SSRF / K9 KYC main flow / admin 写端点错误码契约）。**SDK 同步**：新增 `casehall.getMyLawyerCredentialStatus()` + `enterprise.getMyEnterpriseKycStatus()` 律师/企业 OWNER 自查端点；`finance/types.ts` P2-016 PII Javadoc 升级（含 `keyVersion` v1/v2 payload 协议）；新建 `docs/pii-role-matrix.md`（4 角色 × 3 PII 级矩阵）；admin 写端点错误码改 HTTP 状态码语义（`200+{ok:false}` → `403/404/501`）。**升级指引详见 §"v2.0.0 升级指引"**。SDK 公开类型 / 方法签名零移除、零改名；BREAKING 范围在网关后端契约。 |

package/dist/browser/index.mjs

@@ -2079,6 +2079,8 @@ var Client = class _Client {
   serverURL;
   /** Compliance API 根地址 (已 trim 尾随 /); null = 走默认 ${serverURL}/admin-api */
   complianceBaseURL;
+  /** `/api/v4` 网关调用 base 覆盖 (已 trim 尾随 /); null = 走默认 serverURL */
+  apiBaseURL;
   /** OAuth metadata profile — 刷新 token 时发现 metadata 用 (默认 'desktop') */
   oauthMetadataProfile;
   /** Browser Web OAuth refresh strategy (default 'direct') */
@@ -2120,6 +2122,7 @@ var Client = class _Client {
     const picked = pickAndNormalizeGatewayURL(cfg);
     this.serverURL = picked ?? DEFAULT_GATEWAY_BASE_URL;
     this.complianceBaseURL = cfg.complianceBaseURL ? cfg.complianceBaseURL.replace(/\/+$/, "") : null;
+    this.apiBaseURL = cfg.apiBaseURL ? cfg.apiBaseURL.replace(/\/+$/, "") : null;
     this.oauthMetadataProfile = cfg.oauthMetadataProfile ?? "desktop";
     this.browserRefreshMode = cfg.browserRefreshMode ?? "direct";
     this.refreshProxyURL = cfg.refreshProxyURL ?? null;
@@ -3046,7 +3049,7 @@ var Client = class _Client {
   // Internal HTTP
   // ===========================================================================
   apiURL(path) {
-    let base = this.serverURL;
+    let base = this.apiBaseURL ?? this.serverURL;
     if (!base.endsWith("/api/v4")) {
       base += "/api/v4";
     }