@acosmi/sdk-ts 1.4.2 → 1.5.1

package/CHANGELOG.md

@@ -9,6 +9,184 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.5.1] — 2026-05-23
+
+> **Docs / examples patch — 无 API 变化**。对 README、`docs/compliance.md`、`docs/开发与发布手册.md`、`examples/`、源码注释做全量复核与修订，消除发现的 8 项漂移与遗漏。无 runtime 行为变更、无新增/移除导出符号、无 wire-format 变化；`typecheck` / `lint` / `vitest`(214) / `build` / `test:pack` 全绿。
+
+### Changed — README.md
+
+- 补全 API 总览表 25+ 漏列方法：`chatMessages` / `chatMessagesStream` / `buildChatRequest` / `loginWithHandler` / `isAuthorized` / `getTokenSet` / 浏览器 Web OAuth 4 原语 / `discoverWithProfile` / `register` / `revokeToken` / `generateState` / `ensureModelCached` / `browseSkillStore` / `getSkillSummary` / `certifySkill` / `getCertificationStatus` / `markAllNotificationsRead` / `deleteNotification` / `unregisterDevice` / `updateNotificationPreference` / WS `connect`/`disconnect`/`isConnected` / `listConsumeRecords` / `invalidateCoefficientCache` / `getTokenPackageDetail` / `listMyOrders` / `Client.create`。
+- 修复 §"双格式红线" 把 `preferredFormat` / `supportedFormats` 错写为 camelCase 的描述——`ManagedModel` 上这两个字段是 snake_case wire 字段；同步说明 `modelId` / `isEnabled` / `inputModalities` 等顶层走 camelCase。
+- 修复 Quick Start / 流式 / Web Search 三个示例的 `ChatRequest` 字段：`maxTokens` → `max_tokens`（与 `src/models/types.ts:ChatRequest.max_tokens` 对齐）。
+- 重写 §"手动 OAuth" 段：`register/authorize/exchangeCode` 全部按 `src/auth/auth.ts` 真实签名重写——`register` 不接 scopes / `authorize` 需 `reg.client_id`+`handler:` 而非 `onEvent:`、返回 `{ result, verifier }` / `exchangeCode` 需 5 个位置参数含 `result.redirectURI` + `verifier`；指向 `examples/auth-oauth-flow.ts` 完整示例；加浏览器 Web OAuth 替代品指引。
+- §错误处理表补 `ModelNotFoundError`（`chat` / `ensureModelCached` listModels 自动刷新后仍未命中）；为既有 `NetworkError` / `StreamError` / `CompliancePollError` 补字段细节。
+- §Agent Runs 段补 `AgentRunStreamEvent` 完整 13 类事件表（`run_started` / `status` / `text_delta` / `reasoning_delta` / `tool_call` / `tool_result` / `local_tool_request` / `artifact` / `sources` / `usage` / `settle` / `error` / `done`）。
+- 新增 §`sanitize` 命名空间小节：列 `client.setDefensiveSanitize` / `setAutoStripEphemeralHistory` / `applyRequestSanitizers` 三个 mixin 方法 + `sanitize.sanitize` / `dropBlocks` / `stripEphemeral` + 17 个 `Block*` 常量 + `MinimalSanitizeConfig` 字段（`maxMessagesTurns` / `permanentDenyBlocks` / `maxImageBytes` / `maxVideoBytes` / `maxPDFBytes`）+ thinking 块硬豁免红线。
+- §历史表 1.5.0 行补"compliance gateway S1-S6 全量 rollup + scope 总数 15"说明。
+
+### Changed — docs/compliance.md
+
+- 6 处版本号漂移修订：`Since v1.6.0 / 1.7.0 / 1.8.0 / 1.9.0 / 1.10.0` + `Contract-template scopes (added in v1.10.0)` → 统一为 `v1.5.0 (originally planned as v1.X.0 — see CHANGELOG §"SN：..."`，避免消费者误以为这些方法在未来版本才有。
+
+### Changed — docs/开发与发布手册.md
+
+- §7 必测清单：`test/compliance-scopes.test.ts — 12 个` → `15 个`，附 12 → 13（v1.3.2）→ 15（v1.5.0 S5）演进注解。
+- §7 新增"Compliance gateway S1-S6 rollup（v1.5.0）"小节，逐 S 列出新增 25+ SDK 方法、对应后端 G1-G6、新增 scope 与 fail-closed 红线。
+
+### Changed — examples/
+
+- `examples/compliance-evidence-timestamp.ts` 补 `ScopeComplianceReportsWrite`（`createReport` 自 v1.3.2 起改用独立 write scope；过去用 `ScopeComplianceReportsRead` 在生产会 401）。
+- `examples/auth-oauth-flow.ts` 顶部注释指向 v1.4.0+ Web OAuth 原语（`discoverWebOAuthMetadata` / `registerWebOAuthClient` / `createWebAuthorizationRequest` / `completeWebAuthorizationRequest`）+ `Config.browserRefreshMode` / `refreshProxyURL` (v1.4.1+) CORS 规避方案。
+- `examples/core-chat.ts` 顶部注释把 `preferredFormat` / `supportedFormats` 改回 snake_case；补 `ChatRequest` snake_case wire / `ManagedModel` 顶层 camelCase 字段命名说明。
+
+### Changed — 源码注释（无 runtime 影响）
+
+- `src/index.ts` 顶部注释从"端口源 acosmi-sdk-go v0.19.0 (一字不差对齐)"改为"自 2026-05-22 起 TS 是主实现 / 事实标准"，与 README §状态 + 手册 §1 / §10 一致。
+- `src/browser.ts` 顶部注释加 v1.4.0+ Web OAuth 替代品 + v1.4.1+ `browserRefreshMode` 指引。
+- `src/auth/auth.ts` 顶部 + `authorize()` doc：从"浏览器侧应自行实现 popup window"改为指向同文件内 Web OAuth 原语。
+- `docs/api/`（TypeDoc 生成）已同步重生成。
+
+### Verified
+
+- `typecheck`：0 errors
+- `vitest`：17 files / **214 tests passed**
+- `npm pack --dry-run`：tarball 内容无变化
+- 跨语言契约印记（snake_case wire / 双 adapter 等地位 / bug-for-bug 行为）零回归
+
+---
+
+## [1.5.0] — 2026-05-23
+
+> 众律宝 SaaS 工作台 SDK / 后端能力缺口总账（`docs/audit/saas-sdk-backend-capability-gap-register-2026-05-22`）
+> **compliance gateway S1–S6 全量 + Phase 0.3/0.5 共享 DTO**：在 `client.compliance.*`
+> 上新增 22 个方法、2 个新 scope，沉淀 `src/shared/` 跨域共享原语，对接已合并的
+> 后端 **G1–G6** 契约。**纯增量、向后兼容**——不改任何既有导出符号的签名或行为；
+> `tenant` / `iam` / `apiClients` / `operations` / `audit` / `gateway` / `mcp` /
+> `certification` 8 个占位命名空间继续维持 `export {}`；`typecheck` / `lint` /
+> `vitest`(168) / `build` / `test:pack` / `docs` 全绿。
+>
+> 历史注记：本仓库内部 1.5.0/1.6.0/1.7.0/1.8.0/1.9.0/1.10.0/1.11.0 七个内部版本
+> 已合并为单一 1.5.0 发布（1.11.0 已 npm unpublish，留作历史尘埃）。
+
+### Added — Phase 0.3 / 0.5：跨域共享 DTO（原 1.5.0 / 缺口总账 §9.4 / §9.5）
+
+- **`src/shared/` 跨域共享 DTO**——为平台控制面 / `compliance.list*` 等命名空间提供
+  统一原语，按关注点分文件：
+  - `shared/pagination.ts` — `PageRequest`、`SortDirection`，以及 **`PageResult<T>`**
+    （刻意做成既有 `YudaoPageResult<T>` 的别名，不引入第二套 `{list,total}` 结构）。
+  - `shared/operation.ts` — `OperationId` / `OperationSource` / `OperationStatus` /
+    `VerifyStatus` / `IdempotencyKey` 类型与 `IdempotencyKeyHeader` 常量
+    （`'Idempotency-Key'`，写接口幂等键 header 单一真相源）；`ProviderRequestStatus`
+    **复用**既有 `ComplianceProviderRequestStatus`，不另造同名近似类型。
+  - `shared/retry-advice.ts` — `RetryAdvice` 统一失败补救模型 + `RetryAdviceReason`
+    （11 项）+ `retryReasonForComplianceKey()` / `retryReasonForOAuthError()`
+    映射函数 + `complianceErrorToRetryAdvice()` 叠加投影。**叠加层**——独立类型，
+    不修改也不替换 `core/retry.ts` `RetryPolicy` 与 `compliance/errors.ts`
+    `ComplianceErrorInfo`。
+  - `shared/principal.ts` — `PrincipalRef` / `TenantRef` / `ApiClientRef` 轻量引用。
+  - `shared/gate.ts` — `FeatureGateStatus` / `FeatureGateState` / `StepUpStatus` /
+    `GateQuota` / `BillingPreflightResult`（gate / capability / step-up / preflight
+    查询形态）。
+- `test/shared.test.ts` — 17 个契约测试，覆盖别名等价 / 幂等键常量 / reason 映射 /
+  叠加投影只读性 / `classifyComplianceError` 零回归红线。
+
+### Added — S1：6 个分页列表（原 1.6.0 / U-1 / 后端 G1）
+
+- **`client.compliance.list*` 6 个分页列表读方法**——对接后端 G1 的 6 个 `GET .../page`
+  端点，均返回 yudao `PageResult<T>`：
+  - `listEvidenceAssets(req?, signal?)` — `GET /compliance/evidence/assets/page`，
+    过滤项 `assetType` / `status` / `createTimeStart` / `createTimeEnd`。
+  - `listTimestamps(req?, signal?)` — `GET /compliance/timestamps/page`，过滤项
+    `provider` / `verificationStatus` / `createTimeStart` / `createTimeEnd`。
+  - `listEvidencePackages(req?, signal?)` — `GET /compliance/evidence/packages/page`。
+  - `listReports(req?, signal?)` — `GET /compliance/reports/page`。
+  - `listSigningEnvelopes(req?, signal?)` — `GET /compliance/signing-envelopes/page`。
+  - `listSealApprovals(req?, signal?)` — `GET /compliance/seal-approvals/page`。
+- **6 个 `*PageItem` + 6 个 `List*Request` 类型**——按子域归位；所有 `List*Request`
+  继承共享 `PageRequest`。`*PageItem` 是详情视图的 SDK-safe 子集 + `createTime`，
+  不含 provider raw / 证书 / storage / 合同原文。
+
+### Added — S2：capabilities + operations 投影（原 1.7.0 / U-5/U-6 / 后端 G2）
+
+- **`client.compliance.getCapabilities(signal?)`** — `GET /compliance/capabilities`，
+  返回 `ComplianceCapability[]`。后端 G2 为每个高风险 / 收费动作返回闸门视图：
+  `executable` / `state` / `requiredScopes` / `requiredStepUp` / `reason`。
+  调用方在高风险动作执行【前】查询做门控，拿不到能力时必须 fail-closed。
+- **`client.compliance.getFeatureGate(action, signal?)`** — 便捷方法（每次调用一次
+  网络请求，多个动作请改用 `getCapabilities` 一次取回本地查表）。
+- **`client.compliance.listOperations(req?, signal?)`** — `GET /compliance/operations/page`，
+  返回 `PageResult<OperationPageItem>`。
+- **`client.compliance.getOperation(id, signal?)`** — `GET /compliance/operations/{id}`
+  （数值行主键，非 `operationId` 幂等键），返回 `OperationDetail`。
+- **新增 `compliance/operation/` 子域类型**：`ComplianceCapability` / `OperationPageItem` /
+  `OperationDetail` / `ListOperationsRequest`。
+
+### Added — S3：TSA readonly 视图（原 1.8.0 / U-7 / 后端 G3）
+
+- **`client.compliance.listTsaProviders(signal?)`** — `GET /compliance/timestamps/providers`，
+  返回 `TsaProvider[]`，每个 provider：`name` / `environment` / `available`。
+- **`client.compliance.getTsaStats(signal?)`** — `GET /compliance/timestamps/stats`，
+  返回 `TsaStats`：总数 + 按校验状态分桶计数。
+- **新增 `compliance/timestamp/` 子域类型**：`TsaProvider` / `TsaStats`。
+
+### Added — S4：envelope 收尾 + void（原 1.9.0 / U-10/U-12 子集 / 后端 G4）
+
+- **`client.compliance.listEnvelopeContracts(envelopeId, signal?)`** — `GET
+  /compliance/signing-envelopes/{id}/contracts`，返回 `EnvelopeContractItem[]`。
+- **`client.compliance.listEnvelopeProviderRequests(envelopeId, signal?)`** — `GET
+  /compliance/signing-envelopes/{id}/provider-requests`，返回 `OperationPageItem[]`
+  （**复用**操作投影类型）。
+- **`client.compliance.voidEnvelope(envelopeId, req, options?)`** — `POST
+  /compliance/signing-envelopes/{id}/void`，**写方法**：`Idempotency-Key`、不重试、
+  `401` 不刷新重放。`VoidEnvelopeRequest = { reason: string }`。
+- **新增 `compliance/signing/` 子域类型**：`EnvelopeContractItem` / `VoidEnvelopeRequest`。
+
+### Added — S5：合同模板（原 1.10.0 / U-2 / 后端 G5）
+
+- **9 个合同模板方法**：
+  - `createContractTemplate` (POST，DRAFT 初始)
+  - `updateContractTemplate` (POST，仅 DRAFT)
+  - `deleteContractTemplate` (POST，仅 DRAFT)
+  - `getContractTemplate` (GET)
+  - `listContractTemplates` (GET 分页)
+  - `uploadContractTemplatePdf` (POST `{ pdfBase64 }`)
+  - `publishContractTemplate` (POST，DRAFT → PUBLISHED，版本快照固化)
+  - `archiveContractTemplate` (POST，PUBLISHED → ARCHIVED)
+  - `listContractTemplateVersions` (GET，普通数组)
+- **新增 `compliance/template/` 子域类型**：`ContractTemplateField` /
+  `ContractTemplateFieldType` / `ContractTemplateResp` / `ContractTemplatePageItem` /
+  `ContractTemplateStatus` / `ContractTemplateVersion` / `CreateContractTemplateRequest` /
+  `UpdateContractTemplateRequest` / `UploadContractTemplatePdfRequest` /
+  `ListContractTemplatesRequest`。
+- **新增 2 个 scope 常量**：`ScopeComplianceContractTemplateRead`
+  (`compliance:contract_template:read`) / `ScopeComplianceContractTemplateWrite`
+  (`compliance:contract_template:write`)。`ComplianceScope` 联合与 `complianceScopes()`
+  总数 13 → 15。读方法要求 `:read`、写方法要求 `:write`；不要求 step-up。
+
+### Added — S6：用印执行记录（原 1.11.0 / U-4 / 后端 G6）
+
+- **`client.compliance.listSealUses(req?, signal?)`** — `GET /compliance/seal-uses/page`，
+  返回 `PageResult<SealUsePageItem>`，过滤支持 `sealId` / `envelopeId` /
+  `usageStatus` / `createTimeStart` / `createTimeEnd`。一次 seal use 描述
+  envelope / contract / seal / 审批联动后【真正调用 provider 落章】的那一笔记录，
+  与 envelope 领域状态正交。SDK-safe——不含 provider raw payload / 证书 / storage key。
+- **新增 2 个 compliance 领域类型**（`src/compliance/seal-approval/types.ts`）：
+  `SealUsePageItem` / `ListSealUsesRequest`。
+- **Scope 复用**：复用既有 `ScopeComplianceContractSigningRead`
+  (`compliance:contract_signing:read`) ——后端 G6 端点声明同一 read scope，不新增 scope。
+
+### Unchanged
+
+- **印章授权 / 印章 CRUD（U-3 / U-11）**：仍为后端推迟项（CFCA 私有 jar / W3 闸门），
+  本版本不引入 SDK 方法。
+- **envelope send / remind / authorize / download / token** 等动作：后端 G4 范围之外
+  暂缓，本版本不暴露对应 SDK 方法。
+
+> Method Status：本次新增 22 个方法均为 `production-ready`（compliance gateway
+> S1–S6 / G1–G6 契约、端点、DTO、SDK 测试、文档全部闭环）。无 `gated` 方法。
+
+---
+
 ## [1.4.2] — 2026-05-22
 
 > `src/` 目录按业务域重组（实施计划 `docs/audit/sdk-ts-directory-restructure-plan-2026-05-22`）。

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 反向翻译补齐
-- 当前版本：**1.3.2**（`verifyEvidencePublic` 匿名公开验真收口、新增 `compliance:reports:write` scope、compliance 方法状态四档分级；`1.3.0` 新增 `client.compliance`、`complianceBaseURL`、合规域 types/errors/status/scopes、示例与文档；详见 [CHANGELOG](./CHANGELOG.md)）
+- 当前版本：**1.5.1**（文档 / examples / 源码注释全量复核与修订——补 25+ 漏列 API、修 OAuth/Chat 示例签名漂移、`docs/compliance.md` 6 处版本号统一为 1.5.0、`examples/compliance-evidence-timestamp.ts` 补 `compliance:reports:write` scope；无 API / wire-format 变化）。`1.5.0` 沉淀 `src/shared/` 跨域共享 DTO + compliance gateway S1-S6 全量 rollup；`1.4.2` `src/` 按业务域重组；`1.4.x` 浏览器 Web OAuth；`1.3.x` `client.compliance` 合规域客户端；详见 [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)
@@ -28,7 +28,7 @@ await client.login('My App', allScopes());
 
 const resp = await client.chat('claude-opus-4-7', {
   messages: [{ role: 'user', content: 'Hello' }],
-  maxTokens: 1024,
+  max_tokens: 1024, // ChatRequest 走 snake_case wire 字段（与上游 Go json tag 对齐）
 });
 console.log(resp.content);
 ```
@@ -42,12 +42,12 @@ SDK 同时提供 **Anthropic + OpenAI 两条 endpoint**，**等地位**，对应
 | `AnthropicAdapter` | `POST /managed-models/:id/anthropic`  | Anthropic 原生格式（含 thinking 等）|
 | `OpenAIAdapter`    | `POST /managed-models/:id/chat`       | OpenAI 兼容格式（DeepSeek/GLM 等）  |
 
-路由由 `getAdapterForModel(model)` 按 ManagedModel 的 `preferredFormat` / `supportedFormats` 决策：
+路由由 `getAdapterForModel(model)` 按 ManagedModel 的 `preferred_format` / `supported_formats` 决策（wire-format 字段，snake_case 与上游 Go json tag 严格对齐；ManagedModel 上其余顶层字段如 `modelId` / `isEnabled` / `inputModalities` 走 camelCase，详见 `src/models/types.ts`）：
 
-1. `preferredFormat` 非空 → 按值（`anthropic` | `openai`）
-2. `supportedFormats` 含 `anthropic` → AnthropicAdapter
-3. `supportedFormats` 含 `openai` → OpenAIAdapter
-4. 两字段均空（旧上游）→ 按 provider 名回落
+1. `preferred_format` 非空 → 按值（`anthropic` | `openai`）
+2. `supported_formats` 含 `anthropic` → AnthropicAdapter
+3. `supported_formats` 含 `openai` → OpenAIAdapter
+4. 两字段均空（旧上游）→ 按 `provider` 名回落
 
 `client.chat()` / `client.chatStream()` 内部自动调 `getAdapterForModel`，使用方无需关心。
 
@@ -66,7 +66,7 @@ SDK 同时提供 **Anthropic + OpenAI 两条 endpoint**，**等地位**，对应
 ```ts
 const stream = client.chatStream('claude-opus-4-7', {
   messages: [{ role: 'user', content: '写一首诗' }],
-  maxTokens: 1024,
+  max_tokens: 1024,
 });
 
 for await (const ev of stream) {
@@ -142,6 +142,24 @@ await client.agentRuns.cancel(run.runId); // safe to call from UI cancel buttons
 
 `stream(runId)` 支持 durable replay：断线后重新连接同一个 run，会先回放已持久化的 Agent Run SSE 事件，再继续消费运行中的事件。`usage` / `settle` 事件会暴露 `exact`、`cacheReadTokens`、`cacheCreateTokens` 等字段，便于下游展示真实结算状态。
 
+**`AgentRunStreamEvent` 完整事件类型**（union，详见 `src/agent-runs/types.ts`；上面示例只演示了 4 种常见分支）：
+
+| `type` | 触发 / 含义 | 关键字段 |
+| --- | --- | --- |
+| `run_started` | 流首事件，确认服务端已开始执行 | `runId`、`sessionId` |
+| `status` | 任务粗粒度状态变化 | `status` (`queued`/`running`/`completed`/`failed`/`cancelled`)、`message?` |
+| `text_delta` | 主要文本输出增量 | `text` |
+| `reasoning_delta` | 推理 / 思考过程增量（debug 用，不一定向终端用户展示） | `text` |
+| `tool_call` | Agent 发起内置 / 网关工具调用 | `id`、`name`、`input?` |
+| `tool_result` | 内置 / 网关工具调用结果 | `id`、`name?`、`result?`、`error?` |
+| `local_tool_request` | Agent 请求宿主提供本地只读工具结果，宿主须用 `submitLocalToolResult` 回填 | `requestId`、`name`、`input` |
+| `artifact` | 产出文件（图片 / 代码 / 文档等）；用 `downloadArtifact(runId, artifact.id)` 下载 | `artifact: AgentRunArtifact` |
+| `sources` | 网络检索 / RAG 来源信息 | `sources` |
+| `usage` | provider/ADK 透传的 token usage | `usage.exact`、`inputTokens`、`outputTokens`、`totalTokens`、`cacheReadTokens`、`cacheCreateTokens` |
+| `settle` | 服务端结算事件 | `settlement.status`、`tokenRemaining`、`callRemaining`、`exact`、`retryQueued` |
+| `error` | 失败事件（`throwOnError:true` 默认会转 `AgentRunStreamError` 抛出） | `error.code`、`error.message`、`error.stage`、`error.retryable` |
+| `done` | 流终止 | `runId`、`status` |
+
 ## 认证
 
 ### 浏览器内 / 自动 OAuth（推荐）
@@ -153,17 +171,45 @@ const token = await client.ensureToken();      // 拿到当前有效 access toke
 
 ### 手动 OAuth（CLI / 自定义流程）
 
+底层 helper 适用于自管 token 的 CLI / 自定义授权 UI。**大多数场景直接用 `client.login(appName, scopes)` 即可**——它内部封装了下面全部步骤。完整可运行示例见 [`examples/auth-oauth-flow.ts`](./examples/auth-oauth-flow.ts)。
+
 ```ts
-import { discover, register, authorize, exchangeCode } from '@acosmi/sdk-ts';
+import {
+  discover,           // RFC 8414 元数据发现
+  register,           // RFC 7591 动态客户端注册
+  authorize,          // 本地 loopback PKCE（仅 Node）
+  exchangeCode,       // code + verifier → token
+  refreshToken,       // 续期
+  newTokenSet,        // 把 TokenResponse 包成可持久化 TokenSet
+  FileTokenStore,
+  allScopes,
+} from '@acosmi/sdk-ts';
 
 const meta = await discover(process.env.ACOSMI_SERVER_URL!);
-const reg = await register(meta, 'My CLI', allScopes());
-const result = await authorize(meta, reg, allScopes(), {
-  onEvent: (ev) => console.log(ev.type, ev.url),
+const reg = await register(meta, 'My CLI');            // 不接 scopes 参数
+const scopes = allScopes();
+
+// authorize 返回 { result, verifier }，result.code + result.redirectURI 给 exchangeCode
+const { result, verifier } = await authorize(meta, reg.client_id, scopes, {
+  handler: (ev) => {
+    if (ev.type === 'auth_url') console.log('open in browser:', ev.url);
+  },
 });
-const tokens = await exchangeCode(meta, reg, result.code, result.codeVerifier);
+
+const tokenResp = await exchangeCode(
+  meta,
+  reg.client_id,
+  result.code,
+  result.redirectURI,      // 来自 authorize 返回；不是手动构造的 redirect_uri
+  verifier,                 // 来自 authorize 返回；不是 result.* 上的字段
+);
+
+const tokens = newTokenSet(tokenResp, reg.client_id, process.env.ACOSMI_SERVER_URL!);
+await new FileTokenStore('./tokens.json').save(tokens);
 ```
 
+> 浏览器侧（无法启 loopback HTTP server）请改用 v1.4.0+ Web OAuth 原语 `discoverWebOAuthMetadata` + `registerWebOAuthClient` + `createWebAuthorizationRequest` + `completeWebAuthorizationRequest`，由调用方实现 popup / 同窗口 redirect handler，SDK 负责 PKCE / state 校验 / token 兑换。
+
 ### Token 持久化
 
 ```ts
@@ -179,22 +225,80 @@ const client = new Client({ serverURL: process.env.ACOSMI_SERVER_URL!, store: ne
 
 | 模块         | 主要方法                                                                             |
 | ------------ | ------------------------------------------------------------------------------------ |
-| **Chat**     | `chat`, `chatStream`, `chatStreamWithUsage`                                          |
+| **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` |
-| **Auth**     | `login`, `logout`, `ensureToken`, `forceRefresh`, `discover`, `authorize`, `exchangeCode`, `refreshToken` |
-| **Models**   | `listModels`, `listModelsWithStatus`, `getModelCapabilities`, `getQuotaSummary`, `modelSupportsInputModality`, `modelSupportsImageInput`, `findFirstModelByInputModality`, `findDesktopVisualUnderstandingModel` |
-| **Skills**   | `browseSkills`, `browseSkillsList`, `getSkillDetail`, `resolveSkill`, `installSkill`, `downloadSkill`, `uploadSkill`, `generateSkill`, `optimizeSkill`, `validateSkill` |
+| **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` |
+| **Models**   | `listModels`, `listModelsWithStatus`, `getModelCapabilities`, `getQuotaSummary`, `ensureModelCached`, `modelSupportsInputModality`, `modelSupportsImageInput`, `findFirstModelByInputModality`, `findDesktopVisualUnderstandingModel` |
+| **Skills**   | `browseSkillStore`, `browseSkills`, `browseSkillsList`, `getSkillDetail`, `getSkillSummary`, `resolveSkill`, `installSkill`, `downloadSkill`, `uploadSkill`, `generateSkill`, `optimizeSkill`, `validateSkill`, `certifySkill`, `getCertificationStatus` |
 | **Tools**    | `listTools`, `getTool`                                                               |
 | **Wallet**   | `getWalletStats`, `getWalletTransactions`                                            |
-| **Entitlements** | `getBalance`, `getBalanceDetail`, `listEntitlements`, `claimMonthlyFree`, `getByModel`, `listBuckets`, `listCoefficients` |
-| **Packages** | `listTokenPackages`, `buyTokenPackage`, `getOrderStatus`, `waitForPayment`           |
-| **Notifications** | `listNotifications`, `getUnreadCount`, `markNotificationRead`, `registerDevice`, `listNotificationPreferences` |
+| **Entitlements** | `getBalance`, `getBalanceDetail`, `listEntitlements`, `listConsumeRecords`, `claimMonthlyFree`, `getByModel`, `listBuckets`, `listCoefficients`, `invalidateCoefficientCache` |
+| **Packages** | `listTokenPackages`, `getTokenPackageDetail`, `buyTokenPackage`, `getOrderStatus`, `listMyOrders`, `waitForPayment` |
+| **Notifications** | `listNotifications`, `getUnreadCount`, `markNotificationRead`, `markAllNotificationsRead`, `deleteNotification`, `registerDevice`, `unregisterDevice`, `listNotificationPreferences`, `updateNotificationPreference` |
+| **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` |
+| **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` |
+| **Compliance — envelope 收尾** | `compliance.listEnvelopeContracts`, `compliance.listEnvelopeProviderRequests`, `compliance.voidEnvelope`（`void` 为写、带 `Idempotency-Key`） |
+| **Compliance — 合同模板** | `compliance.createContractTemplate`, `compliance.updateContractTemplate`, `compliance.deleteContractTemplate`, `compliance.getContractTemplate`, `compliance.listContractTemplates`, `compliance.uploadContractTemplatePdf`, `compliance.publishContractTemplate`, `compliance.archiveContractTemplate`, `compliance.listContractTemplateVersions`（写均带 `Idempotency-Key`） |
 
 完整签名见 `dist/node/index.d.ts`，IDE 自带补全。
 
+### 跨域共享 DTO（`shared`，v1.5.0）
+
+`src/shared/` 收口跨域基础设施类型，从根入口直接导出，供各业务域统一引用：
+
+| 文件 | 导出 | 说明 |
+| --- | --- | --- |
+| `pagination` | `PageRequest`、`PageResult<T>`、`SortDirection` | `PageResult<T>` 是 `YudaoPageResult<T>` 的别名，全 SDK 单一分页结果结构 |
+| `operation` | `OperationId`、`OperationSource`、`OperationStatus`、`VerifyStatus`、`IdempotencyKey`、`IdempotencyKeyHeader`、`ProviderRequestStatus` | `operationId` 跨来源关联键；`IdempotencyKeyHeader` 写接口幂等键 header 单一真相源 |
+| `retry-advice` | `RetryAdvice`、`RetryAdviceReason`、`retryReasonForComplianceKey()`、`retryReasonForOAuthError()`、`complianceErrorToRetryAdvice()` | 统一失败补救建议——**叠加**在 `RetryPolicy` / `ComplianceErrorInfo` 之上，不替换 |
+| `principal` | `PrincipalRef`、`TenantRef`、`ApiClientRef` | 轻量身份 / 租户引用 |
+| `gate` | `FeatureGateStatus`、`FeatureGateState`、`StepUpStatus`、`GateQuota`、`BillingPreflightResult` | gate / capability / step-up / preflight 查询形态 |
+
+> 这些是为后续平台控制面（`tenant` / `iam` / `operations` / `gateway` 等）与
+> `compliance` 分页 / gate 能力预沉淀的【共享原语】；消费这些类型的命名空间方法
+> 须待对应后端端点就绪后才落地，当前 8 个占位命名空间尚未从根入口导出。
+
+### `sanitize` 命名空间（历史消息清理）
+
+`@acosmi/sdk-ts` 把 `src/sanitize/` 整体以命名空间方式导出（`import { sanitize } from '@acosmi/sdk-ts'`），同时也通过 `@acosmi/sdk-ts/sanitize` 子路径单独导入。Client 与 ChatRequest 的粘合（`Client.prototype.applyRequestSanitizers`）由 `src/core/sanitize-bridge.ts` 通过 declaration merging 自动注入。**默认零开销**——只有显式调用 `client.setDefensiveSanitize(cfg)` 或 `client.setAutoStripEphemeralHistory(true)` 后才走流水线。
+
+| 公开符号 | 形态 | 用途 |
+| --- | --- | --- |
+| `client.setDefensiveSanitize(cfg)` | Client 方法（runtime 注入） | 配置请求前底线防御（`maxMessagesTurns` 历史轮深度、`permanentDenyBlocks` block 类型黑名单、`maxImageBytes` / `maxVideoBytes` / `maxPDFBytes` base64 内联媒体上限）；传 `{}` 关闭 |
+| `client.setAutoStripEphemeralHistory(on)` | Client 方法（runtime 注入） | 开启后每次请求自动从 `rawMessages` 剥除带 `acosmi_ephemeral:true` 标记的 block，并联动剥引用已剥 `tool_use_id` 的 `tool_result` |
+| `client.applyRequestSanitizers(req)` | Client 方法（buildChatRequest 内部自动调用） | 一般无需手动调；自定义 build 链路时可直接复用 |
+| `sanitize.sanitize(messages, cfg)` | 函数 | 对消息历史做白名单过滤 + 深度 / 尺寸校验 + ephemeral 剥离，返回新数组 |
+| `sanitize.dropBlocks(messages, predicate)` | 函数 | 按谓词剔除 content blocks（联动剔除引用同 tool_use_id 的 tool_result） |
+| `sanitize.stripEphemeral(messages)` | 函数 | 剥离 `acosmi_ephemeral:true` 块（端口自 Go `sanitize.StripEphemeral`，bug-for-bug） |
+| `sanitize.MinimalSanitizeConfig` | 类型 | sanitize 配置 |
+| `sanitize.BlockType` / `BlockText` / `BlockImage` / `BlockVideo` / `BlockDocument` / `BlockSearchResult` / `BlockThinking` / `BlockRedactedThinking` / `BlockToolUse` / `BlockToolResult` / `BlockToolReference` / `BlockServerToolUse` / `BlockWebSearchToolResult` / `BlockCodeExecutionToolResult` / `BlockMCPToolUse` / `BlockMCPToolResult` / `BlockContainerUpload` | 类型 + 常量 | 已知 block 类型常量 |
+| `sanitize.HistoryTooDeepError` / `BlockDeniedError` / `SizeError` | 错误 | sanitize 规则不通过时分类抛出（也导出对应单例 `ErrHistoryTooDeep` / `ErrBlockDenied`） |
+
+```ts
+import { Client, sanitize } from '@acosmi/sdk-ts';
+
+const client = new Client({ serverURL });
+
+// 启用底线防御 + 自动剥 ephemeral
+client.setDefensiveSanitize({
+  maxMessagesTurns: 64,
+  // 其他字段按 MinimalSanitizeConfig 形态填充
+});
+client.setAutoStripEphemeralHistory(true);
+
+// 之后 chat / chatStream 走 buildChatRequest 时自动应用 applyRequestSanitizers。
+```
+
+> 红线：**thinking 块在 Anthropic 续轮的"上一轮返回什么、下一轮就必须原样回传"硬约束下走豁免**，禁止从历史中剔除；`tool_use_id` 联动剔除规则参考 `test/sanitize/history.test.ts` 的 P0 红线测试。详细行为见 `src/sanitize/history.ts` + `defensive.ts`。
+
 ### 示例：Skill 商店搜索
 
 ```ts
@@ -225,7 +329,7 @@ const tool = newWebSearchTool({
 
 const resp = await client.chat('claude-opus-4-7', {
   messages: [{ role: 'user', content: '查一下 Web Components 最新规范' }],
-  maxTokens: 2048,
+  max_tokens: 2048,
   tools: [tool],
 });
 ```
@@ -302,13 +406,14 @@ const view = await client.getBugReport(result.feedback_id);
 | 错误类型             | 触发                                                                   |
 | -------------------- | ---------------------------------------------------------------------- |
 | `HTTPError`          | 4xx/5xx，含 `statusCode` / `body` / `type` / `retryAfter`              |
-| `NetworkError`       | TCP/DNS/TLS 失败                                                       |
-| `StreamError`        | SSE 流解析失败                                                         |
+| `NetworkError`       | TCP/DNS/TLS 失败；含 `isTimeout()` / `isEOF()` 便捷判定                  |
+| `StreamError`        | gateway `managed_model_stream_failed` 事件解析（含 `code` / `stage` / `retryable`） |
 | `AgentRunStreamError` | Agent Runs 流返回 `error` 事件（默认抛出；可设 `throwOnError:false` 自行消费） |
 | `BusinessError`      | 网关返回 `code !== 0`，含 `code` (number) / `message` (字符串)         |
 | `RateLimitError`     | 429（含 `retryAfter`）                                                 |
 | `OrderTerminalError` | `waitForPayment` 终态失败                                              |
-| `CompliancePollError` | `waitForTimestampVerified` / `waitForProviderRequestTerminal` 终态失败或超时 |
+| `ModelNotFoundError` | `chat` / `ensureModelCached`：listModels 自动刷新一次后仍未命中目标 modelId（v0.13.x 起替代旧硬返 anthropic 占位的行为，含 `modelId` 字段） |
+| `CompliancePollError` | `waitForTimestampVerified` / `waitForProviderRequestTerminal` 终态失败或超时（含 `kind: 'timeout' | 'terminal_failure' | 'unknown'`） |
 
 ```ts
 import { HTTPError, BusinessError } from '@acosmi/sdk-ts';
@@ -417,12 +522,15 @@ PII / 合同原文 / storage bucket+key / subject snapshot / provider raw / TSA
 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.issueTimestamp(req, options?)
 client.compliance.issueTimestampForAsset(assetId, options?)
 client.compliance.getTimestamp(id, signal?)
 client.compliance.verifyTimestamp(req, options?)
 client.compliance.waitForTimestampVerified(id, opts?)
+client.compliance.listTimestamps(req?, signal?)            // 分页 → PageResult
 
 client.compliance.buildEvidencePackage(assetId, timestampTokenId?, options?)
 
@@ -430,12 +538,17 @@ 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.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
@@ -443,11 +556,68 @@ 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.getProviderRequest(id, signal?)
 client.compliance.waitForProviderRequestTerminal(id, opts?)
+
+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?)          // 版本快照列表（数组）
 ```
 
+> 6 个 `list*` 分页方法（compliance gateway S1）均走 `GET .../page`，返回
+> yudao `PageResult<T>`（`{ total, list }`）。请求参数继承共享 `PageRequest`
+> （`pageNo` / `pageSize` / `sortBy` / `sortDirection`，全部可选）+ 各自的过滤项。
+> `createTimeStart` / `createTimeEnd` 由调用方按 `yyyy-MM-dd HH:mm:ss` 字符串提供，
+> SDK 原样透传、不做格式校验。
+
+> compliance gateway S2 新增能力闸门查询（`getCapabilities` / `getFeatureGate`）
+> 与操作投影读（`listOperations` / `getOperation`）。`getCapabilities` 为每个高
+> 风险 / 收费动作返回 `executable` / `state` / `requiredScopes` / `requiredStepUp`
+> ——拿不到能力时必须 fail-closed。均走 GET 读路径（`401` 单次刷新重放）。
+
+> compliance gateway S4 新增 envelope 收尾方法：`listEnvelopeContracts` /
+> `listEnvelopeProviderRequests` 走 GET 读路径返回普通数组（非 `PageResult`），
+> `listEnvelopeProviderRequests` 复用操作投影类型 `OperationPageItem`；
+> `voidEnvelope` 为写方法——走 compliance 写路径（`Idempotency-Key`、不重试、
+> `401` 不重放），`reason` 随 JSON body 提交。envelope 的 send / remind /
+> authorize / download / token 等动作在后端 S4 范围之外暂缓。
+
+> compliance gateway S5 新增合同模板（contract template）9 个方法：DRAFT →
+> PUBLISHED → ARCHIVED 全生命周期。读方法（`getContractTemplate` /
+> `listContractTemplates` / `listContractTemplateVersions`）走 GET 读路径；写
+> 方法（`createContractTemplate` / `updateContractTemplate` /
+> `deleteContractTemplate` / `uploadContractTemplatePdf` /
+> `publishContractTemplate` / `archiveContractTemplate`）走 compliance 写路径
+> （`Idempotency-Key`、不重试、`401` 不重放）。新增 2 个 scope —
+> `compliance:contract_template:read` / `compliance:contract_template:write` —
+> 不要求 step-up。版本列表与列表项视图都不下发模板【字段叠加】，字段只在详情 /
+> 版本快照里返回。
+
+> compliance gateway S6 新增用印执行（seal use）分页只读方法：`listSealUses`。
+> 走 `GET /compliance/seal-uses/page`，返回 yudao `PageResult<SealUsePageItem>`；
+> 过滤支持 `sealId` / `envelopeId` / `usageStatus` / `createTimeStart` /
+> `createTimeEnd`。复用既有 `compliance:contract_signing:read` scope，不引入新
+> scope。印章授权 / 印章 CRUD（U-3 / U-11）仍为后端推迟项（CFCA 私有 jar /
+> W3 闸门），本版本不引入 SDK 方法。
+
 ### 示例
 
 `examples/` 下提供可直接运行的端到端示例，并随 npm 包一起发布：
@@ -494,7 +664,12 @@ npm run docs    # 经 TypeDoc 生成 API 参考到 docs/api/
 
 | 版本 | 状态 | 概要 |
 | --- | --- | --- |
-| 1.3.2 | 当前稳定版 | `verifyEvidencePublic` 匿名公开验真链路收口（未登录不抛 `not authorized`）；新增第 13 个 compliance scope `compliance:reports:write`（创建出证报告改用写 scope）；`docs/compliance.md` 新增方法状态四档分级（production-ready / gated / draft contract / internal-only）。 |
+| 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）。 |
+| 1.4.0 | 稳定版 | 新增浏览器 Web OAuth 原语 `discoverWebOAuthMetadata` / `registerWebOAuthClient`（csign `/login` Web OAuth 接入）。 |
+| 1.3.2 | 稳定版 | `verifyEvidencePublic` 匿名公开验真链路收口（未登录不抛 `not authorized`）；新增第 13 个 compliance scope `compliance:reports:write`（创建出证报告改用写 scope）；`docs/compliance.md` 新增方法状态四档分级（production-ready / gated / draft contract / internal-only）。 |
 | 1.3.1 | 稳定版 | 修订 npm 包短介绍与搜索关键词，明确模型网关、Agent Run Gateway 与 Compliance 统一客户端定位。 |
 | 1.3.0 | 稳定版 | 新增 compliance SDK client、base URL、types/errors/status/scopes、docs/examples/tests，并明确 idempotency/no-retry/no-401-replay 与 provider material 安全边界。 |
 | 1.2.0 | 稳定版 | 新增 `ManagedModel.inputModalities`、桌面视觉理解 sidecar capability 与 4 个 catalog helpers。 |