@acosmi/sdk-ts 2.17.0 → 2.18.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ 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.18.0] - 2026-08-29 — `ManagedModel.thinking_levels` 类型面对齐
+
+网关 `ManagedModelPublicResponse` 新增 `thinking_levels: []string`（升序档位 id，按「admin 声明 ∩ wire 层真投递」读时派生）。`listModels` / `listModelsWithStatus` 对 `ManagedModel` 本就原样透传（唯一归一化是 `input_modalities` → `inputModalities`），所以本版**只补类型面与文档**，零运行时改动。
+
+### Added
+
+- **`ManagedModel.thinking_levels?: string[]`** —— 该模型可选的思考深度档位 id，取值是 `ThinkingOff` / `ThinkingHigh` / `ThinkingMax`（`'off'` / `'high'` / `'max'`）的子集。字段名保持 wire snake_case，与同结构的 `supported_formats` / `preferred_format` 同风格（见 `src/models/types.ts` 文件头命名约定）。三态语义写进 JSDoc 与 README：`[]` = 该模型没有思考档（不渲染档位选择）；`undefined` = 上游未播报（旧网关），调用方必须按"未知"处理，**严禁**回落到自己推档或按模型名 substring 猜。公开方法签名零移除、零改名，旧调用方逐字节兼容。
+
+### 回归闸门
+
+- `test/list-models-thinking-levels.test.ts` —— `listModels` / `listModelsWithStatus` 在 `thinking_levels: ['off','high','max']`、单档子集、`[]`、字段缺失四种 payload 下的原样可读性；含"`[]` 与 `undefined` 不可互换"的正向对照（防把空数组当缺失处理的读侧漂移），以及"不因新字段而误伤 `inputModalities` 归一化"的共存用例。
+
 ## [2.17.0] - 2026-08-15 — 桌面 loopback OAuth state 全路径闸 + 端口确定性关闭
 
 **回环监听在整个登录期间对本机任意进程开放，state 是唯一的门。** 2.16.0 及更早版本的桌面 loopback `authorize` 不生成也不校验 OAuth `state`（`af2daa0b` 已在源码补上核心校验，但从未发版）；且校验只覆盖"带 code"的回调 —— 携带 OAuth error 的回调**绕过 state 直接把登录结算成"用户已拒绝"**，本机恶意进程不猜任何秘密就能打断/塑形一次等待中的登录；重复 `state` 参数取首值即可蒙混（`?code=攻击者的码&state=<正确值>&state=x` 在旧实现下**成功登录到攻击者会话**）。本版把 state 校验提到 `/callback` 所有形态之前，并收紧为"恰好一个"。

package/README.md

