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

package/templates/apps/website/src/routes/services/+page.svelte.hbs

@@ -31,7 +31,7 @@
 {{/if}}
 </svelte:head>
 
-<section class='py-16 px-4 max-w-4xl mx-auto'>
+<section class='mx-auto w-full max-w-[120rem] px-4 py-16 sm:px-6 lg:px-8'>
 {{#if hasI18n}}
   <PageHeader title={m.page_services_title()} description={m.page_services_desc()} />
 {{else}}

package/templates/base/.dockerignore.hbs

@@ -1,19 +1,25 @@
-.git
+**/.git
+**/node_modules
+**/.pnpm-store
+**/.cache
+**/.svelte-kit
+**/.turbo
+**/build
+**/dist
+**/coverage
+**/playwright-report
+**/test-results
+**/src-tauri/target
+**/hash-core/target
+tmp
 **/*.tar
 .github
 .agents
 .claude
 .codex
 .opencode
-.svelte-kit
-.turbo
 android
-build
-dist
 ios
-node_modules
-playwright-report
-test-results
 **/data
 *.log
 # 仅保留公共基础 .env；分环境配置、私有覆盖及已有交付包不进入构建上下文。

package/templates/base/.gitignore.hbs

@@ -32,3 +32,10 @@ playwright-report/
 # 本机私有配置；公共 .env 与 dev/test/prod 环境文件纳入版本控制。
 .env.local
 .env.*.local
+
+# 构建器生成的安装输入快照
+**/images/dependencies/
+
+# 项目本地缓存
+**/.pnpm-store/
+**/.cache/

package/templates/base/e2e/app.spec.ts.hbs

@@ -23,6 +23,16 @@ test('home page renders from browser', async ({ page }) => {
   await expect(page.locator('main, section').first()).toBeVisible()
   await expect(page.locator('header').first()).toBeVisible()
   await expect(page.locator('footer').first()).toBeAttached()
+  // 大屏使用可用空间，窄屏由组件内部滚动，不能撑宽整个页面。
+  for (const width of [390, 1440, 1920, 2560, 3840]) {
+    await page.setViewportSize({ width, height: 960 })
+    const availableWidth = await page.evaluate(() => document.documentElement.clientWidth)
+    expect(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth)).toBe(true)
+    const shell = page.locator('.hai-mobile-shell')
+    if (await shell.count())
+      expect((await shell.boundingBox())!.width).toBeGreaterThan(availableWidth - 2)
+  }
+  await page.setViewportSize({ width: 390, height: 844 })
 {{#if_eq appType 'h5'}}
   // 在手机宽度验证导航真正切换路由，避免样式失效但首页渲染测试仍通过。
   const nav = page.locator('nav')

package/templates/base/hai.build.json.hbs

@@ -1 +1 @@
-{ "images": [{ "name": "app", "target": "runtime", "containerPort": {{#if isSvelteOnlyApp}}8080{{else}}3000{{/if}} }] }
+{ "images": [{ "name": "app", "dockerfile": "images/app.Dockerfile", "containerPort": {{#if isSvelteOnlyApp}}8080{{else}}3000{{/if}} }] }

package/templates/base/{Dockerfile.hbs → images/app.Dockerfile.hbs}

@@ -1,48 +1,51 @@
-# syntax=docker/dockerfile:1.7
 {{#if isSvelteOnlyApp}}
-FROM node:24-bookworm-slim AS build
-ARG SQLITE_PREBUILD_MIRROR
-ENV npm_config_better_sqlite3_binary_host_mirror=$SQLITE_PREBUILD_MIRROR
+FROM node:24.22.1-bookworm-slim AS build
 
 ENV PNPM_HOME=/pnpm
 ENV PATH=$PNPM_HOME:$PATH
 ENV CI=true
+ENV ONNXRUNTIME_NODE_INSTALL_CUDA=skip
 WORKDIR /workspace
 
-RUN corepack enable && corepack prepare pnpm@12.11.2 --activate
+RUN corepack enable && corepack prepare pnpm@12.11.2 --activate && pnpm config set store-dir /pnpm/store
+COPY pnpm-lock.yaml pnpm-workspace.yaml ./
+COPY images/dependencies/ ./
+RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store pnpm fetch --ignore-scripts
 COPY . .
-RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store pnpm fetch
 RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store pnpm install --offline --frozen-lockfile --ignore-scripts
 RUN pnpm compile
 
-FROM nginxinc/nginx-unprivileged:1.29-alpine AS runtime
+FROM nginxinc/nginx-unprivileged:1.29.8-alpine AS runtime
 
-COPY --chmod=755 docker/19-runtime-config.sh /docker-entrypoint.d/19-hai-runtime-config.sh
-COPY docker/nginx.conf /etc/nginx/conf.d/default.conf
+COPY --chmod=755 images/web/19-runtime-config.sh /docker-entrypoint.d/19-hai-runtime-config.sh
+COPY images/web/nginx.conf /etc/nginx/conf.d/default.conf
 COPY --from=build /workspace/dist /usr/share/nginx/html
 
 EXPOSE 8080
 HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
   CMD wget -q -O /dev/null http://127.0.0.1:8080/health || exit 1
 {{else}}
-FROM node:24-bookworm-slim AS build
-ARG SQLITE_PREBUILD_MIRROR
+FROM node:24.22.1-bookworm-slim AS build
+ARG SQLITE_PREBUILD_MIRROR=
 ENV npm_config_better_sqlite3_binary_host_mirror=$SQLITE_PREBUILD_MIRROR
 
 ENV PNPM_HOME=/pnpm
 ENV PATH=$PNPM_HOME:$PATH
 ENV CI=true
+ENV ONNXRUNTIME_NODE_INSTALL_CUDA=skip
 WORKDIR /workspace
 
-RUN corepack enable && corepack prepare pnpm@12.11.2 --activate
+RUN corepack enable && corepack prepare pnpm@12.11.2 --activate && pnpm config set store-dir /pnpm/store
+COPY pnpm-lock.yaml pnpm-workspace.yaml ./
+COPY images/dependencies/ ./
+RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store pnpm fetch --ignore-scripts
 COPY . .
-RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store pnpm fetch
 RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store pnpm install --offline --frozen-lockfile --ignore-scripts
 RUN pnpm compile
-RUN if [ -d node_modules/better-sqlite3 ]; then cd node_modules/better-sqlite3; for attempt in 1 2 3; do node -e "require('node:child_process').execFileSync(process.execPath,[require.resolve('prebuild-install/bin.js'),'--verbose'],{stdio:'inherit'})" && break; [ "$attempt" = 3 ] && exit 1; sleep 3; done; fi
-RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store pnpm pm deploy --filter {{projectName}} --prod /prod/app
+RUN --mount=type=cache,id={{projectName}}-sqlite,target=/root/.npm/_prebuilds if [ -d node_modules/better-sqlite3 ]; then cd node_modules/better-sqlite3; for attempt in 1 2 3; do node -e "require('node:child_process').execFileSync(process.execPath,[require.resolve('prebuild-install/bin.js'),'--verbose'],{stdio:'inherit'})" && break; [ "$attempt" = 3 ] && exit 1; sleep 3; done; fi
+RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store --mount=type=cache,id={{projectName}}-sqlite,target=/root/.npm/_prebuilds pnpm pm deploy --filter {{projectName}} --prod /prod/app
 
-FROM node:24-bookworm-slim AS runtime-base
+FROM node:24.22.1-bookworm-slim AS runtime-base
 
 ENV NODE_ENV=production
 ENV HOST=0.0.0.0
@@ -58,5 +61,4 @@ HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
   CMD node -e "fetch('http://127.0.0.1:'+process.env.PORT+'/').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
 CMD ["node", "build"]
 
-FROM runtime-base AS runtime
 {{/if}}

package/templates/base/package.json.hbs

@@ -1,7 +1,7 @@
 {
   "engines": { "node": "^22.22.2 || ^24.15.0 || >=26.0.0" },
   "name": "{{projectName}}",
-  "version": "0.1.0-alpha.66",
+  "version": "0.1.0-alpha.67",
   "private": true,
   "packageManager": "pnpm@12.11.2",
   "description": "{{#if_eq appType 'admin'}}Enterprise management system built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'website'}}Enterprise website built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'h5'}}Mobile H5 app built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'api'}}REST API service built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'mobile-app'}}Mobile app built with hai Agent Framework{{/if_eq}}",
@@ -25,7 +25,9 @@
     "dev:prod": "vite dev --mode prod",
     "compile": "{{#if hasI18n}}pnpm paraglide:compile && {{/if}}vite build",
     "build": "hai build",
+{{#if features.deploy}}
     "deploy": "hai deploy",
+{{/if}}
 {{#unless isSvelteOnlyApp}}
     "start": "node --env-file=.env --env-file=.env.prod --env-file-if-exists=.env.local build/index.js",
     "start:test": "node --env-file=.env --env-file=.env.test --env-file-if-exists=.env.local build/index.js",
@@ -73,16 +75,19 @@
     "@h-ai/payment": "{{haiPackageSpecifier}}"{{/if}}{{#if features.vecdb}},
     "@h-ai/vecdb": "{{haiPackageSpecifier}}"{{/if}}{{#if features.datapipe}},
     "@h-ai/datapipe": "{{haiPackageSpecifier}}"{{/if}}{{#if features.scheduler}},
-    "@h-ai/scheduler": "{{haiPackageSpecifier}}"{{/if}}{{#if features.deploy}},
-    "@h-ai/deploy": "{{haiPackageSpecifier}}"{{/if}}{{#if features.api-client}},
+    "@h-ai/scheduler": "{{haiPackageSpecifier}}"{{/if}}{{#if features.api-client}},
     "@h-ai/api-client": "{{haiPackageSpecifier}}"{{/if}}{{#if features.capacitor}},
     "@h-ai/capacitor": "{{haiPackageSpecifier}}"{{/if}}{{#if isCapacitorApp}}{{#unless features.api-client}},
     "@h-ai/api-client": "{{haiPackageSpecifier}}"{{/unless}}{{#unless features.capacitor}},
     "@h-ai/capacitor": "{{haiPackageSpecifier}}"{{/unless}}{{/if}},
+    "sm-crypto": "0.5.7",
     "zod": "{{versions.zod}}"
 {{/if}}
   },
   "devDependencies": {
+{{#if features.deploy}}
+    "@h-ai/deploy": "{{haiPackageSpecifier}}",
+{{/if}}
     "@h-ai/cli": "{{haiPackageSpecifier}}",
 {{#if isSvelteOnlyApp}}
     "@h-ai/core": "{{haiPackageSpecifier}}",

package/templates/base/vite.config.ts.hbs

@@ -80,7 +80,9 @@ export default defineConfig(({ mode, command }) => {
 {{/if}}
 {{#unless isSvelteOnlyApp}}
     ssr: {
-      noExternal: [/@h-ai\//],
+      noExternal: ['@h-ai/ui', '@h-ai/kit'],
+      // sm-crypto 同时列入生产依赖，避免 adapter-node 再次打包其动态 require。
+      external: ['@h-ai/core', 'sm-crypto'],
     },
 {{/unless}}
     server: {

package/templates/shared/.gitattributes

@@ -3,3 +3,9 @@
 *.sh.hbs text eol=lf
 *.envsh text eol=lf
 *.envsh.hbs text eol=lf
+
+# Linux 容器引擎读取忽略规则和构建文件时统一使用 LF。
+.dockerignore text eol=lf
+*.dockerignore text eol=lf
+Dockerfile text eol=lf
+*.Dockerfile text eol=lf

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#配置驱动认证页面)