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

package/templates/shared/run-e2e.mjs

@@ -0,0 +1,65 @@
+/** 运行浏览器验收，并在报告写完后清理本次输出；失败和中断同样清理。 */
+import { spawn } from 'node:child_process'
+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import process from 'node:process'
+
+const cwd = process.cwd()
+const require = createRequire(resolve(cwd, 'package.json'))
+const cli = require.resolve('@playwright/test/cli')
+const dataParent = resolve(process.env.HAI_E2E_DATA_ROOT || tmpdir())
+mkdirSync(dataParent, { recursive: true })
+const dataRoot = mkdtempSync(join(dataParent, 'hai-browser-e2e-'))
+const groups = [[]]
+for (const argument of process.argv.slice(2)) {
+  if (argument === '--next')
+    groups.push([])
+  else
+    groups.at(-1).push(argument)
+}
+let child
+let interrupted = false
+function stop() {
+  if (interrupted)
+    return
+  interrupted = true
+  if (process.platform === 'win32' && child?.pid && child.exitCode === null) {
+    // Windows 的 kill 不传递 SIGTERM；同时结束本次 Playwright 创建的浏览器与服务进程。
+    spawn('taskkill', ['/pid', String(child.pid), '/t', '/f'], { windowsHide: true, stdio: 'ignore' })
+      .once('error', () => child?.kill())
+  }
+  else {
+    child?.kill()
+  }
+}
+process.once('SIGINT', stop)
+process.once('SIGTERM', stop)
+try {
+  for (const args of groups) {
+    const code = await new Promise((resolve, reject) => {
+      child = spawn(process.execPath, [cli, 'test', ...args], {
+        cwd,
+        windowsHide: true,
+        stdio: 'inherit',
+        env: { ...process.env, HAI_AUTH_EVIDENCE_DIR: join(cwd, 'test-results/evidence'), HAI_E2E_DATA_ROOT: dataRoot },
+      })
+      child.once('error', reject)
+      child.once('exit', resolve)
+    })
+    if (code !== 0 || interrupted) {
+      process.exitCode = typeof code === 'number' && code !== 0 ? code : 1
+      break
+    }
+  }
+}
+finally {
+  process.removeListener('SIGINT', stop)
+  process.removeListener('SIGTERM', stop)
+  // 固定为当前测试工程中的标准输出目录，禁止删除调用方任意指定的路径。
+  for (const name of ['test-results', 'playwright-report'])
+    rmSync(join(cwd, name), { recursive: true, force: true, maxRetries: 3, retryDelay: 100 })
+  // Playwright 退出后服务进程已关闭，此时删除 SQLite / storage，避免 Windows 文件锁。
+  rmSync(dataRoot, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 })
+}

package/templates/shared/vite-runtime-config.ts

@@ -0,0 +1,54 @@
+/** Vite 开发与预览的公开运行配置；同一份静态构建可连接不同环境的 API。 */
+import type { CoreConfig } from '@h-ai/core'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { Plugin } from 'vite'
+
+/** 只允许浏览器可见的地址、开关和品牌字段，禁止传入 process.env 或完整服务配置。 */
+export interface PublicRuntimeConfig {
+  /** 包含 API 前缀的公开地址，例如 https://example.test/api/v1。 */
+  apiBase?: string
+  /** 客户端传输开关，与服务端一致。 */
+  apiTransport?: string
+  /** 公开密钥交换端点。 */
+  apiKeyExchangePath?: string
+  /** 客户端公开元数据；不含密钥或连接参数。 */
+  core?: Pick<CoreConfig, 'name' | 'version' | 'env' | 'defaultLocale'> & { logging?: Pick<NonNullable<CoreConfig['logging']>, 'level' | 'format'> }
+}
+
+/**
+ * 在加载应用前提供无缓存的公开配置；构建只复制空的占位文件。
+ * @example `plugins: [publicRuntimeConfig({ apiBase: process.env.PUBLIC_API_BASE })]`
+ */
+export function publicRuntimeConfig(config: PublicRuntimeConfig): Plugin {
+  const metadata = config.core
+  // 明确投影字段，JavaScript 调用方即使误传完整配置也不能公开连接参数或密钥。
+  const publicConfig: PublicRuntimeConfig = {
+    apiBase: config.apiBase,
+    apiTransport: config.apiTransport,
+    apiKeyExchangePath: config.apiKeyExchangePath,
+    core: metadata
+      ? {
+          name: metadata.name,
+          version: metadata.version,
+          env: metadata.env,
+          defaultLocale: metadata.defaultLocale,
+          logging: metadata.logging ? { level: metadata.logging.level, format: metadata.logging.format } : undefined,
+        }
+      : undefined,
+  }
+  const body = `globalThis.__HAI_PUBLIC_CONFIG__ = { ...globalThis.__HAI_PUBLIC_CONFIG__, ...${JSON.stringify(publicConfig)} };\n`
+  const respond = (_request: IncomingMessage, response: ServerResponse): void => {
+    response.setHeader('Content-Type', 'application/javascript; charset=utf-8')
+    response.setHeader('Cache-Control', 'no-store')
+    response.end(body)
+  }
+  return {
+    name: 'hai-public-runtime-config',
+    configureServer(server) {
+      server.middlewares.use('/runtime-config.js', respond)
+    },
+    configurePreviewServer(server) {
+      server.middlewares.use('/runtime-config.js', respond)
+    },
+  }
+}

