@acosmi/sdk-ts 2.19.6 → 2.20.0

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+## 2.20.0
+
+- **订阅双池展示契约（追加式，方案 D-14）**：`QuotaSummary` 新增两个可选字段，`ManagedModel` 新增一个可选字段，全部**纯类型面追加**，运行时代码零改动 —— `getQuotaSummary` / `listModels` 历来原样透传网关响应体，2.19.6 的调用方式一字不改仍然成立。
+  - `QuotaSummary.freePool?: QuotaSummaryFreePool` —— 付费合同随每个订阅周期自带的**精选免费池 F**：`quota` / `used` / `remaining`（**微 Credits**，÷1000 = Credits）、可选 `expiresAt`、`unit: 'MICRO_CREDIT'`、`eligibleModels: string[]`（池类 FREE ∪ 仍在限免期的 PROMO_FREE 的 model id，可以是空数组）。F 只能被这些模型先扣，用完后同一请求自动溢出扣付费池 P。**`subscriptionPool` 语义不变，恒为付费池 P。**
+  - `QuotaSummary.creditUnit?: 'OFFICIAL_CNY' | 'COST_CNY'`（导出类型 `QuotaSummaryCreditUnit`）—— 本响应所有 Credit 数值的计量口径：`OFFICIAL_CNY` = 新合同（1 Credit = ¥0.000001 官方价），`COST_CNY` = 老合同（成本口径）。
+  - `ManagedModel.freePoolEligible?: boolean` —— 该模型此刻是否有资格先扣 F，用于模型选择器的「精选」角标；限免到期会随时间翻转。
+- **缺席语义（三个字段都适用，不可当 0 / false 读）**：`freePool` 缺席 = 老合同（没有 F）**或**老网关（不认识 F）；`creditUnit` 缺席 = 老网关，不能默认成任一取值，尤其不能默认成 `OFFICIAL_CNY` 去乘 ¥ 单价；`freePoolEligible` 缺席 = 老网关，只在 `=== true` 时画角标。把缺席画成「精选额度 0 / 已用满」是在向老合同用户断言一件不存在的事。
+- **`freeTier` 保留原语义、退出展示分区职责**：`ManagedModel.freeTier` 仍是「PLAN:FREE 档 allowedModels 内」这一静态分类，字段与取值一字未动（老客户端零破坏）；文档注释改为明示「哪些模型先扣精选免费池」由 `freePoolEligible` 表达，两套集合可以不一致，新代码不要再用 `freeTier` 分区或打角标。`QuotaSummary` 的注释同步澄清：`freeTotalEtu` / `freeBuckets` 是 GENERIC 赠送桶，**不是** `freePool`，两者不可相加。
+- 新增跨语言契约 fixture：`test/fixtures/quota-summary.{two-pool,legacy}.json`（`GET /api/v4/entitlements/quota-summary` 完整响应体，以网关 `buildQuotaSummary` 当前实际产出的全部字段为底）与 `test/fixtures/managed-models.{two-pool,legacy}.json`（目录条目 `freePoolEligible` 的 true / false / 缺席三态），配套 `test/quota-summary.two-pool.test.ts`。Go / Rust SDK 持有同字节的副本，Go 网关与 CrabCode 以它为准。
+- 文档：README 更新历史与「当前版本」行（此前停在 2.19.5）同步到 2.20.0。
+
 ## 2.19.6
 
 - `QuotaSummarySubscriptionPool` 追加三个可选字段 `boosterRemaining?: number` / `boosterCount?: number` / `boosterNextExpiresAt?: string`，描述订阅池里由**加油包**贡献的那一部分：网关 `quota_summary.go` 在既有那一次 alive 遍历里，对 alive 的 COMMERCIAL 桶中 `sourceType === 'booster_pack'` 的行求和（`boosterRemaining`，单位同 `unit`，即**微 Credits**，÷1000 = Credits）、计数（`boosterCount`，一行 = 一个加油包）、并在这些 alive **限期**桶里选举最早到期时刻（`boosterNextExpiresAt`，ISO-8601）。加油包是「加总额度」的产品动作，与只清 5 小时 / 7 天窗口、对额度池零交互的**重置卡**是两笔账，展示端不得互相替代。

package/README.md

