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

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

@@ -0,0 +1,197 @@
+# @h-ai/ai reference
+
+本文件承载 `SKILL.md` 中不常用但仍需要保留的 API 参考。优先读取 `SKILL.md`；只有当任务需要完整方法清单、错误码或长示例时再读取本文件。
+
+## 初始化与依赖
+
+| 能力 | 是否需要 `ai.init()` | 依赖 |
+| --- | --- | --- |
+| `ai.tools` | 否 | 无 |
+| `ai.stream` | 否 | 无 |
+| `ai.llm` | 是 | OpenAI 兼容 LLM 配置 |
+| `ai.embedding` | 是 | LLM/Embedding 模型配置 |
+| `ai.memory` | 是 | Store + 可选 Embedding |
+| `ai.retrieval` / `ai.rag` | 是 | Embedding + Store |
+| `ai.knowledge` | 是 | LLM + Embedding + Store + datapipe |
+| `ai.context` | 是 | LLM + Store + 可选 Memory/RAG/Reasoning |
+| `ai.a2a` | 是 | A2A 配置 + executor |
+
+关闭必须使用 `await ai.close()`，这样才能确定释放自定义 `AIStoreProvider.close()`。
+
+## LLM
+
+| 方法 | 说明 |
+| --- | --- |
+| `chat(options)` | 非流式 Chat Completion |
+| `chatStream(options)` | 流式 Chat Completion |
+| `ask(query, options?)` | 返回纯文本的简易问答 |
+| `askStream(query, options?)` | 流式纯文本问答 |
+| `listModels()` | 查询可用模型 |
+| `getHistory(scope, options?)` | 查询会话历史 |
+| `listSessions(objectId)` | 查询主体会话 |
+
+```ts
+const result = await ai.llm.chat({
+  model: 'fast',
+  messages: [
+    { role: 'system', content: '你是一个翻译助手' },
+    { role: 'user', content: '你好世界' },
+  ],
+})
+if (result.success) {
+  const reply = result.data.choices[0]?.message.content ?? ''
+}
+```
+
+## Tools
+
+- `ai.tools.define({ name, description, parameters, handler })`
+- `ai.tools.createRegistry()`
+- `registry.register(tool)` / `registry.unregister(name)`
+- `registry.getDefinitions()`：传给 LLM 的工具定义
+- `registry.execute(toolCall)` / `registry.executeAll(toolCalls, { parallel })`
+
+工具 handler 输入由 Zod schema 约束，外部输入不要绕过 schema。
+
+## MCP
+
+### 独立服务器
+
+```ts
+const mcp = createMcpServer({ name: 'my-server', version: '1.0.0' })
+mcp.registerResource('config', 'config://app', { description: '应用配置' }, async uri => ({
+  contents: [{ uri: uri.href, text: '{}' }],
+}))
+await mcp.connect(new StdioServerTransport())
+```
+
+### `ai.mcp`
+
+| 方法 | 说明 |
+| --- | --- |
+| `registerTool(definition, handler)` | 注册内置工具 |
+| `callTool(name, args, context?)` | 调用工具 |
+| `registerResource(resource, handler)` | 注册资源 |
+| `readResource(uri)` | 读取资源 |
+| `registerPrompt(prompt, handler)` | 注册提示词 |
+| `getPrompt(name, args)` | 生成提示词消息 |
+
+## Embedding
+
+Embedding OpenAI 客户端按 `apiKey + baseURL + timeout` 缓存；同一 key 指向不同网关时不会复用错误客户端。
+
+| 方法 | 说明 |
+| --- | --- |
+| `embed(request)` | 支持单条/批量输入 |
+| `embedText(text)` | 返回单条向量 |
+| `embedBatch(texts)` | 返回向量数组 |
+
+## Memory
+
+| 方法 | 说明 |
+| --- | --- |
+| `extract(messages, options?)` | 从对话提取记忆并存储 |
+| `add(entry)` | 手动添加记忆 |
+| `get(memoryId)` / `update(memoryId, updates)` | 读取/更新 |
+| `recall(query, options?)` | 检索相关记忆 |
+| `injectMemories(messages, options?)` | 注入 system 记忆上下文 |
+| `remove(memoryId)` / `clear(options?)` | 删除 |
+| `list(options?)` / `listPage(options?)` | 列表/分页 |
+
+推荐所有记忆操作带 `objectId`，避免不同用户或 Agent 混写。
+
+## Retrieval / RAG
+
+```ts
+await ai.retrieval.addSource({
+  id: 'docs',
+  name: '产品文档',
+  collection: 'doc_vectors',
+  topK: 5,
+  minScore: 0.7,
+})
+
+const result = await ai.rag.query('核心架构是什么？', {
+  sources: ['docs'],
+  topK: 5,
+})
+```
+
+`retrieve` 会并发检索目标 source 并按 score 合并排序；无 source 时返回 `RETRIEVAL_SOURCE_NOT_FOUND`。
+
+## Knowledge
+
+| 方法 | 说明 |
+| --- | --- |
+| `setup(options?)` | 初始化 collection / 表 / 索引 |
+| `ingest(input)` | 文档入库 |
+| `ingestFile(input)` | 从文件导入（Node.js） |
+| `ingestBatch(inputs, onProgress?)` | 批量导入 |
+| `retrieve(query, options?)` | 实体增强检索 |
+| `ask(query, options?)` | 知识库问答 |
+| `findByEntity(entityName, options?)` | 实体关联文档 |
+| `listEntities(options?)` / `listDocuments(options?)` | 列表 |
+| `removeDocument(documentId, options?)` | 删除文档和关联 |
+
+入库链路：parse/clean → chunk → embedding → vecdb upsert → reldb metadata/entity index。
+
+## Context
+
+`ai.context.createManager(options)` 返回有状态管理器，适合多轮对话。
+
+常用选项：
+
+- `scope: { objectId, sessionId }`
+- `systemPrompt`
+- `compress: { auto, strategy, maxTokens, preserveLastN }`
+- `memory: { enable, enableExtract, topK }`
+- `rag: { enable, sources, topK, minScore }`
+- `tools`
+
+常用方法：`addMessage`、`getMessages`、`getTokenUsage`、`chat`、`chatStream`、`save`、`reset`。
+
+## File / Rerank / Reasoning
+
+- `ai.file.parse({ content, filename, options })`：text/html/pdf/docx/ocr 解析。
+- `ai.file.parseText(content, filename?)`：直接返回文本。
+- `ai.rerank.rerank(request)` / `rerankTexts(query, texts, topN?)`：相关性重排。
+- `ai.reasoning.run(query, options?)` / `runStream(query, options?)`：`react`、`cot`、`plan-execute`。
+
+## A2A
+
+| 方法 | 说明 |
+| --- | --- |
+| `registerExecutor(executor)` | 注册 Agent executor |
+| `getAgentCard()` | 获取 Agent Card |
+| `handleRequest(body, context?)` | 处理 A2A JSON-RPC 请求 |
+| `listMessages(filter)` | 查询 A2A 消息记录 |
+| `callRemoteAgent(remoteUrl, message, options?)` | 调用远端 Agent |
+
+A2A 的 SDK handler 延迟创建；注册 executor 或首次处理请求时才装配运行时对象。
+
+## 错误码速查
+
+| 分段 | 代表错误 |
+| --- | --- |
+| `hai:ai:000` | `INTERNAL_ERROR` |
+| `hai:ai:010-012` | 初始化：`NOT_INITIALIZED` / `CONFIGURATION_ERROR` / `INIT_IN_PROGRESS` |
+| `hai:ai:020-033` | Rerank / File |
+| `hai:ai:100-107` | LLM / 历史记录 |
+| `hai:ai:200-204` | MCP |
+| `hai:ai:300-302` | Embedding |
+| `hai:ai:400-403` | Tool |
+| `hai:ai:500-502` | Reasoning |
+| `hai:ai:600-701` | Retrieval / RAG |
+| `hai:ai:800-805` | Knowledge |
+| `hai:ai:900-904` | Memory |
+| `hai:ai:950-971` | Context / Store / Session |
+| `hai:ai:980-984` | A2A |
+
+## 浏览器端
+
+浏览器端通过 `@h-ai/api-client` 或自定义 endpoint 访问服务端 AI 能力。`ai.stream` 可在浏览器直接用于解析服务端流式 chunk。
+
+```ts
+const response = await apiClient.ai.chats.createCompletion({ messages })
+const memories = await apiClient.ai.memories.recall({ query: '偏好', objectId: 'user-001', topK: 5 })
+```

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,12 +86,16 @@ const client = apiClient.create(contract)
 await client.init({ baseUrl: 'https://api.example.com/api/v1' })
 ```
 
+`client.config` / `apiClient.config` 返回的是脱敏后的运行配置快照；`baseUrl` 的内嵌凭证与 `headers.authorization` 等敏感值会自动隐藏。
+
 ### 4. 关闭
 
 ```ts
 await apiClient.close()
 ```
 
+> 已初始化后再次 `init()` 会返回 `CONFIG_ERROR`，不会覆盖现有 client；切换 `baseUrl` / `fetch` / `transport` 前必须先 `close()`，避免旧 transport 会话泄漏。
+
 ## Token Storage 适配器
 
 | 工厂调用 | 存储位置 | 适用场景 |
@@ -126,7 +132,7 @@ if (login.success) {
 
 | API | 用途 |
 | --- | --- |
-| `apiClient.init(config)` | 初始化默认 API Service client |
+| `apiClient.init(config)` | 初始化默认 API Service client；重复初始化返回 `CONFIG_ERROR` |
 | `apiClient.close()` | 清理 client 状态 |
 | `apiClient.auth.setTokens(tokens)` | 写入 access token；非 httpOnly 存储会同时写入 refresh token |
 | `apiClient.auth.clear()` | 清理 Token |

package/templates/skills/hai-app-create/SKILL.md

@@ -55,7 +55,7 @@ description: 以 TDD 方式在应用中创建新功能：先编写测试定义
 
 ```
 src/
