@h-ai/cli 0.1.0-alpha.20 → 0.1.0-alpha.22

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

@@ -0,0 +1,65 @@
+# AGENTS.md
+
+> H5 移动端项目 AI 编程助手入口。优先结合 `README.md`、`.agents/skills/`、`src/routes/`、`messages/*` 与移动端测试工作。
+
+## 行为契约
+
+1. 每次响应第一行写：`规模: XS|S|M|L — <一句话意图>`。
+2. 任务规模 ≥ M 时，先回顾现有路由、触屏交互、messages、测试与 `.agents/skills/*/SKILL.md`。
+3. 在写第一行新代码前，用 1 行回答 Q1-Q7 必要性自检。
+4. 任务规模 ≥ M 时，说明将影响的页面、移动端导航、API、messages、测试和 README。
+
+## 必要性自检（M / L 任务必须输出）
+
+- Q1：已有页面 / layout / 底部导航 / 组件是否可复用？
+- Q2：能否扩展现有路由、移动端组件和 API，而不是新增抽象层？
+- Q3：当前真实调用点是哪些触屏页面、导航和 API？
+- Q4：能否用更少的 route、section、helper 解决？
+- Q5：是否把服务端、中间态或敏感 token 细节泄漏给页面层？
+- Q6：是否与现有移动端布局、i18n、脚本和路由结构一致？
+- Q7：是否比较过更安全的鉴权、缓存和请求处理方式？
+
+## 影响分析（M / L 任务必须输出）
+
+- 直接影响：哪些页面、layout、导航、API、messages、README、测试会变。
+- 间接影响：哪些移动端流程、权限入口、共享组件和接口断言需要同步。
+
+## 项目定位
+
+本项目是 hai-framework H5 模板，面向移动浏览器，重点是触屏布局、移动端导航、i18n、API 调用与端到端流程。
+
+## 架构边界
+
+- 使用移动端友好的布局和 `@h-ai/ui` 移动组件。
+- 页面文本走 i18n，同步中英文 messages。
+- API 输入必须校验，业务错误按 HaiResult 传递。
+- `+server.ts` 只能导出 handler 和 SvelteKit 允许的配置项；helper 放到 `src/lib/**`。
+- 敏感 token 不要写入不安全存储；优先复用模板已有的鉴权与请求模式。
+- 本样板默认不以 `@h-ai/serv`、`@h-ai/api-contract`、`@h-ai/api-client`、`@h-ai/capacitor` 作为主架构。
+
+## 工作流程
+
+1. 先搜索现有移动端页面、导航、messages、API 和测试。
+2. 修改导航、触屏交互、API 或认证流程时，同步 README、i18n 和测试。
+3. 每次改动后运行质量门禁，不能留下“已知失败”。
+
+## 质量门禁
+
+```bash
+pnpm typecheck
+pnpm lint
+pnpm build
+pnpm test
+pnpm test:e2e
+```
+
+## 完成条件
+
+- 页面、导航、API、i18n 与测试保持一致。
+- 最终回复说明门禁状态、已更新移动端流程 / 文档与未完成项。
+
+## 优先 Skills
+
+- `hai-build`、`hai-app-create`、`hai-app-review`、`hai-app-tests`
+- `hai-kit`、`hai-ui`、`hai-reldb`、`hai-cache`
+- 其它 `hai-*` 模块按需读取

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

@@ -0,0 +1,19 @@
+# CLAUDE.md
+
+@AGENTS.md
+
+> Claude Code H5 项目指引。共享规范通过 `@AGENTS.md` 复用；具体模块用法按需读取 `.agents/skills/`。
+
+如果当前运行环境未自动展开 `@AGENTS.md`，必须先手动阅读 `AGENTS.md`，再开始修改代码或文档。
+
+## 开始工作前
+
+- 回复第一行保持：`规模: XS|S|M|L — <一句话意图>`。
+- 任务规模 ≥ M 时，先输出 Q1-Q7 必要性自检与影响分析。
+- 修改前先看 `src/routes/`、移动端导航、`messages/*` 与测试。
+
+## H5 特有提醒
+
+- 优先复用现有移动端布局、底部导航和 `@h-ai/ui` 组件。
+- 页面文案、导航标签和错误提示都要同步 i18n。
+- 不要把 `@h-ai/serv` / `@h-ai/api-client` / `@h-ai/capacitor` 当成当前 H5 样板的默认主架构。

