@acosmi/sdk-ts 2.3.0 → 2.5.1

package/dist/node/{openai-xKHChcmG.d.cts → openai-B5xWiGMs.d.cts}

@@ -1,4 +1,4 @@
-import { P as ProviderAdapter, k as ProviderFormat, j as ModelCapabilities, e as ChatRequest, f as ChatResponse, n as StreamEvent } from './index-CI7FM3xe.cjs';
+import { P as ProviderAdapter, k as ProviderFormat, j as ModelCapabilities, e as ChatRequest, f as ChatResponse, n as StreamEvent } from './index-BdzF9tmA.cjs';
 
 /**
  * Anthropic 内容块
@@ -107,6 +107,9 @@ declare class OpenAIStreamConverter {
     private messageStarted;
     private thinkingStarted;
     private thinkingStopped;
+    /** thinking block 打开时占用的 Anthropic block index — 关闭时必须用它, 不能用
+     *  可能已被 text/tool 推进的 this.blockIndex (否则 content_block_stop 索引错配)。 */
+    private thinkingBlockIndex;
     private textStarted;
     /** OpenAI tool_call index → Anthropic block index */
     private toolBlockIndex;

package/dist/node/{openai-oeY7dGNW.d.ts → openai-C3DcaljC.d.ts}

@@ -1,4 +1,4 @@
-import { P as ProviderAdapter, k as ProviderFormat, j as ModelCapabilities, e as ChatRequest, f as ChatResponse, n as StreamEvent } from './index-CI7FM3xe.js';
+import { P as ProviderAdapter, k as ProviderFormat, j as ModelCapabilities, e as ChatRequest, f as ChatResponse, n as StreamEvent } from './index-BdzF9tmA.js';
 
 /**
  * Anthropic 内容块
@@ -107,6 +107,9 @@ declare class OpenAIStreamConverter {
     private messageStarted;
     private thinkingStarted;
     private thinkingStopped;
+    /** thinking block 打开时占用的 Anthropic block index — 关闭时必须用它, 不能用
+     *  可能已被 text/tool 推进的 this.blockIndex (否则 content_block_stop 索引错配)。 */
+    private thinkingBlockIndex;
     private textStarted;
     /** OpenAI tool_call index → Anthropic block index */
     private toolBlockIndex;

package/docs//345/274/200/345/217/221/344/270/216/345/217/221/345/270/203/346/211/213/345/206/214.md

@@ -10,7 +10,7 @@
 | 项目     | 值 |
 | -------- | -- |
 | 实现地位 | **主实现 / 事实标准**；Go SDK 暂停维护，后续从 TS 反向翻译 |
-| 当前版本 | **2.0.1**（packaging fix — `package.json.files` 数组补齐两个 docs；上游 v2.0.0 为 Phase 3 复核 + 全量根治 BREAKING，含商品化 P1-P7 namespace 全量 + 律师 / 企业 OWNER 自查端点 + PII 真落盘加密链 + admin 写端点 HTTP 错误码契约） |
+| 当前版本 | **2.5.1**（模型 adapter 格式一致性护栏，patch，2026-05-31；上游 2.1.0 远控 / 2.2.0 图片视频 / 2.3.0 `apiBaseURL` / 2.4.0 `skillMd?` / 2.5.0 健康度审计根因修复，详见 §14 与 CHANGELOG） |
 | 版本策略 | TS 独立演进；wire-format / API 不兼容变更升 major（v2.0.0 已发，见 §10 / §18） |
 | 主消费者 | `crabcode` (Anthropic 格式)、`crabdesign` / `crabclaw` 等下游产品 |
 | 长期保留 | `OpenAIAdapter` (P0 红线，`crabclaw` 暂不用 TS 但保留双格式等地位) |