-  hooks.server.ts                # Handle Hook 入口
+  hooks.server.ts                # `handle` hook 入口
   app.css                        # 全局样式（TailwindCSS 4）
   lib/
     server/

package/templates/skills/hai-app-review/SKILL.md

@@ -45,7 +45,7 @@ description: 对应用代码进行审查：检查 TDD 合规性、架构分层
 
 ### 架构分层
 
-- [ ] `hooks.server.ts` 仅做中间件编排（初始化、i18n、Handle Hook），无业务逻辑
+- [ ] `hooks.server.ts` 仅做中间件编排（初始化、i18n、`handle` hook），无业务逻辑
 - [ ] `+page.server.ts` / `+server.ts` 仅做请求处理（守卫 → 校验 → 调用服务 → 响应）
 - [ ] 业务逻辑集中在 `$lib/server/services/`
 - [ ] 客户端组件不直接调用数据库或服务端模块

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-deploy/SKILL.md

@@ -61,6 +61,8 @@ services:
 ```typescript
 import { deploy } from '@h-ai/deploy'
 
+deploy.credentials.load()
+
 await deploy.init({
   provider: { type: 'vercel', token: 'vel_xxx' },
   services: {
@@ -113,9 +115,13 @@ if (result.success) {
 
 | 方法                   | 签名                                                                       | 说明         |
 | ---------------------- | -------------------------------------------------------------------------- | ------------ |
+| `deploy.credentials.load` | `() => HaiResult<string[]>`                                             | 加载凭证到 `process.env` |
+| `deploy.credentials.save` | `(key: string, value: string) => HaiResult<void>`                        | 保存单个凭证 |
+| `deploy.credentials.saveAll` | `(entries: Record<string, string>) => HaiResult<void>`                | 批量保存凭证 |
+| `deploy.credentials.getPath` | `() => string`                                                         | 获取凭证文件路径 |
 | `deploy.init`          | `(config: DeployConfigInput) => Promise<HaiResult<void>>`        | 初始化模块   |
 | `deploy.close`         | `() => Promise<void>`                                                      | 关闭模块     |
-| `deploy.scan`          | `(appDir: string) => Promise<HaiResult<ScanResult>>`             | 扫描应用     |
+| `deploy.scan`          | `(appDir: string) => Promise<HaiResult<ScanResult>>`             | 扫描应用（不依赖 init） |
 | `deploy.provisionAll`  | `(projectName: string) => Promise<HaiResult<ProvisionResult[]>>` | 开通所有服务 |
 | `deploy.deployApp`     | `(appDir: string, options?) => Promise<HaiResult<DeployResult>>` | 完整部署     |
 | `deploy.config`        | `DeployConfig \| null`                                                     | 当前配置     |
@@ -125,12 +131,9 @@ if (result.success) {
 
 ## 凭证管理
 
-| 函数                         | 说明                                       |
-| ---------------------------- | ------------------------------------------ |
-| `loadCredentials()`          | 加载 ~/.hai/credentials.yml 到 process.env |
-| `saveCredential(key, value)` | 保存单个凭证                               |
-| `saveCredentials(entries)`   | 批量保存凭证                               |
-| `getCredentialsPath()`       | 获取凭证文件路径                           |
+所有凭证操作都通过 `deploy.credentials.*` 访问，模块入口不再单独导出自由函数。
+
+> `deploy.credentials.*()` 与 `deploy.scan()` 都不依赖 `deploy.init()`，可用于 CLI 在读取 `_deploy.yml` 之前准备环境。
 
 ---
 
@@ -147,8 +150,8 @@ if (result.success) {
 | `HaiDeployError.PROVISION_FAILED`      | `hai:deploy:007`   | 基础设施开通失败         |
 | `HaiDeployError.ADAPTER_MISSING`       | `hai:deploy:008`   | SvelteKit adapter 未安装 |
 | `HaiDeployError.SCAN_FAILED`           | `hai:deploy:009`   | 应用扫描失败             |
-| `HaiDeployError.ENV_VAR_FAILED`        | `hai:deploy:010`   | 环境变量设置失败         |
-| `HaiDeployError.NOT_INITIALIZED`       | `hai:deploy:011`   | 模块未初始化             |
+| `HaiDeployError.NOT_INITIALIZED`       | `hai:deploy:010`   | 模块未初始化             |
+| `HaiDeployError.ENV_VAR_FAILED`        | `hai:deploy:011`   | 环境变量设置失败         |
 | `HaiDeployError.UNSUPPORTED_TYPE`      | `hai:deploy:012`   | 不支持的类型             |
 | `HaiDeployError.CONFIG_ERROR`          | `hai:deploy:013`   | 配置错误                 |
 | `HaiDeployError.CREDENTIAL_ERROR`      | `hai:deploy:014`   | 凭证读写失败             |

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

@@ -5,7 +5,7 @@ description: 使用 @h-ai/kit 构建 SvelteKit 请求管道、认证守卫、统
 
 # hai-kit
 
-> `@h-ai/kit` 只负责 SvelteKit 集成：Handle Hook、guard、response、validate、client、auth、crud、A2A。公共跨端 HTTP API 契约统一使用 `@h-ai/api-contract` + `@h-ai/serv`，不要在 kit 中定义业务 API contract。
+> `@h-ai/kit` 只负责 SvelteKit 集成：`handle` hook、guard、response、validate、client、auth、crud、A2A。公共跨端 HTTP API 契约统一使用 `@h-ai/api-contract` + `@h-ai/serv`，不要在 kit 中定义业务 API contract。
 
 ## 使用步骤
 
@@ -48,20 +48,24 @@ export const POST = kit.handler(async ({ request, locals }) => {
 ```ts
 import { kit } from '@h-ai/kit'
 
