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

package/templates/skills/bridges/h5/AGENTS.md

@@ -2,13 +2,20 @@
 
 > H5 移动端项目 AI 编程助手入口。优先结合 `README.md`、`.agents/skills/`、`src/routes/`、`messages/*` 与移动端测试工作。
 
+## 需求与模板
+
+- 业务行为以用户当前明确要求及其指定的需求/设计文档为准。本文件、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 树。
 
@@ -42,6 +49,15 @@
 2. 修改导航、触屏交互、API 或认证流程时，同步 README、i18n 和测试。
 3. 按改动范围验证，修复本次引入的失败；已有问题与未运行项明确报告。
 
+页面统一继承根布局的 header/footer；新增页面沿用 SvelteKit 自动文件路由，刷新定位及服务端 load/鉴权保持一致。
+
+## 代码注释与示例
+
+- 尽可能补充有信息量的中文 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。未运行项说明原因。

package/templates/skills/bridges/mobile-app/AGENTS.md

@@ -2,13 +2,20 @@
 
 > Capacitor Mobile App 项目 AI 编程助手入口。优先结合 `README.md`、`.agents/skills/`、`src/`、`messages/*` 与移动端测试工作。
 
+## 需求与模板
+
+- 业务行为以用户当前明确要求及其指定的需求/设计文档为准。本文件、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 树。
 
@@ -29,8 +36,10 @@
 
 ## 架构边界
 
-- 不使用 SvelteKit 路由、server hooks 或 `@h-ai/kit`。
-- 不新增 `+page.svelte`、`+layout.svelte`、`hooks.server.ts`、`src/routes/*` 等 SvelteKit 文件。
+- 页面统一继承公共 header/footer；新增 SPA 页面放 `src/lib/pages/**/*.svelte`，由 `HashRouter` 自动发现。菜单只维护业务入口，不维护路由表。
+
+- 当前客户端使用 Vite SPA；保留此架构时不混入 SvelteKit 路由、server hooks 或 `@h-ai/kit`。
+- 需求迁移到 SvelteKit 时同步运行环境、路由、初始化、构建与原生壳集成；不能仅添加 `+page.svelte` 等文件就视为完成迁移。
 - 原生能力通过 `@h-ai/capacitor` 使用；token 原生端使用 Capacitor 安全存储，Web 预览仅使用内存存储。
 - API 调用使用 `@h-ai/api-client`，业务错误按 HaiResult 处理。
 - 页面文本走 i18n，同步中英文 messages。
@@ -53,6 +62,13 @@ pnpm cap:build:android:release
 2. 修改原生能力、权限、登录态或 API 流程时，同步 README、i18n 和测试。
 3. 按改动范围验证，修复本次引入的失败；已有问题与未运行项明确报告。
 
+## 代码注释与示例
+
+- 尽可能补充有信息量的中文 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。未运行项说明原因。

package/templates/skills/bridges/website/AGENTS.md

@@ -2,13 +2,20 @@
 
 > 企业官网项目 AI 编程助手入口。优先结合 `README.md`、`.agents/skills/`、`src/routes/`、`messages/*` 与测试工作。
 
+## 需求与模板
+
+- 业务行为以用户当前明确要求及其指定的需求/设计文档为准。本文件、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 树。
 
@@ -42,6 +49,15 @@
 2. 修改页面时同步 README、i18n、测试和 SEO 相关元信息。
 3. 按改动范围验证，修复本次引入的失败；已有问题与未运行项明确报告。
 
+页面统一继承根布局的 header/footer；新增页面沿用 SvelteKit 自动文件路由，刷新定位及服务端 load/鉴权保持一致。
+
+## 代码注释与示例
+
+- 尽可能补充有信息量的中文 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。未运行项说明原因。

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

