@acosmi/sdk-ts 2.9.0 → 2.11.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.11.0] - 2026-07-09 — 窗口限额 (WINDOW_LIMIT_EXCEEDED) 结构化承接
+
+后端新增 5 小时 / 7 天滚动窗口 credit 限额：hold 失败返回 429 + 顶层 `errorCode:"WINDOW_LIMIT_EXCEEDED"` + `windowKind` / `windowResetAt`（`/chat` OpenAI 网关扁平形态与 `/anthropic` Anthropic 形态皆有），agent-run SSE error 事件与额度总览同步扩展。SDK 把机器码与窗口字段结构化透传，并顺带修复 `/chat` 网关错误形态 message 一直解析为空的历史缺口。
+
+### Added
+
+- **`HTTPError.errorCode` / `windowKind` / `windowResetAt`** — 后端业务机器码（响应体顶层 `errorCode`）与窗口限额字段（档位 `'FIVE_HOUR' | 'WEEKLY'`、预计恢复时间 ISO-8601 UTC）结构化上提；`parseHTTPError` 在任一错误形态下透传。构造 options 加性扩展，既有调用零改动。
+- **`isWindowLimitError(err)` / `isWindowLimitStreamError(err)`** — 窗口限额识别：前者是 `HTTPError` type guard（结构化 `errorCode` 优先，message/body 含 `WINDOW_LIMIT_EXCEEDED` 子串防御兜底，覆盖后端部署版本错位期）；后者面向流式产物（`StreamError` / `AgentRunStreamError` / 裸 error payload，`code === 'window_limit_exceeded'` 优先 + 同样的子串兜底）。普通 429 rate limit 不误判。
+- **`AgentRunErrorPayload.windowKind` / `windowResetAt`** — agent-run SSE error 事件可选窗口字段，事件解析（`normalizeError` 白名单 pick）透传，camelCase 契约主拼写 + snake_case 兼容兜底。
+- **`QuotaSummary.windowLimits`（`WindowLimitStatus[]`）** — 额度总览新增滚动窗口限额状态：`{ kind: 'FIVE_HOUR' | 'WEEKLY', limitCredits, usedCredits, resetAt?: string | null }`；后端未启用窗口限额时字段整个缺失，向后兼容。
+
+### Fixed
+
+- **`/chat` OpenAI 网关错误形态 message 丢失** — `parseHTTPError` 此前只解析嵌套 `{error:{type,message}}` 形态；网关顶层扁平形态 `{code:429,message:"..."}` 的 message 恒为空、机器码只存活在 body 原串。现补顶层 `message` 解析（该形态无 error.type 来源，`type` 留空），非 JSON body / 空 body 行为逐字节不变。
+
+## [2.10.0] - 2026-06-20 — 多模态向量 / 重排序 (qwen3-vl-embedding / qwen3-vl-rerank)
+
+向量与重排序端点扩展为**多模态**（text / image / **video**），对接 DashScope `qwen3-vl-embedding`（多模态向量端点）与 `qwen3-vl-rerank`（原生 rerank 端点 + 多模态 content）。面向自建搜索引擎的图文 / 视频检索场景。计费口径不变（`total_tokens` 套 input 费率），上游模型名仍由管理员后台自填，不在 SDK / 网关硬编码。
+
+### Added
+
+- **`EmbeddingRequest.contents`** — 多模态向量输入：`MultimodalContent[]`（`{ text?, image?, video? }`）。与 `input`（文本线路）二选一；多模态托管模型用 `contents`。同时新增可选 `output_type` / `fps` / `enable_fusion` 参数。
+- **`RerankRequest` 多态 query / documents** — `query: RerankQuery`（`string | { text?, image? }`），`documents: RerankDocument[]`（`(string | { text?, image?, video? })[]`）；新增可选 `fps`（多模态视频文档抽帧率）。文本调用完全向后兼容（仍可传 `string` / `string[]`）。
+- **类型** — `MultimodalContent` / `RerankQuery` / `RerankDocument`。
+
+### Changed
+
+- **`EmbeddingRequest.input` 改为可选**（`input?: string | string[]`）——多模态线路改用 `contents`。文本调用方无需改动（仍可只传 `input`）。
+
 ## [2.9.0] - 2026-06-20 — 向量 (Embedding) + 重排序 (Rerank) 端点 + listModels 全集模式
 
 托管模型网关新增向量与重排序两类模型（上游接阿里云百炼 DashScope），SDK 订阅会员可经现有会员计费体系（Hold→Settle→Release，按 `total_tokens` 套 input 费率）直接调用。具体上游模型名（`text-embedding-v4` / `gte-rerank-v2` / `qwen3-rerank` 等）由管理员在托管模型后台自填，不在 SDK / 网关硬编码。