@@ -150,7 +150,7 @@ TS 现为主实现，**文件级与 Go 1:1 对齐的约束已作废** —— `sr
 - ✅ **符号名跨语言一致** — 导出的类型 / 方法 / 错误名是 TS↔Go 对照锚点
 - ✅ **bug-for-bug 行为对齐**（e.g. retry POST=false 默认，sanitize thinking 硬豁免）
 - ✅ **ISO 8601 字符串时间** — 与 Go RFC3339 wire-compat
-- ✅ **string 表示金额 / json.Number 字段** — 避免 JS number 精度损失（金融安全）
+- ✅ **金额按域分两种约定** — ①钱包/展示类（如 `WalletStats.balance`）用 **json.Number string**（十进制元，避免 JS number 精度损失）；②finance 域（发票/退款/对公转账）用 **`amountFen` 分单位整数 `number`**（如 `amountFen`/`taxAmountFen`/`requestedAmountFen`，2^53 内无浮点风险）。**不要写"金额一律 string"**——会与 finance 实际类型矛盾
 - ✅ **双 adapter 等地位** — `AnthropicAdapter` + `OpenAIAdapter` P0 红线，不可降级
 - ✅ **已有端口代码的 "端口自 X.go" 溯源注释** — 历史对照保留；compliance、对外鉴权层等
   新域本就无 Go 对应物，不写该注释
@@ -219,7 +219,11 @@ git commit -m "fix: ..."
 - `test/compliance-scopes.test.ts` — **15 个** compliance scope 常量与 `complianceScopes()`（v1.3.0 首发 12 个 → v1.3.2 +`compliance:reports:write` → v1.5.0 S5 +`compliance:contract_template:{read,write}` 合计 15；含 `compliance:reports:publish` 等 step-up gated 写 scope）
 - `test/shared.test.ts` — v1.5 跨域共享 DTO：`PageResult` 别名等价 / retryAdvice reason 映射 / 叠加投影只读性 / `classifyComplianceError` 零回归红线 17 case
 
-> **v2.0.0 新方法测试位** — Phase 3 复核新增 `casehall.getMyLawyerCredentialStatus()` 与 `enterprise.getMyEnterpriseKycStatus()` 两个自查端点；wire-format 走既有 `doJSON` + `APIResponse` 路径，覆盖在 typecheck + smoke pack 层（无新业务红线，**不进 P0 必跑列表**）。若将来这两个端点的鉴权 / 字段策略发生变化，须在此列表追加显式测试。
+> **🔴 P0 红线（v2.5.0 修订）— 任何 namespace 新增/变更方法必须有「URL 组装测试」**：用注入捕获 `fetchImpl` 断言最终拼装出的 `method + path + query`。`typecheck` 与 `smoke pack` **既测不出路径错也测不出路径对**（它们只校验类型，不发请求），仅靠它们兜底会让路径级缺陷漏到生产。参见 `test/business-domain-url.test.ts`（已钉死 casehall/finance/enterprise 全部方法 URL）。
+>
+> ⚠️ **特别注意 casehall/finance/enterprise 的「双 `/api`」是有意契约，不是 bug**：它们经「同源代理直连 tk-dist」链路（nginx `location /api/v4/api/casehall/` → tk-dist `:48080/api/casehall/*`），SDK 传 `/api/...` 是对的，`apiURL()` 再拼 `/api/v4` 得 `/api/v4/api/...` 正确。详见下方「两条传输约定」。`test/business-domain-url.test.ts` 已断言 casehall.`getMyLawyerCredentialStatus` → `/api/v4/api/casehall/lawyer-credentials/my`，**任何"去掉 /api 的修正"都会让该测试失败并使生产 casehall 落 404**。
+>
+> （史）v2.0.0 新增的 `casehall.getMyLawyerCredentialStatus()` 与 `enterprise.getMyEnterpriseKycStatus()` 自查端点现已被上述 URL 组装测试覆盖。
 
 ### Agent Runs 公开 API 范围
 
@@ -299,6 +303,16 @@ git commit -m "fix: ..."
 从 v1.3.0 起，SDK 暴露 `client.compliance` 子客户端，覆盖时间章、电子证据、
 证据包、报告、合同签署 envelope、用印审批和 provider request 脱敏状态轮询。
 
+**🔑 两条传输约定（务必先读 —— 决定一个方法的 path 该不该带 `/api` 前缀）**
+
+SDK 的业务 path 经 `apiURL()` 统一前置 `/api/v4`。但后端有两类落点，对应两种 path 写法，**写错会 404 或反而"修对成 404"**：
+
+1. **网关反代的公开端点 → path 不带 `/api`**。例：`subscription`/`pricing`/`products` 用 `/distribution/public/...`。Go 网关（`nexus-v4` `routes_business.go` `registerDistributionPublicProxy`）匹配 `/api/v4/distribution/public/**`、`TrimPrefix("/api/v4")` 后转发到 tk-dist。**只有 `/distribution/public/**` 在网关注册**，其它 distribution/admin 子路径网关无路由。
+2. **直连 tk-dist 的同源代理端点 → path 带 `/api`（与后端控制器 `@RequestMapping("/api/...")` 逐字一致）**。例：`casehall.getMyLawyerCredentialStatus` 用 `/api/casehall/lawyer-credentials/my`、`finance.*` 用 `/api/distribution/finance/...`、`enterprise.*` 用 `/api/admin/...` 或 `/api/distribution/enterprise/kyc/...`。这些经消费域 nginx 的 **casehall 式直连规则**（`location /api/v4/api/casehall/ → http://127.0.0.1:48080/api/casehall/`，剥 `/api/v4` 直连 tk-dist `:48080`，与 `/admin-api` 同款）落地，最终 URL 出现「双 `/api`」(`/api/v4/api/...`) **是正确的**。
+   - 生产实证（2026-05-31）：`sign.zhonglvbao.com/api/v4/api/casehall/lawyer-credentials/my` → 401（可达，待鉴权）；去掉 `/api` 的 `…/api/v4/casehall/...` → 404。
+   - **新接入第 2 类业务方法时**：SDK 用后端控制器全 `/api/...` 路径，并在该方法的**消费部署域** nginx 补一条 casehall 式 `location /api/v4/api/<前缀>/ → :48080/api/<前缀>/`。**finance/enterprise 当前无前端消费**，路径已对、等接线时补 nginx 即可。
+   - casehall 的 `listLawyers`/`getMyCases` 等 `/casehall/app|me/...`（不带 `/api`）方法对应**后端 consumer 端点尚未实现**（已标 `@experimental`），调用会 404；不是 path 前缀问题，是下游后端缺失。
+
 **公开 API 边界**：
 
 - `Config.complianceBaseURL` 默认 `${serverURL}/admin-api`，不复用 `/api/v4`。
@@ -378,6 +392,7 @@ git commit -m "fix: ..."
   以编译期穷举强约束映射表不漏。
 - ✅ **`ProviderRequestStatus` 复用**既有 `ComplianceProviderRequestStatus`，
   不另造同名近似类型。
+  - ⚠️ **两个 provider status 概念并存，大小写不同，勿混用**：`ComplianceProviderRequestStatus`（`src/compliance/provider/types.ts`，**大写** `PENDING`/`SUCCESS`/`FAILED`/`UNKNOWN`/`RETRYING`，provider 单次请求视图）与 `ComplianceProviderStatus`（`src/compliance/status.ts`，**小写** `pending`/`success`/`failed`/`unknown`/`retrying`，前端计费/履约视图）。两者都导出且名字相近，调用方务必按字段来源选对大小写枚举。
 - ✅ **`IdempotencyKeyHeader`（`'Idempotency-Key'`）是写接口幂等键 header 的
   单一真相源**，新写接口一律引用该常量。
 
@@ -582,7 +597,7 @@ git push origin vX.Y.Z
 **实例 — v2.0.0（2026-05-25）**：商品化 P1-P7 Phase 3 复核后 SDK 首次 major bump。SDK 公开类型 / 方法签名零移除、零改名，但**网关后端契约 BREAKING**：
 1. `SensitiveSerializer` 取消 `ROLE_ADMIN` → `platform_admin` 别名 fail-OPEN，统一收敛为 4 角色严格白名单（`platform_admin` / `s2s` / `lawyer` / `consumer`），违反即返回脱敏值。
 2. admin 写端点错误码从 `200 + {ok:false, code}` 改为 HTTP 状态码（`403` 鉴权不足 / `404` 资源不存在 / `501` `NOT_CONFIGURED_CODE`）。
-3. PII 字段（如 `Invoice.taxNumber` / 律师执照号）落盘从"应用层脱敏"升级为"AES-GCM 真加密 + AAD field binding + `keyVersion` v1/v2 协议"，运行时 transparent，但消费方读取行为受 §1 角色严格化影响。
+3. PII 字段（如 `Invoice.taxId` / 律师执照号）落盘从"应用层脱敏"升级为"AES-GCM 真加密 + AAD field binding + `keyVersion` v1/v2 协议"，运行时 transparent，但消费方读取行为受 §1 角色严格化影响。
 
 **实例 — v2.0.1（2026-05-25）**：纯 packaging fix。`package.json.files` 数组补 `docs/pii-role-matrix.md` + `docs/开发与发布手册.md`，让 v2.0.0 引入的两个 docs 随 npm tarball 下发。无源码改动，从 v2.0.0 升级无需 review。教训：**任何 v.major.0 BREAKING 发版同时必须自查 `files` 数组**——见 §18 v2.0.0 复盘。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acosmi/sdk-ts",
-  "version": "2.3.0",
+  "version": "2.5.1",
   "description": "Acosmi TypeScript SDK：模型网关、Agent Run Gateway 与 Compliance（电子证据、时间章、报告、签署 envelope）统一客户端，支持浏览器 / Node ≥18 / Deno / Bun。",
   "type": "module",
   "main": "./dist/node/index.cjs",