@h-ai/cli 0.1.0-alpha.66 → 0.1.0-alpha.67

package/templates/skills/hai-capacitor/reference.md

@@ -42,12 +42,14 @@ await capacitor.close()
 
 ### 2. Token 安全存储（与 api-client 配合）
 
+先复用应用已有的 API 初始化入口。示例中的 `apiBase` 由应用解析公开运行配置，已经包含 API 前缀，不重复拼接 `/api/v1`。Web 部署可通过 `runtime-config.js` 覆盖地址；原生包在复制静态资源前设置公开配置。
+
 ```typescript
 import { apiClient } from '@h-ai/api-client'
 import { createCapacitorTokenStorage } from '@h-ai/capacitor'
 
 await apiClient.init({
-  baseUrl: import.meta.env.PUBLIC_API_BASE,
+  baseUrl: apiBase,
   auth: {
     storage: createCapacitorTokenStorage(),
   },
@@ -236,7 +238,7 @@ export async function initCapacitor() {
 
 ### SPA 模式配置（必需）
 
-Capacitor 应用使用 Vite 构建 SPA，并让原生壳读取 `dist`：
+Capacitor 原生壳读取 `webDir` 指定的静态产物。纯 Vite 模板默认为 `dist`；SvelteKit 项目需配置静态适配器，输出可能是 `build`。构建器、容器与 `webDir` 必须一致，以下是 Vite 示例：
 
 ```typescript
 // capacitor.config.ts
@@ -258,9 +260,9 @@ export default config
 import { apiClient } from '@h-ai/api-client'
 import { createCapacitorTokenStorage } from '@h-ai/capacitor'
 
