@acosmi/sdk-ts 2.0.0 → 2.0.1

package/CHANGELOG.md

@@ -5,6 +5,12 @@ 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.0.1] - 2026-05-25 — Packaging fix
+
+### Fixed
+
+- `package.json` `files` 字段白名单遗漏 — v2.0.0 publish 后发现 `docs/pii-role-matrix.md` (新建) 与 `docs/开发与发布手册.md` (修订) 未进 npm 包. 集成方 `npm install @acosmi/sdk-ts` 后 `node_modules/@acosmi/sdk-ts/docs/` 缺这两份关键文档. 修白名单加显式三份 `docs/*.md` (排除 `docs/api/` 1.7MB TypeDoc 输出避免包膨胀).
+
 ## [2.0.0] - 2026-05-25 — BREAKING (Phase 3 复核 + 全量根治)
 
 商品化 P1-P7 Phase 3 深度复核审计 (主仓 9 commit, HEAD `e510f68a`) + SDK 全量同步.

package/docs/pii-role-matrix.md

@@ -0,0 +1,178 @@
+# PII 角色可见性矩阵 (v1.9.0+)
+
+> 适用版本: `@acosmi/sdk-ts` v1.9.0+
+> 对应主仓: K10a PII Aspect (`@FieldEncrypt` / `@Sensitive` 切面) + IMPL-A 角色严格化
+> 最后更新: 2026-05-25
+
+## 1. 背景
+
+商品化 P1-P7 Phase 3 收口时, 主仓 (tk-dist Java) 完成两条根因修复并随 SDK v1.9.0
+发布:
+
+- **K10a PII Aspect**: `dist_invoice` / `dist_corporate_transfer` / `dist_refund_record`
+  等 finance 表族 + `dist_lawyer_profile` 法律表族 + `dist_enterprise_*` 企业席位表族
+  敏感列改走 `@FieldEncrypt` 切面真加密落盘. V63 列宽 VARCHAR→TEXT 兜密文; V64 backfill
+  老明文 → v2 payload.
+
+- **IMPL-A 角色严格化** (`SensitiveSerializer.normalizeAuthority`): yudao 通用
+  `ROLE_ADMIN` / `ROLE_USER` / `INTERNAL` 三个老别名 fail-OPEN 升级为 platform_admin
+  视角的隐患已根治. 调用方传 token 必须真有正式角色, 否则视同 guest.
+
+SDK 边界: 类型注释只描述 PII 级别, 不内置脱敏逻辑 — 真实脱敏由后端 `PiiDesensitizer`
+按角色返回不同字符串 (明文 / `***1234` / 全 `***`). SDK 调用方 (Web / Desktop / CLI)
+需理解角色矩阵以正确渲染.
+
+## 2. 4 角色枚举
+
+来源: `SensitiveSerializer.normalizeAuthority` (主仓
+`yudao-module-distribution/...impl/serializer/SensitiveSerializer.java`).
+
+| 角色常量 | 含义 | 典型颁发方 |
+| --- | --- | --- |
+| `ROLE_PLATFORM_ADMIN` | 平台管理员 (跨租户) — 后台运营 / 客服 / 财务工作台 | 主仓 yudao admin 登录 + claim platform_admin |
+| `ROLE_S2S` | 服务对服务调用 — Nexus Go 网关 / 微服务内部互调 | S2S Token (X-Service-Secret) |
+| `ROLE_LAWYER` | 律师 — 仅查看自己执业资料 + 自己接单的案件 | C 端登录 + 律师资质审核通过 |
+| `ROLE_CONSUMER` | 消费者 — 普通 C 端用户, 仅查看自己的数据 | C 端 OAuth (`/api/consumer/**`) |
+| (guest / unknown) | 匿名 / 未登录 / 角色不匹配 | 无 token / Bearer 无效 / 角色字符串非上述 4 个 |
+
+## 3. PII 级 × 角色矩阵
+
+PII 分 3 级 (与 `@Sensitive(level=...)` 严格对齐):
+
+- **L1 公开** — 任何场景明文 (id / orderId / amountFen / status / createdAt 等)
+- **L2 半遮** — 部分场景半遮 (title / contactAddress / nickname / avatarUrl 等)
+- **L3 仅 admin** — 强敏感字段, 默认全脱敏 (taxId / bankAccount / contactPhone /
+  bankName / licenseNo / idCardNo 等)
+
+| 角色 | L1 公开 | L2 半遮 | L3 仅 admin |
+| --- | --- | --- | --- |
+| `ROLE_PLATFORM_ADMIN` | 明文 | 明文 | 明文 |
+| `ROLE_S2S` | 明文 | 明文 | 明文 |
+| `ROLE_LAWYER` | 明文 | 明文 | 脱敏 (`***1234`) |
+| `ROLE_CONSUMER` | 明文 | 明文 | 脱敏 (`***1234`) |
+| (guest / unknown) | 明文 | 脱敏 | 脱敏 |
+
+> **Note**: `ROLE_LAWYER` / `ROLE_CONSUMER` 自己的数据 L3 字段仍可通过专门的 admin 直读
+> 端点 (`/api/distribution/**/me/decrypted`) 解密, 但默认 listMyXxx 端点走脱敏视图.
+> SDK 类型上不强制 — 调用方按上下文判定.
+
+## 4. Breaking Change — v1.9.0+ 旧别名失效
+
+主仓 IMPL-A 角色严格化把以下 3 条 fail-OPEN 别名根治:
+
+| 旧别名 (≤ v1.8.x) | 误升级到 (旧行为) | v1.9.0+ 处理 |
+| --- | --- | --- |
+| `ROLE_ADMIN` | `platform_admin` (L3 明文) | 视同 `guest` (L2/L3 全脱敏) |
+| `ROLE_USER` | `consumer` (L1/L2 明文) | 视同 `guest` (L2/L3 全脱敏) |
+| `INTERNAL` | `s2s` (L3 明文) | 视同 `guest` (L2/L3 全脱敏) |
+
+### 集成方应对
+
+1. **token 升级到正式角色**: yudao admin 后台 token 改派发 `ROLE_PLATFORM_ADMIN`;
+   微服务 S2S 调用切到 `ROLE_S2S` claim; C 端 OAuth 已自动派发 `ROLE_CONSUMER`.
+2. **fallback 走 guest 视角**: 升级期 (灰度) 旧 token 调用 `/api/distribution/admin/**`
+   会拿到脱敏数据 — 这是设计内行为, 不是 bug.
+3. **角色字符串大小写敏感**: 必须全大写 `ROLE_PLATFORM_ADMIN`, 小写 / 缺前缀的
+   `platform_admin` 会被 `normalizeAuthority` 拒绝.
+
+## 5. 实际生效字段示例
+
+按 v1.9.0 SDK 主要类型清单 (与主仓 `@Sensitive` 注解严格对齐):
+
+### finance namespace (`src/finance/types.ts`)
+
+| 字段 | 级别 | 角色匹配后明文示例 | guest 视图 |
+| --- | --- | --- | --- |
+| `Invoice.id / invoiceNo / orderId / amountFen / status` | L1 | `INV20260525001` | 同 |
+| `Invoice.title` | L2 | `Acosmi Tech Ltd` | `Acos*****td` |
+| `Invoice.contactAddress` | L2 | `北京市朝阳区...` | `北京市*****` |
+| `Invoice.taxId` | L3 | `91110108MA01ABC123` | `91**********23` |
+| `Invoice.bankAccount` | L3 | `6225882104567890` | `6225********7890` |
+| `Invoice.bankName` | L3 | `招商银行北京分行` | `招商***` |
+| `Invoice.contactPhone` | L3 | `13800001234` | `138****1234` |
+
+### enterprise namespace (`src/enterprise/types.ts`)
+
+| 字段 | 级别 |
+| --- | --- |
+| `EnterpriseSummary.contactPhone` | L3 (仅 OWNER/ADMIN 可见) |
+| `EnterpriseSummary.contactEmail` | L3 |
+| `EnterpriseSummary.creditCode` | L2 |
+
+### casehall namespace (`src/casehall/types.ts`)
+
+| 字段 | 级别 |
+| --- | --- |
+| `LawyerSummary.licenseNo` | L3 (公开 listLawyers 已脱敏剥离, 仅 admin 直读) |
+| `LawyerSummary.idCardNo` | L3 |
+| `LawyerSummary.realName` | L2 |
+| `CaseLead.disputeAmountFen` | L1 |
+| `CaseLead.contactPhone` | L3 |
+
+## 6. 脱敏算法引用
+
+后端 `PiiDesensitizer` (主仓 `yudao-module-distribution/...PiiDesensitizer.java`) 按字段
+类型自动派生脱敏策略:
+
+| 策略 | 输入 | 输出 |
+| --- | --- | --- |
+| `PHONE` | `13800001234` | `138****1234` |
+| `EMAIL` | `user@acosmi.com` | `u***@acosmi.com` |
+| `ID_CARD` | `110101199001011234` | `1101**********1234` |
+| `BANK_CARD` | `6225882104567890` | `6225********7890` |
+| `NAME` | `张三丰` | `张*丰` |
+| `ADDRESS` | `北京市朝阳区...` | `北京市*****` |
+| `GENERIC` | 任意其他 L2/L3 字符串 | `XX*****XX` (前后 2 字符+中间星号) |
+
+`@Sensitive(strategy=...)` 显式指定策略时优先; 否则按字段名启发 (字段名含 phone/mobile
+→ PHONE, 含 email → EMAIL, 等).
+
+## 7. 测试集成方应做的 mock
+
+集成方 (Web / Desktop / 微服务) 在单测中应 mock 不同角色 token 切换, 验证渲染层正确处理:
+
+```ts
+// vitest 示例 — Web 端验证 admin 视图 vs guest 视图字段差异
+import { describe, it, expect, vi } from 'vitest';
+import { Client } from '@acosmi/sdk-ts';
+
+describe('Invoice rendering across roles', () => {
+  it('platform_admin sees L3 plain', async () => {
+    // mock token 含 ROLE_PLATFORM_ADMIN claim
+    const client = new Client({ serverURL, token: mintToken({ role: 'ROLE_PLATFORM_ADMIN' }) });
+    const list = await client.listMyInvoices();
+    expect(list[0].bankAccount).toMatch(/^\d{16}$/); // 明文
+  });
+
+  it('consumer sees L3 desensitized', async () => {
+    const client = new Client({ serverURL, token: mintToken({ role: 'ROLE_CONSUMER' }) });
+    const list = await client.listMyInvoices();
+    expect(list[0].bankAccount).toMatch(/^\d{4}\*+\d{4}$/); // 6225********7890
+  });
+
+  it('guest (no token) sees L2/L3 desensitized', async () => {
+    const client = new Client({ serverURL });
+    // (公开列表端点, 无登录)
+    const lawyers = await client.listLawyers();
+    expect(lawyers.items[0].licenseNo).toBeUndefined(); // L3 直接剥字段
+    expect(lawyers.items[0].realName).toMatch(/\*/); // L2 半遮
+  });
+
+  it('ROLE_ADMIN (legacy alias) is treated as guest in v1.9.0+', async () => {
+    // 旧 yudao admin token, role=ROLE_ADMIN (无 platform_admin)
+    const client = new Client({ serverURL, token: mintToken({ role: 'ROLE_ADMIN' }) });
+    const list = await client.listMyInvoices();
+    expect(list[0].bankAccount).toMatch(/\*/); // 视同 guest, L3 脱敏
+  });
+});
+```
+
+## 8. 参考链接
+
+- 主仓 PII Aspect: `yudao-module-distribution/...impl/aspect/PiiEncryptAspect.java`
+- 主仓角色规范化: `yudao-module-distribution/...impl/serializer/SensitiveSerializer.java`
+- 主仓脱敏算法: `yudao-module-distribution/...impl/serializer/PiiDesensitizer.java`
+- 主仓迁移 V51 (finance 表族加密): `nexus-v4/sql/yudao-server-v51-pii-encrypt-init.sql`
+- 主仓迁移 V63 (列宽兜底): `nexus-v4/sql/yudao-server-v63-pii-column-text.sql`
+- 主仓迁移 V64 (backfill): `nexus-v4/sql/yudao-server-v64-pii-backfill-v2.sql`
+- SDK 类型注释: `src/finance/types.ts` `Invoice` JSDoc

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

