@h-ai/cli 0.1.0-alpha.10

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

@@ -0,0 +1,484 @@
+---
+name: hai-core
+description: 使用 @h-ai/core 进行配置加载、日志记录、i18n 国际化、HaiResult 错误处理与模块生命周期管理；当需求涉及 core.init、core.logger、core.config、core.i18n、ok/err 或模块初始化模式时使用。
+---
+
+# hai-core
+
+> `@h-ai/core` 是 hai-framework 的基础模块，提供配置管理、结构化日志、国际化、HaiResult 错误模型与模块生命周期工具。所有其他模块均依赖 core。
+
+---
+
+## 运行环境
+
+**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` | ✅ | ✅ |
+| 工具函数 | ✅ | ✅ |
+
+---
+
+## 适用场景
+
+- 项目初始化与配置加载
+- 使用 `core.logger` 记录日志
+- 使用 `core.config` 读取/校验模块配置
+- 使用 `core.i18n` 管理多语言
+- 使用 `ok()` / `err()` 构建 HaiResult 类型返回值
+- 创建模块级 logger 或 i18n 消息获取器
+
+---
+
+## 使用步骤
+
+### 1. 初始化
+
+```typescript
+import { core } from '@h-ai/core'
+
+// 自动加载 config/ 目录下的所有 _*.yml 和 *.yml
+core.init({ configDir: './config' })
+
+// 也可指定日志级别和配置监听
+core.init({ configDir: './config', watchConfig: true })
+```
+
+### 2. 使用功能
+
+```typescript
+// 日志
+core.logger.info('Server started', { port: 3000 })
+
+// 配置
+const dbConfig = core.config.get('db')
+```
+
+---
+
+## 核心 API
+
+### 生命周期
+
+| 方法        | 签名                              | 说明                                      |
+| ----------- | --------------------------------- | ----------------------------------------- |
+| `core.init` | `(options?: CoreOptions) => void` | 初始化（同步，加载配置目录中的所有 YAML） |
+
+> `CoreOptions`：`{ logging?: Partial<LoggingConfig>, configDir?: string, watchConfig?: boolean }`
+>
+> 注意：core 没有 `close()` 方法，初始化后持续可用。
+
+### 配置管理 — `core.config`
+
+| 方法         | 签名                                                           | 说明                           |
+| ------------ | -------------------------------------------------------------- | ------------------------------ |
+| `get`        | `<T>(name: string) => T \| undefined`                          | 获取模块配置段                 |
+| `getOrThrow` | `<T>(name: string) => T`                                       | 获取配置（未加载时抛异常）     |
+| `load`       | `<T>(name, filePath, schema?) => HaiResult<T>`       | 手动加载配置文件               |
+| `validate`   | `<T>(name: string, schema: ZodType) => HaiResult<T>` | 用 Zod Schema 校验已加载的配置 |
+| `has`        | `(name: string) => boolean`                                    | 检查配置段是否存在             |
+| `reload`     | `(name: string) => HaiResult<unknown>`               | 重新从磁盘加载配置             |
+| `clear`      | `(name?: string) => void`                                      | 清除配置缓存                   |
+| `keys`       | `() => string[]`                                               | 获取所有已加载的配置名称       |
+| `watch`      | `<T>(name, callback) => () => void`                            | 监听配置文件变更并自动重载     |
+| `unwatch`    | `(name?: string) => void`                                      | 停止配置文件监听               |
+| `isWatching` | `(name: string) => boolean`                                    | 检查是否正在监听某个配置       |
+
+**`watch()` 回调处理**：
+
+```typescript
+// watch 回调签名：(config: T | null, error?: HaiError) => void
+// - 成功重载时：传入新配置，error 为 undefined
+// - 重载失败时：config 为 null，error 为错误详情（包含 code 和 message）
+
+const unwatch = core.config.watch('db', (cfg, error) => {
+  if (error) {
+    // 处理重载失败（如文件解析错误），不应更新本地使用的配置
+    core.logger.error('Config reload failed', {
+      name: 'db',
+      code: error.code,
+      message: error.message,
+    })
+    return
+  }
+  // 使用新配置
+  // 注意：此时 core.config.get('db') 已经指向新数据
+  core.logger.info('Config updated', { db: cfg })
+})
+
+// 调用 unwatch() 停止监听
+unwatch()
+```
+
+配置文件格式（YAML，支持环境变量插值）：
+
+- `${VAR}` — 读取 `process.env.VAR`；缺失则返回 `HaiConfigError.CONFIG_ENV_VAR_MISSING` 错误
+- `${VAR:default}` — 读取 `process.env.VAR`；缺失则使用默认值
+- **类型还原**：整个值恰好是单个变量表达式时，结果还原为原生类型（number / boolean 等）；混合文本始终为字符串
+
+```yaml
+# config/_core.yml
+app:
+  name: ${HAI_APP_NAME:my-app} # → string
+  env: ${HAI_ENV:development} # → string
+log:
+  level: ${HAI_LOG_LEVEL:info} # → string
+  format: ${HAI_LOG_FORMAT:pretty} # → string，pretty | json
+feature:
+  debug: ${DEBUG:false} # → boolean false（类型还原）
+  maxRetries: ${MAX_RETRIES:3} # → number 3（类型还原）
+  url: http://${HOST}:${PORT} # → string（混合文本，不还原）
+```
+
+### 日志 — `core.logger`
+
+`core.logger` 既是默认 Logger 实例，也是日志管理的统一入口。
+
+**日志记录**（实例方法）：`trace` / `debug` / `info` / `warn` / `error` / `fatal`
+
+```typescript
+core.logger.info('User created', { userId: '123' })
+core.logger.error('Failed to connect', { error })
+core.logger.debug('Processing item', { id, step: 'validation' })
+```
+
+**管理方法**：
+
+| 方法        | 签名                                   | 说明                     |
+| ----------- | -------------------------------------- | ------------------------ |
+| `create`    | `(options?: LoggerOptions) => Logger`  | 创建新 Logger 实例       |
+| `child`     | `(context: Record<string, unknown>) => Logger` | 创建携带固定上下文的子 Logger |
+| `configure` | `(config: Partial<LoggingConfig>) => void` | 配置全局日志选项（级别、格式等） |
+| `setLevel`  | `(level: LogLevel) => void`            | 设置全局日志级别         |
+| `getLevel`  | `() => LogLevel`                       | 获取当前全局日志级别     |
+
+```typescript
+// 创建模块级 logger
+const logger = core.logger.create({ name: 'my-module' })
+logger.info('Module initialized')
+
+// 创建携带固定上下文的子 logger（自动合并到每条日志）
+const reqLogger = core.logger.child({ requestId: 'req-001' })
+reqLogger.info('Request started') // 日志中自动包含 requestId
+
+// 配置输出格式和级别
+core.logger.configure({
+  level: 'warn',
+  format: 'json',
+  redact: ['password', 'token'], // 脱敏字段
+}) // Node.js 支持
+core.logger.setLevel('debug')
+const level = core.logger.getLevel() // 'debug'
+```
+
+**日志级别规范**：
+
+| 级别    | 适用场景                           |
+| ------- | ---------------------------------- |
+| `trace` | 循环内详细调试数据                 |
+| `debug` | 函数进入、参数概要、读操作         |
+| `info`  | 业务事件（初始化完成、写操作成功） |
+| `warn`  | 异常但可恢复（校验失败、重试）     |
+| `error` | 操作失败（需人工排查）             |
+| `fatal` | 致命错误（服务无法继续）           |
+
+### 国际化 — `core.i18n`
+
+| 方法                  | 签名                                                                  | 说明           |
+| --------------------- | --------------------------------------------------------------------- | -------------- |
+| `getGlobalLocale`     | `() => string`                                                        | 获取当前语言   |
+| `setGlobalLocale`     | `(locale: string) => void`                                            | 设置全局语言   |
+| `createMessageGetter` | `(messages: Record<string, Record<string, string>>) => MessageGetter` | 创建消息获取器 |
+
+创建模块 i18n：
+
+```typescript
+import enUS from '../messages/en-US.json'
+import zhCN from '../messages/zh-CN.json'
+
+const m = core.i18n.createMessageGetter({
+  'zh-CN': zhCN,
+  'en-US': enUS,
+})
+
+// 使用
+m('user_created') // "用户已创建"
+m('welcome', { params: { name: '张三' } }) // "欢迎，张三"
+```
+
+### ID 生成 — `core.id`
+
+| 方法           | 签名                                    | 说明                          |
+| -------------- | --------------------------------------- | ----------------------------- |
+| `generate`     | `(size?: number) => string`             | nanoid（默认 21 字符）        |
+| `short`        | `() => string`                          | 10 字符短 ID                  |
+| `withPrefix`   | `(prefix: string, length?: number) => string` | 带前缀的 nanoid               |
+| `trace`        | `() => string`                          | `trace-` 前缀 ID              |
+| `request`      | `() => string`                          | `req-` 前缀 ID                |
+| `uuid`         | `() => string`                          | UUID v4                       |
+| `isValidUUID`  | `(value: string) => boolean`            | 校验 UUID 格式                |
+| `isValidNanoId`| `(value: string, size?: number) => boolean` | 校验 nanoid 格式          |
+
+```typescript
+const id = core.id.generate()          // 'V1StGXR_Z5j3eK4uA9b8c'
+const shortId = core.id.short()        // 10 字符
+const prefixed = core.id.withPrefix('order_') // 'order_V1StGXR...'
+const traceId = core.id.trace()        // 'trace-V1StGXR...'
+const reqId = core.id.request()        // 'req-V1StGXR...'
+const uuid = core.id.uuid()            // UUID v4
+
+core.id.isValidUUID('f47ac10b-...')    // true/false
+core.id.isValidNanoId('abc123', 6)     // true/false
+```
+
+### 工具函数
+
+#### 类型检查 — `core.typeUtils`
+
+`isDefined` / `isObject` / `isFunction` / `isPromise` / `isString` / `isNumber` / `isBoolean` / `isArray`
+
+#### 对象操作 — `core.object`
+
+`deepClone` / `deepMerge` / `pick` / `omit` / `keys` / `values` / `entries` / `fromEntries`
+
+```typescript
+core.object.deepMerge(a, b, c)       // 递归合并（防原型污染）
+core.object.pick(obj, ['a', 'b'])
+core.object.omit(obj, ['c', 'd'])
+```
+
+#### 字符串操作 — `core.string`
+
+`capitalize` / `kebabCase` / `camelCase` / `snakeCase` / `pascalCase` / `truncate` / `trim` / `isBlank` / `isNotBlank` / `padStart` / `padEnd` / `constantTimeEqual`
+
+```typescript
+core.string.capitalize('hello')      // 'Hello'
+core.string.kebabCase('helloWorld')  // 'hello-world'
+core.string.constantTimeEqual(a, b)  // 防时序攻击比较
+```
+
+#### 数组操作 — `core.array`
+
+`unique` / `chunk` / `groupBy` / `first` / `last` / `flatten` / `compact` / `shuffle` / `intersection` / `difference`
+
+```typescript
+core.array.unique([1, 1, 2])           // [1, 2]
+core.array.chunk([1, 2, 3, 4], 2)      // [[1,2], [3,4]]
+core.array.groupBy(items, item => item.type) // Record<string, T[]>
+core.array.intersection([1, 2], [2, 3]) // [2]
+```
+
+#### 异步操作 — `core.async`
+
+`delay` / `withTimeout` / `retry` / `parallel` / `serial` / `debounce` / `throttle`
+
+```typescript
+await core.async.delay(1000)
+await core.async.withTimeout(fetch('/api'), 5000)
+await core.async.retry(fn, { maxRetries: 3, delay: 1000 })
+await core.async.parallel(items, processFn, 5)  // 并发限制
+const debouncedFn = core.async.debounce(fn, 300)
+```
+
+#### 时间操作 — `core.time`
+
+`formatDate` / `timeAgo` / `now` / `nowSeconds` / `parseDate` / `isValidDate` / `addDays` / `addHours` / `startOfDay` / `endOfDay`
+
+```typescript
+core.time.formatDate(new Date(), 'YYYY-MM-DD HH:mm:ss')
+core.time.timeAgo(new Date(Date.now() - 60000)) // '1 分钟前'
+core.time.addDays(date, 7)
+```
+
+### HaiResult 模型与错误处理
+
+所有 hai 模块操作返回 `HaiResult<T>` 类型，强制处理成功/失败分支：
+
+```typescript
+import { ok, err, HaiCommonError } from '@h-ai/core'
+
+// 成功
+return ok(data)
+
+// 失败
+return err(HaiCommonError.NOT_FOUND, 'Resource not found')
+```
+
+**使用模式**：
+
+```typescript
+const result = await someOperation()
+
+// 模式1：直接检查
+if (!result.success) {
+  core.logger.error('Operation failed', { error: result.error })
+  return result // 直接透传错误
+}
+const data = result.data
+
+// 模式2：提前返回
+if (!result.success)
+  return result
+// 后续代码可安全使用 result.data
+```
+
+## 错误码
+
+Core 模块定义了两组标准错误码：
+
+### `HaiCommonError`（通用错误）
+
+| 错误码 | code | 说明 |
+|--------|------|------|
+| `HaiCommonError.NOT_INITIALIZED` | `hai:common:001` | 模块未初始化 |
+| `HaiCommonError.INIT_FAILED` | `hai:common:002` | 初始化失败 |
+| `HaiCommonError.INIT_IN_PROGRESS` | `hai:common:004` | 正在初始化中 |
+| `HaiCommonError.UNAUTHORIZED` | `hai:common:100` | 未认证 |
+| `HaiCommonError.FORBIDDEN` | `hai:common:101` | 无权限 |
+| `HaiCommonError.TOKEN_EXPIRED` | `hai:common:102` | Token 已过期 |
+| `HaiCommonError.TOKEN_INVALID` | `hai:common:103` | Token 无效 |
+| `HaiCommonError.VALIDATION_ERROR` | `hai:common:200` | 校验失败 |
+| `HaiCommonError.INVALID_REQUEST` | `hai:common:201` | 请求无效 |
+| `HaiCommonError.PARAMETER_MISSING` | `hai:common:202` | 参数缺失 |
+| `HaiCommonError.NOT_FOUND` | `hai:common:300` | 资源不存在 |
+| `HaiCommonError.ALREADY_EXISTS` | `hai:common:301` | 资源已存在 |
+| `HaiCommonError.CONFLICT` | `hai:common:302` | 冲突 |
+| `HaiCommonError.API_ERROR` | `hai:common:400` | API 错误 |
+| `HaiCommonError.NETWORK_ERROR` | `hai:common:401` | 网络错误 |
+| `HaiCommonError.TIMEOUT` | `hai:common:402` | 超时 |
+| `HaiCommonError.SERVICE_UNAVAILABLE` | `hai:common:403` | 服务不可用 |
+| `HaiCommonError.INTERNAL_ERROR` | `hai:common:500` | 内部错误 |
+| `HaiCommonError.DATABASE_ERROR` | `hai:common:501` | 数据库错误 |
+| `HaiCommonError.UNKNOWN_ERROR` | `hai:common:599` | 未知错误 |
+
+**使用示例**：
+
+```typescript
+import { HaiCommonError, err } from '@h-ai/core'
+
+// 创建错误实例
+err(HaiCommonError.NOT_FOUND, 'User not found')
+err(HaiCommonError.VALIDATION_ERROR, 'Invalid email', validationErrors)
+```
+
+### `HaiConfigError`（配置错误）
+
+| 错误码 | code | 说明 |
+|--------|------|------|
+| `HaiConfigError.CONFIG_FILE_NOT_FOUND` | `hai:core:010` | 配置文件不存在 |
+| `HaiConfigError.CONFIG_PARSE_ERROR` | `hai:core:011` | YAML 解析失败 |
+| `HaiConfigError.CONFIG_VALIDATION_ERROR` | `hai:core:012` | Schema 校验失败 |
+| `HaiConfigError.CONFIG_ENV_VAR_MISSING` | `hai:core:013` | 必需环境变量缺失 |
+| `HaiConfigError.CONFIG_NOT_LOADED` | `hai:core:014` | 配置未加载 |
+
+**使用场景**：
+
+```typescript
+import { core, HaiConfigError } from '@h-ai/core'
+
+const result = core.config.load('db', './config/db.yml', schema)
+if (!result.success) {
+  if (result.error.code === HaiConfigError.CONFIG_FILE_NOT_FOUND.code) {
+    core.logger.error('Config file missing')
+  }
+  else if (result.error.code === HaiConfigError.CONFIG_VALIDATION_ERROR.code) {
+    core.logger.error('Config validation failed', { issues: result.error.cause })
+  }
+}
+```
+
+## 常见模式
+
+### 服务端初始化（SvelteKit hooks.server.ts）
+
+```typescript
+import { initModules } from '$lib/server/init'
+
+// init.ts
+import { core } from '@h-ai/core'
+
+const appHandle = kit.createHandle({ /* ... */ })
+
+export const handle = kit.sequence(appHandle)
+
+let initialized = false
+export async function initModules() {
+  if (initialized)
+    return
+  core.init({ configDir: './config' })
+  // ... 其他模块 init
+  initialized = true
+}
+```
+
+### 配置校验最佳实践
+
+```typescript
+import { z } from 'zod'
+
+const MyConfigSchema = z.object({
+  apiKey: z.string().min(1),
+  timeout: z.number().positive().default(5000),
+})
+
+// 模块初始化时校验
+const result = core.config.validate('myModule', MyConfigSchema)
+if (!result.success) {
+  core.logger.error('Invalid config', { error: result.error })
+  return result
+}
+const config = result.data // 类型安全
+```
+
+---
+
+## 相关 Skills
+
+- `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