-export async function initApi() {
+export async function initApi(apiBase: string) {
   return apiClient.init({
-    baseUrl: `${import.meta.env.PUBLIC_API_BASE}/api/v1`,
+    baseUrl: apiBase,
     auth: {
       storage: createCapacitorTokenStorage(),
     },

package/templates/skills/hai-ci/SKILL.md

@@ -52,6 +52,8 @@ pnpm test
 
 从当前 package.json 确认实际 scripts，使用声明的最低 Node 版本验证并与 engines/README 同步；PowerShell 使用 `pnpm.cmd`。测试内容由 `hai-app-tests` 定义；本技能决定门禁如何稳定执行。
 
+AI 本地验收和排查按 [分轮验证与集中修复](../hai-app-tests/validation.md) 收集所有可执行结果，再集中修复；普通失败不立即从头重跑。独立 CI job 可继续收集结果，真实前置失败则阻塞其依赖 job；必需检查与发布步骤仍须全部成功，不以继续收集为由设置 `continue-on-error` 或放行失败。
+
 lint/typecheck 只能执行已配置的规则。新增开发规范时区分可静态检测项（如显式 any/console.log）与必须行为验收项（如资源越权、事务/幂等、失败结果、生命周期清理），后者在适用单元/集成/E2E 中验证。禁止通过关闭规则、添加无依据忽略或把 `|| true` 加到门禁来“统一风格”。
 
 ### E2E 策略

package/templates/skills/hai-core/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hai-core
-description: "使用 @h-ai/core 配置、日志、i18n、ID、Zod 错误本地化和 HaiResult。"
+description: "配置 hai 应用启动、YAML/环境变量、日志、i18n 与 HaiResult；排查配置覆盖和错误本地化。"
 ---
 
 # hai-core
@@ -18,7 +18,7 @@ description: "使用 @h-ai/core 配置、日志、i18n、ID、Zod 错误本地
 ## 使用路径
 
 - Node 启动用 core.init({ configDir }) 加载配置；勿传 logging 覆盖 _core.yml 中的日志设置，除非任务明确要求。
-- 应用名称、版本、环境、默认语言和日志设置统一从 `_core.yml` 经 core.config 获取，日志使用 core.logger；UI 不另维护硬编码副本。SvelteKit layout / fullstack app.info 仅下发公开字段白名单；独立 Vite mobile-app 在 Node 构建时解析并注入公开值，修改配置后重新构建。浏览器不加载 YAML，不接收完整模块配置、密钥或日志脱敏上下文。
+- 应用名称、版本、环境、默认语言和日志设置统一从 `_core.yml` 经 core.config 获取，日志使用 core.logger；UI 不另维护硬编码副本。SvelteKit layout / fullstack app.info 仅下发公开字段白名单；独立 Vite mobile-app 在 Node 构建时解析并注入公开默认值，修改这些编译默认值需要重新构建。静态 Web 的公开 API 地址等通过 `runtime-config.js` 覆盖时无需重建镜像，原生包在复制静态资源前准备配置入口。浏览器不加载 YAML，不接收完整模块配置、密钥或日志脱敏上下文。
 - `HAI_<配置名>_<路径>` 可整体覆盖根/对象/数组；父节点优先，未覆盖时才遍历已有叶子。camelCase 不拆词，约定变量优先于显式插值。
 - 环境文件采用六类：`.env.example` 完整列出字段用途、默认值、枚举和范围；`.env` 为公共基础；`.env.dev`、`.env.test`、`.env.prod` 为公共环境覆盖，这五类均提交 Git。`.env.local` 为本机私有配置，不提交 Git。优先级为进程环境 > `.env.local` > 环境文件 > `.env`；Vite 在 Node 配置阶段调用 `core.config.loadEnvFiles({ mode, envDir })` 并检查 success 后注入进程，Node 脚本按相同顺序传入 `--env-file`。`core.init` 不自行读取 dotenv。
 - 配置 getter 与 ID/logger 方法不是 HaiResult；validate/load 等须检查 success。
@@ -26,7 +26,7 @@ description: "使用 @h-ai/core 配置、日志、i18n、ID、Zod 错误本地
 
 ## 按需参考
 
-详细配置、API 签名、错误码和范本在 [reference.md](reference.md)。按下列标题定位所需小节，不默认通读；用例中的业务变量需结合当前应用补齐。
+按任务读取 [reference.md](reference.md) 的对应小节；签名以当前源码或安装版本的公开类型为准，不默认加载全部资料。示例中的业务变量由应用提供。
 
 - 运行环境
 - 适用场景

package/templates/skills/hai-crypto/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hai-crypto
-description: "使用 @h-ai/crypto 进行 SM2/SM3/SM4、密码哈希与传输加密。"
+description: "实现 SM2/SM3/SM4 加解密、验签、密码哈希，或通过 serv/kit/api-client 接入传输加密。"
 ---
 
 # hai-crypto
@@ -11,261 +11,25 @@ description: "使用 @h-ai/crypto 进行 SM2/SM3/SM4、密码哈希与传输加
 | --- | --- |
 | 能力 | 使用 @h-ai/crypto 进行 SM2/SM3/SM4、密码哈希与传输加密 |
 | 适用场景 | 应用加密、验签、密码保存或传输保护 |
-| 输入 | CryptoConfigInput、字节/文本、密钥和 transport 装配选项 |
+| 输入 | 无参 init、字节/文本、密钥和 transport 装配选项 |
 | 输出 | 加解密/验签的 HaiResult；transport 工厂按公开类型使用 |
 | 限制 | 先 init；password 仅服务端，浏览器仅支持部分能力。传输通过 serv/kit/api-client 顶层装配，不导入内部工厂。 |
 
-> `@h-ai/crypto` 提供非对称加密、哈希、对称加密与密码哈希能力，支持 Node.js 与浏览器双端。
+## 使用路径
 
-## 运行环境
+1. `crypto.init()` 无配置参数，检查结果；确认目标端是否支持所需能力，password 仅 Node。
+2. 选用公开 asymmetric/hash/symmetric/password 操作，检查 HaiResult；SM3 HMAC 不等同于 SHA-256 HMAC。
+3. 传输加密经 serv/kit/api-client 顶层配置接入，统一协商与刷新路径；不导入内部工厂。
+4. 验证加解密往返、错误密钥/签名和关闭，密钥与明文不写日志或浏览器公开配置。
 
-**Node.js + 浏览器双端可用。** 浏览器端通过 `crypto.init()` 初始化（无需配置参数）。
+## 按需参考
 
-| 能力 | Node.js | 浏览器 | 说明 |
-|------|---------|--------|------|
-| `crypto.asymmetric` 非对称加密 | ✅ | ✅ | SM2 加解密、签名验签 |
-| `crypto.hash` 哈希 | ✅ | ✅ | SM3 哈希、HMAC |
-| `crypto.symmetric` 对称加密 | ✅ | ✅ | SM4 ECB/CBC |
-| `crypto.password` 密码哈希 | ✅ | ❌ | 依赖 Node.js crypto（服务端专用） |
-| `crypto.transport` 传输加密 | ✅ | ✅ | 服务端管理器 + 客户端 encryptedFetch |
+按本次操作读取对应小节；以已安装版本的公开类型核验签名，示例中的业务变量由应用提供。
 
-浏览器端主要用于 kit 传输加密场景（`kit.client.create({ transport: { crypto } })`），一般不需要直接调用 crypto API。
-
-## 适用场景
-
-- 非对称加密/解密、签名/验签、密钥生成
-- 哈希计算与 HMAC
-- 对称加密/解密（ECB/CBC 模式）
-- 密码存储与验证（加盐迭代哈希）
-- 传输加密：为 serv / kit / api-client 提供统一协议、密钥协商和请求响应加解密
-
-## 使用步骤
-
-### 1. 初始化与关闭
-
-```typescript
-import { crypto } from '@h-ai/crypto'
-
-await crypto.init()
-
-// 使用后关闭
-await crypto.close()
-```
-
-## 核心 API
-
-### 非对称加密 — `crypto.asymmetric`
-
-| 方法                | 签名                                                        | 说明         |
-| ------------------- | ----------------------------------------------------------- | ------------ |
-| `generateKeyPair`   | `() => HaiResult<KeyPair>`                                     | 生成密钥对   |
-| `encrypt`           | `(data, publicKey, options?) => HaiResult<string>`             | 公钥加密     |
-| `decrypt`           | `(ciphertext, privateKey, options?) => HaiResult<string>`      | 私钥解密     |
-| `sign`              | `(data, privateKey, options?) => HaiResult<string>`            | 私钥签名     |
-| `verify`            | `(data, signature, publicKey, options?) => HaiResult<boolean>` | 公钥验签     |
-| `isValidPublicKey`  | `(key: string) => boolean`                                  | 校验公钥格式 |
-| `isValidPrivateKey` | `(key: string) => boolean`                                  | 校验私钥格式 |
-
-```typescript
-const keyPair = crypto.asymmetric.generateKeyPair()
-if (keyPair.success) {
-  const { publicKey, privateKey } = keyPair.data
-
-  const encrypted = crypto.asymmetric.encrypt('敏感数据', publicKey)
-  if (encrypted.success) {
-    const decrypted = crypto.asymmetric.decrypt(encrypted.data, privateKey)
-  }
-
-  const signature = crypto.asymmetric.sign('待签名数据', privateKey)
-  if (signature.success) {
-    const valid = crypto.asymmetric.verify('待签名数据', signature.data, publicKey)
-  }
-}
-```
-
-**AsymmetricEncryptOptions**：`{ cipherMode?: 0 | 1, outputFormat?: 'hex' | 'base64' }`
-**SignOptions**：`{ hash?: boolean, userId?: string }`
-
-### 哈希 — `crypto.hash`
-
-| 方法     | 签名                                                       | 说明     |
-| -------- | ---------------------------------------------------------- | -------- |
-| `hash`   | `(data: string \| Uint8Array, options?) => HaiResult<string>` | 哈希     |
-| `hmac`   | `(data, key) => HaiResult<string>`                            | HMAC     |
-| `verify` | `(data, expectedHash) => HaiResult<boolean>`                  | 验证哈希 |
-
-```typescript
-const hash = crypto.hash.hash('hello')
-const hmac = crypto.hash.hmac('hello', 'secret-key')
-const valid = crypto.hash.verify('hello', hash.data!)
-```
-
-**HashOptions**：`{ inputEncoding?: 'utf8' | 'hex' }`
-
-### 对称加密 — `crypto.symmetric`
-
-| 方法            | 签名                                            | 说明                        |
-| --------------- | ----------------------------------------------- | --------------------------- |
-| `generateKey`   | `() => string`                                  | 生成 128-bit 密钥（32 hex） |
-| `generateIV`    | `() => string`                                  | 生成随机 IV（32 hex）       |
-| `encrypt`       | `(data, key, options?) => HaiResult<SymmetricEncryptedPayload>` | 加密（返回结构化密文）      |
-| `decrypt`       | `(payload, key) => HaiResult<string>`          | 解密结构化密文              |
-| `encryptWithIV` | `(data, key) => HaiResult<EncryptWithIVResult>`    | CBC 模式加密（自动生成 IV） |
-| `decryptWithIV` | `(ciphertext, key, iv) => HaiResult<string>`       | CBC 模式解密                |
-| `deriveKey`     | `(password, salt) => string`                    | 从密码和盐值派生密钥        |
-| `isValidKey`    | `(key: string) => boolean`                      | 校验密钥格式                |
-| `isValidIV`     | `(iv: string) => boolean`                       | 校验 IV 格式                |
-
-```typescript
-const key = crypto.symmetric.generateKey()
-
-// 默认安全用法：CBC + 自动 IV，返回 { mode, ciphertext, iv, encoding }
-const encrypted = crypto.symmetric.encrypt('明文数据', key)
-if (encrypted.success) {
-  const decrypted = crypto.symmetric.decrypt(encrypted.data, key)
-}
-
-// 需要单独存储 IV 时使用结构化结果
-const withIV = crypto.symmetric.encryptWithIV('明文数据', key)
-if (withIV.success) {
-  const decrypted = crypto.symmetric.decryptWithIV(withIV.data.ciphertext, key, withIV.data.iv)
-}
-```
-
-**SymmetricEncryptOptions**：`{ mode?: 'ecb' | 'cbc', iv?: string, outputFormat?: 'hex' | 'base64' }`
-**SymmetricEncryptedPayload**：`{ mode: 'ecb' | 'cbc', ciphertext: string, iv?: string, encoding: 'hex' | 'base64' }`
-
-> `encrypt()` 默认使用 CBC 并自动生成 IV。ECB 会泄漏明文结构，只有底层协议明确要求时才显式 `{ mode: 'ecb' }`。
-
-### 密码哈希 — `crypto.password`
-
-| 方法     | 签名                                    | 说明     |
-| -------- | --------------------------------------- | -------- |
-| `hash`   | `(password, config?) => HaiResult<string>` | 密码哈希 |
-| `verify` | `(password, hash) => HaiResult<boolean>`   | 验证密码 |
-
-```typescript
-const hashed = crypto.password.hash('MyPassword123')
-if (hashed.success) {
-  const valid = crypto.password.verify('MyPassword123', hashed.data)
-}
-```
-
-哈希格式：`$hai$<iterations>$<salt>$<hash>`
-**PasswordConfig**：`{ saltLength?: number, iterations?: number }`
-
-### 传输加密 — `crypto.transport`
-
-传输加密主工厂必须从 `crypto.transport` 访问；共享 `keyStore` provider 请从 `@h-ai/crypto` 根入口导入，不从子目录内部路径导入。
-
-| 方法 | 签名 | 说明 |
-| --- | --- | --- |
-| `createServer` | `(options?) => HaiResult<TransportEncryptionManager>` | 创建服务端传输加密管理器 |
-| `createClient` | `({ keyExchangeUrl, fetch? }) => TransportClient` | 创建客户端 encryptedFetch 会话 |
-| `protocol` | `TRANSPORT_PROTOCOL` | 协议常量：`X-Client-Id`、`X-Encrypted`、默认协商路径 |
-
-共享 `keyStore` provider（从 `@h-ai/crypto` 根入口导入）：
-
-| 工厂 | 签名 | 说明 |
-| --- | --- | --- |
-| `createInMemoryKeyStore` | `(maxClients?) => TransportKeyStore` | 默认 FIFO 内存实现 |
-| `createRedisTransportKeyStore` | `({ cache, ttlSeconds? }) => TransportKeyStore` | 基于 `@h-ai/cache` 的共享实现，通常配 Redis |
-| `createReldbTransportKeyStore` | `({ reldb, ttlSeconds? }) => TransportKeyStore` | 基于 `@h-ai/reldb` 的共享实现，自动建表 |
-
-```typescript
-const server = crypto.transport.createServer({ maxClients: 10000 })
-if (!server.success)
-  return server
-
-const client = crypto.transport.createClient({
-  keyExchangeUrl: 'https://api.example.com/api/v1/_hai/key-exchange',
-})
-
-const resp = await client.encryptedFetch('https://api.example.com/api/v1/echo', {
-  method: 'POST',
-  body: JSON.stringify({ hello: 'world' }),
-})
-```
-
-```typescript
-import { createRedisTransportKeyStore, crypto } from '@h-ai/crypto'
-import { cache } from '@h-ai/cache'
-
-await cache.init({ type: 'redis', host: '127.0.0.1', port: 6379 })
-
-const sharedServer = crypto.transport.createServer({
-  keyStore: createRedisTransportKeyStore({ cache, ttlSeconds: 3600 }),
-})
-```
-
-使用流程：
-1. 先 `await crypto.init()`。
-2. 服务端 `createServer()` 后暴露一个 POST 密钥协商端点：接收 `clientPublicKey`，返回 `serverPublicKey + clientId`。
-3. 客户端 `createClient({ keyExchangeUrl })` 后，首次 `init()` / `encryptedFetch()` 会自动做密钥协商。
-4. 协商完成后，请求附带 `X-Client-Id`；若请求有 body，则自动包装成 `{ encryptedKey, ciphertext, iv }`。
-5. 服务端先 `decryptRequest()`，业务处理后再 `encryptResponse(clientId, data)`。
-6. 客户端收到 `X-Encrypted: true` 的响应后自动解密；`destroy()` 可清空当前会话。
-
-`encryptedFetch()` 与原生 fetch 一样会 reject：网络错误、密钥协商失败、请求加密失败或响应解密失败都应在调用方按 fetch 错误处理策略捕获。
-
-常规应用优先使用上层封装：
-- serv：`serv.createApp({ transport: { crypto } })`
-- kit：`kit.createHandle({ crypto: { crypto, transport: true } })` + `kit.client.create({ transport: { crypto } })`
-- api-client：`apiClient.init({ transport: { crypto } })`
-
-## 错误码 — `HaiCryptoError`
-
-| 错误码 | code | 说明 |
-|--------|------|------|
-| `HaiCryptoError.INVALID_INPUT` | `hai:crypto:002` | 无效输入 |
-| `HaiCryptoError.INVALID_KEY` | `hai:crypto:003` | 无效密钥 |
-| `HaiCryptoError.NOT_INITIALIZED` | `hai:crypto:010` | 未初始化 |
-| `HaiCryptoError.INIT_FAILED` | `hai:crypto:011` | 初始化失败 |
-| `HaiCryptoError.KEY_GENERATION_FAILED` | `hai:crypto:020` | 密钥生成失败 |
-| `HaiCryptoError.ENCRYPTION_FAILED` | `hai:crypto:021` | 加密失败 |
-| `HaiCryptoError.DECRYPTION_FAILED` | `hai:crypto:022` | 解密失败 |
-| `HaiCryptoError.SIGN_FAILED` | `hai:crypto:023` | 签名失败 |
-| `HaiCryptoError.VERIFY_FAILED` | `hai:crypto:024` | 验签失败 |
-| `HaiCryptoError.HASH_FAILED` | `hai:crypto:040` | 哈希计算失败 |
-| `HaiCryptoError.HMAC_FAILED` | `hai:crypto:041` | HMAC 计算失败 |
-| `HaiCryptoError.INVALID_IV` | `hai:crypto:060` | 无效 IV |
-
-## 常见模式
-
-### 数据加密存储
-
-```typescript
-const key = process.env.HAI_CRYPTO_DATA_KEY!
-const encrypted = crypto.symmetric.encrypt(sensitiveData, key)
-// 存入数据库
-
-// 读取时解密
-const decrypted = crypto.symmetric.decrypt(storedPayload, key)
-```
-
-> 默认密文是结构化对象，必须完整存储 `mode` / `ciphertext` / `iv` / `encoding` 字段；如果数据库字段已拆分 IV 与密文，请改用 `encryptWithIV()` / `decryptWithIV()`。
-
-### 密码存储与验证
-
-```typescript
-// 注册时哈希存储
-const hashResult = crypto.password.hash(userPassword)
-if (hashResult.success) {
-  // 存储 hashResult.data 到数据库
-}
-
-// 登录时验证
-const verifyResult = crypto.password.verify(inputPassword, storedHash)
-if (verifyResult.success && verifyResult.data) {
-  // 密码匹配
-}
-```
-
-## 相关 Skills
-
-- `hai-core`：配置与 HaiResult 模型
-- `hai-iam`：密码哈希（内部自动调用 crypto.password）
-- `hai-kit`：SvelteKit 集成（传输加密）
-- `hai-serv` / `hai-api-client`：跨域 HTTP API 的透明传输加密
-
-管理端在线加密演示直接调用 Crypto SM3/SM4 API，SM4 使用随机临时密钥和 IV，并在显示成功前解密校验；密钥不保存。输入改变即清空旧结果，禁止用随机摘要或 Base64 伪装算法结果。
+- [运行环境](reference.md#运行环境)
+- [适用场景](reference.md#适用场景)
+- [使用步骤](reference.md#使用步骤)
+- [核心 API](reference.md#核心-api)
+- [错误码 — `HaiCryptoError`](reference.md#错误码--haicryptoerror)
+- [常见模式](reference.md#常见模式)
+- [相关 Skills](reference.md#相关-skills)

package/templates/skills/hai-crypto/reference.md

@@ -0,0 +1,256 @@
+# hai-crypto 参考
+
+> `@h-ai/crypto` 提供非对称加密、哈希、对称加密与密码哈希能力，支持 Node.js 与浏览器双端。
+
+## 运行环境
+
+**Node.js + 浏览器双端可用。** 浏览器端通过 `crypto.init()` 初始化（无需配置参数）。
+
+| 能力 | Node.js | 浏览器 | 说明 |
+|------|---------|--------|------|
+| `crypto.asymmetric` 非对称加密 | ✅ | ✅ | SM2 加解密、签名验签 |
+| `crypto.hash` 哈希 | ✅ | ✅ | SM3 哈希、HMAC |
+| `crypto.symmetric` 对称加密 | ✅ | ✅ | SM4 ECB/CBC |
+| `crypto.password` 密码哈希 | ✅ | ❌ | 依赖 Node.js crypto（服务端专用） |
+| `crypto.transport` 传输加密 | ✅ | ✅ | 服务端管理器 + 客户端 encryptedFetch |
+
+浏览器端主要用于 kit 传输加密场景（`kit.client.create({ transport: { crypto } })`），一般不需要直接调用 crypto API。
+
+## 适用场景
+
+- 非对称加密/解密、签名/验签、密钥生成
+- 哈希计算与 HMAC
+- 对称加密/解密（ECB/CBC 模式）
+- 密码存储与验证（加盐迭代哈希）
+- 传输加密：为 serv / kit / api-client 提供统一协议、密钥协商和请求响应加解密
+
+## 使用步骤
+
+### 1. 初始化与关闭
+
+```typescript
+import { crypto } from '@h-ai/crypto'
+
+await crypto.init()
+
+// 使用后关闭
+await crypto.close()
+```
+
+## 核心 API
+
+### 非对称加密 — `crypto.asymmetric`
+
+| 方法                | 签名                                                        | 说明         |
+| ------------------- | ----------------------------------------------------------- | ------------ |
+| `generateKeyPair`   | `() => HaiResult<KeyPair>`                                     | 生成密钥对   |
+| `encrypt`           | `(data, publicKey, options?) => HaiResult<string>`             | 公钥加密     |
+| `decrypt`           | `(ciphertext, privateKey, options?) => HaiResult<string>`      | 私钥解密     |
+| `sign`              | `(data, privateKey, options?) => HaiResult<string>`            | 私钥签名     |
+| `verify`            | `(data, signature, publicKey, options?) => HaiResult<boolean>` | 公钥验签     |
+| `isValidPublicKey`  | `(key: string) => boolean`                                  | 校验公钥格式 |
+| `isValidPrivateKey` | `(key: string) => boolean`                                  | 校验私钥格式 |
+
+```typescript
+const keyPair = crypto.asymmetric.generateKeyPair()
+if (keyPair.success) {
+  const { publicKey, privateKey } = keyPair.data
+
+  const encrypted = crypto.asymmetric.encrypt('敏感数据', publicKey)
+  if (encrypted.success) {
+    const decrypted = crypto.asymmetric.decrypt(encrypted.data, privateKey)
+  }
+
+  const signature = crypto.asymmetric.sign('待签名数据', privateKey)
+  if (signature.success) {
+    const valid = crypto.asymmetric.verify('待签名数据', signature.data, publicKey)
+  }
+}
+```
+
+**AsymmetricEncryptOptions**：`{ cipherMode?: 0 | 1, outputFormat?: 'hex' | 'base64' }`
+**SignOptions**：`{ hash?: boolean, userId?: string }`
+
+### 哈希 — `crypto.hash`
+
+| 方法     | 签名                                                       | 说明     |
+| -------- | ---------------------------------------------------------- | -------- |
+| `hash`   | `(data: string \| Uint8Array, options?) => HaiResult<string>` | 哈希     |
+| `hmac`   | `(data, key) => HaiResult<string>`                            | HMAC     |
+| `verify` | `(data, expectedHash) => HaiResult<boolean>`                  | 验证哈希 |
+
+```typescript
+const hash = crypto.hash.hash('hello')
+const hmac = crypto.hash.hmac('hello', 'secret-key')
+const valid = crypto.hash.verify('hello', hash.data!)
+```
+
+**HashOptions**：`{ inputEncoding?: 'utf8' | 'hex' }`
+
+### 对称加密 — `crypto.symmetric`
+
+| 方法            | 签名                                            | 说明                        |
+| --------------- | ----------------------------------------------- | --------------------------- |
+| `generateKey`   | `() => string`                                  | 生成 128-bit 密钥（32 hex） |
+| `generateIV`    | `() => string`                                  | 生成随机 IV（32 hex）       |
+| `encrypt`       | `(data, key, options?) => HaiResult<SymmetricEncryptedPayload>` | 加密（返回结构化密文）      |
+| `decrypt`       | `(payload, key) => HaiResult<string>`          | 解密结构化密文              |
+| `encryptWithIV` | `(data, key) => HaiResult<EncryptWithIVResult>`    | CBC 模式加密（自动生成 IV） |
+| `decryptWithIV` | `(ciphertext, key, iv) => HaiResult<string>`       | CBC 模式解密                |
+| `deriveKey`     | `(password, salt) => string`                    | 从密码和盐值派生密钥        |
+| `isValidKey`    | `(key: string) => boolean`                      | 校验密钥格式                |
+| `isValidIV`     | `(iv: string) => boolean`                       | 校验 IV 格式                |
+
+```typescript
+const key = crypto.symmetric.generateKey()
+
+// 默认安全用法：CBC + 自动 IV，返回 { mode, ciphertext, iv, encoding }
+const encrypted = crypto.symmetric.encrypt('明文数据', key)
+if (encrypted.success) {
+  const decrypted = crypto.symmetric.decrypt(encrypted.data, key)
+}
+
+// 需要单独存储 IV 时使用结构化结果
+const withIV = crypto.symmetric.encryptWithIV('明文数据', key)
+if (withIV.success) {
+  const decrypted = crypto.symmetric.decryptWithIV(withIV.data.ciphertext, key, withIV.data.iv)
+}
+```
+
+**SymmetricEncryptOptions**：`{ mode?: 'ecb' | 'cbc', iv?: string, outputFormat?: 'hex' | 'base64' }`
+**SymmetricEncryptedPayload**：`{ mode: 'ecb' | 'cbc', ciphertext: string, iv?: string, encoding: 'hex' | 'base64' }`
+
+> `encrypt()` 默认使用 CBC 并自动生成 IV。ECB 会泄漏明文结构，只有底层协议明确要求时才显式 `{ mode: 'ecb' }`。
+
+### 密码哈希 — `crypto.password`
+
+| 方法     | 签名                                    | 说明     |
+| -------- | --------------------------------------- | -------- |
+| `hash`   | `(password, config?) => HaiResult<string>` | 密码哈希 |
+| `verify` | `(password, hash) => HaiResult<boolean>`   | 验证密码 |
+
+```typescript
+const hashed = crypto.password.hash('MyPassword123')
+if (hashed.success) {
+  const valid = crypto.password.verify('MyPassword123', hashed.data)
+}
+```
+
+哈希格式：`$hai$<iterations>$<salt>$<hash>`
+**PasswordConfig**：`{ saltLength?: number, iterations?: number }`
+
+### 传输加密 — `crypto.transport`
+
+传输加密主工厂必须从 `crypto.transport` 访问；共享 `keyStore` provider 请从 `@h-ai/crypto` 根入口导入，不从子目录内部路径导入。
+
+| 方法 | 签名 | 说明 |
+| --- | --- | --- |
+| `createServer` | `(options?) => HaiResult<TransportEncryptionManager>` | 创建服务端传输加密管理器 |
+| `createClient` | `({ keyExchangeUrl, fetch? }) => TransportClient` | 创建客户端 encryptedFetch 会话 |
+| `protocol` | `TRANSPORT_PROTOCOL` | 协议常量：`X-Client-Id`、`X-Encrypted`、默认协商路径 |
+
+共享 `keyStore` provider（从 `@h-ai/crypto` 根入口导入）：
+
+| 工厂 | 签名 | 说明 |
+| --- | --- | --- |
+| `createInMemoryKeyStore` | `(maxClients?) => TransportKeyStore` | 默认 FIFO 内存实现 |
+| `createRedisTransportKeyStore` | `({ cache, ttlSeconds? }) => TransportKeyStore` | 基于 `@h-ai/cache` 的共享实现，通常配 Redis |
+| `createReldbTransportKeyStore` | `({ reldb, ttlSeconds? }) => TransportKeyStore` | 基于 `@h-ai/reldb` 的共享实现，自动建表 |
+
+```typescript
+const server = crypto.transport.createServer({ maxClients: 10000 })
+if (!server.success)
+  return server
+
+const client = crypto.transport.createClient({
+  keyExchangeUrl: 'https://api.example.com/api/v1/_hai/key-exchange',
+})
+
+const resp = await client.encryptedFetch('https://api.example.com/api/v1/echo', {
+  method: 'POST',
+  body: JSON.stringify({ hello: 'world' }),
+})
+```
+
+```typescript
+import { createRedisTransportKeyStore, crypto } from '@h-ai/crypto'
+import { cache } from '@h-ai/cache'
+
+await cache.init({ type: 'redis', host: '127.0.0.1', port: 6379 })
+
+const sharedServer = crypto.transport.createServer({
+  keyStore: createRedisTransportKeyStore({ cache, ttlSeconds: 3600 }),
+})
+```
+
+使用流程：
+1. 先 `await crypto.init()`。
+2. 服务端 `createServer()` 后暴露一个 POST 密钥协商端点：接收 `clientPublicKey`，返回 `serverPublicKey + clientId`。
+3. 客户端 `createClient({ keyExchangeUrl })` 后，首次 `init()` / `encryptedFetch()` 会自动做密钥协商。
+4. 协商完成后，请求附带 `X-Client-Id`；若请求有 body，则自动包装成 `{ encryptedKey, ciphertext, iv }`。
+5. 服务端先 `decryptRequest()`，业务处理后再 `encryptResponse(clientId, data)`。
+6. 客户端收到 `X-Encrypted: true` 的响应后自动解密；`destroy()` 可清空当前会话。
+
+`encryptedFetch()` 与原生 fetch 一样会 reject：网络错误、密钥协商失败、请求加密失败或响应解密失败都应在调用方按 fetch 错误处理策略捕获。
+
+常规应用优先使用上层封装：
+- serv：`serv.createApp({ transport: { crypto } })`
+- kit：`kit.createHandle({ crypto: { crypto, transport: true } })` + `kit.client.create({ transport: { crypto } })`
+- api-client：`apiClient.init({ transport: { crypto } })`
+
+## 错误码 — `HaiCryptoError`
+
+| 错误码 | code | 说明 |
+|--------|------|------|
+| `HaiCryptoError.INVALID_INPUT` | `hai:crypto:002` | 无效输入 |
+| `HaiCryptoError.INVALID_KEY` | `hai:crypto:003` | 无效密钥 |
+| `HaiCryptoError.NOT_INITIALIZED` | `hai:crypto:010` | 未初始化 |
+| `HaiCryptoError.INIT_FAILED` | `hai:crypto:011` | 初始化失败 |
+| `HaiCryptoError.KEY_GENERATION_FAILED` | `hai:crypto:020` | 密钥生成失败 |
+| `HaiCryptoError.ENCRYPTION_FAILED` | `hai:crypto:021` | 加密失败 |
+| `HaiCryptoError.DECRYPTION_FAILED` | `hai:crypto:022` | 解密失败 |
+| `HaiCryptoError.SIGN_FAILED` | `hai:crypto:023` | 签名失败 |
+| `HaiCryptoError.VERIFY_FAILED` | `hai:crypto:024` | 验签失败 |
+| `HaiCryptoError.HASH_FAILED` | `hai:crypto:040` | 哈希计算失败 |
+| `HaiCryptoError.HMAC_FAILED` | `hai:crypto:041` | HMAC 计算失败 |
+| `HaiCryptoError.INVALID_IV` | `hai:crypto:060` | 无效 IV |
+
+## 常见模式
+
+### 数据加密存储
+
+```typescript
+const key = process.env.HAI_CRYPTO_DATA_KEY!
+const encrypted = crypto.symmetric.encrypt(sensitiveData, key)
+// 存入数据库
+
+// 读取时解密
+const decrypted = crypto.symmetric.decrypt(storedPayload, key)
+```
+
+> 默认密文是结构化对象，必须完整存储 `mode` / `ciphertext` / `iv` / `encoding` 字段；如果数据库字段已拆分 IV 与密文，请改用 `encryptWithIV()` / `decryptWithIV()`。
+
+### 密码存储与验证
+
+```typescript
+// 注册时哈希存储
+const hashResult = crypto.password.hash(userPassword)
+if (hashResult.success) {
+  // 存储 hashResult.data 到数据库
+}
+
+// 登录时验证
+const verifyResult = crypto.password.verify(inputPassword, storedHash)
+if (verifyResult.success && verifyResult.data) {
+  // 密码匹配
+}
+```
+
+## 相关 Skills
+
+- `hai-core`：配置与 HaiResult 模型
+- `hai-iam`：密码哈希（内部自动调用 crypto.password）
+- `hai-kit`：SvelteKit 集成（传输加密）
+- `hai-serv` / `hai-api-client`：跨域 HTTP API 的透明传输加密
+
+管理端在线加密演示直接调用 Crypto SM3/SM4 API，SM4 使用随机临时密钥和 IV，并在显示成功前解密校验；密钥不保存。输入改变即清空旧结果，禁止用随机摘要或 Base64 伪装算法结果。