@h-ai/cli 1.0.0-beta.7 → 1.0.0-beta.9

package/dist/{src-CX5IJGYM.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-XI5SKOOR.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-CX5IJGYM.js.map
-//# sourceMappingURL=src-CX5IJGYM.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.7",
+  "version": "1.0.0-beta.9",
   "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.7",
+    "@h-ai/core": "1.0.0-beta.9",
     "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.7",
-    "@h-ai/cache": "1.0.0-beta.7",
-    "@h-ai/crypto": "1.0.0-beta.7",
-    "@h-ai/deploy": "1.0.0-beta.7",
-    "@h-ai/feedback": "1.0.0-beta.7",
-    "@h-ai/iam": "1.0.0-beta.7",
-    "@h-ai/reach": "1.0.0-beta.7",
-    "@h-ai/reldb": "1.0.0-beta.7",
-    "@h-ai/storage": "1.0.0-beta.7",
+    "@h-ai/api-client": "1.0.0-beta.9",
+    "@h-ai/cache": "1.0.0-beta.9",
+    "@h-ai/crypto": "1.0.0-beta.9",
+    "@h-ai/deploy": "1.0.0-beta.9",
+    "@h-ai/feedback": "1.0.0-beta.9",
+    "@h-ai/iam": "1.0.0-beta.9",
+    "@h-ai/kit": "1.0.0-beta.9",
+    "@h-ai/payment": "1.0.0-beta.9",
+    "@h-ai/reach": "1.0.0-beta.9",
+    "@h-ai/reldb": "1.0.0-beta.9",
+    "@h-ai/storage": "1.0.0-beta.9",
+    "@h-ai/vecdb": "1.0.0-beta.9",
     "@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/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.7",
+  "version": "1.0.0-beta.9",
   "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",

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

@@ -14,6 +14,8 @@ Codex 用 `adapter: 'codex'`，DeepSeek Harness 用 `adapter: 'deepseek-harness'
 
 内置 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 模型密钥。

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

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

@@ -9,6 +9,8 @@
 
 ## 使用步骤
 
+`client.close()` 使旧刷新失效并等待已开始的凭据写入，但不清除宿主 TokenStorage。关闭完成后可复用同一存储重新 init；迟到刷新不能覆盖新身份。请求 timeout 覆盖响应头与完整 JSON 正文；自定义流按需读取，以调用方 signal 取消正文。内置 Cookie 适配器的登录和刷新包含跨域凭据，服务端须配置明确 Origin；内存/原生存储保留原请求凭据策略。
+
 ### 1. 初始化
 
 浏览器默认使用 httpOnly cookie 存储（推荐）：

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

@@ -38,9 +38,13 @@ type: memory # memory | redis
 ### 2. 初始化与关闭
 
 ```typescript
-import { cache } from '@h-ai/cache'
+import { core } from '@h-ai/core'
+import { cache, CacheConfigSchema } from '@h-ai/cache'
 
-await cache.init(core.config.get('cache'))
+const config = core.config.validate('cache', CacheConfigSchema)
+if (!config.success) throw new Error(config.error.message)
+const initialized = await cache.init(config.data)
+if (!initialized.success) throw new Error(initialized.error.message)
 // 使用后关闭
 const closed = await cache.close()
 if (!closed.success) throw new Error(closed.error.message)

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

@@ -21,7 +21,7 @@ description: "配置 hai 应用启动、YAML/环境变量、日志、i18n 与 Ha
 - 自动加载和监听配置目录内所有 YAML；项目根 `hai.json` 的 `build` / `deploy` 由 CLI 读取，不进入运行时配置。单项 load 返回失败时记日志并继续，必需配置须 validate 并检查 success；目录扫描、日志设置等异常仍可能传播。
 - 应用名称、版本、环境、默认语言和日志设置统一从 `_core.yml` 经 core.config 获取，日志使用 core.logger；UI 不另维护硬编码副本。SvelteKit layout / fullstack app.info 仅下发公开字段白名单；独立 Vite mobile-app 在 Node 构建时解析并注入公开默认值，修改这些编译默认值需要重新构建。静态 Web 的公开 API 地址等通过 `runtime-config.js` 覆盖时无需重建镜像，原生包在复制静态资源前准备配置入口。浏览器不加载 YAML，不接收完整模块配置、密钥或日志脱敏上下文。
 - `HAI_<配置名>_<路径>` 支持父 JSON 基础与细项覆盖，同源先父后子，高来源整段替换清除低来源细项。camelCase 不拆词，约定变量优先于显式插值；宿主显式提供 `configSchemas` 识别 YAML 缺少的可选路径，模块执行业务校验。
-- 环境文件采用六类：`.env.example` 完整列出字段用途、默认值、枚举和范围；`.env` 为公共基础；`.env.dev`、`.env.test`、`.env.prod` 为公共环境覆盖，这五类均提交 Git。`.env.local` 为本机私有配置，不提交 Git。优先级为进程环境 > `.env.local` > 环境文件 > `.env`；Vite 在 Node 配置阶段调用 `core.config.loadEnvFiles({ mode, envDir })` 并检查 success 后注入进程，Node 脚本按相同顺序传入 `--env-file`。`core.init` 不自行读取 dotenv。
+- 环境文件约定：`.env.example` 完整列出字段用途、默认值、枚举和范围；`.env` 为公共基础；`.env.dev`、`.env.test`、`.env.prod` 为公共环境覆盖，公共文件提交 Git。`.env.local` 为共享私有配置，`.env.<mode>.local` 为模式私有配置，均不提交 Git。优先级为进程环境 > `.env.<mode>.local` > `.env.local` > `.env.<mode>` > `.env` > YAML；Vite 在 Node 配置阶段调用 `core.config.loadEnvFiles({ mode, envDir })` 并检查 success 后注入进程，Node 入口复用 `run-node.mjs` 的结构合并，避免原生多 `--env-file` 遗留低来源细项。`core.init` 不自行读取 dotenv。
 - 配置 getter 与 ID/logger 方法不是 HaiResult；validate/load 等须检查 success。
 - 日志可用 `{ error }` 记录原生 Error；两端先规范化诊断再字段/URL 脱敏，配置 redact 路径仍生效。默认包含 passwordHash、passwd、secretKey 等实际凭据字段；异常文本清理显式凭据标签和 URL，不保证识别无标签秘密。原异常不变，错误子图循环/深度用固定标记；业务隐私仍由调用方清理或遮蔽整条路径。
 - 初始化前创建的默认、模块与嵌套 child Logger 在后续输出中应用当前全局 logging；configure/setLevel 也作用于已有实例。create 的显式 level/format/context 优先，未指定项动态继承。浏览器 json/pretty 与附加 redact 路径实际生效，消息文本仍由调用方脱敏。

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

@@ -9,6 +9,8 @@
 
 ## 运行环境
 
+传输客户端 `destroy()` 会取消并废弃在途握手；旧握手成功或失败都不能恢复状态或影响下一代握手。单请求取消仍只停止该请求的等待。
+
 **Node.js + 浏览器双端可用。** 浏览器端通过 `crypto.init()` 初始化（无需配置参数）。
 
 | 能力 | Node.js | 浏览器 | 说明 |

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

@@ -244,30 +244,52 @@ import { apiContract } from '@h-ai/api-contract'
 
 ### 服务端路由（SvelteKit）
 
+应用实现 `readOrder`：从共享数据库读取订单，返回持久化的金额、币种、所有者与支付状态。通知地址取服务端配置；在宿主权限配置中登记并授予 `payment:create`。以下工厂在路由模块中注入这两个可信依赖，`kit.handler` 仅提供错误边界，认证和资源授权仍在示例中显式执行。
+
 ```typescript
+import type { HaiResult } from '@h-ai/core'
 import { kit } from '@h-ai/kit'
-// src/routes/api/v1/payment/create/+server.ts
 import { payment } from '@h-ai/payment'
+import { z } from 'zod'
+
+interface PayableOrder {
+  orderNo: string
+  ownerId: string
+  amount: number
+  currency: string
+  description: string
+  status: 'pending' | 'paid' | 'closed'
+}
 
-export const POST = kit.handler(async ({ request, locals }) => {
-  const body = await request.json()
-  const result = await payment.createOrder(body.provider, {
-    orderNo: body.orderNo,
-    amount: body.amount,
-    description: body.description,
-    tradeType: body.tradeType,
-    userId: body.userId,
-    notifyUrl: body.notifyUrl,
+export function createPaymentHandler(
+  readOrder: (id: string) => Promise<HaiResult<PayableOrder | null>>,
+  notifyUrl: string,
+) {
+  return kit.handler(async ({ request, locals }) => {
+    const session = locals.session
+    if (!session) return kit.response.unauthorized()
+    kit.guard.require(session, 'payment:create')
+    const input = await kit.validate.body(request, z.object({ orderId: z.string().min(1) }).strict())
+    const order = await readOrder(input.orderId)
+    if (!order.success) return kit.response.fromError(order.error)
+    if (!order.data || order.data.ownerId !== session.userId || order.data.status !== 'pending')
+      return kit.response.forbidden()
+    const result = await payment.createOrder('stripe', {
+      orderNo: order.data.orderNo,
+      amount: order.data.amount,
+      currency: order.data.currency,
+      description: order.data.description,
+      tradeType: 'h5',
+      notifyUrl,
+    })
+    if (!result.success) return kit.response.fromError(result.error, locals.requestId)
+    return kit.response.ok(result.data, locals.requestId)
   })
-
-  if (!result.success) {
-    return kit.response.internalError(result.error.message)
-  }
-
-  return kit.response.ok(result.data, locals.requestId)
-})
+}
 ```
 
+在 `+server.ts` 中将可信业务读取函数和通知地址传给工厂，再导出返回值为 `POST`。
+
 ### 完整支付流程
 
 ```

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

@@ -6,6 +6,8 @@
 
 ## 运行环境
 
+Provider 名称必须唯一，重名在连接前返回 CONFIG_ERROR。close 等待在途初始化并释放其 Provider，返回后不再迟到发布模块或定时器。
+
 > ⚠️ **服务端模块（Node.js only）。** 浏览器端不直接发送邮件/短信，而是通过 API 端点触发服务端 `reach.send()`。
 
 ## 依赖
@@ -76,21 +78,27 @@ API Provider 只接受 HTTP(S) URL。回调地址若来自不可信输入，业
 ### 2. 初始化与关闭
 
 ```typescript
-import { cache } from '@h-ai/cache'
+import { cache, CacheConfigSchema } from '@h-ai/cache'
 import { core } from '@h-ai/core'
-import { reach } from '@h-ai/reach'
-import { reldb } from '@h-ai/reldb'
+import { reach, ReachConfigSchema } from '@h-ai/reach'
+import { reldb, ReldbConfigSchema } from '@h-ai/reldb'
 
 // 当前配置启用了 delay：数据库和队列表为必需依赖。
-const database = await reldb.init(core.config.get('db'))
+const databaseConfig = core.config.validate('db', ReldbConfigSchema)
+if (!databaseConfig.success) throw new Error(databaseConfig.error.message)
+const database = await reldb.init(databaseConfig.data)
 if (!database.success)
   throw new Error(database.error.message)
-const cached = await cache.init(core.config.get('cache')) // 可选，启用 flush 分布式锁
+const cacheConfig = core.config.validate('cache', CacheConfigSchema)
+if (!cacheConfig.success) throw new Error(cacheConfig.error.message)
+const cached = await cache.init(cacheConfig.data) // 可选，启用 flush 分布式锁
 if (!cached.success)
   throw new Error(cached.error.message)
 
 // 再初始化触达模块（自动检测已初始化的 reldb/cache 单例）
-const initialized = await reach.init(core.config.get('reach'))
+const reachConfig = core.config.validate('reach', ReachConfigSchema)
+if (!reachConfig.success) throw new Error(reachConfig.error.message)
+const initialized = await reach.init(reachConfig.data)
 if (!initialized.success)
   throw new Error(initialized.error.message)
 // ... 使用触达服务
@@ -234,7 +242,7 @@ interface ReachConfigInput {
 
 验证码和密码重置等有时效的通知应明确选择 DND 策略；可靠入队成功不代表用户已收到验证码。
 
-队列 `created_at` / `updated_at` / `locked_until` / `next_attempt_at` 均为 Unix 毫秒 `BIGINT`（SQLite 为 64 位 INTEGER）；仓库把 driver 的字符串/数字归一化为安全整数 number，并拒绝负数、小数和不安全整数。模板仓库的 TIMESTAMP 时间返回 Date。已有表须在部署时同步列结构，包含次数、退避策略和失败分类，模块不自动迁移旧表；跨库验收必须运行 PostgreSQL/MySQL 用例，SQLite 无法证明 32 位溢出已经消除。
+队列 `created_at` / `updated_at` / `locked_until` / `next_attempt_at` 均为 Unix 毫秒 `BIGINT`（SQLite 为 64 位 INTEGER）；仓库把 driver 的字符串/数字归一化为安全整数 number，并拒绝负数、小数和不安全整数。模板仓库的 TIMESTAMP 时间返回 Date。初始化自动执行版本化迁移，包含次数、退避策略和失败分类；升级前先 dry-run、备份并停止旧写入。旧通知载荷退役会清空正文/变量并将旧待发项标记 discarded，回退镜像不能恢复这些数据；跨库验收必须运行 PostgreSQL/MySQL 用例，SQLite 无法证明 32 位溢出已经消除。
 
 ### 租约、接收端幂等与未知结果
 

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

@@ -62,9 +62,12 @@ PostgreSQL 空闲连接错误已监听，由池移除并在下一次查询替换
 
 ```typescript
 import { core } from '@h-ai/core'
-import { reldb } from '@h-ai/reldb'
+import { reldb, ReldbConfigSchema } from '@h-ai/reldb'
 
-await reldb.init(core.config.get('db'))
+const config = core.config.validate('db', ReldbConfigSchema)
+if (!config.success) throw new Error(config.error.message)
+const initialized = await reldb.init(config.data)
+if (!initialized.success) throw new Error(initialized.error.message)
 // ... 使用数据库
 const closed = await reldb.close()
 if (!closed.success) throw new Error(closed.error.message)

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

@@ -175,7 +175,7 @@ await scheduler.init({
 
 可信服务端用 `execution.listLogFailures({ limit, offset })` 监控 pending（范围与 listUnknown 相同），用 `execution.repairLog(occurrenceId)` 从共享 journal 幂等补写；可跨节点、重启及并发调用。写入已提交但回执丢失时通过固定主键和完整内容核对去重。补写返回 `LOG_PERSIST_FAILED`（032）时继续保留 pending，并输出安全告警；全部数据库不可用且终态未提交时仍按 unknown 核对外部效果，不能假定存在可恢复结果。补写与日志保留均不调用业务 Hook。保留策略失败仅告警，不撤销已保存日志。`onTaskFinish` 是本地业务完成通知，其 unconfirmed 状态不是持久化确认；以 trigger 返回值及 execution.get 的 logPersistence 为准。
 
-领取前竞争/跳过的 interrupted 仅为观测日志，没有可补写的终态；其写入未确认时返回 unconfirmed。JSON 大载荷保存完整结果和全部重试记录，避免 MySQL 的 255 字符截断；新 schema 不自动迁移旧日志/执行表。关闭会等待在途补写，先关闭 scheduler 再关闭数据库。
+领取前竞争/跳过的 interrupted 仅为观测日志，没有可补写的终态；其写入未确认时返回 unconfirmed。JSON 大载荷保存完整结果和全部重试记录，避免 MySQL 的 255 字符截断；初始化会自动执行版本化迁移，归档并复制旧日志；升级前先 dry-run、备份并停止旧写入，按模块 README 核对迁移影响。关闭会等待在途补写，先关闭 scheduler 再关闭数据库。
 
 ```ts
 const result = await scheduler.trigger('cleanup', { idempotencyKey: 'cleanup-2026-10-23' })

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

@@ -4,6 +4,8 @@
 
 ## 运行环境
 
+Local 的 key 路径拒绝文件符号链接和目录 junction，`.meta.json` / `.upload.tmp` 保留后缀不区分大小写。覆盖 put 清除旧元数据，copy 默认继承源元数据。浏览器根入口仅导出 Schema、类型和客户端辅助能力。
+
 > ⚠️ **服务端模块**。`storage.file` / `storage.dir` / `storage.presign` 均在 Node.js 端使用。浏览器端通过预签名 URL 或 API 端点间接访问存储（见下方「浏览器端文件上传」）。
 
 ## 适用场景
@@ -53,9 +55,13 @@ MinIO、RustFS 使用同一个 S3 Provider：配置 `type: s3`、S3 API `endpoin
 ### 2. 初始化与关闭
 
 ```typescript
-import { storage } from '@h-ai/storage'
+import { core } from '@h-ai/core'
+import { storage, StorageConfigSchema } from '@h-ai/storage'
 
-await storage.init(core.config.get('storage'))
+const config = core.config.validate('storage', StorageConfigSchema)
+if (!config.success) throw new Error(config.error.message)
+const initialized = await storage.init(config.data)
+if (!initialized.success) throw new Error(initialized.error.message)
 // 使用后关闭
 const closeResult = await storage.close()
 if (!closeResult.success) {