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

package/templates/apps/mobile-app/src/App.svelte.hbs

@@ -1,6 +1,9 @@
 <script lang='ts'>
 {{#if features.iam}}
   import type { IamPublicConfig } from '@h-ai/api-contract'
+{{/if}}
+  import type { Component } from 'svelte'
+{{#if features.iam}}
   import { apiClient } from '@h-ai/api-client'
 {{/if}}
   import { applyTheme, getSavedTheme, setGlobalLocale } from '@h-ai/ui'
@@ -8,9 +11,11 @@
   import { AuthPanel } from '@h-ai/ui/components/scenes/iam/index'
 {{/if}}
   import { onMount } from 'svelte'
-  import { closeApi, initApi, resolveApiBase, usesNativeTokenStorage } from './lib/api.js'
+
+  import { closeApi, initApi, usesNativeTokenStorage } from './lib/api.js'
   import { appConfig, initClientCore } from './lib/app-config.js'
   import { initCapacitor, isNativeApp } from './lib/capacitor.js'
+  import { HashRouter } from './lib/navigation/hash-router.svelte.js'
   import * as m from './lib/paraglide/messages.js'
   import { getLocale } from './lib/paraglide/runtime.js'
 
@@ -31,11 +36,12 @@
   }
 {{/if}}
 
-  type TabId = 'home' | 'tasks' | 'profile'
+  const pages = import.meta.glob<{ default: Component<{ nativeRuntime: boolean, nativeTokenStorage: boolean }> }>('./lib/pages/**/*.svelte')
+  const router = new HashRouter(Object.keys(pages), '/home')
+  const pageComponent = $derived(pages[router.file]())
 
   let booting = $state(true)
   let bootError = $state<string | null>(null)
-  let activeTab = $state<TabId>('home')
   let nativeRuntime = $state(false)
   let nativeTokenStorage = $state(false)
 
@@ -74,136 +80,59 @@
     }
   }
 
+  /** 切换底部导航；例如 handleTabChange('tasks') 会写入 #/tasks。 */
   function handleTabChange(id: string): void {
-    if (id === 'home' || id === 'tasks' || id === 'profile')
-      activeTab = id
+    router.navigate(`/${id}`)
   }
 
   onMount(() => {
+    const stopRouting = router.start()
 {{#if features.iam}}
     resetToken = new URL(location.href).searchParams.get('token') ?? ''
 {{/if}}
     void bootstrap()
 
     return () => {
+      stopRouting()
       void closeApi()
     }
   })
 </script>
 
-{#if booting}
-  <div class='hai-mobile-viewport'>
-    <div class='hai-mobile-shell max-w-lg'>
-      <div class='flex min-h-screen items-center justify-center'>
-        <span class='loading loading-spinner loading-lg'></span>
-      </div>
-    </div>
-  </div>
-{:else if bootError}
-  <div class='hai-mobile-viewport'>
-    <div class='hai-mobile-shell max-w-lg'>
-      <div class='flex min-h-screen flex-col items-center justify-center gap-3 p-6 text-center'>
-        <span class='icon-[tabler--alert-triangle] text-error text-4xl'></span>
-        <h1 class='text-lg font-bold'>{m.boot_failed_title()}</h1>
-        <p class='text-base-content/60 text-sm'>{bootError}</p>
-        <Button variant='primary' size='sm' onclick={() => location.reload()}>{m.common_retry()}</Button>
-      </div>
-    </div>
-  </div>
+<div class='hai-mobile-viewport'>
+  <div class='hai-mobile-shell max-w-lg'>
+    <AppBar title={appConfig.name} safeArea fixed={false} class='bg-base-100/95 backdrop-blur border-base-content/8' />
+    <main class='hai-mobile-main'>
+      {#if booting}
+        <div class='grid min-h-64 place-items-center'><span class='loading loading-spinner loading-lg'></span></div>
+      {:else if bootError}
+        <section class='flex min-h-64 flex-col items-center justify-center gap-3 p-6 text-center'>
+          <h1 class='text-lg font-bold'>{m.boot_failed_title()}</h1>
+          <p class='text-base-content/60 text-sm'>{bootError}</p>
+          <Button variant='primary' size='sm' onclick={() => location.reload()}>{m.common_retry()}</Button>
+        </section>
 {{#if features.iam}}
-{:else if !authenticated}
-  <main>
-    <AuthPanel config={authConfig} actions={authActions} {resetToken} initialMode={resetToken ? 'reset' : 'login'} onauthenticated={handleAuthenticated} />
-  </main>
+      {:else if !authenticated}
+        <AuthPanel config={authConfig} actions={authActions} {resetToken} initialMode={resetToken ? 'reset' : 'login'} onauthenticated={handleAuthenticated} />
+{{/if}}
+      {:else}
+        {#await pageComponent}
+          <div class='grid min-h-64 place-items-center'><span class='loading loading-spinner'></span></div>
+        {:then { default: Page }}
+          <Page {nativeRuntime} {nativeTokenStorage} />
+        {/await}
+      {/if}
+    </main>
+    <footer class='border-t border-base-content/8 bg-base-100 p-2 text-center text-xs text-base-content/50'>
+      {appConfig.name} · {appConfig.version} · {appConfig.env}
+    </footer>
+{{#if features.iam}}
+    {#if authenticated && !booting && !bootError}
+{{/if}}
+      <BottomNav items={navItems} active={router.path.slice(1)} onchange={handleTabChange} safeArea centered maxWidth='lg' />
+{{#if features.iam}}
+    {/if}
 {{/if}}
-{:else}
-  <div class='hai-mobile-viewport'>
-    <div class='hai-mobile-shell max-w-lg'>
-      <AppBar title={appConfig.name} safeArea fixed={false} class='bg-base-100/95 backdrop-blur border-base-content/8' />
-
-      <main class='hai-mobile-main'>
-        {#if activeTab === 'home'}
-          <section class='space-y-4 p-4 pb-6'>
-            <div class='bg-primary text-primary-content rounded-2xl p-5 shadow-sm'>
-              <p class='text-sm opacity-75'>{m.hero_eyebrow()}</p>
-              <h1 class='mt-1 text-2xl font-bold'>{m.hero_title()}</h1>
-              <p class='mt-2 text-sm opacity-80'>{m.hero_subtitle()}</p>
-            </div>
-
-            <div class='grid grid-cols-2 gap-3'>
-              <Card padding='sm' shadow='sm'>
-                <div class='flex flex-col gap-2'>
-                  <span class='icon-[tabler--device-mobile-code] text-primary text-2xl'></span>
-                  <span class='text-sm font-medium'>{m.feature_native_title()}</span>
-                  <span class='text-base-content/60 text-xs'>{m.feature_native_desc()}</span>
-                </div>
-              </Card>
-              <Card padding='sm' shadow='sm'>
-                <div class='flex flex-col gap-2'>
-                  <span class='icon-[tabler--api-app] text-primary text-2xl'></span>
-                  <span class='text-sm font-medium'>{m.feature_api_title()}</span>
-                  <span class='text-base-content/60 text-xs'>{m.feature_api_desc()}</span>
-                </div>
-              </Card>
-            </div>
-
-            <Card title={m.status_title()} shadow='sm'>
-              <p class='mb-3 text-xs text-base-content/50'>{appConfig.name} · {appConfig.version} · {appConfig.env}</p>
-              <div class='grid grid-cols-2 gap-3 text-sm'>
-                <div>
-                  <p class='text-base-content/50'>{m.status_api_label()}</p>
-                  <p class='font-medium break-all'>{resolveApiBase()}</p>
-                </div>
-                <div>
-                  <p class='text-base-content/50'>{m.status_runtime_label()}</p>
-                  <Badge variant={nativeRuntime ? 'success' : 'warning'} size='sm'>
-                    {nativeRuntime ? m.status_runtime_native() : m.status_runtime_web()}
-                  </Badge>
-                </div>
-                <div class='col-span-2'>
-                  <p class='text-base-content/50'>{m.status_token_label()}</p>
-                  <p class='font-medium'>{nativeTokenStorage ? m.status_token_native() : m.status_token_memory()}</p>
-                </div>
-              </div>
-            </Card>
-          </section>
-        {:else if activeTab === 'tasks'}
-          <section class='space-y-4 p-4 pb-6'>
-            <Card title={m.tasks_title()} shadow='sm'>
-              <div class='space-y-3'>
-                {#each [m.tasks_sync(), m.tasks_polish(), m.tasks_release()] as task (task)}
-                  <div class='bg-base-200 rounded-xl flex items-center gap-3 p-3'>
-                    <span class='icon-[tabler--circle-check] text-success text-xl'></span>
-                    <span class='text-sm font-medium'>{task}</span>
-                  </div>
-                {/each}
-              </div>
-            </Card>
-          </section>
-        {:else}
-          <section class='space-y-4 p-4 pb-6'>
-            <Card title={m.profile_title()} shadow='sm'>
-              <div class='space-y-3 text-sm'>
-                <div class='bg-base-200 rounded-xl p-3'>{m.profile_language()}</div>
-                <div class='bg-base-200 rounded-xl p-3'>{m.profile_theme()}</div>
-                <div class='bg-base-200 rounded-xl p-3'>{m.profile_secure()}</div>
-              </div>
-            </Card>
-          </section>
-        {/if}
-      </main>
-
-      <BottomNav
-        items={navItems}
-        active={activeTab}
-        onchange={handleTabChange}
-        safeArea
-        centered
-        maxWidth='lg'
-        class='border-base-content/8 shadow-[0_-12px_32px_rgba(15,23,42,0.08)]'
-      />
-    </div>
   </div>
-{/if}
-
+</div>
 <ToastContainer />

package/templates/apps/mobile-app/src/lib/pages/home.svelte.hbs

@@ -0,0 +1,58 @@
+<script lang='ts'>
+  import { resolveApiBase } from '../api.js'
+  import { appConfig } from '../app-config.js'
+  import * as m from '../paraglide/messages.js'
+  /** 首页展示的平台运行状态；例如 { nativeRuntime: true, nativeTokenStorage: true }。 */
+  interface Props {
+    /** 是否运行于原生壳。 */
+    nativeRuntime: boolean
+    /** 是否使用原生安全凭据存储。 */
+    nativeTokenStorage: boolean
+  }
+  const { nativeRuntime, nativeTokenStorage }: Props = $props()
+</script>
+
+<section class='space-y-4 p-4 pb-6'>
+  <div class='bg-primary text-primary-content rounded-2xl p-5 shadow-sm'>
+    <p class='text-sm opacity-75'>{m.hero_eyebrow()}</p>
+    <h1 class='mt-1 text-2xl font-bold'>{m.hero_title()}</h1>
+    <p class='mt-2 text-sm opacity-80'>{m.hero_subtitle()}</p>
+  </div>
+
+  <div class='grid grid-cols-2 gap-3'>
+    <Card padding='sm' shadow='sm'>
+      <div class='flex flex-col gap-2'>
+        <span class='icon-[tabler--device-mobile-code] text-primary text-2xl'></span>
+        <span class='text-sm font-medium'>{m.feature_native_title()}</span>
+        <span class='text-base-content/60 text-xs'>{m.feature_native_desc()}</span>
+      </div>
+    </Card>
+    <Card padding='sm' shadow='sm'>
+      <div class='flex flex-col gap-2'>
+        <span class='icon-[tabler--api-app] text-primary text-2xl'></span>
+        <span class='text-sm font-medium'>{m.feature_api_title()}</span>
+        <span class='text-base-content/60 text-xs'>{m.feature_api_desc()}</span>
+      </div>
+    </Card>
+  </div>
+
+  <Card title={m.status_title()} shadow='sm'>
+    <p class='mb-3 text-xs text-base-content/50'>{appConfig.name} · {appConfig.version} · {appConfig.env}</p>
+    <div class='grid grid-cols-2 gap-3 text-sm'>
+      <div>
+        <p class='text-base-content/50'>{m.status_api_label()}</p>
+        <p class='font-medium break-all'>{resolveApiBase()}</p>
+      </div>
+      <div>
+        <p class='text-base-content/50'>{m.status_runtime_label()}</p>
+        <Badge variant={nativeRuntime ? 'success' : 'warning'} size='sm'>
+          {nativeRuntime ? m.status_runtime_native() : m.status_runtime_web()}
+        </Badge>
+      </div>
+      <div class='col-span-2'>
+        <p class='text-base-content/50'>{m.status_token_label()}</p>
+        <p class='font-medium'>{nativeTokenStorage ? m.status_token_native() : m.status_token_memory()}</p>
+      </div>
+    </div>
+  </Card>
+</section>

package/templates/apps/mobile-app/src/lib/pages/profile.svelte.hbs

@@ -0,0 +1,13 @@
+<script lang='ts'>
+  import * as m from '../paraglide/messages.js'
+</script>
+
+<section class='space-y-4 p-4 pb-6'>
+  <Card title={m.profile_title()} shadow='sm'>
+    <div class='space-y-3 text-sm'>
+      <div class='bg-base-200 rounded-xl p-3'>{m.profile_language()}</div>
+      <div class='bg-base-200 rounded-xl p-3'>{m.profile_theme()}</div>
+      <div class='bg-base-200 rounded-xl p-3'>{m.profile_secure()}</div>
+    </div>
+  </Card>
+</section>

package/templates/apps/mobile-app/src/lib/pages/tasks.svelte.hbs

@@ -0,0 +1,16 @@
+<script lang='ts'>
+  import * as m from '../paraglide/messages.js'
+</script>
+
+<section class='space-y-4 p-4 pb-6'>
+  <Card title={m.tasks_title()} shadow='sm'>
+    <div class='space-y-3'>
+      {#each [m.tasks_sync(), m.tasks_polish(), m.tasks_release()] as task (task)}
+        <div class='bg-base-200 rounded-xl flex items-center gap-3 p-3'>
+          <span class='icon-[tabler--circle-check] text-success text-xl'></span>
+          <span class='text-sm font-medium'>{task}</span>
+        </div>
+      {/each}
+    </div>
+  </Card>
+</section>

package/templates/base/.dockerignore.hbs

@@ -15,3 +15,8 @@ playwright-report
 test-results
 **/data
 *.log
+# 仅排除本机私有配置，与 Git 处理一致；公共 .env 与 dev/test/prod 随上下文构建。
+**/.env.local
+**/.env.*.local
+**/.env.runtime
+**/.hai/deploy

package/templates/base/.gitignore.hbs

@@ -1,19 +1,33 @@
+# 构建产物目录
 node_modules
 {{#unless isSvelteOnlyApp}}
 .svelte-kit
 {{/unless}}
 build
 dist
+.turbo
 android
 ios
-.env
-.env.*
-!.env.example
+**/src/lib/paraglide
+**/src-tauri/gen/
+**/src-tauri/target/
+**/hash-core/target/
+
+# 日志测试目录
 *.log
-.DS_Store
 test-results/
 playwright-report/
+
+
+# 系统文件
+.DS_Store
+
+# 本地数据目录
 **/data/
 
 # hai deploy 产物（compose / .env.runtime / 镜像 tar / sidecar 凭据）
 .hai/
+
+# 本机私有配置；公共 .env 与 dev/test/prod 环境文件纳入版本控制。
+.env.local
+.env.*.local

package/templates/base/Dockerfile.hbs

@@ -1,6 +1,12 @@
 # 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
+ARG HAI_DEPLOY_ENVIRONMENT=prod
+ARG HAI_CORE_ENV=production
+ENV HAI_DEPLOY_ENVIRONMENT=$HAI_DEPLOY_ENVIRONMENT
+ENV HAI_CORE_ENV=$HAI_CORE_ENV
 
 ENV PNPM_HOME=/pnpm
 ENV PATH=$PNPM_HOME:$PATH
@@ -24,6 +30,12 @@ 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
+ENV npm_config_better_sqlite3_binary_host_mirror=$SQLITE_PREBUILD_MIRROR
+ARG HAI_DEPLOY_ENVIRONMENT=prod
+ARG HAI_CORE_ENV=production
+ENV HAI_DEPLOY_ENVIRONMENT=$HAI_DEPLOY_ENVIRONMENT
+ENV HAI_CORE_ENV=$HAI_CORE_ENV
 
 ENV PNPM_HOME=/pnpm
 ENV PATH=$PNPM_HOME:$PATH
@@ -36,12 +48,16 @@ RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store pnpm fetch
 COPY . .
 RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store pnpm install --offline --frozen-lockfile --ignore-scripts
 RUN pnpm build
+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
 
 FROM node:24-bookworm-slim AS runtime-base
+ARG HAI_DEPLOY_ENVIRONMENT=prod
+ARG HAI_CORE_ENV=production
 
 ENV NODE_ENV=production
-ENV HAI_CORE_ENV=production
+ENV HAI_DEPLOY_ENVIRONMENT=$HAI_DEPLOY_ENVIRONMENT
+ENV HAI_CORE_ENV=$HAI_CORE_ENV
 ENV HOST=0.0.0.0
 ENV PORT=3000
 WORKDIR /app

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

@@ -21,14 +21,26 @@ test('home page renders from browser', async ({ page }) => {
   await expect(page).toHaveTitle(process.env.HAI_CORE_NAME ?? '{{projectName}}')
   await expect(pageErrors).toEqual([])
   await expect(page.locator('main, section').first()).toBeVisible()
+  await expect(page.locator('header').first()).toBeVisible()
+  await expect(page.locator('footer').first()).toBeAttached()
 {{#if_eq appType 'h5'}}
   // 在手机宽度验证导航真正切换路由，避免样式失效但首页渲染测试仍通过。
   const nav = page.locator('nav')
   await nav.getByRole('button', { name: /发现|Discover/i, exact: true }).click()
   await expect(page).toHaveURL(/\/discover$/)
+  await page.reload()
+  await expect(page).toHaveURL(/\/discover$/)
+  await expect(page.getByRole('heading', { name: /发现|Discover/i })).toBeVisible()
   await nav.getByRole('button', { name: /首页|Home/i, exact: true }).click()
   await expect(page).toHaveURL(/\/$/)
   expect(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth)).toBe(true)
+{{/if_eq}}
+{{#if_eq appType 'website'}}
+  await page.goto('/about')
+  await page.reload()
+  await expect(page).toHaveURL(/\/about$/)
+  await expect(page.locator('header')).toBeVisible()
+  await expect(page.locator('footer')).toBeVisible()
 {{/if_eq}}
   const evidence = process.env.HAI_AUTH_EVIDENCE_DIR || path.resolve('test-results/auth-screenshots')
   await mkdir(evidence, { recursive: true })
@@ -50,6 +62,8 @@ test('configured IAM registration and password login', async ({ page, context })
   const authUrl = '{{#if isCapacitorApp}}/{{else}}/auth/login{{/if}}'
   await page.goto(authUrl)
   await expect(page.locator('#login-username')).toBeVisible()
+  await expect(page.locator('header').first()).toBeVisible()
+  await expect(page.locator('footer')).toBeVisible()
   await page.screenshot({ path: path.join(evidence, '{{projectName}}-login.png'), fullPage: true })
   await page.getByRole('{{#if isCapacitorApp}}button{{else}}link{{/if}}', { name: /立即注册|Register now/i }).click()
   await expect(page.locator('input[name="username"]')).toBeVisible()

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.63",
+  "version": "0.1.0-alpha.65",
   "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}}",
@@ -21,11 +21,20 @@
     "paraglide:compile": "paraglide-js compile --project ./project.inlang --outdir ./src/lib/paraglide",
 {{/if}}
     "dev": "vite dev",
+    "dev:test": "vite dev --mode test",
+    "dev:prod": "vite dev --mode prod",
     "build": "{{#if hasI18n}}pnpm paraglide:compile && {{/if}}vite build",
+    "build:prod": "{{#if hasI18n}}pnpm paraglide:compile && {{/if}}vite build --mode prod",
+{{#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",
+    "start:prod": "pnpm start",
+{{/unless}}
     "preview": "vite preview",
-    "check": "{{#if hasI18n}}pnpm paraglide:compile && {{/if}}{{#if isSvelteOnlyApp}}svelte-check --tsconfig ./tsconfig.json{{else}}svelte-kit sync && svelte-check --tsconfig ./tsconfig.json{{/if}}",
+    "check": "pnpm typecheck",
     "typecheck": "{{#if hasI18n}}pnpm paraglide:compile && {{/if}}{{#if isSvelteOnlyApp}}svelte-check --tsconfig ./tsconfig.json{{else}}svelte-kit sync && svelte-check --tsconfig ./tsconfig.json{{/if}}",
     "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
     "test": "{{#if hasI18n}}pnpm paraglide:compile && {{/if}}vitest run",
     "test:watch": "vitest",
     "test:e2e": "playwright test",
@@ -79,6 +88,9 @@
 {{/if}}
   },
   "devDependencies": {
+{{#if isSvelteOnlyApp}}
+    "@h-ai/core": "{{haiPackageSpecifier}}",
+{{/if}}
     "@antfu/eslint-config": "{{versions.antfuEslintConfig}}",
     "@playwright/test": "{{versions.playwright}}",
 {{#if isCapacitorApp}}

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

@@ -3,6 +3,9 @@ import type { CoreConfig } from '@h-ai/core'
 {{/unless}}
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
+{{#unless isSvelteOnlyApp}}
+import process from 'node:process'
+{{/unless}}
 import { fileURLToPath } from 'node:url'
 {{#unless isSvelteOnlyApp}}
 import { core } from '@h-ai/core'
@@ -43,9 +46,12 @@ describe('generated scaffold', () => {
 {{#unless isCapacitorApp}}
 
   it('ships an application config loaded at startup', async () => {
-    const coreConfig = await readFile(join(rootDir, 'config/_core.yml'), 'utf-8')
-    expect(coreConfig).toContain('name: {{projectName}}')
-    expect(coreConfig).toContain('defaultLocale: {{defaultLocale}}')
+    const result = core.config.load<CoreConfig>('core', join(rootDir, 'config/_core.yml'))
+    expect(result.success).toBe(true)
+    if (!result.success)
+      return
+    expect(result.data.name).toBe(process.env.HAI_CORE_NAME ?? '{{projectName}}')
+    expect(result.data.defaultLocale).toBe(process.env.HAI_CORE_DEFAULTLOCALE ?? '{{defaultLocale}}')
   })
 {{/unless}}
 {{#unless isSvelteOnlyApp}}

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

@@ -6,9 +6,7 @@ import type { CoreConfig } from '@h-ai/core'
 {{/if}}
 import path from 'node:path'
 import process from 'node:process'
-{{#if isSvelteOnlyApp}}
 import { core } from '@h-ai/core'
-{{/if}}
 {{#if hasUi}}
 import { haiOptimizeExclude, haiPrebundledDeps } from '@h-ai/ui/vite'
 {{/if}}
@@ -23,10 +21,13 @@ import { sveltekit } from '@sveltejs/kit/vite'
 {{#if hasUi}}
 import tailwindcss from '@tailwindcss/vite'
 {{/if}}
-import { defineConfig, loadEnv } from 'vite'
+import { defineConfig } from 'vite'
 
 export default defineConfig(({ mode }) => {
-  const env = loadEnv(mode, process.cwd(), '')
+  const envResult = core.config.loadEnvFiles({ mode, envDir: process.cwd() })
+  if (!envResult.success)
+    throw new Error(envResult.error.message)
+  const env = envResult.data
   Object.assign(process.env, env)
 {{#if isSvelteOnlyApp}}
   // 浏览器无法读取 YAML；构建时通过 core 解析，仅注入明确可公开的字段。
@@ -42,6 +43,7 @@ export default defineConfig(({ mode }) => {
 {{/if}}
 
   return {
+    envDir: false,
     envPrefix: ['VITE_', 'PUBLIC_'],
 {{#if isSvelteOnlyApp}}
     define: { __APP_CORE_CONFIG__: JSON.stringify(appConfig) },

package/templates/shared/hash-router.svelte.ts

@@ -0,0 +1,83 @@
+import { SvelteMap, SvelteURL } from 'svelte/reactivity'
+
+/**
+ * 页面目录驱动的 hash 导航；仅管理 URL，不包含业务权限或页面加载逻辑。
+ * @example
+ * ```ts
+ * const pages = import.meta.glob('../pages/*.svelte')
+ * const router = new HashRouter(Object.keys(pages), '/home')
+ * const stop = router.start(() => void loadCurrentPage())
+ * router.navigate('/reports/weekly?period=month')
+ * stop()
+ * ```
+ */
+export class HashRouter {
+  /** 当前页面路径，例如 `/reports/weekly`。 */
+  path = $state('')
+  /** 当前页面查询串，例如 `?period=month`。 */
+  search = $state('')
+  private readonly files = new SvelteMap<string, string>()
+
+  private readonly fallback: string
+
+  /**
+   * 建立页面文件到 URL 的映射，新增页面无需维护路由表。
+   * @param pageFiles - import.meta.glob 返回的文件名
+   * @param fallback - 空路径和未知页面的回退路径
+   * @example new HashRouter(Object.keys(import.meta.glob('../pages/*.svelte')), '/home')
+   */
+  constructor(pageFiles: string[], fallback: string) {
+    this.fallback = fallback
+    for (const file of pageFiles) {
+      const route = file.replace(/^.*\/pages/, '').replace(/\.svelte$/, '').replace(/\/index$/, '') || '/'
+      this.files.set(route, file)
+    }
+    if (!this.files.has(fallback))
+      throw new Error('Hash router fallback page is missing')
+    this.path = fallback
+  }
+
+  /** 当前路径对应的页面文件；可用于索引 import.meta.glob 的惰性加载器。 */
+  get file(): string {
+    return this.files.get(this.path) ?? this.files.get(this.fallback)!
+  }
+
+  /**
+   * 恢复地址栏状态并监听链接、前进与后退；卸载时调用返回的清理函数。
+   * @param onChange - URL 导航完成后的业务通知
+   * @returns 移除事件监听器的函数
+   * @example const stop = router.start(() => void store.navigate(router.path.slice(1)))
+   */
+  start(onChange: () => void = () => {}): () => void {
+    const synchronize = () => {
+      this.navigate(location.hash.slice(1), true)
+      onChange()
+    }
+    synchronize()
+    window.addEventListener('hashchange', synchronize)
+    return () => {
+      window.removeEventListener('hashchange', synchronize)
+    }
+  }
+
+  /**
+   * 导航到页面；未知路径回退，查询串随 hash 保留并可在刷新后恢复。
+   * @param target - 以 `/` 开头的本地页面路径和查询串
+   * @param replace - 是否替换当前历史项
+   * @example router.navigate('/settings?section=profile')
+   */
+  navigate(target: string, replace = false): void {
+    const local = target.startsWith('/') && !target.startsWith('//') && !target.includes('\\')
+    const url = new SvelteURL(local ? target : this.fallback, 'https://hash.invalid')
+    const known = this.files.has(url.pathname)
+    this.path = known ? url.pathname : this.fallback
+    this.search = known ? url.search : ''
+    const hash = `#${this.path}${this.search}`
+    if (location.hash !== hash) {
+      if (replace)
+        history.replaceState(history.state, '', hash)
+      else
+        history.pushState(history.state, '', hash)
+    }
+  }
+}

package/templates/skills/AGENTS.md

@@ -2,13 +2,20 @@
 
 > 通用 AI 编程助手入口。优先阅读 `README.md`、现有测试与 `.agents/skills/`；本文件同时作为 `hai add` / AI 支持回填时的 generic fallback。
 
+## 需求与模板
+
+- 业务行为以用户当前明确要求及其指定的需求/设计文档为准。本文件、README、skills、示例、生成代码及其测试中的模板默认行为是起点，不是不可变的业务约束；角色代码、权限模型、页面流程、字段、限额、存储方式与架构均可按实际需求调整。
+- 需求与模板不同，审查时记录为模板适配项，不据此判定需求错误或阻塞审查，也不要求用户额外授权“覆盖模板”；实施时在已有授权范围内修改或移除冲突逻辑，并同步 contract、鉴权、数据迁移、界面、配置、测试、文档及本文件中的过期规则。
+- 未说明的行为可参考现有实现并注明假设，不能升级为强制需求。只有业务要求自身矛盾、与已确认项目决策的优先级不明，或存在真实技术/安全障碍时才提出具体问题；已明确的规则不重复要求选择。
+- 业务规则与技术契约分别判断：可用 API 以当前安装版本的公开类型为准；输入校验、服务端授权、资源隔离和密钥保护仍须落实。需求涉及替换技术方案时说明影响并同步迁移，不能用保留模板默认值代替解决问题。
+
 ## 行为契约
 
 需求/设计文档审查或从文档生成代码时，读取 [hai-spec-review](.agents/skills/hai-spec-review/SKILL.md)，严格确认完备性、歧义、技术正确性与命名一致性；影响行为的问题未解决前不判定文档可生成。普通小改动不重审无关文档。
 
 升级 hai-framework 到最新/指定版本、比较版本差异或同步框架 skills 时，先读 [框架升级与同步 Skill](.agents/skills/hai-framework-sync/SKILL.md)，执行版本发现、差异分析、用户选择/阻塞处理、迁移与验证；仅要求比较时不修改应用。
 
-根据文档规划、实施、继续或返修任务时，读取 [hai-spec-implement](.agents/skills/hai-spec-implement/SKILL.md)：审查后按可验收功能和依赖拆分，维护 docs 下的清单及 docs/tasks 下的任务信息，每项独立分支 TDD、验证并本地合并；返修复用原任务与分支。仅规划不实施，指定任务先核验依赖。
+根据文档规划、实施、继续、返修或按已提交文档变更同步实现时，读取 [hai-spec-implement](.agents/skills/hai-spec-implement/SKILL.md)：维护 docs 清单与任务记录，比较已验收与目标文档 Git 快照，更新原任务或新建任务，每项独立分支 TDD、验证并本地合并；全部差异与整体验收通过后才推进基线。返修复用原任务与分支。仅规划不实施，指定任务先核验依赖。
 
 普通新增、修改、修复任务开始前，先读 [应用开发 Skill](.agents/skills/hai-app-create/SKILL.md) 和 [开发规范与框架能力路由](.agents/skills/hai-app-create/development.md)；再按任务读取模块 Skill 及其相邻参考文件。架构/构建、审查、测试分别读取 hai-build、hai-app-review、hai-app-tests，不加载整个 skill 树。
 
@@ -36,6 +43,13 @@
 3. 改动公共类型、配置、模板或共享逻辑时，同步更新所有调用方与文档。
 4. 每次改动后按影响范围运行质量门禁并记录结果。
 
+## 代码注释与示例
+
+- 尽可能补充有信息量的中文 JSDoc：所有 export 的函数/类/方法、核心算法与业务流程、所有数据库表/列、接口/type/schema 及其字段都必须说明用途、单位、约束和关联关系。核心逻辑解释决策原因、边界、权限与失败路径，不逐行复述代码。
+- 函数按实际契约写 @param、@returns，仅确实抛错时写 @throws；异步、HaiResult 与事务失败行为须说明。类型/表结构说明字段含义、可空性、默认值、主外键和唯一约束。
+- 上述函数和结构的 JSDoc 均提供可理解的 @example：函数给调用及结果判断，结构给合法数据，表给典型行或查询示例。省略上下文要标明，不使用真实凭据。示例随实现同步，不能只堆叠没有信息量的注释。
+- 调用及结构示例见 [.agents/skills/hai-app-create/development.md](.agents/skills/hai-app-create/development.md) 的 JSDoc 注释一节。
+
 ## 质量门禁
 
 先核对 package.json，按影响范围执行已有脚本；文档检查引用，UI/路由变更再运行 E2E。未运行项说明原因。