package/templates/skills/bridges/h5/copilot-instructions.md

@@ -0,0 +1,44 @@
+# GitHub Copilot 项目指令
+
+> H5 移动端工程指引。详细模块用法按需读取 `.agents/skills/`。
+
+## 行为契约
+
+- 每次响应第一行写：`规模: XS|S|M|L — <一句话意图>`。
+- 任务规模 ≥ M 时，先输出 Q1-Q7 必要性自检与影响分析，再开始修改。
+- 修改前先阅读 `AGENTS.md`、`README.md`、相关页面 / messages / 测试与 `.agents/skills/*/SKILL.md`。
+
+## 技术栈要点
+
+- SvelteKit + Svelte 5 Runes。
+- TailwindCSS / DaisyUI / `@h-ai/ui` 移动组件。
+- Paraglide i18n。
+
+## 技术边界
+
+- 页面组件只负责渲染和交互；复杂业务逻辑放在服务层或模块 API。
+- 移动端文案、导航和错误提示全部走 i18n。
+- `+server.ts` 只能导出 handler 与官方允许的配置项；helper 放到 `src/lib/**`。
+- 优先复用现有移动端导航与组件，不要引入不必要的桌面式交互。
+- 禁止 `any`、`console.log`、硬编码密钥。
+
+## 开发流程
+
+1. 先检索现有移动端页面、导航、messages、API 和测试。
+2. 修改导航、API 或认证流程时，同步 README、i18n 和测试。
+3. 不要把未运行或失败的门禁写成“已通过”。
+
+## 质量门禁
+
+```bash
+pnpm typecheck
+pnpm lint
+pnpm build
+pnpm test
+pnpm test:e2e
+```
+
+## 完成条件
+
+- 页面、导航、API、i18n 与测试同步更新。
+- 最终交付说明中列出门禁状态、受影响流程 / 文档与未完成项。

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

