@h-ai/cli 0.1.0-alpha.65 → 0.1.0-alpha.67

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

@@ -0,0 +1,172 @@
+# 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。
+
+## 使用步骤
+
+### 1. 请求管道
+
+```ts
+import type { Handle } from '@sveltejs/kit'
+import { kit } from '@h-ai/kit'
+
+const haiHandle = kit.createHandle({
+  auth: {
+    verifyToken: async token => token ? { userId: 'u_1', roles: ['admin'], permissions: ['user:read'] } : null,
+    loginUrl: '/auth/login',
+    protectedPaths: ['/admin/*'],
+  },
+  rateLimit: { windowMs: 60_000, maxRequests: 100 },
+  logging: true,
+})
+
+export const handle: Handle = haiHandle
+```
+
+### 2. SvelteKit API endpoint
+
+```ts
+import { kit } from '@h-ai/kit'
+import { z } from 'zod'
+
+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 payload = await kit.validate.body(request, CreateUserSchema)
+  return kit.response.created(payload)
+})
+```
+
+### 3. 浏览器同源请求
+
+```ts
+import { kit } from '@h-ai/kit'
+
+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 { 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: {
+    verifyToken,
+    protectedPaths: ['/api/*'],
+    publicPaths: ['/api/_hai/*'],
+  },
+  crypto: {
+    crypto,
+    transport: {
+      requireEncryption: true,
+      keyStore: createRedisTransportKeyStore({ cache, ttlSeconds: 3600 }),
+    },
+  },
+})
+```
+
+需要保护会话 Cookie 时配置 `crypto.encryptedCookies`，并通过 `crypto.cookieEncryptionKey` 或 `HAI_KIT_COOKIE_KEY` 提供密钥。缺少密钥会在 `createHandle()` 时失败；加解密错误不会回退到明文 Cookie。
+
+```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 })
+  }
+</script>
+```
+
+```ts
+// lib/utils/api.ts —— 业务层只看到 apiFetch
+import { kit } from '@h-ai/kit'
+
+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` 只适合迁移期灰度。
+
+### 5. 使用 `_kit.yml` 统一 transport 配置
+
+`@h-ai/kit` 现在提供 `KitConfigSchema` / `resolveKitConfig()`，适合同一份 `_kit.yml`
+同时驱动 `hooks.server.ts` 与浏览器端 `kit.client.installBrowserTransport()`：
+
+```yml
+server:
+  host: 127.0.0.1
+  port: 3000
+
+transport:
+  keyExchangePath: /api/_hai/key-exchange
+  requireEncryption: true
+  encryptResponse: true
+  excludePaths:
+    - /api/storage
+    - /api/public
+    - /api/auth/profile/avatar
+  maxClients: 10000
+```
+
+```ts
+import { resolveKitConfig } from '@h-ai/kit'
+import { parse } from 'yaml'
+import rawKitConfig from '../config/_kit.yml?raw'
+
+export const appKitConfig = resolveKitConfig(parse(rawKitConfig) ?? {})
+```
+
+`resolveKitConfig()` 同时解析 `server`（host/port）与 `transport`；host/port 优先级为 `HOST` / `PORT` 环境变量 > `_kit.yml` 的 `server` > 默认 `127.0.0.1:3000`（与 `@h-ai/serv` 同构）。
+`_kit.yml` 只放公开的 server/transport 路径/开关，不放密钥；如自定义 `keyExchangePath`，浏览器端必须同步映射为 `keyExchangeUrl`。
+
+## 核心 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 资源 |
+
+## 常见模式
+
+- 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 校验用户输入，并设置认证/权限边界。
+
+## 声明式 CRUD 表单字段
+
+`kit.crud.define` 的字段支持 `colSpan: 'auto' | 1 | 2`，以及 `validation.message: string | (() => string)`。布局通过 UI 的 `CrudPage.form` 配置；客户端校验用于交互提示，服务端仍使用 Zod 验证和现有权限守卫。UI 公共契约见相邻 [hai-ui skill](../hai-ui/SKILL.md)。

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

