@h-ai/cli 0.1.0-alpha.13 → 0.1.0-alpha.16

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

@@ -1,484 +1,157 @@
 ---
 name: hai-kit
-description: 使用 @h-ai/kit 构建 SvelteKit 请求管道与 API 安全边界（handle/guard/middleware/handler/validate/response/fromContract）。当需求涉及 hooks.server.ts、hooks.client.ts、权限守卫、限流、统一响应、Bearer Token 认证、契约处理、CORS 配置、svelte.config.js 或 playwright.config.ts 时使用。
+description: 使用 @h-ai/kit 构建 SvelteKit 请求管道、认证守卫、统一响应、Zod 校验、浏览器端 apiFetch、A2A 与双构建适配；当需求涉及 hooks.server.ts、权限守卫、CORS、限流、同源 transport 或 SvelteKit API endpoint 时使用。
 ---
 
 # hai-kit
 
-`@h-ai/kit` 是 hai-framework 的 SvelteKit 集成层。它把请求处理中的"通用横切能力"收敛到统一命名空间 `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。
 
-- 请求入口：`createHandle` / `sequence`
-- 安全边界：`guard` / `middleware`
-- API 工具：`handler` / `response` / `validate`
-- Bearer Token 认证：从 `Authorization` header 解析，SSR 端通过 `hai_token` Cookie 透传
-- 契约处理：`fromContract(endpoint, fn)` — 基于 EndpointDef 的类型安全 handler
-- 双构建模式：`createAdapter()` 根据环境变量选择 adapter-node 或 adapter-static
-
-## 模块概述
-
-当任务涉及以下关键词时，优先使用本 Skill：
-
-- `hooks.server.ts` / `hooks.client.ts`
-- `svelte.config.js` / `vite.config.ts` / `playwright.config.ts`
-- `kit.createHandle` / `kit.sequence`
-- `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`）
-
-> **重要变更**：Cookie Session 和 CSRF 中间件已移除。统一使用 Bearer Token 认证。
-
-## 依赖
-
-| 模块 | 用途 | 是否必需 | 初始化要求 |
-| --- | --- | --- | --- |
-| `@h-ai/iam` | 身份认证与授权（A2A 认证） | 可选 | 使用 A2A 功能时需在 kit 使用前初始化 |
-| `@h-ai/crypto` | 加密（传输加密 / Cookie 加密） | 可选 | 启用加密时需在 kit 使用前初始化 |
-
----
-
-## 项目配置（从 npm 安装）
-
-> 以下示例面向通过 `npm install @h-ai/kit` 引用发布包的项目。monorepo 内部使用 `workspace:*` 时路径略有不同。
-
-### 1. 安装依赖
-
-```bash
-# 核心包
-npm install @h-ai/kit
-
-# 必须的对等依赖
-npm install svelte @sveltejs/kit
-npm install -D @sveltejs/vite-plugin-svelte vite
-
-# 可选：双构建 adapter
-npm install -D @sveltejs/adapter-node @sveltejs/adapter-static
-
-# API 校验
-npm install zod
-```
-
-### 2. svelte.config.js
-
-```js
-import adapter from '@sveltejs/adapter-auto'
-import { vitePreprocess } from '@sveltejs/vite-plugin-svelte'
-
-/** @type {import('@sveltejs/kit').Config} */
-const config = {
-  preprocess: [vitePreprocess()],
-  compilerOptions: {
-    runes: true,
-  },
-  kit: {
-    adapter: adapter(),
-    // 如需双构建模式（SSR/SSG 按环境切换）：
-    // import { createAdapter } from '@h-ai/kit/adapter'
-    // adapter: createAdapter(),
-    csrf: {
-      // E2E 测试时信任本地域名
-      trustedOrigins: process.env.HAI_E2E === '1'
-        ? ['http://localhost:4173', 'http://127.0.0.1:4173']
-        : [],
-    },
-    alias: {
-      $components: './src/lib/components',
-      $stores: './src/lib/stores',
-    },
-  },
-}
-
-export default config
-```
-
-> 若同时使用 `@h-ai/ui`，在 `preprocess` 数组前方加 `autoImportHaiUi()`（详见 hai-ui Skill）。
-
-### 3. vite.config.ts
-
-```ts
-import process from 'node:process'
-import { sveltekit } from '@sveltejs/kit/vite'
-import tailwindcss from '@tailwindcss/vite'
-import { defineConfig, loadEnv } from 'vite'
-
-export default defineConfig(({ mode }) => {
-  const env = loadEnv(mode, process.cwd(), '')
-  Object.assign(process.env, env)
-
-  return {
-    plugins: [
-      sveltekit(),
-      tailwindcss(),
-      // 如使用 Paraglide i18n：
-      // paraglideVitePlugin({ project: './project.inlang', outdir: './src/lib/paraglide', strategy: ['cookie', 'baseLocale'] }),
-    ],
-    optimizeDeps: {
-      exclude: ['bits-ui'], // bits-ui 使用 Svelte 虚拟模块
-    },
-    ssr: {
-      // @h-ai 包为 ESM，需 Vite 在 SSR 时处理
-      noExternal: [/@h-ai\//],
-    },
-    server: {
-      port: 5173,
-    },
-  }
-})
-```
+## 使用步骤
 
-### 4. src/hooks.server.ts — 请求管道
+### 1. 请求管道
 
 ```ts
 import type { Handle } from '@sveltejs/kit'
 import { kit } from '@h-ai/kit'
 
-// ─── 模块初始化（延迟 + 并发安全） ─── //
-let initPromise: Promise<void> | null = null
-
-async function ensureInit() {
-  if (!initPromise) {
-    initPromise = initModules().catch((err) => {
-      initPromise = null // 失败清除，允许重试
-      throw err
-    })
-  }
-  await initPromise
-}
-
-async function initModules() {
-  // 按需初始化 reldb、iam、cache 等模块
-}
-
-// ─── 初始化 Handle ─── //
-const initHandle: Handle = async ({ event, resolve }) => {
-  await ensureInit()
-  return resolve(event)
-}
-
-// ─── 认证 Handle ─── //
 const haiHandle = kit.createHandle({
   auth: {
-    verifyToken: async (token) => {
-      // 验证 Bearer Token，返回 SessionData 或 null
-      return token ? { userId: 'u_1', roles: ['admin'], permissions: ['user:read'] } : null
-    },
+    verifyToken: async token => token ? { userId: 'u_1', roles: ['admin'], permissions: ['user:read'] } : null,
     loginUrl: '/auth/login',
-    protectedPaths: ['/admin/*', '/api/*'],
-    publicPaths: ['/api/auth/*', '/api/public/*'],
+    protectedPaths: ['/admin/*'],
   },
   rateLimit: { windowMs: 60_000, maxRequests: 100 },
   logging: true,
-  cors: {
-    origins: ['https://example.com'],
-    capacitor: true,          // 自动允许 Capacitor 原生 App WebView Origin
-    credentials: true,
-  },
 })
 
-export const handle: Handle = kit.sequence(initHandle, haiHandle)
+export const handle: Handle = haiHandle
 ```
 
-### 5. src/hooks.client.ts — 客户端 Token 注入
+### 2. SvelteKit API endpoint
 
 ```ts
 import { kit } from '@h-ai/kit'
-
-// 自动将 localStorage 中的 Bearer Token 附加到 SSR fetch 请求
-export const handleFetch = kit.auth.createHandleFetch()
-```
-
-### 6. playwright.config.ts — E2E 测试
-
-```ts
-import process from 'node:process'
-import { defineConfig } from '@playwright/test'
-
-const baseURL = process.env.BASE_URL || 'http://localhost:4173'
-
-export default defineConfig({
-  testDir: './e2e',
-  fullyParallel: false,
-  forbidOnly: !!process.env.CI,
-  retries: process.env.CI ? 2 : 0,
-  workers: 2,
-  reporter: 'list',
-  timeout: 30_000,
-
-  use: {
-    baseURL,
-    channel: 'chrome',
-    extraHTTPHeaders: { Origin: baseURL },
-    trace: 'on-first-retry',
-    screenshot: 'only-on-failure',
-  },
-
-  webServer: {
-    command: 'pnpm build && pnpm exec vite preview --port 4173 --strictPort',
-    env: { HAI_E2E: '1', NODE_ENV: 'test' },
-    url: baseURL,
-    reuseExistingServer: false,
-    timeout: 180_000,
-  },
-})
-```
-
-> `HAI_E2E=1` 与 `NODE_ENV=test` 搭配使用：提高 rateLimit 上限、信任本地 Origin。
-
----
-
-## 使用步骤
-
-### 1) API 端点使用 `kit.handler`
-
-```typescript
-import { kit } from '@h-ai/kit'
 import { z } from 'zod'
 
-const CreateSchema = z.object({ name: z.string().min(1) })
+const CreateUserSchema = z.object({ name: z.string().min(1) })
 
 export const POST = kit.handler(async ({ request, locals }) => {
   kit.guard.require(locals.session, 'user:create')
-  const data = await kit.validate.body(request, CreateSchema)
-  return kit.response.created(data)
+  const payload = await kit.validate.body(request, CreateUserSchema)
+  return kit.response.created(payload)
 })
 ```
 
-### 2) 基于契约的类型安全 handler（推荐）
+### 3. 浏览器同源请求
 
-```typescript
-import { iam } from '@h-ai/iam'
-import { iamEndpoints } from '@h-ai/iam/api'
+```ts
 import { kit } from '@h-ai/kit'
 
-export const POST = kit.fromContract(iamEndpoints.login, async (input, event) => {
-  const result = await iam.auth.login(input)
-  if (!result.success) {
-    return kit.response.unauthorized(result.error.message)
-  }
-  return kit.response.ok(result.data)
-})
+const client = kit.client.create({ auth: true })
+export const { apiFetch } = client
 ```
 
-### 3) CORS + Capacitor 配置
-
-```typescript
-export const handle = kit.createHandle({
-  cors: {
-    origins: ['https://example.com', 'https://*.example.com'],
-    capacitor: true,          // Capacitor 原生 App WebView Origin
-    methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
-    credentials: true,
-  },
-})
-```
+### 4. 同源传输加密
 
-### 4) 需要传输加密时启用 `crypto` 配置
+kit 不再维护本地传输加密实现；服务端和客户端都统一委托 `@h-ai/crypto` 的 `crypto.transport`。
 
-```typescript
+```ts
+// hooks.server.ts
 import { crypto } from '@h-ai/crypto'
 import { kit } from '@h-ai/kit'
 
-crypto.init()
+await crypto.init()
 
 export const handle = kit.createHandle({
+  auth: {
+    verifyToken,
+    protectedPaths: ['/api/*'],
+    publicPaths: ['/api/_hai/*'],
+  },
   crypto: {
     crypto,
-    transport: { requireEncryption: false },
-    cookieEncryptionKey: process.env.HAI_KIT_COOKIE_KEY,
+    transport: { requireEncryption: true },
   },
 })
 ```
 
-## 核心 API
-
-| API                         | 用途                   | 关键点                                        |
-| --------------------------- | ---------------------- | --------------------------------------------- |
-| `kit.createHandle(config?)` | 创建 SvelteKit Handle  | Bearer Token 解析、守卫、中间件、CORS         |
-| `kit.sequence(...handles)`  | 组合多个 Handle        | 洋葱模型顺序执行                              |
-| `kit.handler(fn)`           | 包装 API 处理函数      | 非控制流异常统一转 500                        |
-| `kit.fromContract(ep, fn)`  | 契约到 handler         | 自动 Zod 入参校验，类型安全                   |
-| `kit.guard.*`               | 权限守卫               | `require`（throw 式） / `check`（布尔）       |
-| `kit.response.*`            | 标准化响应             | 统一 `{ success, data?, error?, requestId? }` |
-| `kit.validate.*`            | 请求体/查询/参数校验   | 失败 throw Response（SvelteKit 控制流）       |
-| `kit.i18n.setLocale(locale)` | 设置请求级 locale     | 在 handle 中调用，供服务端模块使用             |
-| `defineEndpoint(def)`       | 定义 EndpointDef 契约  | 与 api-client 配合使用                        |
-
-### EndpointDef 契约
-
-```typescript
-import { defineEndpoint } from '@h-ai/kit'
-import { z } from 'zod'
-
-const myEndpoint = defineEndpoint({
-  method: 'POST',
-  path: '/api/v1/items',
-  input: z.object({ name: z.string() }),
-  output: z.object({ id: z.string(), name: z.string() }),
-  requireAuth: true,
-})
-```
-
-## 错误码（常见）
-
-### API 响应错误码（`kit.response`）
-
-| code               | status | 场景               |
-| ------------------ | ------ | ------------------ |
-| `BAD_REQUEST`      | 400    | 参数或请求格式错误 |
-| `UNAUTHORIZED`     | 401    | 未认证             |
-| `FORBIDDEN`        | 403    | 无权限             |
-| `NOT_FOUND`        | 404    | 资源不存在         |
-| `CONFLICT`         | 409    | 资源冲突           |
-| `VALIDATION_ERROR` | 422    | 数据校验失败       |
-| `INTERNAL_ERROR`   | 500    | 未处理异常         |
-
-## API 契约范式（端到端类型安全）
-
-> `kit.fromContract` 和 `api.call` 共同消费模块 `api/` 下的 `EndpointDef`，实现服务端↔客户端的全链路类型安全 + 运行时 Zod 校验。
-
-### 服务端流程（本模块责任）
-
-1. 从 `@h-ai/xx/api` 导入 `xxEndpoints`
-2. `kit.fromContract(xxEndpoints.xxx, handler)` → 自动 Zod 校验入参 → handler 获得类型安全的 `input`
-3. 需权限时在 handler 内调用 `kit.guard.require`
-
-### 多模块契约示例
-
-```typescript
-// ─── 存储：预签名上传 ───
-import { storageEndpoints } from '@h-ai/storage/api'
-import { storage } from '$lib/server/init'
-
-export const POST = kit.fromContract(storageEndpoints.presignUpload, async (input, event) => {
-  kit.guard.require(event.locals.session, 'storage:write')
-  const result = await storage.presign.putUrl(input.key, input)
-  if (!result.success) {
-    return kit.response.internalError(result.error.message)
-  }
-  return kit.response.ok({ url: result.data, key: input.key })
-})
-
-// ─── IAM：登录 ───
-import { iamEndpoints } from '@h-ai/iam/api'
-import { iam } from '$lib/server/init'
-
-export const POST = kit.fromContract(iamEndpoints.login, async (input) => {
-  const result = await iam.auth.login(input)
-  if (!result.success) {
-    return kit.response.unauthorized(result.error.message)
+```ts
+// routes/+layout.svelte
+<script lang='ts'>
+  import { browser } from '$app/environment'
+  import { crypto } from '@h-ai/crypto'
+  import { kit } from '@h-ai/kit'
+  import { appKitConfig } from '$lib/config/kit-config'
+
+  // 一次性安装：内部按 appKitConfig.transport 是否启用决定行为，并预热 crypto
+  if (browser) {
+    kit.client.installBrowserTransport(appKitConfig, { crypto })
   }
-  return kit.response.ok(result.data)
-})
-```
-
-## 常见模式
-
-### 契约模式（推荐新项目使用）
-
-1. 在模块的 `api/` 目录定义 `EndpointDef`（Zod schema）
-2. 服务端用 `kit.fromContract(endpoint, handler)` 处理
-3. 客户端用 `api.call(endpoint, input)` 调用
-4. 入参/出参全链路类型安全 + 运行时校验
-
-### 双构建模式
-
-```typescript
-// svelte.config.js
-import { createAdapter } from '@h-ai/kit/adapter'
-
-const config = {
-  kit: {
-    adapter: createAdapter(), // 自动选择 adapter-node 或 adapter-static
-  },
-}
+</script>
 ```
 
----
-
-## 浏览器侧使用
-
-### 创建统一 API 客户端 — `kit.client`
-
-> **所有浏览器端 API 请求必须通过 `apiFetch`，禁止直接 `fetch()`。**
-
-在 `src/lib/utils/api.ts` 中一次性创建，全应用共享：
-
-```typescript
-// src/lib/utils/api.ts
+```ts
+// lib/utils/api.ts —— 业务层只看到 apiFetch
 import { kit } from '@h-ai/kit'
 
-const client = kit.client.create({ auth: true })
-export const { apiFetch } = client
+export const { apiFetch } = kit.client.create({ auth: true })
 ```
 
-如需传输加密：
+默认协商端点：`/api/_hai/key-exchange`。如 `keyExchangePath` 自定义，浏览器端同步设置 `keyExchangeUrl`。
 
-```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,
-})
+transport 默认保护同源 `/api/*` endpoint 与 SvelteKit `__data.json` 页面数据请求；页面文档、静态资源与 `multipart/form-data` 上传请求保持明文透传。
 
-export const { apiFetch } = client
-```
+安全策略默认 fail-closed：`requireEncryption: true` 时，受保护路径缺少 `X-Client-Id` 必须返回 400；服务端 transport 管理器不可用、响应体无法加密或超过单次加密上限时返回错误，禁止明文业务响应回退。`requireEncryption: false` 只适合迁移期灰度。
 
-`apiFetch` 自动处理：
-- **CSRF**：写方法自动读取 `hai_csrf` Cookie 并设置 `X-CSRF-Token`
-- **Bearer Token**：自动从 localStorage 读取并注入 `Authorization` header
-- **传输加密**：可选，首次写请求时自动密钥交换
+### 5. 使用 `_kit.yml` 统一 transport 配置
 
-### Token 存储 — `kit.auth.createTokenStore`
-
-```typescript
-import { kit } from '@h-ai/kit'
+`@h-ai/kit` 现在提供 `KitConfigSchema` / `resolveKitConfig()`，适合同一份 `_kit.yml`
+同时驱动 `hooks.server.ts` 与浏览器端 `kit.client.installBrowserTransport()`：
 
-const tokenStore = kit.auth.createTokenStore('hai_access_token')
-tokenStore.set(tokens.accessToken)
-tokenStore.get()
-tokenStore.clear()
+```yml
+transport:
+  keyExchangePath: /api/_hai/key-exchange
+  requireEncryption: true
+  encryptResponse: true
+  excludePaths:
+    - /api/storage
+    - /api/public
+    - /api/auth/profile/avatar
+  maxClients: 10000
 ```
 
-### 选择指南：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 校验 |
+```ts
+import { resolveKitConfig } from '@h-ai/kit'
+import { parse } from 'yaml'
+import rawKitConfig from '../config/_kit.yml?raw'
 
----
+export const appKitConfig = resolveKitConfig(parse(rawKitConfig) ?? {})
+```
 
-## 导出路径
+`_kit.yml` 只放公开的 transport 路径/开关，不放密钥；如自定义 `keyExchangePath`，浏览器端必须同步映射为 `keyExchangeUrl`。
 
-| 路径                | 用途                                             |
-| ------------------- | ------------------------------------------------ |
-| `@h-ai/kit`        | 主入口：`kit` 命名空间、类型、`defineEndpoint`   |
-| `@h-ai/kit/client`  | 浏览器端客户端（单独引用时）                     |
-| `@h-ai/kit/adapter` | 双构建 adapter（`createAdapter()`）              |
-| `@h-ai/kit/vite`    | Vite 插件                                        |
-| `@h-ai/kit/a2a`     | A2A 协议集成                                     |
-| `@h-ai/kit/crypto`  | 加密模块集成                                     |
+## 核心 API
 
----
+| API | 用途 |
+| --- | --- |
+| `kit.createHandle()` | 创建 SvelteKit Handle |
+| `kit.sequence()` | 组合多个 Handle |
+| `kit.handler()` | API endpoint 错误边界 |
+| `kit.guard.require()` | 权限守卫 |
+| `kit.response.*` | 统一响应工厂 |
+| `kit.validate.*` | Zod 请求校验 |
+| `kit.auth.*` | Cookie / Token 辅助 |
+| `kit.client.create()` | 浏览器端同源 apiFetch |
+| `kit.client.installBrowserTransport(config, { crypto })` | 推荐入口：按解析后的 `_kit.yml` 一键安装浏览器端传输加密 |
+| `kit.client.installBrowserTransportFetch()` | 底层入口：直接传 transport 配置安装浏览器全局 fetch 包装 |
+| `kit.crud.define()` | 声明式 CRUD 资源 |
 
-## 相关 Skills
+## 常见模式
 
-- `hai-ui`：UI 组件库（svelte.config.js / app.css 配置）
-- `hai-core`：全局配置、日志、HaiResult 基础能力
-- `hai-iam`：Token 认证、角色权限模型
-- `hai-api-client`：客户端契约调用（SPA / 原生 App 场景）
-- `hai-crypto`：传输加密与密钥管理能力
-- `hai-capacitor`：原生 App CORS 场景
+- SvelteKit 应用内同源请求用 `kit.client.create().apiFetch`。
+- SvelteKit 应用启用 transport 时，在 `+layout.svelte` 的 `if (browser)` 分支调用一次 `kit.client.installBrowserTransport(appKitConfig, { crypto })`，无需重复连线 `keyExchangeUrl` / `excludePaths`。
+- Web/App/小程序跨域访问公共 API 用 `@h-ai/api-client` typed client。
+- 传输加密只通过 `crypto.transport` 间接装配，不在 kit 中新增本地加密工厂或鸭子类型。
+- 服务端业务模块直接调用模块 API，不通过 HTTP 自环。
+- API endpoint 必须用 Zod 校验用户输入，并设置认证/权限边界。

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

@@ -203,17 +203,15 @@ const payResult = await invokePayment(orderResult.data)
 
 自定义 Provider 通过 `payment.registerProvider(provider)` 注册。
 
-### API 契约
+### HTTP API 契约
 
 ```typescript
-import { paymentEndpoints } from '@h-ai/payment/api'
-
-// paymentEndpoints.createOrder    — POST /payment/create
-// paymentEndpoints.queryOrder     — GET  /payment/query
-// paymentEndpoints.notifyWechat   — POST /payment/notify/wechat
-// paymentEndpoints.notifyAlipay   — POST /payment/notify/alipay
-// paymentEndpoints.notifyStripe   — POST /payment/notify/stripe
-// paymentEndpoints.refund         — POST /payment/refund
+import { apiContract } from '@h-ai/api-contract'
+
+// apiContract.payment.orders.create        — POST /payment/orders
+// apiContract.payment.orders.get           — GET  /payment/orders/{orderNo}
+// apiContract.payment.orders.refund        — POST /payment/orders/{orderNo}/refunds
+// apiContract.payment.notifications.wechat — POST /payment/notifications/wechat
 ```
 
 ---
@@ -249,7 +247,7 @@ export const POST = kit.handler(async ({ request, locals }) => {
 ### 完整支付流程
 
 ```
-1. 客户端 → 服务端：创建订单（api.call(paymentEndpoints.createOrder, {...})）
+1. 客户端 → 服务端：创建订单（api.payment.orders.create({...})）
 2. 服务端 → 支付平台：调用 Provider 创建预支付
 3. 服务端 → 客户端：返回 providerData（含调起参数）
 4. 客户端：invokePayment(providerData) 调起支付