@h-ai/cli 1.0.0-beta.6 → 1.0.0-beta.8

package/dist/{src-NXCCU6GO.js → src-IW4CY2IN.js}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-export { DEPLOY_MIDDLEWARE, DeployConfigSchema, DeploymentArtifactSchema, HaiDeployError, ProviderConfigSchema, artifactChecksum, canKeepMiddleware, createDeploymentPlan, deploy, describeMiddlewareBackend, getDeployCommandState, getDeployRecovery, importDeploymentSecrets, loadDeploymentConfig, loadDeploymentEnvironment, mergeEnvironmentLayers, normalizeProjectName, parseMiddlewareField, readDeploymentArtifact, resolveDownloadProxy, resolveImageReference, saveDeploymentEnvironment, saveMiddlewareEnvironment, validateMiddlewareField } from './chunk-4XVCGFBA.js';
+export { DEPLOY_MIDDLEWARE, DeployConfigSchema, DeploymentArtifactSchema, HaiDeployError, ProviderConfigSchema, artifactChecksum, canKeepMiddleware, createDeploymentPlan, deploy, describeMiddlewareBackend, getDeployCommandState, getDeployRecovery, importDeploymentSecrets, loadDeploymentConfig, loadDeploymentEnvironment, mergeEnvironmentLayers, normalizeProjectName, parseMiddlewareField, readDeploymentArtifact, resolveDownloadProxy, resolveImageReference, saveDeploymentEnvironment, saveMiddlewareEnvironment, validateMiddlewareField } from './chunk-MEEFB4BI.js';
 import './chunk-ZSDEVXZ7.js';
-//# sourceMappingURL=src-NXCCU6GO.js.map
-//# sourceMappingURL=src-NXCCU6GO.js.map
+//# sourceMappingURL=src-IW4CY2IN.js.map
+//# sourceMappingURL=src-IW4CY2IN.js.map

package/dist/src-IW4CY2IN.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"src-IW4CY2IN.js"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/cli",
   "type": "module",
