@acosmi/sdk-ts 2.4.0 → 2.5.1

package/CHANGELOG.md

@@ -5,6 +5,44 @@ 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.5.1] - 2026-05-31 — 模型 adapter 格式一致性护栏（行为加固 patch，向后兼容）
+
+`getAdapterForModel` 路由加固：`preferred_format` 现仅在**确被 `supported_formats` 收录**时才采信（或 `supported_formats` 未声明时维持原样）。防止上游元数据漂移（如 `preferred_format=anthropic` 但 `supported_formats=[openai]`）把 SDK 路由到模型并不支持的格式端点，撞 `/anthropic`「未绑定 Anthropic」4xx。这是网关侧「同 model_id 双 profile 选行」根因修复在 SDK 侧的同构护栏。
+
+### Changed
+
+- **`getAdapterForModel`**：决策顺序第 1 步由「`preferred_format` 非空即采信」收紧为「`preferred_format` 非空**且**该格式在 `supported_formats` 内（或 `supported_formats` 未声明）才采信」。`supported_formats` 为空/未知（旧上游）时行为逐字节不变（仍采信 `preferred_format`，再回落 provider 名硬编码）。新增 3 条 `test/adapters/routing.test.ts` 用例钉死矛盾场景。
+- 升级无需 review：仅当上游同时返回 `preferred_format` 与一个**不含该格式**的 `supported_formats` 时路由结果才改变（此前是错误路由，现纠正）。
+
+## [2.5.0] - 2026-05-31 — 源码健康度审计根因修复（additive minor，公开 API 零移除/零改名）
+
+逐文件源码 + 文档深度审计后的根因修复。主索引：`docs/audit/TS版SDK源码健康度与文档审计报告.md`（含 §0.5 前置核实修订与 live 生产实证）。**公开类型与方法签名零移除、零改名**；新增导出 `normalizeOverrideBaseURL` / `DEFAULT_API_TIMEOUT_MS` / `OpenAIStreamConverter`。
+
+### 重要澄清（推翻原审计 P1-1 误报）
+
+- **casehall / finance / enterprise 业务域路径未改，且经生产实证确认正确。** 它们带 `/api/...` 前缀、经 `apiURL()` 拼成 `/api/v4/api/...`（双 `/api`）是「同源代理直连 tk-dist」链路的**有意契约**（nginx `location /api/v4/api/casehall/` → tk-dist `:48080/api/casehall/*`），与后端控制器 `@RequestMapping` 逐字一致。`sign.zhonglvbao.com/api/v4/api/casehall/lawyer-credentials/my` 实测 401 可达；若按表面"去 /api"会落 404 破坏在产 casehall。新增 `test/business-domain-url.test.ts` 钉死全部业务域 URL 契约，防回归。
+- casehall 的 `listLawyers` 等 9 个 `/casehall/app|me/...` 方法对应**后端 consumer 端点尚未实现**，已加 `@experimental` JSDoc 诚实标注（调用会 404）。
+
+### Fixed
+
+- **`agentRuns.downloadArtifact()` 超限静默截断 → 抛错**：读 `maxDownloadSize + 1` 探测，超限抛 `download artifact: response exceeds NMB limit`（对齐 `downloadSkill`），不再把损坏的截断数据交给调用方。
+- **本地工具回调无硬超时 → `Promise.race` 硬超时**：`invokeLocalTool` 即使 handler 完全忽略 `ctx.signal` 也不会永挂，超时返回稳定失败结果；保留 `ctx.signal` 协作式取消。
+- **OpenAI 流式 `reasoning_content` 后直接 `tool_calls`（无 text）时 block index 错乱 → 修正**：新增 `thinkingBlockIndex` 记录 thinking 占用索引；tool_calls 新建 block 前镜像 text 分支先关 thinking 再递增；finish 按真实索引关闭。修 thinking/tool 撞 index 0 与错配 stop。
+- **非法 `expires_at` 被当未过期 → 视为过期**：`tokenSetIsExpired` 加 `Number.isFinite` 闸；`FileTokenStore`/`LocalStorageTokenStore` 的 `load()` 加 `isValidTokenSet` 形状校验（坏数据返回 `null` 而非带坏 token 继续）。
+- **OAuth 链路绕过注入 `fetchImpl` → 统一走注入 fetch**：`auth.ts` 的 discover/register/exchange/refresh/revoke helper 末位加可选 `fetchImpl`（默认全局 fetch，向后兼容），`Client` 全链路传 `this.fetchImpl`。自定义 fetch/代理/测试 mock/受限运行时现可覆盖全链路。
+- **空成功响应（204/空 body）抛 JSON parse error → 返回 `undefined`**：核心 `doJSONFullInternal` 与 `agentRuns.requestAPI` 对齐 compliance，空响应不再 `JSON.parse('')`。
+- **`apiBaseURL` / `complianceBaseURL` 缺校验 → 与 gateway base 同级校验**：新增 `normalizeOverrideBaseURL` 拒 ws/wss、空 host、query、hash。
+- **部分非流式请求无默认超时 → 套默认超时**：新增 `DEFAULT_API_TIMEOUT_MS`（60s）+ `Client.withRequestTimeout`；`agentRuns.requestAPI` 与 `compliance.executeJson` 在调用方未传 signal 时套组合超时（超时 + 用户 signal 任一 abort）。流式/下载路径保留长连接语义。
+- **WebSocket 重复 `connect` 泄漏旧连接 → 先关旧再建新**：`connect()` 开头若已有连接先 `disconnect()`，杜绝多个后台重连 loop / FD 泄漏。
+- **`FileTokenStore.save()` 注释承诺 fsync 但未实现 → 真 fsync**：`open → writeFile → fh.sync()（文件 fsync）→ close → rename → 目录 fsync（best-effort，跨平台不支持时吞错）`，兑现 durability 承诺，保留 atomic rename。
+- **chat 请求对象被原地 mutate → 内部浅 clone**：`chat`/`chatMessages*`/`chatStream*` 5 处入口浅 clone（`{...req, stream}`），sanitizer 改 clone 的 `rawMessages`，调用方传入的 `req` 零改动。
+- **Anthropic `extraBody` 能覆盖 SDK 管理字段 → denylist**：`thinking`/`effort`/`max_tokens`/`temperature`/`betas` 强制跳过并告警，保留透传非管理字段。
+- **`CompliancePollError` 不携带最后状态 → 填充 `lastInfo`**：`poll()` 各抛错点装入最后一次状态视图，便于排障。
+
+### Changed（文档）
+
+- README / 开发手册：版本归一到 2.5.0；`Invoice.taxNumber` → `taxId`（README + 手册）；finance 金额叙述改「`amountFen` 分单位整数 number」（钱包/展示类仍 json.Number string）；多端章节补浏览器 `localStorage` token + WebSocket query token 风险说明；开发手册 P0 红线改为「任何 namespace 新增/变更方法必须有 URL 组装测试」并新增「两条传输约定」专章 + provider 双状态枚举（大写 `ComplianceProviderRequestStatus` vs 小写 `ComplianceProviderStatus`）澄清。
+
 ## [2.4.0] - 2026-05-30 — `SkillStoreItem.skillMd?` 透出（additive minor，零回归）
 
 Additive minor，纯类型，无方法签名 / 运行时改动。修复**下游经 SDK 拿不到技能 SKILL.md 正文**：网关 `SkillStoreResponse` 早已返回 `skillMd`（`json:"skillMd,omitempty"`，`ToStoreResponse()` 已 map），但 SDK 的 `SkillStoreItem` 类型未声明该字段，导致 `getSkillDetail` / `resolveSkill` / `browseSkills` 的消费方（CrabCode）在类型层访问不到正文。

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 反向翻译补齐。
-- **当前 npm 版本：`2.1.0`**（远程控制 CrabCode 多接入面，2026-05-28）。
+- **当前 npm 版本：`2.5.1`**（模型 adapter 格式一致性护栏，2026-05-31）。
+- **`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 用例钉死矛盾场景。
+- **`v2.5.0`（健康度审计根因修复，2026-05-31）**：源码深度审计后修复一批真实运行时缺陷 —— `agentRuns.downloadArtifact()` 超限不再静默截断而是抛错；本地工具回调 `Promise.race` 硬超时（忽略 `signal` 的 handler 也不再永挂）；OpenAI 流式 `reasoning_content` 后直接 `tool_calls`（无 text）时 block index 不再错乱；非法 `expires_at` 视为过期 + TokenStore 形状校验；OAuth 发现/注册/换/吊销链路统一走注入 `fetchImpl`；空成功响应（204）不再抛 JSON parse error；`apiBaseURL`/`complianceBaseURL` 与 gateway base 同级校验（拒 ws/wss/query/hash）；非流式请求默认超时；WebSocket 重复 connect 先关旧连接；`FileTokenStore.save()` 真 fsync；chat 请求对象不再被原地 mutate；Anthropic `extraBody` 不能覆盖 SDK 管理字段。**公开类型/方法签名零移除、零改名**（新增导出 `normalizeOverrideBaseURL` / `DEFAULT_API_TIMEOUT_MS`）。casehall/finance/enterprise 业务域路径经生产实证确认正确（同源代理直连 tk-dist），**未改**，并新增 URL 组装回归测试钉死契约。
 - **`v2.1.0`（已发布）**：远程控制 CrabCode 多接入面 —— `serverURL`/`baseURL` Gateway URL 公共契约（见下方小节）、`agentRuns.createRemoteRun` / `agentRuns.streamRemoteControl` + 11 事件 union（见 §Agent Runs → 远程控制）、`chatbridge` 第三方聊天平台桥接类型（types-only 骨架，见 §Chat Bridge）、专用 `remote_control` scope（不进 `allScopes()`）。契约见 `docs/audit/sdk-remote-control-contract-2026-05-27.md`。
 - **v2.0.0 BREAKING（Phase 3 复核 + 全量根治，2026-05-25）摘要**：
   - SDK 同步主仓 9 commit 闭环 20 P0（RBAC 表达式统一 / PII 真落盘加密链 / K7 视频 webhook 幂等 / K8 OCR SSRF / K9 KYC main flow / admin 写端点错误码契约）。
@@ -30,7 +32,7 @@ v2.0.0 标 BREAKING，但 **TS SDK 公开类型与方法签名零移除、零改
 | 持有 `ROLE_ADMIN` 角色（不是 `platform_admin`）想读 PII L3 字段（如发票税号、律师执照号） | **必须 review** — 网关 `SensitiveSerializer` 不再把 `ROLE_ADMIN` 当 `platform_admin` 别名 fail-OPEN，统一收敛为 4 角色严格白名单。仍需 PII L3 read 的角色须重新申请 `platform_admin` | `docs/pii-role-matrix.md` |
 | 持有 admin 写端点 (`/admin/**/...`) 旧契约 — 期望 `200+{ok:false,code:xxx}` 业务错误码 | **必须改** — 改读 HTTP 状态码：`403` 鉴权不足 / `404` 资源不存在 / `501` `NOT_CONFIGURED_CODE` 网关未配置 provider；body 不再保证带业务码 | 主仓 `K10AdminController` |
 | 用 `client.casehall.*` / `client.enterprise.*` 调律师 / 企业 OWNER 资质相关接口 | **零改动** — 新增 `getMyLawyerCredentialStatus()` / `getMyEnterpriseKycStatus()` 是纯增量，不影响既有方法 | `src/casehall/client.ts`、`src/enterprise/client.ts` |
-| 读 `Invoice.taxNumber` / `Invoice.bankAccount` 等 PII 字段 | **零代码改动** — 字段名 / wire-format 不变，仅 Javadoc 标注从"脱敏"升级为"keyVersion v1/v2 真加密 + AAD field binding"，运行时 transparent | `src/finance/types.ts` |
+| 读 `Invoice.taxId` / `Invoice.bankAccount` 等 PII 字段 | **零代码改动** — 字段名 / wire-format 不变，仅 Javadoc 标注从"脱敏"升级为"keyVersion v1/v2 真加密 + AAD field binding"，运行时 transparent | `src/finance/types.ts` |
 | 集成 v1.x 时按"`ROLE_ADMIN` 自动当 `platform_admin`"测试用例 | **必须改** — 删掉别名假设；测试角色显式写 `platform_admin` / `s2s` / `lawyer` / `consumer` 之一 | `docs/pii-role-matrix.md` §角色映射表 |
 
 > v2.0.0 → v2.0.1 是纯 packaging fix（`package.json.files` 数组补 2 个 docs），无源码改动；从 v2.0.0 升 v2.0.1 不需要任何 review。
@@ -183,11 +185,13 @@ SDK 同时提供 **Anthropic + OpenAI 两条 endpoint**，**等地位**，对应
 
 路由由 `getAdapterForModel(model)` 按 ManagedModel 的 `preferred_format` / `supported_formats` 决策（wire-format 字段，snake_case 与上游 Go json tag 严格对齐；ManagedModel 上其余顶层字段如 `modelId` / `isEnabled` / `inputModalities` 走 camelCase，详见 `src/models/types.ts`）：
 
-1. `preferred_format` 非空 → 按值（`anthropic` | `openai`）
+1. `preferred_format` 非空 **且**该格式在 `supported_formats` 内（或 `supported_formats` 未声明）→ 按值（`anthropic` | `openai`）
 2. `supported_formats` 含 `anthropic` → AnthropicAdapter
 3. `supported_formats` 含 `openai` → OpenAIAdapter
 4. 两字段均空（旧上游）→ 按 `provider` 名回落
 
+> **格式一致性护栏（v2.5.1）**：第 1 步收紧后，`preferred_format` 与 `supported_formats` 矛盾时（如 `preferred_format=anthropic` 但 `supported_formats=[openai]`）不再盲信 `preferred_format`，而落到第 2/3 步按实际支持的格式选择，避免路由到模型并不支持的端点。`supported_formats` 未声明（旧上游）时 `preferred_format` 仍直接采信，向后兼容。
+
 `client.chat()` / `client.chatStream()` 内部自动调 `getAdapterForModel`，使用方无需关心。
 
 ## 多端
@@ -200,6 +204,10 @@ SDK 同时提供 **Anthropic + OpenAI 两条 endpoint**，**等地位**，对应
 
 构建产物：`dist/{node,browser}/` 各自 ESM + CJS + `.d.ts`，主入口约 120 KB。
 
+> **安全权衡（集成方必读）**：
+> - **浏览器 `LocalStorageTokenStore`**：token 落在 `localStorage`，受同源 XSS 威胁可被读取，且不随标签页关闭清除。仅在可接受该风险的场景使用；高安全场景应改用内存 store + 服务端 session/同源代理（Route Handler）持有 token。
+> - **Notifications WebSocket 把 token 放 URL query（`?token=`）**：query string 可能进入 nginx access log / 代理日志 / 浏览器历史。浏览器端 WebSocket 无法设自定义 header 是此设计的根因；Node 环境（`ws` 包支持 `options.headers`）应优先 header 或 `Sec-WebSocket-Protocol` 子协议承载 token，部署上需对 WS 端点关闭 query 日志。
+
 ## 流式
 
 ```ts