@@ -0,0 +1,77 @@
+# AGENTS.md
+
+> Capacitor Mobile App 项目 AI 编程助手入口。优先结合 `README.md`、`.agents/skills/`、`src/`、`messages/*` 与移动端测试工作。
+
+## 行为契约
+
+1. 每次响应第一行写：`规模: XS|S|M|L — <一句话意图>`。
+2. 任务规模 ≥ M 时，先回顾现有页面、原生桥接、API 调用、messages、测试与 `.agents/skills/*/SKILL.md`。
+3. 在写第一行新代码前，用 1 行回答 Q1-Q7 必要性自检。
+4. 任务规模 ≥ M 时，说明将影响的页面、状态管理、原生桥接、API、messages、README 和测试。
+
+## 必要性自检（M / L 任务必须输出）
+
+- Q1：已有页面、store、service、Capacitor 封装是否可复用？
+- Q2：能否扩展现有 `src/lib/capacitor.ts`、service 或组件，而不是新建抽象层？
+- Q3：当前真实调用点是哪些页面、原生能力或 API 流程？
+- Q4：能否用更少的 page、store、helper 解决？
+- Q5：是否把原生桥接、token 或 API 细节泄漏给页面层？
+- Q6：是否与现有 Svelte 5 + Vite + Capacitor 目录、脚本和 i18n 一致？
+- Q7：是否比较过更安全的存储、权限和网络调用方案？
+
+## 影响分析（M / L 任务必须输出）
+
+- 直接影响：哪些页面、store、原生桥接、messages、README、测试和打包脚本会变。
+- 间接影响：哪些 Android/iOS 权限、API 调用方、构建/打包流程和共享组件需要同步。
+
+## 项目概述
+
+本项目是 hai-framework Mobile/Capacitor 模板：直接使用 Svelte 5 + Vite 输出 SPA，Capacitor 负责 Android/iOS 原生壳和设备能力。
+
+## 架构边界
+
+- 不使用 SvelteKit 路由、server hooks 或 `@h-ai/kit`。
+- 不新增 `+page.svelte`、`+layout.svelte`、`hooks.server.ts`、`src/routes/*` 等 SvelteKit 文件。
+- 原生能力通过 `@h-ai/capacitor` 使用；token 原生端使用 Capacitor 安全存储，Web 预览仅使用内存存储。
+- API 调用使用 `@h-ai/api-client`，业务错误按 HaiResult 处理。
+- 页面文本走 i18n，同步中英文 messages。
+- 原生桥接与设备调用放在 `src/lib/capacitor.ts` 或 service，避免散落在页面模板中。
+- 本样板默认不使用 `@h-ai/core`、`@h-ai/kit`、`@h-ai/serv`、`@h-ai/api-contract` 作为主架构。
+
+## 常用命令
+
+```bash
+pnpm build
+pnpm cap:sync:android
+pnpm cap:run:android
+pnpm cap:build:android:debug
+pnpm cap:build:android:release
+```
+
+## 工作流程
+
+1. 先搜索现有页面、stores、原生桥接、API client、messages 和测试。
+2. 修改原生能力、权限、登录态或 API 流程时，同步 README、i18n 和测试。
+3. 每次改动后运行质量门禁，不能留下“已知失败”。
+
+## 质量门禁
+
+```bash
+pnpm typecheck
+pnpm lint
+pnpm build
+pnpm test
+pnpm test:e2e
+```
+
+## 完成条件
+
+- 页面、原生桥接、API、i18n 与测试保持一致。
+- 若改动影响打包 / 原生权限 / 设备能力，README 与脚本说明必须同步更新。
+- 最终回复说明门禁状态、已更新移动端流程 / 文档与未完成项。
+
+## 优先 Skills
+
+- `hai-build`、`hai-app-review`、`hai-app-tests`
+- `hai-ui`、`hai-api-client`、`hai-capacitor`
+- 其它 `hai-*` 模块按需读取

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

@@ -0,0 +1,19 @@
+# CLAUDE.md
+
+@AGENTS.md
+
+> Claude Code Capacitor Mobile App 项目指引。共享规范通过 `@AGENTS.md` 复用；具体模块用法按需读取 `.agents/skills/`。
+
+如果当前运行环境未自动展开 `@AGENTS.md`，必须先手动阅读 `AGENTS.md`，再开始修改代码或文档。
+
+## 开始工作前
+
+- 回复第一行保持：`规模: XS|S|M|L — <一句话意图>`。
+- 任务规模 ≥ M 时，先输出 Q1-Q7 必要性自检与影响分析。
+- 修改前先看 `src/`、`src/lib/capacitor.ts`、API client、messages 和测试。
+
+## Mobile/Capacitor 特有提醒
+
+- 本项目是 Svelte 5 + Vite，不是 SvelteKit；不要新建 `+page.svelte`、`hooks.server.ts` 等文件。
+- 设备能力与 token 存储放在原生桥接 / service 层，不要散落进页面模板。
+- 页面文本、错误提示和设置项都要同步 i18n。

package/templates/skills/bridges/mobile-app/copilot-instructions.md