-  "version": "1.0.0-beta.6",
+  "version": "1.0.0-beta.8",
   "description": "Hai Framework CLI for project scaffolding and code generation.",
   "license": "Apache-2.0",
   "keywords": [
@@ -30,7 +30,7 @@
     "node": "^22.23.4 || ^24.22.1 || ^26.12.1"
   },
   "dependencies": {
-    "@h-ai/core": "1.0.0-beta.6",
+    "@h-ai/core": "1.0.0-beta.8",
     "cac": "^7.0.1",
     "chalk": "^6.0.1",
     "fast-wrap-ansi": "^0.2.2",
@@ -41,15 +41,18 @@
     "yaml": "^2.9.1"
   },
   "devDependencies": {
-    "@h-ai/api-client": "1.0.0-beta.6",
-    "@h-ai/cache": "1.0.0-beta.6",
-    "@h-ai/crypto": "1.0.0-beta.6",
-    "@h-ai/deploy": "1.0.0-beta.6",
-    "@h-ai/feedback": "1.0.0-beta.6",
-    "@h-ai/iam": "1.0.0-beta.6",
-    "@h-ai/reach": "1.0.0-beta.6",
-    "@h-ai/reldb": "1.0.0-beta.6",
-    "@h-ai/storage": "1.0.0-beta.6",
+    "@h-ai/api-client": "1.0.0-beta.8",
+    "@h-ai/cache": "1.0.0-beta.8",
+    "@h-ai/crypto": "1.0.0-beta.8",
+    "@h-ai/deploy": "1.0.0-beta.8",
+    "@h-ai/feedback": "1.0.0-beta.8",
+    "@h-ai/iam": "1.0.0-beta.8",
+    "@h-ai/kit": "1.0.0-beta.8",
+    "@h-ai/payment": "1.0.0-beta.8",
+    "@h-ai/reach": "1.0.0-beta.8",
+    "@h-ai/reldb": "1.0.0-beta.8",
+    "@h-ai/storage": "1.0.0-beta.8",
+    "@h-ai/vecdb": "1.0.0-beta.8",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^26.6.5",
     "@types/prompts": "^2.4.9",
@@ -59,7 +62,8 @@
     "testcontainers": "^12.2.0",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.11"
+    "vitest": "^4.1.11",
+    "zod": "^4.6.5"
   },
   "scripts": {
     "build": "tsup",

package/templates/apps/api/apps/{{projectName}}-serv/config/_serv.yml.hbs

@@ -33,7 +33,7 @@ http:
 
 cors:
   origin: ${HAI_SERV_CORS_ORIGIN:*}
-  nativeOrigins: ${HAI_SERV_CORS_NATIVEORIGINS:http://localhost,https://tauri.localhost,tauri://localhost,capacitor://localhost}
+  nativeOrigins: ${HAI_SERV_CORS_NATIVEORIGINS:http://localhost,https://localhost,http://tauri.localhost,https://tauri.localhost,tauri://localhost,capacitor://localhost}
 {{#if features.iam}}  credentials: ${HAI_SERV_CORS_CREDENTIALS:true}
 {{else}}  credentials: ${HAI_SERV_CORS_CREDENTIALS:false}
 {{/if}}  allowedHeaders:

package/templates/apps/api/apps/{{projectName}}-serv/src/app.ts.hbs

@@ -68,7 +68,11 @@ export function {{api.serviceAppFactoryName}}(_options: CreateApiServiceAppOptio
 {{else}}  const transport = undefined
 {{/if}}
 {{#if features.iam}}
-  const refreshCookie = _options.refreshCookie === 'disabled' ? undefined : { secure: security.secureRefreshCookie }
+  const refreshCookie = _options.refreshCookie === 'disabled'
+    ? undefined
+    : { secure: security.secureRefreshCookie, nativeTokenTransport: { isRequest: (request: Request) => request.headers.get('x-hai-token-transport') === 'body'
+      && ['hai-mobile-app', 'hai-desktop-app'].includes(request.headers.get('x-request-client') ?? '')
+      && security.isNativeOrigin(request.headers.get('origin') ?? '') } }
 {{/if}}
 {{#if features.feedback}}
   // 普通业务日志与反馈使用同一可信应用范围；身份仍由 IAM 验证。
@@ -113,7 +117,7 @@ export function {{api.serviceAppFactoryName}}(_options: CreateApiServiceAppOptio
         middleware: serv.cors({
           origin: security.allowOrigin,
           credentials: servConfig.cors.credentials,
-          allowedHeaders: [...servConfig.cors.allowedHeaders],
+          allowedHeaders: [...new Set([...servConfig.cors.allowedHeaders, 'x-request-client', 'x-hai-token-transport'])],
           exposedHeaders: [...servConfig.cors.exposedHeaders],
         }),
       },

package/templates/apps/api/apps/{{projectName}}-serv/tests/service.test.ts.hbs

@@ -14,7 +14,7 @@ import { join } from 'node:path'
 {{#if features.storage}}import { storage } from '@h-ai/storage'
 {{/if}}{{#if features.vecdb}}import { vecdb } from '@h-ai/vecdb'
 {{/if}}import { {{api.contractExportName}} } from '{{api.contractPackageName}}'
-import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest'
 
 import { {{api.serviceAppFactoryName}} } from '../src/app.js'
 
@@ -44,6 +44,7 @@ beforeAll(async () => {
 {{/if}}{{#if features.vecdb}}  vecdbRoot = join(tempRoot, 'vecdb')
 {{/if}}
 
+  vi.stubEnv('HAI_SERV_CORS_NATIVEORIGINS', undefined)
   core.init({
     configDir: './config',
     logging: { level: 'warn' },
@@ -82,8 +83,7 @@ beforeAll(async () => {
 {{/if}}
 
   const app = {{api.serviceAppFactoryName}}({
-    transport: 'disabled',{{#if features.iam}}
-    refreshCookie: 'disabled',{{/if}}
+    transport: 'disabled',
   })
   const listening = new Promise<AddressInfo>((resolve) => {
     server = serv.listen(app, {
@@ -98,6 +98,8 @@ beforeAll(async () => {
   client = apiClient.create({{api.contractExportName}})
   const initResult = await client.init({
     baseUrl: `${baseUrl}${servConfig.http.apiPrefix}`,
+    clientName: 'hai-mobile-app',
+    headers: { 'origin': 'capacitor://localhost', 'x-hai-token-transport': 'body' },
     auth: { storage: apiClient.tokenStorage.memory() },
   })
   if (!initResult.success)
@@ -114,6 +116,7 @@ afterAll(async () => {
 {{/if}}{{#if features.cache}}  await cache.close()
 {{/if}}{{#if features.db}}  await reldb.close()
 {{/if}}  rmSync(tempRoot, { recursive: true, force: true })
+  vi.unstubAllEnvs()
 })
 
 describe('{{api.servPackageName}}', () => {
@@ -144,6 +147,29 @@ describe('{{api.servPackageName}}', () => {
   })
 
 {{#if features.iam}}
+  it.each([
+    ['capacitor://localhost', 'hai-mobile-app'],
+    ['https://localhost', 'hai-mobile-app'],
+    ['http://tauri.localhost', 'hai-desktop-app'],
+    ['https://tauri.localhost', 'hai-desktop-app'],
+    ['tauri://localhost', 'hai-desktop-app'],
+  ])('refreshes an expired access token at the default native Origin %s', async (origin, clientName) => {
+    const native = apiClient.create({{api.contractExportName}})
+    try {
+      expect((await native.init({ baseUrl: `${baseUrl}${servConfig.http.apiPrefix}`, clientName, headers: { 'origin': origin, 'x-hai-token-transport': 'body' }, auth: { storage: apiClient.tokenStorage.memory() } })).success).toBe(true)
+      const registration = await apiClient.createAuthActions(native).register(uniqueUser('refresh'))
+      expect(registration.success).toBe(true)
+      if (!registration.success)
+        return
+      expect(registration.data.tokens.refreshToken).toBeTruthy()
+      await native.auth.setTokens({ ...registration.data.tokens, accessToken: 'expired-access-for-test' })
+      expect((await native.iam.auth.currentUser()).success).toBe(true)
+    }
+    finally {
+      await native.close()
+    }
+  })
+
   it('registers a user and returns authenticated echo context', async () => {
     const user = uniqueUser('svc')
     const authActions = apiClient.createAuthActions(client)

package/templates/apps/fullstack/.gitignore.hbs

@@ -3,8 +3,13 @@ node_modules
 build
 dist
 .turbo
-android
-ios
+**/android/.gradle/
+**/android/**/build/
+**/ios/Pods/
+**/ios/App/Pods/
+*.keystore
+*.jks
+*.p12
 **/src/lib/paraglide
 **/src-tauri/gen/
 **/src-tauri/target/

package/templates/apps/fullstack/apps/{{projectName}}-app/README.md.hbs

@@ -4,6 +4,8 @@
 
 ## 简介
 
+`android` / `ios` 是需要维护的原生工程，应提交 Git；签名秘密单独忽略。普通 `clean` 保留这些目录，只清除构建产物。
+
 App/H5 前端工程，复用 shared 的响应式 mini 后台，使用 Svelte 5 + Vite + Capacitor，可输出 Web 预览并同步 Android / iOS 原生工程。
 
 ## 核心功能清单

package/templates/apps/fullstack/apps/{{projectName}}-app/package.json.hbs

@@ -23,7 +23,7 @@
     "lint:fix": "eslint . --fix",
     "test": "pnpm paraglide:compile && vitest run --passWithNoTests",
     "test:watch": "pnpm paraglide:compile && vitest",
-    "clean": "rimraf dist build android ios .turbo src/lib/paraglide",
+    "clean": "rimraf dist build .turbo src/lib/paraglide",
     "cap:add:android": "cap add android",
     "cap:add:ios": "cap add ios",
     "cap:sync": "pnpm build && cap sync",

package/templates/apps/fullstack/packages/{{projectName}}-serv/README.md.hbs

@@ -19,9 +19,9 @@
 - `config/_core.yml`：应用元信息（名称 / 版本 / 环境 / 语言），启动时由 `core.config` 加载。
 - `config/_serv.yml`：服务端运行时设置（CORS 来源等）。
 - `config/_db.yml` / `_cache.yml` / `_iam.yml` / `_storage.yml` / `_audit.yml` / `_reach.yml`：管理及开发通知配置，初始化前使用模块公开 Schema 验证。Reach 默认控制台 Provider，生产按注释替换为 SMTP/短信/API。
-- `config/_ai.yml` / `_vecdb.yml` / `_payment.yml` / `_scheduler.yml`：保留未启用模块的完整注释示例；配置文件存在不代表模块已接入。先在本 workspace 安装对应依赖，再在 `src/server/runtime.ts` 按公开 Schema 校验、初始化并反序关闭，接入实际业务后按需取消注释。整份注释先去掉一层外层注释，可选字段继续按需开启。
+- `config/_ai.yml` / `_vecdb.yml` / `_payment.yml` / `_kit.yml`：保留未启用模块的完整注释示例；配置文件存在不代表模块已接入。先在本 workspace 安装对应依赖，再在 `src/server/runtime.ts` 按公开 Schema 校验、初始化并反序关闭，接入实际业务后按需取消注释。整份注释先去掉一层外层注释，可选字段继续按需开启。scheduler 已用于审计任务，配置位于 `_scheduler.yml`。
 - `src/index.ts`：进程入口，通过 `src/server/runtime.ts` 先向 Core 注册各模块公开 Schema 并加载配置，再初始化 reldb → cache → crypto → storage → reach（有配置时）→ audit → iam → scheduler（有任务时）；YAML 未声明的合法可选字段同样支持细项环境变量，启动失败及退出反序释放。
-- 选择 AI 时自动安装 reldb/vecdb/AI，并在 reldb/cache 之后初始化 vecdb、在其余依赖之后初始化 AI；关闭时先释放 AI，最后释放 vecdb/关系库，关闭失败会返回错误并保留重试义务。生产环境必须使用共享后端，根 `.env.prod` 默认连接 Compose `db/cache/storage/vecdb`，凭据和真实 Reach Provider JSON 私有注入。
+- 默认不安装 AI、vecdb、payment 和 datapipe。后续接入 AI 时安装对应依赖，在 reldb/cache 之后初始化 vecdb、在其余依赖之后初始化 AI；关闭时先释放 AI，最后释放 vecdb/关系库。生产环境必须使用共享后端，根 `.env.prod` 默认连接 Compose `db/cache/storage`，新增 vecdb 后补充共享向量库配置；凭据和真实 Reach Provider JSON 私有注入。
 - `src/app-server.ts`：服务装配入口，挂载健康检查、OpenAPI、docs 与 procedures；应用名称 / 版本与 CORS 来源均取自上述配置。
 - `src/server/procedures/app-procedures.ts`：app 领域 procedures，对应 contract 中的 `app.info` / `app.echo` 路由。
 - `src/server/procedures/admin-procedures.ts`：认证、管理员用户/角色/审计管理和个人设置，使用 `.auth()` / `.permission(...)` 守卫。每个请求读取用户最新启用状态、角色和权限。

package/templates/apps/mobile-app/messages/en-US.json

@@ -24,7 +24,7 @@
   "status_runtime_web": "Browser preview",
   "status_token_label": "Token storage",
   "status_token_native": "Secure storage",
-  "status_token_memory": "Memory storage",
+  "status_token_memory": "Memory access token + httpOnly cookie",
   "tasks_title": "Today's tasks",
   "tasks_sync": "Wire backend APIs",
   "tasks_polish": "Polish mobile UX",

package/templates/apps/mobile-app/messages/ja-JP.json

@@ -24,7 +24,7 @@
   "status_runtime_web": "ブラウザープレビュー",
   "status_token_label": "トークン保存",
   "status_token_native": "安全なストレージ",
-  "status_token_memory": "メモリー内保存",
+  "status_token_memory": "メモリー内access token + httpOnly Cookie",
   "tasks_title": "本日のタスク",
   "tasks_sync": "バックエンドAPIを接続",
   "tasks_polish": "モバイルUXを改善",

package/templates/apps/mobile-app/messages/zh-CN.json

@@ -24,7 +24,7 @@
   "status_runtime_web": "浏览器预览",
   "status_token_label": "Token 存储",
   "status_token_native": "安全存储",
-  "status_token_memory": "内存存储",
+  "status_token_memory": "内存 access token + httpOnly Cookie",
   "tasks_title": "今日任务",
   "tasks_sync": "同步后端接口",
   "tasks_polish": "打磨移动端体验",

package/templates/apps/mobile-app/src/lib/api.ts.hbs

@@ -1,6 +1,6 @@
 /**
  * {{projectName}} — API 客户端初始化。
- * Web 预览仅使用内存 TokenStore；原生端使用 Capacitor 安全存储。
+ * Web 预览使用内存 access token + httpOnly refresh Cookie；原生端使用 Capacitor 安全存储。
  * 原生存储失败会拒绝 Promise；登录/退出调用方须处理 auth.setTokens/clear 失败并释放界面 loading。
  */
 import { apiClient } from '@h-ai/api-client'
@@ -56,7 +56,7 @@ export function resolveApiBase(): string {
 }
 
 /**
- * 查询实际 Capacitor 平台，决定安全原生存储或 Web 内存存储。
+ * 查询实际 Capacitor 平台，决定安全原生存储或 Web Cookie 刷新通道。
  * @returns 是否处于 Capacitor 原生平台；浏览器预览返回 false。
  * @throws Error - 平台模块加载或检测失败时拒绝 Promise，不伪装为 Web 模式。
  * @example 模块内部上下文
@@ -74,7 +74,7 @@ export async function usesNativeTokenStorage(): Promise<boolean> {
 
 /**
  * 按真实平台创建 TokenStorage；绑定 client 后通过 client.auth 变更身份。
- * @returns 原生安全存储或 Web 内存存储；其方法的读写故障继续拒绝 Promise。
+ * @returns 原生安全存储或内存 access token + httpOnly refresh Cookie；其方法的读写故障继续拒绝 Promise。
  * @throws Error - 平台检测或存储工厂失败时拒绝，不改用较弱的持久化方式。
  * @example 模块内部上下文
  * ```ts
@@ -86,7 +86,7 @@ async function createTokenStorage() {
   if (await usesNativeTokenStorage())
     return createCapacitorTokenStorage()
 
-  return apiClient.tokenStorage.memory()
+  return apiClient.tokenStorage.httpOnlyCookie()
 }
 
 /**
@@ -137,6 +137,7 @@ export async function initApi(): Promise<void> {
  * ```
  */
 async function initialize(): Promise<void> {
+  const native = await usesNativeTokenStorage()
   const storage = await createTokenStorage()
 {{#if features.crypto}}
   const transport = resolveTransport()
@@ -149,6 +150,8 @@ async function initialize(): Promise<void> {
     }
     const result = await apiClient.init({
       baseUrl: resolveApiBase(),
+      clientName: 'hai-mobile-app',
+      headers: native ? { 'x-hai-token-transport': 'body' } : {},
       auth: { storage },
       ...(transport ? { transport } : {}),
     })
@@ -169,7 +172,7 @@ async function initialize(): Promise<void> {
     throw error
   }
 {{else}}
-  const result = await apiClient.init({ baseUrl: resolveApiBase(), auth: { storage } })
+  const result = await apiClient.init({ baseUrl: resolveApiBase(), clientName: 'hai-mobile-app', headers: native ? { 'x-hai-token-transport': 'body' } : {}, auth: { storage } })
   if (!result.success)
     throw new Error(result.error.message)
   initialized = true

package/templates/base/.gitignore.hbs

@@ -6,8 +6,13 @@ node_modules
 build
 dist
 .turbo
-android
-ios
+android/.gradle/
+android/**/build/
+ios/Pods/
+ios/App/Pods/
+*.keystore
+*.jks
+*.p12
 **/src/lib/paraglide
 **/src-tauri/gen/
 **/src-tauri/target/

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

@@ -120,12 +120,16 @@ test('configured IAM registration and password login', async ({ page, context })
   await registerForm.locator('#register-confirm-password').fill(password)
   await registerForm.locator('button[type="submit"]').click()
   await expect(page.locator('.register-form')).not.toBeVisible()
-{{#unless isCapacitorApp}}
+{{#if isCapacitorApp}}
+  // 浏览器预览通过刷新 Cookie 恢复会话，不能把页面重载当作退出。
+  await page.reload()
+  await expect(page.getByRole('navigation')).toBeVisible()
+{{else}}
   // 通过页面 fetch 复用 Cookie 与已安装的传输加密，避免 HTTP 辅助客户端绕过浏览器协议。
   const me = await page.evaluate(async url => (await fetch(url)).status, new URL('./api/auth/me', test.info().project.use.baseURL).href)
   expect(me).toBe(200)
+{{/if}}
   await context.clearCookies()
-{{/unless}}
   await page.reload()
   await page.goto(authUrl)
   await expect(page.locator('#login-username')).toBeVisible()
@@ -204,8 +208,9 @@ test('configured IAM registration and password login', async ({ page, context })
   expect(new URL(page.url()).searchParams.has('token')).toBe(false)
   await page.reload()
 {{#if isCapacitorApp}}
-  // Web 预览采用内存 TokenStore，刷新后应回到登录，而不是已消费令牌的重置页面。
-  await expect(page.locator('#login-username')).toBeVisible()
+  // 已消费的重置令牌不再参与启动；刷新 Cookie 恢复同一已登录会话。
+  await expect(page.getByRole('navigation')).toBeVisible()
+  await expect(page.locator('#login-username')).not.toBeVisible()
 {{else}}
   expect(await page.evaluate(async url => (await fetch(url)).status, new URL('./api/auth/me', test.info().project.use.baseURL).href)).toBe(200)
 {{/if}}

package/templates/base/package.json.hbs

@@ -1,7 +1,7 @@
 {
   "engines": { "node": "^22.23.4 || ^24.22.1 || ^26.12.1" },
   "name": "{{projectName}}",
-  "version": "1.0.0-beta.6",
+  "version": "1.0.0-beta.8",
   "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}}",
@@ -41,7 +41,7 @@
     "test": "{{#if hasI18n}}pnpm paraglide:compile && {{/if}}vitest run",
     "test:watch": "vitest",
     "test:e2e": "node scripts/run-e2e.mjs",
-    "clean": "{{#if isSvelteOnlyApp}}rimraf dist build android ios .turbo src/lib/paraglide{{else}}rimraf .svelte-kit build .turbo{{/if}}"{{#if isCapacitorApp}},
+    "clean": "{{#if isSvelteOnlyApp}}rimraf dist build .turbo src/lib/paraglide{{else}}rimraf .svelte-kit build .turbo{{/if}}"{{#if isCapacitorApp}},
     "cap:add:android": "cap add android",
     "cap:add:ios": "cap add ios",
     "cap:sync": "pnpm compile && cap sync",
@@ -56,7 +56,9 @@
     "cap:build:ios": "pnpm compile && cap sync ios && cap build ios"{{/if}}
   },
   "dependencies": {
+{{#unless isSvelteOnlyApp}}
     "pino-pretty": "{{versions.pinoPretty}}",
+{{/unless}}
   {{#if isSvelteOnlyApp}}
     "@h-ai/api-client": "{{haiPackageSpecifier}}",
     "@h-ai/capacitor": "{{haiPackageSpecifier}}",
@@ -96,6 +98,9 @@
     "@h-ai/cli": "{{haiPackageSpecifier}}",
 {{#if isSvelteOnlyApp}}
     "@h-ai/core": "{{haiPackageSpecifier}}",
+{{#if features.iam}}
+    "@h-ai/api-contract": "{{haiPackageSpecifier}}",
+{{/if}}
 {{/if}}
     "@antfu/eslint-config": "{{versions.antfuEslintConfig}}",
     "@playwright/test": "{{versions.playwright}}",

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

@@ -1,6 +1,6 @@
 ---
 name: hai-ai
-description: "接入 @h-ai/ai 的 LLM、工具/MCP、RAG、会话记忆、图像、语音及 A2A。"
+description: "接入 @h-ai/ai 的 LLM、工具/MCP、RAG、会话记忆、图像、语音、A2A 及 ACP。"
 ---
 
 # hai-ai
@@ -9,7 +9,7 @@ description: "接入 @h-ai/ai 的 LLM、工具/MCP、RAG、会话记忆、图像
 
 | 项目 | 契约 |
 | --- | --- |
-| 能力 | 接入 @h-ai/ai 的 LLM、工具/MCP、RAG、会话记忆、图像、语音及 A2A |
+| 能力 | 接入 @h-ai/ai 的 LLM、工具/MCP、RAG、会话记忆、图像、语音、A2A 及 ACP |
 | 适用场景 | AI 应用服务端集成或浏览器代理接入 |
 | 输入 | AIConfigInput、消息/音频/图片、scope、AbortSignal |
 | 输出 | 领域操作为 HaiResult；流为 AsyncIterable，迭代可抛错 |
@@ -26,6 +26,8 @@ description: "接入 @h-ai/ai 的 LLM、工具/MCP、RAG、会话记忆、图像
 
 ## 按需参考
 
+智能体接入、工程/worktree、容器和 Git 发布见 [ACP 接入指南](acp.md)。
+
 详细配置、API 签名、错误码和范本在 [guide.md](guide.md)。按下列标题定位所需小节，不默认通读；用例中的业务变量需结合当前应用补齐。
 
 - 使用边界
@@ -48,3 +50,5 @@ description: "接入 @h-ai/ai 的 LLM、工具/MCP、RAG、会话记忆、图像
 公开 API 示例以安装包的实际入口为准；框架源码中的内部工厂例子仅供模块维护。HaiResult 调用先检查 success，流与浏览器 AudioClient 按显式抛错契约处理；Context flush 失败和 A2A 未知外部效果不得盲目重放。
 
 Node 自定义 SSE 使用 ai.stream 的统一编解码，不用 split/trim 手拆上游事件；encoder 的非法元数据会显式抛错。Anthropic/MiMo 的真实 HTTP 流在退出和取消时释放正文，EOF 不伪造未完成事件，不自动重连或重放业务。
+
+资源目录维护见 [配置与数据库资源清单](resources.md)：配置只读、数据库 CRUD、来源与版本、LLM/音频/图像/MCP/检索源/ACP。

package/templates/skills/hai-ai/acp.md

@@ -0,0 +1,145 @@
+# ACP 智能体、工作区和会话
+
+ACP 把宿主应用接到能操作工程的智能体。`ai.llm` 负责模型调用，`ai.acp` 负责智能体进程、协议、工程目录和会话；SDD、代码评审规则、预览页面、验收和业务部署仍由应用实现。仅在 Node 服务端使用，浏览器经应用自己鉴权的 API 接收事件。
+
+## 选择接入方式
+
+| mode | 用途 | 模型和文件 |
+| --- | --- | --- |
+| `embedded` | 启动本机安装的原生 ACP 程序 | 引用 Hai `llm.models`；使用 directory 工作区 |
+| `builtin-service` | 使用已构建镜像启动专属容器 | 引用 Hai 模型；workspace volume 挂 `/workspace`，状态卷挂 `/state` |
+| `custom-service` | 已有原生 HTTP/WS ACP 服务 | 远端自行维护模型；传远端可见的 cwd；框架不操作远端 Git |
+
+Codex 用 `adapter: 'codex'`，DeepSeek Harness 用 `adapter: 'deepseek-harness'`，其他已配置模型的 ACP 程序用 `adapter: 'generic'` 和 `command/args`。需生成其他原生配置时，向 `ai.init(config, { acpAdapters })` 提供可信服务端适配器；适配器返回 command、args、env、可选 files（写到隔离状态目录）。不把密钥存入 Agent 定义，`environmentRefs` 是目标变量名到宿主环境变量名的映射。
+
+内置 Codex/dsh 通过 stdio 使用。HTTP/WS 是锁定 SDK 2.2.0 的官方实验传输，服务必须实现相同的 ACP 传输版本；不把任意 HTTP 聊天接口当 ACP，也不自动架设 stdio 网关。自定义服务必须声明 `supportedTransports`，协议不匹配返回错误。
+
+Linux 上运行 embedded Codex 前，按 [Codex 沙箱前置](https://learn.chatgpt.com/docs/sandboxing) 准备 bubblewrap 和所需的 AppArmor profile，并用 `codex sandbox` 在临时目录验证读写。沙箱初始化失败应先修复宿主环境，不能通过关闭沙箱或让模型猜测文件内容完成任务。
+
+## 原生 HTTP/WS 服务：Goose
+
+Goose 1.57.0 自身提供 `goose serve` 与 `/acp` HTTP/WS，使用 custom-service 接入。先由部署方启动服务、挂载工作区/状态卷，并在 Goose 端维护模型（例如 `GOOSE_PROVIDER=openrouter`、`GOOSE_MODEL`、`OPENROUTER_API_KEY`）；服务独立设置 `GOOSE_SERVER__SECRET_KEY`。Hai 只使用 `X-Secret-Key` 认证，不向服务注入 Hai 模型密钥。
+
+```ts
+import { ai } from '@h-ai/ai'
+
+// ai 已初始化，Goose 已运行；HAI_GOOSE_SECRET 为服务端环境变量，值与远端服务密钥一致。
+async function connectGoose() {
+  const registered = await ai.acp.agents.register({
+    id: 'goose', name: 'Goose', mode: 'custom-service',
+    transport: 'http', url: 'http://127.0.0.1:3284/acp',
+    supportedTransports: ['http', 'ws'],
+    headerEnv: { 'X-Secret-Key': 'HAI_GOOSE_SECRET' },
+  })
+  if (!registered.success) return registered
+  return ai.acp.sessions.create({ agentId: 'goose', cwd: '/workspace' })
+}
+```
+
+WebSocket 改为 `transport: 'ws'` 和 `ws://` 地址。`cwd` 是远端可见路径；应用负责远程服务和存储的启动、关闭、Git、归属检查及 TLS。缺少或错误服务密钥会被 Goose 拒绝；恢复按握手能力走原生 load/resume，不用历史 prompt 模拟。依据：[Goose 固定版本接入文档](https://github.com/aaif-goose/goose/blob/v1.57.0/documentation/docs/gdk/acp/index.md)。
+
+## 配置和数据库共同维护
+
+`acp.agents`、`acp.workspaces` 可以直接写在配置文件里，也可通过 register 保存到数据库。get/list 返回 `{ value, source, version? }`，配置同 ID 优先且不可修改；数据库支持完整 update 和 remove。模型、MCP 等清单也遵循此规则，见 [资源清单](resources.md)。创建会话可通过 `mcpServerIds` 绑定合并清单里的 MCP。
+
+## 最小本机接入
+
+下面的目录、Git 地址、模型和密钥由部署方提供。首次登记一次，后续用 get/list 读取；重复 register 返回冲突。普通 API 都先检查 `success`。
+
+Windows stdio 需要系统 PowerShell 可用；npm 的 `.cmd` 包装应改用 `command: 'node.exe'` 和实际 JS 入口参数数组。框架跟踪整个进程树，关闭时清理后台子进程；系统策略阻止启动时直接返回错误。
+
+```ts
+import { ai } from '@h-ai/ai'
+
+async function run() {
+  const initialized = await ai.init({
+    llm: { models: [{
+      id: 'coding', model: 'your-responses-model', protocol: 'responses',
+      apiKey: process.env.MODEL_API_KEY,
+      baseUrl: 'https://models.example.com/v1',
+      capabilities: { contextWindow: 128000, maxOutputTokens: 16384, inputModalities: ['text'], outputModalities: ['text'], toolCalling: true, reasoning: { supported: false } },
+    }] },
+  })
+  if (!initialized.success) return initialized
+  try {
+    const agent = await ai.acp.agents.register({ id: 'coder', name: 'Codex', mode: 'embedded', adapter: 'codex', modelIds: ['coding'], defaultModelId: 'coding' })
+    if (!agent.success) return agent
+    const workspace = await ai.acp.workspaces.register({ id: 'project', storage: { type: 'directory', path: '/srv/projects/demo' }, repositories: [{ id: 'api', url: 'https://git.example.com/team/api.git', mainBranch: 'trunk' }] })
+    if (!workspace.success) return workspace
+    const ready = await ai.acp.workspaces.prepare('project')
+    if (!ready.success) return ready
+    const created = await ai.acp.sessions.create({ agentId: 'coder', workspaceId: 'project', newWorktree: true })
+    if (!created.success) return created
+    const session = created.data
+    const response = await session.prompt([{ type: 'text', text: '阅读工程并说明结构' }])
+    if (!response.success) return response
+    return response.data.text
+  }
+  finally { await ai.close() }
+}
+```
+
+`agents.initialize(id)` 检查模型绑定和原生配置能否生成；真正启动和握手用 `agents.check(id, { workspaceId })`。容器 Agent 的 `image` 必须与 workspace 的 image 一致。注册 volume 时固定实际选中的引擎；`auto` 优先就绪 Podman，再尝试 Docker，显式选定不可用引擎直接失败。
+
+生产环境先初始化共享数据库和网络向量库，或注入 shared AIStoreProvider。Agent/workspace/session 记录和 CAS 占用存入 AI Store，原生历史保存在隔离状态目录。不能把临时内存 Provider 当跨节点锁。
+
+## 容器运行与模型复用
+
+源码仓库提供 `packages/ai/models/agents` Dockerfile 和构建命令：
+
+```sh
+pnpm --filter @h-ai/ai agent:build codex-acp
+pnpm --filter @h-ai/ai agent:build deepseek-harness --engine=docker --java --rust --go
+```
+
+Codex 镜像明确包含 `@agentclientprotocol/codex-acp@2.5.0` 和 `@openai/codex@0.165.0`。所有镜像包含 Git、Node、Python；Java/Rust/Go 按构建选项安装。镜像自行构建、推送和部署；框架启动时不偷偷构建镜像、不挂引擎 socket。Dockerfile 随 npm 包的 models/agents 一起提供。
+
+Agent 改为 `mode: 'builtin-service', image: 'hai-ai/codex-acp:2.5.0', engine: 'auto'`；workspace 改为 `storage: { type: 'volume', name: 'project-code', image: 'hai-ai/codex-acp:2.5.0', engine: 'auto' }`。容器重建继续复用这两个命名卷，Git 和 Agent 在容器内始终看到 `/workspace`，不会混用宿主绝对 worktree 路径。工作区主目录为 `main/`，隔离 session 为 `sessions/<id>/`，上传文件放 `files/`。
+
+Podman 不自动继承远程服务的代理变量。需要代理时，使用 Agent/workspace 的 `environmentRefs` 显式传入容器可达的地址；宿主的回环代理不能直接在容器内使用。
+
+模型能力配置位于 `llm.models[].capabilities`：contextWindow、maxOutputTokens、inputModalities、outputModalities、toolCalling、reasoning.supported/efforts。未知就省略；不能用请求 `maxTokens` 预算推断真实容量。dsh 自定义模型需明确上下文、输出容量、输入模态、工具和推理能力，避免其内部默认值夸大模型能力。dsh 映射 Chat Completions、Responses、Anthropic；Codex 原生要求 Responses。现有 Hai 的 Responses 转换是客户端能力，不是对外反向网关。只有 Chat Completions 的服务不会因配置了 Codex 自动变成 Responses 服务。
+
+模型密钥在启动时重新解析；恢复时模型名、协议、地址、能力发生变化会拒绝，密钥轮换可以继续。自定义 ACP 服务只接受 `headerEnv` 里的认证引用，不接收 Hai 模型配置。
+
+## 工程和 Git
+
+每个 Git 工程必须写明 `mainBranch`，remote 默认为 origin。`prepare` 只克隆缺失工程并校验既有工程；不自动 pull、不重置脏目录。`workspaces.importFiles(id, [{ path, content }])` 添加普通文件，拒绝路径逃逸、链接和覆盖；没有 Git 工程的工作区无需安装 Git。涉及 Git 而命令缺失返回 `ACP_GIT_NOT_FOUND`。
+
+当前托管 Git 面向普通仓库；发现子模块或 Git LFS 属性时返回 `ACP_UNSUPPORTED`，不把未拉取的子模块或 LFS 指针当作完整工程。需要这些能力的应用可自行准备环境并使用低层 `connect`，其 Git 生命周期由应用负责。
+
+创建 session 默认共享 `main/` 路径，框架会阻止另一个共享 session 同时占用它。`newWorktree: true` 从每个工程当前已提交的本地主分支创建同名分支和 worktree，普通文件单独复制；可以指定 `branch`，默认 `acp/<sessionId>`。它不会自动拉远端，也不会导入主目录未提交修改。
+
+- `session.updateMain()`：停止本 session 的执行环境，再 fetch 各工程的明确主分支并 ff-only 更新本地主目录；不把主分支合入 session，不自动 rebase。共享主目录被其他会话占用时返回 busy。
+- `session.publish({ mode: 'push-branch', message, author: { name, email } })`：提交隔离 session 修改并推送其同名分支。
+- `session.publish({ mode: 'merge-main', message, author })`：提交后检查、更新登记的主分支，再合并并推送。无 force push，不静默处理冲突。
+
+发布仅允许框架创建的隔离 session，避免将共享目录中别人的修改算入当前任务。操作前停止受管进程/容器，避免背景工具继续写入；要继续编码显式 `sessions.resume(id)`。原生 Agent 自己创建的 worktree 不自动纳入框架发布范围。
+
+多个工程不是原子事务。失败时返回 `ACP_PARTIAL_FAILURE`，`error.cause.reports` 列出每个工程 success、phase、commit 和 error；已完成工程不回滚，冲突保留现场。失败于 push 后，排除权限/网络问题可重试；远端结果不明时先核对实际分支。普通文件的修改留在 session 目录，不自动纳入 Git 发布。失败创建的 worktree 也保留，避免删除已有成果。
+
+## 交互、事件和结果
+
+`onEvent` 在创建会话前注册，接收原生 session/update（含 `_meta`）；`session.stream(content, signal)` 提供有界 AsyncIterable，提前退出会取消该轮。prompt 返回 stopReason、text、events；有 messageId 时 text 取最后一条消息，完整消息仍在 events。没有消息边界的 Agent 只能拼接其文本，不能猜测某段是最终答案。
+
+`promptStructured(content, zodSchema, signal)` 只接受 end_turn、完整唯一 JSON（可为完整 JSON fenced block）和通过 Schema 的内容。不提取夹在说明中的任意对象，不自动重试付费请求。需要业务证据、ID 或范围判断时由应用进一步校验。
+
+权限默认取消。通过 `handlers` 提供官方 SDK 类型的 permission/fs/terminal/elicitation 回调，并在 `capabilities` 声明实际实现；terminal 必须提供完整回调组。回调运行在可信服务端，应用需按用户、session 和路径授权。Agent 自带本机工具可能不经过回调，worktree 也不是安全沙箱；只读评审需要操作系统/容器权限隔离。
+
+图片、音频、嵌入资源和远程 MCP 按初始化能力检查。mode/config 通过原生协议操作。取消、握手/任务超时、输出超限会返回明确错误；连接关闭后不会自动重放请求。`sessions.resume` 仅在 Agent 声明 load/resume 时使用原生 ID 和原状态，不用历史 prompt 伪造恢复。`connect` 提供底层连接、认证和原生会话枚举/删除，用于应用已经管理执行环境的情况。
+
+`session.close()` / `ai.close()` 等待拥有的进程树或容器停止后释放占用，保留目录和卷。失联或清理失败不会按 TTL 直接抢占；管理员先检查记录里的容器资源和实际执行环境，确认停止后再恢复占用记录。生产部署需监控此类故障。应用仍需负责 API 鉴权、项目归属、外部 Git 凭据及预览/业务发布。
+
+## 配置与错误
+
+`acp` 可省略：requestTimeout=30000ms、promptTimeout=600000ms、cancelTimeout=5000ms、maxContentBytes=8388608、maxPendingEvents=1024。对应 `HAI_AI_ACP_REQUESTTIMEOUT`、`HAI_AI_ACP_PROMPTTIMEOUT` 等环境变量。CLI 的 `_ai.yml` 和 `.env.example` 由公共配置目录生成这些字段；仅取消需要的配置注释不会自动启动 Agent。
+
+错误码：070 Git 缺失；071 普通操作失败；072 参数；073 未登记；074 占用；075 不支持；076 取消；077 超时；078 输出无效/超限；079 状态冲突；080 多工程部分失败；081 已关闭；082 运行环境不可用；083 模型不兼容；084 清理失败。统一前缀 `hai:ai:`。错误不包含原始 stderr、凭据或完整命令行。
+
+## 事件与恢复边界
+
+事件保留原生内容。智能体提供 messageId 时，prompt.text 使用最后一条消息；没有 messageId 时合并本轮收到的文本。HTTP 的 session/new 响应与会话事件是独立通道，早期事件可能稍晚到达；需要严格结果时使用 promptStructured，混入说明或不完整 JSON 会返回失败，不自动截取一个看似合法的对象。
+
+DSH 模型需要容量、输入模态、工具能力与推理声明；reasoning.supported 为 true 时需明确 efforts，false 会映射为原生 reasoningEfforts: false。Codex 原生配置会选择 api-key 认证并使用 Hai Responses provider。
+
+会话绑定、定义删除和工作区修改通过共享 CAS 临界区防止悬空引用；工作路径使用独立占用锁。进程或宿主异常中断后，不自动用 TTL 假定执行者已停止：需运维先核验/终止记录中的执行资源，再修复遗留占用；正常 close 后可直接 resume。框架不将 Git worktree 当成安全沙箱。

package/templates/skills/hai-ai/guide.md

@@ -2,7 +2,7 @@
 
 从 [SKILL.md](SKILL.md) 选择主题后读取对应小节。代码片段展示 API 用法；省略的业务变量、schema、依赖与 return 上下文需由应用补齐。
 
-`@h-ai/ai` 统一提供 LLM、工具、MCP、Embedding、Memory、Retrieval/RAG、Knowledge、Context、File、Rerank、Image、Audio 与 A2A 能力。
+`@h-ai/ai` 统一提供 LLM、工具、MCP、Embedding、Memory、Retrieval/RAG、Knowledge、Context、File、Rerank、Image、Audio、A2A 与 ACP 能力。工程智能体、工作区和会话见 [ACP 指南](acp.md)，配置与数据库资源合并见 [资源清单](resources.md)。
 
 ## 使用边界
 

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

@@ -193,7 +193,7 @@ flush 对本节点后台提取的异常和失败 HaiResult 返回 MEMORY_EXTRACT
 
 - `ai.file.parse({ content, filename, options })`：text/html/pdf/docx/ocr 解析。
 - `ai.file.parseText(content, filename?)`：直接返回文本。
-- `ai.rerank.rerank(request)` / `rerankTexts(query, texts, topN?)`：相关性重排。
+- `ai.rerank.rerank(request)` / `rerankTexts(query, texts, topN?)`：相关性重排；模型 `timeout` 覆盖响应头与正文读取，超时返回失败结果。
 - `ai.reasoning.run(query, options?)` / `runStream(query, options?)`：`react`、`cot`、`plan-execute`。
 
 ## Audio