@h-ai/cli 0.1.0-alpha8 → 0.1.0-alpha9

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/cli",
   "type": "module",
-  "version": "0.1.0-alpha8",
+  "version": "0.1.0-alpha9",
   "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-alpha8"
+    "@h-ai/core": "0.1.0-alpha9"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",

package/templates/base/package.json.hbs

@@ -1,6 +1,6 @@
 {
   "name": "{{projectName}}",
-  "version": "0.1.0-alpha8",
+  "version": "0.1.0-alpha9",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",
@@ -14,26 +14,26 @@
     "test:e2e": "playwright test"
   },
   "dependencies": {
-    "@h-ai/core": "^0.1.0-alpha8",
-    "@h-ai/kit": "^0.1.0-alpha8"{{#if hasUi}},
-    "@h-ai/ui": "^0.1.0-alpha8"{{/if}}{{#if features.db}},
-    "@h-ai/reldb": "^0.1.0-alpha8"{{/if}}{{#if features.cache}},
-    "@h-ai/cache": "^0.1.0-alpha8"{{/if}}{{#if features.iam}},
-    "@h-ai/iam": "^0.1.0-alpha8"{{/if}}{{#if features.crypto}},
-    "@h-ai/crypto": "^0.1.0-alpha8"{{/if}}{{#if features.storage}},
-    "@h-ai/storage": "^0.1.0-alpha8"{{/if}}{{#if features.ai}},
-    "@h-ai/ai": "^0.1.0-alpha8"{{/if}}{{#if features.audit}},
-    "@h-ai/audit": "^0.1.0-alpha8"{{/if}}{{#if features.reach}},
-    "@h-ai/reach": "^0.1.0-alpha8"{{/if}}{{#if features.payment}},
-    "@h-ai/payment": "^0.1.0-alpha8"{{/if}}{{#if features.vecdb}},
-    "@h-ai/vecdb": "^0.1.0-alpha8"{{/if}}{{#if features.datapipe}},
-    "@h-ai/datapipe": "^0.1.0-alpha8"{{/if}}{{#if features.scheduler}},
-    "@h-ai/scheduler": "^0.1.0-alpha8"{{/if}}{{#if features.deploy}},
-    "@h-ai/deploy": "^0.1.0-alpha8"{{/if}}{{#if features.api-client}},
-    "@h-ai/api-client": "^0.1.0-alpha8"{{/if}}{{#if features.capacitor}},
-    "@h-ai/capacitor": "^0.1.0-alpha8"{{/if}}{{#if isCapacitorApp}},
-    "@h-ai/api-client": "^0.1.0-alpha8",
-    "@h-ai/capacitor": "^0.1.0-alpha8"{{/if}},
+    "@h-ai/core": "^0.1.0-alpha9",
+    "@h-ai/kit": "^0.1.0-alpha9"{{#if hasUi}},
+    "@h-ai/ui": "^0.1.0-alpha9"{{/if}}{{#if features.db}},
+    "@h-ai/reldb": "^0.1.0-alpha9"{{/if}}{{#if features.cache}},
+    "@h-ai/cache": "^0.1.0-alpha9"{{/if}}{{#if features.iam}},
+    "@h-ai/iam": "^0.1.0-alpha9"{{/if}}{{#if features.crypto}},
+    "@h-ai/crypto": "^0.1.0-alpha9"{{/if}}{{#if features.storage}},
+    "@h-ai/storage": "^0.1.0-alpha9"{{/if}}{{#if features.ai}},
+    "@h-ai/ai": "^0.1.0-alpha9"{{/if}}{{#if features.audit}},
+    "@h-ai/audit": "^0.1.0-alpha9"{{/if}}{{#if features.reach}},
+    "@h-ai/reach": "^0.1.0-alpha9"{{/if}}{{#if features.payment}},
+    "@h-ai/payment": "^0.1.0-alpha9"{{/if}}{{#if features.vecdb}},
+    "@h-ai/vecdb": "^0.1.0-alpha9"{{/if}}{{#if features.datapipe}},
+    "@h-ai/datapipe": "^0.1.0-alpha9"{{/if}}{{#if features.scheduler}},
+    "@h-ai/scheduler": "^0.1.0-alpha9"{{/if}}{{#if features.deploy}},
+    "@h-ai/deploy": "^0.1.0-alpha9"{{/if}}{{#if features.api-client}},
+    "@h-ai/api-client": "^0.1.0-alpha9"{{/if}}{{#if features.capacitor}},
+    "@h-ai/capacitor": "^0.1.0-alpha9"{{/if}}{{#if isCapacitorApp}},
+    "@h-ai/api-client": "^0.1.0-alpha9",
+    "@h-ai/capacitor": "^0.1.0-alpha9"{{/if}},
     "zod": "^3.23.0"
   },
   "devDependencies": {

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

@@ -9,6 +9,21 @@ description: 使用 @h-ai/ai 进行 LLM 调用（OpenAI 兼容）、MCP 服务
 
 ---
 
+## 运行环境
+
+| 能力 | Node.js | 浏览器 |
+|------|---------|--------|
+| `ai.llm` LLM 调用 | ✅ | ❌（通过 API 端点代理） |
+| `ai.mcp` MCP 服务器 | ✅ | ❌ |
+| `ai.tools` 工具定义 | ✅ | ✅（纯函数，无需 init） |
+| `ai.stream` 流处理 | ✅ | ✅（纯函数，无需 init） |
+| `ai.memory` / `ai.conversation` | ✅ | ❌（通过 API 查询） |
+| `ai.knowledge` 知识库 | ✅ | ❌（通过 API 查询） |
+
+浏览器端消费 AI 能力的标准模式：通过 `api.stream()` 或 `apiFetch` 调用服务端 API 端点。
+
+---
+
 ## 依赖
 
 | 模块 | 用途 | 是否必需 | 初始化要求 |
@@ -368,16 +383,6 @@ if (result.success) {
 | `renameSession`  | `(sessionId, title) => Promise<HaiResult<void>>`                     | 重命名会话                                              |
 | `removeSession`  | `(sessionId) => Promise<HaiResult<void>>`                            | 删除会话                                                |
 
-**ContextManagerOptions**（嵌套子模块配置）：
-- `scope?: InteractionScope` — 交互作用域
-- `systemPrompt?: string` — 系统提示词
-- `model?: string` / `temperature?: number` — LLM 参数覆盖
-- `compress?: CompressOptions & { auto?: boolean }` — 压缩配置（maxTokens/strategy/preserveLastN/auto 等）
-- `memory?: { enable?, enableExtract?, topK?, maxTokens?, position? }` — 记忆配置
-- `rag?: { enable?, sources?, topK?, minScore?, enableRerank? }` — RAG 配置
-- `reasoning?: { enable?, strategy?, maxRounds? }` — 推理配置
-- `tools?: ToolRegistryOperations` — 工具注册表
-
 **ContextManager 方法**：
 - `addMessage(msg)` — 追加消息（自动压缩）
 - `getMessages()` / `getTokenUsage()` / `getSummaries()` — 查询状态
@@ -649,6 +654,63 @@ async function manualChat(userInput: string) {
 
 ---
 
+## 浏览器端使用
+
+### 流式对话（SSE）
+
+浏览器通过 `api.stream()` 消费服务端流式 API：
+
+```typescript
+import { api } from '@h-ai/api-client'
+
+const controller = new AbortController()
+
+for await (const chunk of api.stream('/api/v1/ai/chat', {
+  conversationId: 'conv-1',
+  content: '你好',
+}, { signal: controller.signal })) {
+  // 每个 chunk 是 SSE data: 行的文本内容
+  appendToUI(chunk)
+}
+
+// 主动停止
+controller.abort()
+```
+
+或使用 `apiFetch`（SSR SvelteKit 同源场景）：
+
+```typescript
+import { apiFetch } from '$lib/utils/api'
+
+const res = await apiFetch('/api/v1/ai/chat', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ conversationId, content: userInput }),
+})
+
+// 手动消费 SSE 流
+const reader = res.body!.getReader()
+const decoder = new TextDecoder()
+while (true) {
+  const { done, value } = await reader.read()
+  if (done) break
+  appendToUI(decoder.decode(value))
+}
+```
+
+### 浏览器端使用 ai.stream（处理流式 chunk）
+
+`ai.stream` 是纯函数，浏览器端可直接使用：
+
+```typescript
+import { ai } from '@h-ai/ai'
+
+const processor = ai.stream.createProcessor()
+// 将服务端返回的 SSE chunk 逐条 process，提取 delta
+```
+
+---
+
 ## 相关 Skills
 
 - `hai-build`：模块初始化顺序

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

@@ -9,6 +9,20 @@ description: 使用 @h-ai/api-client 单例模式构建多端共用的纯 TypeSc
 
 ---
 
+## 运行环境
+
+**浏览器端专用。** 服务端 `+page.server.ts` / `+server.ts` 应直接调用模块 API（如 `iam.auth.login()`），不经过 HTTP 自环。
+
+### 与 kit.client 的分工
+
+| 场景 | 推荐 | 原因 |
+|------|------|------|
+| SSR SvelteKit 应用（同源请求） | `kit.client.create().apiFetch`（见 hai-kit SKILL） | 自动 CSRF、传输加密、同源 Cookie 透传 |
+| SPA / 原生 App（跨域请求） | **本模块** `api.init()` + `api.call()` | 完整 Token 管理、401 自动刷新、独立 baseUrl |
+| 契约调用（类型安全，跨域） | **本模块** `api.call(endpoint, input)` | EndpointDef 双向 Zod 校验 |
+
+---
+
 ## 适用场景
 
 - 浏览器端/App 端统一 API 请求
@@ -247,11 +261,6 @@ const chat = await api.call(aiEndpoints.sendMessage, {
 | `ai`       | `@h-ai/ai/api`       | `aiEndpoints`        | chat, chatStream, sendMessage   |
 | `payment`  | `@h-ai/payment/api`  | `paymentEndpoints`   | createOrder, queryOrder, …      |
 
-### 新模块接入契约
-
-在模块 `src/api/` 下创建 Schema + Contract，并在 `package.json` 中声明 `"./api"` 子路径导出。
-
----
 
 ## 常见模式
 

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

@@ -7,6 +7,10 @@ description: 使用 @h-ai/audit 进行审计日志的记录、查询、清理与
 
 统一审计日志模块，基于 `@h-ai/reldb` 实现持久化，提供审计日志的记录、分页查询、清理与统计。
 
+## 运行环境
+
+> ⚠️ **服务端模块（Node.js only）。** 审计日志由服务端自动记录，浏览器端通过 API 端点查询审计数据。
+
 ## 依赖
 
 | 模块 | 用途 | 是否必需 | 初始化要求 |

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

@@ -9,6 +9,12 @@ description: 使用 @h-ai/cache 进行内存或 Redis 缓存操作（kv/hash/lis
 
 ---
 
+## 运行环境
+
+> ⚠️ **服务端模块（Node.js only）。** 浏览器端无需直接操作缓存，由服务端模块（如 IAM、Scheduler）内部使用。
+
+---
+
 ## 适用场景
 
 - 缓存热点数据减少数据库查询

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

@@ -9,6 +9,12 @@ description: 使用 @h-ai/capacitor 桥接 Capacitor 原生能力（Token 安全
 
 ---
 
+## 运行环境
+
+> **浏览器端 / 原生 App 专用。** 在 Capacitor 原生环境（Android/iOS）中提供完整能力，纯 Web 环境下部分功能退化（如 Preferences 退化为 localStorage）。
+
+---
+
 ## 适用场景
 
 - Android/iOS 原生应用开发（SvelteKit + Capacitor）
@@ -20,24 +26,6 @@ description: 使用 @h-ai/capacitor 桥接 Capacitor 原生能力（Token 安全
 
 ---
 
-## 模块结构
-
-```
-packages/capacitor/src/
-  index.ts                    # export * 聚合
-  capacitor-main.ts           # 服务对象（export const capacitor）
-  capacitor-types.ts           # 公共类型（CapacitorFunctions / CapacitorError / 业务类型）
-  capacitor-config.ts          # 错误码（HaiCapacitorError as const）
-  capacitor-i18n.ts            # i18n 消息获取器
-  capacitor-token-storage.ts   # Token 存储（TokenStorage 实现 + safe* 工具）
-  capacitor-device.ts          # 设备信息
-  capacitor-camera.ts          # 相机/相册
-  capacitor-push.ts            # 推送通知
-  capacitor-status-bar.ts      # 状态栏
-```
-
----
-
 ## 使用步骤
 
 ### 1. 初始化与关闭

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

@@ -9,6 +9,20 @@ description: 使用 @h-ai/core 进行配置加载、日志记录、i18n 国际
 
 ---
 
+## 运行环境
+
+**Node.js + 浏览器双端可用。** 构建工具自动选择正确入口（`package.json` exports 条件导出）。
+
+| 能力 | Node.js | 浏览器 |
+|------|---------|--------|
+| `core.logger` | ✅ pino（结构化 JSON / pretty） | ✅ loglevel（DevTools console） |
+| `core.config` | ✅ 完整（YAML 加载、watch、validate） | ⚠️ 仅支持 `core.init({ ... })` 传入配置 |
+| `core.i18n` | ✅ | ✅ |
+| `core.id` | ✅ | ✅ |
+| 工具函数 | ✅ | ✅ |
+
+---
+
 ## 适用场景
 
 - 项目初始化与配置加载
@@ -98,24 +112,8 @@ const unwatch = core.config.watch('db', (cfg, error) => {
 
 // 调用 unwatch() 停止监听
 unwatch()
-
-// 配置未加载时立即返回 NOT_LOADED 错误
-core.config.watch('nonexistent', (_cfg, error) => {
-  // error.code === HaiConfigError.CONFIG_NOT_LOADED.code
-})
-
-// 多个监听回调可在同一配置文件变更时同时触发
-core.config.watch('app', cb1)
-core.config.watch('app', cb2) // cb1 和 cb2 都会被调用
 ```
 
-**文件监听特性**：
-
-- 使用 `fs.watch()` 实现，自动防抖（100ms 防抖避免快速重复保存触发多次回调）
-- 同一配置名只会创建一个 watcher（多次 `watch()` 共享同一 watcher 实例）
-- 当最后一个回调被移除时，watcher 自动关闭
-- `unwatch()` 会关闭watcher，但缓存的配置数据保留
-
 配置文件格式（YAML，支持环境变量插值）：
 
 - `${VAR}` — 读取 `process.env.VAR`；缺失则返回 `HaiConfigError.CONFIG_ENV_VAR_MISSING` 错误
@@ -301,62 +299,13 @@ core.time.addDays(date, 7)
 所有 hai 模块操作返回 `HaiResult<T>` 类型，强制处理成功/失败分支：
 
 ```typescript
-import type { HaiResult, HaiErrorDef, HaiError } from '@h-ai/core'
-import { err, ok } from '@h-ai/core'
+import { ok, err, HaiCommonError } from '@h-ai/core'
 
 // 成功
 return ok(data)
 
-// 失败：使用预定义错误定义创建错误实例
+// 失败
 return err(HaiCommonError.NOT_FOUND, 'Resource not found')
-
-// 带原始错误和建议的完整失败
-return err(
-  HaiCommonError.INTERNAL_ERROR,
-  'Failed to process request',
-  originalError,
-  'Check database connection'
-)
-```
-
-**错误定义 vs 错误实例**：
-
-```typescript
-// HaiErrorDef 是错误定义（包含错误码、HTTP 状态码、模块信息）
-const errorDef: HaiErrorDef = {
-  code: 'hai:common:001',        // system:module:code
-  httpStatus: 500,               // HTTP 响应状态码
-  system: 'hai',                 // 系统标识
-  module: 'common',              // 所属模块
-}
-
-// HaiError 是具体错误实例（包含定义数据 + 运行时信息）
-const errorInst: HaiError = {
-  ...errorDef,
-  message: '具体错误消息',        // i18n 翻译后的消息
-  cause?: originalError,         // 原始错误
-  suggestion?: '用户可采取的行动', // 建议
-}
-
-// err() 函数接受 HaiErrorDef，自动创建 HaiError 实例
-err(errorDef, '消息文本', cause, '建议')
-```
-
-**HaiResult 类型定义**：
-
-```typescript
-type HaiResult<T>
-  = | { success: true, data: T }
-  | { success: false, error: HaiError }
-  code: string
-  message: string
-  httpStatus?: number
-  system?: string
-  module?: string
-  cause?: unknown
-  suggestion?: string
-  ext?: Record<string, unknown>
-}
 ```
 
 **使用模式**：
@@ -377,35 +326,6 @@ if (!result.success)
 // 后续代码可安全使用 result.data
 ```
 
-### 模块工具 — `core.module`
-
-| 方法                      | 签名                                                                 | 说明                                     |
-| ------------------------- | -------------------------------------------------------------------- | ---------------------------------------- |
-| `createNotInitializedKit` | `<E>(code: E['code'], messageFn: () => string) => NotInitializedKit` | 创建未初始化代理（访问任何方法返回错误） |
-
-```typescript
-// 在模块 main.ts 中使用
-const notInitialized = core.module.createNotInitializedKit(
-  HaiReldbError.NOT_INITIALIZED,
-  () => reldbM('reldb_notInitialized'),
-)
-
-// 创建占位 Proxy（异步接口，默认）
-let currentDdl: DdlOperations = notInitialized.proxy<DdlOperations>()
-// 创建占位 Proxy（同步接口）
-const currentHash: HashOperations = notInitialized.proxy<HashOperations>('sync')
-
-export const myModule = {
-  async init(config) {
-    currentDdl = createDdlOperations(config)
-    return ok(undefined)
-  },
-  get ddl() {
-    return currentDdl
-  },
-}
-```
-
 ## 错误码
 
 Core 模块定义了两组标准错误码：
@@ -471,27 +391,6 @@ if (!result.success) {
 }
 ```
 
-### 自定义错误码（模块级）
-
-各模块应定义自己的错误码常量，遵循格式 `hai:<module>:<code>`：
-
-```typescript
-// 示例：db 模块定义错误码
-const DbErrorInfo = {
-  NOT_INITIALIZED: '001:500',
-  CONNECTION_FAILED: '010:500',
-  QUERY_FAILED: '011:500',
-  INVALID_SCHEMA: '012:400',
-} as const satisfies ErrorInfo
-
-export const DbError = error.buildHaiErrorsDef('db', DbErrorInfo)
-
-// 使用
-import { DbError, err } from '@h-ai/db'
-
-err(DbError.CONNECTION_FAILED, 'Failed to connect to PostgreSQL')
-```
-
 ## 常见模式
 
 ### 服务端初始化（SvelteKit hooks.server.ts）
@@ -542,3 +441,44 @@ const config = result.data // 类型安全
 - `hai-build`：项目整体架构与技能导航
 - `hai-kit`：SvelteKit 集成层（Handle/Guard/Middleware）
 - `hai-reldb` / `hai-cache` / `hai-iam`：使用 core.config 读取配置的下游模块
+
+---
+
+## 浏览器侧使用
+
+> **禁止在应用中直接引入 `loglevel`。** `core.logger` 在浏览器端自动使用 loglevel 作为后端，API 与 Node.js 完全一致。
+
+### 初始化
+
+浏览器端无文件系统，不需要 `configDir`。在 `+layout.svelte` 或应用入口调用：
+
+```typescript
+import { core } from '@h-ai/core'
+
+// 浏览器端：仅传入 logging 配置即可
+core.init({ logging: { level: 'info' } })
+```
+
+### 日志记录
+
+```typescript
+// 与 Node.js 完全一致的 API
+core.logger.info('Page loaded', { route: '/home' })
+core.logger.error('API call failed', { url, status })
+
+// 创建模块级 logger
+const logger = core.logger.create({ name: 'my-page' })
+logger.debug('Data fetched', { count: items.length })
+
+// ❌ 禁止直接引用底层日志库
+// import log from 'loglevel'  ← 不要这样做
+```
+
+### 浏览器侧限制
+
+| 功能 | 行为 |
+|------|------|
+| `format: 'json' \| 'pretty'` | 被忽略（始终输出到 DevTools console） |
+| `redact` 字段脱敏 | 不生效（需手动脱敏） |
+| `fatal` 级别 | 映射为 `console.error`（带 `[FATAL]` 前缀） |
+| context 输出 | JSON 字符串追加到消息末尾（非结构化对象） |

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

@@ -9,6 +9,21 @@ description: 使用 @h-ai/crypto 进行加密（非对称/哈希/对称）与密
 
 ---
 
+## 运行环境
+
+**Node.js + 浏览器双端可用。** 浏览器端通过 `crypto.init()` 初始化（无需配置参数）。
+
+| 能力 | Node.js | 浏览器 | 说明 |
+|------|---------|--------|------|
+| `crypto.asymmetric` 非对称加密 | ✅ | ✅ | SM2 加解密、签名验签 |
+| `crypto.hash` 哈希 | ✅ | ✅ | SM3 哈希、HMAC |
+| `crypto.symmetric` 对称加密 | ✅ | ✅ | SM4 ECB/CBC |
+| `crypto.password` 密码哈希 | ✅ | ❌ | 依赖 Node.js crypto（服务端专用） |
+
+浏览器端主要用于 kit 传输加密场景（`kit.client.create({ transport: { crypto } })`），一般不需要直接调用 crypto API。
+
+---
+
 ## 适用场景
 
 - 非对称加密/解密、签名/验签、密钥生成

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

@@ -9,6 +9,12 @@ description: 使用 @h-ai/datapipe 进行文本清洗（HTML/URL/空白移除）
 
 ---
 
+## 运行环境
+
+> **服务端模块（Node.js only）。** 通常在 AI 知识库入库或文档预处理场景中使用，由 `@h-ai/ai` 内部调用或在服务端显式调用。
+
+---
+
 ## 适用场景
 
 - 文本清洗：移除 HTML 标签、URL、Email，标准化空白

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

@@ -9,6 +9,12 @@ description: 使用 @h-ai/deploy 进行自动化部署：Vercel 部署 + 基础
 
 ---
 
+## 运行环境
+
+> ⚠️ **Node.js CLI / 服务端模块。** 通过 `hai deploy` CLI 命令或在 Node.js 脚本中使用。
+
+---
+
 ## 适用场景
 
 - 一键部署 SvelteKit 应用到 Vercel

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

@@ -9,6 +9,12 @@ description: 使用 @h-ai/iam 进行身份认证（密码/OTP/LDAP/API Key）、
 
 ---
 
+## 运行环境
+
+> ⚠️ **服务端模块（Node.js only）。** 浏览器端通过 `api.call(iamEndpoints.xxx)` 或 `apiFetch` 调用 IAM API 端点（参见 hai-api-client / hai-kit SKILL）。`@h-ai/iam/api` 子路径导出的 Zod Schema 和 EndpointDef 可在浏览器端使用。
+
+---
+
 ## 依赖
 
 | 模块 | 用途 | 是否必需 | 初始化要求 |
@@ -243,7 +249,7 @@ const result = await api.call(iamEndpoints.login, { username, password })
 | `HaiIamError.PASSWORD_EXPIRED` | `hai:iam:007` | 密码已过期 |
 | `HaiIamError.PASSWORD_POLICY_VIOLATION` | `hai:iam:008` | 密码不符合策略 |
 | `HaiIamError.OTP_INVALID` | `hai:iam:009` | 验证码无效 |
-| `HaiIamError.OTP_EXPIRED` | `hai:iam:010` | 验证码已过期 |
+| `HaiIamError.NOT_INITIALIZED` | `hai:iam:010` | 未初始化 |
 | `HaiIamError.OTP_RESEND_TOO_FAST` | `hai:iam:011` | 发送过于频繁 |
 | `HaiIamError.LOGIN_DISABLED` | `hai:iam:012` | 登录方式已禁用 |
 | `HaiIamError.REGISTER_DISABLED` | `hai:iam:013` | 注册已禁用 |
@@ -255,6 +261,7 @@ const result = await api.call(iamEndpoints.login, { username, password })
 | `HaiIamError.RESET_TOKEN_INVALID` | `hai:iam:019` | 重置令牌无效 |
 | `HaiIamError.RESET_TOKEN_EXPIRED` | `hai:iam:020` | 重置令牌已过期 |
 | `HaiIamError.RESET_TOKEN_MAX_ATTEMPTS` | `hai:iam:021` | 重置验证次数超限 |
+| `HaiIamError.OTP_EXPIRED` | `hai:iam:022` | 验证码已过期 |
 | `HaiIamError.SESSION_NOT_FOUND` | `hai:iam:101` | 会话不存在 |
 | `HaiIamError.SESSION_EXPIRED` | `hai:iam:102` | 会话已过期 |
 | `HaiIamError.SESSION_INVALID` | `hai:iam:103` | 会话无效 |
@@ -276,7 +283,6 @@ const result = await api.call(iamEndpoints.login, { username, password })
 | `HaiIamError.FORBIDDEN` | `hai:iam:501` | 禁止访问 |
 | `HaiIamError.INVALID_ARGUMENT` | `hai:iam:502` | 参数无效 |
 | `HaiIamError.CONFIG_ERROR` | `hai:iam:901` | 配置错误 |
-| `HaiIamError.NOT_INITIALIZED` | `hai:iam:910` | 未初始化 |
 | `HaiIamError.INTERNAL_ERROR` | `hai:iam:999` | 内部错误 |
 
 ---

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

@@ -23,6 +23,9 @@ description: 使用 @h-ai/kit 构建 SvelteKit 请求管道与 API 安全边界
 - `kit.guard.*`（`require` / `check`）
 - `kit.handler` / `kit.response` / `kit.validate`
 - `kit.fromContract(endpoint, fn)` — 契约到 SvelteKit handler
+- `kit.client.create()` — 浏览器端统一 API 客户端（`apiFetch`）
+- `kit.auth.createTokenStore()` — 浏览器端 Token 存储
+- `kit.auth.createHandleFetch()` — `hooks.client.ts` 自动附加 Token
 - Bearer Token / `Authorization` header
 - CORS 配置（含 Capacitor Origin 预设）
 - 传输加密（key exchange / `X-Client-Id`）
@@ -61,12 +64,6 @@ export const handle = kit.createHandle({
 })
 ```
 
-Bearer Token 解析流程：
-
-1. 检查 `Authorization: Bearer <token>` header
-2. 若无 header，回退到 `event.cookies.get('hai_access_token')`（SSR 透传场景）
-3. Token 经 `auth.verifyToken` 校验后挂载到 `event.locals.session`
-
 ### 2) API 端点使用 `kit.handler`
 
 ```typescript
@@ -169,38 +166,10 @@ const myEndpoint = defineEndpoint({
 | `VALIDATION_ERROR` | 422    | 数据校验失败       |
 | `INTERNAL_ERROR`   | 500    | 未处理异常         |
 
-### 传输加密常见错误（i18n key）
-
-| key                              | 含义                               |
-| -------------------------------- | ---------------------------------- |
-| `kit_transportClientIdRequired`  | 缺少 `X-Client-Id`（强制加密模式） |
-| `kit_transportClientKeyNotFound` | 客户端密钥不存在或失效             |
-| `kit_transportInvalidPayload`    | 加密载荷格式非法                   |
-| `kit_transportDecryptFailed`     | 请求体解密失败                     |
-| `kit_transportKeyExchangeFailed` | 密钥交换失败                       |
-
 ## API 契约范式（端到端类型安全）
 
 > `kit.fromContract` 和 `api.call` 共同消费模块 `api/` 下的 `EndpointDef`，实现服务端↔客户端的全链路类型安全 + 运行时 Zod 校验。
 
-### 契约架构
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    @h-ai/xx/api                             │
-│  xx-api-schemas.ts  ←  Zod Schema（唯一真相源）            │
-│  xx-api-contract.ts ←  xxEndpoints（method + path + schema）│
-└─────────────┬──────────────────────────┬────────────────────┘
-              │                          │
-     ┌────────▼────────┐       ┌─────────▼─────────┐
-     │  客户端（浏览器）│       │  服务端（SvelteKit）│
-     │  api.call(ep, i) │       │  kit.fromContract  │
-     │  @h-ai/api-client│       │  @h-ai/kit         │
-     └────────┬────────┘       └─────────┬─────────┘
-              │      HTTP（类型安全）     │
-              └──────────────────────────┘
-```
-
 ### 服务端流程（本模块责任）
 
 1. 从 `@h-ai/xx/api` 导入 `xxEndpoints`
@@ -249,33 +218,8 @@ export const POST = kit.fromContract(paymentEndpoints.createOrder, async (input,
 })
 ```
 
-### 已有契约模块一览
-
-| 模块       | 导入路径               | 端点对象             | 典型端点                        |
-| ---------- | -------------------- | -------------------- | ------------------------------- |
-| `storage`  | `@h-ai/storage/api`  | `storageEndpoints`   | presignUpload, listFiles, …     |
-| `iam`      | `@h-ai/iam/api`      | `iamEndpoints`       | login, logout, currentUser, …   |
-| `ai`       | `@h-ai/ai/api`       | `aiEndpoints`        | chat, chatStream, sendMessage   |
-| `payment`  | `@h-ai/payment/api`  | `paymentEndpoints`   | createOrder, queryOrder, …      |
-
-### 新模块接入契约
-
-在模块 `src/api/` 下创建 Schema + Contract，并在 `package.json` 中声明 `"./api"` 子路径导出。
-
 ## 常见模式
 
-### Bearer Token 认证流程
-
-```
-客户端 → Authorization: Bearer <accessToken> → kit.createHandle 解析
-                                                  ↓
-                                        auth.verifyToken(token) → locals.session
-                                                  ↓
-                                        protectedPaths 守卫检查 → 通过则继续
-```
-
-SSR 场景下，浏览器通过 `hai_access_token` httpOnly Cookie 透传 Token，Handle 自动回退读取。
-
 ### 契约模式（推荐新项目使用）
 
 1. 在模块的 `api/` 目录定义 `EndpointDef`（Zod schema）
@@ -314,6 +258,97 @@ const config = {
 
 - `hai-core`：全局配置、日志、HaiResult 基础能力
 - `hai-iam`：Token 认证、角色权限模型
-- `hai-api-client`：客户端契约调用
+- `hai-api-client`：客户端契约调用（SPA / 原生 App 场景）
 - `hai-crypto`：传输加密与密钥管理能力
 - `hai-capacitor`：原生 App CORS 场景
+
+---
+
+## 浏览器侧使用
+
+### 创建统一 API 客户端 — `kit.client`
+
+> **所有浏览器端 API 请求必须通过 `apiFetch`，禁止直接 `fetch()`。**
+
+在 `src/lib/utils/api.ts` 中一次性创建，全应用共享：
+
+```typescript
+// src/lib/utils/api.ts
+import { kit } from '@h-ai/kit'
+
+const client = kit.client.create({
+  auth: true, // 自动从 localStorage 注入 Bearer Token
+})
+
+export const { apiFetch } = client
+```
+
+如需传输加密，传入 crypto：
+
+```typescript
+import { crypto } from '@h-ai/crypto'
+import { kit } from '@h-ai/kit'
+
+if (typeof window !== 'undefined') {
+  crypto.init() // 浏览器端初始化加密模块
+}
+
+const client = kit.client.create({
+  transport: { crypto }, // 透明完成密钥交换 + 请求/响应体加解密
+  auth: true,
+})
+
+export const { apiFetch } = client
+```
+
+`apiFetch` 自动处理：
+- **CSRF**：写方法（POST/PUT/DELETE）自动读取 `hai_csrf` Cookie 并设置 `X-CSRF-Token`
+- **Bearer Token**：自动从 localStorage 读取并注入 `Authorization` header
+- **传输加密**：可选，首次写请求时自动密钥交换
+
+使用示例：
+
+```typescript
+// ✅ 正确方式
+import { apiFetch } from '$lib/utils/api'
+
+const res = await apiFetch('/api/users', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify(data),
+})
+
+// ❌ 禁止在组件中直接 fetch
+// const res = await fetch('/api/users', { ... })
+```
+
+### Token 存储 — `kit.auth.createTokenStore`
+
+```typescript
+import { kit } from '@h-ai/kit'
+
+// 创建 localStorage 存储（Web 端默认）
+const tokenStore = kit.auth.createTokenStore('hai_access_token')
+tokenStore.set(tokens.accessToken) // 登录后保存
+tokenStore.get()                   // string | null
+tokenStore.clear()                 // 登出时清除
+```
+
+### hooks.client.ts 标准配置 — `kit.auth.createHandleFetch`
+
+```typescript
+// src/hooks.client.ts
+import { kit } from '@h-ai/kit'
+
+// 自动为同源请求附加 Authorization: Bearer <token>
+export const handleFetch = kit.auth.createHandleFetch()
+```
+
+### 选择指南：kit.client vs api-client
+
+| 场景 | 推荐 | 原因 |
+|------|------|------|
+| SSR SvelteKit 应用（同源请求） | `kit.client.create().apiFetch` | 自动 CSRF、同源 Cookie 透传、传输加密 |
+| SPA / 原生 App（跨域请求） | `api.init()` + `api.call()` | 完整 Token 管理、401 自动刷新 |
+| 服务端 `+page.server.ts` | 直接调用模块 API | 无需 HTTP 自环 |
+| 契约调用（类型安全） | `api.call(endpoint, input)` | EndpointDef 双向 Zod 校验 |

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

@@ -9,6 +9,12 @@ description: 使用 @h-ai/payment 接入微信支付、支付宝、Stripe 统一
 
 ---
 
+## 运行环境
+
+> **服务端 + 浏览器分工模块。** `payment.createOrder` / `payment.handleNotify` / `payment.refund` 等操作在 Node.js 端执行。浏览器端使用 `invokePayment()`（从 `@h-ai/payment/client` 导入）调起支付。
+
+---
+
 ## 依赖
 
 | 模块 | 用途 | 是否必需 | 初始化要求 |
@@ -189,25 +195,14 @@ const payResult = await invokePayment(orderResult.data)
 
 ## Provider 模式
 
-### PaymentProvider 接口
-
-```typescript
-interface PaymentProvider {
-  readonly name: string
-  createOrder: (input: CreateOrderInput) => Promise<HaiResult<PaymentOrder>>
-  handleNotify: (request: PaymentNotifyRequest) => Promise<HaiResult<PaymentNotifyResult>>
-  queryOrder: (outTradeNo: string) => Promise<HaiResult<OrderStatus>>
-  refund: (input: RefundInput) => Promise<HaiResult<RefundResult>>
-  closeOrder: (outTradeNo: string) => Promise<HaiResult<void>>
-}
-```
-
 内置 Provider：
 
-- **wechat** — 微信支付 API v3（RSA-SHA256 签名、AES-256-GCM 回调解密）
-- **alipay** — 支付宝开放平台（RSA2 签名验签）
+- **wechat** — 微信支付 API v3
+- **alipay** — 支付宝开放平台
 - **stripe** — Stripe Checkout Session 模式
 
+自定义 Provider 通过 `payment.registerProvider(provider)` 注册。
+
 ### API 契约
 
 ```typescript
@@ -267,16 +262,7 @@ export const POST = kit.handler(async ({ request, locals }) => {
 
 ## 审计日志
 
-关键支付操作成功后自动写入审计日志（依赖 `@h-ai/audit`），无需额外配置。失败仅 warn，不影响支付流程。
-
-| 操作 | `action` | `resource` | `resourceId` | `details` |
-| --- | --- | --- | --- | --- |
-| 创建订单 | `create_order` | `payment` | `orderNo` | `{ provider, amount, tradeType }` |
-| 支付回调 | `payment_notify` | `payment` | `orderNo` | `{ provider, transactionId, status, amount }` |
-| 退款 | `refund` | `payment` | `orderNo` | `{ provider, refundNo, amount }` |
-| 关闭订单 | `close_order` | `payment` | `orderNo` | `{ provider }` |
-
-> `queryOrder` 为只读操作，不写审计日志。
+关键支付操作（创建订单、回调、退款、关闭订单）成功后自动写入审计日志（依赖 `@h-ai/audit`），无需额外配置。`queryOrder` 为只读操作，不写审计日志。
 
 ---
 

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

@@ -9,6 +9,12 @@ description: 使用 @h-ai/reach 进行邮件、短信和 API 回调发送；当
 
 ---
 
+## 运行环境
+
+> ⚠️ **服务端模块（Node.js only）。** 浏览器端不直接发送邮件/短信，而是通过 API 端点触发服务端 `reach.send()`。
+
+---
+
 ## 依赖
 
 | 模块 | 用途 | 是否必需 | 初始化要求 |
@@ -300,22 +306,6 @@ if (!result.success) {
 }
 ```
 
-### 分布式锁（DND flush 保护）
-
-> 多节点部署时，DND（delay 策略）的 pending 消息 flush 通过 `@h-ai/cache` 分布式锁保护，确保同一时刻只有一个节点执行 flush。
-
-```typescript
-import { cache } from '@h-ai/cache'
-
-// 初始化 cache 后，reach 自动使用分布式锁保护 flush 操作
-await cache.init({ type: 'redis', host: 'localhost', port: 6379 })
-await reach.init({ /* ... */ })
-```
-
-- 锁键：`reach:flush-pending`，TTL 60 秒
-- 若 cache 未初始化，分布式锁自动禁用，不影响单节点运行
-- 使用稳定的进程级 owner 标识，防止误释放他人锁
-
 ---
 
 ## 相关 Skills

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

@@ -9,6 +9,12 @@ description: 使用 @h-ai/reldb 进行 SQLite/PostgreSQL/MySQL 的初始化、SQ
 
 ---
 
+## 运行环境
+
+> ⚠️ **服务端模块（Node.js only）。** 浏览器端请通过 API 端点间接访问数据库（参见 hai-kit 契约模式 `kit.fromContract`）。
+
+---
+
 ## 适用场景
 
 - 新增或修改数据库访问逻辑（SQL/DDL/CRUD/事务）
@@ -310,7 +316,7 @@ if (txResult.success) {
 }
 ```
 
-**事务内可用操作**（`DmlWithTxOperations` 继承 `DmlOperations`）：
+**事务内可用操作**：
 
 - `tx.query / tx.get / tx.execute / tx.batch / tx.queryPage`
 - `tx.crud.table(config)` — 事务内的 CRUD 仓库
@@ -392,11 +398,11 @@ await reldb.sql.execute(`UPDATE users SET profile = ${sql} WHERE id = ?`, [...pa
 | `HaiReldbError.DUPLICATE_ENTRY`      | `hai:reldb:007`  | 重复条目           |
 | `HaiReldbError.DEADLOCK`             | `hai:reldb:008`  | 死锁               |
 | `HaiReldbError.TIMEOUT`              | `hai:reldb:009`  | 超时               |
-| `HaiReldbError.POOL_EXHAUSTED`       | `hai:reldb:010`  | 连接池耗尽         |
-| `HaiReldbError.NOT_INITIALIZED`      | `hai:reldb:011`  | 数据库未初始化     |
-| `HaiReldbError.DDL_FAILED`           | `hai:reldb:012`  | DDL 操作失败       |
-| `HaiReldbError.UNSUPPORTED_TYPE`     | `hai:reldb:013`  | 不支持的数据库类型 |
-| `HaiReldbError.CONFIG_ERROR`         | `hai:reldb:014`  | 配置错误           |
+| `HaiReldbError.NOT_INITIALIZED`      | `hai:reldb:010`  | 数据库未初始化     |
+| `HaiReldbError.POOL_EXHAUSTED`       | `hai:reldb:011`  | 连接池耗尽         |
+| `HaiReldbError.UNSUPPORTED_TYPE`     | `hai:reldb:012`  | 不支持的数据库类型 |
+| `HaiReldbError.CONFIG_ERROR`         | `hai:reldb:013`  | 配置错误           |
+| `HaiReldbError.DDL_FAILED`           | `hai:reldb:020`  | DDL 操作失败       |
 
 ---
 

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

@@ -7,6 +7,10 @@ description: 使用 @h-ai/scheduler 进行统一定时任务管理、任务持
 
 > `@h-ai/scheduler` 使用统一任务模型管理 API / JS / Hook 三类执行路径，支持持久化、手工触发来源记录、分布式锁与全局生命周期回调。
 
+## 运行环境
+
+> ⚠️ **服务端模块（Node.js only）。** 浏览器端通过 API 端点触发 `scheduler.trigger()` 或查询任务日志。
+
 ## 依赖
 
 | 模块 | 用途 | 是否必需 | 初始化要求 |
@@ -20,6 +24,7 @@ description: 使用 @h-ai/scheduler 进行统一定时任务管理、任务持
 
 ```ts
 import { cache } from '@h-ai/cache'
+import { core } from '@h-ai/core'
 import { reldb } from '@h-ai/reldb'
 import { scheduler } from '@h-ai/scheduler'
 
@@ -32,13 +37,13 @@ await scheduler.init({
   retentionDays: 30,
   hooks: {
     onTaskStart(event) {
-      console.info('start', event.task.id, event.trigger)
+      core.logger.info('Task started', { taskId: event.task.id, trigger: event.trigger })
     },
     onTaskInterrupted(event) {
-      console.warn('interrupted', event.task.id, event.reason)
+      core.logger.warn('Task interrupted', { taskId: event.task.id, reason: event.reason })
     },
     onTaskFinish(event) {
-      console.info('finish', event.log.status)
+      core.logger.info('Task finished', { status: event.log.status })
     },
   },
 })
@@ -106,65 +111,6 @@ const logs = await scheduler.getLogs({
 })
 ```
 
-## 核心类型
-
-### TaskDefinition
-
-```ts
-interface TaskDefinition {
-  id: string
-  name: string
-  description?: string
-  cron: string
-  enabled?: boolean
-  deleteAfterRun?: boolean
-  retry?: {
-    maxAttempts: number
-    backoffMs?: number[]
-  }
-  params?: Record<string, unknown>
-  handler?: ApiTaskConfig | JsTaskConfig
-}
-```
-
-### Handler 配置
-
-```ts
-interface ApiTaskConfig {
-  kind: 'api'
-  url: string
-  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'
-  headers?: Record<string, string>
-  body?: unknown
-  timeout?: number
-}
-
-interface JsTaskConfig {
-  kind: 'js'
-  code: string
-  timeout?: number
-}
-```
-
-### TaskExecutionLog
-
-```ts
-interface TaskExecutionLog {
-  id: number
-  taskId: string
-  taskName: string
-  taskType: 'api' | 'js' | 'hook'
-  triggerType: 'scheduled' | 'manual'
-  triggerSource: string | null
-  status: 'success' | 'failed' | 'interrupted'
-  result: string | null
-  error: string | null
-  startedAt: number
-  finishedAt: number
-  duration: number
-}
-```
-
 ## 核心 API
 
 | 方法 / 属性 | 签名 | 说明 |

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

@@ -9,6 +9,12 @@ description: 使用 @h-ai/storage 进行文件存储操作（本地/S3），包
 
 ---
 
+## 运行环境
+
+> ⚠️ **服务端模块**。`storage.file` / `storage.dir` / `storage.presign` 均在 Node.js 端使用。浏览器端通过预签名 URL 或 API 端点间接访问存储（见下方「浏览器端文件上传」）。
+
+---
+
 ## 适用场景
 
 - 文件上传与下载
@@ -222,6 +228,46 @@ if (result.success) {
 
 ---
 
+## 浏览器端文件上传（预签名 URL 模式）
+
+浏览器端无法直接使用 `storage` 模块，应通过 API 获取预签名 URL 后直传：
+
+```typescript
+import { apiFetch } from '$lib/utils/api'
+
+// 1. 向服务端请求预签名上传 URL
+const res = await apiFetch('/api/storage/presign/upload', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ key: `uploads/${file.name}`, contentType: file.type }),
+})
+const { url } = await res.json()
+
+// 2. 浏览器直传到存储（不经过服务端，大文件友好）
+await fetch(url, {
+  method: 'PUT',
+  body: file,
+  headers: { 'Content-Type': file.type },
+})
+```
+
+也可使用契约调用（需配合 `@h-ai/api-client`）：
+
+```typescript
+import { api } from '@h-ai/api-client'
+import { storageEndpoints } from '@h-ai/storage/api'
+
+const result = await api.call(storageEndpoints.presignUpload, {
+  key: `avatars/${userId}.png`,
+  contentType: 'image/png',
+})
+if (result.success) {
+  await fetch(result.data.url, { method: 'PUT', body: file })
+}
+```
+
+---
+
 ## 相关 Skills
 
 - `hai-build`：模块初始化顺序

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

@@ -9,6 +9,12 @@ description: 使用 @h-ai/ui 构建多端应用界面，包含三层组件架构
 
 ---
 
+## 运行环境
+
+> **浏览器端专用。** Svelte 组件在浏览器中渲染，服务端无需引用。
+
+---
+
 ## 适用场景
 
 - 构建管理后台页面（表单、表格、弹窗、导航等）
@@ -257,10 +263,9 @@ const theme = getCurrentTheme()
 
 1. **Svelte 5 Runes**：使用 `$state`、`$derived`、`$effect`
 2. **Snippet 插槽**：使用 `{#snippet name()}...{/snippet}` 语法
-3. **三层依赖红线**：primitives 不依赖上层，compounds 只依赖 primitives + Bits UI，scenes 可依赖两者
-4. **自动导入例外**：`toast`、类型导入、`Range`/`FileList` 必须显式 `import`
-5. **Combobox 统一单选/多选**：`MultiSelect` 已删除
-6. **移动端样式**：务必引入 `design-tokens.css` + `mobile.css`，使用 SafeArea 包裹原生 App 页面
+3. **自动导入例外**：`toast`、类型导入、`Range`/`FileList` 必须显式 `import`
+4. **Combobox 统一单选/多选**：`MultiSelect` 已删除
+5. **移动端样式**：务必引入 `design-tokens.css` + `mobile.css`，使用 SafeArea 包裹原生 App 页面
 
 ---
 
@@ -271,5 +276,3 @@ const theme = getCurrentTheme()
 - `hai-iam`：IAM 模块 API（与 LoginForm/RegisterForm 配合）
 - `hai-capacitor`：原生 App 开发（与 SafeArea/AppBar 配合）
 - `hai-api-client`：客户端数据获取
-
-- `hai-capacitor`：原生 App 开发（与 SafeArea/AppBar 配合）

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

@@ -9,6 +9,12 @@ description: 使用 @h-ai/vecdb 进行向量数据库操作（LanceDB/pgvector/Q
 
 ---
 
+## 运行环境
+
+> ⚠️ **服务端模块（Node.js only）。** 浏览器端不直接操作向量数据库，通过 `@h-ai/ai` 的 API 端点间接使用（如 RAG 检索、知识库查询）。
+
+---
+
 ## 适用场景
 
 - 新增或修改向量数据库访问逻辑（集合管理/向量插入/搜索）