@@ -0,0 +1,45 @@
+# GitHub Copilot 项目指令
+
+> Capacitor Mobile App 工程指引。详细模块用法按需读取 `.agents/skills/`。
+
+## 行为契约
+
+- 每次响应第一行写：`规模: XS|S|M|L — <一句话意图>`。
+- 任务规模 ≥ M 时，先输出 Q1-Q7 必要性自检与影响分析，再开始修改。
+- 修改前先阅读 `AGENTS.md`、`README.md`、相关页面 / 原生桥接 / 测试与 `.agents/skills/*/SKILL.md`。
+
+## 技术栈要点
+
+- Svelte 5 + Vite SPA（无 SvelteKit）。
+- Capacitor Android/iOS 原生壳。
+- `@h-ai/capacitor` 负责原生能力和安全 token 存储。
+- `@h-ai/api-client` 负责 typed API 调用。
+
+## 技术边界
+
+- 不新增 `+page.svelte` / `+layout.svelte` / `hooks.server.ts` 等 SvelteKit 文件。
+- 原生能力封装在 `src/lib/capacitor.ts` 或 service，不写进页面模板。
+- 原生 token 使用安全存储；Web 预览不要落到不安全持久化存储。
+- 页面文本走 i18n。
+- 禁止 `any`、`console.log`、硬编码密钥。
+
+## 开发流程
+
+1. 先检索现有页面、store、原生桥接、API client、messages 和测试。
+2. 修改原生能力、权限、登录态或 API 流程时，同步 README、i18n 和测试。
+3. 不要把未运行或失败的门禁写成“已通过”。
+
+## 质量门禁
+
+```bash
+pnpm typecheck
+pnpm lint
+pnpm build
+pnpm test
+pnpm test:e2e
+```
+
+## 完成条件
+
+- 页面、原生桥接、API、i18n 与测试同步更新。
+- 交付说明中列出门禁状态、受影响的设备能力 / 文档与未完成项。

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

@@ -0,0 +1,65 @@
+# AGENTS.md
+
+> 企业官网项目 AI 编程助手入口。优先结合 `README.md`、`.agents/skills/`、`src/routes/`、`messages/*` 与测试工作。
+
+## 行为契约
+
+1. 每次响应第一行写：`规模: XS|S|M|L — <一句话意图>`。
+2. 任务规模 ≥ M 时，先回顾现有页面、SEO 相关实现、表单/API、测试与 `.agents/skills/*/SKILL.md`。
+3. 在写第一行新代码前，用 1 行回答 Q1-Q7 必要性自检。
+4. 任务规模 ≥ M 时，说明将影响的页面、表单、messages、SEO 元信息、测试和 README。
+
+## 必要性自检（M / L 任务必须输出）
+
+- Q1：已有页面 / layout / 组件 / 表单是否可复用？
+- Q2：能否扩展现有 route、section、组件，而不是新增抽象层？
+- Q3：当前真实调用点是哪些页面、表单或 API？
+- Q4：能否用更少的 section、组件、helper 解决？
+- Q5：是否把后端、存储或中间态细节泄漏给页面层？
+- Q6：是否与现有路由、i18n、SEO 和脚本一致？
+- Q7：是否比较过更安全的表单校验、SEO 和构建方案？
+
+## 影响分析（M / L 任务必须输出）
+
+- 直接影响：哪些页面、layout、表单/API、messages、README、测试会变。
+- 间接影响：哪些导航入口、SEO 标签、部署脚本和共享组件需要同步。
+
+## 项目定位
+
+本项目是 hai-framework 企业官网模板，重点是 SvelteKit 页面、SEO、i18n、表单/API 边界和可部署构建产物。
+
+## 架构边界
+
+- 页面内容与导航文案全部走 i18n，同步中英文 messages。
+- 表单和 API 输入必须 Zod 校验。
+- UI 组件优先使用 `@h-ai/ui`，不要重复实现已有组件。
+- `+server.ts` 只能导出 handler 和 SvelteKit 允许的配置项；helper 放到 `src/lib/**`。
+- SEO 元信息、路由结构和消息文案要一起维护。
+- 本样板默认不以 `@h-ai/serv`、`@h-ai/api-contract`、`@h-ai/api-client`、`@h-ai/capacitor` 作为主架构。
+
+## 工作流程
+
+1. 先搜索现有页面、layout、组件、messages、表单/API 和测试。
+2. 修改页面时同步 README、i18n、测试和 SEO 相关元信息。
+3. 每次改动后运行质量门禁，不能留下“已知失败”。
+
+## 质量门禁
+
+```bash
+pnpm typecheck
+pnpm lint
+pnpm build
+pnpm test
+pnpm test:e2e
+```
+
+## 完成条件
+
+- 页面、表单、SEO、i18n 与测试保持一致。
+- 最终回复说明门禁状态、已更新页面 / 表单 / 文档与未完成项。
+
+## 优先 Skills
+
+- `hai-build`、`hai-app-create`、`hai-app-review`、`hai-app-tests`
+- `hai-kit`、`hai-ui`、`hai-reldb`、`hai-cache`
+- 其它 `hai-*` 模块按需读取

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