package/templates/skills/AGENTS.md

@@ -41,7 +41,7 @@
 1. 先搜索现有实现、引用点、测试和 README。
 2. 小步修改，优先保持目录结构、公开 API 和脚本稳定。
 3. 改动公共类型、配置、模板或共享逻辑时，同步更新所有调用方与文档。
-4. 每次改动后按影响范围运行质量门禁并记录结果。
+4. 一轮修改完成后按影响范围收集全部可执行门禁结果，汇总问题再集中修复、复测；普通失败不立即从头重跑。
 
 ## 代码注释与示例
 
@@ -52,7 +52,7 @@
 
 ## 质量门禁
 
-先核对 package.json，按影响范围执行已有脚本；文档检查引用，UI/路由变更再运行 E2E。未运行项说明原因。
+先核对 package.json，按 [分轮验证与集中修复](.agents/skills/hai-app-tests/validation.md) 收集适用检查与日志，再归并修复、复测失败及受影响项；普通失败不中断独立检查，真实前置阻塞才暂停依赖项。文档检查引用，UI/路由变更加 E2E，未运行项说明原因。
 
 ```bash
 pnpm typecheck
@@ -64,7 +64,7 @@ pnpm test:e2e
 
 ## 完成条件
 
-- typecheck / lint / build / test / test:e2e 状态明确；失败必须先修复或明确说明原因。
+- typecheck / lint / build / test / test:e2e 状态明确；整轮收集后集中修复，最终必需门禁对最终代码有效通过，未执行或阻塞明确原因，不能宣称完成。
 - README、i18n、测试、代码注释与实现保持一致。
 - 最终回复说明执行过的门禁、已同步的文档 / 依赖方，以及未完成项。
 

package/templates/skills/bridges/admin/AGENTS.md

@@ -60,7 +60,7 @@
 
 ## 质量门禁
 
-先核对 package.json，按影响范围执行已有脚本；文档检查引用，UI/路由变更再运行 E2E。未运行项说明原因。
+先核对 package.json，按 [分轮验证与集中修复](.agents/skills/hai-app-tests/validation.md) 收集适用检查与日志，再归并修复、复测失败及受影响项；普通失败不中断独立检查，真实前置阻塞才暂停依赖项。文档检查引用，UI/路由变更加 E2E，未运行项说明原因。
 
 ```bash
 pnpm typecheck

package/templates/skills/bridges/api/AGENTS.md

@@ -57,7 +57,7 @@
 
 ## 质量门禁
 
-先核对 package.json，按影响范围执行已有脚本；文档检查引用，UI/路由变更再运行 E2E。未运行项说明原因。
+先核对 package.json，按 [分轮验证与集中修复](.agents/skills/hai-app-tests/validation.md) 收集适用检查与日志，再归并修复、复测失败及受影响项；普通失败不中断独立检查，真实前置阻塞才暂停依赖项。文档检查引用，UI/路由变更加 E2E，未运行项说明原因。
 
 ```bash
 pnpm typecheck

package/templates/skills/bridges/fullstack/AGENTS.md.hbs

@@ -74,7 +74,7 @@ Fullstack 多包工程入口。先读 README、根 workspace 脚本与相关 pac
 
 ## 质量门禁
 
-按影响范围执行，跨包契约从根工作区验证：
+按 [分轮验证与集中修复](.agents/skills/hai-app-tests/validation.md) 收集一轮适用门禁及日志，汇总后集中修复、复测失败及受影响项；普通失败不中断独立检查，真实前置阻塞才暂停依赖项。跨包契约从根工作区验证：
 
 ```bash
 pnpm typecheck