@@ -7,7 +7,9 @@
 ## 状态
 
 - **主实现 / 事实标准**：本 TS SDK 现为 Acosmi SDK 的主力实现。Go SDK [acosmi-sdk-go](https://github.com/acosmi/acosmi-sdk-go) 已暂停维护，待 TS 稳定后再从 TS 反向翻译补齐。
-- **当前版本：`2.15.0`**（sources 四态分类与零结果兼容契约，2026-08-02）。
+- **当前版本：`2.18.0`**（`ManagedModel.thinking_levels` 类型面对齐，2026-08-29）。
+- **`v2.18.0`（加性类型发布）**：`ManagedModel` 新增可选字段 `thinking_levels?: string[]` —— 网关下发的**升序思考档位 id 列表**（`ThinkingOff`/`ThinkingHigh`/`ThinkingMax` 的子集）。`listModels` 对它原样透传，公开签名向后兼容、零行为变化；`[]` = 该模型无思考档，`undefined` = 旧网关未播报（按"未知"处理，严禁自行推档）。详见〈思考档位 `thinking_levels`〉。
+- **`v2.17.0`（安全修复发布）**：桌面 loopback `authorize()` 对 `/callback` 的**一切形态**（成功 / OAuth error / 畸形）先行校验 CSRF `state`，且必须"恰好一个"并严格等值 —— 缺失、重复（含重复的正确值）、错值一律以稳定错误码 `state_mismatch` 拒绝本次登录；此前携带 OAuth error 的回调绕过 state 直接结算 `auth_denied`，本机任意进程零知识即可打断/塑形等待中的登录，且 `?code=…&state=<正确值>&state=x` 这类重复参数可蒙混通过。`finally` 补 `closeIdleConnections()`，每条终止路径以端口完全关闭收尾。公开 API 签名零变化；回归闸门 `test/auth/desktop-loopback-state.test.ts` 十路终止矩阵。
 - **`v2.15.0`（加性兼容发布）**：新增 `classifySourcesEvent()`、`SourcesEventParseResult` 与稳定 issue code，把 `not_sources`、合法 `empty_sources`、非空 `sources`、`malformed_sources` 明确分开。既有 `parseSourcesEvent()` 的代码路径、宽松判定、`null` 条件和返回对象形状保持原样；现有 consumer 无需改动，新 consumer 才选择严格 API。
 - **`v2.6.0`（会员订阅查询 + 类型修正，2026-06-04）**：新增 `subscription.getMembership()` / `getSubscriptionTier()` / `subscriptionPrecheck()`；`ManagedModel` 补档位门控字段（`locked`/`freeTier`/`minPlanTier`/`chatRuntimeSupported`/`defaultToolIds`）；auth 新增 `ScopeChatBridge`(+read/write/rotate) 与 `chatBridgeScopes()`。**破坏性类型修正**：`BalanceDetail` 形状对齐网关 `InternalBalanceResponse`、`Order` 拆为 `BuyResponse`/`OrderListItem`、`getOrderStatus`/`waitForPayment` 改用 `BuyResponse.paymentStatus`（修死循环）、`PayPayload.payMethod`→`paymentMethod`、`TokenPackage` 对齐 `toProductView`、`WalletStats`/`Transaction` `amount` 由 string 改 number、consume-records 分页修正、notifications WebSocket 用一次性 `stream-ticket` 取代 URL `?token=` JWT。废弃 `listUserSubscriptions`（改用 `getMembership`）、`ModelCoefficient`/`listCoefficients`（系数退役恒空）、`ManagedModel.pricePerMTok`/`isDefault`（公开端点不返回）；notifications 设备/偏好方法标 `@experimental`。详见 CHANGELOG。
 - **`v2.5.1`（格式一致性护栏，2026-05-31）**：`getAdapterForModel` 路由加固 —— `preferred_format` 现仅在**确被 `supported_formats` 收录**时才采信（或 `supported_formats` 未声明时维持原样）。防止上游元数据漂移（如 `preferred_format=anthropic` 但 `supported_formats=[openai]`）把 SDK 路由到模型并不支持的格式端点，撞 `/anthropic`「未绑定 Anthropic」4xx。`supported_formats` 为空/未知（旧上游）时**行为逐字节不变**。新增 3 条 routing 用例钉死矛盾场景。
@@ -176,6 +178,21 @@ console.log(res.videoUrl); // VideoTaskResponse: taskId / status / videoUrl / er
 
 > 字段是网关**通用契约**；某厂商支持哪些取值由上游模型决定（如万相尺寸 `宽*高` 星号格式由网关代转）。网关适配范围：OpenAI 兼容图片 + 火山引擎（即梦/豆包）视频 + DashScope 通义万相（wanx）原生异步任务（图片+视频）。
 
+## 思考档位 `thinking_levels`（v2.18+）
+
+`ManagedModel.thinking_levels?: string[]` —— 该模型**可选的思考深度档位 id**，升序下发，取值是 `ThinkingOff` / `ThinkingHigh` / `ThinkingMax`（`'off'` / `'high'` / `'max'`）的子集。网关按「admin 声明 ∩ wire 层真投递」读时派生；`listModels` 对它**原样透传**（与 `supported_formats` / `preferred_format` 同为 wire snake_case，不做 camelCase 重映射）。
+
+**三态必须分开处理 —— `[]` 与 `undefined` 不是同一件事**：
+
+```ts
+const m = (await client.listModels()).find((x) => x.id === modelId)!;
+if (m.thinking_levels === undefined) renderThinkingUnknown();     // 旧网关未播报 → 按"未知"处理
+else if (m.thinking_levels.length === 0) hideThinkingPicker();    // 该模型没有思考档 → 不渲染档位选择
+else renderThinkingPicker(m.thinking_levels);                     // 升序档位, 原样渲染
+```
+
+缺失时**严禁**自己推档或按模型名 substring 猜 —— 档位值域归网关模型目录所有，靠运营动作扩张，不靠发 SDK 新版（同 `inputModalities` 开放值域的教训，见 v2.14.0）。该字段与 `capabilities.supports_thinking` / `supports_max_effort` 是**正交**两件事：后者描述模型有无该能力，前者描述**这条链路上此刻真能选哪几档**。
+
 ## 向量 / 重排序（托管模型网关，v2.9+）
 
 向量（embedding）与重排序（rerank）走与 chat 同一套**会员计费**（Hold→Settle→Release，按 `total_tokens` 套 input 费率），上游接阿里云百炼 DashScope。仅 `capabilities.supports_embedding` / `supports_rerank` 的托管模型可用；具体上游模型名由管理员在后台自填。
@@ -602,6 +619,8 @@ const tokens = newTokenSet(tokenResp, reg.client_id, process.env.ACOSMI_SERVER_U
 await new FileTokenStore('./tokens.json').save(tokens);
 ```
 
+> **state 语义（v2.17.0 起）**：桌面 loopback 流程自动生成 32 字节随机 `state` 并对 `/callback` 的一切形态先行校验 —— 恰好一个且严格等值，缺失 / 重复 / 错值一律以错误码 `state_mismatch` 拒绝本次登录并关闭 listener（含携带 OAuth error 的回调；用户真拒绝须回传正确 state 才结算为 `auth_denied`）。调用方零改动：`state` 由 SDK 内部管理，不出现在 `authorize()` 的公开签名里。授权服务器按 RFC 6749 §4.1.2.1 在**错误响应**上也必须原样回传 `state`（Acosmi 官方 consent 页已适配）。
+>
 > 浏览器侧（无法启 loopback HTTP server）请改用 v1.4.0+ Web OAuth 原语 `discoverWebOAuthMetadata` + `registerWebOAuthClient` + `createWebAuthorizationRequest` + `completeWebAuthorizationRequest`，由调用方实现 popup / 同窗口 redirect handler，SDK 负责 PKCE / state 校验 / token 兑换。
 
 ### Token 持久化
@@ -1124,7 +1143,9 @@ npm run docs    # 经 TypeDoc 生成 API 参考到 docs/api/
 
 | 版本 | 状态 | 概要 |
 | --- | --- | --- |
-| 2.16.0 | **当前版本** | **chat 超时预算真正下传 + 流式活性回调（2026-08-06）**。`chat` / `chatMessagesAnthropic` / `chatMessagesOpenAI` / `generateVideo` 此前漏传 `doJSONFullRaw` 的第 5 实参，内层 **30 秒**默认值恒先于外层 11 分钟预算触发 —— v1.6.0 那次"调整为 11min"一天都没生效过（生产实证：单日 29 条 latency≈30 000 ms 的 499，横跨 4 厂商 5 模型，受害最重的是默认主循环模型）。加性导出 `CHAT_REQUEST_TIMEOUT_MS`；`chatStream` / `chatMessagesStream` 新增第 4 个可选实参 `onUpstreamActivity`，让被 `isSSECommentLine` 吞掉的保活注释行（以及 OpenAI 格式下零事件的 data 行）能抵达消费方的空闲看门狗。不传回调时行为逐字节不变。 |
+| 2.18.0 | **当前版本** | **`ManagedModel.thinking_levels` 类型面对齐（2026-08-29）**。加性新增可选字段 `thinking_levels?: string[]`：网关下发的升序思考档位 id 列表（`'off'`/`'high'`/`'max'` 的子集，按「admin 声明 ∩ wire 层真投递」派生）。`listModels` 原样透传，无归一化、无新方法、公开签名零变化。`[]` = 该模型无思考档；`undefined` = 旧网关未播报，调用方按"未知"处理，严禁按模型名推档。 |
+| 2.17.0 | 稳定版 | **桌面 loopback OAuth state 全路径闸 + 端口确定性关闭（2026-08-15）**。`/callback` 一切形态（成功 / OAuth error / 畸形）先验 `state` 且必须恰好一个并严格等值；缺失 / 重复（含重复的正确值）/ 错值一律 `state_mismatch` 拒绝且不再被误结算为 `auth_denied`；错误信息只描述形态，不回显 code / state / token / 完整 callback query。`finally` 补 `closeIdleConnections()`（Node 18 上 `close()` 不关残留 idle keep-alive）。用户真拒绝（OAuth error + 正确 state）语义保留为 `auth_denied`。公开 API 签名零变化。 |
+| 2.16.0 | 稳定版 | **chat 超时预算真正下传 + 流式活性回调（2026-08-06）**。`chat` / `chatMessagesAnthropic` / `chatMessagesOpenAI` / `generateVideo` 此前漏传 `doJSONFullRaw` 的第 5 实参，内层 **30 秒**默认值恒先于外层 11 分钟预算触发 —— v1.6.0 那次"调整为 11min"一天都没生效过（生产实证：单日 29 条 latency≈30 000 ms 的 499，横跨 4 厂商 5 模型，受害最重的是默认主循环模型）。加性导出 `CHAT_REQUEST_TIMEOUT_MS`；`chatStream` / `chatMessagesStream` 新增第 4 个可选实参 `onUpstreamActivity`，让被 `isSSECommentLine` 吞掉的保活注释行（以及 OpenAI 格式下零事件的 data 行）能抵达消费方的空闲看门狗。不传回调时行为逐字节不变。 |
 | 2.15.0 | 稳定版 | **sources 四态分类与零结果契约（2026-08-02）**。加性新增 `classifySourcesEvent`、`SourcesEventParseResult` 与稳定 issue code，区分非 sources、合法空结果、有效结果和结构损坏；未知额外字段继续兼容。既有 `parseSourcesEvent` 的返回形状、宽松解析和 `null` 条件保持不变。 |
 | 2.14.0 | 稳定版 | **托管模型 input modalities 开放值域（2026-08-02）**。snake_case/camelCase 归一规则对称，数据字段允许未来新增标签；查询 API 仍保留已知标签自动补全。现网 camelCase 路径行为不变。 |
 | 2.13.0 | 稳定版 | **邀请奖励窗口重置券（2026-08-01）**。加性新增窗口重置券总览与幂等核销 API，不改变既有 token、额度和会员调用。 |