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

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

@@ -2,13 +2,20 @@
 
 > 管理后台项目 AI 编程助手入口。优先结合 `README.md`、`.agents/skills/`、`src/routes/`、`src/lib/server/` 与 `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. 变更权限、登录、会话、导航或 CRUD 页面时，优先扩展现有 service / component，而不是临时散落逻辑。
 3. 修改页面、API、认证流程后，同步测试、README 和 i18n。
 
+页面统一继承根布局的 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/api/AGENTS.md

@@ -2,13 +2,20 @@
 
 > API 服务项目 AI 编程助手入口。优先结合 `README.md`、`.agents/skills/`、`apps/*-contract/src/**`、`apps/*-service/src/**` 与测试工作。
 
+## 需求与模板
+
+- 业务行为以用户当前明确要求及其指定的需求/设计文档为准。本文件、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 树。
 
@@ -30,9 +37,9 @@
 ## 架构边界
 
 - API 输入输出必须由 `apps/*-contract/src/**` 中的 Zod schema 与 contract 定义统一约束。
-- Service 通过 `@h-ai/serv` + `@h-ai/api-contract` 装配 HTTP App；不要退回到 SvelteKit API routes 架构。
+- 当前 Service 通过 `@h-ai/serv` + `@h-ai/api-contract` 装配 HTTP App；保留此架构时不混入 SvelteKit API routes，需求要求迁移时同步入口、contract、调用方与脚本。
 - Typed client / contract / service 三者保持同一份路径与类型定义，不要复制粘贴接口。
-- 不生成用户页面；不要引入 UI 专属依赖或页面文案。
+- 纯 API 需求不生成用户页面或引入 UI 专属依赖；需求增加前端时，按实际架构补充应用及其文案和验证。
 - 配置和密钥来自 `apps/*-service/config/` 与环境变量，禁止硬编码。
 
 ## 工作流程
@@ -41,6 +48,13 @@
 2. 修改 contract、响应格式、安全策略或配置时，同步 README、typed client 调用方与测试。
 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/fullstack/AGENTS.md.hbs

@@ -2,13 +2,20 @@
 
 Fullstack 多包工程入口。先读 README、根 workspace 脚本与相关 package/app；模块用法按需读取 `.agents/skills/*/SKILL.md` 及其引用。
 
+## 需求与模板
+
+- 业务行为以用户当前明确要求及其指定的需求/设计文档为准。本文件、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 树。
 
@@ -21,7 +28,11 @@ Fullstack 多包工程入口。先读 README、根 workspace 脚本与相关 pac
 - 修改前检索实现、调用方、测试和文档，优先复用现有 contract、procedure、共享组件与脚本。
 - 跨包变更先明确受影响的 contract、serv、shared、前端及交付流程，再同步调用方；不必输出固定问卷。
 
-## 架构边界
+## 初始架构
+
+- 页面统一继承公共 header/footer；新增 SPA 页面放 `packages/{{projectName}}-shared/src/lib/pages/**/*.svelte`，由 `HashRouter` 自动发现。菜单只维护业务入口，不维护路由表。
+
+以下为生成时的目录和分层；需求调整架构时同步相关包、脚本与说明，按调整后的实际结构工作。
 
 | 路径 | 职责 |
 | --- | --- |
@@ -33,20 +44,33 @@ Fullstack 多包工程入口。先读 README、根 workspace 脚本与相关 pac
 | `apps/{{projectName}}-desktop` | Svelte 5 + Vite + Tauri v2 桌面端，按选择生成 |
 | `apps/{{projectName}}-miniapp` | 选择 miniapp 时生成的预留说明与文案，当前不是可运行应用 |
 
-- 前端负责 UI 与请求编排；后端业务放 serv，共享能力放 shared。本样板默认不用 `@h-ai/kit`，不要混入 SvelteKit load / route 结构。
+- 前端负责 UI 与请求编排；后端业务放 serv，共享能力放 shared。保留当前 Vite SPA 架构时，不混入 SvelteKit load / route 结构；需要迁移时成套调整。
 - 用户文本按 shared 跨端文案与各 app 专属文案分工，同步现有 locale。
 - 本样板默认启用 IAM、reldb、cache、audit、storage 和 crypto，复用现有初始化与关闭顺序；新增模块前先检查依赖、配置与公开契约。
 - 应用名称、版本、环境、日志与 locale 配置通过 core 统一获取；浏览器显示来自服务端 `app.info`，不另写硬编码副本或将私有配置注入客户端。
 
-## 管理与安全边界
+## 初始管理业务
+
+这些是可运行示例的默认行为，按实际需求选择保留、修改或移除；不是 hai-framework 对所有应用的要求。
+
+- 初始使用 `admin` / `user` 两种角色：管理员进入用户、角色和审计管理，普通用户进入个人设置。角色代码、数量、权限粒度及可访问页面由业务需求决定；更换模型时同步服务端授权、资源范围与各端入口。
+- 初始角色页维护说明并显示人数，用户页分配角色；示例防止管理员自删除、自禁用、自降级及移除最后管理员。是否采用这些流程和保护由需求确定，保留的业务不变量需覆盖并发管理请求。
+- 默认头像接受 PNG/JPEG/WebP，最大 512 KiB；普通用户更新自己的头像，管理员可替用户更新。格式、限额和操作主体可调整，contract、客户端和服务端保持一致；仍需验证文件内容及资源访问权限，storage key 由服务端生成。
+- 默认用户与审计列表使用页码分页：`page >= 1`、`pageSize` 为 1–100、每页 20 条。分页方式、筛选和上限可按需求调整，同步 schema、procedure、store 和测试。
+- 默认将语言与主题偏好保存到当前用户 metadata，审计采用操作字段和资源标识。偏好来源、审计字段、保留期及失败策略按需求确定，敏感数据按实际用途脱敏。
+
+## 当前传输与安全契约
+
+- JSON 业务请求与响应经 typed api-client 和 serv 的 crypto transport 加解密，包含登录与刷新；健康/就绪检查和公开头像二进制资源使用既有例外。新增 API 沿用当前管道；需求调整传输方案时同步客户端、服务端及测试，不能静默绕过仍生效的安全契约。
+- Web 使用内存 access token 和 HttpOnly refresh Cookie；App 原生端装配 `createCapacitorTokenStorage`，浏览器预览沿用 Cookie；Desktop 原生端使用内存 TokenStorage，重启后重新登录。原生 body 刷新通道同时验证 `X-HAI-Token-Transport: body`、端对应的 `x-request-client` 与受信完整 Origin，刷新请求沿用这些头。调整会话方案时保持凭据保护和通道校验；敏感 token 不写 localStorage 或普通配置文件。
+- 服务端依据实际权限模型验证每个受保护操作，个人操作绑定当前会话，代他人操作验证对应权限；不能只靠隐藏导航保护资源。SQL 动态值参数化，日志与审计不泄露密码、token 或密钥。
+
+## 代码注释与示例
 
-- `admin` / `user` 是固定角色代码。管理员进入用户、角色和审计管理；普通用户只进入个人设置。服务端为每个管理操作验证角色，个人资料、密码和头像按当前会话绑定用户，不能只靠导航隐藏保护权限。
-- 角色管理更新说明并显示人数，用户管理负责角色分配；保留当前管理员的自删除、自禁用、自降级及最后管理员保护，并验证并发管理请求。
-- JSON 业务请求与响应统一经 typed api-client 和 serv 的 crypto transport 加解密，包含登录与刷新；健康/就绪检查和公开头像二进制资源遵循已有例外，不能为新增业务 API 绕过传输加密。
-- Web 使用内存 access token 和 HttpOnly refresh Cookie；App 原生端装配 `createCapacitorTokenStorage`，浏览器预览沿用 Cookie；Desktop 原生端使用内存 TokenStorage，重启后重新登录。原生 body 刷新通道同时验证 `X-HAI-Token-Transport: body`、端对应的 `x-request-client` 与受信完整 Origin，刷新请求沿用这些头。敏感 token 不写 localStorage，不擅自将其持久化到普通配置文件。
-- 头像接受 PNG/JPEG/WebP，最大 512 KiB；contract、客户端与服务端校验保持一致。服务端验证实际图片数据并生成 storage key；普通用户仅更新自己的头像，管理员可替用户更新。
-- 用户与审计查询按 contract 分页，`page >= 1`、`pageSize` 为 1–100；页面默认每页 20 条。新增筛选同步 schema、procedure、store 和测试，SQL 值参数化。
-- 语言与主题偏好保存到当前用户 metadata，客户端只应用已支持的值。审计仅记录操作字段和资源标识，不记录密码、token、头像内容或联系信息。
+- 尽可能补充有信息量的中文 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/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 build:prod` 或 `pnpm dev:prod` 预览配置 |
+| 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,6 +180,33 @@ 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
+}
+```
+
 ## 验证与交付
 
 - 对新增/改变行为按 [hai-app-tests](../hai-app-tests/SKILL.md) 写有意义的测试；目标用例先因行为缺失失败，既有回归保持通过。UI/路由改动覆盖真实流程、异步失败与权限路径；纯文案/文档按影响验证。

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 时的常见依赖关系，不要求无关应用安装这些模块：
 

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 为准