@h-ai/cli 0.1.0-alpha9 → 1.0.0-beta.2

package/templates/skills/hai-api-client/SKILL.md

@@ -1,355 +1,42 @@
 ---
 name: hai-api-client
-description: 使用 @h-ai/api-client 单例模式构建多端共用的纯 TypeScript HTTP 客户端，通过 api.init() 初始化，支持 Bearer Token 自动管理、401 刷新重试、契约调用（EndpointDef）与流式响应；当需求涉及客户端 API 请求、Token 管理、契约调用或多端数据层时使用。
+description: "接入或排查 @h-ai/api-client typed API、登录 Token、自动刷新与加密传输；适用于 Web、SSR 和原生客户端。"
 ---
 
 # hai-api-client
 
-> `@h-ai/api-client` 是 hai-framework 的纯 TypeScript HTTP 客户端，多端共用（Web/H5/Android），基于 fetch API 实现。以单例模式暴露 `api` 对象，通过 `api.init()` 初始化。核心能力：Token 自动附加、401 自动刷新重试、基于 EndpointDef 的类型安全契约调用。
+## 能力契约
 
----
-
-## 运行环境
-
-**浏览器端专用。** 服务端 `+page.server.ts` / `+server.ts` 应直接调用模块 API（如 `iam.auth.login()`），不经过 HTTP 自环。
-
-### 与 kit.client 的分工
-
-| 场景 | 推荐 | 原因 |
-|------|------|------|
-| SSR SvelteKit 应用（同源请求） | `kit.client.create().apiFetch`（见 hai-kit SKILL） | 自动 CSRF、传输加密、同源 Cookie 透传 |
-| SPA / 原生 App（跨域请求） | **本模块** `api.init()` + `api.call()` | 完整 Token 管理、401 自动刷新、独立 baseUrl |
-| 契约调用（类型安全，跨域） | **本模块** `api.call(endpoint, input)` | EndpointDef 双向 Zod 校验 |
-
----
-
-## 适用场景
-
-- 浏览器端/App 端统一 API 请求
-- Bearer Token 自动管理（存储、附加、刷新）
-- 基于 EndpointDef 契约的类型安全调用
-- 流式响应（SSE / ReadableStream）
-- 拦截器（请求/响应前后处理）
-
----
-
-## 使用步骤
-
-### 1. 初始化客户端
-
-```typescript
-import { api } from '@h-ai/api-client'
-
-// 应用启动时初始化
-await api.init({
-  baseUrl: 'http://localhost:3000',
-  auth: {
-    refreshUrl: '/auth/refresh',
-    // Token 刷新失败回调（可选，常用于跳转登录页）
-    onRefreshFailed: () => {
-      window.location.href = '/login'
-    },
-  },
-  timeout: 15000,
-})
-```
-
-> `auth.storage` 可选：默认使用 `createLocalStorageTokenStorage()`；SSR/测试建议显式传 `createMemoryTokenStorage()`，App 端建议传 `createCapacitorTokenStorage()`。
-
-### 2. 普通请求
-
-```typescript
-// GET 请求
-const users = await api.get<User[]>('/api/v1/users')
-
-// POST 请求
-const result = await api.post<CreateResult>('/api/v1/users', {
-  username: 'alice',
-  email: 'alice@example.com',
-})
-
-// 带查询参数（直接传入 Record<string, unknown>）
-const page = await api.get<PageResult>('/api/v1/users', { page: 1, pageSize: 20 })
-```
-
-### 3. 契约调用（推荐）
-
-```typescript
-import { iamEndpoints } from '@h-ai/iam/api'
-
-// 类型安全：入参和返回值由 EndpointDef 的 Zod schema 推导，入参/出参双向校验
-const loginResult = await api.call(iamEndpoints.login, {
-  identifier: 'admin',
-  password: 'StrongPassword123',
-})
-
-if (loginResult.success) {
-  // loginResult.data 类型自动推导为 { user, tokens, agreements? }
-  await api.auth.setTokens(loginResult.data.tokens)
-}
-```
-
-### 4. Token 管理
-
-```typescript
-// 手动设置 Token（登录后）
-await api.auth.setTokens({
-  accessToken: 'xxx',
-  refreshToken: 'yyy',
-  expiresIn: 3600,
-  tokenType: 'Bearer',
-})
-
-// 清除 Token（登出）
-await api.auth.clear()
-
-// 监听 Token 刷新
-api.auth.onTokenRefreshed((tokens) => {
-  // tokens 包含新的 accessToken / refreshToken
-})
-```
-
-### 5. 流式响应
-
-```typescript
-const controller = new AbortController()
-
-// stream(path, body?, options?) — 返回 AsyncIterable<string>，按 SSE data: 行 yield
-for await (const chunk of api.stream('/api/v1/ai/chat', { message: 'Hello' }, { signal: controller.signal })) {
-  // 每个 chunk 是 SSE data: 行的内容
-}
-
-// 主动停止
-controller.abort()
-```
-
-### 6. 关闭
-
-```typescript
-await api.close()
-```
-
----
-
-## 核心 API
+| 项目 | 契约 |
+| --- | --- |
+| 能力 | 使用 @h-ai/api-client 调用 typed API，管理 Token、刷新与加密传输 |
+| 适用场景 | 跨端调用共享 HTTP API 或排查认证刷新 |
+| 输入 | baseUrl、共享 contract、TokenStorage、可选 transport.crypto |
+| 输出 | typed client；领域响应为 HaiResult |
+| 限制 | 先 init，结束 close；浏览器 Cookie 与服务端配置匹配，原生端使用安全 TokenStorage。不要在多用户 SSR 中共享带用户 token 的单例。 |
 