@@ -1,6 +1,6 @@
 ---
 name: hai-payment
-description: "使用 @h-ai/payment 创建支付订单、验证回调、查单和退款，客户端调起支付。"
+description: "接入微信、支付宝或 Stripe 的订单、回调验签、查单与退款，并处理客户端调起和幂等履约。"
 ---
 
 # hai-payment
@@ -15,257 +15,25 @@ description: "使用 @h-ai/payment 创建支付订单、验证回调、查单和
 | 输出 | 服务端 HaiResult；客户端 invokePayment 按 client 契约使用 |
 | 限制 | 服务端保存凭据并验签；客户端完成不代表付款成功，以可信回调/查单为准。订单履约与重试需幂等。 |
 
-> `@h-ai/payment` 是 hai-framework 的统一支付模块，通过 Provider 模式支持微信支付、支付宝、Stripe。服务端处理订单和回调，客户端调起支付。
+## 使用路径
 
-## 运行环境
+1. 服务端校验 Provider 配置后 init，真实凭据经私有配置注入；浏览器只导入 `/client`。
+2. 订单号、金额单位、商品与用户由服务端可信数据决定，先保存业务订单再创建支付。
+3. 回调使用原始 body 与 headers 验签；核对订单、金额及状态，幂等更新。客户端调起成功不代表付款完成。
+4. 查单、退款与回调重试覆盖成功、失败和重复路径；真实支付仅在用户授权范围内，最后 close。
 
-> **服务端 + 浏览器分工模块。** `payment.createOrder` / `payment.handleNotify` / `payment.refund` 等操作在 Node.js 端执行。浏览器端使用 `invokePayment()`（从 `@h-ai/payment/client` 导入）调起支付。
+## 按需参考
 
-## 依赖
+按本次操作读取对应小节；以已安装版本的公开类型核验签名，示例中的业务变量由应用提供。
 
