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

package/templates/base/.gitignore.hbs

@@ -25,8 +25,9 @@ playwright-report/
 # 本地数据目录
 **/data/
 
-# hai deploy 产物（compose / .env.runtime / 镜像 tar / sidecar 凭据）
+# 构建与部署产物（镜像 / Compose tar / 私有运行配置）
 .hai/
+*.tar
 
 # 本机私有配置；公共 .env 与 dev/test/prod 环境文件纳入版本控制。
 .env.local

package/templates/base/Dockerfile.hbs

@@ -3,10 +3,6 @@
 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
@@ -14,14 +10,14 @@ ENV CI=true
 WORKDIR /workspace
 
 RUN corepack enable && corepack prepare pnpm@12.11.2 --activate
-COPY pnpm-lock.yaml pnpm-workspace.yaml ./
-RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store pnpm fetch
 COPY . .
+RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store pnpm fetch
 RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store pnpm install --offline --frozen-lockfile --ignore-scripts
-RUN pnpm build
+RUN pnpm compile
 
 FROM nginxinc/nginx-unprivileged:1.29-alpine AS runtime
 
+COPY --chmod=755 docker/19-runtime-config.sh /docker-entrypoint.d/19-hai-runtime-config.sh
 COPY docker/nginx.conf /etc/nginx/conf.d/default.conf
 COPY --from=build /workspace/dist /usr/share/nginx/html
 
@@ -32,10 +28,6 @@ HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
 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
@@ -43,21 +35,16 @@ ENV CI=true
 WORKDIR /workspace
 
 RUN corepack enable && corepack prepare pnpm@12.11.2 --activate
-COPY pnpm-lock.yaml pnpm-workspace.yaml ./
-RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store pnpm fetch
 COPY . .
+RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store pnpm fetch
 RUN --mount=type=cache,id={{projectName}}-pnpm,target=/pnpm/store pnpm install --offline --frozen-lockfile --ignore-scripts
-RUN pnpm build
+RUN pnpm compile
 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_DEPLOY_ENVIRONMENT=$HAI_DEPLOY_ENVIRONMENT
-ENV HAI_CORE_ENV=$HAI_CORE_ENV
 ENV HOST=0.0.0.0
 ENV PORT=3000
 WORKDIR /app
@@ -71,9 +58,5 @@ HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
   CMD node -e "fetch('http://127.0.0.1:'+process.env.PORT+'/').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
 CMD ["node", "build"]
 
-FROM runtime-base AS runtime-with-data
-
-COPY --from=embedded-data --chown=node:node / /app/data/
-
 FROM runtime-base AS runtime
 {{/if}}

package/templates/base/docker/nginx.conf.hbs

@@ -9,6 +9,12 @@ server {
     try_files $uri $uri/ /index.html;
   }
 