@@ -920,14 +928,16 @@ npm run docs    # 经 TypeDoc 生成 API 参考到 docs/api/
 
 | 版本 | 状态 | 概要 |
 | --- | --- | --- |
-| 2.4.0 | **当前稳定版（npm latest）** | **`SkillStoreItem.skillMd?` 透出（additive minor，2026-05-30）**。修复下游经 SDK 拿不到技能 SKILL.md 正文：网关 `SkillStoreResponse` 早已返回 `skillMd`（`ToStoreResponse()` 已 map），但 SDK `SkillStoreItem` 漏声明。新增可选 `skillMd?: string`（Anthropic SKILL.md 正文，仅 Detail/resolve/非 minimal browse 携带；`SkillStoreListItem` minimal 刻意不含正文）；`readme` 一并改为可选 `readme?`（匹配网关 `omitempty`）。零方法签名/运行时改动。下游 CrabCode 重锁 `@acosmi/sdk-ts@2.4.0` + `bun install --force` 生效；SKILL.md 为不可信用户内容，GUI 渲染须 sanitize + 展示 securityLevel/securityScore/certificationStatus。 |
+| 2.5.1 | **当前稳定版** | **模型 adapter 格式一致性护栏（2026-05-31）**。`getAdapterForModel` 路由加固：`preferred_format` 仅当被 `supported_formats` 收录（或 `supported_formats` 未声明）才采信，防止上游元数据漂移把 SDK 路由到模型不支持的格式端点（撞 `/anthropic` 4xx）。`supported_formats` 未声明（旧上游）时行为逐字节不变；新增 3 条 routing 用例。详见 CHANGELOG。 |
+| 2.5.0 | 稳定版 | **源码健康度审计根因修复（2026-05-31）**。修复一批真实运行时缺陷：`downloadArtifact()` 超限抛错（不再静默截断）/ 本地工具 `Promise.race` 硬超时 / OpenAI 流式 reasoning→tool_calls block index 修正 / 非法 `expires_at` 视为过期 + TokenStore 校验 / OAuth 链路走注入 `fetchImpl` / 空成功响应（204）不抛 parse error / `apiBaseURL`·`complianceBaseURL` 同级校验 / 非流式默认超时 / WS 重复 connect 关旧连接 / `FileTokenStore.save()` 真 fsync / chat 请求对象不被原地 mutate / Anthropic `extraBody` 不覆盖 SDK 管理字段 / `CompliancePollError` 携带最后状态。**公开类型/方法签名零移除、零改名**（新增导出 `normalizeOverrideBaseURL`·`DEFAULT_API_TIMEOUT_MS`）。casehall/finance/enterprise 路径经生产实证确认正确（同源代理直连 tk-dist）未改 + 新增 URL 组装回归测试。详见 CHANGELOG 与 `docs/audit/TS版SDK源码健康度与文档审计报告.md`。 |
+| 2.4.0 | 稳定版（npm latest） | **`SkillStoreItem.skillMd?` 透出（additive minor，2026-05-30）**。修复下游经 SDK 拿不到技能 SKILL.md 正文：网关 `SkillStoreResponse` 早已返回 `skillMd`（`ToStoreResponse()` 已 map），但 SDK `SkillStoreItem` 漏声明。新增可选 `skillMd?: string`（Anthropic SKILL.md 正文，仅 Detail/resolve/非 minimal browse 携带；`SkillStoreListItem` minimal 刻意不含正文）；`readme` 一并改为可选 `readme?`（匹配网关 `omitempty`）。零方法签名/运行时改动。下游 CrabCode 重锁 `@acosmi/sdk-ts@2.4.0` + `bun install --force` 生效；SKILL.md 为不可信用户内容，GUI 渲染须 sanitize + 展示 securityLevel/securityScore/certificationStatus。 |
 | 2.3.0 | 稳定版 | **`apiBaseURL` 可配置网关 base（additive，2026-05-30）**。新增可选 client 配置项，让浏览器侧 `/api/v4` 网关调用（managed-model / agent-run / casehall）可经同源代理转发，规避非网关同源域名（如 `sign.zhonglvbao.com`）下 acosmi.com 对带 `Origin` 跨域浏览器请求的 403。公开类型 / 方法签名零移除、零改名（additive minor）。 |
 | 2.2.1 | 稳定版 | **README 字段名修正（docs-only patch，2026-05-29）**。修复 v2.2.0 README 示例把能力字段误写为 camelCase（`supportsImageGeneration`）；正确为 wire snake_case `capabilities.supports_image_generation` / `supports_video_generation`（`listModels` 对 `capabilities` 对象原样透传）。补充：字段随 catalog 下发、可选（缺省 false）、无专用 catalog helper。无源码改动，从 2.2.0 升级无需 review。 |
 | 2.2.0 | 稳定版 | **托管模型图片/视频生成（2026-05-29）**。图片/视频生成与文本模型同属托管模型网关（同 `Client`、同 `models:chat` 鉴权面），仅 `capabilities.supports_image_generation` / `supports_video_generation` 的模型可用；计费结算在营销系统，SDK / 网关只负责调用与用量上报。新增 `client.generateImage(modelID, req, signal?)`（同步，`POST /managed-models/:id/images/generations`）/ `client.generateVideo(modelID, req, signal?)`（建异步任务，返回 `taskId`）/ `client.pollVideoTask(modelID, taskID, durationSeconds?, signal?)`（轮询，`durationSeconds` 透传给网关在 `completed` 时上报视频秒数）；新增 `ImageGenerationRequest`/`ImageGenerationResponse`/`VideoGenerationRequest`/`VideoTaskResponse` 类型 + `ModelCapabilities.supports_image_generation`/`supports_video_generation` 标志（wire snake_case，`capabilities` 对象透传不归一化）。网关适配 OpenAI 兼容图片 + 火山引擎（即梦/豆包）视频 + DashScope 通义万相（wanx）原生异步任务（图片+视频）。公开类型 / 方法签名零移除、零改名（additive minor）。 |
 | 2.1.0 | 稳定版 | **远程控制 CrabCode 多接入面（2026-05-28）**。`serverURL`/`baseURL`/`baseUrl` Gateway URL 公共契约 + `normalizeGatewayBaseURL`（仅 http/https，拒 ws/wss）；`agentRuns.createRemoteRun` / `streamRemoteControl` + 11 事件 `RemoteControlEvent` union + `parseRemoteControlEvent` / `isTerminalRemoteEvent`；`AdapterKind`(6) / `RunnerKind`(3) / `PermissionPolicy` / `WorkspacePolicy`；专用 `remote_control` scope（不进 `allScopes()`，`remoteControlScopes()`）；`chatbridge` 第三方聊天平台类型骨架（types-only，无 client 方法，Phase 7B 后端落地）；`subscription.getPlanByCode`。wire 约定按平面分（远控 snake_case + 毫秒整数 / chatbridge camelCase，契约 §12-§14）。公开类型 / 方法签名零移除、零改名（additive minor）。 |
 | 2.0.1 | 稳定版 | **Packaging fix — 纯发布元数据，无源码改动**。`package.json.files` 数组补 `docs/pii-role-matrix.md` + `docs/开发与发布手册.md` 两项，让 v2.0.0 引入的 PII 角色矩阵与开发手册随 npm tarball 一并下发。从 v2.0.0 升级到 v2.0.1 无需任何 review。 |
 | 2.0.0 | **BREAKING** | **Phase 3 复核 + 全量根治（2026-05-25）**。主仓 9 commit 闭环 20 P0（RBAC 表达式统一 / PII 真落盘加密链 / K7 视频 webhook 幂等 / K8 OCR SSRF / K9 KYC main flow / admin 写端点错误码契约）。**SDK 同步**：新增 `casehall.getMyLawyerCredentialStatus()` + `enterprise.getMyEnterpriseKycStatus()` 律师/企业 OWNER 自查端点；`finance/types.ts` P2-016 PII Javadoc 升级（含 `keyVersion` v1/v2 payload 协议）；新建 `docs/pii-role-matrix.md`（4 角色 × 3 PII 级矩阵）；admin 写端点错误码改 HTTP 状态码语义（`200+{ok:false}` → `403/404/501`）。**升级指引详见 §"v2.0.0 升级指引"**。SDK 公开类型 / 方法签名零移除、零改名；BREAKING 范围在网关后端契约。 |
