@acosmi/sdk-ts 2.8.0 → 2.10.0

package/CHANGELOG.md

@@ -5,6 +5,31 @@ 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.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 / 网关硬编码。
+
+### Added
+
+- **`client.embeddings(modelID, req)`** — 向量（同步，`POST /managed-models/:id/embeddings`）：请求 `{ input: string | string[], dimensions?, encoding_format? }`，响应为 OpenAI `/v1/embeddings` 标准格式（`{ object, model, data: [{ embedding }], usage }`，网关直通无包装）。仅 `capabilities.supports_embedding=true` 的模型可用。
+- **`client.rerank(modelID, req)`** — 重排序（同步，`POST /managed-models/:id/rerank`）：统一扁平契约 `{ query, documents[], top_n?, return_documents?, instruct? }`，响应 `{ results: [{ index, relevance_score, document? }], usage, model }`（网关已把上游原生嵌套 / OpenAI 兼容扁平两线路归一化）。仅 `capabilities.supports_rerank=true` 的模型可用。
+- **类型** — `EmbeddingRequest`/`EmbeddingData`/`EmbeddingResponse`/`RerankRequest`/`RerankResult`/`RerankResponse`。
+- **`listModels` / `listModelsWithStatus` 新增 `opts.includeLocked`** — `true` 时请求 `/managed-models?picker=1` 全集模式：网关把越档模型作为 `Locked=true` 补回返全集，供 C 端选择器展示「付费订阅区」+ 置灰升级引导。缺省行为不变（只返有桶模型，向后兼容）。全集模式不写 `modelCache`，避免 locked 模型混入可用模型集。
+
 ## [2.7.0] - 2026-06-11 — 远控管理面补齐 + BYOK 密钥客户端 + Chat Bridge CRUD（Phase 7B）
 
 补齐远控核心交互之外的全部管理面（此前下游 CrabCode 只能裸 fetch），新增 BYO 模型密钥客户端，落地 chat-bridge integration/credential 管理面 CRUD——云端控制台与下游调用的是同一组端点同一份租户隔离数据，天然互通。全部方法逐字段对齐 nexus-v4 handler 真实 wire 形状（契约 §12/§14/§18 附录 A）。

package/README.md

@@ -175,6 +175,68 @@ console.log(res.videoUrl); // VideoTaskResponse: taskId / status / videoUrl / er
 
 > 字段是网关**通用契约**；某厂商支持哪些取值由上游模型决定（如万相尺寸 `宽*高` 星号格式由网关代转）。网关适配范围：OpenAI 兼容图片 + 火山引擎（即梦/豆包）视频 + DashScope 通义万相（wanx）原生异步任务（图片+视频）。
 
+## 向量 / 重排序（托管模型网关，v2.9+）
+
+向量（embedding）与重排序（rerank）走与 chat 同一套**会员计费**（Hold→Settle→Release，按 `total_tokens` 套 input 费率），上游接阿里云百炼 DashScope。仅 `capabilities.supports_embedding` / `supports_rerank` 的托管模型可用；具体上游模型名由管理员在后台自填。
+
+### 向量（同步）
+
+`embeddings` 一次调用拿向量，响应即 OpenAI `/v1/embeddings` 标准格式。
+
+```ts
+const models = await client.listModels();
+const embModel = models.find((m) => m.capabilities?.supports_embedding);
+
+const resp = await client.embeddings(embModel!.id, {
+  input: ['第一段文本', '第二段文本'], // string 或 string[]
+  dimensions: 1024,                   // 可选
+});
+console.log(resp.data[0].embedding);  // number[]
+console.log(resp.usage.total_tokens);
+```
+
+### 重排序（同步）
+
+`rerank` 传入 query + 候选文档，返回按相关性排序的下标与得分。
+
+```ts
+const rerankModel = models.find((m) => m.capabilities?.supports_rerank);
+
+const resp = await client.rerank(rerankModel!.id, {
+  query: '什么是文本排序模型',
+  documents: ['文档A', '文档B', '文档C'],
+  top_n: 3,              // 可选
+  return_documents: true, // 可选：结果内回传文档原文
+});
+for (const r of resp.results) {
+  console.log(r.index, r.relevance_score, r.document);
+}
+```
+
+> 重排序对外是**统一扁平契约**；网关内部按模型绑定的线路（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**，**等地位**，对应两个不同下游产品。
@@ -508,6 +570,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.supports_image_generation` / `supports_video_generation` 模型可用 |
+| **向量 / 重排序**（v2.9.0+） | `embeddings`（同步）, `rerank`（同步）；仅 `capabilities.supports_embedding` / `supports_rerank` 模型可用 |
 | **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` |

