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

package/templates/base/tsconfig.json.hbs

@@ -0,0 +1,50 @@
+{{#if isSvelteOnlyApp}}
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "moduleDetection": "force",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "types": ["svelte", "vite/client", "node", "vitest/globals"],
+    "allowJs": true,
+    "checkJs": false,
+    "strict": true,
+    "noEmit": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true
+  },
+  "include": [
+    "src/**/*.ts",
+    "src/**/*.svelte",
+    "tests/**/*.ts",
+    "vite.config.ts",
+    "svelte.config.js"
+  ],
+  "exclude": ["node_modules", "dist", "build", "android", "ios"]
+}
+{{else}}
+{
+  "extends": "./.svelte-kit/tsconfig.json",
+  "compilerOptions": {
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "allowJs": true,
+    "checkJs": false,
+    "strict": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true
+  },
+  "include": [
+    "src/**/*",
+    "src/**/*.svelte"
+  ],
+  "exclude": [
+    "node_modules",
+    ".svelte-kit"
+  ]
+}
+{{/if}}

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

@@ -6,7 +6,11 @@ import process from 'node:process'
 {{#if hasI18n}}
 import { paraglideVitePlugin } from '@inlang/paraglide-js'
 {{/if}}
+{{#if isSvelteOnlyApp}}
+import { svelte } from '@sveltejs/vite-plugin-svelte'
+{{else}}
 import { sveltekit } from '@sveltejs/kit/vite'
+{{/if}}
 {{#if hasUi}}
 import tailwindcss from '@tailwindcss/vite'
 {{/if}}
@@ -18,7 +22,11 @@ export default defineConfig(({ mode }) => {
 
   return {
     plugins: [
+  {{#if isSvelteOnlyApp}}
+      svelte(),
+  {{else}}
       sveltekit(),
+  {{/if}}
 {{#if hasUi}}
       tailwindcss(),
 {{/if}}
@@ -35,9 +43,11 @@ export default defineConfig(({ mode }) => {
       exclude: ['bits-ui'],
     },
 {{/if}}
+{{#unless isSvelteOnlyApp}}
     ssr: {
       noExternal: [/@h-ai\//],
     },
+{{/unless}}
     server: {
       fs: {
         allow: [path.resolve(process.cwd())],

package/templates/skills/AGENTS.md

@@ -1,37 +1,70 @@
 # AGENTS.md
 
-> 通用 AI 编程助手指引。详细 Skill 文件位于 `.agents/skills/` 目录。
+> 通用 AI 编程助手入口。优先阅读 `README.md`、现有测试与 `.agents/skills/`；本文件同时作为 `hai add` / AI 支持回填时的 generic fallback。
+
+## 行为契约
+
+1. 每次响应第一行写：`规模: XS|S|M|L — <一句话意图>`。
+2. 任务规模 ≥ M 时，先回顾 `README.md`、相关测试、现有 AI 指导文件与对应 `.agents/skills/*/SKILL.md`。
+3. 在写第一行新代码前，用 1 行回答 Q1-Q7：复用对象、可扩展点、当前真实调用点、更简方案、知识泄漏、一致性、性能/安全对比。
+4. 任务规模 ≥ M 时，同步说明直接/间接影响：文件、接口/类型、导入、测试、文档、依赖方。
+5. 不能把未运行或失败的门禁写成“已通过”。
+
+## 必要性自检（M / L 任务必须输出）
+
+- Q1：仓库里是否已有同类能力可复用？
+- Q2：能否扩展现有文件/模块，而不是新建抽象或目录？
+- Q3：当前真实调用点是什么，不要为了“以后可能”而设计？
+- Q4：有没有少一层、少一个参数、少一个文件的更简单方案？
+- Q5：这次改动会不会让使用方必须了解新的内部细节？
+- Q6：是否与当前项目命名、目录、脚本和对外暴露形式一致？
+- Q7：是否已经比较过更高效或更安全的做法？
+
+## 影响分析（M / L 任务必须输出）
+
+- 直接影响：修改 / 新建 / 删除哪些文件；哪些脚本、类型、配置或路由会变。
+- 间接影响：哪些测试、README、i18n、示例、共享类型、依赖方需要同步更新。
 
 ## 项目概述
 
-本项目使用 hai-framework 构建，基于 SvelteKit 2 + Svelte 5 (Runes) + TailwindCSS 4 + DaisyUI 5 + TypeScript 5.7+。
+本项目由 hai-framework CLI 生成。单应用工程通常在 `src/` 下开发；多包工程会同时包含 `packages/*` 与 `apps/*`。实际结构以当前项目目录为准。
 
-前后端分离工程中，SvelteKit app 主要负责 UI、路由与请求编排；业务 API 与服务端逻辑位于 `packages/<project>-serv`，通过 `@h-ai/serv` 实现。SSR、SPA 或静态输出以各 app 的 adapter 与配置为准，不要把 fullstack 后端业务逻辑写进 SvelteKit 页面、`load` 或前端组件。
+## 通用硬约束
 
-## 核心规范
+- 先用全局检索确认是否已有实现、测试和文档；优先复用，避免为“未来可能”新增抽象。
+- 统一模式：`module.init(config) -> use -> module.close()`；公共 `@h-ai/*` API 返回 `HaiResult<T>` 或 `Promise<HaiResult<T>>`，业务错误不要直接 `throw`。
+- 禁止 `any`、无说明的危险类型断言、`console.log`、硬编码密钥。
+- 用户可见文本必须走 i18n；如果项目启用了 `messages/zh-CN.json` 与 `messages/en-US.json`，修改文案时必须同步更新。
+- 代码注释中文，日志消息英文。
+- 如项目使用 SvelteKit，`+server.ts` 只能导出 HTTP handler 与 SvelteKit 允许的配置项；辅助函数放到 `src/lib/**`。
 
-- 统一模式：`module.init(config) → use → module.close()`，所有操作返回 `HaiResult<T>`
-- **TDD 驱动开发**：先写测试（Red）→ 确认失败 → 再实现（Green）→ 确认通过 → 重构（Refactor）
-- 禁止 `any`（使用 `unknown` + 缩窄），禁止 `console.log`（使用 `core.logger`）
-- 用户可见文本走 i18n，代码注释中文，日志英文
-- HaiResult 错误直接透传，不重新包装
-- 框架模块公共 API 不抛异常，统一返回 `HaiResult<T>`；不要用 `try/catch` 处理模块返回的错误
-- 质量门禁按顺序执行：`pnpm typecheck` → `pnpm lint` → `pnpm build`（涉及构建/发布时）→ `pnpm test` → `pnpm --filter <workspace> test:e2e`（涉及 UI/路由/E2E 时）
+## 工作流程
 
-## 完成条件
+1. 先搜索现有实现、引用点、测试和 README。
+2. 小步修改，优先保持目录结构、公开 API 和脚本稳定。
+3. 改动公共类型、配置、模板或共享逻辑时，同步更新所有调用方与文档。
+4. 每次改动后按影响范围运行质量门禁并记录结果。
+
+## 质量门禁
 
-- 失败的质量门禁必须先修复；不能提交或回复“已知失败”的改动。
-- 新增/修改功能要同步测试；UI、路由和关键用户流程要同步 E2E。
-- README、`.agents/skills/**/SKILL.md`、代码注释、i18n 消息、公共类型/API contract 与实现保持一致。
-- 修改共享包、公共 API、contract、client、server procedure 或 CLI 模板后，必须检索并更新所有受影响的 `packages/*`、`apps/*` 与脚手架模板。
-- 最终回复必须报告 typecheck/lint/build/test/e2e 状态、已更新文档、已更新依赖方；未执行或未通过项要说明原因和下一步。
+```bash
+pnpm typecheck
+pnpm lint
+pnpm build
+pnpm test
+pnpm test:e2e
+```
+
+## 完成条件
 
-## Skills 参考
+- typecheck / lint / build / test / test:e2e 状态明确；失败必须先修复或明确说明原因。
+- README、i18n、测试、代码注释与实现保持一致。
+- 最终回复说明执行过的门禁、已同步的文档 / 依赖方，以及未完成项。
 
-所有详细指南位于 `.agents/skills/` 目录，按需阅读：
+## Skills 路由
 
-- **入口**：`hai-build/SKILL.md` — 项目架构总览与 Skill 导航
-- **框架模块**：`hai-core/`、`hai-kit/`、`hai-reldb/`、`hai-iam/`、`hai-crypto/`、`hai-cache/`、`hai-storage/`、`hai-ai/`
-- **UI 组件**：`hai-ui/SKILL.md`
-- **TDD 开发流程**：`hai-app-tests/`（TDD 测试先行）、`hai-app-create/`（TDD 实现）、`hai-app-review/`（TDD 重构审查）
-- **仓库工程流程**：`hai-ci/`（CI/CD 与质量门禁）、`hai-pr-review/`（PR / Issue 交付审查与 AI Review）、`hai-framework-sync/`（两仓同步）
+- `hai-build/SKILL.md`：架构、构建和质量门禁。
+- `hai-app-create/SKILL.md`：应用骨架、路由、页面与 API 模板。
+- `hai-app-review/SKILL.md`：应用代码审查。
+- `hai-app-tests/SKILL.md`：Vitest / Playwright 测试策略。
+- 具体模块按需读取对应 `hai-*` Skill。

package/templates/skills/CLAUDE.md

@@ -2,12 +2,23 @@
 
 @AGENTS.md
 
-> Claude Code 项目指引。共享规范通过 `@AGENTS.md` 复用；共享参考资料位于 `.agents/skills/` 目录。
+> Claude Code 项目指引。共享规范通过 `@AGENTS.md` 复用；本文件用于 generic fallback 场景，模块和工作流参考资料位于 `.agents/skills/`。
 
-## 使用说明
+如果当前运行环境未自动展开 `@AGENTS.md`，必须先手动阅读 `AGENTS.md`，再开始修改代码或文档。
 
-- 本文件是 Claude Code 的原生项目级指引入口。
-- 项目概述、核心规范、质量门禁与完成条件统一维护在 `AGENTS.md`；Claude Code 通过 `@AGENTS.md` 复用这些共享规范，避免双份文档漂移。
-- 如果当前运行环境未自动展开 `@AGENTS.md`，必须先手动阅读 `AGENTS.md`，再开始修改代码或文档。
-- 共享的模块与工作流参考资料维护在 `.agents/skills/` 中；需要具体用法时，可按路径阅读对应 `SKILL.md`。
-- 当前模板为了保持单一 Skill 树，不额外生成 `.claude/skills/`；如需 Claude Code 的原生 project skills 自动发现，需要单独维护该目录。
+## 开始工作前
+
+- 回复第一行保持：`规模: XS|S|M|L — <一句话意图>`。
+- 任务规模 ≥ M 时，先输出 Q1-Q7 必要性自检与影响分析，再写代码。
+- 修改前先看 `README.md`、相关测试和对应 `.agents/skills/*/SKILL.md`。
+
+## 工作重点
+
+- 优先复用现有实现，不为未来假设提前抽象。
+- 若项目启用 SvelteKit，记住 `+server.ts` 不能导出自定义 helper。
+- 若项目启用 i18n，用户可见文本必须同步多语言文件。
+
+## 完成前检查
+
+- 按影响范围运行 `pnpm typecheck`、`pnpm lint`、`pnpm build`、`pnpm test`、`pnpm test:e2e`。
+- 在最终回复里说明门禁结果、文档 / 测试同步情况与未完成项。

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

@@ -0,0 +1,66 @@
+# AGENTS.md
+
+> 管理后台项目 AI 编程助手入口。优先结合 `README.md`、`.agents/skills/`、`src/routes/`、`src/lib/server/` 与 `messages/*` 工作。
+
+## 行为契约
+
+1. 每次响应第一行写：`规模: XS|S|M|L — <一句话意图>`。
+2. 任务规模 ≥ M 时，先回顾相关路由、服务、测试、i18n 文案与 `.agents/skills/*/SKILL.md`。
+3. 在写第一行新代码前，用 1 行回答 Q1-Q7 必要性自检。
+4. 任务规模 ≥ M 时，说明将影响的页面、layout、API、认证流程、测试和文档。
+
+## 必要性自检（M / L 任务必须输出）
+
+- Q1：已有页面 / service / 模块 API 是否可复用？
+- Q2：能否扩展现有 `src/lib/server/services`、`src/routes`、共享组件，而不是新建抽象？
+- Q3：当前真实调用点是哪些页面、表单、API 或 guard？
+- Q4：能否用更少的 route / load / helper / 组件解决？
+- Q5：是否把 provider、DB 细节或中间态泄漏给页面层？
+- Q6：是否与现有路由结构、i18n、权限模型和脚本一致？
+- Q7：是否比较过更安全的鉴权、校验和数据处理方案？
+
+## 影响分析（M / L 任务必须输出）
+
+- 直接影响：哪些 `+page.svelte`、`+layout.svelte`、`+page.server.ts`、`+server.ts`、service、messages、README、测试会变。
+- 间接影响：哪些角色权限、导航入口、共享组件、表单流程和依赖模块需要同步。
+
+## 项目定位
+
+本项目是 hai-framework 管理后台：SvelteKit 负责路由、页面、`hooks.server.ts` 和 API 端点；IAM、数据库、缓存等能力通过 `@h-ai/*` 模块初始化后使用。
+
+## 架构边界
+
+- 页面组件、layout、load 只负责渲染、权限态拼装和请求编排；业务逻辑放在 `src/lib/server/services` 或模块 API。
+- 认证授权使用 `@h-ai/iam` / `@h-ai/kit`；Web token 优先 httpOnly cookie。
+- 所有用户可见文本走 `$lib/paraglide/messages.js`，同步 `messages/zh-CN.json` 与 `messages/en-US.json`。
+- API 边界必须做 Zod 校验，HaiResult 错误用 kit response 转换。
+- `+server.ts` 只能导出 handler 和 SvelteKit 允许的配置项；helper 放到 `src/lib/server/**`。
+- 本样板默认不使用 `@h-ai/serv`、`@h-ai/api-contract`、`@h-ai/api-client`、`@h-ai/capacitor` 作为主架构。
+
+## 工作流程
+
+1. 先搜索现有路由、service、共享组件、messages 和测试。
+2. 变更权限、登录、会话、导航或 CRUD 页面时，优先扩展现有 service / component，而不是临时散落逻辑。
+3. 修改页面、API、认证流程后，同步测试、README 和 i18n。
+
+## 质量门禁
+
+```bash
+pnpm typecheck
+pnpm lint
+pnpm build
+pnpm test
+pnpm test:e2e
+```
+
+## 完成条件
+
+- 修改页面、API、认证流程时同步测试、README 和 i18n。
+- 修改公共模块用法或共享组件时，全局检索并同步依赖方。
+- 最终回复说明门禁状态、已更新页面 / API / 文档与未完成项。
+
+## 优先 Skills
+
+- `hai-build`、`hai-app-create`、`hai-app-review`、`hai-app-tests`
+- `hai-kit`、`hai-ui`、`hai-iam`、`hai-reldb`、`hai-cache`、`hai-crypto`
+- 其它 `hai-*` 模块按需读取

package/templates/skills/bridges/admin/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/`、`src/lib/server/`、`messages/*` 与相关测试。
+
+## 管理后台特有提醒
+
+- 页面层只做渲染与请求编排，不把业务逻辑塞进 `+page.svelte`。
+- 鉴权、guard、response 优先复用 `@h-ai/kit` / `@h-ai/iam`。
+- 所有用户可见文本都要同步 i18n。

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

@@ -0,0 +1,46 @@
+# GitHub Copilot 项目指令
+
+> 管理后台工程指引。详细模块用法按需读取 `.agents/skills/`。
+
+## 行为契约
+
+- 每次响应第一行写：`规模: XS|S|M|L — <一句话意图>`。
+- 任务规模 ≥ M 时，先输出 Q1-Q7 必要性自检与影响分析，再开始修改。
+- 修改前先阅读 `AGENTS.md`、`README.md`、相关页面 / service / 测试与 `.agents/skills/*/SKILL.md`。
+
+## 技术栈要点
+
+- SvelteKit 2 + Svelte 5 Runes。
+- `@h-ai/kit` 负责 SvelteKit handle、守卫、响应和校验。
+- `@h-ai/iam` 负责登录、会话与 RBAC。
+- UI 使用 TailwindCSS、DaisyUI 与 `@h-ai/ui`。
+
+## 技术边界
+
+- 页面 / layout / load 只做渲染、权限态和请求编排；业务逻辑放到 `src/lib/server/services` 或 `@h-ai/*` 模块。
+- `+server.ts` 只能导出 handler 与官方允许的配置项；helper 放到 `src/lib/server/**`。
+- 页面文本必须走 i18n。
+- API 输入必须 Zod 校验，权限检查使用 kit guard。
+- 公共模块 API 返回 `HaiResult<T>`，不要用 `try/catch` 包裹正常业务错误。
+- 本样板默认不以 `@h-ai/serv` / `@h-ai/api-client` / `@h-ai/api-contract` 作为主架构。
+
+## 开发流程
+
+1. 先检索现有路由、service、共享组件、messages 和测试。
+2. 修改认证、导航、CRUD、表单流程后，同步测试、README 和 i18n。
+3. 不要把未运行或失败的门禁写成“已通过”。
+
+## 质量门禁
+
+```bash
+pnpm typecheck
+pnpm lint
+pnpm build
+pnpm test
+pnpm test:e2e
+```
+
+## 完成条件
+
+- 页面、API、认证相关改动同步更新测试、README 和 i18n。
+- 最终交付说明要列出门禁状态、已更新页面 / API / 文档与未完成项。

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

@@ -0,0 +1,65 @@
+# AGENTS.md
+
+> API 服务项目 AI 编程助手入口。优先结合 `README.md`、`.agents/skills/`、`apps/*-contract/src/**`、`apps/*-service/src/**` 与测试工作。
+
+## 行为契约
+
+1. 每次响应第一行写：`规模: XS|S|M|L — <一句话意图>`。
+2. 任务规模 ≥ M 时，先回顾现有 contract、service、配置、测试与 `.agents/skills/*/SKILL.md`。
+3. 在写第一行新代码前，用 1 行回答 Q1-Q7 必要性自检。
+4. 任务规模 ≥ M 时，说明将影响的 contract、procedures、配置、README 和调用方。
+
+## 必要性自检（M / L 任务必须输出）
+
+- Q1：已有 contract / procedure / module API 是否可复用？
+- Q2：能否扩展现有 schema、config、procedure，而不是新增抽象层？
+- Q3：当前真实调用点是哪些测试、客户端或 service 入口？
+- Q4：能否用更少的 contract 节点、middleware 或配置解决？
+- Q5：是否把 provider、DB 行结构或内部错误细节泄漏给调用方？
+- Q6：是否与现有 workspace 目录结构、脚本和质量门禁一致？
+- Q7：是否比较过更安全的输入校验、安全头和密钥处理方案？
+
+## 影响分析（M / L 任务必须输出）
+
+- 直接影响：哪些 `apps/*-contract`、`apps/*-service`、config、README、测试会变。
+- 间接影响：哪些 typed client、部署脚本、环境变量说明和断言需要同步。
+
+## 项目定位
+
+本项目是 hai-framework API workspace：`apps/<project>-contract` 提供 typed contract，`apps/<project>-service` 提供 `@h-ai/serv` 实现，无 UI 页面和前端 i18n。
+
+## 架构边界
+
+- API 输入输出必须由 `apps/*-contract/src/**` 中的 Zod schema 与 contract 定义统一约束。
+- Service 通过 `@h-ai/serv` + `@h-ai/api-contract` 装配 HTTP App；不要退回到 SvelteKit API routes 架构。
+- Typed client / contract / service 三者保持同一份路径与类型定义，不要复制粘贴接口。
+- 公共模块 API 返回 `HaiResult<T>`；业务错误不要直接 `throw`。
+- 不生成用户页面；不要引入 UI 专属依赖或页面文案。
+- 配置和密钥来自 `apps/*-service/config/` 与环境变量，禁止硬编码。
+
+## 工作流程
+
+1. 先搜索现有 contract、procedures、init、config 和测试。
+2. 修改 contract、响应格式、安全策略或配置时，同步 README、typed client 调用方与测试。
+3. 每次改动后运行质量门禁，不能留下“已知失败”。
+
+## 质量门禁
+
+```bash
+pnpm typecheck
+pnpm lint
+pnpm build
+pnpm test
+pnpm test:e2e
+```
+
+## 完成条件
+
+- 修改 contract、procedure、配置或环境变量说明后，同步测试、README 和调用方。
+- 最终回复说明门禁状态、已更新 contract / service / 配置 / 文档与未完成项。
+
+## 优先 Skills
+
+- `hai-build`、`hai-app-create`、`hai-app-review`、`hai-app-tests`
+- `hai-serv`、`hai-api-contract`、`hai-api-client`
+- `hai-core`、`hai-reldb`、`hai-cache`、`hai-iam`、`hai-crypto`

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

@@ -0,0 +1,19 @@
+# CLAUDE.md
+
+@AGENTS.md
+
+> Claude Code API 服务项目指引。共享规范通过 `@AGENTS.md` 复用；具体模块用法按需读取 `.agents/skills/`。
+
+如果当前运行环境未自动展开 `@AGENTS.md`，必须先手动阅读 `AGENTS.md`，再开始修改代码或文档。
+
+## 开始工作前
+
+- 回复第一行保持：`规模: XS|S|M|L — <一句话意图>`。
+- 任务规模 ≥ M 时，先输出 Q1-Q7 必要性自检与影响分析。
+- 修改前先看 `src/routes/api/**`、`src/lib/server/**`、配置文件和测试。
+
+## API 特有提醒
+
+- `+server.ts` 只能导出 handler 与允许的配置项。
+- 输入校验、安全头、环境变量说明和错误响应要一起维护。
+- 不要把 UI 页面、营销文案或客户端状态管理带进 API 项目。

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

@@ -0,0 +1,46 @@
+# GitHub Copilot 项目指令
+
+> API 服务工程指引。详细模块用法按需读取 `.agents/skills/`。
+
+## 行为契约
+
+- 每次响应第一行写：`规模: XS|S|M|L — <一句话意图>`。
+- 任务规模 ≥ M 时，先输出 Q1-Q7 必要性自检与影响分析，再开始修改。
+- 修改前先阅读 `AGENTS.md`、`README.md`、相关 route / config / 测试与 `.agents/skills/*/SKILL.md`。
+
+## 技术栈要点
+
+- `apps/*-contract` 维护 typed API contract、Zod schema 与共享类型。
+- `apps/*-service` 基于 `@h-ai/serv` 装配 HTTP App、procedures 与模块初始化。
+- `@h-ai/core` 提供配置、日志、i18n 与 HaiResult 基础能力。
+- `@h-ai/api-client` 负责 typed client 调用与测试接入。
+
+## 技术边界
+
+- API 输入必须 Zod 校验。
+- contract / service / typed client 必须共用同一份 contract 定义，不要复制路径或类型。
+- 响应统一使用 HaiResult 约定，业务错误按 HaiResult 透传。
+- 后端主架构使用 `@h-ai/serv` + `@h-ai/api-contract` + `@h-ai/api-client`，不要退回到 SvelteKit API routes。
+- 禁止 UI 页面样板、`any`、`console.log`、硬编码密钥。
+- 配置文件位于 `apps/*-service/config/`，service 入口与 procedures 位于 `apps/*-service/src/`。
+
+## 开发流程
+
+1. 先检索现有 contract、procedures、config 和测试。
+2. 修改响应格式、安全头、错误码或环境变量说明时，同步 README、测试和调用方。
+3. 不要把未运行或失败的门禁写成“已通过”。
+
+## 质量门禁
+
+```bash
+pnpm typecheck
+pnpm lint
+pnpm build
+pnpm test
+pnpm test:e2e
+```
+
+## 完成条件
+
+- API、配置和测试同步更新。
+- 交付说明中列出门禁状态、受影响 route / 配置 / 文档与未完成项。

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

@@ -0,0 +1,84 @@
+# AGENTS.md
+
+> Fullstack 多包工程 AI 编程助手入口。优先结合 `README.md`、`.agents/skills/`、根工作区脚本、`packages/*`、`apps/*` 与 e2e 工作。
+
+## 行为契约
+
+1. 每次响应第一行写：`规模: XS|S|M|L — <一句话意图>`。
+2. 任务规模 ≥ M 时，先回顾相关 package、app、workspace 脚本、测试与 `.agents/skills/*/SKILL.md`。
+3. 在写第一行新代码前，用 1 行回答 Q1-Q7 必要性自检。
+4. 任务规模 ≥ M 时，说明将影响的 contract、serv、shared、各前端、测试、README 和发布脚本。
+
+## 必要性自检（M / L 任务必须输出）
+
+- Q1：已有 contract、procedure、shared client、跨端组件或脚本是否可复用？
+- Q2：能否扩展现有 `packages/*` / `apps/*`，而不是新建重复 package、adapter 或 wrapper？
+- Q3：当前真实调用点是哪些 package、app、页面或部署流程？
+- Q4：能否用更少的 workspace package、导出层或前端改动解决？
+- Q5：是否把服务端实现、数据库细节或原生桥接泄漏给调用方？
+- Q6：是否与现有 workspace 结构、脚本、契约与 i18n 分工一致？
+- Q7：是否比较过更高效或更安全的跨端协作方式？
+
+## 影响分析（M / L 任务必须输出）
+
+- 直接影响：哪些 `packages/<project>-contract`、`packages/<project>-serv`、`packages/<project>-shared`、`apps/<project>-*`、README、测试、打包脚本会变。
+- 间接影响：哪些 workspace 依赖、typed client、Capacitor/Tauri 配置、i18n 编译和 e2e 需要同步。
+
+## 项目概述
+
+本项目是 hai-framework fullstack 工作区：
+
+- `packages/<project>-contract`：前后端共享 API contract、Zod schema 与类型。
+- `packages/<project>-serv`：后端服务，使用 `@h-ai/serv` 实现业务 API。
+- `packages/<project>-shared`：跨端共享 UI Shell、主题、语言切换和 typed API client。
+- `apps/<project>-web`：Svelte 5 + Vite Web 前端。
+- `apps/<project>-app`：Svelte 5 + Vite + Capacitor 移动端 SPA。
+- `apps/<project>-desktop`：Svelte 5 + Vite + Tauri v2 桌面端。
+
+前端只做 UI 与请求编排；后端业务逻辑放在 `packages/<project>-serv`，不要写进前端组件。
+
+## 架构边界
+
+- Contract、serv、shared、各端页面必须同步演进。
+- 公共 API 返回 `HaiResult<T>`，错误直接透传，不重新包装。
+- 用户可见文本走 i18n：shared 放跨端文案，各 app 放本端文案。
+- 移动端 token 使用 Capacitor 安全存储；Web 使用 httpOnly cookie；桌面端按 Tauri 安全边界配置。
+- Web / App / Desktop 前端不承载后端业务逻辑；服务端逻辑统一放在 `packages/<project>-serv`。
+- 共享 UI、typed API client、主题与语言切换放在 `packages/<project>-shared`。
+- 本样板默认不使用 `@h-ai/kit`；不要把 fullstack 后端逻辑写回 SvelteKit 式 `load` / route 模式。
+
+## 工作流程
+
+1. 先搜索相关 package、app、workspace 脚本、测试和 README。
+2. 修改 contract / serv / shared 后，全局检索并同步所有 `packages/*` 和 `apps/*`。
+3. 修改 Web / App / Desktop 页面时，同步对应 README、messages 和测试。
+4. 涉及发布或原生壳时，同时检查根脚本、Capacitor/Tauri 配置与 e2e。
+
+## 质量门禁
+
+```bash
+pnpm typecheck
+pnpm lint
+pnpm build
+pnpm test
+pnpm test:e2e
+```
+
+涉及发布时还要运行：
+
+```bash
+pnpm compile
+pnpm package
+```
+
+## 完成条件
+
+- 修改 contract / serv / shared 后，全局检索并同步所有 `packages/*` 和 `apps/*`。
+- 修改 Web/App/Desktop 页面时，同步对应 README、messages 和测试。
+- 最终回复说明门禁状态、未执行项原因、已同步文档和依赖方。
+
+## 优先 Skills
+
+- `hai-build`、`hai-app-review`、`hai-app-tests`
+- `hai-core`、`hai-ui`、`hai-serv`、`hai-api-contract`、`hai-api-client`、`hai-capacitor`
+- 其它 `hai-*` 模块按需读取

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

@@ -0,0 +1,19 @@
+# CLAUDE.md
+
+@AGENTS.md
+
+> Claude Code fullstack 项目指引。共享规范通过 `@AGENTS.md` 复用；contract、serv、shared、Web/App/Desktop 的详细做法按需读取 `.agents/skills/`。
+
+如果当前运行环境未自动展开 `@AGENTS.md`，必须先手动阅读 `AGENTS.md`，再开始修改代码或文档。
+
+## 开始工作前
+
+- 回复第一行保持：`规模: XS|S|M|L — <一句话意图>`。
+- 任务规模 ≥ M 时，先输出 Q1-Q7 必要性自检与影响分析。
+- 修改前先看相关 `packages/*`、`apps/*`、workspace 脚本、messages 和测试。
+
+## Fullstack 特有提醒
+
+- `packages/<project>-serv` 才是后端业务逻辑主场，不要把逻辑写进前端组件。
+- contract、shared client、各端页面改动必须成套同步。
+- App/Desktop 还要关注 Capacitor / Tauri 的原生壳配置与打包脚本。

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

@@ -0,0 +1,54 @@
+# GitHub Copilot 项目指令
+
+> Fullstack 工程指引。详细模块用法按需读取 `.agents/skills/`。
+
+## 行为契约
+
+- 每次响应第一行写：`规模: XS|S|M|L — <一句话意图>`。
+- 任务规模 ≥ M 时，先输出 Q1-Q7 必要性自检与影响分析，再开始修改。
+- 修改前先阅读 `AGENTS.md`、`README.md`、相关 `packages/*` / `apps/*` / 测试与 `.agents/skills/*/SKILL.md`。
+
+## 技术栈要点
+
+- Contract：`packages/<project>-contract` 定义 API contract、schema 与共享类型。
+- Fullstack 服务端：`packages/<project>-serv` 使用 `@h-ai/serv` 实现业务 API。
+- Shared：`packages/<project>-shared` 放跨端 Shell、i18n、主题和 typed API client。
+- Web：Svelte 5 + Vite 前端。
+- App：Svelte 5 + Vite + Capacitor 原生壳。
+- Desktop：Svelte 5 + Vite + Tauri v2 纯客户端壳。
+
+不要把后端业务逻辑写进 Svelte 前端组件。
+
+## 技术边界
+
+- 公共 API 返回 `HaiResult<T>`；业务错误不要直接 `throw`。
+- Contract、serv procedure、shared client 与各端调用方必须一起更新。
+- 用户可见文本走 i18n，shared 与各端 messages 分工清晰。
+- Web/App/Desktop 前端只做 UI 与请求编排；后端逻辑放在 Fullstack 服务端。
+- 禁止 `any`、`console.log`、硬编码密钥。
+- 代码注释中文，日志消息英文。
+
+## 开发流程
+
+1. 先检索相关 package、app、workspace 脚本、messages 和测试。
+2. 修改公共契约后，全局检索并更新所有受影响的 `packages/*`、`apps/*` 和 CLI 模板。
+3. 修改 App / Desktop 时，同时检查 Capacitor / Tauri v2 原生壳配置与打包脚本。
+4. 不要把未运行或失败的门禁写成“已通过”。
+
+## 质量门禁
+
+```bash
+pnpm typecheck
+pnpm lint
+pnpm build
+pnpm test
+pnpm test:e2e
+pnpm compile
+pnpm package
+```
+
+## 完成条件
+
+- README、`.agents/skills/**/SKILL.md`、i18n、测试与实现同步。
+- 修改公共契约后，全局检索并更新所有受影响的 `packages/*`、`apps/*` 和 CLI 模板。
+- 交付说明中列出门禁状态、受影响 package/app 与未完成项。