-| API                                | 用途           | 关键点                                |
-| ---------------------------------- | -------------- | ------------------------------------- |
-| `api.init(config)`                 | 初始化客户端   | 返回 `HaiResult<void>`   |
-| `api.close()`                      | 关闭并释放资源 | 重复调用安全                          |
-| `api.isInitialized`                | 初始化状态     | `boolean`                             |
-| `api.config`                       | 当前配置       | 未初始化时为 `null`                   |
-| `api.get<T>(path, params?)`        | GET 请求       | params 附加到 URL query string        |
-| `api.post<T>(path, body?)`         | POST 请求      | body 自动 JSON 序列化                 |
-| `api.put<T>(path, body?)`          | PUT 请求       | —                                     |
-| `api.patch<T>(path, body?)`        | PATCH 请求     | —                                     |
-| `api.delete<T>(path, params?)`     | DELETE 请求    | params 附加到 URL query string        |
-| `api.call(endpoint, input)`        | 契约调用       | 入参/出参 Zod 双向校验，路径/方法由契约决定 |
-| `api.upload(path, file, options?)`  | 文件上传       | FormData，支持附加字段                |
-| `api.stream(path, body?)`          | 流式请求       | 返回 AsyncIterable<string>（SSE）     |
-| `api.auth.setTokens(tokens)`       | 设置 Token     | 存入 TokenStorage                     |
-| `api.auth.clear()`                 | 清空 Token     | 清空存储                              |
-| `api.auth.onTokenRefreshed(cb)`    | 刷新回调       | 返回取消订阅函数，Token 自动刷新成功时通知 |
+## 使用路径
 
-### EndpointDef 契约结构
+1. 读取服务端 contract、apiPrefix、CORS、Cookie 与 transport 配置，选择默认客户端或 `apiClient.create(contract)`。
+2. 浏览器使用 Cookie/内存；SSR 按请求创建客户端，原生使用安全 TokenStorage，不跨用户复用单例。
+3. 检查 init 与每次业务调用的 `success`。登录成功后设置 tokens；优先使用 `createAuthActions` 连接认证 UI。
+4. 同步服务端与客户端的刷新、加密和错误处理；切换配置前 close，任务结束释放客户端。
+5. 验证登录、刷新重试、失败、退出与会话恢复。
 
