@acosmi/sdk-ts 2.0.1 → 2.1.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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.1.0] - 2026-05-28 — 远程控制 CrabCode 多接入面
+
+Additive minor。公开类型 / 方法签名零移除、零改名。契约见 `docs/audit/sdk-remote-control-contract-2026-05-27.md`。
+
+### Added
+
+- **Acosmi Gateway URL 公共契约**：`serverURL` / `baseURL` / `baseUrl` 三别名 + `normalizeGatewayBaseURL()`（仅接受 `http`/`https`，拒绝 `ws`/`wss` 及空 host，规整尾斜杠）。详见 README §"Acosmi Gateway URL 公共契约"。
+- **远程控制（CrabCode remote-control）**，`agentRuns` 命名空间下、事件协议独立于旧 `stream`：
+  - `agentRuns.createRemoteRun(req, signal?)` — `req.runtime` 固定 `'crabcode_remote'`，`runner` + `adapter` 必填。
+  - `agentRuns.streamRemoteControl(runId, signal?)` — 无 options 参数；`error` 恒非终结、`done`/`settle` 终结、从不抛异常。
+  - 11 事件 `RemoteControlEvent` union + helper `parseRemoteControlEvent(raw)`（wire→强类型，未知 type 返回 `null`）/ `isTerminalRemoteEvent(ev)`。
+  - 枚举：`AdapterKind`（6）/ `RunnerKind`（3）/ `PermissionPolicy` / `WorkspacePolicy`。
+  - 专用 scope `remote_control`（+ 3 子 scope）：`remoteControlScopes()` / `ScopeRemoteControl`，**不进 `allScopes()`**，绝不复用 `models:chat` / `ai`。
+  - wire 约定按平面分（契约 §12）：远控平面 = snake_case + 时长整数毫秒（`approval_timeout_ms`）；唯一序列化出口 `RemoteSessionEvent.ToWire()`，跨语言金标 fixtures 护栏（`test/remote-control-wire-golden.test.ts` ⇄ 后端 `wire_golden.json`）。
+- **`chatbridge` 第三方聊天平台桥接类型骨架**（types-only，无 `client.chatBridge.*` 方法，Phase 7B 后端落地）：导出类型 + 守卫 `isPlatform` / `isRegion` / `isIntegrationStatus` / `isChannelInboundEvent` / `asCredentialRef`。资源视图平面 = camelCase；secret 只入上游 vault，公共面仅见 `CredentialRef` + fingerprint + 脱敏 metadata（契约 §16）。
+- `subscription.getPlanByCode(planCode, signal?)` — 按 `planCode` 精确取单个可售订阅计划（复用 `listPlans` 客户端过滤，未命中返回 `null`；deep-review §12.3）。
+
 ## [2.0.1] - 2026-05-25 — Packaging fix
 
 ### Fixed

package/README.md

@@ -6,11 +6,34 @@
 
 ## 状态
 