@@ -0,0 +1,19 @@
+# CLAUDE.md
+
+@AGENTS.md
+
+> Claude Code 企业官网项目指引。共享规范通过 `@AGENTS.md` 复用；具体模块用法按需读取 `.agents/skills/`。
+
+如果当前运行环境未自动展开 `@AGENTS.md`，必须先手动阅读 `AGENTS.md`，再开始修改代码或文档。
+
+## 开始工作前
+
+- 回复第一行保持：`规模: XS|S|M|L — <一句话意图>`。
+- 任务规模 ≥ M 时，先输出 Q1-Q7 必要性自检与影响分析。
+- 修改前先看 `src/routes/`、`messages/*`、表单/API 与测试。
+
+## 官网特有提醒
+
+- 页面文案、导航、SEO 元信息与 i18n 需要一起维护。
+- 优先复用现有 `@h-ai/ui` 组件，不要重复造轮子。
+- 不要把 `@h-ai/serv` / `@h-ai/api-client` 当成默认官网主架构。

package/templates/skills/bridges/website/copilot-instructions.md

@@ -0,0 +1,44 @@
+# GitHub Copilot 项目指令
+
+> 企业官网工程指引。详细模块用法按需读取 `.agents/skills/`。
+
+## 行为契约
+
+- 每次响应第一行写：`规模: XS|S|M|L — <一句话意图>`。
+- 任务规模 ≥ M 时，先输出 Q1-Q7 必要性自检与影响分析，再开始修改。
+- 修改前先阅读 `AGENTS.md`、`README.md`、相关页面 / messages / 测试与 `.agents/skills/*/SKILL.md`。
+
+## 技术栈要点
+
+- SvelteKit 页面与路由。
+- TailwindCSS / DaisyUI / `@h-ai/ui`。
+- Paraglide i18n，messages 位于 `messages/zh-CN.json` 与 `messages/en-US.json`。
+
+## 技术边界
+
+- 所有页面文案走 i18n。
+- 表单/API 输入使用 Zod 校验。
+- `+server.ts` 只能导出 handler 与官方允许的配置项；helper 放到 `src/lib/**`。
+- 页面内容、SEO 元信息和测试要一起维护。
+- 禁止 `any`、`console.log`、硬编码密钥。
+
+## 开发流程
+
+1. 先检索现有页面、组件、messages、表单/API 和测试。
+2. 修改页面或 SEO 相关实现时，同步 README、i18n、测试和元信息。
+3. 不要把未运行或失败的门禁写成“已通过”。
+
+## 质量门禁
+
+```bash
+pnpm typecheck
+pnpm lint
+pnpm build
+pnpm test
+pnpm test:e2e
+```
+
+## 完成条件
+
+- 页面、表单、SEO、i18n 与测试同步更新。
+- 最终交付说明中列出门禁状态、受影响页面 / 文档与未完成项。

package/templates/skills/copilot-instructions.md

@@ -1,80 +1,43 @@
 # GitHub Copilot 项目指令
 
-> 本文件作为 GitHub Copilot 的项目级指引，指向 `.agents/skills/` 中的详细 Skill 文件。
+> 本文件作为 Copilot 项目级指引；当缺少 appType 专属桥接时，使用本文件作为 generic fallback。详细用法按需读取 `.agents/skills/`。
 
-## 项目概述
+## 行为契约
 