-const client = kit.client.create({ auth: true })
+const client = kit.client.create()
 export const { apiFetch } = client
 ```
 
+> 同源 endpoint 优先使用 httpOnly Cookie；`auth: true` 只读取 `kit.auth.setBrowserToken()` 写入的页面内存 Token，不会默认读写 localStorage。确需 Bearer Header 时，显式传入 `BrowserTokenStore`，禁止把敏感 Token 存入 localStorage。
+
 ### 4. 同源传输加密
 
 kit 不再维护本地传输加密实现；服务端和客户端都统一委托 `@h-ai/crypto` 的 `crypto.transport`。
 
 ```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 +75,10 @@ export const handle = kit.createHandle({
   },
   crypto: {
     crypto,
-    transport: { requireEncryption: true },
+    transport: {
+      requireEncryption: true,
+      keyStore: createRedisTransportKeyStore({ cache, ttlSeconds: 3600 }),
+    },
   },
 })
 ```
@@ -95,11 +102,13 @@ export const handle = kit.createHandle({
 // lib/utils/api.ts —— 业务层只看到 apiFetch
 import { kit } from '@h-ai/kit'
 
-export const { apiFetch } = kit.client.create({ auth: true })
+export const { apiFetch } = kit.client.create()
 ```
 
 默认协商端点：`/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. 选择操作接口
 
 | 接口 | 用途               | 入口                         |