@h-ai/cli 0.1.0-alpha5

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

@@ -0,0 +1,319 @@
+---
+name: hai-build
+description: 应用开发入口技能。提供项目架构总览（SSR/SPA/原生 App 多端）、TDD 开发工作流、模块初始化顺序与技能导航。当用户需要了解项目结构、查找正确的技能、或开始新任务时触发。
+---
+
+# hai-build — 应用开发入口
+
+> 本技能是 hai-framework 应用开发的起点。帮助理解项目结构、定位正确的技能、并遵循 **TDD 驱动的标准工作流**。支持 SSR Web、SPA、Android/iOS 原生 App 等多端构建。
+
+---
+
+## 适用场景
+
+- 初次接触项目，需要了解整体架构与模块关系
+- 不确定应使用哪个技能来完成任务
+- 需要了解模块初始化顺序与依赖关系
+- 需要执行跨模块操作或全局配置变更
+- 多端构建切换（SSR ↔ SPA ↔ 原生 App）
+
+---
+
+## 项目架构
+
+### 技术栈
+
+| 层次     | 技术                           |
+| -------- | ------------------------------ |
+| 框架     | SvelteKit 2 + Svelte 5 (Runes) |
+| 样式     | TailwindCSS 4 + DaisyUI 5      |
+| 语言     | TypeScript 5.7+ (strict)       |
+| 构建     | Vite + tsup                    |
+| 包管理   | pnpm                           |
+| 单元测试 | Vitest                         |
+| E2E 测试 | Playwright                     |
+| 原生 App | Capacitor 7                    |
+| 认证     | Bearer Token（统一）           |
+
+### 多端构建模式
+
+| 模式    | Adapter        | 认证方式              | 部署目标                |
+| ------- | -------------- | --------------------- | ----------------------- |
+| SSR Web | adapter-node   | Bearer Token + Cookie | Node.js 服务器          |
+| SPA     | adapter-static | Bearer Token          | CDN / 静态托管          |
+| Android | adapter-static | Bearer Token          | Capacitor → Android APK |
+| iOS     | adapter-static | Bearer Token          | Capacitor → iOS IPA     |
+
+**Adapter 切换**：
+
+```typescript
+// svelte.config.js — 使用 kit 提供的 createAdapter
+import { createAdapter } from '@h-ai/kit/adapter'
+
+const config = {
+  kit: {
+    adapter: createAdapter(), // 根据 VITE_ADAPTER 环境变量自动选择
+  },
+}
+```
+
+- `VITE_ADAPTER=node`（默认）→ adapter-node（SSR）
+- `VITE_ADAPTER=static` → adapter-static（SPA / 原生 App）
+
+### 目录结构
+
+```
+项目根/
+  config/                         # 模块配置（YAML）
+    _core.yml                     # Core 配置（必须）
+    _db.yml                       # DB 配置（按需）
+    _cache.yml                    # Cache 配置（按需）
+    _iam.yml                      # IAM 配置（按需）
+    _storage.yml                  # Storage 配置（按需）
+    _ai.yml                       # AI 配置（按需）
+  src/
+    app.html                      # HTML 入口
+    app.d.ts                      # 全局类型声明
+    hooks.server.ts               # 服务端 Hook（模块初始化 + 请求管道）
+    lib/
+      api.ts                      # API Client 初始化（SPA / 原生 App 使用）
+      capacitor.ts                # Capacitor 初始化（原生 App）
+      server/
+        init.ts                   # 模块初始化入口（单例，SSR）
+      paraglide/                  # i18n 生成文件（禁止手动修改）
+      components/                 # 应用组件
+    routes/
+      +layout.svelte              # 根布局
+      +page.svelte                # 首页
+      (auth)/                     # 认证相关页面组
+      api/                        # API 端点
+        v1/                       # API v1 版本
+          payment/                # 支付端点（按需）
+  static/                         # 静态资源
+  messages/                       # i18n 翻译文件
+  capacitor.config.ts             # Capacitor 配置（原生 App）
+```
+
+### 模块依赖图
+
+```
+core（基础能力：配置、日志、i18n、HaiResult）
+  ├── crypto（加密：SM2/SM3/SM4）
+  ├── db（数据库：SQLite/PostgreSQL/MySQL）
+  ├── cache（缓存：内存/Redis）
+  ├── storage（存储：本地/S3）
+  ├── ai（AI：LLM/MCP/Agent）
+  ├── iam（身份管理）← 依赖 crypto + db + cache
+  ├── payment（支付）← 依赖 db + crypto
+  ├── kit（SvelteKit 集成）← 依赖 iam + cache + storage + crypto
+  ├── api-client（HTTP 客户端）← 纯浏览器端，依赖 iam/api（类型）
+  ├── capacitor（原生能力）← 纯浏览器端
+  └── ui（UI 组件库）← 依赖 core
+```
+
+### 模块初始化顺序
+
+#### SSR 模式（hooks.server.ts）
+
+在 `src/lib/server/init.ts` 中按依赖顺序初始化：
+
+```typescript
+import { cache } from '@h-ai/cache'
+import { core } from '@h-ai/core'
+import { reldb } from '@h-ai/reldb'
+import { iam } from '@h-ai/iam'
+import { payment } from '@h-ai/payment' // 按需
+
+let initialized = false
+
+export async function initModules() {
+  if (initialized)
+    return
+
+  // 1. Core 必须最先初始化（加载配置、日志、i18n）
+  await core.init()
+
+  // 2. 基础设施层（无相互依赖，可任意顺序）
+  await reldb.init(core.config.get('db'))
+  await cache.init(core.config.get('cache'))
+
+  // 3. 业务层（依赖基础设施）
+  await iam.init({ ...core.config.get('iam'), reldb, cache })
+  // 支付模块（按需）
+  await payment.init({ ...core.config.get('payment'), reldb })
+
+  // 4. 集成层
+  // kit 无需 init，通过 createHandle 配置
+
+  initialized = true
+}
+```
+
+#### SPA / 原生 App 模式（src/lib/api.ts）
+
+```typescript
+import { api } from '@h-ai/api-client'
+
+export async function initApi() {
+  return api.init({
+    baseUrl: import.meta.env.VITE_API_BASE_URL,
+    timeout: 15_000,
+  })
+}
+
+export { api }
+```
+
+#### 原生 App 追加初始化（src/lib/capacitor.ts）
+
+```typescript
+import { capacitor } from '@h-ai/capacitor'
+
+export async function initCapacitor() {
+  await capacitor.init({ statusBar: { style: 'dark' } })
+}
+```
+
+### 配置文件格式
+
+所有模块配置使用 YAML，支持 `${ENV_VAR:default}` 环境变量语法：
+
+```yaml
+# config/_core.yml
+app:
+  name: ${HAI_APP_NAME:my-app}
+  env: ${HAI_ENV:development}
+log:
+  level: ${HAI_LOG_LEVEL:info}
+```
+
+---
+
+## 技能导航
+
+根据任务类型选择正确的技能：
+
+### 模块使用（API 与集成）
+
+| 任务                  | 技能             | 触发关键词                                        |
+| --------------------- | ---------------- | ------------------------------------------------- |
+| 配置/日志/i18n/HaiResult | `hai-core`       | core.init, core.logger, core.config, HaiResult       |
+| 数据库操作            | `hai-reldb`      | reldb.init, SQL, CRUD, 事务, 分页, DDL               |
+| 缓存操作              | `hai-cache`      | cache.init, cache.get/set, TTL, Redis             |
+| 文件存储              | `hai-storage`    | storage.init, 上传, 下载, S3, 本地存储            |
+| 加密/签名/哈希        | `hai-crypto`     | crypto.init, SM2, SM3, SM4, 加密, 签名            |
+| 身份认证/授权         | `hai-iam`        | iam.init, 登录, 注册, RBAC, Token, Bearer         |
+| AI/LLM/MCP            | `hai-ai`         | ai.init, LLM, MCP, Agent, 工具调用                |
+| SvelteKit 集成        | `hai-kit`        | kit.createHandle, guard, fromContract, middleware |
+| UI 组件               | `hai-ui`         | 表单, 按钮, 表格, Modal, Toast, 移动端组件        |
+| HTTP 客户端           | `hai-api-client` | api.call, api.get, api.post, Bearer, 拦截器       |
+| 原生 App 能力         | `hai-capacitor`  | capacitor, 相机, 推送, 状态栏, 设备信息           |
+| 支付                  | `hai-payment`    | payment, 微信支付, 支付宝, Stripe, 订单           |
+
+### 开发流程
+
+| 任务                   | 技能             | 触发关键词                             |
+| ---------------------- | ---------------- | -------------------------------------- |
+| 创建页面/组件/API/模型 | `hai-app-create` | 新建页面, 添加组件, API 端点, 数据模型 |
+| 代码审查与规范化       | `hai-app-review` | 审查, review, 规范, 优化               |
+| 编写/补充测试          | `hai-app-tests`  | 测试, test, 单测, 覆盖率, TDD, E2E     |
+
+---
+
+## TDD 开发工作流（强制）
+
+> 所有新功能开发必须遵循 TDD：**先写测试 → 确认失败 → 再实现 → 确认通过 → 重构**。
+
+### 完整流程
+
+```
+需求分析 → 设计测试用例 → 编写测试（Red）→ 运行测试确认失败
+    → 编写实现（Green）→ 运行测试确认通过
+    → 重构优化（Refactor）→ 运行质量门禁
+```
+
+### 按阶段使用的技能
+
+| 阶段                | 主要技能         | 说明                                       |
+| ------------------- | ---------------- | ------------------------------------------ |
+| 需求分析 + 测试设计 | `hai-app-tests`  | 拆分测试点，确定单元测试与 E2E 测试        |
+| Red：编写测试       | `hai-app-tests`  | 编写 Vitest 单元测试 + Playwright E2E 测试 |
+| Green：编写实现     | `hai-app-create` | 按照创建规范编写服务/路由/组件             |
+| Refactor：重构审查  | `hai-app-review` | 代码规范审查、分层检查、日志/i18n 合规     |
+
+### 快速指令
+
+```bash
+# Red：运行测试确认全部失败
+pnpm --filter <app-name> test
+pnpm --filter <app-name> test:e2e
+
+# Green：运行测试确认全部通过
+pnpm --filter <app-name> test
+pnpm --filter <app-name> test:e2e
+
+# Refactor：质量门禁
+pnpm typecheck && pnpm lint && pnpm test
+```
+
+---
+
+## 统一编码规范
+
+### 强制规则
+
+- **禁止 `any`**：不确定类型用 `unknown`，在边界处做类型缩窄
+- **禁止 `console.log`**：使用 `core.logger`（trace/debug/info/warn/error/fatal）
+- **禁止硬编码密钥**：使用环境变量，新增变量需在 `.env` 中写入占位符
+- **禁止硬编码用户文案**：所有用户可见文本必须使用 i18n key
+- **禁止修改 `src/lib/paraglide`** 生成文件
+
+### HaiResult 模式
+
+所有 hai 模块操作均返回 `HaiResult<T>` 类型：
+
+```typescript
+const result = await reldb.sql.query('SELECT * FROM users')
+if (!result.success) {
+  // result.error: { code, message, details? }
+  core.logger.error('Query failed', { error: result.error })
+  return kit.response.internalError()
+}
+// result.data 可安全使用
+return kit.response.ok(result.data)
+```
+
+### 质量门禁
+
+每次变更后按顺序执行：
+
+```bash
+pnpm typecheck    # TypeScript 类型检查
+pnpm lint         # ESLint 检查
+pnpm test         # Vitest 单元测试
+```
+
+---
+
+## 标准工作流
+
+### 变更前：需求分析 + 测试设计
+
+1. 列出将修改的文件路径
+2. 确认哪些类型/接口会变
+3. 搜索确认引用关系（避免遗漏）
+4. **设计测试用例清单**（单元测试 + E2E 测试）
+
+### 变更中：TDD 三步走
+
+1. **Red**：编写单元测试（Vitest）+ E2E 测试（Playwright），运行确认全部失败
+2. **Green**：按技能指引完成功能实现，逐步让测试通过
+3. **Refactor**：审查代码规范、重构优化
+
+### 变更后：验证
+
+1. `pnpm typecheck` 通过
+2. `pnpm lint` 通过
+3. `pnpm test` 通过（单元测试）
+4. `pnpm --filter <app-name> test:e2e` 通过（E2E 测试）
+5. 搜索确认所有引用点已更新

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