-```typescript
-interface EndpointDef<TInput, TOutput> {
-  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'
-  path: string
-  input: ZodSchema<TInput>
-  output: ZodSchema<TOutput>
-  requireAuth?: boolean
-  meta?: { summary?: string; tags?: string[] }
-}
-```
+错误提示与诊断分离：HTTP/UI 边界用 core.error.toPublic，仅公开 i18n 安全消息及 error.traceId；重新翻译后用 core.error.formatMessage 保留关联。ToastContainer 默认只显示可读说明，自动将编号移入排查信息图标，展开后可查看、复制并提供给客户支持或开发人员。前后端日志传完整 Error 和操作上下文，使用同一 requestId/traceId 并脱敏；禁止只写通用错误标题，也不能把 cause/ext/SQL/绑定值直接返回用户。数据库日志保留安全的驱动错误码、消息和堆栈。
 
-### TokenStorage 接口
+非 2xx HTTP 响应中的合法失败 HaiResult 保留服务端业务码、消息与 traceId，以真实 HTTP 状态执行脱敏。验证 409 冲突、422 输入错误、429 限流和 5xx，不只测试 HTTP 200 业务失败；UI 包装 Error 时通过 cause 保留 HaiError。
 
-```typescript
-interface TokenStorage {
-  getAccessToken: () => Promise<string | null>
-  setAccessToken: (token: string) => Promise<void>
-  getRefreshToken: () => Promise<string | null>
-  setRefreshToken: (token: string) => Promise<void>
-  clear: () => Promise<void>
-}
-```
+## 按需参考
 
-内置实现：`createLocalStorageTokenStorage()`（Web）、`createMemoryTokenStorage()`（SSR/测试）。
-App 端使用 `@h-ai/capacitor` 的 `createCapacitorTokenStorage()`。
+serv/kit 对通过请求绑定、签名和 MAC 校验但超出时间窗口的报文返回加密的 HTTP 400 时间错误；客户端抛 `TransportTimeError`（`hai:crypto:071`），提示同步设备和服务器时间后刷新重试。`api-client` 映射为 `VALIDATION_FAILED`，在 `cause.transportCode` 保留该原因。不会自动重放请求或放宽防重放窗口；篡改或未认证报文仍返回通用认证失败。
 
