@acosmi/sdk-ts 2.8.0 → 2.9.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@ 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.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,46 @@ 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 侧无需关心。
+
 ## 双格式红线（设计核心）
 
 SDK 同时提供 **Anthropic + OpenAI 两条 endpoint**，**等地位**，对应两个不同下游产品。
@@ -508,6 +548,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

@@ -2679,8 +2679,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 +2693,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 +2901,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 自动路由