@acosmi/sdk-ts 2.2.1 → 2.4.0

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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.4.0] - 2026-05-30 — `SkillStoreItem.skillMd?` 透出（additive minor，零回归）
+
+Additive minor，纯类型，无方法签名 / 运行时改动。修复**下游经 SDK 拿不到技能 SKILL.md 正文**：网关 `SkillStoreResponse` 早已返回 `skillMd`（`json:"skillMd,omitempty"`，`ToStoreResponse()` 已 map），但 SDK 的 `SkillStoreItem` 类型未声明该字段，导致 `getSkillDetail` / `resolveSkill` / `browseSkills` 的消费方（CrabCode）在类型层访问不到正文。
+
+### Changed
+
+- **`SkillStoreItem` 新增可选 `skillMd?: string`** — Anthropic SKILL.md 正文。声明为可选以匹配网关 `omitempty`（空时字段缺省）。仅全量响应（Detail / resolve / 非 minimal browse）携带；`SkillStoreListItem`（`fields=minimal`）**不含**正文，刻意保持 90% 瘦身不变。
+- **`SkillStoreItem.readme` 改为可选 `readme?: string`** — 修正旧的轻微契约不符：网关该字段为 `json:"readme,omitempty"`，空时缺省。
+
+未触碰 `SkillStoreListItem`（minimal 刻意剥正文）。从 2.3.x 升级无需 review；消费 `skillMd` 时按可选处理（空表示该技能未提供 SKILL.md 正文，可回退 `readme`）。
+
+> 下游 CrabCode 生效需重锁 `@acosmi/sdk-ts@2.4.0` + `bun install --force`。SKILL.md 为用户发布的不可信内容，GUI 渲染须 sanitize（禁原始 HTML 注入）并同屏展示 `securityLevel` / `securityScore` / `certificationStatus`。
+
+## [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。

package/README.md

@@ -920,7 +920,9 @@ npm run docs    # 经 TypeDoc 生成 API 参考到 docs/api/
 
 | 版本 | 状态 | 概要 |
 | --- | --- | --- |
-| 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.4.0 | **当前稳定版（npm latest）** | **`SkillStoreItem.skillMd?` 透出（additive minor，2026-05-30）**。修复下游经 SDK 拿不到技能 SKILL.md 正文：网关 `SkillStoreResponse` 早已返回 `skillMd`（`ToStoreResponse()` 已 map），但 SDK `SkillStoreItem` 漏声明。新增可选 `skillMd?: string`（Anthropic SKILL.md 正文，仅 Detail/resolve/非 minimal browse 携带；`SkillStoreListItem` minimal 刻意不含正文）；`readme` 一并改为可选 `readme?`（匹配网关 `omitempty`）。零方法签名/运行时改动。下游 CrabCode 重锁 `@acosmi/sdk-ts@2.4.0` + `bun install --force` 生效；SKILL.md 为不可信用户内容，GUI 渲染须 sanitize + 展示 securityLevel/securityScore/certificationStatus。 |
+| 2.3.0 | 稳定版 | **`apiBaseURL` 可配置网关 base（additive，2026-05-30）**。新增可选 client 配置项，让浏览器侧 `/api/v4` 网关调用（managed-model / agent-run / casehall）可经同源代理转发，规避非网关同源域名（如 `sign.zhonglvbao.com`）下 acosmi.com 对带 `Origin` 跨域浏览器请求的 403。公开类型 / 方法签名零移除、零改名（additive minor）。 |
+| 2.2.1 | 稳定版 | **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。 |

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";
     }