package/README.md

@@ -215,6 +215,28 @@ for (const r of resp.results) {
 
 > 重排序对外是**统一扁平契约**；网关内部按模型绑定的线路（DashScope 原生嵌套 `gte-rerank-v2` / OpenAI 兼容扁平 `qwen3-rerank`）自动转换并归一化响应，SDK 侧无需关心。
 
+### 多模态向量 / 重排序（v2.10+，text / image / video）
+
+对接 DashScope `qwen3-vl-embedding`（多模态向量）与 `qwen3-vl-rerank`（多模态重排序）。向量用 `contents` 取代 `input`；重排序的 `query` / `documents` 接受多模态对象（`{ text? , image?, video? }`）。适用于自建搜索引擎的图文 / 视频检索。
+
+```ts
+// 多模态向量：图 / 视频 / 文本混合
+const emb = await client.embeddings(mmEmbModel!.id, {
+  contents: [{ text: '一只橘猫' }, { image: 'https://…/cat.png' }, { video: 'https://…/clip.mp4' }],
+  output_type: 'dense', // 可选
+  fps: 2,               // 可选：视频抽帧率
+});
+
+// 多模态重排序：query 与候选可为多模态对象，也可混入纯文本字符串
+const rr = await client.rerank(mmRerankModel!.id, {
+  query: { text: '红色跑车' },
+  documents: [{ image: 'https://…/car.png' }, { video: 'https://…/road.mp4' }, '一段描述文字'],
+  fps: 1.5, // 可选
+});
+```
+
+> 文本调用完全向后兼容：`input` / 字符串 `query` / 字符串 `documents` 行为不变。多模态托管模型须由管理员在后台勾选对应能力位与输入模态（text/image/video）。
+
 ## 双格式红线（设计核心）
 
 SDK 同时提供 **Anthropic + OpenAI 两条 endpoint**，**等地位**，对应两个不同下游产品。

package/dist/browser/index.mjs

@@ -91,7 +91,21 @@ var init_types = __esm({
 });
 
 // src/shared/errors.ts
-var RateLimitError, BusinessError, OrderTerminalError, ModelNotFoundError, HTTPError, NetworkError, StreamError;
+function isWindowLimitError(err) {
+  if (!(err instanceof HTTPError)) return false;
+  if (err.errorCode === windowLimitErrorCode) return true;
+  return err.message.includes(windowLimitErrorCode) || err.body.includes(windowLimitErrorCode);
+}
+function isWindowLimitStreamError(err) {
+  if (err == null || typeof err !== "object") return false;
+  const e = err;
+  if (e.code === windowLimitStreamCode) return true;
+  for (const field of [e.message, e.userMessage, e.rawError]) {
+    if (typeof field === "string" && field.includes(windowLimitErrorCode)) return true;
+  }
+  return false;
+}
+var RateLimitError, BusinessError, OrderTerminalError, ModelNotFoundError, HTTPError, NetworkError, StreamError, windowLimitErrorCode, windowLimitStreamCode;
 var init_errors = __esm({
   "src/shared/errors.ts"() {
     RateLimitError = class extends Error {
@@ -138,6 +152,12 @@ var init_errors = __esm({
       retryAfter;
       /** 原始响应体 (截断到 maxErrorBodySize) */
       body;
+      /** 后端业务机器码 (响应体顶层 errorCode, e.g. "WINDOW_LIMIT_EXCEEDED"); 缺失为 undefined */
+      errorCode;
+      /** 窗口限额场景: 触发的滚动窗口档位 (FIVE_HOUR = 5 小时 / WEEKLY = 7 天); 缺失为 undefined */
+      windowKind;
+      /** 窗口限额场景: 预计恢复时间 (ISO-8601 UTC); 缺失为 undefined */
+      windowResetAt;
       constructor(statusCode, opts = {}) {
         let msg;
         if (opts.type) {
@@ -155,6 +175,9 @@ var init_errors = __esm({
         this.type = opts.type ?? "";
         this.retryAfter = opts.retryAfter ?? 0;
         this.body = opts.body ?? "";
+        this.errorCode = opts.errorCode;
+        this.windowKind = opts.windowKind;
+        this.windowResetAt = opts.windowResetAt;
       }
     };
     NetworkError = class extends Error {
@@ -210,6 +233,8 @@ var init_errors = __esm({
         this.retryable = retryable;
       }
     };
+    windowLimitErrorCode = "WINDOW_LIMIT_EXCEEDED";
+    windowLimitStreamCode = "window_limit_exceeded";
   }
 });
 
@@ -1930,19 +1955,28 @@ function parseHTTPErrorWithHeader(statusCode, body, header) {
   }
   let type = "";
   let message = "";
+  let errorCode;
+  let windowKind;
+  let windowResetAt;
   try {
     const obj = JSON.parse(bodyStr);
     if (obj && typeof obj === "object") {
-      const errObj = obj.error;
+      const top = obj;
+      const errObj = top.error;
       if (errObj && typeof errObj === "object") {
         const e = errObj;
         if (typeof e.message === "string") message = e.message;
         if (typeof e.type === "string") type = e.type;
+      } else if (typeof top.message === "string") {
+        message = top.message;
       }
+      if (typeof top.errorCode === "string") errorCode = top.errorCode;
+      if (top.windowKind === "FIVE_HOUR" || top.windowKind === "WEEKLY") windowKind = top.windowKind;
+      if (typeof top.windowResetAt === "string") windowResetAt = top.windowResetAt;
     }
   } catch {
   }
-  return new HTTPError(statusCode, { type, message, retryAfter, body: bodyStr });
+  return new HTTPError(statusCode, { type, message, retryAfter, body: bodyStr, errorCode, windowKind, windowResetAt });
 }
 function classifyTransport(op, urlStr, err) {
   const ne = new NetworkError(op, urlStr, err);
@@ -2206,9 +2240,16 @@ var Client = class _Client {
   fetchImpl;
   /** 互斥锁 (TS 用 Promise chain 替代 sync.Mutex) */
   mu = Promise.resolve();
-  /** WebSocket 状态 (实际方法由 ws.ts mixin 维护) */
+  /**
+   * WebSocket 状态 (实际方法由 ws.ts mixin 维护)。
+   * @internal — 实现细节: 跨模块 (ws.ts mixin) 需可见故为 public, 但非消费者 API,
+   * 消费者用 connect/subscribe 等高层方法; 引用的 WSState 不进公开文档。
+   */
   ws = null;
-  /** v0.15.1: token 就绪等待机制 — login 成功后 resolve, 等待方解除阻塞 */
+  /**
+   * v0.15.1: token 就绪等待机制 — login 成功后 resolve, 等待方解除阻塞。
+   * @internal — 内部同步原语 (Deferred), 非消费者 API。
+   */
   tokenReady = newDeferred();
   /** Login 进行中 — 等待方需等而非 fail-fast */
   loginInFlight = false;
@@ -5629,6 +5670,9 @@ function normalizeError(value) {
     message: stringField(value, "message", "error") || "agent run failed",
     stage: optionalStringField(value, "stage"),
     retryable: typeof value.retryable === "boolean" ? value.retryable : void 0,
+    // 窗口限额扩展 (code="window_limit_exceeded"): 契约 wire 为 camelCase, 蛇形兼容兜底。
+    windowKind: optionalStringField(value, "windowKind", "window_kind"),
+    windowResetAt: optionalStringField(value, "windowResetAt", "window_reset_at"),
     raw: value
   };
 }
@@ -7546,6 +7590,6 @@ function brandCredential(c) {
   return c;
 }
 
-export { AGENT_RUN_META_TITLE, AGENT_RUN_META_WORKSPACE, ALL_INTEGRATION_STATUS, ALL_PLATFORMS, ALL_REGIONS, AgentRunStreamError, AgentRunsClient, AnthropicAdapter, AudienceEnum, BillingModeEnum, BucketClassCommercial, BucketClassGeneric, BusinessError, ChatBridgeClient, Client, ComplianceClient, CompliancePollError, CrabCodeByokClient, DEFAULT_API_TIMEOUT_MS, DEFAULT_GATEWAY_BASE_URL, LocalStorageTokenStore as DefaultBrowserTokenStore, DefaultRetryPolicy, ErrAuthDenied, ErrBillingCallbackCannotCommit, ErrBillingCommitRequiresLocalVerify, ErrBillingS2sForbidden, ErrBrowserOpen, ErrComplianceStepUpRequired, ErrDiscovery, ErrEnvelopeGateClosed, ErrOAuthCORSBlocked, ErrProviderNotConfigured, ErrProviderUnknownNoRetry, ErrRefreshProxyFailed, ErrRegistration, ErrSSLProxy, ErrSealApprovalContractHashMismatch, ErrSealApprovalExpired, ErrSealApprovalLocationMismatch, ErrSealApprovalNonceUsed, ErrSealApprovalNotApproved, ErrSealApprovalSealMismatch, ErrSealApprovalTransactorMismatch, ErrSealUseAlreadyConsumed, ErrStateMismatch, ErrTimeout, ErrTokenExchange, ErrTokenExpired, EventAuthURL, EventComplete, EventError, FileTokenStore, FilterStatusAdminBypass, FilterStatusDisabledByFlag, FilterStatusFallbackMissingUser, FilterStatusFallbackNoBuckets, FilterStatusFallbackTkdistError, FilterStatusFallbackTkdistSkew, FilterStatusInternalBypass, FilterStatusOK, FilterStatusUnknown, HTTPError, IdempotencyKeyHeader, InMemoryTokenStore, LocalStorageTokenStore, ModelNotFoundError, NetworkError, OAuthTokenEndpointError, OpenAIAdapter, OrderTerminalError, ProductFamilyEnum, ProviderFormat, RETRY_ADVICE_REASONS, RateLimitError, RegionScopeEnum, ScopeAI, ScopeAccount, ScopeChatBridge, ScopeChatBridgeRead, ScopeChatBridgeRotate, ScopeChatBridgeWrite, ScopeComplianceContractSigningRead, ScopeComplianceContractSigningWrite, ScopeComplianceContractTemplateRead, ScopeComplianceContractTemplateWrite, ScopeComplianceEvidenceRead, ScopeComplianceEvidenceWrite, ScopeComplianceReportsPublish, ScopeComplianceReportsRead, ScopeComplianceReportsWrite, ScopeComplianceSealApprovalApprove, ScopeComplianceSealApprovalRequest, ScopeComplianceSealManage, ScopeComplianceSealUseExecute, ScopeComplianceTimestampIssue, ScopeComplianceTimestampVerify, ScopeEntitlements, ScopeModels, ScopeModelsChat, ScopeProfile, ScopeRemoteControl, ScopeRemoteControlAgentRun, ScopeRemoteControlPermissionResponse, ScopeRemoteControlSessionControl, ScopeSkillStore, ScopeSkills, ScopeTokenPackages, ScopeTools, ScopeToolsExecute, ScopeWallet, ScopeWalletReadonly, ServerToolTypeWebSearch, StreamError, ThinkingHigh, ThinkingHighMinMaxTokens, ThinkingMax, ThinkingMaxFallbackMaxTokens, ThinkingOff, allScopes, anthropicResponseTextContent, anthropicResponseThinkingContent, anthropicResponseToolUseBlocks, apiResponseBusinessError, apiResponseGetMessage, asCredentialRef, authorize, bucketInfoIsCommercial, bucketRowIsCommercial, buildBetas, chatBridgeScopes, classifyComplianceError, commerceScopes, completeWebAuthorizationRequest, complianceErrorToRetryAdvice, complianceScopes, computeBackoff, createWebAuthorizationRequest, defaultRetryable, defaultSafeToRetry, discover, discoverWebOAuthMetadata, discoverWithProfile, effectivePolicy, exchangeCode, extractAnthropicBlockMeta, fileLockDefaults, findDesktopVisualUnderstandingModel, findFirstModelByInputModality, generateState, getAdapter, getAdapterForModel, isBillingConfirmable, isChannelInboundEvent, isComplianceBusinessError, isComplianceTerminalError, isIntegrationStatus, isInvalidGrantError, isPlatform, isRegion, isSSECommentLine, isSSLError, isTerminalRemoteEvent, isValidTokenSet, maxEndUserIdLength, modelScopes, modelSupportsImageInput, modelSupportsInputModality, newFileTokenStore, newThinkingConfig, newTokenSet, newWebSearchTool, normalizeGatewayBaseURL, normalizeOverrideBaseURL, parseNotificationEvent, parseRemoteControlEvent, parseSettlement, parseSourcesEvent, refreshToken, register, registerWebOAuthClient, remoteControlScopes, retryReasonForComplianceKey, retryReasonForOAuthError, revokeToken, sanitize_exports as sanitize, skillScopes, tokenSetIsExpired, uniqueMerge, validateEndUserId };
+export { AGENT_RUN_META_TITLE, AGENT_RUN_META_WORKSPACE, ALL_INTEGRATION_STATUS, ALL_PLATFORMS, ALL_REGIONS, AgentRunStreamError, AgentRunsClient, AnthropicAdapter, AudienceEnum, BillingModeEnum, BucketClassCommercial, BucketClassGeneric, BusinessError, ChatBridgeClient, Client, ComplianceClient, CompliancePollError, CrabCodeByokClient, DEFAULT_API_TIMEOUT_MS, DEFAULT_GATEWAY_BASE_URL, LocalStorageTokenStore as DefaultBrowserTokenStore, DefaultRetryPolicy, ErrAuthDenied, ErrBillingCallbackCannotCommit, ErrBillingCommitRequiresLocalVerify, ErrBillingS2sForbidden, ErrBrowserOpen, ErrComplianceStepUpRequired, ErrDiscovery, ErrEnvelopeGateClosed, ErrOAuthCORSBlocked, ErrProviderNotConfigured, ErrProviderUnknownNoRetry, ErrRefreshProxyFailed, ErrRegistration, ErrSSLProxy, ErrSealApprovalContractHashMismatch, ErrSealApprovalExpired, ErrSealApprovalLocationMismatch, ErrSealApprovalNonceUsed, ErrSealApprovalNotApproved, ErrSealApprovalSealMismatch, ErrSealApprovalTransactorMismatch, ErrSealUseAlreadyConsumed, ErrStateMismatch, ErrTimeout, ErrTokenExchange, ErrTokenExpired, EventAuthURL, EventComplete, EventError, FileTokenStore, FilterStatusAdminBypass, FilterStatusDisabledByFlag, FilterStatusFallbackMissingUser, FilterStatusFallbackNoBuckets, FilterStatusFallbackTkdistError, FilterStatusFallbackTkdistSkew, FilterStatusInternalBypass, FilterStatusOK, FilterStatusUnknown, HTTPError, IdempotencyKeyHeader, InMemoryTokenStore, LocalStorageTokenStore, ModelNotFoundError, NetworkError, OAuthTokenEndpointError, OpenAIAdapter, OrderTerminalError, ProductFamilyEnum, ProviderFormat, RETRY_ADVICE_REASONS, RateLimitError, RegionScopeEnum, ScopeAI, ScopeAccount, ScopeChatBridge, ScopeChatBridgeRead, ScopeChatBridgeRotate, ScopeChatBridgeWrite, ScopeComplianceContractSigningRead, ScopeComplianceContractSigningWrite, ScopeComplianceContractTemplateRead, ScopeComplianceContractTemplateWrite, ScopeComplianceEvidenceRead, ScopeComplianceEvidenceWrite, ScopeComplianceReportsPublish, ScopeComplianceReportsRead, ScopeComplianceReportsWrite, ScopeComplianceSealApprovalApprove, ScopeComplianceSealApprovalRequest, ScopeComplianceSealManage, ScopeComplianceSealUseExecute, ScopeComplianceTimestampIssue, ScopeComplianceTimestampVerify, ScopeEntitlements, ScopeModels, ScopeModelsChat, ScopeProfile, ScopeRemoteControl, ScopeRemoteControlAgentRun, ScopeRemoteControlPermissionResponse, ScopeRemoteControlSessionControl, ScopeSkillStore, ScopeSkills, ScopeTokenPackages, ScopeTools, ScopeToolsExecute, ScopeWallet, ScopeWalletReadonly, ServerToolTypeWebSearch, StreamError, ThinkingHigh, ThinkingHighMinMaxTokens, ThinkingMax, ThinkingMaxFallbackMaxTokens, ThinkingOff, allScopes, anthropicResponseTextContent, anthropicResponseThinkingContent, anthropicResponseToolUseBlocks, apiResponseBusinessError, apiResponseGetMessage, asCredentialRef, authorize, bucketInfoIsCommercial, bucketRowIsCommercial, buildBetas, chatBridgeScopes, classifyComplianceError, commerceScopes, completeWebAuthorizationRequest, complianceErrorToRetryAdvice, complianceScopes, computeBackoff, createWebAuthorizationRequest, defaultRetryable, defaultSafeToRetry, discover, discoverWebOAuthMetadata, discoverWithProfile, effectivePolicy, exchangeCode, extractAnthropicBlockMeta, fileLockDefaults, findDesktopVisualUnderstandingModel, findFirstModelByInputModality, generateState, getAdapter, getAdapterForModel, isBillingConfirmable, isChannelInboundEvent, isComplianceBusinessError, isComplianceTerminalError, isIntegrationStatus, isInvalidGrantError, isPlatform, isRegion, isSSECommentLine, isSSLError, isTerminalRemoteEvent, isValidTokenSet, isWindowLimitError, isWindowLimitStreamError, maxEndUserIdLength, modelScopes, modelSupportsImageInput, modelSupportsInputModality, newFileTokenStore, newThinkingConfig, newTokenSet, newWebSearchTool, normalizeGatewayBaseURL, normalizeOverrideBaseURL, parseNotificationEvent, parseRemoteControlEvent, parseSettlement, parseSourcesEvent, refreshToken, register, registerWebOAuthClient, remoteControlScopes, retryReasonForComplianceKey, retryReasonForOAuthError, revokeToken, sanitize_exports as sanitize, skillScopes, tokenSetIsExpired, uniqueMerge, validateEndUserId };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map