@@ -183,7 +183,7 @@ const result = await ai.rag.query('核心架构是什么？', {
 - 播放负载：`serializePlayableAudio(audio)` 返回 `HaiResult<PlayableAudio>`；`PlayableAudio` 为 `{ audioBase64, format: 'wav'|'mp3', mimeType }`。该函数将 `pcm16` 封装为 WAV，透传 WAV/MP3；`opus` 不支持转换。
 - 请求可选：识别 `contextHints?: string[]`（热词/提示）；合成 `instruction?: string`（自然语言风格指令）；均支持 `signal: AbortSignal`。
 - 模型配置：`audio.models: [{ id, provider: 'openai'|'mimo'|'qwen'|'doubao', model, operations, apiKey?, baseUrl?, appKey?, accessKey?, resourceId?, workspaceId? }]`；`operations` 必须明确为识别、合成或两者。确认 LLM 与语音模型共用凭据时，可设置 `audio.inheritLlmApiKey: true`，默认关闭。
-- 凭据优先级：模型条目 `apiKey` → 显式启用继承后的 LLM `apiKey` → `HAI_AI_AUDIO_<PROVIDER>_API_KEY` 或 `OPENAI_API_KEY` / `MIMO_API_KEY` / `DASHSCOPE_API_KEY` / `VOLC_API_KEY`（豆包旧版控制台额外 `VOLC_APP_KEY` / `VOLC_ACCESS_KEY`）。可选密钥中的 YAML `null`、空字符串和纯空白字符串都会规范化为未配置。
+- 凭据优先级：模型条目 `apiKey` → 显式启用继承后的 LLM `apiKey` → `HAI_AI_AUDIO_<PROVIDER>_APIKEY` 或 `OPENAI_API_KEY` / `MIMO_API_KEY` / `DASHSCOPE_API_KEY` / `VOLC_API_KEY`（豆包旧版控制台额外 `VOLC_APP_KEY` / `VOLC_ACCESS_KEY`）。可选密钥中的 YAML `null`、空字符串和纯空白字符串都会规范化为未配置。
 - 资源上限：`audio.maxAudioBytes`（默 10 MiB）、`audio.maxStreamDurationMs`（默 5 分钟）；所有请求支持 `signal: AbortSignal` 打断。
 - Provider 为内部实现，不从根入口导出；不支持的输入方式招 `AUDIO_UNSUPPORTED_INPUT`，不伪装实时。取消 → `AUDIO_CANCELLED`，超时 → `AUDIO_TIMEOUT`，连接失败或 `end` 前异常断连 → `AUDIO_CONNECTION_FAILED`。浏览器客户端（`@h-ai/ai/client`）严格区分正常结束 / 取消 / 异常断连：取消招 `AUDIO_CANCELLED`、`end` 前断连招 `AUDIO_CONNECTION_FAILED`、服务端 error 帧保留其领域错误码，`synthesize` 不把未完成的部分音频当作成功返回。
 
@@ -196,7 +196,7 @@ const result = await ai.rag.query('核心架构是什么？', {
 - 请求：`GenerateImageRequest { prompt, model?, size?: { width, height }, referenceImages?: ReferenceImage[], signal? }`；`ReferenceImage` 为 `{ data: Uint8Array, mimeType: string }`。
 - 返回：`GenerateImageResult { images: Array<{ data: Uint8Array, mimeType, width?, height? }> }`。
 - 模型配置：`image.models: [{ id, provider: 'openai'|'google'|'qwen'|'seedream'|'pollinations', model, apiKey?, baseUrl?, workspaceId?, timeout? }]`；`image.generateModel` 选择默认模型别名。
-- 凭据优先使用模型项 `apiKey`，否则回退 `HAI_AI_IMAGE_<PROVIDER>_API_KEY` 或厂商标准环境变量。
+- 凭据优先使用模型项 `apiKey`，否则回退 `HAI_AI_IMAGE_<PROVIDER>_APIKEY` 或厂商标准环境变量。
 - 厂商差异由内部 Provider 消化：OpenAI/Pollinations 的 multipart edits、Google `inlineData`、Qwen/Seedream 的 Data URL 参考图，以及各家 Base64、临时 URL 或二进制响应均归一为图片字节。
 - Google 只接受其文档列出的宽高比；Qwen/Seedream 还可能对总像素与边长有限制。业务应提供厂商支持的尺寸预设，不要假设任意像素组合都可用。
 

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

@@ -13,19 +13,21 @@ description: "在 hai 应用中新增、修改或修复功能，按需求复用
 | 适用场景 | 日常应用功能开发与已授权修复 |
 | 输入 | 功能需求、现有路由/contract、数据模型和验收场景 |
 | 输出 | 能力选择依据、最小实现、行为验证、i18n 与受影响文档 |
-| 限制 | 优先复用；TDD 仅让新增目标用例先失败，已有回归保持通过。API workspace 不生成 SvelteKit 路由。 |
+| 限制 | 优先复用；TDD 验证本次目标行为，仍适用的回归保持通过。保留 API workspace 架构时不混入 SvelteKit 路由。 |
 
 ## 使用路径
 
+业务以用户当前明确要求及其指定文档为准；模板规则、生成代码与测试只描述初始方案。需求改变角色、流程、限额或架构时，在已有授权范围内同步调整冲突实现及过期 AGENTS/skills/README，不要求把需求改回模板。具体判定见 [development.md](development.md#需求与模板的关系)。
+
 从需求/设计文档开始生成项目或功能前，使用 [hai-spec-review](../hai-spec-review/SKILL.md) 检查文档是否足以确定实现；修正影响行为的缺项、歧义和技术错误后再进入生成。普通小改动按本次范围确认规则，不要求重审无关文档。
 
-需要按文档规划/执行任务或返修已交付任务时，使用 [hai-spec-implement](../hai-spec-implement/SKILL.md) 管理 docs 清单、任务记录、TDD 和任务分支；本 skill 负责其中的具体应用实现，复用记录中的范围与验收。
+需要按文档规划/执行、返修或根据已提交文档差异同步实现时，使用 [hai-spec-implement](../hai-spec-implement/SKILL.md) 管理 docs 清单、任务记录、文档基线、TDD 和任务分支；本 skill 负责其中的具体应用实现，复用固定目标版本、范围与验收。
 
 需要新建项目、添加模块、补齐配置或生成代码时，先按 [CLI 安装与命令](development.md#cli-安装与命令) 全局安装 `@h-ai/cli`，再执行 `hai` 命令。
 
 1. 读取 [development.md](development.md)：先按真实需求匹配框架能力、已安装版本与应用架构，再确定改动。适用能力包括同一模块已有 feature、配置和扩展点，不以导入包作为复用完成的证据。
 2. 读取所选模块的 skill 与实际公开类型，复用现有服务和组件。新增依赖或直接使用第三方 SDK 前说明已有能力的具体缺口；无需安装无关模块。
-3. 新增或改变行为时用有意义的目标用例验证，已有回归保持通过；按下方参考实现，使用 [hai-app-review](../hai-app-review/SKILL.md) 检查改动涉及的安全与质量边界。
+3. 新增或改变行为时用有意义的目标用例验证，仍适用的回归保持通过；被明确新需求替代的模板断言同步更新并记录依据。按下方参考实现，使用 [hai-app-review](../hai-app-review/SKILL.md) 检查改动涉及的安全与质量边界。
 4. 运行当前项目已定义的门禁，报告行为证据、能力选择及未验证项。纯文案、格式和文档变化按影响验证，不强制新增测试。
 
 ## 按需参考

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

@@ -2,6 +2,12 @@
 
 日常新增、修改和修复功能时读取本文件；专项模块 API 只读取下表匹配的 skill。这里的“应用尽用”是让每项真实需求优先使用适用框架能力，并检查已有 feature、配置和扩展点；不要求所有项目安装或启用全部模块。
 
+## 需求与模板的关系
+
+业务规则以用户当前明确要求和指定的需求/设计文档为准。模板 AGENTS、README、skills、示例、生成逻辑和测试提供初始方案，不固定角色/权限、流程、字段、限额、偏好存储或部署架构。需求明确时直接在已授权范围内适配，不为保留模板而修改需求或重复要求选择；仅审查时列出适配项，不写业务代码。
+
+实现证据用于确认当前行为，不能推翻目标业务规则。同步修改冲突的 schema、服务端授权、初始化/种子数据、迁移、UI、配置、测试与过期规则；未改变的行为继续回归。API 是否可用由安装版本的公开契约决定，服务端授权、资源隔离、输入校验和凭据保护仍需满足；确有不可行或安全问题时举证并给出替代方案。
+
 ## 先确认应用与版本
 
 - 新手引导与帮助中心使用 `@h-ai/ui/guide`，按 [UI 引导指南](../hai-ui/guide.md) 接入。fullstack 的共享管理界面已有默认帮助入口；业务内容放共享 guide-store，使用应用 i18n 和稳定 data-guide 锚点，不重复实现浮层。
@@ -11,6 +17,97 @@
 - 从所属 workspace 的依赖与 lockfile 确认 `@h-ai/*` 实际解析版本和 npm/local 模式。模板 skill 提供导航，**当前安装包的 `package.json.exports`、公开 `.d.ts` 与随包文档决定可用 API**；本地框架源码只在版本匹配或显式联调时作实现证据。
 - 若 skill 与安装版本不符，以公开类型和实际行为核验。先使用已支持能力；任务要求升级时按 [hai-framework-sync](../hai-framework-sync/SKILL.md) 发现目标、比较差异并完成迁移验证。不能直接复制未发布源码的 API，也不能为绕过差异添加虚构兼容层。
 
+### 页面与布局
+
+页面共用根布局的 header/footer。独立移动应用的页面放在 `src/lib/pages/**/*.svelte`，Fullstack 放在 `packages/<name>-shared/src/lib/pages/**/*.svelte`，由 `HashRouter` 和 `import.meta.glob` 自动发现；新增页面无需修改路由表，菜单按业务配置入口。SvelteKit 保留 `src/routes/**/+page.svelte` 自动文件路由、服务端鉴权和刷新定位。
+
+### 环境配置
+
+应用运行参数集中在各项目的环境文件。公共文件只保存可公开的值，凭据写入本机覆盖或由部署平台注入。
+
+| 文件           | 用途                                                   | Git    |
+| -------------- | ------------------------------------------------------ | ------ |
+| `.env.example` | 所有可用字段的示例、用途、枚举和范围；可选字段保留注释 | 提交   |
+| `.env`         | 所有环境共用的公共基础配置                             | 提交   |
+| `.env.dev`     | 开发环境公共覆盖                                       | 提交   |
+| `.env.test`    | 测试环境公共覆盖                                       | 提交   |
+| `.env.prod`    | 生产环境公共覆盖                                       | 提交   |
+| `.env.local`   | 当前机器的私有配置，覆盖公共配置                       | 不提交 |
+
+YAML 使用 `${HAI_DB_TYPE:sqlite}` 等显式引用，冒号后是未配置时的本地默认值。应用仍通过 `core.config.validate(name, ModuleConfigSchema)` 和模块初始化校验类型、枚举、范围和必填项；插值本身不能代替校验。只开启实际使用的模块，未启用模块的整份 YAML 保留注释。
+
+#### 命名和类型
+
+- `HAI_<配置名>_<字段路径>`：`_db.yml` 的 `type` 对应 `HAI_DB_TYPE`；`_ai.yml` 的 `llm.apiKey` 对应 `HAI_AI_LLM_APIKEY`。camelCase 不拆词，数组使用从零开始的索引，如 `HAI_AI_AUDIO_MODELS_0_BASEURL`。
+- 框架配置统一采用路径命名，如 `HAI_REACH_PROVIDERS_0_PASS`。第三方 SDK 自身读取的 `OPENAI_API_KEY` 等外部变量保留厂商约定；应用 YAML 使用框架标准名。
+- 完整变量引用按 YAML 标量还原类型：布尔用 `true/false`，数字不带单位；要保留看似数字/布尔的字符串，在环境值中保留 YAML 引号，例如 dotenv 中 `HAI_AI_LLM_APIKEY='"123456"'`。空字符串保持为空字符串。
+- `HAI_DB` 等父级变量可用 JSON/YAML 整体替换对象，优先于子级变量；非必要不整体覆盖，避免遗漏字段。
+- `PUBLIC_` / `VITE_` 只用于浏览器可见的 API 地址和非敏感参数。业务正文、模板 ID、表名/列名及数据结构留在代码/YAML；环境参数不能改变固定表结构契约。
+
+#### 加载与启动
+
+| 入口             | 开发       | 测试环境                 | 生产环境                                      |
+| ---------------- | ---------- | ------------------------ | --------------------------------------------- |
+| 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。
+
+`prod` 是文件模式名，对应 `HAI_CORE_ENV=production`；环境枚举为 `development | test | production | staging`。SvelteKit adapter-node 产物使用 `node --env-file=.env --env-file=.env.prod --env-file-if-exists=.env.local build/index.js`。文件路径相对进程工作目录，公共文件随项目提交；容器通过部署平台或 `--env-file` 注入目标环境值。浏览器只接收公开白名单，构建产物和镜像不包含 `.env.local`。
+
+Fullstack 的环境文件在工程根；service 脚本通过 `../../.env*` 加载，Web/App/Desktop 的 Vite `envDir` 指向根目录。API workspace 的环境文件在 `apps/<name>-service/`。独立应用在各自根目录加载。浏览器配置在构建期注入时，改环境参数后须重新构建；fullstack 的公开应用元数据由 service `app.info` 返回。
+
+#### 迁移已有项目
+
+先把原来被忽略的 `.env` 私有值迁入 `.env.local`，再提交公共基础和环境文件。本机文件只保留需要覆盖的值，避免整份复制示例后固定开发环境。旧的 `HAI_AI_LLM_API_KEY` / `HAI_AI_LLM_BASE_URL` 改为 `HAI_AI_LLM_APIKEY` / `HAI_AI_LLM_BASEURL`；音频和图像厂商回退变量同样使用 `APIKEY` 后缀。Reach 和 deploy 凭据按当前 YAML 路径命名，以项目 `.env.example` 为准，同步迁移部署平台变量和本机文件。
+
+原 `HAI_AI_ANTHROPIC_API_KEY` / `HAI_AI_ANTHROPIC_BASE_URL` 不再使用。默认协议为 `anthropic` 时改用标准 LLM 变量；混合模型池中有独立凭据或端点时，将 `apiKey` / `baseUrl` 配置在对应模型项。厂商回退 `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL` 保留，优先级以 AI 模块说明为准。
+
+#### 常用变量及约束
+
+| 变量                                                              | 说明与取值约束                                                                         |
+| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `HAI_CORE_ENV`                                                    | `development \| test \| production \| staging`                                         |
+| `HAI_CORE_DEBUG`                                                  | `true \| false`                                                                        |
+| `HAI_CORE_LOGGING_LEVEL`                                          | `trace \| debug \| info \| warn \| error \| fatal`                                     |
+| `HAI_CORE_LOGGING_FORMAT`                                         | `json \| pretty`                                                                       |
+| `HAI_DB_TYPE`                                                     | `sqlite \| postgresql \| mysql`                                                        |
+| `HAI_DB_DATABASE`                                                 | SQLite 文件路径或 `:memory:`；网络数据库为数据库名                                     |
+| `HAI_DB_HOST` / `HAI_DB_PORT` / `HAI_DB_USER` / `HAI_DB_PASSWORD` | 主机、整数端口 1–65535、用户名、敏感密码；PostgreSQL 常用 5432，MySQL 常用 3306        |
+| `HAI_DB_URL` / `HAI_DB_SSL`                                       | 非空连接 URL 优先于拆分字段；TLS 为布尔值、require/prefer/allow/disable 或 TLS 对象    |
+| `HAI_CACHE_TYPE` / `HAI_CACHE_DB`                                 | `memory \| redis`；DB 为整数 0–15；memory 仅单进程使用                                 |
+| `HAI_STORAGE_TYPE`                                                | `local \| s3`；local 要求 root，s3 要求 bucket、region、accessKeyId、secretAccessKey   |
+| `HAI_SERV_SERVER_HOST` / `HAI_SERV_SERVER_PORT`                   | HTTP 主机和整数端口 1–65535；部署平台 HOST/PORT 可覆盖                                 |
+| `HAI_AI_LLM_API` / `HAI_AI_LLM_TEMPERATURE`                       | `chat \| responses \| anthropic`；temperature 为数字 0–2                               |
+| `HAI_AI_LLM_APIKEY` / `HAI_AI_LLM_BASEURL` / `HAI_AI_LLM_MODEL`   | 厂商密钥、服务 URL、实际可用模型名；启用时满足厂商要求                                 |
+| `HAI_ADMIN_DEFAULT_PASSWORD`                                      | 首次创建管理员的密码，满足 IAM 密码策略；CLI 为 fullstack 本地 `.env.local` 生成随机值 |
+| `PUBLIC_API_BASE`                                                 | 可公开的 API 地址，不得包含用户名、密码或 token                                        |
+
+其余变量逐项见对应 `.env.example` 及模块公开 Schema；可选块启用后也应使用相同命名、显式引用与逐项说明。
+
+#### 跨环境切换数据库
+
+保持 `_db.yml` 不变，在公共 `.env.test` 设置：
+
+```dotenv
+HAI_DB_TYPE=sqlite
+HAI_DB_DATABASE=:memory:
+```
+
+在公共 `.env.prod` 设置非敏感连接参数，密码由生产进程或目标机器 `.env.local` 注入：
+
+```dotenv
+HAI_DB_TYPE=postgresql
+HAI_DB_DATABASE=my_app
+HAI_DB_HOST=db.internal
+HAI_DB_PORT=5432
+HAI_DB_USER=my_app
+# 在目标环境注入 HAI_DB_PASSWORD，或提供完整 HAI_DB_URL。
+HAI_DB_SSL=require
+```
+
+切换到 MySQL 时相应设置 `HAI_DB_TYPE=mysql`、端口和凭据。确保项目已安装所选 Provider 的驱动；数据库数据迁移另行执行，切换配置不会搬迁数据。缓存切到 Redis、存储切到 S3 时同样填写对应连接字段。
+
 ## CLI 安装与命令
 
 CLI 的 npm 包名是 `@h-ai/cli`，安装后提供 `hai` 命令。使用脚手架前先全局安装并确认版本；PowerShell 中使用 `pnpm.cmd` 执行 pnpm 命令。
@@ -58,9 +155,9 @@ hai create my-app
 
 已有能力满足需求时使用它；已导入模块但仍手写其已有认证、缓存、上传、分页或 UI 功能，需要修正。确有缺口时记录缺失的具体能力、当前版本和最小补充方案，按需求增加依赖或应用代码；不为凑模块覆盖率增加服务和抽象。
 
-独立 fullstack 默认后台的 Web/App/Desktop 共用管理组件、状态与 typed client。`@h-ai/serv/features/iam` 默认 procedures 可按需选用并与 contract 对齐；仅为业务审计或资源策略覆写必要路由。主题的 DOM 更新和安全缓存使用 `@h-ai/ui/theme`（`applyTheme` / `getSavedTheme`），应用只保留响应式状态与已编译主题白名单。固定角色、管理员自我保护、头像资源范围及写失败补偿仍由应用按需求实现。
+独立 fullstack 默认后台的 Web/App/Desktop 共用管理组件、状态与 typed client。`@h-ai/serv/features/iam` 默认 procedures 可按需选用并与 contract 对齐；有业务缺口时覆写必要路由。主题的 DOM 更新和安全缓存使用 `@h-ai/ui/theme`（`applyTheme` / `getSavedTheme`），应用保留响应式状态与已编译主题白名单。初始 admin/user、管理员自我保护、头像限额、分页和审计策略都是应用示例，可按需求替换；实际权限、资源范围和写入一致性按目标业务落实。
 
-Fullstack 创建时在被 Git 与容器构建忽略的根 `.env` 写入独立随机 `HAI_ADMIN_DEFAULT_PASSWORD`，`.env.example` 保留空占位。`dev` / `start` 自动读取；已有用户不重设密码。启动边界保留模块错误的具体说明与错误码，失败后反序清理。不能把生成的本地凭据复制到前端配置、日志、源码或镜像。
+Fullstack 创建时在被 Git 与容器构建忽略的根 `.env.local` 写入独立随机 `HAI_ADMIN_DEFAULT_PASSWORD`，`.env.example` 保留空占位。`dev` / `start` 自动读取；已有用户不重设密码。启动边界保留模块错误的具体说明与错误码，失败后反序清理。不能把生成的本地凭据复制到前端配置、日志、源码或镜像。
 
 ## 落实契约与安全边界
 
@@ -83,8 +180,37 @@ Fullstack 创建时在被 Git 与容器构建忽略的根 `.env` 写入独立随
 
 serv/oRPC 普通 procedure 返回的失败 HaiResult 可以位于 HTTP 200 包络，`error.httpStatus` 是错误元数据，不等于响应状态；输入 schema 校验、传输错误、路由中间件及 kit 的 Response 各有状态契约。验收同时检查响应体 `success/error.code` 和真实 HTTP 状态，不照搬另一架构的 401/500 断言，也不以 HTTP 200 判为业务成功。
 
+## JSDoc 注释
+
+所有导出函数、核心业务流程、表/列、接口/type/schema 及字段提供中文 JSDoc，说明用途、约束、单位、关联及失败行为，并包含 `@example`。函数用实际的 `@param` / `@returns`，仅会抛错的契约写 `@throws`；数据结构给合法数据，数据库表说明主外键、可空性、默认值、唯一约束和典型行。核心逻辑解释决策与边界，避免重复代码字面含义。
+
+```ts
+/**
+ * 分页输入；page 从 1 开始，pageSize 为 1–100。
+ * @example const query: PageQuery = { page: 1, pageSize: 20 }
+ */
+export interface PageQuery {
+  /** 当前页，最小为 1。 */
+  page: number
+  /** 每页记录数，最大为 100。 */
+  pageSize: number
+}
+
+/**
+ * 将已校验的分页参数转换为数据库偏移量。
+ * @param query - 已通过边界 Schema 校验的分页参数
+ * @returns 从零开始的偏移量
+ * @example pageOffset({ page: 2, pageSize: 20 }) // 20
+ */
+export function pageOffset(query: PageQuery): number {
+  return (query.page - 1) * query.pageSize
+}
+```
+
 ## 验证与交付
 
+所有测试临时工程、镜像、容器、辅助进程、日志、截图与报告须在 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

@@ -314,13 +314,13 @@ interface CreateArticleInput {
 
 CLI 项目统一忽略 `**/data/`，含根目录、workspace 子目录及 `.gitkeep`；数据库/上传文件不入 Git。Fullstack 的服务端 config 始终保留 core、serv、db、cache、iam、storage、audit、reach、ai、vecdb、payment、scheduler、deploy 共 13 份 YAML，未启用模块整份注释，可选字段及替代 Provider 按块注释，`.env.example` 也保留未启用模块的注释凭据。
 
-H5 认证路由独立显示；业务页面使用 `@h-ai/ui` 的 `BottomNav` 与移动端壳样式，导航启用 centered/maxWidth/safeArea，与页面同宽。
+H5 所有页面继承根布局的 header/footer；认证页隐藏底部导航，业务页面使用 `@h-ai/ui` 的 `BottomNav` 与移动端壳样式，导航启用 centered/maxWidth/safeArea，与页面同宽。
 
 扩展这些配置前先核对当前安装版本及模块公开 Schema。在服务端 workspace 安装需要的依赖，在 `src/server/runtime.ts` 按依赖顺序校验/初始化、失败清理并反序关闭，再接入 contract/procedure。整份注释文件先去掉一层外层注释，可选块只开启需要的字段；切换 Provider 时替换旧连接块并保持名称唯一。配置文件存在不代表模块已启用。crypto.init() 无配置参数，datapipe 无生命周期，不增加虚构的 YAML。
 
 环境变量叶子覆盖只遍历 YAML 已有路径，注释键须先取消注释，或用 HAI_DB/HAI_CACHE 等整体对象覆盖。camelCase 不拆词，例如 connectTimeout → HAI_CACHE_CONNECTTIMEOUT；密钥仅写入被忽略的环境文件或部署环境。语言列表在前端/shared 的 project.inlang/settings.json 中同步，core 只配置 defaultLocale。
 
-Fullstack 自动生成的 .env 默认只启用管理员初始密码和 PUBLIC_API_BASE，其余环境覆盖保留注释，YAML 修改可直接生效。显式开启环境覆盖后，修改 YAML 时须核对该覆盖是否仍适用。
+Fullstack 的公共 `.env` 启用当前模块的运行参数，YAML 显式引用同名变量并保留本地回退；未启用模块与可选字段保留注释。环境文件的用途、加载优先级及私有值保存方式遵守 [环境配置规范](development.md#环境配置)，模块仍按公开 Schema 校验。
 
 复用当前应用服务端启动/关闭入口；SvelteKit 通常为 `$lib/server/init.ts`，API/fullstack 使用已有 service/serv 初始化文件。下列是启用 IAM 时的常见依赖关系，不要求无关应用安装这些模块：
 
@@ -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-app-review/SKILL.md

@@ -17,10 +17,10 @@ description: "审查 hai 应用的框架复用、安全边界、返回契约、
 
 ## 审查路径
 
-1. 读取当前项目入口规则、package scripts、lockfile 与差异，确认 SvelteKit、API workspace、fullstack 或 Vite/原生架构。
+1. 读取当前项目入口规则、用户指定需求、package scripts、lockfile 与差异，确认 SvelteKit、API workspace、fullstack 或 Vite/原生架构。业务以当前明确需求为准；模板角色、流程、限额和生成代码是初始实现，不能据此否定新需求或要求恢复已被替代的行为。
 2. 按 [development.md](../hai-app-create/development.md) 对需求核对实际框架能力、当前安装版本及适用安全边界；只读所涉及模块 skill、公开类型和相关调用方。
 3. 沿真实路径检查输入 → 身份/资源权限 → 服务/副作用 → 结果 → UI。先报告能导致安全或行为错误的问题，再检查风格与维护性。
-4. 对已授权修复做最小改动并验证。修正真实缺陷不以“已有测试未发现”为前提；保留用户已有改动与业务目标。
+4. 对已授权修复做最小改动并验证。修正真实缺陷不以“已有测试未发现”为前提；保留用户已有改动与业务目标。区分实现偏离需求的缺陷与待做的模板适配，核对测试及 AGENTS/skills/README 是否仍描述过期默认业务。
 
 ## 框架复用与架构
 

package/templates/skills/hai-app-tests/SKILL.md

@@ -13,11 +13,12 @@ description: "编写或修复 hai 应用的 Vitest/Playwright 测试，验证业
 | 适用场景 | 需求验收、缺陷回归或应用测试改进 |
 | 输入 | 验收条件、被测公共入口、现有测试和运行环境 |
 | 输出 | 可复现用例及明确区分静态、mock、浏览器/外部服务的结果 |
-| 限制 | Red 阶段仅要求新增目标用例因行为缺失而失败，不要求旧测试失败；不用删断言或修改预期掩盖缺陷。 |
+| 限制 | Red 阶段验证本次目标用例因行为缺失而失败，不要求无关回归失败；不能为迁就实现删除断言或修改预期。 |
 
 ## 使用路径
 
 - 先选单元/集成/浏览器层，复用测试 fixture，验证用户可观察结果。
+- 验收以用户当前明确要求和指定业务文档为准；模板测试不是不可变需求。规则已改变时同步更新或替换过期断言，记录新需求依据并覆盖新的授权/失败边界；保留仍适用的回归，不能用“保持旧测试通过”强留冲突业务。
 - 按 [development.md](../hai-app-create/development.md) 的真实行为与安全边界选测试；新增/改变业务行为、缺陷修复有目标用例，纯文案/格式/文档及无行为变化的可逆低影响修改不补镜像测试。
 - 不要求每个功能同时新增单元与 E2E；复用已有用例，选择能验证变化的最小适用层，关键跨层用户流程仍需端到端证据。
 - 新用例已通过时先检查是否已有能力；不能为达成 Red 人为破坏旧测试。

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

@@ -30,7 +30,7 @@
 
 1. **编写目标用例**：在适用的单元/集成/E2E 层验证目标变化，不重复创建其它层仅为打勾
 2. 对本次相关的正常、输入边界、越权/跨租户、依赖失败、事务/幂等/清理场景给出可观察断言；纯工具无需添加无关权限路径
-3. **运行测试确认新增目标用例因预期行为缺失而失败（既有回归保持通过）**：
+3. **运行测试确认目标用例因预期行为缺失而失败（仍适用的既有回归保持通过）**；明确新需求替代的模板断言同步更新并记录依据，不能为迁就实现改预期：
    ```bash
    pnpm --filter <app-name> test        # 目标位于单元/集成时使用
    pnpm --filter <app-name> test:e2e    # 目标位于 E2E 时使用；脚本以实际 package.json 为准

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 等子进程与服务退出后再删除数据库和上传文件，不依赖下一轮测试补清理。
 
 ## 按需参考
 

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

@@ -19,7 +19,8 @@ description: "使用 @h-ai/core 配置、日志、i18n、ID、Zod 错误本地
 
 - Node 启动用 core.init({ configDir }) 加载配置；勿传 logging 覆盖 _core.yml 中的日志设置，除非任务明确要求。
 - 应用名称、版本、环境、默认语言和日志设置统一从 `_core.yml` 经 core.config 获取，日志使用 core.logger；UI 不另维护硬编码副本。SvelteKit layout / fullstack app.info 仅下发公开字段白名单；独立 Vite mobile-app 在 Node 构建时解析并注入公开值，修改配置后重新构建。浏览器不加载 YAML，不接收完整模块配置、密钥或日志脱敏上下文。
-- HAI_<配置名>_<路径> 可整体覆盖根/对象/数组；父节点优先，未覆盖时才遍历已有叶子。camelCase 不拆词，约定变量优先于显式插值。
+- `HAI_<配置名>_<路径>` 可整体覆盖根/对象/数组；父节点优先，未覆盖时才遍历已有叶子。camelCase 不拆词，约定变量优先于显式插值。
+- 环境文件采用六类：`.env.example` 完整列出字段用途、默认值、枚举和范围；`.env` 为公共基础；`.env.dev`、`.env.test`、`.env.prod` 为公共环境覆盖，这五类均提交 Git。`.env.local` 为本机私有配置，不提交 Git。优先级为进程环境 > `.env.local` > 环境文件 > `.env`；Vite 在 Node 配置阶段调用 `core.config.loadEnvFiles({ mode, envDir })` 并检查 success 后注入进程，Node 脚本按相同顺序传入 `--env-file`。`core.init` 不自行读取 dotenv。
 - 配置 getter 与 ID/logger 方法不是 HaiResult；validate/load 等须检查 success。
 - 初始化前创建的默认、模块与嵌套 child Logger 在后续输出中应用当前全局 logging；configure/setLevel 也作用于已有实例。create 的显式 level/format/context 优先，未指定项动态继承。浏览器 json/pretty 与附加 redact 路径实际生效，消息文本仍由调用方脱敏。