+  location = /runtime-config.js {
+    alias /tmp/hai-runtime-config/runtime-config.js;
+    add_header Cache-Control "no-store";
+    default_type application/javascript;
+  }
+
   location = /health {
     access_log off;
     add_header Content-Type text/plain;

package/templates/base/hai.build.json.hbs

@@ -0,0 +1 @@
+{ "images": [{ "name": "app", "target": "runtime", "containerPort": {{#if isSvelteOnlyApp}}8080{{else}}3000{{/if}} }] }

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.65",
+  "version": "0.1.0-alpha.66",
   "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}}",
@@ -23,8 +23,9 @@
     "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",
+    "compile": "{{#if hasI18n}}pnpm paraglide:compile && {{/if}}vite build",
+    "build": "hai build",
+    "deploy": "hai deploy",
 {{#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",
@@ -37,26 +38,20 @@
     "lint:fix": "eslint . --fix",
     "test": "{{#if hasI18n}}pnpm paraglide:compile && {{/if}}vitest run",
     "test:watch": "vitest",
-    "test:e2e": "playwright test",
-    "clean": "{{#if isSvelteOnlyApp}}rimraf dist build android ios .turbo src/lib/paraglide{{else}}rimraf .svelte-kit build .turbo{{/if}}",
-    "docker:build": "docker build --target runtime -t {{projectName}}:latest .",
-{{#unless isSvelteOnlyApp}}
-    "docker:build:data": "docker build --target runtime-with-data --build-context embedded-data=./data -t {{projectName}}:latest .",
-{{/unless}}
-    "podman:build": "podman build --format docker --jobs=1 --target runtime -t {{projectName}}:latest ."{{#unless isSvelteOnlyApp}},
-    "podman:build:data": "podman build --format docker --jobs=1 --target runtime-with-data --build-context embedded-data=./data -t {{projectName}}:latest ."{{/unless}}{{#if isCapacitorApp}},
+    "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}},
     "cap:add:android": "cap add android",
     "cap:add:ios": "cap add ios",
-    "cap:sync": "pnpm build && cap sync",
-    "cap:sync:android": "pnpm build && cap sync android",
-    "cap:sync:ios": "pnpm build && cap sync ios",
+    "cap:sync": "pnpm compile && cap sync",
+    "cap:sync:android": "pnpm compile && cap sync android",
+    "cap:sync:ios": "pnpm compile && cap sync ios",
     "cap:android": "cap open android",
     "cap:ios": "cap open ios",
     "cap:run:android": "cap run android",
     "cap:run:ios": "cap run ios",
-    "cap:build:android:debug": "pnpm build && cap sync android && cd android && gradlew.bat assembleDebug",
-    "cap:build:android:release": "pnpm build && cap sync android && cap build android --androidreleasetype APK",
-    "cap:build:ios": "pnpm build && cap sync ios && cap build ios"{{/if}}
+    "cap:build:android:debug": "pnpm compile && cap sync android && cd android && gradlew.bat assembleDebug",
+    "cap:build:android:release": "pnpm compile && cap sync android && cap build android --androidreleasetype APK",
+    "cap:build:ios": "pnpm compile && cap sync ios && cap build ios"{{/if}}
   },
   "dependencies": {
   {{#if isSvelteOnlyApp}}
@@ -88,6 +83,7 @@
 {{/if}}
   },
   "devDependencies": {
+    "@h-ai/cli": "{{haiPackageSpecifier}}",
 {{#if isSvelteOnlyApp}}
     "@h-ai/core": "{{haiPackageSpecifier}}",
 {{/if}}

package/templates/base/svelte.config.js.hbs

@@ -56,6 +56,8 @@ const config = {
     runes: true,
   },
   kit: {
+    // 环境文件由 Vite 的 core loader 统一加载；Kit 不再二次读取根目录私有配置。
+    env: { dir: './.svelte-kit' },
 {{#if isCapacitorApp}}
     adapter: adapter({
       pages: 'build',

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

@@ -22,9 +22,12 @@ import { sveltekit } from '@sveltejs/kit/vite'
 import tailwindcss from '@tailwindcss/vite'
 {{/if}}
 import { defineConfig } from 'vite'
+{{#if isSvelteOnlyApp}}
+import { publicRuntimeConfig } from './scripts/vite-runtime-config.js'
+{{/if}}
 
-export default defineConfig(({ mode }) => {
-  const envResult = core.config.loadEnvFiles({ mode, envDir: process.cwd() })
+export default defineConfig(({ mode, command }) => {
+  const envResult = command === 'build' ? { success: true as const, data: {} as Record<string, string> } : core.config.loadEnvFiles({ mode, envDir: process.cwd() })
   if (!envResult.success)
     throw new Error(envResult.error.message)
   const env = envResult.data
@@ -50,6 +53,7 @@ export default defineConfig(({ mode }) => {
 {{/if}}
     plugins: [
   {{#if isSvelteOnlyApp}}
+      publicRuntimeConfig({ apiBase: process.env.PUBLIC_API_BASE, core: appConfig }),
       svelte(),
   {{else}}
       sveltekit(),

package/templates/shared/.gitattributes

@@ -0,0 +1,5 @@
+# Windows 构建机交付 Linux 启动脚本时必须保留 LF，避免 /bin/sh 解释器失效。
+*.sh text eol=lf
+*.sh.hbs text eol=lf
+*.envsh text eol=lf
+*.envsh.hbs text eol=lf

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/run-e2e.mjs

@@ -0,0 +1,65 @@
+/** 运行浏览器验收，并在报告写完后清理本次输出；失败和中断同样清理。 */
+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
+function stop() {
+  if (interrupted)
+    return
+  interrupted = true
+  if (process.platform === 'win32' && child?.pid && child.exitCode === null) {
+    // Windows 的 kill 不传递 SIGTERM；同时结束本次 Playwright 创建的浏览器与服务进程。
+    spawn('taskkill', ['/pid', String(child.pid), '/t', '/f'], { windowsHide: true, stdio: 'ignore' })
+      .once('error', () => child?.kill())
+  }
+  else {
+    child?.kill()
+  }
+}
+process.once('SIGINT', stop)
+process.once('SIGTERM', stop)
+try {
+  for (const args of groups) {
+    const code = await new Promise((resolve, reject) => {
+      child = spawn(process.execPath, [cli, 'test', ...args], {
+        cwd,
+        windowsHide: true,
+        stdio: 'inherit',
+        env: { ...process.env, HAI_AUTH_EVIDENCE_DIR: join(cwd, 'test-results/evidence'), HAI_E2E_DATA_ROOT: dataRoot },
+      })
+      child.once('error', reject)
+      child.once('exit', resolve)
+    })
+    if (code !== 0 || interrupted) {
+      process.exitCode = typeof code === 'number' && code !== 0 ? code : 1
+      break
+    }
+  }
+}
+finally {
+  process.removeListener('SIGINT', stop)
+  process.removeListener('SIGTERM', stop)
+  // 固定为当前测试工程中的标准输出目录，禁止删除调用方任意指定的路径。
+  for (const name of ['test-results', 'playwright-report'])
+    rmSync(join(cwd, name), { recursive: true, force: true, maxRetries: 3, retryDelay: 100 })
+  // Playwright 退出后服务进程已关闭，此时删除 SQLite / storage，避免 Windows 文件锁。
+  rmSync(dataRoot, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 })
+}

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

@@ -0,0 +1,54 @@
+/** 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) {
+      server.middlewares.use('/runtime-config.js', respond)
+    },
+    configurePreviewServer(server) {
+      server.middlewares.use('/runtime-config.js', respond)
+    },
+  }
+}

package/templates/skills/hai-app-create/development.md

@@ -48,7 +48,7 @@ YAML 使用 `${HAI_DB_TYPE:sqlite}` 等显式引用，冒号后是未配置时
 
 | 入口             | 开发       | 测试环境                 | 生产环境                                      |
 | ---------------- | ---------- | ------------------------ | --------------------------------------------- |
-| Vite / SvelteKit | `pnpm dev` | `pnpm dev:test`          | `pnpm build:prod` 或 `pnpm dev:prod` 预览配置 |
+| Vite / SvelteKit | `pnpm dev` | `pnpm dev:test`          | `pnpm dev:prod` 预览；build 不选择环境 |
 | Node service     | `pnpm dev` | 构建后 `pnpm start:test` | 构建后 `pnpm start:prod`                      |
 
 所有入口优先级一致：**进程环境 > `.env.local` > `.env.<dev|test|prod>` > `.env`**。Vite 配置在 Node 阶段通过 `core.config.loadEnvFiles({ mode, envDir })` 读取，检查 `success` 后注入进程；`development`/`production` 分别映射到 `dev`/`prod`。Node 服务按 `.env`、环境文件、`.env.local` 的顺序传入 `--env-file`，后者覆盖前者，已有进程环境最高。`core.init` 只读取已注入的变量，不自行读取 dotenv。
@@ -209,6 +209,8 @@ export function pageOffset(query: PageQuery): number {
 
 ## 验证与交付
 
+所有测试临时工程、镜像、容器、辅助进程、日志、截图与报告须在 finally/teardown 自动清理，成功、失败和取消均执行；只清理本次创建的资源，不提交验收产物。
+
 - 对新增/改变行为按 [hai-app-tests](../hai-app-tests/SKILL.md) 写有意义的测试；目标用例先因行为缺失失败，既有回归保持通过。UI/路由改动覆盖真实流程、异步失败与权限路径；纯文案/文档按影响验证。
 - 从当前 `package.json` 选择实际脚本，优先 workspace filter；按 `typecheck → lint → build（构建/配置/跨包变更）→ test → 相关 E2E` 验证，PowerShell 使用 `pnpm.cmd`。不能调用框架仓库私有命令替代应用检查。
 - typecheck/lint 只覆盖部分质量规则；权限、事务、降级、真实 provider、浏览器、容器和原生交付各自需要适用行为证据。缺环境或密钥时报告未验证，不能用 mock 冒充真实集成。

package/templates/skills/hai-app-create/reference.md

@@ -334,13 +334,13 @@ core.init() → crypto.init() → reldb.init() → cache.init() → iam.init()
 
 仅涉及容器构建/部署变更时使用本节；普通功能开发无需每次启动镜像。
 
-- 保持脚手架根目录 `Dockerfile`、`.dockerignore` 与 `package.json` 中 `docker:build*` / `podman:build*` 命令同步。
+- 保持脚手架根目录 `Dockerfile`、`.dockerignore` 与 `package.json` 中 `build` / `compile` 命令与 hai.build.json同步。
 - Podman 多阶段构建保持 `--format docker --jobs=1`；前者保留 `HEALTHCHECK`，后者避免部分 Podman 5.8/Buildah 组合在并行 stage 构建时触发内部 semaphore panic。
 - 先复制 lockfile 与 workspace 配置执行 `pnpm fetch`，再复制源码并离线安装、构建；避免源码变化重复下载依赖，同时兼容新增 workspace。
 - SvelteKit 服务使用 Node adapter；纯 Vite 前端使用带 SPA fallback 的静态镜像；fullstack 的 Service 与 Web 分别交付，Service 直接监听且不增加转发进程。
 - Web 的 `PUBLIC_*` 部署配置在容器启动时生成静态运行时配置，不作为 build arg 烘焙，确保同一镜像可跨环境部署。
 - 配置文件随镜像提供，并允许只读挂载覆盖；密钥只通过环境变量或 `--env-file` 注入。
-- 普通构建不携带 `data/`；只有用户明确运行 `docker:build:data` / `podman:build:data` 时才通过 named build context 嵌入 SQLite/本地存储初始快照。
+- 普通构建不携带 `data/`；持续写入使用运行期 volume；需要预置数据时显式维护独立 Dockerfile target 和 named build context，不把本机数据加入默认镜像。
 - 数据库和本地存储的持续写入必须落到 volume，不能依赖镜像可写层。
 - 完成前实际启动镜像，验证健康端点、非 root 用户、环境变量覆盖、配置挂载和预置数据读取。
 

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

@@ -21,7 +21,22 @@ description: "定位 hai 应用架构、模块依赖、初始化顺序、构建
 - 升级 hai-framework、比较版本差异或同步框架 skills 时，使用 [hai-framework-sync](../hai-framework-sync/SKILL.md) 完成版本发现、差异分析、选择/阻塞处理、迁移与验证。
 - 功能开发先用 [development.md](../hai-app-create/development.md) 把需求匹配到当前版本的框架能力与配置；再读取所选模块 skill 和公开类型。
 - 有生命周期的模块按真实依赖初始化、检查结果并反序清理；core、纯函数和工厂不套用相同生命周期。
-- 构建任务检查当前 engines、适配器、环境变量、缓存与目标产物，不能照搬框架仓库私有构建命令。
+- 构建任务检查当前 engines、适配器、缓存与目标产物，不能照搬框架仓库私有构建命令。
+
+## 构建与部署
+
+- `pnpm build` 默认仅编译源码（调用 compile）；`pnpm build --target docker` 根据 hai.build.json 构建并导出 app/可选 web 镜像，auto 优先可达 Podman、其次 Docker，可用 --runtime 显式指定。
+- compile 交付源码编译结果，docker 交付镜像归档，desktop 交付 Tauri 系统安装包；每次只选一种。images[].target 是 Dockerfile 阶段名，fullstack 的 app 使用 runtime、web 使用 web，不能与 CLI target 混用；参数默认值和示例必须与真实入口同步。
+- Podman 的客户端代理通过预定义构建参数传递，覆盖 Windows/macOS 远程引擎的服务端默认值；代理地址必须能从构建容器访问，--no-http-proxy 禁止此传递。不要把代理写成 Dockerfile ENV 或固化进交付镜像。
+- --network 默认沿用引擎网络；只有实际构建网络无法访问依赖/代理时才显式选择网络，pasta 仅适用于 rootless Podman。build 与 run 的主机名解析可能不同，须验证构建网络中的可达性，不默认改成 host 网络。
+- 从运行 build 的应用根 package.json.version 读取版本，不能使用 CLI/框架版本或服务子包版本代替。清单格式 version=2，appVersion 为应用版本；镜像 tar 名含版本、buildId 区分同版本构建，Tauri 也接收根版本。不要手改清单或保留无版本的交付归档。
+- 构建不区分 dev/test/prod，不加载部署环境覆盖，不注入运行期凭据；完整镜像清单含 SHA-256，全部成功才发布 latest。不要让 compile、Dockerfile 或 Tauri beforeBuildCommand 递归调用自身的原生/镜像构建。
+- Vite 的 envDir 与 SvelteKit 的 kit.env.dir 是独立加载入口，必须同时阻止构建阶段读取工程根的 .env 文件；开发/预览由 core loader 注入，运行期由 deploy 注入。用临时 .env.local 哨兵值检查输出，避免只过滤进程变量却仍把私有文件固化进产物。
+- 静态客户端通过 runtime-config.js 或原生宿主初始化脚本获取公开地址与元数据；仅投影公开白名单，禁止将完整 process.env、服务配置或密钥序列化到浏览器。预览与容器启动均须验证真实登录，不能依赖构建期 API 地址让 E2E 通过。
+- `pnpm build --target desktop --platform windows|linux|macos --arch x64|arm64` 调用对应工程的 Tauri build。要求在目标系统准备 Rust target、SDK 和打包工具，不假定跨系统编译。原生安装包必须按目标系统实测。
+- deploy 只消费已有产物，详见 [hai-deploy](../hai-deploy/SKILL.md)。网络不通时 --bundle-only 生成 tar，按说明手工搬运；packaged 不代表部署已运行。
+- 测试临时工程、镜像、容器、辅助进程、日志、截图和报告必须在 finally/teardown 自动清理，失败/取消也清理；不得提交测试产物或删除用户既有资源。
+- 浏览器测试的数据放入本轮独立临时目录；Windows 等子进程与服务退出后再删除数据库和上传文件，不依赖下一轮测试补清理。
 
 ## 按需参考