@h-ai/cli 0.1.0-alpha.16 → 0.1.0-alpha.19

package/templates/apps/fullstack/packages/{{projectName}}-shared/src/lib/components/ThemeSwitcher.svelte.hbs

@@ -0,0 +1,18 @@
+<script lang="ts">
+  import * as m from '../paraglide/messages.js'
+  import { AVAILABLE_THEMES, themeStore } from '../stores/theme.svelte.js'
+
+  function handleChange(event: Event) {
+    const target = event.target as HTMLSelectElement
+    themeStore.set(target.value)
+  }
+</script>
+
+<label class="form-control w-32 sm:w-40">
+  <span class="label-text text-xs">{m.settings_theme()}</span>
+  <select class="select select-bordered select-sm bg-base-100/80" value={themeStore.current} onchange={handleChange}>
+    {#each AVAILABLE_THEMES as theme (theme)}
+      <option value={theme}>{theme}</option>
+    {/each}
+  </select>
+</label>

package/templates/apps/fullstack/packages/{{projectName}}-shared/src/lib/stores/theme.svelte.ts.hbs

@@ -0,0 +1,55 @@
+{{!-- Shared theme store for {{projectName}} fullstack apps. --}}
+const STORAGE_KEY = 'hai-theme'
+const DEFAULT_THEME = '{{fullstack.theme.defaultTheme}}'
+export const AVAILABLE_THEMES: readonly string[] = [{{#each fullstack.theme.themes}}'{{this}}'{{#unless @last}}, {{/unless}}{{/each}}]
+
+function isBrowser(): boolean {
+  return typeof window !== 'undefined' && typeof document !== 'undefined'
+}
+
+function readInitialTheme(): string {
+  if (!isBrowser())
+    return DEFAULT_THEME
+  try {
+    const stored = window.localStorage.getItem(STORAGE_KEY)
+    if (stored && AVAILABLE_THEMES.includes(stored))
+      return stored
+  }
+  catch {
+    // localStorage 不可用时（隐私模式 / SSR），回退到默认主题
+  }
+  return DEFAULT_THEME
+}
+
+class ThemeState {
+  current = $state<string>(DEFAULT_THEME)
+
+  constructor() {
+    this.current = readInitialTheme()
+    if (isBrowser())
+      this.apply(this.current)
+  }
+
+  set(value: string): void {
+    if (!AVAILABLE_THEMES.includes(value))
+      return
+    this.current = value
+    this.apply(value)
+    if (isBrowser()) {
+      try {
+        window.localStorage.setItem(STORAGE_KEY, value)
+      }
+      catch {
+        // 忽略 localStorage 写入失败
+      }
+    }
+  }
+
+  private apply(value: string): void {
+    if (!isBrowser())
+      return
+    document.documentElement.dataset.theme = value
+  }
+}
+
+export const themeStore = new ThemeState()

package/templates/apps/fullstack/packages/{{projectName}}-shared/tsconfig.json.hbs

@@ -0,0 +1,17 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "allowImportingTsExtensions": true,
+    "allowJs": true,
+    "checkJs": false,
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "noEmit": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "types": ["svelte"],
+    "verbatimModuleSyntax": true
+  },
+  "include": ["src/**/*", "src/**/*.svelte"],
+  "exclude": ["node_modules", "src/lib/paraglide"]
+}

package/templates/apps/fullstack/playwright.config.ts.hbs

@@ -0,0 +1,34 @@
+import process from 'node:process'
+import { defineConfig } from '@playwright/test'
+
+export default defineConfig({
+  testDir: './e2e',
+  fullyParallel: false,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: 1,
+  reporter: 'list',
+  timeout: 30_000,
+  use: {
+    baseURL: '{{#if fullstack.e2eFrontend}}http://127.0.0.1:{{fullstack.e2eFrontend.port}}{{else}}http://127.0.0.1:3000{{/if}}',
+    channel: 'chrome',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+  },
+  webServer: [
+    {
+      name: '{{fullstack.servPackageName}}',
+      command: 'pnpm --filter {{fullstack.servPackageName}} start',
+      url: 'http://127.0.0.1:3000/health',
+      reuseExistingServer: false,
+      timeout: 120_000,
+    }{{#if fullstack.e2eFrontend}},
+    {
+      name: '{{fullstack.e2eFrontend.packageName}}',
+      command: 'pnpm --filter {{fullstack.e2eFrontend.packageName}} preview',
+      url: 'http://127.0.0.1:{{fullstack.e2eFrontend.port}}',
+      reuseExistingServer: false,
+      timeout: 120_000,
+    }{{/if}},
+  ],
+})

package/templates/apps/fullstack/pnpm-workspace.yaml

@@ -0,0 +1,7 @@
+shellEmulator: true
+
+trustPolicy: no-downgrade
+
+packages:
+  - 'packages/*'
+  - 'apps/*'

package/templates/apps/fullstack/tsconfig.base.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "ignoreDeprecations": "6.0",
+    "resolveJsonModule": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true
+  }
+}

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

@@ -0,0 +1,7 @@
+import { expect, test } from '@playwright/test'
+
+/** 首页从真实浏览器页面发起，覆盖基础渲染链路。 */
+test('home page renders from browser', async ({ page }) => {
+  await page.goto('/')
+  await expect(page.locator('main, section').first()).toBeVisible()
+})

package/templates/base/eslint.config.js

@@ -15,6 +15,12 @@ export default antfu({
     '**/project.inlang/**',
     '**/paraglide/**',
     '**/.agents/**',
+    '**/.github/**',
+    '**/AGENTS.md',
+    '**/CLAUDE.md',
+    '**/README.md',
+    '**/opencode.json',
+    '**/package.json',
   ],
   svelte: true,
 }, {

package/templates/base/package.json.hbs

@@ -1,6 +1,6 @@
 {
   "name": "{{projectName}}",
-  "version": "0.1.0-alpha.16",
+  "version": "0.1.0-alpha.19",
   "private": true,
   "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 'android-app'}}Android app built with hai Agent Framework{{/if_eq}}",
   "keywords": ["hai", "sveltekit", "svelte5", "{{appType}}"],
@@ -14,6 +14,7 @@
     "build": "vite build",
     "preview": "vite preview",
     "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+    "typecheck": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
     "lint": "eslint .",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -21,34 +22,36 @@
     "clean": "rimraf .svelte-kit build .turbo"
   },
   "dependencies": {
-    "@h-ai/core": "^0.1.0-alpha.16",
-    "@h-ai/kit": "^0.1.0-alpha.16"{{#if hasUi}},
-    "@h-ai/ui": "^0.1.0-alpha.16"{{/if}}{{#if features.db}},
-    "@h-ai/reldb": "^0.1.0-alpha.16"{{/if}}{{#if features.cache}},
-    "@h-ai/cache": "^0.1.0-alpha.16"{{/if}}{{#if features.iam}},
-    "@h-ai/iam": "^0.1.0-alpha.16"{{/if}}{{#if features.crypto}},
-    "@h-ai/crypto": "^0.1.0-alpha.16"{{/if}}{{#if features.storage}},
-    "@h-ai/storage": "^0.1.0-alpha.16"{{/if}}{{#if features.ai}},
-    "@h-ai/ai": "^0.1.0-alpha.16"{{/if}}{{#if features.audit}},
-    "@h-ai/audit": "^0.1.0-alpha.16"{{/if}}{{#if features.reach}},
-    "@h-ai/reach": "^0.1.0-alpha.16"{{/if}}{{#if features.payment}},
-    "@h-ai/payment": "^0.1.0-alpha.16"{{/if}}{{#if features.vecdb}},
-    "@h-ai/vecdb": "^0.1.0-alpha.16"{{/if}}{{#if features.datapipe}},
-    "@h-ai/datapipe": "^0.1.0-alpha.16"{{/if}}{{#if features.scheduler}},
-    "@h-ai/scheduler": "^0.1.0-alpha.16"{{/if}}{{#if features.deploy}},
-    "@h-ai/deploy": "^0.1.0-alpha.16"{{/if}}{{#if features.api-client}},
-    "@h-ai/api-client": "^0.1.0-alpha.16"{{/if}}{{#if features.capacitor}},
-    "@h-ai/capacitor": "^0.1.0-alpha.16"{{/if}}{{#if isCapacitorApp}}{{#unless features.api-client}},
-    "@h-ai/api-client": "^0.1.0-alpha.16"{{/unless}}{{#unless features.capacitor}},
-    "@h-ai/capacitor": "^0.1.0-alpha.16"{{/unless}}{{/if}},
-    "zod": "^4.3.6"
+    "@h-ai/core": "^0.1.0-alpha.19",
+    "@h-ai/kit": "^0.1.0-alpha.19"{{#if hasUi}},
+    "@h-ai/ui": "^0.1.0-alpha.19"{{/if}}{{#if features.db}},
+    "@h-ai/reldb": "^0.1.0-alpha.19"{{/if}}{{#if features.cache}},
+    "@h-ai/cache": "^0.1.0-alpha.19"{{/if}}{{#if features.iam}},
+    "@h-ai/iam": "^0.1.0-alpha.19"{{/if}}{{#if features.crypto}},
+    "@h-ai/crypto": "^0.1.0-alpha.19"{{/if}}{{#if features.storage}},
+    "@h-ai/storage": "^0.1.0-alpha.19"{{/if}}{{#if features.ai}},
+    "@h-ai/ai": "^0.1.0-alpha.19"{{/if}}{{#if features.audit}},
+    "@h-ai/audit": "^0.1.0-alpha.19"{{/if}}{{#if features.reach}},
+    "@h-ai/reach": "^0.1.0-alpha.19"{{/if}}{{#if features.payment}},
+    "@h-ai/payment": "^0.1.0-alpha.19"{{/if}}{{#if features.vecdb}},
+    "@h-ai/vecdb": "^0.1.0-alpha.19"{{/if}}{{#if features.datapipe}},
+    "@h-ai/datapipe": "^0.1.0-alpha.19"{{/if}}{{#if features.scheduler}},
+    "@h-ai/scheduler": "^0.1.0-alpha.19"{{/if}}{{#if features.deploy}},
+    "@h-ai/deploy": "^0.1.0-alpha.19"{{/if}}{{#if features.api-client}},
+    "@h-ai/api-client": "^0.1.0-alpha.19"{{/if}}{{#if features.capacitor}},
+    "@h-ai/capacitor": "^0.1.0-alpha.19"{{/if}}{{#if isCapacitorApp}}{{#unless features.api-client}},
+    "@h-ai/api-client": "^0.1.0-alpha.19"{{/unless}}{{#unless features.capacitor}},
+    "@h-ai/capacitor": "^0.1.0-alpha.19"{{/unless}}{{/if}},
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@playwright/test": "^1.59.1",
+    "@antfu/eslint-config": "^9.0.0",
+    "@playwright/test": "^1.60.0",
 {{#if isCapacitorApp}}
-    "@capacitor/cli": "^8.2.0",
-    "@capacitor/core": "^8.2.0",
-    "@capacitor/android": "^8.2.0",
+  "@aparajita/capacitor-secure-storage": "^8.0.0",
+    "@capacitor/cli": "^8.3.4",
+    "@capacitor/core": "^8.3.4",
+    "@capacitor/android": "^8.3.4",
     "@capacitor/preferences": "^8.0.1",
     "@sveltejs/adapter-static": "^3.0.10",
 {{else}}
@@ -58,22 +61,26 @@
     "@sveltejs/adapter-auto": "^7.0.1",
 {{/if_eq}}
 {{/if}}
-    "@sveltejs/kit": "^2.57.1",
-    "@sveltejs/vite-plugin-svelte": "^7.0.0",
-    "@types/node": "^25.6.0",
+    "@sveltejs/kit": "^2.61.1",
+    "@sveltejs/vite-plugin-svelte": "^7.1.2",
+    "@types/node": "^25.9.1",
+    "eslint": "^10.4.0",
+    "eslint-plugin-format": "^2.0.1",
+    "eslint-plugin-svelte": "^3.17.1",
     "pino-pretty": "^13.1.3",
     "rimraf": "^6.1.3",
-    "svelte": "^5.55.3",
-    "svelte-check": "^4.4.6",
-    "typescript": "^6.0.2",
-    "vite": "^8.0.8",
-    "vitest": "^4.1.4"{{#if hasUi}},
-    "@tailwindcss/vite": "^4.2.2",
-    "tailwindcss": "^4.2.2",
-    "daisyui": "^5.5.19",
-    "@iconify-json/tabler": "^1.2.33",
+    "svelte": "^5.55.9",
+    "svelte-check": "^4.4.8",
+    "svelte-eslint-parser": "^1.6.1",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.14",
+    "vitest": "^4.1.7"{{#if hasUi}},
+    "@tailwindcss/vite": "^4.3.0",
+    "tailwindcss": "^4.3.0",
+    "daisyui": "^5.5.20",
+    "@iconify-json/tabler": "^1.2.35",
     "@iconify/tailwind4": "^1.2.3"{{/if}}{{#if hasI18n}},
-    "@inlang/paraglide-js": "^2.15.3",
+    "@inlang/paraglide-js": "^2.18.1",
     "@inlang/plugin-message-format": "^4.4.0"{{/if}}
   }{{#if features.db}},
   "pnpm": {

package/templates/base/src/app.css.hbs

@@ -1,3 +1,4 @@
+{{! @skipIfEmpty }}
 {{#if hasUi}}
 /* ─── Tailwind CSS v4 ─── */
 @import 'tailwindcss';

package/templates/base/src/lib/server/init.ts.hbs

@@ -27,13 +27,13 @@
 {{/if}}
  */
 
+{{#if features.cache}}
+import { cache, CacheConfigSchema } from '@h-ai/cache'
+{{/if}}
 import { core } from '@h-ai/core'
 {{#if features.db}}
 import { reldb, ReldbConfigSchema } from '@h-ai/reldb'
 {{/if}}
-{{#if features.cache}}
-import { cache, CacheConfigSchema } from '@h-ai/cache'
-{{/if}}
 {{#if features.iam}}
 import type { IamConfigSettingsInput } from '@h-ai/iam'
 import { iam } from '@h-ai/iam'

package/templates/base/tests/scaffold.test.ts.hbs

@@ -0,0 +1,27 @@
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+const rootDir = fileURLToPath(new URL('..', import.meta.url))
+
+describe('generated scaffold', () => {
+  it('declares project metadata and quality gate scripts', async () => {
+    const packageJsonPath = join(rootDir, 'package.json')
+    const pkg = JSON.parse(await readFile(packageJsonPath, 'utf-8')) as {
+      name: string
+      scripts: Record<string, string>
+    }
+
+    expect(pkg.name).toBe('{{projectName}}')
+    expect(pkg.scripts.typecheck).toBeDefined()
+    expect(pkg.scripts.lint).toBeDefined()
+    expect(pkg.scripts.test).toBeDefined()
+    expect(pkg.scripts['test:e2e']).toBeDefined()
+  })
+
+  it('renders the app shell locale marker', async () => {
+    const appHtml = await readFile(join(rootDir, 'src/app.html'), 'utf-8')
+    expect(appHtml).toContain('lang="{{#if hasI18n}}%lang%{{else}}{{defaultLocale}}{{/if}}"')
+  })
+})

package/templates/features/payment/routes/api/v1/payment/create/+server.ts

@@ -7,18 +7,26 @@ import { payment } from '@h-ai/payment'
 
 export const POST: RequestHandler = async ({ request, locals }) => {
   const body = await request.json()
-  const { provider, tradeType, outTradeNo, totalAmount, subject, notifyUrl } = body
+  const { provider, tradeType, outTradeNo, totalAmount, subject, notifyUrl, userId, metadata } = body
 
   if (!provider || !outTradeNo || !totalAmount || !subject) {
     return kit.response.badRequest('Missing required fields: provider, outTradeNo, totalAmount, subject')
   }
 
-  const result = await payment.createOrder({
-    provider,
-    tradeType: tradeType ?? 'JSAPI',
-    outTradeNo,
-    totalAmount,
-    subject,
+  const normalizedTradeType = tradeType === 'h5'
+    || tradeType === 'app'
+    || tradeType === 'native'
+    || tradeType === 'mini_program'
+    ? tradeType
+    : 'jsapi'
+
+  const result = await payment.createOrder(provider, {
+    orderNo: outTradeNo,
+    amount: Number(totalAmount),
+    description: subject,
+    tradeType: normalizedTradeType,
+    userId,
+    metadata,
     notifyUrl: notifyUrl ?? `${new URL(request.url).origin}/api/v1/payment/notify/${provider}`,
   })
 

package/templates/features/payment/routes/api/v1/payment/notify/[provider]/+server.ts

@@ -21,8 +21,7 @@ export const POST: RequestHandler = async ({ request, params }) => {
     headers[key] = value
   })
 
-  const result = await payment.handleNotify({
-    provider,
+  const result = await payment.handleNotify(provider, {
     headers,
     body,
   })

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

@@ -122,6 +122,8 @@ ai.init(core.config.get('ai'))
 ai.close()
 ```
 
+`ai.config` 返回的是脱敏后的配置快照；`apiKey`、`privateKey`、`baseUrl` 等敏感字段会自动隐藏，URL 类字段只掩码内嵌凭证。
+
 **特殊说明**：`ai.tools` 和 `ai.stream` 无需 init 即可使用；`ai.llm` 和 `ai.mcp` 操作需要先 init。
 
 ---

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

@@ -48,6 +48,8 @@ await apiClient.init({
 })
 ```
 
+> `createCapacitorTokenStorage()` 仅在 Android/iOS 原生环境 + `@aparajita/capacitor-secure-storage` 已安装时持久化 token；纯 Web 不会回退到 `localStorage`。
+
 SSR / Node.js 测试场景请显式传入内存存储：
 
 ```ts
@@ -84,6 +86,8 @@ const client = apiClient.create(contract)
 await client.init({ baseUrl: 'https://api.example.com/api/v1' })
 ```
 
+`client.config` / `apiClient.config` 返回的是脱敏后的运行配置快照；`baseUrl` 的内嵌凭证与 `headers.authorization` 等敏感值会自动隐藏。
+
 ### 4. 关闭
 
 ```ts

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

@@ -52,7 +52,10 @@ await audit.init({
 ### 3. 关闭
 
 ```ts
-await audit.close()
+const closeResult = await audit.close()
+if (!closeResult.success) {
+  throw new Error(closeResult.error.message)
+}
 ```
 
 ## 核心 API
@@ -62,7 +65,7 @@ await audit.close()
 | 方法                  | 签名                                                             | 说明       |
 | --------------------- | ---------------------------------------------------------------- | ---------- |
 | `audit.init`          | `(config: AuditInitConfig) => Promise<HaiResult<void>>` | 初始化模块 |
-| `audit.close`         | `() => Promise<void>`                                            | 关闭模块   |
+| `audit.close`         | `() => Promise<HaiResult<void>>`                                 | 关闭模块   |
 | `audit.isInitialized` | `boolean`                                                        | 初始化状态 |
 
 ### 日志操作
@@ -86,6 +89,8 @@ await audit.close()
 | `audit.helper.passwordResetComplete(userId, ip?, ua?)`                         | 密码重置完成 |
 | `audit.helper.crud(input)` | CRUD 操作    |
 
+> `audit.log()` / `audit.helper.*()` 中的 `details` 仅会自动脱敏凭证类字段（如 `password` / `token` / `secret`）；邮箱、手机号默认保留原值。
+
 ## 错误码
 
 | 错误码                            | code             | 说明         |

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

@@ -51,6 +51,8 @@ await cache.init(core.config.get('cache'))
 await cache.close()
 ```
 
+`cache.config` 返回的是脱敏后的配置快照；Redis `password` / `url` 等敏感值不会原样暴露给日志或调试输出。
+
 ---
 
 ## 核心 API

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

@@ -5,20 +5,20 @@ description: 使用 @h-ai/capacitor 桥接 Capacitor 原生能力（Token 安全
 
 # hai-capacitor
 
-> `@h-ai/capacitor` 是 hai-framework 的 Capacitor 原生桥接模块，封装常用原生能力为统一 API，返回 `HaiResult<T>`。与 `@h-ai/api-client` 配合实现 App 端 Token 安全存储。
+> `@h-ai/capacitor` 是 hai-framework 的 Capacitor 原生桥接模块，封装常用原生能力为统一 API，返回 `HaiResult<T>`。与 `@h-ai/api-client` 配合时，Token 仅存于原生安全存储，不回退到 Web `localStorage`。
 
 ---
 
 ## 运行环境
 
-> **浏览器端 / 原生 App 专用。** 在 Capacitor 原生环境（Android/iOS）中提供完整能力，纯 Web 环境下部分功能退化（如 Preferences 退化为 localStorage）。
+> **浏览器端 / 原生 App 专用。** 在 Capacitor 原生环境（Android/iOS）中提供完整能力；`createCapacitorTokenStorage()` 仅在原生环境持久化 token，纯 Web 不做不安全回退。`capacitor.preferences` 仍可用于普通偏好数据。
 
 ---
 
 ## 适用场景
 
 - Android/iOS 原生应用开发（SvelteKit + Capacitor）
-- Token 安全存储（Capacitor Preferences → SharedPreferences / UserDefaults）
+- Token 安全存储（`@aparajita/capacitor-secure-storage`）
 - 设备信息获取（平台、型号、版本）
 - 推送通知注册与监听（FCM / APNs）
 - 原生相机拍照 / 相册选取
@@ -64,13 +64,13 @@ await apiClient.init({
 })
 ```
 
-`createCapacitorTokenStorage()` 返回 `TokenStorage` 实例（兼容 `@h-ai/api-client`），底层使用 `@capacitor/preferences`：
+`createCapacitorTokenStorage()` 返回 `TokenStorage` 实例（兼容 `@h-ai/api-client`），底层使用 `@aparajita/capacitor-secure-storage`：
 
-- Android → SharedPreferences（应用沙盒）
-- iOS → UserDefaults
-- Web → localStorage（退化，建议仅原生端使用）
+- Android → Android KeyStore + 加密 SharedPreferences
+- iOS → Keychain
+- Web → **不回退到 localStorage**；`get*()` 返回 `null`，`set*()` / `clear()` 为 no-op
 
-所有方法内置 try-catch，Preferences 异常时 get 返回 `null`、set/clear 静默失败并记录日志。
+所有方法内置 try-catch；原生安全存储异常时 get 返回 `null`、set/clear 静默失败并记录日志。
 
 #### Preferences 子操作
 
@@ -208,6 +208,7 @@ await capacitor.statusBar.show()
 | `HaiCapacitorError.PREFERENCES_SET_FAILED`   | `hai:capacitor:012`    | Preferences 写入失败 |
 | `HaiCapacitorError.PREFERENCES_REMOVE_FAILED`| `hai:capacitor:013`    | Preferences 删除失败 |
 | `HaiCapacitorError.DEVICE_INFO_FAILED`       | `hai:capacitor:020`    | 获取设备信息失败     |
+| `HaiCapacitorError.APP_VERSION_FAILED`       | `hai:capacitor:021`    | 获取应用版本失败     |
 | `HaiCapacitorError.PUSH_REGISTER_FAILED`     | `hai:capacitor:030`    | 推送注册失败         |
 | `HaiCapacitorError.PUSH_LISTEN_FAILED`       | `hai:capacitor:031`    | 推送监听失败         |
 | `HaiCapacitorError.CAMERA_FAILED`            | `hai:capacitor:040`    | 拍照/相册失败        |
@@ -359,7 +360,8 @@ async function captureAndUpload() {
 | 插件 | 类型 | 用于 |
 | --- | --- | --- |
 | `@capacitor/core` | peerDependency（必需） | 核心运行时 |
-| `@capacitor/preferences` | peerDependency（必需） | Token 存储 |
+| `@aparajita/capacitor-secure-storage` | 可选 peerDependency（原生 token 存储必需） | `createCapacitorTokenStorage()` |
+| `@capacitor/preferences` | peerDependency（必需） | `capacitor.preferences.*` 普通偏好数据 |
 | `@capacitor/device` | 可选 | `getDeviceInfo()` |
 | `@capacitor/app` | 可选 | `getAppVersion()` |
 | `@capacitor/push-notifications` | 可选 | `registerPush()` / `listenPush()` |

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

@@ -16,7 +16,7 @@ description: 使用 @h-ai/core 进行配置加载、日志记录、i18n 国际
 | 能力 | Node.js | 浏览器 |
 |------|---------|--------|
 | `core.logger` | ✅ pino（结构化 JSON / pretty） | ✅ loglevel（DevTools console） |
-| `core.config` | ✅ 完整（YAML 加载、watch、validate） | ⚠️ 仅支持 `core.init({ ... })` 传入配置 |
+| `core.config` | ✅ 完整（YAML 加载、watch、validate） | ⚠️ 占位 API；文件配置方法返回 `SERVICE_UNAVAILABLE` |
 | `core.i18n` | ✅ | ✅ |
 | `core.zodValidation` | ✅ | ✅ |
 | `core.id` | ✅ | ✅ |
@@ -79,6 +79,8 @@ const formErrors = core.zodValidation.mapZodErrorToFormErrors(zodError, getMessa
 
 ### 配置管理 — `core.config`
 
+> 浏览器端保留 `core.config` 对象用于类型/runtime 对齐，但没有文件系统：`get()` 返回 `undefined`，`has()` 返回 `false`，`keys()` 返回 `[]`；`load()` / `validate()` / `reload()` 返回 `HaiCommonError.SERVICE_UNAVAILABLE`；`watch()` 会立即回调该错误并返回 no-op 取消函数。
+
 | 方法         | 签名                                                           | 说明                           |
 | ------------ | -------------------------------------------------------------- | ------------------------------ |
 | `get`        | `<T>(name: string) => T \| undefined`                          | 获取模块配置段                 |
@@ -541,6 +543,7 @@ logger.debug('Data fetched', { count: items.length })
 
 | 功能 | 行为 |
 |------|------|
+| `core.config` 文件配置 | 不支持；文件相关方法返回 `SERVICE_UNAVAILABLE`，配置应由服务端读取后下发 |
 | `format: 'json' \| 'pretty'` | 被忽略（始终输出到 DevTools console） |
 | `redact` 字段脱敏 | 不生效（需手动脱敏） |
 | `fatal` 级别 | 映射为 `console.error`（带 `[FATAL]` 前缀） |