@h-ai/cli 0.1.0-alpha9 → 1.0.0-beta.2

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,
   })
@@ -31,6 +30,10 @@ export const POST: RequestHandler = async ({ request, params }) => {
     return new Response('FAIL', { status: 500 })
   }
 
+  // 此模板仅确认已验签解析；success 不代表已付款，Stripe 延迟付款会返回 pending。
+  // 业务接入时须在响应成功前，用共享数据库核对订单/金额/币种，按 eventId 去重并防止状态倒退；
+  // 仅 status=paid 可触发履约，不在进程内 Set/Map 中维护通知去重。
+
   // 微信支付要求返回 JSON，支付宝要求返回 "success"
   if (provider === 'wechat') {
     return new Response(JSON.stringify({ code: 'SUCCESS', message: '' }), {

package/templates/features/storage/routes/api/upload/+server.ts

@@ -2,28 +2,30 @@
  * 文件上传 API — storage 功能示例
  */
 import type { RequestHandler } from './$types'
+import { core } from '@h-ai/core'
 import { kit } from '@h-ai/kit'
 import { storage } from '@h-ai/storage'
 
-export const POST: RequestHandler = async ({ request, locals }) => {
+export const POST: RequestHandler = kit.handler(async ({ request, locals }) => {
   const formData = await request.formData()
-  const file = formData.get('file') as File | null
+  const file = formData.get('file')
 
-  if (!file) {
-    return kit.response.badRequest('No file provided')
+  if (!(file instanceof File) || file.size === 0 || file.size > 10 * 1024 * 1024) {
+    return kit.response.badRequest(core.i18n.coreM('core_errorValidation'), locals.requestId)
   }
 
   const { Buffer } = await import('node:buffer')
   const buffer = Buffer.from(await file.arrayBuffer())
-  const key = `uploads/${Date.now()}-${file.name}`
+  // 路径由服务端生成，用户文件名仅作为元数据保存。
+  const key = `uploads/${core.id.uuid()}`
 
-  const result = await storage.put(key, buffer, {
+  const result = await storage.file.put(key, buffer, {
     contentType: file.type,
     metadata: { originalName: file.name },
   })
 
   if (!result.success) {
-    return kit.response.internalError(result.error.message)
+    return kit.response.fromError(result.error, locals.requestId)
   }
 
   return kit.response.ok({
@@ -32,4 +34,4 @@ export const POST: RequestHandler = async ({ request, locals }) => {
     size: file.size,
     type: file.type,
   }, locals.requestId)
-}
+})

package/templates/i18n/project.inlang/settings.json

@@ -1,9 +1,9 @@
 {
   "$schema": "https://inlang.com/schema/project-settings",
   "baseLocale": "zh-CN",
-  "locales": ["zh-CN", "en-US"],
+  "locales": ["zh-CN", "en-US", "ja-JP"],
   "modules": [
-    "../../node_modules/@inlang/plugin-message-format/dist/index.js"
+    "./node_modules/@inlang/plugin-message-format/dist/index.js"
   ],
   "plugin.inlang.messageFormat": {
     "pathPattern": "./messages/{locale}.json"

package/templates/shared/.gitattributes

@@ -0,0 +1,11 @@
+# Windows 构建机交付 Linux 启动脚本时必须保留 LF，避免 /bin/sh 解释器失效。
+*.sh text eol=lf
+*.sh.hbs text eol=lf
+*.envsh text eol=lf
+*.envsh.hbs text eol=lf
+
+# Linux 容器引擎读取忽略规则和构建文件时统一使用 LF。
+.dockerignore text eol=lf
+*.dockerignore text eol=lf
+Dockerfile text eol=lf
+*.Dockerfile text eol=lf

package/templates/shared/build-metadata.ts

@@ -0,0 +1,42 @@
+import { execFileSync } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import process from 'node:process'
+
+/** 当前编译目标的私有产物身份；同一 SSR 构建重入复用身份，各端版本来自自己的 manifest。 */
+export function resolveBuildMetadata(directory: string): { appVersion: string, buildId: string, commit: string } {
+  const manifest: { version?: unknown } = JSON.parse(readFileSync(join(directory, 'package.json'), 'utf8'))
+  const appVersion = typeof manifest.version === 'string' && manifest.version.trim() ? manifest.version.trim() : 'unknown'
+  if (appVersion.length > 128)
+    throw new Error('Invalid package.json version: maximum length is 128')
+  const suppliedId = process.env.HAI_BUILD_ID?.trim()
+  if (process.env.HAI_BUILD_ID !== undefined && !/^[\w.+-]{1,128}$/.test(suppliedId ?? ''))
+    throw new Error('Invalid HAI_BUILD_ID: expected 1–128 letters, digits, underscores, dots, plus or minus signs')
+  const buildId = suppliedId ?? randomUUID()
+  const suppliedCommit = process.env.HAI_BUILD_COMMIT?.trim()
+  if (process.env.HAI_BUILD_COMMIT !== undefined && !/^(?:[a-f\d]{40}|[a-f\d]{64}|unknown)$/i.test(suppliedCommit ?? ''))
+    throw new Error('Invalid HAI_BUILD_COMMIT: expected a full Git SHA or unknown')
+  const commit = suppliedCommit ?? sourceCommit(directory)
+  // SvelteKit 在同一构建进程内重新求值 Vite 配置；不依赖临时配置模块缓存。
+  process.env.HAI_BUILD_ID = buildId
+  process.env.HAI_BUILD_COMMIT = commit
+  return { appVersion, buildId, commit }
+}
+
+/** 未跟踪的生成工程不能把临时目录的父框架提交冒充自身源码。 */
+function sourceCommit(directory: string): string {
+  try {
+    const options = { cwd: directory, encoding: 'utf8' as const, stdio: 'pipe' as const, windowsHide: true }
+    const root = execFileSync('git', ['rev-parse', '--show-toplevel'], options).trim()
+    const manifest = relative(root, join(directory, 'package.json')).replaceAll('\\', '/')
+    if (manifest.startsWith('../'))
+      return 'unknown'
+    execFileSync('git', ['ls-files', '--error-unmatch', '--', manifest], { ...options, cwd: root })
+    const commit = execFileSync('git', ['rev-parse', 'HEAD'], options).trim()
+    return /^(?:[a-f\d]{40}|[a-f\d]{64})$/i.test(commit) ? commit : 'unknown'
+  }
+  catch {
+    return 'unknown'
+  }
+}

package/templates/shared/container-runtime-config.sh

@@ -0,0 +1,30 @@
+#!/bin/sh
+set -eu
+
+# 只编码公开白名单；Base64 不会把环境值中的引号或换行解释为 JavaScript。
+encode() { printf '%s' "$1" | base64 | tr -d '\n'; }
+mkdir -p /tmp/hai-runtime-config
+cat > /tmp/hai-runtime-config/runtime-config.js <<EOF
+{
+  const decode = value => new TextDecoder().decode(Uint8Array.from(atob(value), character => character.charCodeAt(0)));
+  const nonempty = object => Object.fromEntries(Object.entries(object).filter(([, value]) => value !== ''));
+  const core = nonempty({
+    name: decode('$(encode "${HAI_CORE_NAME:-}")'),
+    version: decode('$(encode "${HAI_CORE_VERSION:-}")'),
+    env: decode('$(encode "${HAI_CORE_ENV:-}")'),
+    defaultLocale: decode('$(encode "${HAI_CORE_DEFAULTLOCALE:-}")')
+  });
+  const logging = nonempty({
+    level: decode('$(encode "${HAI_CORE_LOGGING_LEVEL:-}")'),
+    format: decode('$(encode "${HAI_CORE_LOGGING_FORMAT:-}")')
+  });
+  if (Object.keys(logging).length) core.logging = logging;
+  const config = nonempty({
+    apiBase: decode('$(encode "${PUBLIC_API_BASE:-}")'),
+    apiTransport: decode('$(encode "${PUBLIC_API_TRANSPORT:-}")'),
+    apiKeyExchangePath: decode('$(encode "${PUBLIC_API_KEY_EXCHANGE_PATH:-}")')
+  });
+  if (Object.keys(core).length) config.core = core;
+  globalThis.__HAI_PUBLIC_CONFIG__ = { ...globalThis.__HAI_PUBLIC_CONFIG__, ...config };
+}
+EOF

package/templates/shared/e2e-env.ts

@@ -0,0 +1,98 @@
+import { createECDH } from 'node:crypto'
+import { isAbsolute } from 'node:path'
+import process from 'node:process'
+
+/**
+ * 仅给 Playwright 的服务子进程装配环境；不修改测试进程和 pnpm/Turbo 的环境。
+ * @param profile - 本轮测试明确选择的模块配置和可信控制值。
+ * @returns Playwright webServer.env；undefined 项由 Node spawn 从子进程环境中移除。
+ * @throws 缺少绝对数据目录，或 API 指向非本轮 loopback HTTP 夹具时抛错。
+ * @example
+ * ```ts
+ * // 测试内部上下文；数据目录由 run-e2e 为本轮分配。
+ * const env = createE2eServerEnv({
+ *   HAI_E2E_DATA_ROOT: process.cwd(),
+ *   HAI_CACHE: JSON.stringify({ type: 'memory' }),
+ * })
+ * if (env.HAI_E2E !== '1') throw new Error('E2E profile was not applied')
+ * ```
+ */
+export function createE2eServerEnv(profile: Record<string, string>): Record<string, string> {
+  const dataRoot = profile.HAI_E2E_DATA_ROOT || process.env.HAI_E2E_DATA_ROOT
+  if (!dataRoot || !isAbsolute(dataRoot))
+    throw new Error('Run E2E through the managed entrypoint with its own absolute HAI_E2E_DATA_ROOT')
+  if (profile.PUBLIC_API_BASE) {
+    const api = new URL(profile.PUBLIC_API_BASE)
+    if (api.protocol !== 'http:' || !['127.0.0.1', 'localhost', '[::1]'].includes(api.hostname) || api.username || api.password)
+      throw new Error('E2E API must use an unauthenticated loopback HTTP fixture')
+  }
+  const environment: Record<string, string | undefined> = Object.fromEntries(
+    Object.keys(process.env).filter(key => /^(?:HAI_|PUBLIC_|VITE_)/i.test(key)).map(key => [key, undefined]),
+  )
+  for (const name of ['HAI_E2E_DATA_ROOT', 'HAI_AUTH_EVIDENCE_DIR', 'HAI_CORE_NAME', 'HAI_CORE_VERSION']) {
+    if (process.env[name] !== undefined)
+      environment[name] = process.env[name]
+  }
+  Object.assign(environment, { HAI_E2E: '1', NODE_ENV: 'test', HAI_E2E_DATA_ROOT: dataRoot }, profile)
+  // Playwright 声明仅接受 string，但其 WebServer 合并 env 后直接交 Node spawn；
+  // 已用安装版真实 WebServer 验证 undefined 会删除继承项，因此仅在第三方类型边界使用窄断言。
+  return environment as Record<string, string>
+}
+
+/**
+ * 每轮生成独立可信 SM2 ring；私钥只传服务子进程，不进入公开配置或报告。
+ * @returns 符合 transport serverKeyRing 配置的 JSON 字符串。
+ * @throws 当前 Node/OpenSSL 不支持 SM2 时抛错，不降级为不可信握手。
+ * @example
+ * ```ts
+ * // 测试内部上下文；仅交给本轮服务子进程。
+ * const env = createE2eServerEnv({
+ *   HAI_E2E_DATA_ROOT: process.cwd(),
+ *   HAI_CRYPTO_TRANSPORT_SERVERKEYRING: createE2eTransportRing(),
+ * })
+ * if (!env.HAI_CRYPTO_TRANSPORT_SERVERKEYRING) throw new Error('Trusted ring is required')
+ * ```
+ */
+export function createE2eTransportRing(): string {
+  const key = createECDH('SM2')
+  key.generateKeys()
+  return JSON.stringify({ activeKeyId: 'e2e-v1', keys: { 'e2e-v1': {
+    publicKey: key.getPublicKey('hex'),
+    privateKey: key.getPrivateKey('hex').padStart(64, '0'),
+  } } })
+}
+
+/**
+ * 只把既有的本轮 loopback 通知夹具控制地址转成明确 Reach 配置。
+ * @returns 未启用通知夹具时为空对象；启用时包含 OTP、模板及协议配置。
+ * @throws IAM_NOTIFICATION_URL 不是无凭据的 loopback HTTP 地址时抛错。
+ * @example
+ * ```ts
+ * // 测试内部上下文；IAM_NOTIFICATION_URL 由样板门禁启动的通知夹具提供。
+ * const env = createE2eServerEnv({
+ *   ...createE2eNotificationEnv(),
+ *   HAI_E2E_DATA_ROOT: process.cwd(),
+ * })
+ * if (env.HAI_E2E !== '1') throw new Error('Notification profile was not isolated')
+ * ```
+ */
+export function createE2eNotificationEnv(): Record<string, string> {
+  const address = process.env.IAM_NOTIFICATION_URL
+  if (!address)
+    return {}
+  const url = new URL(address)
+  if (url.protocol !== 'http:' || !['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname) || url.username || url.password)
+    throw new Error('E2E notification fixture must use an unauthenticated loopback HTTP address')
+  return {
+    HAI_IAM_LOGIN_OTP: 'true',
+    HAI_IAM_PASSWORDRESET_ENABLED: 'true',
+    HAI_REACH_PROVIDERS: JSON.stringify(['email', 'sms'].map(name => ({ name, type: 'api', url: new URL('/send', url).href }))),
+    HAI_REACH_TEMPLATES: JSON.stringify([
+      { name: 'otp_email', provider: 'email', body: 'Code: {code}' },
+      { name: 'otp_sms', provider: 'sms', body: 'Code: {code}' },
+      { name: 'password_reset', provider: 'email', body: 'Reset: {token}' },
+      { name: 'password_reset_sms', provider: 'sms', body: 'Reset: {token}' },
+    ]),
+    HAI_IAM_AGREEMENTS: JSON.stringify({ showOnRegister: true, showOnLogin: true, userAgreementMarkdown: '# Configured registration agreement\n\n**Registration terms**\n\n- Keep your account credentials secure.', userAgreementUrl: new URL('/terms', url).href, privacyPolicyUrl: new URL('/privacy', url).href }),
+  }
+}

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/shared/public-base-path.mjs

@@ -0,0 +1,19 @@
+/** 公开的网站挂载目录；只读取显式构建值，不加载私有环境文件。 */
+import process from 'node:process'
+import { core } from '@h-ai/core'
+
+const basePathMessage = core.i18n.createMessageGetter({
+  'zh-CN': { invalid: 'PUBLIC_BASE_PATH须为空或以/开头的站内目录；不允许外部地址、末尾/、查询、片段或路径逃逸。' },
+  'en-US': { invalid: 'PUBLIC_BASE_PATH must be empty or a site-local directory beginning with /. External URLs, trailing /, queries, fragments and path traversal are not allowed.' },
+  'ja-JP': { invalid: 'PUBLIC_BASE_PATHは空、または/で始まるサイト内ディレクトリーです。外部URL、末尾の/、クエリー、フラグメント、パス逸脱は使えません。' },
+})
+
+/** @param {string} [value] - 无末尾斜杠的公开目录；空字符串表示域名根目录。 */
+export function resolvePublicBasePath(value = process.env.PUBLIC_BASE_PATH ?? '') {
+  if (value && (!/^\/[\w.-]+(?:\/[\w.-]+)*$/.test(value) || value.split('/').some(segment => segment === '.' || segment === '..'))) {
+    const language = [process.env.HAI_CORE_DEFAULTLOCALE, process.env.LC_ALL, process.env.LC_MESSAGES, process.env.LANG].find(item => item?.trim())?.split(/[_.-]/)[0]?.toLowerCase()
+    const locale = language === 'en' || language === 'c' || language === 'posix' ? 'en-US' : language === 'ja' ? 'ja-JP' : 'zh-CN'
+    throw new Error(basePathMessage('invalid', { locale }))
+  }
+  return value
+}

package/templates/shared/run-e2e.mjs

@@ -0,0 +1,104 @@
+/** 运行浏览器验收，保留本轮证据；退出后仅回收本轮服务数据，失败和中断同样处理。 */
+import { spawn } from 'node:child_process'
+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import process from 'node:process'
+
+const cwd = process.cwd()
+const require = createRequire(resolve(cwd, 'package.json'))
+const cli = require.resolve('@playwright/test/cli')
+const dataParent = resolve(process.env.HAI_E2E_DATA_ROOT || tmpdir())
+mkdirSync(dataParent, { recursive: true })
+const dataRoot = mkdtempSync(join(dataParent, 'hai-browser-e2e-'))
+const groups = [[]]
+for (const argument of process.argv.slice(2)) {
+  if (argument === '--next')
+    groups.push([])
+  else
+    groups.at(-1).push(argument)
+}
+let child
+let interrupted = false
+let stopping
+/**
+ * 结束本轮 Playwright；Windows 同时结束其进程树，finally 等待该命令退出后才清理数据。
+ * @returns {void} 终止请求由 child 退出事件和 stopping Promise 确认。
+ * @example 模块内部信号处理
+ * ```js
+ * process.once('SIGTERM', stop)
+ * ```
+ */
+function stop() {
+  if (interrupted)
+    return
+  interrupted = true
+  if (process.platform === 'win32' && child?.pid && child.exitCode === null) {
+    // Windows 的 kill 不传递 SIGTERM；同时结束本次 Playwright 创建的浏览器与服务进程。
+    stopping = new Promise((resolve) => {
+      const killer = spawn('taskkill', ['/pid', String(child.pid), '/t', '/f'], { windowsHide: true, stdio: 'ignore' })
+      killer.once('error', () => {
+        child?.kill()
+        resolve()
+      })
+      killer.once('exit', resolve)
+    })
+  }
+  else {
+    child?.kill()
+  }
+}
+process.once('SIGINT', stop)
+process.once('SIGTERM', stop)
+try {
+  // 证据与临时业务数据分开；每组使用独立输出，后续 Playwright 不会清空前组证据。
+  const evidenceParent = resolve(process.env.HAI_AUTH_EVIDENCE_DIR || join(cwd, 'test-results'))
+  mkdirSync(evidenceParent, { recursive: true })
+  const runRoot = mkdtempSync(join(evidenceParent, 'run-'))
+  for (const [index, args] of groups.entries()) {
+    const groupRoot = join(runRoot, `group-${index + 1}`)
+    const groupDataRoot = join(dataRoot, `group-${index + 1}`)
+    mkdirSync(groupDataRoot)
+    const hasOutput = args.some(argument => argument === '--output' || argument.startsWith('--output='))
+    const outputArgs = hasOutput ? [] : ['--output', join(groupRoot, 'results')]
+    const html = process.env.PLAYWRIGHT_HTML_OUTPUT_DIR || process.env.PLAYWRIGHT_HTML_REPORT
+    const code = await new Promise((resolve, reject) => {
+      child = spawn(process.execPath, [cli, 'test', ...args, ...outputArgs], {
+        cwd,
+        windowsHide: true,
+        stdio: 'inherit',
+        env: {
+          ...process.env,
+          ...(!html ? { PLAYWRIGHT_HTML_OUTPUT_DIR: join(groupRoot, 'html') } : {}),
+          HAI_AUTH_EVIDENCE_DIR: process.env.HAI_AUTH_EVIDENCE_DIR || join(groupRoot, 'evidence'),
+          HAI_E2E_DATA_ROOT: groupDataRoot,
+        },
+      })
+      child.once('error', reject)
+      child.once('exit', resolve)
+    })
+    // 配置组互相独立，普通失败继续收集；保留首个失败码，中断才停止后续组。
+    if (code !== 0)
+      process.exitCode ||= typeof code === 'number' && code !== 0 ? code : 1
+    if (interrupted) {
+      process.exitCode ||= 1
+      break
+    }
+  }
+}
+finally {
+  process.removeListener('SIGINT', stop)
+  process.removeListener('SIGTERM', stop)
+  await stopping
+  // Playwright 退出后服务进程已关闭，此时删除 SQLite / storage，避免 Windows 文件锁。
+  try {
+    rmSync(dataRoot, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 })
+  }
+  catch (error) {
+    process.stderr.write(`E2E data cleanup failed: ${error instanceof Error ? error.message : String(error)}\n`)
+    // 清理错误不能把原始失败（如 exit 7）覆盖成另一状态，也不能让成功变为假成功。
+    if (!process.exitCode)
+      process.exitCode = 1
+  }
+}

package/templates/shared/vite-runtime-config.ts

@@ -0,0 +1,56 @@
+/** Vite 开发与预览的公开运行配置；同一份静态构建可连接不同环境的 API。 */
+import type { CoreConfig } from '@h-ai/core'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { Plugin } from 'vite'
+
+/** 只允许浏览器可见的地址、开关和品牌字段，禁止传入 process.env 或完整服务配置。 */
+export interface PublicRuntimeConfig {
+  /** 包含 API 前缀的公开地址，例如 https://example.test/api/v1。 */
+  apiBase?: string
+  /** 客户端传输开关，与服务端一致。 */
+  apiTransport?: string
+  /** 公开密钥交换端点。 */
+  apiKeyExchangePath?: string
+  /** 客户端公开元数据；不含密钥或连接参数。 */
+  core?: Pick<CoreConfig, 'name' | 'version' | 'env' | 'defaultLocale'> & { logging?: Pick<NonNullable<CoreConfig['logging']>, 'level' | 'format'> }
+}
+
+/**
+ * 在加载应用前提供无缓存的公开配置；构建只复制空的占位文件。
+ * @example `plugins: [publicRuntimeConfig({ apiBase: process.env.PUBLIC_API_BASE })]`
+ */
+export function publicRuntimeConfig(config: PublicRuntimeConfig): Plugin {
+  const metadata = config.core
+  // 明确投影字段，JavaScript 调用方即使误传完整配置也不能公开连接参数或密钥。
+  const publicConfig: PublicRuntimeConfig = {
+    apiBase: config.apiBase,
+    apiTransport: config.apiTransport,
+    apiKeyExchangePath: config.apiKeyExchangePath,
+    core: metadata
+      ? {
+          name: metadata.name,
+          version: metadata.version,
+          env: metadata.env,
+          defaultLocale: metadata.defaultLocale,
+          logging: metadata.logging ? { level: metadata.logging.level, format: metadata.logging.format } : undefined,
+        }
+      : undefined,
+  }
+  const body = `globalThis.__HAI_PUBLIC_CONFIG__ = { ...globalThis.__HAI_PUBLIC_CONFIG__, ...${JSON.stringify(publicConfig)} };\n`
+  const respond = (_request: IncomingMessage, response: ServerResponse): void => {
+    response.setHeader('Content-Type', 'application/javascript; charset=utf-8')
+    response.setHeader('Cache-Control', 'no-store')
+    response.end(body)
+  }
+  return {
+    name: 'hai-public-runtime-config',
+    configureServer(server) {
+      const base = server.config.base.startsWith('/') ? server.config.base : '/'
+      server.middlewares.use(`${base}runtime-config.js`, respond)
+    },
+    configurePreviewServer(server) {
+      const base = server.config.base.startsWith('/') ? server.config.base : '/'
+      server.middlewares.use(`${base}runtime-config.js`, respond)
+    },
+  }
+}

package/templates/skills/AGENTS.md

@@ -1,26 +1,85 @@
 # AGENTS.md
 
-> 通用 AI 编程助手指引。详细 Skill 文件位于 `.agents/skills/` 目录。
+> 通用 AI 编程助手入口。优先阅读 `README.md`、现有测试与 `.agents/skills/`；本文件同时作为 `hai add` / AI 支持回填时的 generic fallback。
+
+## 需求与模板
+
+- 业务行为以用户当前明确要求及其指定的需求/设计文档为准。本文件、README、skills、示例、生成代码及其测试中的模板默认行为是起点，不是不可变的业务约束；角色代码、权限模型、页面流程、字段、限额、存储方式与架构均可按实际需求调整。
+- 需求与模板不同，审查时记录为模板适配项，不据此判定需求错误或阻塞审查，也不要求用户额外授权“覆盖模板”；实施时在已有授权范围内修改或移除冲突逻辑，并同步 contract、鉴权、数据迁移、界面、配置、测试、文档及本文件中的过期规则。
+- 未说明的行为可参考现有实现并注明假设，不能升级为强制需求。只有业务要求自身矛盾、与已确认项目决策的优先级不明，或存在真实技术/安全障碍时才提出具体问题；已明确的规则不重复要求选择。
+- 业务规则与技术契约分别判断：可用 API 以当前安装版本的公开类型为准；输入校验、服务端授权、资源隔离和密钥保护仍须落实。需求涉及替换技术方案时说明影响并同步迁移，不能用保留模板默认值代替解决问题。
+
+## 行为契约
+
+涉及框架数据结构、配置、核心流程或模块边界的新增、修改、删除，先读 [变更影响与方案确认](.agents/skills/hai-change-plan/SKILL.md)，说明实际影响并等待用户决定。已有具体确认不重复要求；普通应用私有实现按当前业务授权执行。确认后的变更成套更新文档、配置、网站内容源、注释、模板与调用方。
+
+需求/设计文档审查或从文档生成代码时，读取 [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 清单与任务记录，比较已验收与目标文档 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 树。
+
+- 对当前需求逐项检索 hai-framework 能力和已有实现，确认适用的公开 API 后优先复用；未安装模块先核对依赖与配置，不能因 Skill 已存在就假定已启用。框架不适用时说明具体限制与选用方案，不为覆盖清单引入无关模块。
+- 按已安装版本的公开类型确认模块契约：生命周期模块按 init → use → close；core/serv/kit、纯函数/工厂与流按实际签名处理。返回 HaiResult 的操作先检查 success，不以 try/catch 代替判断；事务失败明确触发回滚。
+- 边界输入做 schema 校验，服务端验证身份、租户与资源权限；SQL 动态值参数化，文件路径防逃逸。密钥不进入 PUBLIC_/VITE_ 变量、客户端代码和日志；敏感 token 不写 localStorage。
+- 禁止 any、无说明的 as unknown as、console.log 和硬编码密钥；从包公开入口导入。注释中文、结构化日志英文并脱敏，用户文本走现有 i18n 并同步所有 locale。
+- 完成时说明实际复用的框架能力、未采用的相关能力及原因、门禁结果；跨边界同步类型、配置、调用方、文档和测试。
+
+先读 README、package.json、相关实现/测试和所需 .agents/skills；不要加载整个 skill 树。新增抽象前确认复用路径与真实需求；保留用户改动。跨文件任务简述影响和验证计划，无须固定规模标签或重复问卷。
+
+- 直接影响：修改 / 新建 / 删除哪些文件；哪些脚本、类型、配置或路由会变。
+- 间接影响：哪些测试、README、i18n、示例、共享类型、依赖方需要同步更新。
 
 ## 项目概述
 
-本项目使用 hai-framework 构建，基于 SvelteKit 2 + Svelte 5 (Runes) + TailwindCSS 4 + DaisyUI 5 + TypeScript 5.7+。
+本项目由 hai-framework CLI 生成。单应用工程通常在 `src/` 下开发；多包工程会同时包含 `packages/*` 与 `apps/*`。实际结构以当前项目目录为准。
+
+如项目使用 SvelteKit，`+server.ts` 只能导出 HTTP handler 与 SvelteKit 允许的配置项；辅助函数放到 `src/lib/**`。
+
+## 工作流程
+
+开发、审查、测试和排错先读[沟通与同步维护](.agents/skills/hai-app-create/collaboration.md)：结论优先，区分发现与待验证、计划与完成；按实际影响检查使用文档、配置示例、截图、测试、CLI 模板和调用方。每批说明解决什么、使用变化、验证及剩余问题。
+
+1. 先搜索现有实现、引用点、测试和 README。
+2. 小步修改，优先保持目录结构、公开 API 和脚本稳定。
+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 注释一节。
+
+## 质量门禁
+
+AI 先分析差异、调用方和受影响流程，默认只选择相关 test/E2E 与必要门禁，用户明确要求时才全量。核对 package.json，按 [分轮验证与集中修复](.agents/skills/hai-app-tests/validation.md) 收集所选检查与日志，再归并修复、复测失败及受影响项；普通失败不中断独立检查，真实前置阻塞才暂停依赖项。文档检查引用，UI/路由变更加相关 E2E，未运行项说明原因。
+
+```bash
+pnpm typecheck
+pnpm lint
+pnpm build
+pnpm test
+pnpm test:e2e
+```
+
+## 完成条件
 
-## 核心规范
+- typecheck / lint / build / test / test:e2e 状态明确；整轮收集后集中修复，最终必需门禁对最终代码有效通过，未执行或阻塞明确原因，不能宣称完成。
+- README、i18n、测试、代码注释与实现保持一致。
+- 最终回复说明执行过的门禁、已同步的文档 / 依赖方，以及未完成项。
 
-- 统一模式：`module.init(config) → use → module.close()`，所有操作返回 `HaiResult<T>`
-- **TDD 驱动开发**：先写测试（Red）→ 确认失败 → 再实现（Green）→ 确认通过 → 重构（Refactor）
-- 禁止 `any`（使用 `unknown` + 缩窄），禁止 `console.log`（使用 `core.logger`）
-- 用户可见文本走 i18n，代码注释中文，日志英文
-- HaiResult 错误直接透传，不重新包装
-- 框架模块公共 API 不抛异常，统一返回 `HaiResult<T>`；不要用 `try/catch` 处理模块返回的错误
-- 质量门禁：`pnpm typecheck && pnpm lint && pnpm test && pnpm --filter <app> test:e2e`
+## Skills 路由
 
-## Skills 参考
+- `.agents/skills/hai-build/SKILL.md`：架构、构建和质量门禁。
+- `.agents/skills/hai-app-create/SKILL.md`：应用骨架、路由、页面与 API 模板。
+- `.agents/skills/hai-app-review/SKILL.md`：应用代码审查。
+- `.agents/skills/hai-app-tests/SKILL.md`：Vitest / Playwright 测试策略。
+- 具体模块按需读取对应 `hai-*` Skill。
 
-所有详细指南位于 `.agents/skills/` 目录，按需阅读：
+前端项目已交付对应技能时，先按 hai-ui-design 确定任务、布局、状态与组件映射，使用 hai-ui 实现，再由 hai-ui-review 检查真实页面。窄范围修改复用已有设计；按实际语言/主题/尺寸验证。
 
-- **入口**：`hai-build/SKILL.md` — 项目架构总览与 Skill 导航
-- **框架模块**：`hai-core/`、`hai-kit/`、`hai-reldb/`、`hai-iam/`、`hai-crypto/`、`hai-cache/`、`hai-storage/`、`hai-ai/`
-- **UI 组件**：`hai-ui/SKILL.md`
-- **TDD 开发流程**：`hai-app-tests/`（TDD 测试先行）、`hai-app-create/`（TDD 实现）、`hai-app-review/`（TDD 重构审查）
+工作流技能按 hai-领域-动作 命名，能力使用类沿用领域名。需求、验收、发现与当前版本证据按 [工作交接契约](.agents/skills/hai-spec-implement/handoff.md) 传递，沿既有清单恢复任务。

package/templates/skills/CLAUDE.md

@@ -1,12 +1 @@
-# CLAUDE.md
-
 @AGENTS.md
-
-> Claude Code 项目指引。共享规范通过 `@AGENTS.md` 复用；共享参考资料位于 `.agents/skills/` 目录。
-
-## 使用说明
-
-- 本文件是 Claude Code 的原生项目级指引入口。
-- 项目概述、核心规范与工作流约定统一维护在 `AGENTS.md`；Claude Code 通过 `@AGENTS.md` 复用这些共享规范，避免双份文档漂移。
-- 共享的模块与工作流参考资料维护在 `.agents/skills/` 中；需要具体用法时，可按路径阅读对应 `SKILL.md`。
-- 当前模板为了保持单一 Skill 树，不额外生成 `.claude/skills/`；如需 Claude Code 的原生 project skills 自动发现，需要单独维护该目录。