@@ -0,0 +1,736 @@
+# @acosmi/sdk-ts 开发与发布手册
+
+> 适用版本: v1.0.0+
+> 最后更新: 2026-05-25
+
+## 1. 项目概览
+
+`@acosmi/sdk-ts` 是 Acosmi 模型网关、SDK-facing Agent Run Gateway 与 compliance API 的 TypeScript SDK。**自 2026-05-22 起 TS SDK 成为主实现 / 事实标准**：Go SDK `acosmi-sdk-go` 暂停维护，本仓专注把 TS 做好做稳；待 TS 稳定后再从 TS 反向翻译补齐 Go。早期版本由 Go 端口而来，但布局与演进已不再受 Go 约束。
+
+| 项目     | 值 |
+| -------- | -- |
+| 实现地位 | **主实现 / 事实标准**；Go SDK 暂停维护，后续从 TS 反向翻译 |
+| 当前版本 | 1.9.0（商品化 P1-P7 namespace 全量：subscription / pricing / products / csign 合规 SKU / casehall / enterprise / finance） |
+| 版本策略 | TS 独立演进；wire-format / API 不兼容变更升 major |
+| 主消费者 | `crabcode` (Anthropic 格式)、`crabdesign` / `crabclaw` 等下游产品 |
+| 长期保留 | `OpenAIAdapter` (P0 红线，`crabclaw` 暂不用 TS 但保留双格式等地位) |
+| LICENSE  | MIT — Copyright (c) 2026 Acosmi |
+
+## 2. 仓库与发布拓扑
+
+```
+SDK 独立仓 (public)                         npm 公开包
+/Users/fushihua/Desktop/Acosmi/acosmi-sdk-ts → npmjs.com/@acosmi/sdk-ts
+└── github.com/acosmi/sdk-ts                 └── tag v* 触发 release workflow
+```
+
+**铁律**：
+- SDK 是独立发布物，提交与 tag 只在 `acosmi-sdk-ts` 仓库内完成。
+- 不把外层 monorepo 的 Java / Go / CFCA real provider 改动带入 SDK commit。
+- 公开仓 history 和提交信息必须保持产品/SDK 语义，不包含协作工具或开发过程元数据。
+- `docs/` 可放公开用户文档；内部 audit、证书材料、provider runbook 不进公开仓。
+
+## 3. 开发环境
+
+- Node.js **≥18**（package.json `engines.node` 公开承诺，不动）；推荐本地 24 Active LTS；CI 用 24（含 JS-actions runtime, `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24=true`）
+- npm ≥8
+- 推荐 IDE：VSCode + ESLint + Prettier 扩展
+
+## 4. 目录结构
+
+`src/` 按**业务域文件夹**组织：每个域一个文件夹 + 一个 `index.ts` barrel，`core/`
+收口运行时基座，`shared/` 收口跨域基础设施。根 `src/index.ts` 只从各域 barrel
+re-export。新增业务域时落对应文件夹，规则唯一明确。
+
+```
+acosmi-sdk-ts/
+├── src/                       # 源码（按域文件夹组织）
+│   ├── index.ts               # 公共入口 barrel（从各域 re-export）
+│   ├── browser.ts             # 浏览器构建入口
+│   ├── core/                  # 运行时基座，无业务域
+│   │   ├── client.ts          # 主 Client class
+│   │   ├── store.ts           # FileTokenStore + LocalStorageTokenStore + InMemoryTokenStore
+│   │   ├── retry.ts           # 重试策略
+│   │   ├── http.ts            # HTTP / SSE helper
+│   │   └── sanitize-bridge.ts # Client × sanitize 胶水 (declaration merging)
+│   ├── shared/                # 跨域基础设施 + 跨域共享 DTO（v1.5.0）
+│   │   ├── api-response.ts    # APIResponse / YudaoPageResult
+│   │   ├── errors.ts          # HTTPError / NetworkError / StreamError / BusinessError / ...
+│   │   ├── pagination.ts      # PageRequest / PageResult（= YudaoPageResult 别名）/ SortDirection
+│   │   ├── operation.ts       # OperationId / Source / Status / VerifyStatus / IdempotencyKey(Header)
+│   │   ├── retry-advice.ts    # RetryAdvice + reason 映射（叠加层，不替换 RetryPolicy）
+│   │   ├── principal.ts       # PrincipalRef / TenantRef / ApiClientRef 轻量引用
+│   │   └── gate.ts            # FeatureGateStatus / StepUpStatus / BillingPreflightResult
+│   ├── auth/                  # 鉴权 / 身份域
+│   │   ├── auth.ts            # OAuth 2.1 PKCE / 动态注册 / token refresh / revoke
+│   │   ├── scopes.ts          # 分组 scope
+│   │   └── types.ts           # ServerMetadata / TokenResponse / TokenSet / ClientRegistration
+│   ├── models/                # 模型网关域
+│   │   ├── types.ts           # ManagedModel / Chat* / StreamEvent / ...
+│   │   ├── wire-anthropic.ts  wire-openai.ts   # 两套 wire-format DTO
+│   │   ├── adapters/          # AnthropicAdapter + OpenAIAdapter (P0 双格式红线)
+│   │   └── model-helpers.ts  stream-meta.ts  betas.ts
+│   ├── billing/               # 计费域（entitlements / packages / wallet）
+│   ├── casehall/              # 法律案件咨询（v1.8.0）— 律师公开视图 / 案件线索 / 咨询 / 5 SKU
+│   ├── certification/         # 预留 — 实名 / 人脸 / 活体 / 企业认证 / CA
+│   ├── compliance/            # 合规域（重点扩张：evidence / timestamp / signing / ...）
+│   ├── enterprise/            # 企业席位（v1.8.1）— 企业组织 / 成员 / 订阅 / 席位 / 用量
+│   ├── finance/               # 财务域（v1.9.0）— 发票 / 退款 / 对公转账（决策 14/15 + R12）
+│   ├── notifications/         # 通知 / 推送 / WebSocket
+│   ├── agent-runs/            # SDK-facing Agent Run Gateway（client + 公开协议类型）
+│   ├── pricing/               # 公开业务参数（v1.7.0）+ csign 合规 SKU 报价（v1.7.0）
+│   ├── products/              # 商品中心（v1.7.0）— productFamily / audience / billingMode 索引
+│   ├── sanitize/              # 历史消息清理子包
+│   ├── skills/                # 技能商店 + 工具列表
+│   ├── subscription/          # 订阅档位（v1.7.0）— SubscriptionPlan / UserSubscription
+│   ├── support/               # bug-report 等
+│   └── apiClients/ tenant/ iam/ audit/ operations/ mcp/ gateway/
+│                              # 全域命名空间预留骨架（能力见对外鉴权层独立计划）
+├── test/                      # vitest 单元测试
+├── examples/                  # npm 包随附示例
+│   ├── core-chat.ts
+│   ├── auth-oauth-flow.ts
+│   ├── agent-runs-stream.ts
+│   ├── compliance-read.ts
+│   ├── compliance-evidence-timestamp.ts
+│   └── compliance-envelope.ts
+├── docs/
+│   ├── compliance.md          # npm 包随附 compliance API 指南
+│   ├── api/                   # TypeDoc 生成的 API 参考（npm run docs）
+│   └── 开发与发布手册.md      # 仓库维护手册，不随 npm 包发布
+├── dist/                      # 构建产物 (gitignored, CI 编译)
+├── package.json
+├── tsup.config.ts             # 多端构建
+├── tsconfig.json
+├── typedoc.json               # TypeDoc API 参考文档配置
+├── .eslintrc.json
+├── .npmignore                 # 排除 src/test/configs/.github
+├── README.md                  # 用户文档（API 总览 + 示例）
+├── LICENSE                    # MIT
+└── .github/workflows/
+    └── release.yml            # push tag v* → npm publish + GitHub Release
+```
+
+> 重组为**非破坏性**：对外导出符号、`package.json` 的 `exports`、`dist/` 产物路径
+> 全部不变；下游 `crabcode` / `crabclaw` / `csign` 零感知。`node.ts` 因是未接线的
+> 死入口（无 `./node` 子路径导出、非任何 build entry）已删除。
+
+## 5. 编码规范
+
+### TypeScript 风格（硬规则）
+
+| 类别 | 规则 | 例 |
+|------|------|----|
+| 函数/方法 | **camelCase** | `discover`, `getAdapterForModel` |
+| 类 / 接口 / 类型 | **PascalCase** | `Client`, `ServerMetadata`, `AnthropicAdapter` |
+| Error 子类 | **PascalCase + Error 后缀** | `HTTPError`, `BusinessError`, `OrderTerminalError` |
+| 常量 | **PascalCase**（前缀型）或 **UPPER_CASE** | `ErrDiscovery`, `ScopeAI`, `EventComplete` |
+| 文件名 | **kebab-case** | `stream-meta.ts`, `bug-report.ts` |
+| Wire-format 字段 | **snake_case**（与 Go json tag 严格对齐） | `preferred_format`, `created_at`, `max_tokens` |
+
+### 不要使用的 Go-isms（硬禁止）
+
+- ❌ **PascalCase 函数** — TS 公开 API 必须 camelCase（`AllScopes()` 是 Go 风格，改 `allScopes()`）
+- ❌ **多返回值 `[T, Error]` 元组** — 用 `throw` + 类型化 Error 子类
+- ❌ **`nil` 字面量** — 用 `null` / `undefined`
+- ❌ **`: any`** — 优先 `: unknown` 或精确类型
+- ❌ **Go 关键字识别符**：`func`, `package`, `chan`, `defer`, `goroutine`
+- ❌ **指针风格 `T | null`** — 用 optional `?: T`（除非 wire-format 必须）
+- ❌ **`fmt.Sprintf` / `fmt.Errorf` / `log.Println`** — 用模板字符串 / `new Error()` / `console`
+
+### 跨语言契约印记（TS→Go 反向翻译对照基准，不许改）
+
+TS 现为主实现，**文件级与 Go 1:1 对齐的约束已作废** —— `src/` 布局完全自由（见 §4
+域文件夹结构）。但以下跨语言契约仍是将来把 TS 反向翻译为 Go 时的对照基准，必须保留：
+
+- ✅ **snake_case wire-format 字段名** — wire 协议契约（50+ struct 已对齐），不可漂移
+- ✅ **符号名跨语言一致** — 导出的类型 / 方法 / 错误名是 TS↔Go 对照锚点
+- ✅ **bug-for-bug 行为对齐**（e.g. retry POST=false 默认，sanitize thinking 硬豁免）
+- ✅ **ISO 8601 字符串时间** — 与 Go RFC3339 wire-compat
+- ✅ **string 表示金额 / json.Number 字段** — 避免 JS number 精度损失（金融安全）
+- ✅ **双 adapter 等地位** — `AnthropicAdapter` + `OpenAIAdapter` P0 红线，不可降级
+- ✅ **已有端口代码的 "端口自 X.go" 溯源注释** — 历史对照保留；compliance、对外鉴权层等
+  新域本就无 Go 对应物，不写该注释
+
+### TS 不可避免的偏移（与 Go 不 1:1）
+
+| 维度 | Go | TS |
+|------|----|----|
+| 错误处理 | `(val, err)` 多返回值 | `throw` + 类型化 Error 子类 |
+| 上下文取消 | `context.Context` | `AbortSignal` |
+| 流返回 | `(eventCh, errCh chan)` | `AsyncIterable<StreamEvent>` |
+| 锁 | `sync.Mutex` | Promise chain (`this.mu`) |
+| IO | 同步 `os.ReadFile` | `fs/promises` async |
+| Token Store 持久化 | 同步 file IO | `async` Save/Load/Clear |
+
+## 6. 开发流程
+
+### 改源码 → 提交
+
+```bash
+cd /Users/fushihua/Desktop/Acosmi/acosmi-sdk-ts
+
+# 改完后必须通过发布前验证
+npm run typecheck    # 0 errors
+npm run lint         # 0 errors
+npm test             # all pass
+npm run build        # 多端 dist/ 全部生成
+npm run test:pack    # packed tarball consumer smoke
+
+# commit (仅 SDK 独立仓)
+git status --short
+git diff --check
+git add <files>
+git commit -m "fix: ..."
+```
+
+### Commit message 规范
+
+`type(scope): subject` 风格（与 Go SDK 仓库一致）：
+
+- `feat(sdk-ts): ...` 新功能
+- `fix(sdk-ts): ...` bug fix
+- `refactor(sdk-ts): ...` 重构（无功能变化）
+- `docs(sdk-ts): ...` 文档
+- `test(sdk-ts): ...` 测试
+- `release(sdk-ts): vX.Y.Z` 版本发布
+
+公开仓提交信息只写产品/SDK 变更，不写协作工具、临时计划或开发过程元数据。
+
+## 7. 测试
+
+- 框架：**vitest**（Node + jsdom 兼容）
+- 位置：`test/`（随功能增长，发版前以 `npm test` 实际输出为准）
+- 命令：`npm test` 单跑 / `npm run test:watch` watch
+
+### 必测 P0 红线（改了就必跑）
+
+- `test/adapters/routing.test.ts` — 双格式四级路由 8 case（**P0 红线**）
+- `test/adapters/anthropic-build.test.ts` — buildRequestBody 14 case
+- `test/sanitize/history.test.ts` — StripEphemeral / DropBlocks / thinking 豁免 7 case
+- `test/scopes.test.ts` — 分组 scope 5 case
+- `test/agent-runs.test.ts` — Agent Runs create/stream/401/local-tool/artifact 公开协议
+- `test/model-helpers.test.ts` — v1.2 InputModality catalog helpers + sidecar 选择规则
+- `test/list-models-input-modalities.test.ts` — v1.2 snake_case → camelCase 归一化 + undefined 保留
+- `test/compliance.test.ts` — v1.3 compliance URL / 401 / no-retry / idempotency / error classify / polling / privacy boundary
+- `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
+
+### Agent Runs 公开 API 范围
+
+从 v1.1.0 起，SDK 不再只是模型网关客户端，还包含下游产品可用的云端智能体任务协议：
+
+- `client.agentRuns.create(req, signal?)`
+- `client.agentRuns.stream(runId, opts?, signal?)`
+- `client.agentRuns.run(req, opts?, signal?)`
+- `client.agentRuns.cancel(runId, signal?)`
+- `client.agentRuns.get(runId, signal?)`
+- `client.agentRuns.listArtifacts(runId, signal?)`
+- `client.agentRuns.downloadArtifact(runId, artifactId, signal?)`
+- `client.agentRuns.submitLocalToolResult(runId, result, signal?)`
+- `client.agentRuns.runWithLocalTools(req, handlers, opts?, signal?)`
+
+红线：
+- 下游产品禁止直连 Nexus 内部 `/api/v4/chat/completions` 或 `/api/v4/managed-models/:id/...` 来实现智能体循环。
+- Agent Runs wire-format 使用 snake_case；SDK public API 使用 camelCase。
+- Agent Runs 服务端状态必须按 `tenantId + userId` 隔离并持久化；run/SSE event/artifact/local-tool-result 不能只放进进程内存。
+- Agent Runs 执行必须接入统一 entitlement hold/settle/release 链路；settle 失败必须进入既有 pending settlement 补偿机制。
+- Agent Runs 结算只能使用 provider/ADK 透传的 `exact: true` usage；不得用字符数、输入长度或其他估算 token 扣费。provider usage 缺失时必须 release hold，并向 stream 返回稳定的 `usage_missing_released` settlement 状态。
+- `create`、`submitLocalToolResult` 等可能产生副作用的 POST 遇到 401 不自动 refresh 后重放，避免重复创建或重复计费；GET/stream/download 这类安全查询允许单次 refresh 重试。
+- SDK 不内置 CrabDesign/CrabCode/CrabClaw 专属本地文件读取逻辑；`local_tool_request` 只定义协议，handler 必须由下游显式传入；`allowedTools` 使用 ASCII function name。
+
+### InputModality + 桌面视觉理解 sidecar 契约（v1.2.0）
+
+从 v1.2.0 起，SDK 暴露上游 `ManagedModel` 的输入模态字段 + 桌面视觉理解 sidecar capability，供 CrabCode desktop automation / computer-use 通过 catalog（而非模型名 substring）选模型：
+
+**类型契约**：
+
+- `InputModality = 'text' | 'image'`（严格白名单）
+- `ManagedModel.inputModalities?: InputModality[]` — 模型可接收的用户输入模态；`undefined` = 未声明（保守按 text-only / unknown 处理）
+- `ModelCapabilities.supports_desktop_visual_understanding?: boolean` — 模型是否被运营标记为桌面截图解析 sidecar（输入 screenshot，输出 UI 结构化描述）
+
+**4 个 catalog helper**（`src/models/model-helpers.ts`）：
+
+- `modelSupportsInputModality(model, modality): boolean`
+- `modelSupportsImageInput(model): boolean`
+- `findFirstModelByInputModality(models, modality): ManagedModel | null` — 按 catalog 顺序，跳过 `isEnabled === false`
+- `findDesktopVisualUnderstandingModel(models): ManagedModel | null` — 选择规则：`isEnabled !== false` + `supports_desktop_visual_understanding === true` + `inputModalities` 含 `image` + `isDefault` 优先 / 否则 catalog 顺序第一
+
+**协议归一化**：
+
+- `listModels` / `listModelsWithStatus` 会归一化上游 snake_case `input_modalities` → camelCase `inputModalities`（兼容老网关）
+- 同时存在 camelCase + snake_case 时 camelCase 胜
+- `zeroModelCapabilities()` 显式置 `supports_desktop_visual_understanding: false`，避免 `undefined` 误判
+
+**红线（严禁违反）**：
+
+- 客户端**不得**在本地硬编码模型名做能力推断（如检测 modelId 含 "vision"）；一切视觉模型选择必须来自 SDK catalog 字段
+- 上游 `ManagedModel` 缺失 `inputModalities` 时，SDK 保留 `undefined`，**不**自动补 `['text']` — 调用方必须保守按 text-only / unknown 处理，**严禁默认假设支持 image**
+- 网关后端强约束：`supports_desktop_visual_understanding=true` 必须 `inputModalities` 含 `image`（handler 400 拒绝错配置）
+- `inputModalities` 与 `capabilities.supports_desktop_visual_understanding` 是正交两件事：前者描述"模型能不能吃图"，后者描述"运营是否把该模型标为桌面 UI 解析专用 sidecar"
+
+**新增单测**：
+
+- `test/list-models-input-modalities.test.ts` — listModels snake/camel 归一化 + undefined 保留 8 case
+- `test/model-helpers.test.ts` — 4 个 helper + isEnabled/isDefault 优先级 15 case
+
+加测试规则：
+- 端口自 Go SDK 的测试用例必须保留 bug-for-bug
+- TS-only 测试（e.g. AbortSignal 行为）单独写文件，不混进端口测试
+
+### Compliance SDK 契约（v1.3.0）
+
+从 v1.3.0 起，SDK 暴露 `client.compliance` 子客户端，覆盖时间章、电子证据、
+证据包、报告、合同签署 envelope、用印审批和 provider request 脱敏状态轮询。
+
+**公开 API 边界**：
+
+- `Config.complianceBaseURL` 默认 `${serverURL}/admin-api`，不复用 `/api/v4`。
+- `src/compliance/client.ts` 只发送 Acosmi 公共 DTO，不发送 provider 选择字段。
+- compliance 类型文件（`src/compliance/**/types.ts` —— 各子域 `evidence/timestamp/signing/...`
+  的 `types.ts` 及共享 `src/compliance/types.ts`）不得暴露 provider
+  product/user/transaction/project/seal-provider 字段。
+- `src/compliance/errors.ts` 只按 Java numeric `BusinessError.code` 分类，不从 message 文案做正则。
+- `src/index.ts` 以 `export * from './compliance'` 导出 compliance 域；`src/compliance/index.ts`
+  barrel 从 `./client` re-export `ComplianceClient`，该 re-export 即加载 `client.ts`，
+  其 `Client.prototype` 的 `compliance` getter declaration-merging 随 barrel 一并生效。
+
+**写操作红线**：
+
+- POST/PUT/DELETE 不自动 retry。
+- 写操作 401 不 refresh + replay；调用方重新认证后用同一 `Idempotency-Key` 恢复。
+- GET 读路径可以做单次 401 refresh retry。
+- 所有写方法必须允许传递 `Idempotency-Key`。
+
+**安全红线**：
+
+- SDK / docs / examples / tests / dist / tarball 不得包含 provider endpoint、证书、私钥、
+  JKS/PFX/P12、P7、zip、jar、口令、provider raw payload 或 callback billing commit payload。
+- Java compliance 后端负责 provider 集成、受控材料、local verify 和 billing 状态机。
+- Go OAuth/JWKS 层负责 token 签发、scope 与 step-up/introspection 语义。
+- TS SDK 只申请 scope、发送公共 DTO、分类公开错误码并轮询脱敏状态。
+
+**必测**：
+
+- `npm test -- --run test/compliance.test.ts test/compliance-scopes.test.ts`
+- `npm run test:pack` 必须覆盖 `client.compliance` consumer 视角类型调用。
+- `npm pack --dry-run` 必须确认 tarball 仅包含 dist、README、CHANGELOG、LICENSE、
+  `docs/compliance.md` 和 `examples/` 等预期文件。
+
+**v1.3.2 增补**（生产闭环实施计划 Phase 1 / 5 / 7）：
+
+- `verifyEvidencePublic` 收口为匿名公开验真：未 `login()` 时直接发匿名请求，不再抛
+  `not authorized`；已持 token 则附 `Authorization` 保留审计上下文；public 端点 `401`
+  不触发 `forceRefresh`、不做 refresh replay。
+- 新增第 13 个 compliance scope `compliance:reports:write`：`createReport` 对应的服务端
+  scope 从 read 切到独立写 scope；`complianceScopes()` 已含；Go/Java/TS 三端字面量一致。
+- `docs/compliance.md` 新增「Method Status」一节，把每个 `client.compliance.*` 方法标注为
+  `production-ready` / `gated` / `draft contract` / `internal-only` 四档。`gated`
+  （`publishReport` / `signEnvelope` / `createH5SigningUrl` / `approveSealApproval`）在服务端
+  step-up / 闸门未闭合前 fail-closed，SDK 不重试、不伪成功；distribution billing 等
+  `internal-only` 能力不进入 SDK 调用面。
+
+### 跨域共享 DTO 契约（v1.5.0）
+
+从 v1.5.0 起，`src/shared/` 除 `errors.ts` / `api-response.ts` 外，新增 5 个跨域
+共享 DTO 文件，为后续平台控制面（`tenant` / `iam` / `operations` / `gateway`
+等占位命名空间）与 `compliance` 分页 / gate 能力预沉淀【共享原语】。依据：能力
+缺口总账 `docs/audit/saas-sdk-backend-capability-gap-register-2026-05-22` §9.4 /
+§9.5（Phase 0.3 / 0.5）。
+
+**落位规则**：
+
+- 共享 DTO 一律落 `src/shared/`，按【关注点】分文件（`pagination` / `operation` /
+  `retry-advice` / `principal` / `gate`），不堆进 `shared/index.ts`，不在 `src/`
+  根新增散文件，不回退巨型 `types.ts`。
+- `shared/index.ts` barrel 汇总 re-export；根 `src/index.ts` 经 `export * from
+  './shared'` 自动导出，新增文件无需改根入口。
+
+**冲突避免红线（严禁违反）**：
+
+- ✅ **`PageResult<T>` 是 `YudaoPageResult<T>` 的别名**，不引入第二套
+  `{list,total}` 分页结果结构——避免 billing / compliance / skills /
+  notifications 之间双分页标准。`PageRequest` 为新增【可选】类型，**不回填改写**
+  既有 4 处内联分页签名（破坏性变更）。
+- ✅ **`RetryAdvice` 是叠加层**——独立类型、独立字段，**不修改也不替换**
+  `core/retry.ts` 的 `RetryPolicy`（决定 SDK 传输层是否自动重试）与
+  `compliance/errors.ts` 的 `ComplianceErrorInfo`（`retryable`/`terminal`/
+  `stepUpRequired`）。否则 `csign sdk-client.ts:classifyVerifyError` 破裂。
+- ✅ **`RetryAdviceReason` 不开第四套错误码登记表**——它是既有三套登记表
+  （Java 数值码 `1_031_xxx` / SDK 符号 key / Go OAuth 标准字符串）的小写归一化
+  映射；`retry-advice.ts` 内 `Record<ComplianceErrorKey, RetryAdviceReason>`
+  以编译期穷举强约束映射表不漏。
+- ✅ **`ProviderRequestStatus` 复用**既有 `ComplianceProviderRequestStatus`，
+  不另造同名近似类型。
+- ✅ **`IdempotencyKeyHeader`（`'Idempotency-Key'`）是写接口幂等键 header 的
+  单一真相源**，新写接口一律引用该常量。
+
+**关键约束**：使 8 个占位命名空间（`tenant` / `iam` / `apiClients` /
+`operations` / `audit` / `gateway` / `mcp` / `certification`）变成真实导出 = 写出
+调用后端端点的 SDK 方法；对应后端端点**当前不存在**。在后端端点与契约就绪前，
+这些命名空间保持 `export {}` 占位，**不实现**——提前写空转方法属编造契约。共享
+DTO 是纯类型 / 纯函数沉淀，不构成对后端契约的预设，故可先行落地。
+
+**必测**：`test/shared.test.ts`（17 case）。
+
+### Compliance gateway S1-S6 rollup（v1.5.0）
+
+v1.5.0 同时把 compliance gateway S1-S6（roadmap 原 v1.6.0-v1.11.0）全量 rollup 进
+当前版本，**新增 SDK 公开方法 25+ 个**，全部走 `client.compliance.*`，红线（写不
+重试 / 写 401 不 replay / GET 单次 401 refresh）不变。CHANGELOG 各节用 "原 1.X.0"
+注解标出来源。
+
+- **S1（原 v1.6.0 / U-1 / 后端 G1）**——6 个分页列表读端点：`listEvidenceAssets`
+  / `listTimestamps` / `listEvidencePackages` / `listReports` /
+  `listSigningEnvelopes` / `listSealApprovals`。统一走 `GET .../page`，返回 yudao
+  `PageResult<T>`（`{ total, list }`），请求参数继承共享 `PageRequest`。
+- **S2（原 v1.7.0 / U-5 + U-6 / 后端 G2）**——capability gate + 操作投影读：
+  `getCapabilities` / `getFeatureGate(action)` / `listOperations` / `getOperation`。
+  能力闸门拿不到时必须 fail-closed。
+- **S3（原 v1.8.0 / U-7 / 后端 G3）**——TSA 只读视图：`listTsaProviders` /
+  `getTsaStats`。
+- **S4（原 v1.9.0 / U-10 + U-12 子集 / 后端 G4）**——envelope 收尾：
+  `listEnvelopeContracts` / `listEnvelopeProviderRequests`（GET 读，返回普通数组
+  而非 `PageResult`），`voidEnvelope`（写，带 `Idempotency-Key`，`reason` 随 body
+  提交）。envelope 的 send / remind / authorize / download / token 等 W3 闸门动作
+  仍后端推迟。
+- **S5（原 v1.10.0 / U-2 / 后端 G5）**——合同模板 9 个方法 DRAFT → PUBLISHED →
+  ARCHIVED 全生命周期：`createContractTemplate` / `updateContractTemplate` /
+  `deleteContractTemplate` / `getContractTemplate` / `listContractTemplates` /
+  `uploadContractTemplatePdf` / `publishContractTemplate` /
+  `archiveContractTemplate` / `listContractTemplateVersions`。新增 2 个 scope
+  `compliance:contract_template:{read,write}`（不要求 step-up）。
+- **S6（原 v1.11.0 / U-4 / 后端 G6）**——用印执行分页：`listSealUses`。复用既有
+  `compliance:contract_signing:read` scope，不引入新 scope。
+
+> 当前 compliance scope 总数 **15** 个（首发 12 + v1.3.2 `compliance:reports:write`
+> + S5 两个 contract_template = 15；其中 `compliance:reports:publish` 在首发批次
+> 内）。`complianceScopes()` 返回全部 15 个；生产建议按最小集合申请。
+
+## 8. 构建
+
+- 工具：**tsup**
+- 命令：`npm run build`
+- 产物结构：
+  - `dist/node/` — Node ESM (`.mjs`) + CJS (`.cjs`) + `.d.ts`
+  - `dist/browser/` — Browser ESM + `.d.ts`
+  - `dist/` — Deno/Bun ESM + `.d.ts`
+- 大小：~120KB（压缩前）
+- `package.json.files`：`dist`、`README.md`、`CHANGELOG.md`、`LICENSE`、
+  `docs/compliance.md`、`examples/`
+- `prepublishOnly` 钩子：`typecheck && lint && test && build && test:pack`（npm publish 前自动跑）
+
+## 9. 发布流程
+
+### 9.1 一次性配置（首次发布前）
+
+#### A. 公开仓 GitHub Repo
+
+```
+github.com/acosmi/sdk-ts (public, MIT)
+```
+
+由企业账号 `acosmi`（lowercase）持有。
+
+#### B. 获取独立 SDK 仓
+
+```bash
+git clone https://github.com/acosmi/sdk-ts.git
+cd sdk-ts
+git config user.name "acosmi-fushihua"
+git config user.email "fushihua@acosmi.com"
+```
+
+> 用 HTTPS（不是 SSH），避免 host key verification 失败。
+
+#### C. npm Token（**关键**：bypass 2FA）
+
+| Token 类型 | bypass 2FA | 推荐度 |
+|------------|------------|--------|
+| **Classic Publish token** | ❌（账号开 2FA 时不能用 CI） | 不推荐 |
+| **Classic Automation token** | ✅（天然 bypass） | 推荐（最简单） |
+| **Granular Access Token** | ⚠️ 默认 ❌，**必须勾选 "Bypass two-factor authentication"** | 推荐（颗粒度细） |
+
+**Granular Token 配置步骤**：
+1. npmjs.com → Account → Granular Access Tokens → Generate New Token
+2. Name：`acosmi-sdk-ts-ci`
+3. Expiration：建议 1 年
+4. Permissions：Read & Write
+5. Packages：选 `@acosmi/sdk-ts`
+6. **勾选 "Bypass two-factor authentication when publishing"** ← 漏勾就 E403
+7. 复制 token
+
+**GitHub repo Secret**：
+- repo → Settings → Secrets and variables → Actions → New repository secret
+- Name: `NPM_TOKEN`
+- Value: 上一步 token
+
+#### D. 验证 release.yml
+
+公开仓 `.github/workflows/release.yml` 关键内容：
+
+```yaml
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    # JS-based actions (checkout / setup-node / action-gh-release) 走 Node 24，
+    # 提前进入 2026-06-02 GitHub 默认状态，避免 Node 20 弃用 annotation。
+    env:
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: 'true'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          # CI 跑 Node 24（Active LTS），与 JS-action 运行时一致；
+          # SDK consumer 仍按 package.json engines.node >=18 兼容承诺。
+          node-version: '24'
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm ci
+      - run: npm run typecheck
+      - run: npm run lint
+      - run: npm test
+      - run: npm run build
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+```
+
+### 9.2 每次发布
+
+```bash
+# === Step 1：确认 SDK 独立仓 ===
+cd /Users/fushihua/Desktop/Acosmi/acosmi-sdk-ts
+git rev-parse --show-toplevel
+git remote -v
+git status --short
+
+# === Step 2：改源码 + 文档 + 升 version ===
+npm run typecheck
+npm run lint
+npm test
+npm run build
+npm run test:pack
+npm pack --dry-run
+
+# === Step 3：审计 ===
+git diff --check
+git diff --stat
+# 额外执行敏感材料扫描，确认没有证书、私钥、keystore、真实 provider endpoint、raw payload。
+
+# === Step 4：提交并推送当前分支 ===
+git add <sdk files>
+git commit -m "feat: add compliance SDK client"
+git push
+
+# === Step 5：发布 tag（会触发 npm publish）===
+# 只有在确认要触发 npm/GitHub Release 时才执行：
+git tag vX.Y.Z
+git push origin vX.Y.Z
+```
+
+### 9.3 公开仓清洁度检查（push 前必看）
+
+- [ ] 作者 = `acosmi-fushihua <fushihua@acosmi.com>`，提交信息干净
+- [ ] commit 范围只包含 SDK 发布相关文件
+- [ ] 没有 Java / Go / CFCA real provider 改动
+- [ ] `docs/` 不包含内部 audit 文档或 provider runbook
+- [ ] `.github/workflows/release.yml` 存在
+- [ ] `package.json` `"version"` 已升
+- [ ] `package.json` `"private"` 字段不存在或为 `false`
+- [ ] 不含 `dist/` `node_modules/` `.eslintcache`
+- [ ] 不含证书、私钥、JKS/PFX/P12、zip、jar、口令、真实 provider endpoint、provider raw payload
+
+## 10. 版本号策略
+
+**自 2026-05-22 起版本策略以 TS 为准**：TS SDK 是主实现，独立演进；Go SDK `acosmi-sdk-go`
+暂停维护，原"Go + TS 主版本号联动"约束已挂起，TS 不再等 Go 对齐版本号。
+
+- **minor**（1.x.0）：新业务方法 / 新域 / 向后兼容的协议扩展
+- **patch**（1.x.y）：bug fix、文档、内部 refactor
+- **major**（x.0.0）：wire-format 不兼容变更、API 移除、TokenStore 接口变化
+
+> 历史背景：v1.0.0 时曾约定 Go + TS 主版本号同步、patch 各自独立。该联动机制因 Go SDK
+> 暂停维护已挂起。将来 Go SDK 从 TS 反向翻译重启时（见 §11、计划 §3），版本对齐策略需
+> 重新评估，本节届时一并修订。
+
+## 11. Go SDK 反向翻译流程（当前暂停）
+
+> **状态：暂停**。本节描述的是将来 Go SDK 重启时的方向，目前不执行。
+
+历史上本节是「Go SDK 升级 → 镜像到 TS」的同步流程；自 2026-05-22 起 TS 成为主实现、
+Go SDK 暂停维护，该 Go→TS 镜像流程已不再适用。
+
+未来方向（计划 §3）：待 TS SDK 稳定后，从 **TS 反向翻译补齐 Go**，方向是 TS→Go。
+反向翻译以 §5「跨语言契约印记」为基准：
+
+- 导出的类型 / 方法 / 错误**符号名**跨语言一致，作为 TS↔Go 对照锚点
+- **snake_case wire-format 字段名**严格一致（wire 协议契约不可漂移）
+- **bug-for-bug 行为对齐**（retry POST=false 默认、sanitize thinking 硬豁免等）
+- 翻译时引入 Go 端不可避免的偏移（`(val, err)` 多返回值、`context.Context`、channel 流等，见 §5 偏移表的反向）
+
+在 Go SDK 重启反向翻译之前，TS SDK 的发版只走 §9.2，不需要任何 Go 侧同步动作。
+
+## 12. 故障排查
+
+### 12.1 npm publish 失败
+
+| 错误 | 原因 | 排查 |
+|------|------|------|
+| `403 Forbidden` "Two-factor authentication or granular access token with bypass 2fa enabled is required" | Token 没开 bypass 2FA | 重建 Granular token，**勾选 "Bypass two-factor authentication"**；或换 Classic Automation token |
+| `403 Forbidden`（其他） | `NPM_TOKEN` secret 失效 / 包名权限不够 | 重建 token，确保 packages 选了 `@acosmi/sdk-ts` |
+| `EPUBLISHCONFLICT` / `cannot publish over the previously published versions` | 没升 version | 升 `package.json` `"version"` |
+| `package private` | `package.json` 还有 `"private": true` | 删掉或改 `false` |
+| `provenance attestation failed` | 仓库 visibility / OIDC 配置不对 | workflow 里**去掉** `--provenance` flag |
+| `404 Not Found` 在 publish 时 | 包名拼错或 `publishConfig.access` 缺 | `package.json` 加 `"publishConfig": { "access": "public" }` |
+
+### 12.2 typecheck 失败
+
+- 改了某个域的 wire-format 类型（`src/models/types.ts` / `src/compliance/**/types.ts` 等）→ 检查所有 caller
+- import 路径错 → `npm run typecheck` 输出文件:行号
+- TS strict 默认开 → 看具体 error，不要图方便加 `as any`
+
+### 12.3 test 失败
+
+- `routing.test.ts` 红 = **P0 红线破坏，严重停车**，立刻回滚
+- `history.test.ts` 红 = sanitize 行为漂移（检查 thinking 豁免 / tool_use_id 联动）
+- `anthropic-build.test.ts` 红 = adapter buildRequestBody 行为变了（确认是有意的契约变更，而非回归）
+
+### 12.4 公开仓 push 失败
+
+| 错误 | 排查 |
+|------|------|
+| `Host key verification failed` | 把 remote URL 从 `git@github.com:` 改成 `https://github.com/` |
+| `Updates were rejected because the remote contains work` | 先 `git fetch` + `git pull --ff-only`；只有维护者明确要重写历史时才 force push |
+| `This repository moved. Please use the new location` | 仓库被 transfer 了，更新 remote URL（见原始 enterprise repo） |
+| GitHub Contributors 显示异常作者 | 检查本地 `git config user.name/user.email`，必要时修正后重新提交 |
+
+### 12.5 下游 crabcode 报 type / 模块 缺失
+
+- 检查 `package.json` `exports` 字段 `types` 是否齐
+- `dist/node/index.d.ts` 必须存在（build 产物）
+- `npm pack --dry-run` 看实际 publish 内容
+- 用户问"缺 X" → 先核 SDK 仓 `src/` 是否已实现该能力 → 多数是 README 未文档化（更新 README）；若确实未实现则按需新增
+
+## 13. 下游消费指引
+
+下游产品（crabcode / crabclaw / 任意第三方）使用方式：
+
+```bash
+npm install @acosmi/sdk-ts
+```
+
+```ts
+import { Client } from '@acosmi/sdk-ts';
+const client = new Client({ serverURL: process.env.ACOSMI_SERVER_URL! });
+```
+
+完整 API 文档见公开仓 [README.md](../README.md)。
+
+下游报"缺 X"时先按 §12.5 排查；如确实未实现，新增 issue → 主仓改 → 走发布流程。
+
+## 14. 发布前严格审计（5-phase）
+
+每次重大发版（含首次发版 / API 重构）必走：
+
+| Phase | 内容 | 输出 |
+|-------|------|------|
+| **A. TS 代码审计** | `src/core/client.ts` + 各业务域 barrel 与子模块逐文件 + 红线扫描 | P0/P1/P2 issue 列表 |
+| **B. Wire-format 对齐** | 50+ struct 的 snake_case 字段名 + 类型 + optional 标记守住跨语言契约（§5）| 0 偏移确认 |
+| **C. 脚手架审计** | package.json / tsup / .npmignore / release.yml / README | 0 漏配置 |
+| **D. 开发手册自审** | 本文件各节是否覆盖实际流程 | 修订列表 |
+| **E. Go SDK 自审** | **暂停** —— Go SDK `acosmi-sdk-go` 已停止维护，无须同步自审；待 Go 从 TS 反向翻译重启后再恢复本 Phase | —（当前不执行）|
+
+四绿 PASS 后再走 §9.2。审计报告归档主仓 `docs/audit/acosmi-sdk-ts-发布前严格复核审计-YYYY-MM-DD.md`，**不进公开仓**。
+
+## 15. 关键文档与链接
+
+- 用户文档：[README.md](../README.md)（公开仓 + 主仓同步）
+- 端口完成档：主仓 `docs/audit/TS-SDK-端口完成-2026-05-01.md`
+- 端口初稿计划：主仓 `docs/audit/acosmi-sdk-ts-port-初稿计划-2026-05-01.md`
+- 严格审计报告：主仓 `docs/audit/acosmi-sdk-ts-发布前严格复核审计-2026-05-01.md`
+- npm 包：https://www.npmjs.com/package/@acosmi/sdk-ts
+- npm 旧包名（待 deprecate）：https://www.npmjs.com/package/acosmi-sdk-ts — 1.0.0 已发布占位；下次新版发布时单独窗口执行 `npm deprecate acosmi-sdk-ts@1.0.0 "Renamed to @acosmi/sdk-ts"`
+- 公开仓：https://github.com/acosmi/sdk-ts
+- Go SDK 端口源：https://github.com/acosmi/acosmi-sdk-go
+
+## 16. 维护者
+
+- 源码改动：SDK 独立仓维护者
+- 公开仓：通过 §9.2 流程提交与发布，不接受无维护者确认的外部发布 PR
+- npm 包：GitHub Actions 自动发布（push tag v* 触发）
+- 安全 Issue：通过 GitHub Security Advisory 私下沟通
+
+## 17. v1.0.0 翻车教训 + 烟测加固（2026-05-01）
+
+### 时间线
+
+- 2026-05-01 07:51:35Z — `npm publish @acosmi/sdk-ts@1.0.0`（首发，CI 自动）
+- 同日 — 下游 crabcode（Anthropic 兼容格式消费方）反馈 P0 双层 broken
+- 同日 — 源码侧 7 commit 修复落地（C0~C6: 4d53585 → 885c08a）
+- 同日 — SDK 公开仓同步并重写为干净发布提交（commit `e60a88e → 0d8c0a9`）
+- 同日 — `git tag v1.0.1 && git push origin v1.0.1` 触发 release.yml CI 自动 npm publish
+- 同日 — `npm publish @acosmi/sdk-ts@1.0.1` 完成（tarball 594.4 kB / 36 文件 / shasum `f8805a04..` / SLSA v1 provenance）
+- 同日 — audit Part 2: `npm i @acosmi/sdk-ts@1.0.1` consumer 视角实拉 + smoke `tsc --noEmit` 全绿，9 处 declare module 在 dist/node/index.d.ts 行 548/571/592/601/645/654/677/720/761 全包名
+- 同日 — `npm deprecate @acosmi/sdk-ts@1.0.0 'broken packaging, use 1.0.1+'`（手动单独跑，CI 不含）
+
+### 翻车的两层根因
+
+| 层 | 现象 | 根因 |
+| --- | --- | --- |
+| Layer 1 — packaging | bun / Node ESM `Cannot find module '@acosmi/sdk-ts'` | `tsup.config.ts` 无 `outExtension`（默认输出 `.js + .cjs`），`package.json.exports` 8 处写死 `.mjs` 引用，两侧无对账 |
+| Layer 2 — d.ts augmentation | consumer 项目 `getBalance` / `submitBugReport` 等 50+ 方法 TS2339 | 9 处 `declare module` 用相对路径（`'../client'` / `'./client'`），tsup 打包 d.ts 不做 path rewrite，consumer 视角下相对路径指向不存在的文件 |
+| 流程根因 | publish 前没拦截 | `prepublishOnly` 仅跑源码侧（typecheck / lint / vitest / build），不验证 **packed product 在 consumer 视角能否解析** |
+
+### 修复点
+
+- **Layer 1**：`tsup.config.ts` 三 entry 显式 `outExtension: ({ format }) => ({ js: format === 'esm' ? '.mjs' : '.cjs' })`
+- **Layer 2**：9 处 `declare module '../client'` / `'./client'` → `declare module '@acosmi/sdk-ts'`；附加 `tsconfig.json` 的 `paths` 让源码 typecheck self-reference
+- **流程**：新增 `scripts/smoke-pack.mjs` + `prepublishOnly` 末尾 `&& npm run test:pack`
+
+### 烟测脚本设计要点
+
+- **跨平台**：用 `spawnSync` 不用 `exec/execSync`（无 shell injection）；`shell: isWin`（Node 20.12+ Windows 安全限制 CVE-2024-27980 修复后跑 `.cmd` 必需）
+- **隔离 consumer**：`mkdtempSync(os.tmpdir())` 临时目录，不污染 caller 的 `node_modules`
+- **覆盖 9 处 augmentation**：`smoke.ts` 内调用每个 `declare module` 文件至少一个 method（`getBalance` / `getWalletStats` / `listTokenPackages` / `listNotifications` / `listTools` / `browseSkillStore` / `submitBugReport` / `applyRequestSanitizers` / WS `connect` typeof 验证）
+- **失败保留**：smoke 失败时保留临时目录供调试；成功才清理
+
+### 未来发版前必读
+
+1. **任何改 `tsup.config.ts` / `package.json.exports` / `declare module` 的 PR**，merge 前必须本地跑 `npm run test:pack`
+2. **publish 流程**：`npm publish` 会自动跑 `prepublishOnly`（含 `test:pack`）；不可手动跳过
+3. **新增 augmentation 时**：`smoke.ts` 内补对应 method 调用，确保 consumer 视角验证覆盖
+4. **手动 deprecate 已发布版本**：`npm deprecate @acosmi/sdk-ts@<version> '<reason>'`（无法撤回但可加警告）
+
+### 详细变更
+
+**历史修复 commits**：
+- `f4972d3` C1 Layer 1 — tsup outExtension
+- `1597d61` C2 Layer 2a — 6 处 `src/client/*.ts` declare module 绑包名 + tsconfig paths self-reference
+- `47e7307` C3 Layer 2b — 3 处 `src/{ws,sanitize-bridge,bug-report}.ts` declare module 绑包名
+- `9f94561` C4 Layer 3 — 新建 `scripts/smoke-pack.mjs` + `prepublishOnly` 加 `test:pack`
+- `b8feb5b` C5 版本同步 1.0.0 → 1.0.1
+- `885c08a` C6 文档闭环 — README + CHANGELOG + 本节 + `package.json.files` 加 CHANGELOG.md
+
+**SDK 公开仓发布历史**：
+- `0d8c0a9` release: v1.0.1 — 19 文件 745+/192-（amend + reset-author 自 `e60a88e`）
+- tag: `v1.0.1` → 触发 release.yml CI
+
+**npm registry 实拉验证** (audit Part 2 PASS)：
+- 包: `@acosmi/sdk-ts@1.0.1`
+- tarball: `https://registry.npmjs.org/@acosmi/sdk-ts/-/sdk-ts-1.0.1.tgz`
+- shasum: `f8805a0443c9b36ce7d559bd333a472ecb8fcef4`
+- integrity: `sha512-CwJMxyCRULQCZT34O/dACSR65bjkRDY2T357oc0q31YFEw8LDEA/+r1Kuy7u/MmuZlsXc0q85cxFjcVcn5RgkA==`
+- 包大小: 594.4 kB / 解包 2.42 MB / 36 文件
+- provenance: SLSA v1（CI 自动签 attestation）
+- 0 production vulnerabilities（vitest devDep 链 esbuild GHSA-67mh-4wv8-2f99 不进 production，作技术债务下个 patch 处理）
+- consumer 视角 smoke `tsc --noEmit` 全绿；dist/node/index.d.ts 9 处 declare module 全 `'@acosmi/sdk-ts'`（line 548/571/592/601/645/654/677/720/761）
+
+**完整执行档**：主仓 `docs/audit/sdk-ts-1.0.0-fix-plan-2026-05-01.md`
+**CHANGELOG**：`./CHANGELOG.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acosmi/sdk-ts",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Acosmi TypeScript SDK：模型网关、Agent Run Gateway 与 Compliance（电子证据、时间章、报告、签署 envelope）统一客户端，支持浏览器 / Node ≥18 / Deno / Bun。",
   "type": "module",
   "main": "./dist/node/index.cjs",
@@ -41,6 +41,8 @@
     "CHANGELOG.md",
     "LICENSE",
     "docs/compliance.md",
+    "docs/pii-role-matrix.md",
+    "docs/开发与发布手册.md",
     "examples"
   ],
   "scripts": {