-| 1.9.0 | 稳定版 | **finance 域落地（商品化总规划 P7）**。新增 `client.finance.*`：`listMyInvoices` / `requestInvoice` / `listMyRefunds` / `requestRefund` / `listMyCorporateTransfers` / `initiateCorporateTransfer` / `uploadCorporateTransferProof`（决策 14/15 + R12）。发票 / 退款 / 对公转账三条业务线全量接入；金额一律用 string（json.Number 端口，避免 JS 浮点损失）。 |
+| 1.9.0 | 稳定版 | **finance 域落地（商品化总规划 P7）**。新增 `client.finance.*`：`listMyInvoices` / `requestInvoice` / `listMyRefunds` / `requestRefund` / `listMyCorporateTransfers` / `initiateCorporateTransfer` / `uploadCorporateTransferProof`（决策 14/15 + R12）。发票 / 退款 / 对公转账三条业务线全量接入；finance 金额用 `amountFen` **分单位整数 `number`**（如 `amountFen` / `taxAmountFen` / `requestedAmountFen`），2^53 内无浮点风险（≈90 万亿元），与钱包/展示类的 json.Number string 是不同约定。 |
 | 1.8.1 | 稳定版 | **enterprise 企业席位域落地（商品化总规划 P6a）**。新增 `client.enterprise.*`：`listMyEnterprises` / `getEnterprise` / `inviteMember` / `listEnterpriseMembers` / `listOrgSubscriptions` / `listSeats` / `assignSeat` / `revokeSeat` / `getOrgConsumeReport`。OWNER/ADMIN 权限下席位月度变更 ≤ 3 次（超出返 41xxx 业务码）；订阅 + 席位 + 用量报表三视图齐备。 |
 | 1.8.0 | 稳定版 | **casehall 法律案件咨询域落地（商品化总规划 P5 方案 B）**。新增 `client.casehall.*`：`listLawyers` / `getLawyer` / `submitCaseLead` / `listMyCaseLeads` / `getMyCases` / `bookConsultation` / `listMyConsultations` / `listMyLegalOrders` / `listLegalSKUs`。律师库公开端点（VERIFIED + ACTIVE，PII L3 已脱敏）+ 案件线索 + 咨询 + 5 LEGAL_SERVICE SKU；admin 板块 9 模块不在 SDK 边界。 |
 | 1.7.0 | 稳定版 | **subscription + pricing + products 三域落地（商品化总规划 P1-P4）**。`subscription`：`listPlans` / `listUserSubscriptions`（订阅档位 + 用户订阅）。`pricing`：`getPricingConfig` / `quoteCompliance`（公开业务参数 + csign 合规 SKU 报价）。`products`：`getProductBySlug` / `listProductsByFamily` / `listComplianceSkus` / `listPublicModels`（商品中心 productFamily / audience / billingMode 索引）。 |