-| 模块 | 用途 | 是否必需 | 初始化要求 |
-| --- | --- | --- | --- |
-| `@h-ai/audit` | 审计日志（支付操作自动审计） | 可选 | 已初始化时自动写入审计日志 |
-
-## 适用场景
-
-- 接入微信支付（JSAPI / H5 / Native / App）
-- 接入支付宝（H5 / App / PC）
-- 接入 Stripe（Checkout Session）
-- 支付回调验签与通知处理
-- 订单查询与退款
-- 客户端调起支付（Web / H5 / App）
-
-## 使用步骤
-
-### 1. 配置
-
-```yaml
-# config/_payment.yml（自行创建）
-wechat:
-  appId: ''
-  mchId: ''
-  apiV3Key: ''
-  privateKey: ''
-  serialNo: ''
-  platformCert: ''  # 可选，回调验签需要
-
-alipay:
-  appId: ''
-  privateKey: ''
-  alipayPublicKey: ''
-  signType: RSA2  # 可选，默认 RSA2
-  sandbox: false   # 可选，默认 false
-
-stripe:
-  secretKey: ''
-  webhookSecret: ''
-  webhookToleranceSeconds: 300  # 可选，默认 300 秒
-```
-
-约定环境变量优先于 YAML，例如 `HAI_PAYMENT_WECHAT_APIV3KEY`、
-`HAI_PAYMENT_STRIPE_WEBHOOKSECRET`。生产密钥只放环境或密钥管理器。
-
-### 2. 初始化（服务端）
-
-```typescript
-import { payment } from '@h-ai/payment'
-
-const initResult = await payment.init({
-  wechat: {
-    appId: 'wx1234567890',
-    mchId: '1600000000',
-    apiV3Key: 'your-api-key-v3',
-    privateKey: '-----BEGIN RSA PRIVATE KEY-----...',
-    serialNo: 'CERT_SERIAL_NO',
-  },
-  alipay: {
-    appId: '2021000000000000',
-    privateKey: '-----BEGIN RSA PRIVATE KEY-----...',
-    alipayPublicKey: '-----BEGIN PUBLIC KEY-----...',
-  },
-})
-if (!initResult.success) {
-  // 处理初始化错误
-}
-```
-
-### 3. 创建订单
-
-```typescript
-const result = await payment.createOrder('wechat', {
-  orderNo: 'ORDER_20250101_001',
-  amount: 9900, // 单位：分
-  description: '商品名称',
-  tradeType: 'jsapi',
-  userId: 'user_openid',
-  notifyUrl: 'https://example.com/payment/notify/wechat',
-  metadata: { source: 'web' },
-})
-
-if (result.success) {
-  // result.data: PaymentOrder { provider, tradeType, clientParams, prepayId? }
-  // clientParams 包含调起支付所需参数
-}
-
-// amount / totalAmount 必须是正整数（单位：分）
-```
-
-### 4. 处理支付回调
-
-```typescript
-// API 路由：POST /payment/notify/:provider
-const result = await payment.handleNotify('wechat', {
-  body: await request.text(),
-  headers: Object.fromEntries(request.headers),
-})
-
-if (result.success) {
-  // result.data: { orderNo, transactionId, amount, status, paidAt? }
-  // 更新订单状态...
-}
-```
-
-### 5. 查询订单
-
-```typescript
-const result = await payment.queryOrder('wechat', 'ORDER_20250101_001')
-
-if (result.success) {
-  // result.data.status: 'pending' | 'paid' | 'closed' | 'refunded' | 'failed'
-}
-```
-
-### 6. 退款
-
-```typescript
-const result = await payment.refund('wechat', {
-  orderNo: 'ORDER_20250101_001',
-  refundNo: 'REFUND_20250101_001',
-  amount: 9900,
-  totalAmount: 9900, // 微信退款必填
-  reason: '用户退款',
-})
-```
-
-### 7. 客户端调起支付（浏览器）
-
-```typescript
-import { invokePayment } from '@h-ai/payment/client'
-
-// 前端拿到服务端返回的 PaymentOrder 后调起支付
-const payResult = await invokePayment(orderResult.data)
-```
-
-## 核心 API（服务端）
-
-| API                                              | 用途     | 返回值                        |
-| ------------------------------------------------ | -------- | ----------------------------- |
-| `payment.init(config)`                           | 初始化   | `HaiResult<void>`                |
-| `payment.close()`                                | 关闭     | `void`                        |
-| `payment.createOrder(providerName, input)`       | 创建订单 | `HaiResult<PaymentOrder>`        |
-| `payment.handleNotify(providerName, request)`    | 处理回调 | `HaiResult<PaymentNotifyResult>` |
-| `payment.queryOrder(providerName, orderNo)`      | 查询订单 | `HaiResult<OrderStatus>`         |
-| `payment.refund(providerName, input)`            | 退款     | `HaiResult<RefundResult>`        |
-| `payment.closeOrder(providerName, orderNo)`      | 关闭订单 | `HaiResult<void>`                |
-| `payment.getProvider(name)`                      | 获取 Provider | `PaymentProvider \| undefined` |
-| `payment.registerProvider(provider)`             | 注册自定义 Provider | `void`              |
-
-## 客户端 API
-
-| API                      | 用途     | 返回值                        |
-| ------------------------ | -------- | ----------------------------- |
-| `invokePayment(options)` | 调起支付 | `HaiResult<InvokePaymentResult>` |
-
-## 错误码 — `HaiPaymentError`
-
-| 错误码 | code | 说明 |
-|--------|------|------|
-| `HaiPaymentError.CREATE_ORDER_FAILED` | `hai:payment:001` | 创建订单失败 |
-| `HaiPaymentError.QUERY_ORDER_FAILED` | `hai:payment:002` | 查询订单失败 |
-| `HaiPaymentError.REFUND_FAILED` | `hai:payment:003` | 退款失败 |
-| `HaiPaymentError.CLOSE_ORDER_FAILED` | `hai:payment:004` | 关闭订单失败 |
-| `HaiPaymentError.NOT_INITIALIZED` | `hai:payment:010` | 模块未初始化 |
-| `HaiPaymentError.SIGN_FAILED` | `hai:payment:020` | 签名失败 |
-| `HaiPaymentError.PROVIDER_NOT_FOUND` | `hai:payment:030` | Provider 未注册 |
-| `HaiPaymentError.INVALID_AMOUNT` | `hai:payment:040` | 金额无效 |
-| `HaiPaymentError.NOTIFY_VERIFY_FAILED` | `hai:payment:050` | 回调验签失败 |
-| `HaiPaymentError.NOTIFY_PARSE_FAILED` | `hai:payment:051` | 回调解析失败 |
-| `HaiPaymentError.INVOKE_WEB_FAILED` | `hai:payment:060` | Web 端调起支付失败 |
-| `HaiPaymentError.INVOKE_APP_FAILED` | `hai:payment:061` | App 端调起支付失败 |
-| `HaiPaymentError.CONFIG_ERROR` | `hai:payment:070` | 配置无效 |
-
-## Provider 模式
-
-内置 Provider：
-
-- **wechat** — 微信支付 API v3
-- **alipay** — 支付宝开放平台
-- **stripe** — Stripe Checkout Session 模式
-
-自定义 Provider 通过 `payment.registerProvider(provider)` 注册。
-
-### HTTP API 契约
-
-```typescript
-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
-```
-
-## 常见模式
-
-### 服务端路由（SvelteKit）
-
-```typescript
-import { kit } from '@h-ai/kit'
-// src/routes/api/v1/payment/create/+server.ts
-import { payment } from '@h-ai/payment'
-
-export const POST = kit.handler(async ({ request, locals }) => {
-  const body = await request.json()
-  const result = await payment.createOrder(body.provider, {
-    orderNo: body.orderNo,
-    amount: body.amount,
-    description: body.description,
-    tradeType: body.tradeType,
-    userId: body.userId,
-    notifyUrl: body.notifyUrl,
-  })
-
-  if (!result.success) {
-    return kit.response.internalError(result.error.message)
-  }
-
-  return kit.response.ok(result.data, locals.requestId)
-})
-```
-
-### 完整支付流程
-
-```
-1. 客户端 → 服务端：创建订单（api.payment.orders.create({...})）
-2. 服务端 → 支付平台：调用 Provider 创建预支付
-3. 服务端 → 客户端：返回 providerData（含调起参数）
-4. 客户端：invokePayment(providerData) 调起支付
-5. 支付平台 → 服务端：异步回调通知
-6. 服务端：handleNotify() 验签 + 更新订单状态
-7. 客户端：轮询或回调查询订单状态
-```
-
-## 审计日志
-
-关键支付操作（创建订单、回调、退款、关闭订单）成功后自动写入审计日志（依赖 `@h-ai/audit`），无需额外配置。`queryOrder` 为只读操作，不写审计日志。
-
-内置 Provider 的 HTTP 请求默认带 15 秒超时；Stripe 可通过 `webhookToleranceSeconds` 调整 webhook 时间戳容忍窗口。
-
-## 相关 Skills
-
-- `hai-kit`：服务端 API 路由与契约处理
-- `hai-api-client`：客户端契约调用
-- `hai-reldb`：订单持久化存储
-- `hai-audit`：审计日志（payment 内部自动调用）
-- `hai-core`：HaiResult 类型、日志、配置
+- [运行环境](reference.md#运行环境)
+- [依赖](reference.md#依赖)
+- [适用场景](reference.md#适用场景)
+- [使用步骤](reference.md#使用步骤)
+- [核心 API（服务端）](reference.md#核心-api服务端)
+- [客户端 API](reference.md#客户端-api)
+- [错误码 — `HaiPaymentError`](reference.md#错误码--haipaymenterror)
+- [Provider 模式](reference.md#provider-模式)
+- [常见模式](reference.md#常见模式)
+- [审计日志](reference.md#审计日志)
+- [相关 Skills](reference.md#相关-skills)