package/templates/skills/bridges/h5/AGENTS.md

@@ -60,7 +60,7 @@
 
 ## 质量门禁
 
-先核对 package.json，按影响范围执行已有脚本；文档检查引用，UI/路由变更再运行 E2E。未运行项说明原因。
+先核对 package.json，按 [分轮验证与集中修复](.agents/skills/hai-app-tests/validation.md) 收集适用检查与日志，再归并修复、复测失败及受影响项；普通失败不中断独立检查，真实前置阻塞才暂停依赖项。文档检查引用，UI/路由变更加 E2E，未运行项说明原因。
 
 ```bash
 pnpm typecheck

package/templates/skills/bridges/mobile-app/AGENTS.md

@@ -71,7 +71,7 @@ pnpm cap:build:android:release
 
 ## 质量门禁
 
-先核对 package.json，按影响范围执行已有脚本；文档检查引用，UI/路由变更再运行 E2E。未运行项说明原因。
+先核对 package.json，按 [分轮验证与集中修复](.agents/skills/hai-app-tests/validation.md) 收集适用检查与日志，再归并修复、复测失败及受影响项；普通失败不中断独立检查，真实前置阻塞才暂停依赖项。文档检查引用，UI/路由变更加 E2E，未运行项说明原因。
 
 ```bash
 pnpm typecheck

package/templates/skills/bridges/website/AGENTS.md

@@ -60,7 +60,7 @@
 
 ## 质量门禁
 