----
-
-## 错误码 — `HaiApiClientError`
-
-| 错误码 | code | 说明 |
-|--------|------|------|
-| `HaiApiClientError.NETWORK_ERROR` | `hai:api-client:001` | 网络不可达 |
-| `HaiApiClientError.TIMEOUT` | `hai:api-client:002` | 请求超时 |
-| `HaiApiClientError.SERVER_ERROR` | `hai:api-client:003` | 5xx 服务端错误 |
-| `HaiApiClientError.UNAUTHORIZED` | `hai:api-client:004` | 401 未认证 |
-| `HaiApiClientError.FORBIDDEN` | `hai:api-client:005` | 403 无权限 |
-| `HaiApiClientError.NOT_FOUND` | `hai:api-client:006` | 404 资源不存在 |
-| `HaiApiClientError.VALIDATION_FAILED` | `hai:api-client:007` | 请求参数校验失败 |
-| `HaiApiClientError.TOKEN_REFRESH_FAILED` | `hai:api-client:008` | Token 刷新失败 |
-| `HaiApiClientError.NOT_INITIALIZED` | `hai:api-client:010` | 未初始化 |
-| `HaiApiClientError.CONFIG_ERROR` | `hai:api-client:011` | 配置错误 |
-| `HaiApiClientError.UNKNOWN` | `hai:api-client:099` | 未知错误 |
-
----
-
-## API 契约范式（端到端类型安全）
-
-> `@h-ai/api-client` 和 `@h-ai/kit` 共同消费模块 `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. `api.call(xxEndpoints.xxx, input)` → Zod 校验入参 → 按 method/path 发起 HTTP → Zod 校验出参
-3. 入参或出参校验失败均返回 `VALIDATION_FAILED`（1206）
-4. 返回 `HaiResult<TOutput>`
-
-```typescript
-import { storageEndpoints } from '@h-ai/storage/api'
-import { iamEndpoints } from '@h-ai/iam/api'
-import { aiEndpoints } from '@h-ai/ai/api'
-
-// 存储：获取上传签名 URL
-const upload = await api.call(storageEndpoints.presignUpload, {
-  key: 'avatars/user-1.png',
-  contentType: 'image/png',
-})
-
-// IAM：登录
-const login = await api.call(iamEndpoints.login, {
-  username: 'admin',
-  password: 'xxx',
-})
-
-// AI：发送消息
-const chat = await api.call(aiEndpoints.sendMessage, {
-  conversationId: 'conv-1',
-  content: 'Hello',
-})
-```
-
-### 已有契约模块一览
-
-| 模块       | 导入路径               | 端点对象             | 典型端点                        |
-| ---------- | -------------------- | -------------------- | ------------------------------- |
-| `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, …      |
-
-
-## 常见模式
-
-### 与 @h-ai/iam/api 契约配合
-
-```typescript
-import { iamEndpoints } from '@h-ai/iam/api'
-
-// 登录（入参字段为 identifier + password）
-const login = await api.call(iamEndpoints.login, { identifier, password })
-if (login.success) {
-  // login.data 类型：{ user, tokens, agreements? }
-  await api.auth.setTokens(login.data.tokens)
-}
-
-// 获取当前用户（自动携带 Bearer Token）
-const me = await api.call(iamEndpoints.currentUser, {})
-// me.data 类型：{ user, roles, permissions }
-
-// 修改密码
-await api.call(iamEndpoints.changePassword, { oldPassword, newPassword })
-
-// 登出
-const accessToken = '...' // 从 Token 存储获取
-await api.call(iamEndpoints.logout, { accessToken })
-await api.auth.clear()
-```
-
-#### 401 自动刷新机制
-
-当请求收到 401 响应时，客户端自动执行：
-
-1. 使用存储的 `refreshToken` 调用 `auth.refreshUrl`（POST）
-2. 刷新成功 → 更新存储 → 用新 Token 重试原请求（仅重试一次）
-3. 刷新失败 → 清空 Token → 触发 `onRefreshFailed` 回调
-4. 多个并发 401 → **自动去重**，只发一次刷新请求
-
-> 流式请求（`api.stream()`）同样支持 401 自动刷新 + 重试。
-
-#### 可用的 IAM 端点
-
-| 分类 | 端点 | 方法 | 路径 | 认证 |
-|------|------|------|------|------|
-| 认证 | `iamEndpoints.login` | POST | /auth/login | 否 |
-| | `iamEndpoints.loginWithOtp` | POST | /auth/login/otp | 否 |
-| | `iamEndpoints.logout` | POST | /auth/logout | 是 |
-| | `iamEndpoints.currentUser` | GET | /auth/me | 是 |
-| | `iamEndpoints.refreshToken` | POST | /auth/refresh | 否 |
-| | `iamEndpoints.sendOtp` | POST | /auth/otp/send | 否 |
-| | `iamEndpoints.register` | POST | /auth/register | 否 |
-| | `iamEndpoints.changePassword` | POST | /auth/change-password | 是 |
-| | `iamEndpoints.updateCurrentUser` | PUT | /auth/me | 是 |
-| 用户管理 | `iamEndpoints.listUsers` | GET | /iam/users | 是 |
-| | `iamEndpoints.getUser` | GET | /iam/users/:id | 是 |
-| | `iamEndpoints.createUser` | POST | /iam/users | 是 |
-| | `iamEndpoints.updateUser` | PUT | /iam/users/:id | 是 |
-| | `iamEndpoints.deleteUser` | DELETE | /iam/users/:id | 是 |
-| | `iamEndpoints.adminResetPassword` | POST | /iam/users/:id/reset-password | 是 |
-| 角色管理 | `iamEndpoints.listRoles` | GET | /iam/roles | 是 |
-| | `iamEndpoints.getRole` | GET | /iam/roles/:id | 是 |
-| | `iamEndpoints.createRole` | POST | /iam/roles | 是 |
-| | `iamEndpoints.updateRole` | PUT | /iam/roles/:id | 是 |
-| | `iamEndpoints.deleteRole` | DELETE | /iam/roles/:id | 是 |
-| 权限管理 | `iamEndpoints.listPermissions` | GET | /iam/permissions | 是 |
-| | `iamEndpoints.getPermission` | GET | /iam/permissions/:id | 是 |
-| | `iamEndpoints.createPermission` | POST | /iam/permissions | 是 |
-| | `iamEndpoints.deletePermission` | DELETE | /iam/permissions/:id | 是 |
-
-### Android App 中使用
-
-```typescript
-import { api } from '@h-ai/api-client'
-import { createCapacitorTokenStorage } from '@h-ai/capacitor'
-
-// 应用启动时初始化
-await api.init({
-  baseUrl: import.meta.env.PUBLIC_API_BASE,
-  auth: {
-    storage: createCapacitorTokenStorage(),
-    refreshUrl: '/api/v1/auth/refresh',
-  },
-})
-```
-
----
+按本次操作读取对应小节；以已安装版本的公开类型核验签名，示例中的业务变量由应用提供。
 
