@h-ai/cli 0.1.0-alpha.18 → 0.1.0-alpha.19

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/cli",
   "type": "module",
-  "version": "0.1.0-alpha.18",
+  "version": "0.1.0-alpha.19",
   "description": "Hai Framework CLI for project scaffolding and code generation.",
   "license": "Apache-2.0",
   "keywords": [
@@ -34,7 +34,7 @@
     "ora": "^9.1.0",
     "prompts": "^2.4.2",
     "yaml": "^2.7.0",
-    "@h-ai/core": "0.1.0-alpha.18"
+    "@h-ai/core": "0.1.0-alpha.19"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",

package/templates/apps/android-app/src/lib/api.ts.hbs

@@ -15,7 +15,7 @@ const API_BASE = (import.meta.env.PUBLIC_API_BASE as string | undefined) ?? 'htt
  * 初始化 API 客户端
  *
  * 应在应用启动时调用一次。
- * - Token 存储使用 Capacitor Preferences（原生安全存储）
+ * - Token 存储使用 Capacitor 原生安全存储插件（仅原生环境启用）
  * - 自动附加 Bearer Token、401 自动刷新重试
  */
 export async function initApi() {

package/templates/base/package.json.hbs

@@ -1,6 +1,6 @@
 {
   "name": "{{projectName}}",
-  "version": "0.1.0-alpha.18",
+  "version": "0.1.0-alpha.19",
   "private": true,
   "description": "{{#if_eq appType 'admin'}}Enterprise management system built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'website'}}Enterprise website built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'h5'}}Mobile H5 app built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'api'}}REST API service built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'android-app'}}Android app built with hai Agent Framework{{/if_eq}}",
   "keywords": ["hai", "sveltekit", "svelte5", "{{appType}}"],
@@ -22,35 +22,36 @@
     "clean": "rimraf .svelte-kit build .turbo"
   },
   "dependencies": {
-    "@h-ai/core": "^0.1.0-alpha.18",
-    "@h-ai/kit": "^0.1.0-alpha.18"{{#if hasUi}},
-    "@h-ai/ui": "^0.1.0-alpha.18"{{/if}}{{#if features.db}},
-    "@h-ai/reldb": "^0.1.0-alpha.18"{{/if}}{{#if features.cache}},
-    "@h-ai/cache": "^0.1.0-alpha.18"{{/if}}{{#if features.iam}},
-    "@h-ai/iam": "^0.1.0-alpha.18"{{/if}}{{#if features.crypto}},
-    "@h-ai/crypto": "^0.1.0-alpha.18"{{/if}}{{#if features.storage}},
-    "@h-ai/storage": "^0.1.0-alpha.18"{{/if}}{{#if features.ai}},
-    "@h-ai/ai": "^0.1.0-alpha.18"{{/if}}{{#if features.audit}},
-    "@h-ai/audit": "^0.1.0-alpha.18"{{/if}}{{#if features.reach}},
-    "@h-ai/reach": "^0.1.0-alpha.18"{{/if}}{{#if features.payment}},
-    "@h-ai/payment": "^0.1.0-alpha.18"{{/if}}{{#if features.vecdb}},
-    "@h-ai/vecdb": "^0.1.0-alpha.18"{{/if}}{{#if features.datapipe}},
-    "@h-ai/datapipe": "^0.1.0-alpha.18"{{/if}}{{#if features.scheduler}},
-    "@h-ai/scheduler": "^0.1.0-alpha.18"{{/if}}{{#if features.deploy}},
-    "@h-ai/deploy": "^0.1.0-alpha.18"{{/if}}{{#if features.api-client}},
-    "@h-ai/api-client": "^0.1.0-alpha.18"{{/if}}{{#if features.capacitor}},
-    "@h-ai/capacitor": "^0.1.0-alpha.18"{{/if}}{{#if isCapacitorApp}}{{#unless features.api-client}},
-    "@h-ai/api-client": "^0.1.0-alpha.18"{{/unless}}{{#unless features.capacitor}},
-    "@h-ai/capacitor": "^0.1.0-alpha.18"{{/unless}}{{/if}},
+    "@h-ai/core": "^0.1.0-alpha.19",
+    "@h-ai/kit": "^0.1.0-alpha.19"{{#if hasUi}},
+    "@h-ai/ui": "^0.1.0-alpha.19"{{/if}}{{#if features.db}},
+    "@h-ai/reldb": "^0.1.0-alpha.19"{{/if}}{{#if features.cache}},
+    "@h-ai/cache": "^0.1.0-alpha.19"{{/if}}{{#if features.iam}},
+    "@h-ai/iam": "^0.1.0-alpha.19"{{/if}}{{#if features.crypto}},
+    "@h-ai/crypto": "^0.1.0-alpha.19"{{/if}}{{#if features.storage}},
+    "@h-ai/storage": "^0.1.0-alpha.19"{{/if}}{{#if features.ai}},
+    "@h-ai/ai": "^0.1.0-alpha.19"{{/if}}{{#if features.audit}},
+    "@h-ai/audit": "^0.1.0-alpha.19"{{/if}}{{#if features.reach}},
+    "@h-ai/reach": "^0.1.0-alpha.19"{{/if}}{{#if features.payment}},
+    "@h-ai/payment": "^0.1.0-alpha.19"{{/if}}{{#if features.vecdb}},
+    "@h-ai/vecdb": "^0.1.0-alpha.19"{{/if}}{{#if features.datapipe}},
+    "@h-ai/datapipe": "^0.1.0-alpha.19"{{/if}}{{#if features.scheduler}},
+    "@h-ai/scheduler": "^0.1.0-alpha.19"{{/if}}{{#if features.deploy}},
+    "@h-ai/deploy": "^0.1.0-alpha.19"{{/if}}{{#if features.api-client}},
+    "@h-ai/api-client": "^0.1.0-alpha.19"{{/if}}{{#if features.capacitor}},
+    "@h-ai/capacitor": "^0.1.0-alpha.19"{{/if}}{{#if isCapacitorApp}}{{#unless features.api-client}},
+    "@h-ai/api-client": "^0.1.0-alpha.19"{{/unless}}{{#unless features.capacitor}},
+    "@h-ai/capacitor": "^0.1.0-alpha.19"{{/unless}}{{/if}},
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@antfu/eslint-config": "^9.0.0",
     "@playwright/test": "^1.60.0",
 {{#if isCapacitorApp}}
-    "@capacitor/cli": "^8.2.0",
-    "@capacitor/core": "^8.2.0",
-    "@capacitor/android": "^8.2.0",
+  "@aparajita/capacitor-secure-storage": "^8.0.0",
+    "@capacitor/cli": "^8.3.4",
+    "@capacitor/core": "^8.3.4",
+    "@capacitor/android": "^8.3.4",
     "@capacitor/preferences": "^8.0.1",
     "@sveltejs/adapter-static": "^3.0.10",
 {{else}}

package/templates/features/payment/routes/api/v1/payment/create/+server.ts

@@ -7,18 +7,26 @@ import { payment } from '@h-ai/payment'
 
 export const POST: RequestHandler = async ({ request, locals }) => {
   const body = await request.json()
-  const { provider, tradeType, outTradeNo, totalAmount, subject, notifyUrl } = body
+  const { provider, tradeType, outTradeNo, totalAmount, subject, notifyUrl, userId, metadata } = body
 
   if (!provider || !outTradeNo || !totalAmount || !subject) {
     return kit.response.badRequest('Missing required fields: provider, outTradeNo, totalAmount, subject')
   }
 
-  const result = await payment.createOrder({
-    provider,
-    tradeType: tradeType ?? 'JSAPI',
-    outTradeNo,
-    totalAmount,
-    subject,
+  const normalizedTradeType = tradeType === 'h5'
+    || tradeType === 'app'
+    || tradeType === 'native'
+    || tradeType === 'mini_program'
+    ? tradeType
+    : 'jsapi'
+
+  const result = await payment.createOrder(provider, {
+    orderNo: outTradeNo,
+    amount: Number(totalAmount),
+    description: subject,
+    tradeType: normalizedTradeType,
+    userId,
+    metadata,
     notifyUrl: notifyUrl ?? `${new URL(request.url).origin}/api/v1/payment/notify/${provider}`,
   })
 

package/templates/features/payment/routes/api/v1/payment/notify/[provider]/+server.ts

@@ -21,8 +21,7 @@ export const POST: RequestHandler = async ({ request, params }) => {
     headers[key] = value
   })
 
-  const result = await payment.handleNotify({
-    provider,
+  const result = await payment.handleNotify(provider, {
     headers,
     body,
   })

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

@@ -122,6 +122,8 @@ ai.init(core.config.get('ai'))
 ai.close()
 ```
 
+`ai.config` 返回的是脱敏后的配置快照；`apiKey`、`privateKey`、`baseUrl` 等敏感字段会自动隐藏，URL 类字段只掩码内嵌凭证。
+
 **特殊说明**：`ai.tools` 和 `ai.stream` 无需 init 即可使用；`ai.llm` 和 `ai.mcp` 操作需要先 init。
 
 ---

package/templates/skills/hai-api-client/SKILL.md

@@ -48,6 +48,8 @@ await apiClient.init({
 })
 ```
 
+> `createCapacitorTokenStorage()` 仅在 Android/iOS 原生环境 + `@aparajita/capacitor-secure-storage` 已安装时持久化 token；纯 Web 不会回退到 `localStorage`。
+
 SSR / Node.js 测试场景请显式传入内存存储：
 
 ```ts
@@ -84,6 +86,8 @@ const client = apiClient.create(contract)
 await client.init({ baseUrl: 'https://api.example.com/api/v1' })
 ```
 
+`client.config` / `apiClient.config` 返回的是脱敏后的运行配置快照；`baseUrl` 的内嵌凭证与 `headers.authorization` 等敏感值会自动隐藏。
+
 ### 4. 关闭
 
 ```ts

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

@@ -52,7 +52,10 @@ await audit.init({
 ### 3. 关闭
 
 ```ts
-await audit.close()
+const closeResult = await audit.close()
+if (!closeResult.success) {
+  throw new Error(closeResult.error.message)
+}
 ```
 
 ## 核心 API
@@ -62,7 +65,7 @@ await audit.close()
 | 方法                  | 签名                                                             | 说明       |
 | --------------------- | ---------------------------------------------------------------- | ---------- |
 | `audit.init`          | `(config: AuditInitConfig) => Promise<HaiResult<void>>` | 初始化模块 |
-| `audit.close`         | `() => Promise<void>`                                            | 关闭模块   |
+| `audit.close`         | `() => Promise<HaiResult<void>>`                                 | 关闭模块   |
 | `audit.isInitialized` | `boolean`                                                        | 初始化状态 |
 
 ### 日志操作
@@ -86,6 +89,8 @@ await audit.close()
 | `audit.helper.passwordResetComplete(userId, ip?, ua?)`                         | 密码重置完成 |
 | `audit.helper.crud(input)` | CRUD 操作    |
 
+> `audit.log()` / `audit.helper.*()` 中的 `details` 仅会自动脱敏凭证类字段（如 `password` / `token` / `secret`）；邮箱、手机号默认保留原值。
+
 ## 错误码
 
 | 错误码                            | code             | 说明         |

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

@@ -51,6 +51,8 @@ await cache.init(core.config.get('cache'))
 await cache.close()
 ```
 
+`cache.config` 返回的是脱敏后的配置快照；Redis `password` / `url` 等敏感值不会原样暴露给日志或调试输出。
+
 ---
 
 ## 核心 API

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

@@ -5,20 +5,20 @@ description: 使用 @h-ai/capacitor 桥接 Capacitor 原生能力（Token 安全
 
 # hai-capacitor
 
-> `@h-ai/capacitor` 是 hai-framework 的 Capacitor 原生桥接模块，封装常用原生能力为统一 API，返回 `HaiResult<T>`。与 `@h-ai/api-client` 配合实现 App 端 Token 安全存储。
+> `@h-ai/capacitor` 是 hai-framework 的 Capacitor 原生桥接模块，封装常用原生能力为统一 API，返回 `HaiResult<T>`。与 `@h-ai/api-client` 配合时，Token 仅存于原生安全存储，不回退到 Web `localStorage`。
 
 ---
 
 ## 运行环境
 
-> **浏览器端 / 原生 App 专用。** 在 Capacitor 原生环境（Android/iOS）中提供完整能力，纯 Web 环境下部分功能退化（如 Preferences 退化为 localStorage）。
+> **浏览器端 / 原生 App 专用。** 在 Capacitor 原生环境（Android/iOS）中提供完整能力；`createCapacitorTokenStorage()` 仅在原生环境持久化 token，纯 Web 不做不安全回退。`capacitor.preferences` 仍可用于普通偏好数据。
 
 ---
 
 ## 适用场景
 
 - Android/iOS 原生应用开发（SvelteKit + Capacitor）
-- Token 安全存储（Capacitor Preferences → SharedPreferences / UserDefaults）
+- Token 安全存储（`@aparajita/capacitor-secure-storage`）
 - 设备信息获取（平台、型号、版本）
 - 推送通知注册与监听（FCM / APNs）
 - 原生相机拍照 / 相册选取
@@ -64,13 +64,13 @@ await apiClient.init({
 })
 ```
 
-`createCapacitorTokenStorage()` 返回 `TokenStorage` 实例（兼容 `@h-ai/api-client`），底层使用 `@capacitor/preferences`：
+`createCapacitorTokenStorage()` 返回 `TokenStorage` 实例（兼容 `@h-ai/api-client`），底层使用 `@aparajita/capacitor-secure-storage`：
 
-- Android → SharedPreferences（应用沙盒）
-- iOS → UserDefaults
-- Web → localStorage（退化，建议仅原生端使用）
+- Android → Android KeyStore + 加密 SharedPreferences
+- iOS → Keychain
+- Web → **不回退到 localStorage**；`get*()` 返回 `null`，`set*()` / `clear()` 为 no-op
 
-所有方法内置 try-catch，Preferences 异常时 get 返回 `null`、set/clear 静默失败并记录日志。
+所有方法内置 try-catch；原生安全存储异常时 get 返回 `null`、set/clear 静默失败并记录日志。
 
 #### Preferences 子操作
 
@@ -208,6 +208,7 @@ await capacitor.statusBar.show()
 | `HaiCapacitorError.PREFERENCES_SET_FAILED`   | `hai:capacitor:012`    | Preferences 写入失败 |
 | `HaiCapacitorError.PREFERENCES_REMOVE_FAILED`| `hai:capacitor:013`    | Preferences 删除失败 |
 | `HaiCapacitorError.DEVICE_INFO_FAILED`       | `hai:capacitor:020`    | 获取设备信息失败     |
+| `HaiCapacitorError.APP_VERSION_FAILED`       | `hai:capacitor:021`    | 获取应用版本失败     |
 | `HaiCapacitorError.PUSH_REGISTER_FAILED`     | `hai:capacitor:030`    | 推送注册失败         |
 | `HaiCapacitorError.PUSH_LISTEN_FAILED`       | `hai:capacitor:031`    | 推送监听失败         |
 | `HaiCapacitorError.CAMERA_FAILED`            | `hai:capacitor:040`    | 拍照/相册失败        |
@@ -359,7 +360,8 @@ async function captureAndUpload() {
 | 插件 | 类型 | 用于 |
 | --- | --- | --- |
 | `@capacitor/core` | peerDependency（必需） | 核心运行时 |
-| `@capacitor/preferences` | peerDependency（必需） | Token 存储 |
+| `@aparajita/capacitor-secure-storage` | 可选 peerDependency（原生 token 存储必需） | `createCapacitorTokenStorage()` |
+| `@capacitor/preferences` | peerDependency（必需） | `capacitor.preferences.*` 普通偏好数据 |
 | `@capacitor/device` | 可选 | `getDeviceInfo()` |
 | `@capacitor/app` | 可选 | `getAppVersion()` |
 | `@capacitor/push-notifications` | 可选 | `registerPush()` / `listenPush()` |

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

@@ -16,7 +16,7 @@ description: 使用 @h-ai/core 进行配置加载、日志记录、i18n 国际
 | 能力 | Node.js | 浏览器 |
 |------|---------|--------|
 | `core.logger` | ✅ pino（结构化 JSON / pretty） | ✅ loglevel（DevTools console） |
-| `core.config` | ✅ 完整（YAML 加载、watch、validate） | ⚠️ 仅支持 `core.init({ ... })` 传入配置 |
+| `core.config` | ✅ 完整（YAML 加载、watch、validate） | ⚠️ 占位 API；文件配置方法返回 `SERVICE_UNAVAILABLE` |
 | `core.i18n` | ✅ | ✅ |
 | `core.zodValidation` | ✅ | ✅ |
 | `core.id` | ✅ | ✅ |
@@ -79,6 +79,8 @@ const formErrors = core.zodValidation.mapZodErrorToFormErrors(zodError, getMessa
 
 ### 配置管理 — `core.config`
 
+> 浏览器端保留 `core.config` 对象用于类型/runtime 对齐，但没有文件系统：`get()` 返回 `undefined`，`has()` 返回 `false`，`keys()` 返回 `[]`；`load()` / `validate()` / `reload()` 返回 `HaiCommonError.SERVICE_UNAVAILABLE`；`watch()` 会立即回调该错误并返回 no-op 取消函数。
+
 | 方法         | 签名                                                           | 说明                           |
 | ------------ | -------------------------------------------------------------- | ------------------------------ |
 | `get`        | `<T>(name: string) => T \| undefined`                          | 获取模块配置段                 |
@@ -541,6 +543,7 @@ logger.debug('Data fetched', { count: items.length })
 
 | 功能 | 行为 |
 |------|------|
+| `core.config` 文件配置 | 不支持；文件相关方法返回 `SERVICE_UNAVAILABLE`，配置应由服务端读取后下发 |
 | `format: 'json' \| 'pretty'` | 被忽略（始终输出到 DevTools console） |
 | `redact` 字段脱敏 | 不生效（需手动脱敏） |
 | `fatal` 级别 | 映射为 `console.error`（带 `[FATAL]` 前缀） |

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

@@ -106,8 +106,8 @@ const valid = crypto.hash.verify('hello', hash.data!)
 | --------------- | ----------------------------------------------- | --------------------------- |
 | `generateKey`   | `() => string`                                  | 生成 128-bit 密钥（32 hex） |
 | `generateIV`    | `() => string`                                  | 生成随机 IV（32 hex）       |
-| `encrypt`       | `(data, key, options?) => HaiResult<string>`       | 加密                        |
-| `decrypt`       | `(ciphertext, key, options?) => HaiResult<string>` | 解密                        |
+| `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`                    | 从密码和盐值派生密钥        |
@@ -116,13 +116,24 @@ const valid = crypto.hash.verify('hello', hash.data!)
 
 ```typescript
 const key = crypto.symmetric.generateKey()
-const result = crypto.symmetric.encryptWithIV('明文数据', key)
-if (result.success) {
-  const decrypted = crypto.symmetric.decryptWithIV(result.data.ciphertext, key, result.data.iv)
+
+// 默认安全用法：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)
 }
 ```
 
-**SymmetricOptions**：`{ mode?: 'ecb' | 'cbc', iv?: string, inputEncoding?: 'utf8' | 'hex', outputFormat?: 'hex' | 'base64' }`
+**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`
 
@@ -143,7 +154,7 @@ if (hashed.success) {
 
 ### 传输加密 — `crypto.transport`
 
-所有传输加密工厂必须从 `crypto.transport` 访问，不从子目录导入内部工厂。
+传输加密主工厂必须从 `crypto.transport` 访问；共享 `keyStore` provider 请从 `@h-ai/crypto` 根入口导入，不从子目录内部路径导入。
 
 | 方法 | 签名 | 说明 |
 | --- | --- | --- |
@@ -151,6 +162,14 @@ if (hashed.success) {
 | `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)
@@ -166,6 +185,17 @@ const resp = await client.encryptedFetch('https://api.example.com/api/v1/echo',
 })
 ```
 
+```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`。
@@ -174,6 +204,8 @@ const resp = await client.encryptedFetch('https://api.example.com/api/v1/echo',
 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 } })`
@@ -210,9 +242,11 @@ const encrypted = crypto.symmetric.encrypt(sensitiveData, key)
 // 存入数据库
 
 // 读取时解密
-const decrypted = crypto.symmetric.decrypt(storedData, key)
+const decrypted = crypto.symmetric.decrypt(storedPayload, key)
 ```
 
+> 默认密文是结构化对象，必须完整存储 `mode` / `ciphertext` / `iv` / `encoding` 字段；如果数据库字段已拆分 IV 与密文，请改用 `encryptWithIV()` / `decryptWithIV()`。
+
 ### 密码存储与验证
 
 ```typescript

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

@@ -83,6 +83,8 @@ await iam.init({
 })
 ```
 
+`iam.config` 返回的是脱敏后的配置快照；LDAP `url` / `bindPassword` 等敏感值会自动隐藏。
+
 初始化时自动创建数据库表（5 张）：`hai_iam_users`、`hai_iam_roles`、`hai_iam_permissions`、`hai_iam_role_permissions`、`hai_iam_user_roles`。
 
 Token 和 OTP 存储在 cache 中（不落库）。refreshToken 使用独立的 cache key 存储。

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

@@ -58,10 +58,12 @@ kit 不再维护本地传输加密实现；服务端和客户端都统一委托
 
 ```ts
 // hooks.server.ts
-import { crypto } from '@h-ai/crypto'
+import { cache } from '@h-ai/cache'
+import { createRedisTransportKeyStore, crypto } from '@h-ai/crypto'
 import { kit } from '@h-ai/kit'
 
 await crypto.init()
+await cache.init({ type: 'redis', host: '127.0.0.1', port: 6379 })
 
 export const handle = kit.createHandle({
   auth: {
@@ -71,7 +73,10 @@ export const handle = kit.createHandle({
   },
   crypto: {
     crypto,
-    transport: { requireEncryption: true },
+    transport: {
+      requireEncryption: true,
+      keyStore: createRedisTransportKeyStore({ cache, ttlSeconds: 3600 }),
+    },
   },
 })
 ```
@@ -100,6 +105,8 @@ export const { apiFetch } = kit.client.create({ auth: true })
 
 默认协商端点：`/api/_hai/key-exchange`。如 `keyExchangePath` 自定义，浏览器端同步设置 `keyExchangeUrl`。
 
+多节点部署时，可在 `kit.createHandle({ crypto: { transport } })` 的运行时对象里直接传 `keyStore`；推荐使用 `@h-ai/crypto` 根入口导出的 `createRedisTransportKeyStore()` / `createReldbTransportKeyStore()`。这类对象依赖不要写进 `_kit.yml`。
+
 transport 默认保护同源 `/api/*` endpoint 与 SvelteKit `__data.json` 页面数据请求；页面文档、静态资源与 `multipart/form-data` 上传请求保持明文透传。
 
 安全策略默认 fail-closed：`requireEncryption: true` 时，受保护路径缺少 `X-Client-Id` 必须返回 400；服务端 transport 管理器不可用、响应体无法加密或超过单次加密上限时返回错误，禁止明文业务响应回退。`requireEncryption: false` 只适合迁移期灰度。

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

@@ -58,6 +58,7 @@ alipay:
 stripe:
   secretKey: ${HAI_PAYMENT_STRIPE_SECRET_KEY}
   webhookSecret: ${HAI_PAYMENT_STRIPE_WEBHOOK_SECRET}
+  webhookToleranceSeconds: 300  # 可选，默认 300 秒
 ```
 
 ### 2. 初始化（服务端）
@@ -101,6 +102,8 @@ if (result.success) {
   // result.data: PaymentOrder { provider, tradeType, clientParams, prepayId? }
   // clientParams 包含调起支付所需参数
 }
+
+// amount / totalAmount 必须是正整数（单位：分）
 ```
 
 ### 4. 处理支付回调
@@ -262,6 +265,8 @@ export const POST = kit.handler(async ({ request, locals }) => {
 
 关键支付操作（创建订单、回调、退款、关闭订单）成功后自动写入审计日志（依赖 `@h-ai/audit`），无需额外配置。`queryOrder` 为只读操作，不写审计日志。
 
+内置 Provider 的 HTTP 请求默认带 15 秒超时；Stripe 可通过 `webhookToleranceSeconds` 调整 webhook 时间戳容忍窗口。
+
 ---
 
 ## 相关 Skills

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

@@ -96,6 +96,8 @@ await reach.init(core.config.get('reach'))
 await reach.close()
 ```
 
+`reach.config` 返回的是脱敏后的配置快照；`api.url` / `endpoint`、授权头、SMTP `pass`、短信密钥等敏感值会自动隐藏。
+
 ### 3. 保存模板（模板绑定 Provider）
 
 ```typescript
@@ -159,7 +161,7 @@ await reach.send({
 | `reach.init`          | `(config: ReachConfigInput) => Promise<HaiResult<void>>`    | 初始化（注册多个 Provider）        |
 | `reach.send`          | `(message: ReachMessage) => Promise<HaiResult<SendResult>>` | 发送消息（通过 provider 字段路由） |
 | `reach.template`      | `ReachTemplateRegistry`                                  | 模板注册表                         |
-| `reach.config`        | `ReachConfig \| null`                                    | 当前配置                           |
+| `reach.config`        | `ReachConfig \| null`                                    | 当前脱敏配置快照                   |
 | `reach.isInitialized` | `boolean`                                                | 是否已初始化                       |
 | `reach.close`         | `() => Promise<void>`                                    | 关闭所有连接                       |
 

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

@@ -51,6 +51,8 @@ await reldb.init(core.config.get('db'))
 await reldb.close()
 ```
 
+`reldb.config` 返回的是脱敏后的配置快照；数据库密码与 URL 内嵌凭证会自动隐藏。
+
 ### 3. 选择操作接口
 
 | 接口 | 用途               | 入口                         |

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

@@ -80,6 +80,8 @@ await scheduler.register({
 })
 ```
 
+> ⚠️ **安全警示**：`kind: 'js'` 仅允许受信任的服务端代码。当前实现使用 Node.js `vm` 便捷执行，不是安全沙箱；禁止把用户、租户或运营后台自由输入的 JS 字符串直接注册为任务。需要可配置执行逻辑时，优先改用 `kind: 'api'` 或 `hooks.onTaskExecute`。
+
 ### 3. 使用全局 execute hook 处理无 handler 任务
 
 ```ts

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

@@ -271,6 +271,7 @@ const app = serv.createApp({
     crypto,
     // keyExchangePath 默认 '/_hai/key-exchange'
     // maxClients: 10000,
+    // keyStore: createRedisTransportKeyStore({ cache, ttlSeconds: 3600 }),
   },
 })
 ```
@@ -298,6 +299,8 @@ await apiClient.init({
 
 > 不要导入或暴露子目录内部 transport 工厂；公共装配点只有 `serv.createApp({ transport: { crypto } })`。
 
+多节点部署时，直接在 `serv.createApp({ transport })` 的运行时对象里注入 `keyStore` 即可；推荐从 `@h-ai/crypto` 根入口导入 `createRedisTransportKeyStore()` / `createReldbTransportKeyStore()`。`keyStore` 不属于 `_serv.yml` 配置项，配置文件仍只保留静态路径和白名单。
+
 **上下文工厂优先级**（`context.session` 填充来源）：
 
 1. 显式 `createContext`（高级场景：多租户、额外字段）

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

@@ -52,9 +52,14 @@ import { storage } from '@h-ai/storage'
 
 await storage.init(core.config.get('storage'))
 // 使用后关闭
-await storage.close()
+const closeResult = await storage.close()
+if (!closeResult.success) {
+  throw new Error(closeResult.error.message)
+}
 ```
 
+> `storage.config` 返回的是**脱敏配置快照**；S3 的 `accessKeyId` / `secretAccessKey` 等敏感字段会被替换为 `[REDACTED]`。
+
 ---
 
 ## 核心 API
@@ -106,6 +111,8 @@ const downloadUrl = await storage.presign.getUrl('uploads/doc.pdf', {
 })
 ```
 
+> `storage.presign.putUrl()` 当前不支持 `maxSize` 约束参数；如需大小限制，请在应用层上传前校验，或在服务端落库/回调处二次校验。
+
 ---
 
 ## 错误码 — `HaiStorageError`
@@ -174,6 +181,8 @@ export const POST = kit.handler(async ({ request, locals }) => {
 
 > 说明：`@h-ai/storage` 只提供存储能力，不强制要求 `/api/storage` 路由命名。应用可按业务语义自定义 API 路径。
 
+> Local Provider 的 `storage.dir.list()` 会递归扫描匹配前缀下的文件，仅支持 `maxKeys` 截断，不支持 `continuationToken` 真分页；大目录建议缩小 `prefix` 或改用 S3 Provider。
+
 ### 头像上传
 
 ```typescript

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

@@ -55,9 +55,14 @@ import { vecdb } from '@h-ai/vecdb'
 
 await vecdb.init(core.config.get('vecdb'))
 // ... 使用向量数据库
-await vecdb.close()
+const closeResult = await vecdb.close()
+if (!closeResult.success) {
+  throw new Error(closeResult.error.message)
+}
 ```
 
+> `vecdb.config` 返回的是**脱敏配置快照**；连接字符串中的用户名/密码、独立 `password` 字段和 `apiKey` 会被替换为 `[REDACTED]`。
+
 ### 3. 选择操作接口
 
 | 接口       | 用途                       | 入口              |
@@ -144,6 +149,8 @@ await vecdb.vector.upsert('docs', [
 await vecdb.vector.delete('docs', ['doc-1', 'doc-2'])
 ```
 
+> 空批量 `insert/upsert/delete` 会被视为 no-op；写入与搜索会校验向量维度，不匹配时返回 `HaiVecdbError.DIMENSION_MISMATCH`。Qdrant `collection.exists()` 仅在 404 时返回 `false`，网络异常会返回查询错误而不是误判不存在。
+
 **VectorDocument**：
 
 ```typescript