-本项目使用 [hai-framework](https://github.com/nicehero/hai-framework) 构建，基于 SvelteKit 2 + Svelte 5 (Runes) + TailwindCSS 4 + DaisyUI 5 + TypeScript 5.7+。
+- 每次响应第一行写：`规模: XS|S|M|L — <一句话意图>`。
+- 任务规模 ≥ M 时，先输出 Q1-Q7 必要性自检与影响分析，再开始修改。
+- 修改前先阅读 `README.md`、相关测试、`AGENTS.md` 与对应 `.agents/skills/*/SKILL.md`。
+- 不要把未运行或失败的门禁写成“已通过”。
 
-## 技术栈要点
+## 通用约定
 
-- **前端框架**：Svelte 5 (Runes: `$props()`, `$state()`, `$derived()`, `$effect()`)
-- **SvelteKit 应用层**：使用文件系统路由、`+layout/+page`、`load` 与 `hooks.server.ts` 做 UI/请求编排；SSR/SPA/静态输出以具体 app 的 adapter 与配置为准
-- **Fullstack 服务端**：前后端分离工程的业务 API 在 `packages/<project>-serv` 中通过 `@h-ai/serv` 实现；不要把服务端业务逻辑塞进 SvelteKit 页面、`load` 或前端组件
-- **样式**：TailwindCSS 4 + DaisyUI 5
-- **后端框架**：hai-framework (`@h-ai/core`, `@h-ai/kit`, `@h-ai/reldb`, `@h-ai/iam` 等)
-- **统一模式**：`module.init(config) → use → module.close()`，所有操作返回 `HaiResult<T>`
-- **单元测试**：Vitest
-- **E2E 测试**：Playwright
-- **包管理**：pnpm
-
-## 编码规范
-
-- 禁止 `any`（使用 `unknown` + 缩窄）
-- 禁止 `console.log`（使用 `core.logger`）
-- 禁止硬编码密钥
-- `xx-main.ts` 仅做生命周期管理和 API 编排，禁止在 main 中编写具体业务逻辑（委托给 `xx-functions.ts` / `xx-runner.ts` 等）
-- 用户可见文本必须走 i18n（`$lib/paraglide/messages.js`）
-- HaiResult 错误直接透传，不重新包装
-- 框架模块公共 API 不抛异常，统一返回 `HaiResult<T>`；不要用 `try/catch` 处理模块返回的错误
-- 日志消息英文、简洁动宾结构
-- 代码注释中文
-
-## Skills 目录
-
-详细的开发指南位于 `.agents/skills/` 目录：
-
-| Skill            | 说明                                                  |
-| ---------------- | ----------------------------------------------------- |
-| `hai-build`      | 项目架构、模块依赖、初始化顺序、编码标准              |
-| `hai-core`       | 配置加载、日志、i18n、HaiResult 模型、模块生命周期       |
-| `hai-kit`        | SvelteKit 集成：`handle` hook、守卫、中间件、响应、校验 |
-| `hai-ui`         | UI 组件库：三层架构、自动导入、主题、i18n             |
-| `hai-reldb`      | 数据库操作：DDL、SQL、CRUD、事务、分页                |
-| `hai-iam`        | 认证与权限：密码/OTP/LDAP、会话、RBAC                 |
-| `hai-crypto`     | 加密：SM2/SM3/SM4、密码哈希、随机生成                 |
-| `hai-cache`      | 缓存：内存/Redis、TTL、集合操作、分布式锁             |
-| `hai-storage`    | 存储：本地/S3、上传下载、预签名 URL                   |
-| `hai-ai`         | AI：LLM 调用、MCP 服务器、工具定义、流处理            |
-| `hai-app-create` | TDD 驱动的功能创建（先测试后实现）                    |
-| `hai-app-review` | 应用代码审查（含 TDD 合规检查）                       |
-| `hai-app-tests`  | TDD 测试规范（Vitest 单元测试 + Playwright E2E）      |
-| `hai-ci`         | CI/CD、GitHub Actions、质量门禁与 workflow 安全       |
-| `hai-pr-review`  | PR / Issue 交付审查、AI Review 策略、CODEOWNERS 与合并门禁 |
-| `hai-framework-sync` | hai-framework 模板源头与应用仓库同步            |
+- 使用 hai-framework 的模块生命周期：`init(config) -> use -> close()`。
+- 公共 API 返回 `HaiResult<T>` 或 `Promise<HaiResult<T>>`，业务错误不要直接 `throw`。
+- 禁止 `any`、`console.log`、硬编码密钥。
+- 用户可见文本必须走 i18n，并同步中英文消息文件。
+- 代码注释中文，日志消息英文。
+- 若项目使用 SvelteKit，`+server.ts` 只能导出 handler 与官方允许的配置项。
 
 ## 开发流程
 
-**必须遵循 TDD**：先写测试（Red）→ 确认失败 → 再实现（Green）→ 确认通过 → 重构（Refactor）。
+1. 先用全局检索确认现有实现、引用点、测试和文档。
+2. 优先复用现有目录和模块，不新增无真实调用点的抽象。
+3. 修改公共类型、API、模板或共享逻辑后，同步 README、测试和所有依赖方。
 
 ## 质量门禁
 
-改动完成后按顺序执行，失败必须先修复，不能把已知失败留给下一轮：
-
-1. `pnpm typecheck`
-2. `pnpm lint`（可先 `pnpm lint:fix`，再重新执行 `pnpm lint`）
-3. `pnpm build`（涉及构建产物、打包配置、前后端分离工程或发布路径时必须执行）
-4. `pnpm test`
-5. `pnpm --filter <app-or-package> test:e2e`（涉及 UI、路由、浏览器交互或端到端流程时必须执行）
+按影响范围执行：
 
-优先使用 `pnpm --filter <workspace-name>` 缩小验证范围；跨包契约、共享类型或根配置变更必须提升到根命令验证。
+```bash
+pnpm typecheck
+pnpm lint
+pnpm build
+pnpm test
+pnpm test:e2e
+```
 
 ## 完成条件
 
-- **测试同步**：新增/修改功能必须补单元测试；UI、路由和关键用户流程必须补 E2E 或更新现有 E2E。
-- **文档同步**：README、`.agents/skills/**/SKILL.md`、代码注释与实际行为保持一致；生成模板改动要同步模板与测试断言。
-- **i18n 同步**：所有用户可见文本必须走 i18n，并同时更新 `zh-CN` 与 `en-US` 消息文件。
-- **类型/契约同步**：公共类型、API contract、client、server procedure 与调用方必须一起更新，不能只改一端。
-- **错误处理同步**：新增错误码、错误消息或 HaiResult 形态时，同步文档、测试和调用方处理逻辑。
-- **依赖方传导**：修改共享包、公共 API 或模板后，用全局检索确认引用点，并更新受影响的 `packages/*`、`apps/*`、CLI 模板/脚手架。
-- **完成报告**：最终回复必须列出 typecheck/lint/build/test/e2e 状态、已更新文档、已更新依赖方；未执行或未通过的项目必须说明原因与后续动作。
+- 门禁失败必须先修复；未执行项要写明原因。
+- README、i18n、测试、代码注释与实现保持一致。
+- 最终交付说明中列出门禁状态、已同步文档与依赖方。

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

@@ -6,6 +6,7 @@ description: 以 TDD 方式在应用中创建新功能：先编写测试定义
 # hai-app-create — TDD 驱动的应用功能创建规范
 
 > 面向 AI 助手的应用功能创建指南。**必须遵循 TDD**：先写测试（Red）→ 再实现（Green）→ 再重构（Refactor）。
+> 若目标是纯 API service workspace，优先围绕 `apps/*-contract`、`apps/*-service` 与测试组织改动，而不是套用页面/路由脚手架。
 
 ---
 

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

@@ -5,7 +5,7 @@ description: 对应用代码进行审查：检查 TDD 合规性、架构分层
 
 # hai-app-review — 应用代码审查规范
 
-> 面向 AI 助手的应用代码审查指南。用于审查使用 hai-framework 构建的 SvelteKit 应用。本技能也是 TDD Refactor 阶段的执行入口。
+> 面向 AI 助手的应用代码审查指南。用于审查使用 hai-framework 构建的 SvelteKit 应用、纯 Svelte/Vite 客户端与 API service workspace。本技能也是 TDD Refactor 阶段的执行入口。
 
 ---
 

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

@@ -216,7 +216,32 @@ describe('CreateUserSchema', () => {
 import process from 'node:process'
 import { defineConfig } from '@playwright/test'
 
-const baseURL = process.env.BASE_URL || 'http://localhost:4173'
+const DEFAULT_BASE_URL = 'http://localhost:4173'
+const baseURL = process.env.BASE_URL || DEFAULT_BASE_URL
+const previewHost = resolveHostFromBaseUrl(baseURL, 'localhost')
+const previewPort = resolvePortFromBaseUrl(baseURL, '4173')
+
+function resolveHostFromBaseUrl(urlString: string, fallbackHost: string): string {
+  try {
+    const url = new URL(urlString)
+    return url.hostname || fallbackHost
+  }
+  catch {
+    return fallbackHost
+  }
+}
+
+function resolvePortFromBaseUrl(urlString: string, fallbackPort: string): string {
+  try {
+    const url = new URL(urlString)
+    if (url.port)
+      return url.port
+    return url.protocol === 'https:' ? '443' : '80'
+  }
+  catch {
+    return fallbackPort
+  }
+}
 
 export default defineConfig({
   testDir: './e2e',
@@ -233,8 +258,8 @@ export default defineConfig({
     screenshot: 'only-on-failure',
   },
   webServer: {
-    command: 'pnpm build && pnpm preview --port 4173 --strictPort',
-    env: { HAI_E2E: '1' },
+    command: `pnpm build && pnpm preview --host ${previewHost} --port ${previewPort} --strictPort`,
+    env: { HAI_E2E: '1', BASE_URL: baseURL },
     url: baseURL,
     reuseExistingServer: false,
     timeout: 180_000,

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

@@ -17,7 +17,7 @@ description: 使用 @h-ai/capacitor 桥接 Capacitor 原生能力（Token 安全
 
 ## 适用场景
 
-- Android/iOS 原生应用开发（SvelteKit + Capacitor）
+- Android/iOS 原生应用开发（Svelte 5 + Vite + Capacitor）
 - Token 安全存储（`@aparajita/capacitor-secure-storage`）
 - 设备信息获取（平台、型号、版本）
 - 推送通知注册与监听（FCM / APNs）
@@ -218,7 +218,7 @@ await capacitor.statusBar.show()
 
 ## 常见模式
 
-### Android 应用标准初始化
+### Mobile App 标准初始化
 
 ```typescript
 // src/lib/capacitor.ts
@@ -241,10 +241,10 @@ export async function initCapacitor() {
 ```
 
 ```svelte
-<!-- src/routes/+layout.svelte -->
-<script lang="ts">
+<!-- src/App.svelte -->
+<script lang='ts'>
   import { onMount } from 'svelte'
-  import { initCapacitor } from '$lib/capacitor'
+  import { initCapacitor } from './lib/capacitor'
 
   onMount(() => { initCapacitor() })
 </script>
@@ -252,27 +252,19 @@ export async function initCapacitor() {
 
 ### SPA 模式配置（必需）
 
-Capacitor 应用必须使用 SPA 模式：
+Capacitor 应用使用 Vite 构建 SPA，并让原生壳读取 `dist`：
 
 ```typescript
-// src/routes/+layout.ts
-export const prerender = true
-export const ssr = false
-```
+// capacitor.config.ts
+import type { CapacitorConfig } from '@capacitor/cli'
 
-```javascript
-// svelte.config.js
-import adapter from '@sveltejs/adapter-static'
-
-const config = {
-  kit: {
-    adapter: adapter({
-      pages: 'build',
-      assets: 'build',
-      fallback: 'index.html',
-    }),
-  },
+const config: CapacitorConfig = {
+  appId: 'com.example.app',
+  appName: 'Example App',
+  webDir: 'dist',
 }
+
+export default config
 ```
 
 ### Token 存储 + 认证流程