@h-ai/cli 0.1.0-alpha5

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

@@ -0,0 +1,355 @@
+---
+name: hai-iam
+description: 使用 @h-ai/iam 进行身份认证（密码/OTP/LDAP/API Key）、统一 Bearer Token 管理（TokenPair/refresh/revoke）与 RBAC 授权（角色/权限/通配符）；当需求涉及登录、注册、权限检查、角色管理、Token 认证或 API 契约时使用。
+---
+
+# hai-iam
+
+> `@h-ai/iam` 是统一的身份与访问管理模块，支持多种认证策略（密码/OTP/LDAP/API Key）、Bearer Token 管理和 RBAC 授权。依赖 `@h-ai/reldb`（持久化）、`@h-ai/cache`（Token + 权限缓存）、`@h-ai/crypto`（密码哈希）、`@h-ai/audit`（审计日志）。
+
+---
+
+## 依赖
+
+| 模块 | 用途 | 是否必需 | 初始化要求 |
+| --- | --- | --- | --- |
+| `@h-ai/reldb` | 数据库（用户/角色/权限持久化） | **必需** | 需在 `iam.init()` 前初始化 |
+| `@h-ai/cache` | 缓存（会话/OTP/重置令牌/权限缓存） | **必需** | 需在 `iam.init()` 前初始化 |
+| `@h-ai/crypto` | 密码哈希 | 内部使用 | 自动初始化 |
+| `@h-ai/audit` | 审计日志（RBAC 关键操作记录） | 内部使用 | 已初始化时自动写入 |
+
+## 适用场景
+
+- 用户注册与登录（密码/OTP/LDAP/API Key）
+- Bearer Token 认证与管理（TokenPair: accessToken + refreshToken）
+- Token 刷新（rotation 策略）与吊销
+- RBAC 角色/权限的创建、分配与检查
+- API Key 管理（创建、吊销、验证）
+- 密码重置流程
+- 与 kit 集成的认证守卫
+- API 契约定义（`@h-ai/iam/api`）
+
+---
+
+## 使用步骤
+
+### 1. 配置
+
+```yaml
+# config/_iam.yml
+password:
+  minLength: ${HAI_IAM_PASSWORD_MIN_LENGTH:8}
+  requireUppercase: true
+  requireNumber: true
+session:
+  maxAge: ${HAI_IAM_SESSION_MAX_AGE:86400}
+  refreshTokenMaxAge: ${HAI_IAM_REFRESH_TOKEN_MAX_AGE:604800} # 7 天
+  sliding: true
+  singleDevice: false
+login:
+  password: true
+  otp: false
+register:
+  enabled: true
+security:
+  maxLoginAttempts: ${HAI_IAM_MAX_LOGIN_ATTEMPTS:5}
+  lockoutDuration: 900
+rbac:
+  defaultRole: user
+  superAdminRole: super_admin
+```
+
+### 2. 初始化
+
+```typescript
+import { cache } from '@h-ai/cache'
+import { reldb } from '@h-ai/reldb'
+import { iam } from '@h-ai/iam'
+
+// 必须先初始化 reldb 和 cache
+await reldb.init(core.config.get('db'))
+await cache.init(core.config.get('cache'))
+
+// IAM 自动使用已初始化的 reldb 和 cache 单例
+await iam.init({
+  ...core.config.get('iam'),
+  seedDefaultData: true,
+})
+```
+
+初始化时自动创建数据库表（5 张）：`hai_iam_users`、`hai_iam_roles`、`hai_iam_permissions`、`hai_iam_role_permissions`、`hai_iam_user_roles`。
+
+Token 和 OTP 存储在 cache 中（不落库）。refreshToken 使用独立的 cache key 存储。
+
+---
+
+## 核心 API
+
+### 认证 — `iam.auth`
+
+| 方法               | 签名                                                        | 说明                               |
+| ------------------ | ----------------------------------------------------------- | ---------------------------------- |
+| `login`            | `({ identifier, password }) => Promise<HaiResult<AuthResult>>` | 密码登录（用户名/邮箱/手机号）     |
+| `loginWithOtp`     | `({ identifier, code }) => Promise<HaiResult<AuthResult>>`     | OTP 验证码登录                     |
+| `loginWithLdap`    | `({ username, password }) => Promise<HaiResult<AuthResult>>`   | LDAP 登录                          |
+| `loginWithApiKey`  | `({ key }) => Promise<HaiResult<AuthResult>>`                  | API Key 登录                       |
+| `sendOtp`          | `(identifier) => Promise<HaiResult<{ expiresAt }>>`            | 发送 OTP 验证码                    |
+| `verifyToken`      | `(token) => Promise<HaiResult<Session>>`                       | 验证令牌（推荐入口，委托 session） |
+| `logout`           | `(token) => Promise<HaiResult<void>>`                          | 登出                               |
+| `registerAndLogin` | `(options: RegisterOptions) => Promise<HaiResult<AuthResult>>`  | 注册并登录（一站式）               |
+
+**AuthResult**（已改造为 TokenPair）：
+
+```typescript
+interface AuthResult {
+  user: User
+  tokens: TokenPair
+  roles: string[]
+  permissions: string[]
+  agreements?: AgreementDisplay
+}
+
+interface TokenPair {
+  accessToken: string
+  refreshToken: string
+  expiresIn: number
+  tokenType: 'Bearer'
+}
+```
+
+### 会话管理 — `iam.session`
+
+| 方法                | 签名                                                                 | 说明                                    |
+| ------------------- | -------------------------------------------------------------------- | --------------------------------------- |
+| `create`            | `({ userId, username, roles, source? }) => Promise<HaiResult<Session>>` | 创建会话（返回含 TokenPair 的 session） |
+| `get`               | `(token) => Promise<HaiResult<Session \| null>>`                        | 获取会话（滑动续期自动延长）            |
+| `verifyToken`       | `(token) => Promise<HaiResult<Session>>`                                | 验证令牌                                |
+| `update`            | `(token, data) => Promise<HaiResult<void>>`                             | 更新会话字段（浅合并 data）             |
+| `delete`            | `(token) => Promise<HaiResult<void>>`                                   | 删除会话                                |
+| `deleteByUserId`    | `(userId) => Promise<HaiResult<number>>`                                | 删除用户所有会话（返回删除数量）        |
+| `refresh`           | `(refreshToken) => Promise<HaiResult<TokenPair>>`                       | 刷新 Token（rotation：旧 Token 失效）   |
+| `revokeRefresh`     | `(refreshToken) => Promise<HaiResult<void>>`                            | 吊销 refreshToken                       |
+| `patchUserSessions` | `(userId, updates: SessionFieldUpdates) => Promise<HaiResult<void>>`    | 批量更新用户所有会话的 roles/permissions |
+
+**Token 刷新（rotation 策略）**：
+
+- `refresh()` 会删除旧的 accessToken + refreshToken
+- 创建全新的 session，返回新的 TokenPair
+- 旧 refreshToken 立即失效，防止重放攻击
+
+### 用户管理 — `iam.user`
+
+| 方法                       | 签名                                                                    | 说明                                 |
+| -------------------------- | ----------------------------------------------------------------------- | ------------------------------------ |
+| `register`                 | `(input) => Promise<HaiResult<RegisterResult>>`                            | 用户注册                             |
+| `getUser`                  | `(id, options?) => Promise<HaiResult<User \| null>>`                       | 获取用户（可选 include: ['roles']）  |
+| `getCurrentUser`           | `(token) => Promise<HaiResult<User>>`                                      | 通过令牌获取当前用户                 |
+| `updateCurrentUser`        | `(token, data: UpdateCurrentUserInput) => Promise<HaiResult<User>>`        | 当前用户修改个人资料（白名单字段）   |
+| `listUsers`                | `(options?: ListUsersOptions) => Promise<HaiResult<PaginatedResult<User>>>` | 用户列表（分页 + 搜索 + 过滤）      |
+| `updateUser`               | `(id, data) => Promise<HaiResult<User>>`                                   | 更新用户信息                         |
+| `deleteUser`               | `(id) => Promise<HaiResult<void>>`                                         | 删除用户（自动清除会话）             |
+| `changePassword`           | `(id, old, new) => Promise<HaiResult<void>>`                               | 修改密码（自动清除会话）             |
+| `changeCurrentUserPassword`| `(token, old, new) => Promise<HaiResult<void>>`                            | 当前用户修改密码（通过令牌识别）     |
+| `requestPasswordReset`     | `(email) => Promise<HaiResult<void>>`                                      | 请求密码重置（防枚举）               |
+| `confirmPasswordReset`     | `(token, newPassword) => Promise<HaiResult<void>>`                         | 确认密码重置（自动清除会话）         |
+| `adminResetPassword`       | `(userId, newPassword) => Promise<HaiResult<void>>`                        | 管理员直接重置密码                   |
+| `validatePassword`         | `(password) => HaiResult<void>`                                  | 验证密码强度（**同步方法**）         |
+
+### RBAC 授权 — `iam.authz`
+
+| 方法                       | 签名                                                                             | 说明                                         |
+| -------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------- |
+| `checkPermission`          | `(userId, permission) => Promise<HaiResult<boolean>>`                               | 检查权限（超管自动通过，支持通配符）         |
+| `getUserPermissions`       | `(userId) => Promise<HaiResult<Permission[]>>`                                      | 获取用户权限列表（通过角色聚合去重）         |
+| `getUserRoles`             | `(userId) => Promise<HaiResult<Role[]>>`                                            | 获取用户角色列表                             |
+| `getUserRolesForMany`      | `(userIds) => Promise<HaiResult<Map<string, Role[]>>>`                              | 批量获取多用户角色（避免 N+1）               |
+| `assignRole`               | `(userId, roleId, tx?) => Promise<HaiResult<void>>`                                 | 分配角色给用户                               |
+| `removeRole`               | `(userId, roleId, tx?) => Promise<HaiResult<void>>`                                 | 移除用户角色                                 |
+| `syncRoles`                | `(userId, roleIds, tx?) => Promise<HaiResult<void>>`                                | 同步用户角色（替换为目标列表）               |
+| `createRole`               | `({ code, name, description? }, tx?) => Promise<HaiResult<Role>>`                   | 创建角色                                     |
+| `getRole`                  | `(roleId) => Promise<HaiResult<Role \| null>>`                                      | 获取角色                                     |
+| `getRoleByCode`            | `(code) => Promise<HaiResult<Role \| null>>`                                        | 根据代码获取角色                             |
+| `getAllRoles`              | `(options?) => Promise<HaiResult<PaginatedResult<Role>>>`                           | 获取所有角色（分页）                         |
+| `updateRole`               | `(roleId, data, tx?) => Promise<HaiResult<Role>>`                                   | 更新角色                                     |
+| `deleteRole`               | `(roleId, tx?) => Promise<HaiResult<void>>`                                         | 删除角色（级联清理关联 + 会话同步）          |
+| `createPermission`         | `({ code, name, type?, resource?, action? }, tx?) => Promise<HaiResult<Permission>>`| 创建权限                                     |
+| `getPermission`            | `(permissionId) => Promise<HaiResult<Permission \| null>>`                          | 获取权限                                     |
+| `getPermissionByCode`      | `(code) => Promise<HaiResult<Permission \| null>>`                                  | 根据代码获取权限                             |
+| `getAllPermissions`         | `(options?: PermissionQueryOptions) => Promise<HaiResult<PaginatedResult<Permission>>>` | 获取所有权限（分页 + 类型/关键字筛选）   |
+| `deletePermission`         | `(permissionId, tx?) => Promise<HaiResult<void>>`                                   | 删除权限（级联清理关联 + 会话同步）          |
+| `assignPermissionToRole`   | `(roleId, permId, tx?) => Promise<HaiResult<void>>`                                 | 分配权限给角色                               |
+| `removePermissionFromRole` | `(roleId, permId, tx?) => Promise<HaiResult<void>>`                                 | 移除角色权限                                 |
+| `getRolePermissions`       | `(roleId) => Promise<HaiResult<Permission[]>>`                                      | 获取角色的权限列表                           |
+| `getRolePermissionsForMany`| `(roleIds) => Promise<HaiResult<Map<string, Permission[]>>>`                        | 批量获取多角色权限（避免 N+1）               |
+
+**通配符规则**：`admin:*` 匹配 `admin:read`、`admin:write` 等。超管角色自动拥有所有权限。
+
+### API Key 管理 — `iam.apiKey`
+
+| 方法           | 签名                                                                    | 说明                                   |
+| -------------- | ----------------------------------------------------------------------- | -------------------------------------- |
+| `createApiKey` | `(userId, options: CreateApiKeyOptions) => Promise<HaiResult<CreateApiKeyResult>>` | 创建 API Key（明文密钥仅返回一次） |
+| `listApiKeys`  | `(userId) => Promise<HaiResult<ApiKey[]>>`                                 | 列出用户的所有 API Key                 |
+| `getApiKey`    | `(keyId) => Promise<HaiResult<ApiKey \| null>>`                            | 获取 API Key 详情                      |
+| `revokeApiKey` | `(keyId) => Promise<HaiResult<void>>`                                      | 吊销/删除 API Key                      |
+| `verifyApiKey` | `(rawKey) => Promise<HaiResult<ApiKey>>`                                   | 验证 API Key 并返回实体（含用户 ID）   |
+
+> 需在 `login.apikey: true` 时才会初始化此子模块，否则访问返回 `NOT_INITIALIZED` 错误。
+
+---
+
+## API 契约 — `@h-ai/iam/api`
+
+```typescript
+import { iamEndpoints } from '@h-ai/iam/api'
+
+// 9 个端点契约，含 Zod schema
+iamEndpoints.login // POST /api/v1/auth/login
+iamEndpoints.loginWithOtp // POST /api/v1/auth/login-otp
+iamEndpoints.sendOtp // POST /api/v1/auth/send-otp
+iamEndpoints.logout // POST /api/v1/auth/logout
+iamEndpoints.register // POST /api/v1/auth/register
+iamEndpoints.currentUser // GET  /api/v1/auth/me
+iamEndpoints.refreshToken // POST /api/v1/auth/refresh
+iamEndpoints.changePassword // POST /api/v1/auth/change-password
+iamEndpoints.resetPassword // POST /api/v1/auth/reset-password
+```
+
+服务端使用 `kit.fromContract()`，客户端使用 `api.call()`：
+
+```typescript
+// 服务端
+export const POST = kit.fromContract(iamEndpoints.login, async (input) => {
+  const result = await iam.auth.login(input)
+  return result.success ? kit.response.ok(result.data) : kit.response.unauthorized()
+})
+
+// 客户端
+const result = await api.call(iamEndpoints.login, { username, password })
+```
+
+---
+
+## 错误码 — `HaiIamError`
+
+| 错误码 | code | 说明 |
+|--------|------|------|
+| `HaiIamError.AUTH_FAILED` | `hai:iam:001` | 认证失败 |
+| `HaiIamError.INVALID_CREDENTIALS` | `hai:iam:002` | 凭证无效 |
+| `HaiIamError.USER_NOT_FOUND` | `hai:iam:003` | 用户不存在 |
+| `HaiIamError.USER_DISABLED` | `hai:iam:004` | 用户已禁用 |
+| `HaiIamError.USER_LOCKED` | `hai:iam:005` | 用户已锁定 |
+| `HaiIamError.USER_ALREADY_EXISTS` | `hai:iam:006` | 用户已存在 |
+| `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.OTP_RESEND_TOO_FAST` | `hai:iam:011` | 发送过于频繁 |
+| `HaiIamError.LOGIN_DISABLED` | `hai:iam:012` | 登录方式已禁用 |
+| `HaiIamError.REGISTER_DISABLED` | `hai:iam:013` | 注册已禁用 |
+| `HaiIamError.STRATEGY_NOT_SUPPORTED` | `hai:iam:014` | 认证策略不支持 |
+| `HaiIamError.APIKEY_INVALID` | `hai:iam:015` | API Key 无效 |
+| `HaiIamError.APIKEY_EXPIRED` | `hai:iam:016` | API Key 已过期 |
+| `HaiIamError.APIKEY_DISABLED` | `hai:iam:017` | API Key 已禁用 |
+| `HaiIamError.APIKEY_NOT_FOUND` | `hai:iam:018` | API Key 不存在 |
+| `HaiIamError.RESET_TOKEN_INVALID` | `hai:iam:019` | 重置令牌无效 |
+| `HaiIamError.RESET_TOKEN_EXPIRED` | `hai:iam:020` | 重置令牌已过期 |
+| `HaiIamError.RESET_TOKEN_MAX_ATTEMPTS` | `hai:iam:021` | 重置验证次数超限 |
+| `HaiIamError.SESSION_NOT_FOUND` | `hai:iam:101` | 会话不存在 |
+| `HaiIamError.SESSION_EXPIRED` | `hai:iam:102` | 会话已过期 |
+| `HaiIamError.SESSION_INVALID` | `hai:iam:103` | 会话无效 |
+| `HaiIamError.SESSION_CREATE_FAILED` | `hai:iam:104` | 会话创建失败 |
+| `HaiIamError.TOKEN_EXPIRED` | `hai:iam:105` | 令牌已过期 |
+| `HaiIamError.TOKEN_INVALID` | `hai:iam:106` | 令牌无效 |
+| `HaiIamError.TOKEN_REFRESH_FAILED` | `hai:iam:107` | 令牌刷新失败 |
+| `HaiIamError.PERMISSION_DENIED` | `hai:iam:201` | 权限不足 |
+| `HaiIamError.ROLE_NOT_FOUND` | `hai:iam:202` | 角色不存在 |
+| `HaiIamError.PERMISSION_NOT_FOUND` | `hai:iam:203` | 权限不存在 |
+| `HaiIamError.ROLE_ALREADY_EXISTS` | `hai:iam:204` | 角色已存在 |
+| `HaiIamError.PERMISSION_ALREADY_EXISTS` | `hai:iam:205` | 权限已存在 |
+| `HaiIamError.LDAP_CONNECTION_FAILED` | `hai:iam:301` | LDAP 连接失败 |
+| `HaiIamError.LDAP_BIND_FAILED` | `hai:iam:302` | LDAP 绑定失败 |
+| `HaiIamError.LDAP_SEARCH_FAILED` | `hai:iam:303` | LDAP 搜索失败 |
+| `HaiIamError.REPOSITORY_ERROR` | `hai:iam:401` | 存储层操作错误 |
+| `HaiIamError.NOT_FOUND` | `hai:iam:402` | 资源不存在 |
+| `HaiIamError.CONFLICT` | `hai:iam:403` | 资源冲突 |
+| `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` | 内部错误 |
+
+---
+
+## 常见模式
+
+### 与 kit 集成（hooks.server.ts）
+
+```typescript
+import { iam } from '$lib/server/init'
+import { kit } from '@h-ai/kit'
+
+const haiHandle = kit.createHandle({
+  validateSession: async (token) => {
+    const result = await iam.auth.verifyToken(token)
+    if (!result.success)
+      return null
+    const roles = await iam.authz.getUserRoles(result.data.userId)
+    return {
+      userId: result.data.userId,
+      roles: roles.success ? roles.data.map(r => r.code) : [],
+      permissions: [],
+    }
+  },
+  guards: [
+    {
+      guard: kit.guard.auth({ apiMode: true }),
+      paths: ['/api/*'],
+      exclude: ['/api/auth/*'],
+    },
+  ],
+})
+
+export const handle = kit.sequence(haiHandle)
+```
+
+### 客户端认证流程
+
+```typescript
+import { iamEndpoints } from '@h-ai/iam/api'
+
+// 登录 → 保存 Token
+const login = await api.call(iamEndpoints.login, { username, password })
+if (login.success) {
+  await api.auth.setTokens(login.data.tokens)
+}
+
+// 获取当前用户
+const me = await api.call(iamEndpoints.currentUser, {})
+
+// Token 过期时，api-client 自动调用 refreshUrl 刷新
+// 刷新失败时，清除 Token 并跳转登录页
+
+// 登出
+await api.call(iamEndpoints.logout, {})
+await api.auth.clear()
+```
+
+### 自动会话失效
+
+以下操作自动清除受影响用户的所有活跃会话：
+
+- `deleteUser` / `updateUser({ enabled: false })` / `changePassword` / `confirmPasswordReset`
+- `assignRole` / `removeRole` / `deleteRole` 会同步更新活跃会话中的角色列表
+
+---
+
+## 相关 Skills
+
+- `hai-build`：模块初始化顺序（db → cache → iam）
+- `hai-kit`：SvelteKit 集成（Bearer Token + 契约处理）
+- `hai-api-client`：客户端契约调用
+- `hai-reldb`：底层数据存储
+- `hai-cache`：Token 与权限缓存
+- `hai-crypto`：密码哈希（内部依赖）
+- `hai-ui`：IAM 场景组件（LoginForm/RegisterForm 等）

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