package/dist/browser/index.mjs

@@ -2206,9 +2206,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;
@@ -2679,8 +2686,8 @@ var Client = class _Client {
    * V30 二轮审计 D-P1-2: 此方法不返回 entitlement-filter-status header.
    * UI 想根据 fallback 状态显示降级提示, 请改调 listModelsWithStatus.
    */
-  async listModels(signal) {
-    const r = await this.listModelsWithStatus(signal);
+  async listModels(signal, opts) {
+    const r = await this.listModelsWithStatus(signal, opts);
     return r.models;
   }
   /**
@@ -2693,16 +2700,20 @@ var Client = class _Client {
    *   - status === 'disabled-by-flag' → 不显示余量 (运维灰度中)
    *   - status === '' (Unknown) → 老 nexus, 按老 v0.17 行为 (不显示 BucketInfo)
    */
-  async listModelsWithStatus(signal) {
+  async listModelsWithStatus(signal, opts) {
+    const includeLocked = opts?.includeLocked === true;
+    const path = includeLocked ? "/managed-models?picker=1" : "/managed-models";
     const { result, headers } = await this.doJSONFull(
       "GET",
-      "/managed-models",
+      path,
       null,
       signal
     );
     const normalized = normalizeInputModalities(result.data);
-    this.modelCache = normalized;
-    this.modelCacheTimeMs = Date.now();
+    if (!includeLocked) {
+      this.modelCache = normalized;
+      this.modelCacheTimeMs = Date.now();
+    }
     let status = "";
     if (headers) {
       const h = headers.get("X-Entitlement-Filter-Status");
@@ -2897,6 +2908,34 @@ var Client = class _Client {
     const { result } = await this.doJSONFullRaw("GET", endpoint, null, signal);
     return this.unwrapAPIResponse(result);
   }
+  /**
+   * 向量 (同步)。POST /managed-models/:id/embeddings
+   *
+   * 仅 capabilities.supports_embedding=true 的托管模型可用 (上游接 DashScope)。
+   * 响应为 OpenAI /v1/embeddings 标准格式 (网关直通, 无 response.Success 包装)。
+   *
+   * @param modelID 向量托管模型 ID
+   */
+  async embeddings(modelID, req, signal) {
+    const endpoint = `/managed-models/${encodeURIComponent(modelID)}/embeddings`;
+    const { result } = await this.doJSONFullRaw("POST", endpoint, req, signal, CHAT_REQUEST_TIMEOUT_MS);
+    return JSON.parse(new TextDecoder().decode(result));
+  }
+  /**
+   * 重排序 (同步)。POST /managed-models/:id/rerank
+   *
+   * 仅 capabilities.supports_rerank=true 的托管模型可用 (上游接 DashScope)。
+   * 统一扁平契约: { query, documents[], top_n?, return_documents?, instruct? };
+   * 响应 { results: [{ index, relevance_score, document? }], usage, model }
+   * (网关已把上游原生/OpenAI 兼容两线路归一化, 无 response.Success 包装)。
+   *
+   * @param modelID 重排序托管模型 ID
+   */
+  async rerank(modelID, req, signal) {
+    const endpoint = `/managed-models/${encodeURIComponent(modelID)}/rerank`;
+    const { result } = await this.doJSONFullRaw("POST", endpoint, req, signal, CHAT_REQUEST_TIMEOUT_MS);
+    return JSON.parse(new TextDecoder().decode(result));
+  }
   /**
    * Anthropic 原生格式同步聊天
    * v0.5.0: 根据 provider 自动路由