@@ -0,0 +1,184 @@
+---
+name: hai-cache
+description: 使用 @h-ai/cache 进行内存或 Redis 缓存操作（kv/hash/list/set/zset/分布式锁）；当需求涉及缓存读写、TTL 管理、集合运算、排行榜、缓存一致性策略或分布式互斥锁时使用。
+---
+
+# hai-cache
+
+> `@h-ai/cache` 提供统一缓存接口，支持 Memory 与 Redis 后端，包含 KV / Hash / List / Set / ZSet / 分布式锁 六类操作。
+
+---
+
+## 适用场景
+
+- 缓存热点数据减少数据库查询
+- 会话存储（配合 IAM）
+- 分布式缓存（Redis）与本地测试缓存（Memory）
+- 集合操作（权限缓存、标签集合）
+- 排行榜（ZSet）与队列（List）
+- 分布式锁（多节点部署互斥控制）
+
+---
+
+## 使用步骤
+
+### 1. 配置
+
+```yaml
+# config/_cache.yml
+type: ${HAI_CACHE_TYPE:memory} # memory | redis
+# Redis 配置（type=redis 时生效）：
+# host: ${HAI_CACHE_REDIS_HOST:localhost}
+# port: ${HAI_CACHE_REDIS_PORT:6379}
+# password: ${HAI_CACHE_REDIS_PASSWORD:}
+# db: ${HAI_CACHE_REDIS_DB:0}
+# keyPrefix: ${HAI_CACHE_KEY_PREFIX:hai:}
+```
+
+### 2. 初始化与关闭
+
+```typescript
+import { cache } from '@h-ai/cache'
+
+await cache.init(core.config.get('cache'))
+// 使用后关闭
+await cache.close()
+```
+
+---
+
+## 核心 API
+
+### KV 操作（`cache.kv`）
+
+| 方法                                | 说明                 |
+| ----------------------------------- | -------------------- |
+| `get / set / del / exists`          | 基础读写与存在性判断 |
+| `expire / expireAt / ttl / persist` | TTL 管理             |
+| `incr / incrBy / decr / decrBy`     | 计数器操作           |
+| `mget / mset`                       | 批量读写             |
+| `scan / keys / type`                | Key 检索与类型判断   |
+
+```typescript
+await cache.kv.set('user:123', { name: '张三' }, { ex: 3600 })
+const result = await cache.kv.get<{ name: string }>('user:123')
+if (result.success && result.data) {
+  // result.data.name === '张三'
+}
+
+await cache.kv.del('user:123')
+```
+
+### Hash/List/Set/ZSet（`cache.hash/list/set_/zset`）
+
+- `cache.hash`：对象字段读写（如用户 profile 局部更新）
+- `cache.list`：队列/消息顺序处理
+- `cache.set_`：去重集合（成员关系、权限集合）
+- `cache.zset`：分数排序（排行榜、权重调度）
+
+```typescript
+await cache.hash.hset('profile:1', { nickname: 'alice' })
+await cache.list.lpush('queue:jobs', 'job-1', 'job-2')
+await cache.set_.sadd('role:admin:perms', 'user.read', 'user.write')
+await cache.zset.zadd('rank:daily', { member: 'u1', score: 100 })
+```
+
+### 分布式锁（`cache.lock`）
+
+| 方法       | 说明                                       |
+| ---------- | ------------------------------------------ |
+| `acquire`  | 尝试获锁（SET NX EX），返回 true/false     |
+| `release`  | 释放锁（支持 owner 验证，防止误释放）      |
+| `isLocked` | 检查锁是否被持有                           |
+| `extend`   | 续期锁 TTL（支持 owner 验证）              |
+
+```typescript
+// 获锁（TTL 30 秒，owner 用于标识持有者）
+const acquired = await cache.lock.acquire('my-lock', { ttl: 30, owner: 'node-1' })
+if (acquired.success && acquired.data) {
+  try {
+    // 受保护的操作
+  }
+  finally {
+    await cache.lock.release('my-lock', 'node-1')
+  }
+}
+
+// 续期
+await cache.lock.extend('my-lock', 60, 'node-1')
+
+// 检查
+const locked = await cache.lock.isLocked('my-lock')
+```
+
+**最佳实践：**
+
+- `owner` 使用稳定的节点标识（如 `nodeId`），不要每次随机生成
+- 释放锁时传入 `owner` 防止误释放他人锁
+- Memory 后端适合开发/测试；Redis 后端用 Lua 脚本保证 release/extend 原子性
+
+---
+
+## 错误码 — `HaiCacheError`
+
+| 错误码 | code | 说明 |
+|--------|------|------|
+| `HaiCacheError.CONNECTION_FAILED` | `hai:cache:001` | 连接失败 |
+| `HaiCacheError.OPERATION_FAILED` | `hai:cache:002` | 操作失败 |
+| `HaiCacheError.SERIALIZATION_FAILED` | `hai:cache:003` | 序列化失败 |
+| `HaiCacheError.DESERIALIZATION_FAILED` | `hai:cache:004` | 反序列化失败 |
+| `HaiCacheError.KEY_NOT_FOUND` | `hai:cache:005` | 键不存在 |
+| `HaiCacheError.TIMEOUT` | `hai:cache:006` | 超时 |
+| `HaiCacheError.NOT_INITIALIZED` | `hai:cache:010` | 未初始化 |
+| `HaiCacheError.UNSUPPORTED_TYPE` | `hai:cache:011` | 不支持的缓存类型 |
+| `HaiCacheError.CONFIG_ERROR` | `hai:cache:012` | 配置错误 |
+
+---
+
+## 常见模式
+
+### 缓存穿透保护
+
+```typescript
+async function getUserCached(userId: string) {
+  const cached = await cache.kv.get<User>(`user:${userId}`)
+  if (cached.success && cached.data)
+    return cached.data
+
+  const user = await userRepo.findById(userId)
+  if (user.success && user.data) {
+    await cache.kv.set(`user:${userId}`, user.data, { ex: 3600 })
+    return user.data
+  }
+  return null
+}
+```
+
+### 分布式锁保护共享资源
+
+```typescript
+const lockKey = 'batch:import'
+const acquired = await cache.lock.acquire(lockKey, { ttl: 60, owner: nodeId })
+if (acquired.success && acquired.data) {
+  try {
+    await runBatchImport()
+  }
+  finally {
+    await cache.lock.release(lockKey, nodeId)
+  }
+}
+else {
+  logger.info('Another node is running the import')
+}
+```
+
+---
+
+## 相关 Skills
+
+- `hai-build`：模块初始化顺序（cache 在 db 之后、iam 之前）
+- `hai-core`：配置与 HaiResult 模型
+- `hai-iam`：会话存储与权限缓存（底层使用 cache）
+- `hai-scheduler`：定时任务分布式锁（底层使用 cache.lock）
+- `hai-reach`：消息发送互斥锁（底层使用 cache.lock）
+- `hai-kit`：SvelteKit 集成层