-先核对 package.json，按影响范围执行已有脚本；文档检查引用，UI/路由变更再运行 E2E。未运行项说明原因。
+先核对 package.json，按 [分轮验证与集中修复](.agents/skills/hai-app-tests/validation.md) 收集适用检查与日志，再归并修复、复测失败及受影响项；普通失败不中断独立检查，真实前置阻塞才暂停依赖项。文档检查引用，UI/路由变更加 E2E，未运行项说明原因。
 
 ```bash
 pnpm typecheck

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

@@ -1,6 +1,6 @@
 ---
 name: hai-api-client
-description: "使用 @h-ai/api-client 调用 typed API，管理 Token、刷新与加密传输。"
+description: "接入或排查 @h-ai/api-client typed API、登录 Token、自动刷新与加密传输；适用于 Web、SSR 和原生客户端。"
 ---
 
 # hai-api-client
@@ -15,167 +15,20 @@ description: "使用 @h-ai/api-client 调用 typed API，管理 Token、刷新
 | 输出 | typed client；领域响应为 HaiResult |
 | 限制 | 先 init，结束 close；浏览器 Cookie 与服务端配置匹配，原生端使用安全 TokenStorage。不要在多用户 SSR 中共享带用户 token 的单例。 |
 
-> `@h-ai/api-client` 是跨端 typed API client。公共 HTTP API 由 `@h-ai/api-contract` 定义，服务端由 `@h-ai/serv` 挂载，客户端直接调用 `apiClient.<domain>.<group>.<operation>()`。
+## 使用路径
 
-## 使用步骤
+1. 读取服务端 contract、apiPrefix、CORS、Cookie 与 transport 配置，选择默认客户端或 `apiClient.create(contract)`。
+2. 浏览器使用 Cookie/内存；SSR 按请求创建客户端，原生使用安全 TokenStorage，不跨用户复用单例。
+3. 检查 init 与每次业务调用的 `success`。登录成功后设置 tokens；优先使用 `createAuthActions` 连接认证 UI。
+4. 同步服务端与客户端的刷新、加密和错误处理；切换配置前 close，任务结束释放客户端。
+5. 验证登录、刷新重试、失败、退出与会话恢复。
 
-### 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' })
-```
-
-### 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 单元测试（需显式传入） |
-| `apiClient.tokenStorage.localStorage()` | localStorage | 非敏感场景（有 XSS 风险，生产不推荐） |
-
-### 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)` | 写入 access token；非 httpOnly 存储会同时写入 refresh token |
-| `apiClient.auth.clear()` | 清理 Token |
-| `apiClient.auth.onTokenRefreshed(cb)` | 监听刷新结果 |
-| `apiClient.create(contract)` | 创建自定义 typed client |
-| `apiClient.tokenStorage.{memory,localStorage,httpOnlyCookie}()` | TokenStorage 工厂 |
-
-### Transport 配置
-
-| 字段 | 说明 |
-| --- | --- |
-| `transport.crypto` | 已初始化的 `@h-ai/crypto` 实例 |
-| `transport.keyExchangePath` | 相对于 `baseUrl` 的协商子路径，默认 `/_hai/key-exchange` |
-
-服务端必须对应启用 `serv.createApp({ transport: { crypto } })`。
-自动刷新会沿用 `transport.encryptedFetch`，并在 httpOnly cookie 模式下发送空请求体 + `credentials: 'include'`，由服务端从 cookie 读取 refresh token。
-
-## 常见模式
-
-- `baseUrl` 通常包含服务端 `apiPrefix`，例如 `/api/v1`。
-- 业务错误不 throw，统一判断 `HaiResult.success`。
-- 客户端不导入服务端 `procedures` 或 `@h-ai/serv`。
-- 客户端不导入 `@h-ai/crypto` 的内部 transport 工厂，只通过 `transport: { crypto }` 装配。
-- 前端只依赖 `@h-ai/api-client` 和 contract 类型，不依赖业务模块实现。
-- httpOnly cookie 模式需服务端与客户端同步配置，不支持跨域刷新（`SameSite=Strict`）。
-
-
-## 配置驱动认证页面
-
-`apiClient.createAuthActions(client)` 为含标准 iam contract 的客户端提供 publicConfig、login、register、sendOtp、requestPasswordReset、confirmPasswordReset。login 输入使用 identifier/password/method/code，method 为 password、ldap、email、sms。成功认证自动调用既有安全 TokenStorage；应用只需把动作传给 AuthPanel，并在 onauthenticated 中刷新自己的用户状态或导航。
+- [使用步骤](reference.md#使用步骤)
+- [Token Storage 适配器](reference.md#token-storage-适配器)
+- [核心 API](reference.md#核心-api)
+- [常见模式](reference.md#常见模式)
+- [配置驱动认证页面](reference.md#配置驱动认证页面)

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

@@ -0,0 +1,166 @@
+# hai-api-client 参考
+
+> `@h-ai/api-client` 是跨端 typed API client。公共 HTTP API 由 `@h-ai/api-contract` 定义，服务端由 `@h-ai/serv` 挂载，客户端直接调用 `apiClient.<domain>.<group>.<operation>()`。
+
+## 使用步骤
+
+### 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' })
+```
+
+### 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 单元测试（需显式传入） |
+| `apiClient.tokenStorage.localStorage()` | localStorage | 非敏感场景（有 XSS 风险，生产不推荐） |
+
+### 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)` | 写入 access token；非 httpOnly 存储会同时写入 refresh token |
+| `apiClient.auth.clear()` | 清理 Token |
+| `apiClient.auth.onTokenRefreshed(cb)` | 监听刷新结果 |
+| `apiClient.create(contract)` | 创建自定义 typed client |
+| `apiClient.tokenStorage.{memory,localStorage,httpOnlyCookie}()` | TokenStorage 工厂 |
+
+### Transport 配置
+
+| 字段 | 说明 |
+| --- | --- |
+| `transport.crypto` | 已初始化的 `@h-ai/crypto` 实例 |
+| `transport.keyExchangePath` | 相对于 `baseUrl` 的协商子路径，默认 `/_hai/key-exchange` |
+
+服务端必须对应启用 `serv.createApp({ transport: { crypto } })`。
+自动刷新会沿用 `transport.encryptedFetch`，并在 httpOnly cookie 模式下发送空请求体 + `credentials: 'include'`，由服务端从 cookie 读取 refresh token。
+
+## 常见模式
+
+- `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 中刷新自己的用户状态或导航。