@@ -0,0 +1,198 @@
+---
+name: hai-crypto
+description: 使用 @h-ai/crypto 进行加密（非对称/哈希/对称）与密码哈希；当需求涉及加密、解密、签名、验签、哈希、密码存储或密钥管理时使用。
+---
+
+# 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（服务端专用） |
+
+浏览器端主要用于 kit 传输加密场景（`kit.client.create({ transport: { crypto } })`），一般不需要直接调用 crypto API。
+
+---
+
+## 适用场景
+
+- 非对称加密/解密、签名/验签、密钥生成
+- 哈希计算与 HMAC
+- 对称加密/解密（ECB/CBC 模式）
+- 密码存储与验证（加盐迭代哈希）
+
+---
+
+## 使用步骤
+
+### 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<string>`       | 加密                        |
+| `decrypt`       | `(ciphertext, key, options?) => 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()
+const result = crypto.symmetric.encryptWithIV('明文数据', key)
+if (result.success) {
+  const decrypted = crypto.symmetric.decryptWithIV(result.data.ciphertext, key, result.data.iv)
+}
+```
+
+**SymmetricOptions**：`{ mode?: 'ecb' | 'cbc', iv?: string, inputEncoding?: 'utf8' | 'hex', outputFormat?: 'hex' | 'base64' }`
+
+### 密码哈希 — `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 }`
+
+---
+
+## 错误码 — `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(storedData, key)
+```
+
+### 密码存储与验证
+
+```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 集成（传输加密）