@@ -7,7 +7,7 @@
 ## 状态
 
 - **主实现 / 事实标准**：本 TS SDK 现为 Acosmi SDK 的主力实现。Go SDK [acosmi-sdk-go](https://github.com/acosmi/acosmi-sdk-go) 已暂停维护，待 TS 稳定后再从 TS 反向翻译补齐。
-- **当前版本：`2.19.5`**（流内重试提示透出 + 流式可选项，2026-09-19）。
+- **当前版本：`2.20.0`**（订阅双池展示契约：`QuotaSummary.freePool?` / `creditUnit?`、`ManagedModel.freePoolEligible?`，纯加法，2026-10-17）。
 - **`v2.19.1`**：可选 versioned 凭据存储、原子刷新与本地退出，支持将 HTTP / WebSocket 绑定到固定登录身份；外部凭据使用独立的 external 模式。所有模式仅在完整网关错误合同证明用户访问凭据失效且请求未接收时自动刷新重试，普通 401 原样返回。versioned 模式要求上游 metadata 的认证合同为 2、网关错误合同为 1；默认 legacy 存储接口继续可用。详见 [CHANGELOG](./CHANGELOG.md)。
 - **`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` 十路终止矩阵。
@@ -1194,7 +1194,8 @@ npm run docs    # 经 TypeDoc 生成 API 参考到 docs/api/
 
 | 版本 | 状态 | 概要 |
 | --- | --- | --- |
-| 2.19.6 | **当前版本** | **订阅池加油包份额（2026-09-20）**。`QuotaSummarySubscriptionPool` 加性新增 `boosterRemaining?` / `boosterCount?` / `boosterNextExpiresAt?`：网关在既有那一次 alive 遍历里，对 alive 的 COMMERCIAL 桶中 `sourceType === 'booster_pack'` 的行求和（微 Credits，÷1000 = Credits）、计数（一行 = 一个加油包）、并在这些 alive **限期**桶里选举最早到期时刻。**三者缺席 = 老网关或此刻没有加油包，都不可读成 0**（网关一行都认不出时三个键一起不下发，绝不写 0）；`boosterNextExpiresAt` 另可因「加油包全是永久桶」而单独缺席，此时前两个字段仍在场。加油包是「加总额度」的产品动作，与只清 5 小时 / 7 天窗口、对额度池零交互的重置卡是两笔账。纯类型面追加，无运行时改动。 |
+| 2.20.0 | **当前版本** | **订阅双池展示契约（2026-10-17，纯加法）**。`QuotaSummary` 加性新增 `freePool?: QuotaSummaryFreePool`（精选免费池 F：`quota` / `used` / `remaining` 微 Credits、可选 `expiresAt`、`unit: 'MICRO_CREDIT'`、`eligibleModels`）与 `creditUnit?: 'OFFICIAL_CNY' \| 'COST_CNY'`；`ManagedModel` 加性新增 `freePoolEligible?: boolean`。`subscriptionPool` 语义不变（= 付费池 P），`freeTier` 保留原语义但不再用于展示分区。**三个字段缺席都不可当 0 / false 读**（老合同没有 F、老网关不认识 F）。新增跨语言契约 fixture 与测试。详见 CHANGELOG。 |
+| 2.19.6 | 稳定版 | **订阅池加油包份额（2026-09-20）**。`QuotaSummarySubscriptionPool` 加性新增 `boosterRemaining?` / `boosterCount?` / `boosterNextExpiresAt?`：网关在既有那一次 alive 遍历里，对 alive 的 COMMERCIAL 桶中 `sourceType === 'booster_pack'` 的行求和（微 Credits，÷1000 = Credits）、计数（一行 = 一个加油包）、并在这些 alive **限期**桶里选举最早到期时刻。**三者缺席 = 老网关或此刻没有加油包，都不可读成 0**（网关一行都认不出时三个键一起不下发，绝不写 0）；`boosterNextExpiresAt` 另可因「加油包全是永久桶」而单独缺席，此时前两个字段仍在场。加油包是「加总额度」的产品动作，与只清 5 小时 / 7 天窗口、对额度池零交互的重置卡是两笔账。纯类型面追加，无运行时改动。 |
 | 2.19.5 | 稳定版 | **流内重试提示透出 + 流式可选项（2026-09-19）**。`StreamError` 加性新增 `serverRetryable`（帧上 `retryable` **原值**，不与 `requestDisposition` 合取 —— 合取会把「服务端明说可重试」与「服务端没说」压成同一个 `false`）与 `retryAfterSecs`（只收有限非负数，非法值一律 `undefined`）；加性导出结构判据 `isStreamError()`（worker / `vm` / 二次打包下 `instanceof` 静默为假）；`chatStream` / `chatMessagesStream` 新增**末位**可选实参 `ChatStreamOptions`（`requestTimeoutMs` 总时长安全网、`onResponseHeaders` 在 `resp.ok` 判断前交出响应头，用于读 `X-Acosmi-Stream-Keepalive` 等流控提示）。全部追加式；不传 `requestTimeoutMs` 时**不武装任何计时器**，流式链路行为与 2.19.4 逐字一致。另修 `FileTokenStore.withLock` 在 Windows delete-pending 窗口把 `EPERM` / `EBUSY` 当成致命错误（NT 在 `unlink` 之后、最后一个句柄关闭之前抛的不是 `EEXIST`，于是同一把锁上的一次正常交接被报成永久失败）；这两个码现在按「锁被占」退避重试并跳过 stale 检测，`EACCES` 刻意不收，非 Windows 平台控制流逐字节不变。 |
 | 2.19.4 | 稳定版 | **OpenAI 线流式 usage 尾帧回收 + 子路径入口修复 + 一批 wire 容错**。`stream_options.include_usage` 下上游在 `finish_reason` 帧之后才发 `{"choices":[],"usage":{...}}`，转换器此前丢弃一切不带 `choices` 的帧、且已在 `finish_reason` 帧上发出不带 usage 的 `message_delta` 与 `message_stop`，于是 OpenAI 线经 `chatMessagesStream` 的回合从来没有带过 usage、消费方一律记成 0；现在任何帧上的 usage 都被记录（后帧覆盖前帧）并写进 `message_stop` 前紧邻的那条 `message_delta`。内容块仍在 `finish_reason` 帧关闭，但尚未见到 usage 时 `message_delta` / `message_stop` 会等「带 usage 的帧 / `data: [DONE]` / body 结束」三者中最先到的一个，新增 `OpenAIStreamConverter.flush()` 在流末补发这次延迟收口（绝不为从未给过 `finish_reason` 的流伪造收口，也没有任何路径会发两次 `message_stop`）。流式 usage 映射与非流式逐字相同（`prompt_tokens`→`input_tokens`、`completion_tokens`→`output_tokens`），缓存 token 与 reasoning token 明细既不映射也不冲抵，缺失或非有限数一律省略而不是写 0。修复 `@acosmi/sdk-ts/adapters/openai` 与 `@acosmi/sdk-ts/adapters/anthropic` 两个子路径入口**加载即抛**（Node ESM / CJS 下 `OpenAIAdapter is not a constructor`、Bun 下 `undefined is not a constructor`）：`ProviderFormat` / `ProviderAdapter` 迁进不 import 任何 adapter 实现的叶子模块，各入口导出名一字不变；`test:pack` 现在会在各自全新的 Node 进程里对每个声明了 `import` 或 `require` 条件的 `exports` 子路径真加载一次。另容忍不带 `delta` 的流 `choice`、不带 `choices` 的非流式响应、不带 `usage` 的非流式响应（分别按空 delta / 空数组 / 0 处理，不再抛错，其余字段照常转换）；修正 text 先于 `reasoning_content` 到达时两个 `content_block_start` 都落在 index 0 的块序错乱。类型面加性新增 `WindowLimitStatus.fiveHourSoftContinuing?`、`WindowLimitStatus.inflightHeldCredits?`、`QuotaSummary.subscriptionPool?` —— 三者缺席都表示「旧网关没播报」，不得读成 `false` / `0`。 |
 | 2.19.3 | 稳定版 | **OpenAI 线网关流失败帧不再把自己撞崩**。网关用 `event: failed` 发结构化错误帧，而 `chatMessagesStream` 的 OpenAI 分支捕获了 SSE 事件名却从不读它，错误帧于是被送进 OpenAI chunk 转换器、死在 `chunk.choices.length` 上 —— 真实上游原因被一个无关的 TypeError 顶掉。该分支现在把 `failed` / `error` 帧交给既有的 `parseStreamError`，与 `chatStreamWithUsage` 早已在做的完全一致；`OpenAIStreamChunk.choices` 同版改为可选（类型声明必填而 wire 确实会省，正是那个 TypeError 的来处）。Anthropic 线零行为变化，请求构造零变化。 |