@@ -0,0 +1,319 @@
+---
+name: hai-kit
+description: 使用 @h-ai/kit 构建 SvelteKit 请求管道与 API 安全边界（handle/guard/middleware/handler/validate/response/fromContract）。当需求涉及 hooks.server.ts、权限守卫、限流、统一响应、Bearer Token 认证、契约处理或 CORS 配置时使用。
+---
+
+# hai-kit
+
+`@h-ai/kit` 是 hai-framework 的 SvelteKit 集成层。它把请求处理中的"通用横切能力"收敛到统一命名空间 `kit`：
+
+- 请求入口：`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`
+- `kit.createHandle` / `kit.sequence`
+- `kit.guard.*`（`require` / `check`）
+- `kit.handler` / `kit.response` / `kit.validate`
+- `kit.fromContract(endpoint, fn)` — 契约到 SvelteKit handler
+- 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 使用前初始化 |
+
+## 使用步骤
+
+### 1) 在 `hooks.server.ts` 搭建请求管道
+
+```typescript
+import { kit } from '@h-ai/kit'
+
+export const handle = kit.createHandle({
+  auth: {
+    verifyToken: async token => token
+      ? { userId: 'u_1', roles: ['admin'], permissions: ['user:read'] }
+      : null,
+    loginUrl: '/auth/login',
+    protectedPaths: ['/admin/*', '/api/*'],
+    publicPaths: ['/api/auth/*', '/api/public/*'],
+  },
+  rateLimit: { windowMs: 60_000, maxRequests: 100 },
+  logging: true,
+  cors: {
+    origins: ['https://example.com'],
+    capacitor: true, // 自动添加 capacitor://localhost 等原生 App Origin
+  },
+})
+```
+
+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
+import { kit } from '@h-ai/kit'
+import { z } from 'zod'
+
+const CreateSchema = 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)
+})
+```
+
+### 3) 基于契约的类型安全 handler（推荐）
+
+```typescript
+import { iam } from '@h-ai/iam'
+import { iamEndpoints } from '@h-ai/iam/api'
+import { kit } from '@h-ai/kit'
+
+// 入参自动 Zod 校验，返回值类型安全
+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)
+})
+```
+
+### 4) CORS 配置
+
+```typescript
+export const handle = kit.createHandle({
+  cors: {
+    origins: ['https://example.com', 'https://*.example.com'], // 支持通配符
+    capacitor: true, // 自动添加 capacitor://localhost, ionic://localhost 等
+    methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
+    credentials: true,
+  },
+})
+```
+
+### 5) 需要传输加密时启用 `crypto` 配置
+
+```typescript
+import { crypto } from '@h-ai/crypto'
+import { kit } from '@h-ai/kit'
+
+export const handle = kit.createHandle({
+  crypto: {
+    crypto,
+    transport: true,
+    cookieEncryptionKey: process.env.HAI_KIT_COOKIE_KEY,
+  },
+})
+```
+
+## 核心 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 控制流）       |
+| `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    | 未处理异常         |
+
+### 传输加密常见错误（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`
+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)
+  }
+  return kit.response.ok(result.data)
+})
+
+// ─── 支付：创建订单 ───
+import { paymentEndpoints } from '@h-ai/payment/api'
+import { payment } from '$lib/server/init'
+
+export const POST = kit.fromContract(paymentEndpoints.createOrder, async (input, event) => {
+  kit.guard.require(event.locals.session, 'payment:create')
+  const result = await payment.order.create(input)
+  if (!result.success) {
+    return kit.response.internalError(result.error.message)
+  }
+  return kit.response.created(result.data)
+})
+```
+
+### 已有契约模块一览
+
+| 模块       | 导入路径               | 端点对象             | 典型端点                        |
+| ---------- | -------------------- | -------------------- | ------------------------------- |
+| `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）
+2. 服务端用 `kit.fromContract(endpoint, handler)` 处理
+3. 客户端用 `api.call(endpoint, input)` 调用
+4. 入参/出参全链路类型安全 + 运行时校验
+
+### CORS + Capacitor 配置
+
+Capacitor 原生 App 的 WebView 发送的请求并非 CORS 同源，需要配置：
+
+```typescript
+cors: {
+  origins: ['https://your-api.com'],
+  capacitor: true,  // 自动添加 capacitor://* 和 ionic://* 等预设
+}
+```
+
+### 双构建模式
+
+```typescript
+// svelte.config.js
+import { createAdapter } from '@h-ai/kit/adapter'
+
+const config = {
+  kit: {
+    adapter: createAdapter(),
+    // VITE_ADAPTER=static → adapter-static (SPA)
+    // VITE_ADAPTER=node   → adapter-node (SSR)
+    // 默认 → adapter-node
+  },
+}
+```
+
+## 相关 Skills
+
+- `hai-core`：全局配置、日志、HaiResult 基础能力
+- `hai-iam`：Token 认证、角色权限模型
+- `hai-api-client`：客户端契约调用
+- `hai-crypto`：传输加密与密钥管理能力
+- `hai-capacitor`：原生 App CORS 场景