-## 相关 Skills
+- [使用步骤](reference.md#使用步骤)
+- [Token Storage 适配器](reference.md#token-storage-适配器)
+- [核心 API](reference.md#核心-api)
+- [常见模式](reference.md#常见模式)
+- [配置驱动认证页面](reference.md#配置驱动认证页面)
 
-- `hai-iam`：认证契约定义（iamEndpoints）
-- `hai-capacitor`：原生 Token 存储
-- `hai-kit`：服务端契约处理（kit.fromContract）
-- `hai-core`：HaiResult 类型、错误处理基础
+普通请求与 Token 刷新自动将当前 `core.i18n` 语言发送为 `Accept-Language`；切换语言时同步 core。`headers` 中显式配置的同名头优先。

package/templates/skills/hai-api-client/reference.md

@@ -0,0 +1,180 @@
+# hai-api-client 参考
+
+> `@h-ai/api-client` 是跨端 typed API client。公共 HTTP API 由 `@h-ai/api-contract` 定义，服务端由 `@h-ai/serv` 挂载，客户端直接调用 `apiClient.<domain>.<group>.<operation>()`。
+
+
+认证协议仅支持 v2：独立随机 SM4-CBC 密钥和 HMAC-SM3 密钥由 SM2 封装，先验签、再验证 MAC，最后解密 CBC。请求由客户端私钥签名，响应由所选服务端版本签名。认证字段包括 version、direction、serverKeyId、clientId、128 位随机 requestId（兼 nonce）、issuedAt、HTTP method、pathname + 原始 search 的 SM3 pathHash，以及响应 status。请求有效期 5 分钟，未来时钟偏差最多 30 秒；共享 registry 原子消费 (clientId, requestId)，nonce 至少保留到 issuedAt + 6 分钟以覆盖节点偏差，存储故障拒绝请求。Redis 必须保留有效 nonce，使用 noeviction/可靠持久化策略；各节点时钟须同步。此能力防止同一传输消息重放，业务重试仍需自己的幂等键。
+
+空 POST 也发送空明文的认证封装；GET/HEAD 将封装放在 X-Hai-Transport 头，204/304/HEAD 等无正文响应也使用同名头承载认证封装。其它请求/响应在 JSON 正文承载封装并带 X-Encrypted: true。客户端必须关联原请求上下文和 HTTP status，缺标记、旧格式或认证失败一律 reject；明文接口由 Serv/Kit 路径规则 `encryption: disabled` 或宿主 `excludePaths` 显式允许；调用方同步选择普通请求，API Client/Kit 包装器使用自己的 `excludePaths`。CORS 须允许并暴露 X-Hai-Transport。握手公钥的真实性依赖 TLS，不替代 IAM 业务授权。
+
+## 使用步骤
+
+### 1. 初始化
+
+浏览器默认使用 httpOnly cookie 存储（推荐）：
+
+```ts
+import { apiClient } from '@h-ai/api-client'
+
+await apiClient.init({
+  baseUrl: 'https://api.example.com/api/v1',
+  auth: {},
+})
+```
+
+启用传输加密时，只传顶层 `crypto` 句柄；api-client 内部自动调用 `crypto.transport.createClient()`：
+
+```ts
+import { apiClient } from '@h-ai/api-client'
+import { crypto } from '@h-ai/crypto'
+
+await crypto.init()
+
+await apiClient.init({
+  baseUrl: 'https://api.example.com/api/v1',
+  auth: {},
+  transport: { crypto }, // 默认协商路径：/api/v1/_hai/key-exchange
+})
+```
+
+App/Capacitor 场景传入自定义 TokenStorage：
+
+```ts
+import { createCapacitorTokenStorage } from '@h-ai/capacitor'
+
+await apiClient.init({
+  baseUrl: 'https://api.example.com/api/v1',
+  auth: { storage: createCapacitorTokenStorage() },
+})
+```
+
+> `createCapacitorTokenStorage()` 仅在 Android/iOS 原生环境 + `@aparajita/capacitor-secure-storage` 已安装时持久化 token；纯 Web 不会回退到 `localStorage`。
+
+SSR / Node.js 测试场景请显式传入内存存储：
+
+```ts
+import { apiClient } from '@h-ai/api-client'
+
+await apiClient.init({
+  baseUrl: 'https://api.example.com/api/v1',
+  auth: { storage: apiClient.tokenStorage.memory() },
+})
+```
+
+### 2. 调用 typed API
+
+```ts
+const login = await apiClient.iam.auth.login({ identifier: 'alice', password: 'secret' })
+if (login.success) {
+  // 默认 httpOnly cookie 模式下，refresh token 由服务端 Set-Cookie 管理。
+  await apiClient.auth.setTokens(login.data.tokens)
+}
+
+const me = await apiClient.iam.auth.currentUser()
+if (me.success) {
+  // currentUser 返回服务端最新角色/权限；不要把权限快照持久化到 localStorage。
+  const { roles, permissions, ...user } = me.data
+}
+const upload = await apiClient.storage.presignedUrls.createUpload({ key: 'avatar.png' })
+const answer = await apiClient.ai.chats.sendMessage({ message: 'hello' })
+```
+
+默认 `ai.chats.createCompletion({ messages, tools, tool_choice })` 只返回非流式 HaiResult JSON；不接受 stream 字段。完整 function 参数 JSON Schema、strict 与工具选择直接到模型。先检查 success，再读取助手 tool_calls；业务方授权执行工具后，以对应 tool_call_id 回传工具消息。流式接口须绑定应用自定义流契约。
+
+### 3. 自定义 contract
+
+```ts
+import { apiClient } from '@h-ai/api-client'
+import { apiContract } from '@h-ai/api-contract'
+
+const contract = apiContract.create({ iam: apiContract.iam })
+const client = apiClient.create(contract)
+await client.init({ baseUrl: 'https://api.example.com/api/v1' })
+```
+
+`client.config` / `apiClient.config` 返回的是脱敏后的运行配置快照；`baseUrl` 的内嵌凭证与 `headers.authorization` 等敏感值会自动隐藏。
+
+### 4. 关闭
+
+```ts
+await apiClient.close()
+```
+
+> 已初始化后再次 `init()` 会返回 `CONFIG_ERROR`，不会覆盖现有 client；切换 `baseUrl` / `fetch` / `transport` 前必须先 `close()`，避免旧 transport 会话泄漏。
+
+## Token Storage 适配器
+
+| 工厂调用 | 存储位置 | 适用场景 |
+| --- | --- | --- |
+| `apiClient.tokenStorage.httpOnlyCookie()` | httpOnly cookie（服务端管理） | **默认**；浏览器端推荐，refresh token 不暴露给 JS |
+| `apiClient.tokenStorage.memory()` | 内存 | SSR / Node.js 单元测试（需显式传入） |
+
+浏览器只使用内存 access token + 服务端 httpOnly refresh Cookie；原生端注入平台安全 TokenStorage。禁止将认证凭据持久化到 Web Storage。
+
+### httpOnly Cookie 模式
+
+Access token 存在内存中，refresh token 由服务端通过 `HttpOnly` cookie 管理，浏览器 JS 无法读取，可有效防止 XSS 窃取 token。
+
+**前提**：服务端需配置 `serv.createApp({ iam, refreshCookie: {} })`，参见 `hai-serv` skill。
+
+启用 `transport` 时，登录、业务请求以及 401 后的自动刷新都会复用同一个加密 fetch 链路；不要在业务代码中手写明文 `/auth/refresh` 请求。
+
+自动刷新识别真实 HTTP 401（`Response.status`），以及 HTTP 200 的有效失败 HaiResult（`success=false`、字符串 `error.code/message`、`error.httpStatus=401`），成功后只重试一次原请求。内置登录、注册与配置的 `auth.refreshPath` 排除自动刷新，403/500 等其它失败也不刷新。serv 普通 procedure 的 HTTP 状态仍为 200；调用方须检查最终 `success/error.code` 并处理刷新失败后的登录失效。
+
+```ts
+import { apiClient } from '@h-ai/api-client'
+
+// apiClient.tokenStorage.httpOnlyCookie() 是默认存储，无需显式指定
+await apiClient.init({
+  baseUrl: 'https://api.example.com/api/v1',
+  auth: {},
+})
+
+// 登录后设置 access token（refresh token 由服务端写入 cookie，前端无需操作）
+const login = await apiClient.iam.auth.login({ identifier: 'alice', password: 'secret' })
+if (login.success) {
+  await apiClient.auth.setTokens(login.data.tokens)
+}
+```
+
+## 核心 API
+
+| API | 用途 |
+| --- | --- |
+| `apiClient.init(config)` | 初始化默认 API Service client；重复初始化返回 `CONFIG_ERROR` |
+| `apiClient.close()` | 清理 client 状态 |
+| `apiClient.auth.setTokens(tokens)` | 使旧刷新失效并替换凭据；非 httpOnly 存储保存提供的 refresh token，缺省时清除旧值 |
+| `apiClient.auth.clear()` | 使旧刷新失效并清理本客户端 Token；服务端会话/Cookie 另由退出接口撤销 |
+| `apiClient.auth.onTokenRefreshed(cb)` | 监听刷新结果 |
+| `apiClient.create(contract)` | 创建自定义 typed client |
+| `apiClient.tokenStorage.{memory,httpOnlyCookie}()` | TokenStorage 工厂 |
+
+退出/换账号使用 `auth.clear()` / `auth.setTokens()`，不直接写 storage。方法立即取消旧刷新，并按顺序提交异步存储操作；迟到的成功/401 不会恢复旧身份、覆盖新账号或触发旧回调。该保证针对同一个客户端的认证管理器，SSR 仍须按请求隔离实例。
+
+### Transport 配置
+
+| 字段 | 说明 |
+| --- | --- |
+| `transport.crypto` | 已初始化的 `@h-ai/crypto` 实例 |
+| `transport.keyExchangePath` | 相对于 `baseUrl` 的协商子路径，默认 `/_hai/key-exchange` |
+
+服务端必须对应启用 `serv.createApp({ transport: { crypto, serverKeyRing, keyStore } })`。serverKeyRing 与 keyStore 仅服务端注入，生产各节点共用受管版本化 ring 和共享 registry；客户端只接收 serverKeyId/公钥并在请求密文带回版本，不得接收私钥。旧版本撤销后需销毁客户端会话并重协商，不自动重放非幂等请求。
+自动刷新会沿用 `transport.encryptedFetch`，并在 httpOnly cookie 模式下发送空请求体 + `credentials: 'include'`，由服务端从 cookie 读取 refresh token。
+
+CLI 独立 mobile 模板在选择 IAM/crypto 时安装前端 crypto 并默认启用该 transport，未选择 crypto 时保留明文 API 模式。`PUBLIC_API_TRANSPORT=off` 仅用于明确匹配的明文服务；`PUBLIC_API_KEY_EXCHANGE_PATH` 可调整公开协商子路径。配置先于 client 初始化，握手失败不会回退明文。关闭顺序为 client → 本客户端初始化的 crypto，不能关闭其他调用方已有的 crypto。
+
+## 常见模式
+
+- `baseUrl` 通常包含服务端 `apiPrefix`，例如 `/api/v1`。
+- 业务错误不 throw，统一判断 `HaiResult.success`。
+- 客户端不导入服务端 `procedures` 或 `@h-ai/serv`。
+- 客户端不导入 `@h-ai/crypto` 的内部 transport 工厂，只通过 `transport: { crypto }` 装配。
+- 前端只依赖 `@h-ai/api-client` 和 contract 类型，不依赖业务模块实现。
+- httpOnly cookie 模式需服务端与客户端同步配置，跨 Origin 请求需正确设置 CORS 与 credentials；`SameSite=Strict` 限制跨站 Cookie，跨域不等于跨站。
+
+
+## 配置驱动认证页面
+
+`apiClient.createAuthActions(client)` 为含标准 iam contract 的客户端提供 publicConfig、login、register、sendOtp、requestPasswordReset、confirmPasswordReset。login 输入使用 identifier/password/method/code，method 为 password、ldap、email、sms。成功认证自动调用既有安全 TokenStorage；应用只需把动作传给 AuthPanel，并在 onauthenticated 中刷新自己的用户状态或导航。
+
+传输容量默认从服务端握手获取 `maxPlaintextBytes`；可选客户端 `transport.maxPlaintextBytes` 只收紧上限。容量失败映射为 `HaiApiClientError.PAYLOAD_TOO_LARGE`（`hai:api-client:020`），cause 保留 direction/stage/limitBytes/actualBytes，应用可据此显示本地化提示。

package/templates/skills/hai-api-contract/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: hai-api-contract
+description: "新增、组合或修改共享 HTTP 接口的路径与输入输出 Schema，供 serv 与 typed client 共用。"
+---
+
+# hai-api-contract
+
+## 能力契约
+
+| 项目 | 契约 |
+| --- | --- |
+| 能力 | 使用 @h-ai/api-contract 定义、组合和扩展共享 HTTP contract 与 Zod 输入输出 |
+| 适用场景 | 新增/修改共享接口定义，不负责实现 handler |
+| 输入 | 领域路径、schema、HTTP 方法、共享错误模型 |
+| 输出 | 供 serv 实现和 api-client 消费的 contract |
+| 限制 | 纯定义，无 init/close；不包含服务端实现或密钥。业务路径属于 contract，公共传输配置属于 transport。 |
+
+## 使用路径
+
+1. 查当前公开 exports 与已有领域 contract，确认业务路径唯一来源。
+2. 在 contract 中声明 method/path 与输入输出 Schema；只导出真正跨接口或跨层复用的 Schema。
+3. 用 `apiContract.create` 组合领域；不把服务实现、私有配置或传输前缀写进 contract。
+4. 同步 serv procedures、typed client、调用方与失败/校验测试；普通业务输出按当前 HaiResult 契约。
+5. 独立 contract 包实际执行声明构建。推导需要的上游公共类型 `ContractProcedureBuilderWithInputOutput`、`ContractProcedureBuilderWithOutput`、`Schema` 已由本包转出；显式类型从公开入口 `import type`，不引用依赖内部路径。
+
+## 按需参考
+
+按本次操作读取对应小节；以已安装版本的公开类型核验签名，示例中的业务变量由应用提供。
+
+- [运行环境](reference.md#运行环境)
+- [适用场景](reference.md#适用场景)
+- [使用步骤](reference.md#使用步骤)
+- [核心 API](reference.md#核心-api)
+- [Contract 定义规范](reference.md#contract-定义规范)
+- [常见模式](reference.md#常见模式)
+- [测试](reference.md#测试)