-- 主实现 / 事实标准：本 TS SDK 现为 Acosmi SDK 的主力实现。Go SDK [acosmi-sdk-go](https://github.com/acosmi/acosmi-sdk-go) 已暂停维护，待 TS 稳定后再从 TS 反向翻译补齐
-- 当前版本：**2.0.0**（Phase 3 复核 + 全量根治 BREAKING 升级，2026-05-25）。**Phase 3 复核**: 主仓 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 注释升级 (含 keyVersion v1/v2 payload 协议); 新建 `docs/pii-role-matrix.md` (4 角色 × 3 PII 级矩阵); admin 写端点错误码改 HTTP 状态码语义 (`200+{ok:false}` → `403/404/501`). **v1.x 历史**: 1.9.0 finance / 1.8.1 enterprise / 1.8.0 casehall / 1.7.0 csign+pricing / 1.6.0 endUserId+11min 保活. 详见 [CHANGELOG](./CHANGELOG.md).
-- 测试：发布前需通过 typecheck/lint/vitest/build/packed-tarball smoke (`npm run test:pack`)
-- API 参考文档：`npm run docs` 经 TypeDoc 生成到 `docs/api/`
-- 包链接：[npm](https://www.npmjs.com/package/@acosmi/sdk-ts) · [GitHub Releases](https://github.com/acosmi/sdk-ts/releases)
+- **主实现 / 事实标准**：本 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）。
+- **`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 写端点错误码契约）。
+  - 新增 `casehall.getMyLawyerCredentialStatus()` + `enterprise.getMyEnterpriseKycStatus()` 律师 / 企业 OWNER 自查端点（纯增量）。
+  - `finance/types.ts` P2-016 PII Javadoc 升级（含 `keyVersion` v1/v2 payload 协议 + 4 角色 × 3 PII 级矩阵）。
+  - 新建 `docs/pii-role-matrix.md`（4 角色：`platform_admin` / `s2s` / `lawyer` / `consumer`）。
+  - admin 写端点错误码改 HTTP 状态码语义（`200+{ok:false}` → `403/404/501`），上游契约整流。
+  - **升级路径详见下方 "v2.0.0 升级指引"**。
+- **v1.x 历史链**：1.9.0 finance / 1.8.1 enterprise / 1.8.0 casehall / 1.7.0 csign+pricing+products+subscription / 1.6.0 endUserId+11min 保活 / 1.5.x 跨域共享 DTO + Compliance S1-S6 rollup / 1.4.x 浏览器 Web OAuth / 1.3.x compliance SDK / 1.2.x InputModality / 1.1.x agentRuns / 1.0.x 包发布修复。详见 [CHANGELOG](./CHANGELOG.md)。
+- **测试**：发布前需通过 `typecheck` / `lint` / `vitest` / `build` / `test:pack`（packed-tarball consumer smoke）。
+- **API 参考文档**：`npm run docs`（TypeDoc）生成到 `docs/api/`。
+- **包链接**：[npm](https://www.npmjs.com/package/@acosmi/sdk-ts) · [GitHub Releases](https://github.com/acosmi/sdk-ts/releases)。
+
+### v2.0.0 升级指引
+
+v2.0.0 标 BREAKING，但 **TS SDK 公开类型与方法签名零移除、零改名**；BREAKING 范围在网关后端，集成方按以下清单核对：
+
+| 受影响场景 | 集成方动作 | 关联 |
+|------------|----------|------|
+| 持有 `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` |
+| 集成 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。
 
 ## 安装
 
@@ -23,7 +46,7 @@ npm install @acosmi/sdk-ts
 ```ts
 import { Client, allScopes } from '@acosmi/sdk-ts';
 
-const client = new Client({ serverURL: process.env.ACOSMI_SERVER_URL! });
+const client = new Client({ baseURL: process.env.ACOSMI_BASE_URL! });
 await client.login('My App', allScopes());
 
 const resp = await client.chat('claude-opus-4-7', {
@@ -34,6 +57,45 @@ const resp = await client.chat('claude-opus-4-7', {
 console.log(resp.content);
 ```
 
+### Acosmi Gateway URL — `serverURL` / `baseURL` 公共契约 (v2.1+)
+
+`Client` 配置中 `serverURL` / `baseURL` / `baseUrl` 三字段同语义、互为 alias，归一化后必须相等；任传其一即可，多写时 normalize 后冲突会立刻抛错。
+
+```ts
+// 推荐拼写
+const client = new Client({ baseURL: 'https://acosmi.com' });
+
+// 与历史 serverURL 完全等价
+const same = new Client({ serverURL: 'https://acosmi.com' });
+
+// 多写一致 OK; 不一致抛错
+new Client({ serverURL: 'https://a.example', baseURL: 'https://b.example' });
+// → Error: Acosmi Gateway URL conflict: …
+```
+
+**红线 (Phase 0 契约 §1-§2)** — Acosmi Gateway URL 是 `@acosmi/sdk-ts` 调 Acosmi nexus-v4 API 的根：
+
+- 只接受 `http:` / `https:`；`ws:` / `wss:` 是 CrabCode `--sdk-url` RemoteIO 会话通道，**不是** SDK gateway URL，传入立刻抛错。
+- agent-runs / managed-models / notifications WS / compliance 都从同一个 normalized base 派生；SDK 内部 `apiURL()` 自动追加 `/api/v4`，不会重复拼。
+- 不推荐 runtime mutate `client.serverURL`；多 base 用 per-instance Client cache（例如 `Map<normalizedGatewayURL, Promise<Client>>`）。
+- `complianceBaseURL` 是独立第二根地址，不被 `baseURL` alias 覆盖。
+
+公共 helper：
+
+```ts
+import { Client, normalizeGatewayBaseURL, DEFAULT_GATEWAY_BASE_URL } from '@acosmi/sdk-ts';
+
+normalizeGatewayBaseURL('https://gw.example/api/v4/'); // → 'https://gw.example/api/v4'
+normalizeGatewayBaseURL('wss://session.example');      // → throw: only allows http/https
+DEFAULT_GATEWAY_BASE_URL;                              // → 'https://acosmi.com'
+
+const c = new Client({ baseURL: 'https://gw.example' });
+c.getBaseURL();   // → 'https://gw.example'  (= c.getServerURL())
+c.apiURL('/agent-runs'); // → 'https://gw.example/api/v4/agent-runs'
+```
+
+详见 `docs/audit/sdk-remote-control-contract-2026-05-27.md`。
+
 ### 用户隔离 (v1.6.0+)
 
 `ChatRequest.endUserId` — 业务侧终端用户的稳定标识, **跨 provider 通用语义**, 不绑死 DeepSeek。SDK 自动按 wire-format 注入: OpenAI 顶层 `user_id` / Anthropic `metadata.user_id`; 网关侧校验并派生后送达上游, 命中三项隔离能力 (内容安全 / KV-cache / 调度)。
@@ -179,6 +241,75 @@ await client.agentRuns.cancel(run.runId); // safe to call from UI cancel buttons
 | `error` | 失败事件（`throwOnError:true` 默认会转 `AgentRunStreamError` 抛出） | `error.code`、`error.message`、`error.stage`、`error.retryable` |
 | `done` | 流终止 | `runId`、`status` |
 
+### 远程控制 — CrabCode remote-control（v2.1.0）
+
+远程控制是 Agent Run 的一个独立 runtime（`runtime: 'crabcode_remote'`），用于把 CrabCode 子进程的会话/工具/权限循环经服务端适配成 C 端可消费的事件流。它**不复用** `agentRuns.stream` 的旧事件 union，事件协议另成一套（契约 §4 的 11 事件）。
+
+```ts
+import { Client, remoteControlScopes } from '@acosmi/sdk-ts';
+
+const client = new Client({ baseURL: process.env.ACOSMI_BASE_URL! });
+// 远控是高风险 scope，不在 allScopes() 内，必须显式申请
+await client.login('CrabCode Remote', remoteControlScopes());
+
+const run = await client.agentRuns.createRemoteRun({
+  appId: 'crabcode',
+  input: '重构这个函数并跑测试',
+  runtime: 'crabcode_remote', // 固定值
+  runner: 'cloud',            // 'cloud' | 'desktop' | 'local_embedded'
+  adapter: 'remote_io',       // 6 选 1，见下表
+  permissionPolicy: { shellAllowed: true, shellDenyList: ['rm', 'shutdown'], approvalTimeoutMs: 30_000 },
+  workspacePolicy: { readOnly: false, deniedPaths: ['/etc', '/root'] },
+});
+
+for await (const ev of client.agentRuns.streamRemoteControl(run.runId)) {
+  switch (ev.type) {
+    case 'text_delta':         process.stdout.write(ev.text); break;
+    case 'permission_request': /* 渲染审批卡片，回写 permission_result */ break;
+    case 'settle':             console.log('billed', ev.billed); break;
+  }
+}
+
+await client.agentRuns.cancel(run.runId); // UI 中止走服务端 cancel control frame，不是 fetch abort
+```
+
+要点：
+
+- **scope 隔离**：远控用专用 `remote_control` scope（服务端展开为 `remote_control:{agent-run,session-control,permission-response}` 三子项）；**绝不复用** `models:chat`/`ai`，且 `allScopes()` 不含它——桌面登录不会自动获得远控权限。用 `remoteControlScopes()` 或显式 `[...allScopes(), ScopeRemoteControl]`。
+- **adapter / runner**（`AdapterKind` / `RunnerKind`，契约 §3 placement 矩阵）：
+
+  | adapter | 适用 |
+  | --- | --- |
+  | `remote_io` | 单次纯会话流（CrabCode `--sdk-url` ws/wss） |
+  | `app_server_tcp_ws` | Desktop 已登录、本机 AppServer loopback RPC |
+  | `bridge_ccr` | 云端/托管 runner，session pool + heartbeat |
+  | `app_server_uds` / `stdio_stream_json` | 同机父子进程内嵌 |
+  | `tauri_managed_app_server` | Tauri native 托管 lifecycle |
+
+- **wire 约定（契约 §12-§14，按平面分）**：远控属 **snake_case 平面**——`permissionPolicy`/`workspacePolicy` 等 SDK camelCase 入参由 SDK 翻译为 snake_case wire（`shell_allowed`/`approval_timeout_ms`/`denied_paths`…）；时长一律**整数毫秒**（`approvalTimeoutMs`，禁 `time.Duration` 上 wire）。事件帧为**扁平信封**（`type`+`seq`+字段同级，snake_case），SDK 用 `parseRemoteControlEvent(raw)` 翻译为强类型 `RemoteControlEvent`。
+- **11 事件 union**（`RemoteControlEvent`，契约 §4）：`text_delta` / `reasoning_delta` / `tool_call` / `tool_result` / `permission_request` / `permission_result` / `usage` / `settle` / `status` / `error` / `done`。`error` **恒为非终结**（终结性错误由 `done.reason`/`done.finalStatus` 承载），`done` / `settle` 才终结流——故 `streamRemoteControl` 不接受 options、从不抛异常；用 `isTerminalRemoteEvent(ev)` 判终结。
+- **辅助导出**：`parseRemoteControlEvent` / `isTerminalRemoteEvent` / `AdapterKind` / `RunnerKind` / `RemoteControlEvent` / `RemoteSessionPlacement` / `PermissionPolicy` / `WorkspacePolicy`（`src/agent-runs/remote-control.ts`）。
+
+## Chat Bridge（第三方聊天平台桥接，v2.1.0 · types-only 骨架，无 client 方法，Phase 7B 后端落地）
+
+`chatbridge` 从根入口导出第三方聊天平台（飞书/企微/钉钉/Slack/Teams/Telegram/WhatsApp）接入 Acosmi 远控的**稳定类型契约**。Phase 7 仅交付类型骨架：**SDK 暂无 `client.chatBridge.*` 方法**，平台 webhook/凭证/桥接 handler 是 Phase 7B 后端工作；平台 SDK 依赖留在独立 adapter 包，不进主包。
+
+```ts
+import {
+  isPlatform, isRegion, isChannelInboundEvent, asCredentialRef,
+  type Platform, type ChatCredentialPublic, type ChannelInboundEvent,
+} from '@acosmi/sdk-ts';
+
+isPlatform('feishu');             // → true（7 平台枚举运行时守卫）
+asCredentialRef('cred_abc...');   // → branded CredentialRef（防 plaintext 误传）
+```
+
+边界（契约 §6 + §16）：
+
+- 平台 secret（bot token / signing key / AES key）**只入上游 credential vault**；SDK 公共面只见 `CredentialRef`（`cred_<base32>`）+ `fingerprint` + 脱敏 metadata，**永不**出现 ciphertext / plaintext（`ChatCredentialPublic` 编译期即无密文字段）。
+- **wire 平面**：chatbridge 资源视图走 nexus-v4 model-direct 序列化，字段为 **camelCase**（与 remote-control 的 snake_case 平面不同，详见契约 §12）。
+- 平台原始 thread / sender / workspace ID 一律 SHA256 hash 后入库（`threadHash`/`senderHash`）。
+
 ## 认证
 
 ### 浏览器内 / 自动 OAuth（推荐）
@@ -247,6 +378,8 @@ 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` |
 | **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` |
 | **Auth — 内置 Loopback OAuth** | `login`, `loginWithHandler`, `logout`, `ensureToken`, `forceRefresh`, `isAuthorized`, `getTokenSet` |
 | **Auth — 手动 OAuth 原语** | `discover`, `discoverWithProfile`, `register`, `authorize`, `exchangeCode`, `refreshToken`, `revokeToken`, `generateState` |
 | **Auth — 浏览器 Web OAuth (v1.4.0+)** | `discoverWebOAuthMetadata`, `registerWebOAuthClient`, `createWebAuthorizationRequest`, `completeWebAuthorizationRequest` |
@@ -260,7 +393,17 @@ const client = new Client({ serverURL: process.env.ACOSMI_SERVER_URL!, store: ne
 | **Notifications — WebSocket** | `connect`, `disconnect`, `isConnected` (实时推送订阅；浏览器走原生 WebSocket，Node 18-21 需自装 `ws`，Node 22+ 用原生) |
 | **Bug Report** | `submitBugReport`, `getBugReport`                                                  |
 | **Web Search** | `newWebSearchTool` (factory)                                                       |
-| **Compliance** | `compliance.createEvidenceAsset`, `compliance.issueTimestamp`, `compliance.waitForTimestampVerified`, `compliance.buildEvidencePackage`, `compliance.createReport`, `compliance.downloadReport`, `compliance.createSigningEnvelope`, `compliance.signEnvelope`, `compliance.getProviderRequest`, `compliance.waitForProviderRequestTerminal` |
+| **Subscription**（v1.7.0+） | `listPlans`, `listUserSubscriptions`                                       |
+| **Pricing**（v1.7.0+） | `getPricingConfig`, `quoteCompliance`                                            |
+| **Products**（v1.7.0+） | `getProductBySlug`, `listProductsByFamily`, `listComplianceSkus`, `listPublicModels` |
+| **Casehall — 法律案件**（v1.8.0+） | `listLawyers`, `getLawyer`, `submitCaseLead`, `listMyCaseLeads`, `getMyCases`, `bookConsultation`, `listMyConsultations`, `listMyLegalOrders`, `listLegalSKUs`, `getMyLawyerCredentialStatus`（v2.0.0+） |
+| **Enterprise — 企业席位**（v1.8.1+） | `listMyEnterprises`, `getEnterprise`, `inviteMember`, `listEnterpriseMembers`, `listOrgSubscriptions`, `listSeats`, `assignSeat`, `revokeSeat`, `getOrgConsumeReport`, `getMyEnterpriseKycStatus`（v2.0.0+） |
+| **Finance — 财务**（v1.9.0+） | `listMyInvoices`, `requestInvoice`, `listMyRefunds`, `requestRefund`, `listMyCorporateTransfers`, `initiateCorporateTransfer`, `uploadCorporateTransferProof` |
+| **Compliance — 证据 / 章戳 / 公开验真** | `compliance.createEvidenceAsset`, `compliance.getEvidenceAsset`, `compliance.verifyEvidencePublic`（匿名公开验真，v1.3.2+）, `compliance.issueTimestamp`, `compliance.issueTimestampForAsset`, `compliance.getTimestamp`, `compliance.verifyTimestamp`, `compliance.waitForTimestampVerified`, `compliance.buildEvidencePackage` |
+| **Compliance — 报告** | `compliance.createReport`（写，带 `Idempotency-Key`）, `compliance.getReport`, `compliance.publishReport`（step-up + 写）, `compliance.downloadReport` |
+| **Compliance — 签署 envelope** | `compliance.createSigningEnvelope`（写）, `compliance.getSigningEnvelope`, `compliance.signEnvelope`（step-up + gate + 写）, `compliance.createH5SigningUrl`（step-up + gate + 写）, `compliance.syncSigningEnvelopeStatus`（写） |
+| **Compliance — 用印审批** | `compliance.submitSealApproval`（写）, `compliance.approveSealApproval`（step-up + 写）, `compliance.rejectSealApproval`（写）, `compliance.cancelSealApproval`（写）, `compliance.listPendingSealApprovals`, `compliance.getSealApproval` |
+| **Compliance — Provider Request** | `compliance.getProviderRequest`, `compliance.waitForProviderRequestTerminal`, `compliance.classifyError` |
 | **Compliance — 分页列表** | `compliance.listEvidenceAssets`, `compliance.listTimestamps`, `compliance.listEvidencePackages`, `compliance.listReports`, `compliance.listSigningEnvelopes`, `compliance.listSealApprovals`, `compliance.listSealUses`（均返回 `PageResult<T>`） |
 | **Compliance — 能力与操作投影** | `compliance.getCapabilities`, `compliance.getFeatureGate`, `compliance.listOperations`, `compliance.getOperation` |
 | **Compliance — TSA 只读视图** | `compliance.listTsaProviders`, `compliance.getTsaStats` |
@@ -537,68 +680,103 @@ PII / 合同原文 / storage bucket+key / subject snapshot / provider raw / TSA
 
 ### 完整 API 列表
 
+标注约定：
+- `// 写` — POST / PUT / DELETE 写操作，**必传 `Idempotency-Key`**（即第二参数 `options?: ComplianceWriteOptions` 的 `idempotencyKey` 字段）；写操作不自动 retry，401 不 refresh + replay
+- `// step-up` — 需 OAuth token 升级等级；失败抛 `BusinessError` 含 code `1031000013`，调用方按 `classifyComplianceError` 分支引导用户重新 introspection
+- `// gate` — 受 capability gate 控制，未闭合时 fail-closed；先用 `getCapabilities` / `getFeatureGate` 探测
+- `// 分页` — 走 `GET .../page` 返回 `PageResult<T>`（`{ total, list }`）
+- 无标注 — GET 读路径，单次 401 refresh 重试
+
+#### 证据资产（evidence）
+
 ```ts
-client.compliance.createEvidenceAsset(req, options?)
+client.compliance.createEvidenceAsset(req, options?)        // 写
 client.compliance.getEvidenceAsset(id, signal?)
-client.compliance.verifyEvidencePublic(req, signal?)
-client.compliance.listEvidenceAssets(req?, signal?)        // 分页 → PageResult
-client.compliance.listEvidencePackages(req?, signal?)      // 分页 → PageResult
+client.compliance.verifyEvidencePublic(req, signal?)        // 匿名公开验真（未 login 不抛 not-authorized）
+client.compliance.listEvidenceAssets(req?, signal?)         // 分页
+client.compliance.listEvidencePackages(req?, signal?)       // 分页
+client.compliance.buildEvidencePackage(assetId, timestampTokenId?, options?)  // 写
+```
+
+#### 时间章（timestamp）
 
-client.compliance.issueTimestamp(req, options?)
-client.compliance.issueTimestampForAsset(assetId, options?)
+```ts
+client.compliance.issueTimestamp(req, options?)                       // 写
+client.compliance.issueTimestampForAsset(assetId, options?)           // 写
 client.compliance.getTimestamp(id, signal?)
-client.compliance.verifyTimestamp(req, options?)
+client.compliance.verifyTimestamp(req, options?)                      // 写（远端 verify 落审计）
 client.compliance.waitForTimestampVerified(id, opts?)
-client.compliance.listTimestamps(req?, signal?)            // 分页 → PageResult
+client.compliance.listTimestamps(req?, signal?)                       // 分页
+client.compliance.listTsaProviders(signal?)                           // TSA provider 只读列表
+client.compliance.getTsaStats(signal?)                                // 时间章统计只读视图
+```
 
-client.compliance.buildEvidencePackage(assetId, timestampTokenId?, options?)
+#### 出证报告（report）
 
-client.compliance.createReport(req, options?)    // 需 compliance:reports:write
+```ts
+client.compliance.createReport(req, options?)               // 写，需 compliance:reports:write
 client.compliance.getReport(id, signal?)
-client.compliance.publishReport(id, options?)    // step-up
-client.compliance.downloadReport(id, signal?)    // 离线复核 hash 视图
-client.compliance.listReports(req?, signal?)               // 分页 → PageResult
+client.compliance.publishReport(id, options?)               // 写 + step-up
+client.compliance.downloadReport(id, signal?)               // 离线复核 hash 视图
+client.compliance.listReports(req?, signal?)                // 分页
+```
 
-client.compliance.createSigningEnvelope(req, options?)
+#### 签署 envelope
+
+```ts
+client.compliance.createSigningEnvelope(req, options?)                 // 写
 client.compliance.getSigningEnvelope(envelopeId, signal?)
-client.compliance.signEnvelope(envelopeId, req, options?)            // step-up + gate
-client.compliance.createH5SigningUrl(envelopeId, req, options?)      // step-up + gate
-client.compliance.syncSigningEnvelopeStatus(envelopeId, options?)
-client.compliance.listSigningEnvelopes(req?, signal?)      // 分页 → PageResult
-client.compliance.listEnvelopeContracts(envelopeId, signal?)         // 合同列表（数组）
-client.compliance.listEnvelopeProviderRequests(envelopeId, signal?)  // provider 请求列表（数组）
-client.compliance.voidEnvelope(envelopeId, req, options?)            // 作废 envelope（写）
-
-client.compliance.submitSealApproval(req, options?)
-client.compliance.approveSealApproval(id, query, options?) // step-up
-client.compliance.rejectSealApproval(id, query, options?)
-client.compliance.cancelSealApproval(id, query, options?)
+client.compliance.signEnvelope(envelopeId, req, options?)              // 写 + step-up + gate
+client.compliance.createH5SigningUrl(envelopeId, req, options?)        // 写 + step-up + gate
+client.compliance.syncSigningEnvelopeStatus(envelopeId, options?)      // 写
+client.compliance.listSigningEnvelopes(req?, signal?)                  // 分页
+client.compliance.listEnvelopeContracts(envelopeId, signal?)           // 合同列表（数组，非 PageResult）
+client.compliance.listEnvelopeProviderRequests(envelopeId, signal?)    // provider 请求列表（数组，非 PageResult）
+client.compliance.voidEnvelope(envelopeId, req, options?)              // 写
+```
+
+#### 用印审批（seal approval / seal use）
+
+```ts
+client.compliance.submitSealApproval(req, options?)         // 写
+client.compliance.approveSealApproval(id, query, options?)  // 写 + step-up
+client.compliance.rejectSealApproval(id, query, options?)   // 写
+client.compliance.cancelSealApproval(id, query, options?)   // 写
 client.compliance.listPendingSealApprovals(signal?)
 client.compliance.getSealApproval(id, signal?)
-client.compliance.listSealApprovals(req?, signal?)         // 分页 → PageResult
-client.compliance.listSealUses(req?, signal?)              // 用印执行分页 → PageResult
+client.compliance.listSealApprovals(req?, signal?)          // 分页
+client.compliance.listSealUses(req?, signal?)               // 分页（用印执行）
+```
+
+#### Provider request 状态轮询
 
+```ts
 client.compliance.getProviderRequest(id, signal?)
 client.compliance.waitForProviderRequestTerminal(id, opts?)
+```
+
+#### 能力闸门 / 操作投影
+
+```ts
+client.compliance.getCapabilities(signal?)                  // 能力闸门列表（拿不到必须 fail-closed）
+client.compliance.getFeatureGate(action, signal?)           // 单动作能力（便捷，一次网络请求）
+client.compliance.listOperations(req?, signal?)             // 分页（操作投影）
+client.compliance.getOperation(id, signal?)
+client.compliance.classifyError(err)                        // BusinessError → ComplianceErrorInfo | null（同顶层 classifyComplianceError，便于 catch 块链式调用）
+```
 
-client.compliance.getCapabilities(signal?)                 // 能力闸门列表
-client.compliance.getFeatureGate(action, signal?)          // 单动作能力（便捷，一次网络请求）
-client.compliance.listOperations(req?, signal?)            // 操作投影分页 → PageResult
-client.compliance.getOperation(id, signal?)                // 操作投影详情
-client.compliance.classifyError(err)                       // BusinessError → ComplianceErrorInfo | null（同顶层 classifyComplianceError，便于在 catch 块上链式调用）
-
-client.compliance.listTsaProviders(signal?)                // TSA provider 只读列表
-client.compliance.getTsaStats(signal?)                     // 时间章统计只读视图
-
-client.compliance.createContractTemplate(req, options?)              // 创建合同模板（DRAFT）
-client.compliance.updateContractTemplate(id, req, options?)          // 更新模板（仅 DRAFT）
-client.compliance.deleteContractTemplate(id, options?)               // 删除模板（仅 DRAFT）
-client.compliance.getContractTemplate(id, signal?)                   // 模板详情
-client.compliance.listContractTemplates(req?, signal?)               // 模板分页 → PageResult
-client.compliance.uploadContractTemplatePdf(id, req, options?)       // 上传 PDF（base64）
-client.compliance.publishContractTemplate(id, options?)              // DRAFT → PUBLISHED
-client.compliance.archiveContractTemplate(id, options?)              // PUBLISHED → ARCHIVED
-client.compliance.listContractTemplateVersions(id, signal?)          // 版本快照列表（数组）
+#### 合同模板（contract template，v1.5.0 S5）
+
+```ts
+client.compliance.createContractTemplate(req, options?)               // 写，DRAFT
+client.compliance.updateContractTemplate(id, req, options?)           // 写（仅 DRAFT）
+client.compliance.deleteContractTemplate(id, options?)                // 写（仅 DRAFT）
+client.compliance.getContractTemplate(id, signal?)                    // 模板详情
+client.compliance.listContractTemplates(req?, signal?)                // 分页
+client.compliance.uploadContractTemplatePdf(id, req, options?)        // 写（上传 PDF base64）
+client.compliance.publishContractTemplate(id, options?)               // 写，DRAFT → PUBLISHED
+client.compliance.archiveContractTemplate(id, options?)               // 写，PUBLISHED → ARCHIVED
+client.compliance.listContractTemplateVersions(id, signal?)           // 版本快照列表（数组）
 ```
 
 > 6 个 `list*` 分页方法（compliance gateway S1）均走 `GET .../page`，返回
@@ -683,7 +861,15 @@ npm run docs    # 经 TypeDoc 生成 API 参考到 docs/api/
 
 | 版本 | 状态 | 概要 |
 | --- | --- | --- |
-| 1.5.1 | 当前稳定版 | **Docs / examples / 源码注释全量复核与修订 — 无 API 变化**。修补 8 项漂移与遗漏：README API 总览补 25+ 漏列方法（Chat 内部方法、Auth 浏览器 Web OAuth 4 原语、Skills/Notifications/Entitlements/Packages 全量、WS `connect/disconnect/isConnected`）；重写 §"手动 OAuth" 段对齐 `auth.ts` 真实签名；§"双格式红线" + 三个 chat 示例 `maxTokens` → snake_case `max_tokens`；错误表补 `ModelNotFoundError`；§Agent Runs 补 13 类 stream event 完整表；新增 §`sanitize` 命名空间小节；`docs/compliance.md` 6 处 `Since v1.6/.../1.10` 统一为 `v1.5.0 (originally planned as ...)`；手册 §7 scope 数 12 → 15 + 新增 S1-S6 rollup 段；`examples/compliance-evidence-timestamp.ts` 补 `ScopeComplianceReportsWrite`（v1.3.2 漂移生产 401 隐患）；`examples/auth-oauth-flow.ts` + `examples/core-chat.ts` 注释对齐当前契约；`src/index.ts` + `src/browser.ts` + `src/auth/auth.ts` 注释从 Go-port 语义改为"TS 主实现 + Web OAuth 替代品"。`typecheck` / `lint` / `vitest`(214) / `build` / `test:pack` 全绿。 |
+| 2.1.0 | **当前稳定版（npm latest）** | **远程控制 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.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 索引）。 |
+| 1.6.0 | 稳定版 | `ChatRequest.endUserId` 业务侧终端用户稳定标识，跨 provider 通用语义；SDK 自动按 wire-format 注入（OpenAI 顶层 `user_id` / Anthropic `metadata.user_id`）；不传时网关从认证身份 HMAC-SHA256 自动派生 32 字符 id。`validateEndUserId(s)` helper 校验 PII / 长度 / 字符集。SSE keep-alive + 11 分钟超时调优；网关侧命中三项隔离能力（内容安全 / KV-cache / 调度）。 |
+| 1.5.1 | 历史稳定版 | **Docs / examples / 源码注释全量复核与修订 — 无 API 变化**。修补 8 项漂移与遗漏：README API 总览补 25+ 漏列方法（Chat 内部方法、Auth 浏览器 Web OAuth 4 原语、Skills/Notifications/Entitlements/Packages 全量、WS `connect/disconnect/isConnected`）；重写 §"手动 OAuth" 段对齐 `auth.ts` 真实签名；§"双格式红线" + 三个 chat 示例 `maxTokens` → snake_case `max_tokens`；错误表补 `ModelNotFoundError`；§Agent Runs 补 13 类 stream event 完整表；新增 §`sanitize` 命名空间小节；`docs/compliance.md` 6 处 `Since v1.6/.../1.10` 统一为 `v1.5.0 (originally planned as ...)`；手册 §7 scope 数 12 → 15 + 新增 S1-S6 rollup 段；`examples/compliance-evidence-timestamp.ts` 补 `ScopeComplianceReportsWrite`（v1.3.2 漂移生产 401 隐患）；`examples/auth-oauth-flow.ts` + `examples/core-chat.ts` 注释对齐当前契约；`src/index.ts` + `src/browser.ts` + `src/auth/auth.ts` 注释从 Go-port 语义改为"TS 主实现 + Web OAuth 替代品"。`typecheck` / `lint` / `vitest`(214) / `build` / `test:pack` 全绿。 |
 | 1.5.0 | 稳定版 | 沉淀 `src/shared/` 跨域共享 DTO（`PageRequest`/`PageResult` 别名、`OperationId`/`OperationStatus`/`IdempotencyKeyHeader`、`RetryAdvice` 叠加层、`PrincipalRef`/`TenantRef`、`FeatureGateStatus`/`StepUpStatus`/`BillingPreflightResult`）。**同时全量 rollup compliance gateway S1-S6** 能力（原 1.6.0-1.11.0 roadmap，见 [CHANGELOG.md](./CHANGELOG.md)）：S1 6 个分页列表、S2 capabilities + operations 投影、S3 TSA 只读视图、S4 envelope 收尾 + void、S5 合同模板全生命周期 + 2 新 scope（`compliance:contract_template:{read,write}`）、S6 用印执行分页（`listSealUses`）。当前 compliance scope 总数 **15** 个（`complianceScopes()` 返回）。纯增量；8 个平台控制面占位命名空间仍待后端契约就绪后落地。 |
 | 1.4.2 | 稳定版 | `src/` 从扁平 36 文件按业务域重组为 per-domain 目录；公共导出符号集合、`exports`、`dist/` 路径一字未变（纯内部重组）。新增 TypeDoc API 文档。 |
 | 1.4.1 | 稳定版 | 新增 `Config.browserRefreshMode` / `refreshProxyURL`——浏览器 Web OAuth token 刷新策略（规避 issuer CORS 403）。 |