@h-ai/cli 0.1.0-alpha.54 → 0.1.0-alpha.55

package/README.md

@@ -15,6 +15,10 @@
 - **API 服务脚手架** — API Service 模板使用 `@h-ai/api-contract` + `@h-ai/serv` 组合公共 contract / procedures，并通过 `@h-ai/api-client` typed client 消费
 - **自动依赖解析** — 选择功能时自动补全依赖（如 IAM 自动引入 Crypto）
 
+## AI 使用指南
+
+CLI 从 `templates/skills/` 将所选 skill 的完整目录复制到生成项目 `.agents/skills/`。`SKILL.md` 提供能力边界和任务导航，`reference.md`/`guide.md` 保留按需范本；同步时不能只复制入口。AGENTS.md 保存应用约束，Claude/Copilot 桥接文件引用它；修改模板需同步相关仓库 skills。模板生成测试会核对参考文件的完整交付。
+
 ## 快速开始
 
 要求 Node.js ≥ 22.12.0；生成的根项目和工作区包均声明相同最低版本。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/cli",
   "type": "module",
-  "version": "0.1.0-alpha.54",
+  "version": "0.1.0-alpha.55",
   "description": "Hai Framework CLI for project scaffolding and code generation.",
   "license": "Apache-2.0",
   "keywords": [
@@ -37,7 +37,7 @@
     "ora": "^9.1.0",
     "prompts": "^2.4.2",
     "yaml": "^2.7.0",
-    "@h-ai/core": "0.1.0-alpha.54"
+    "@h-ai/core": "0.1.0-alpha.55"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",
@@ -47,11 +47,11 @@
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.7",
-    "@h-ai/deploy": "0.1.0-alpha.54",
-    "@h-ai/reach": "0.1.0-alpha.54",
-    "@h-ai/reldb": "0.1.0-alpha.54",
-    "@h-ai/cache": "0.1.0-alpha.54",
-    "@h-ai/storage": "0.1.0-alpha.54"
+    "@h-ai/cache": "0.1.0-alpha.55",
+    "@h-ai/deploy": "0.1.0-alpha.55",
+    "@h-ai/reldb": "0.1.0-alpha.55",
+    "@h-ai/reach": "0.1.0-alpha.55",
+    "@h-ai/storage": "0.1.0-alpha.55"
   },
   "scripts": {
     "build": "tsup",

package/templates/base/package.json.hbs

@@ -1,7 +1,7 @@
 {
   "engines": { "node": ">=22.12.0" },
   "name": "{{projectName}}",
-  "version": "0.1.0-alpha.54",
+  "version": "0.1.0-alpha.55",
   "private": true,
   "packageManager": "pnpm@9.15.0",
   "description": "{{#if_eq appType 'admin'}}Enterprise management system built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'website'}}Enterprise website built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'h5'}}Mobile H5 app built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'api'}}REST API service built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'mobile-app'}}Mobile app built with hai Agent Framework{{/if_eq}}",

package/templates/skills/AGENTS.md

@@ -4,23 +4,7 @@
 
 ## 行为契约
 
-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、package.json、相关实现/测试和所需 .agents/skills；不要加载整个 skill 树。新增抽象前确认复用路径与真实需求；保留用户改动。跨文件任务简述影响和验证计划，无须固定规模标签或重复问卷。
 
 - 直接影响：修改 / 新建 / 删除哪些文件；哪些脚本、类型、配置或路由会变。
 - 间接影响：哪些测试、README、i18n、示例、共享类型、依赖方需要同步更新。
@@ -32,7 +16,7 @@
 ## 通用硬约束
 
 - 先用全局检索确认是否已有实现、测试和文档；优先复用，避免为“未来可能”新增抽象。
-- 统一模式：`module.init(config) -> use -> module.close()`；公共 `@h-ai/*` API 返回 `HaiResult<T>` 或 `Promise<HaiResult<T>>`，业务错误不要直接 `throw`。
+- 生命周期模块按 init → use → close；core/serv/kit/纯函数和流式 API 按实际签名使用。返回 HaiResult 的业务操作先检查 success，不以 try/catch 代替判断。
 - 禁止 `any`、无说明的危险类型断言、`console.log`、硬编码密钥。
 - 用户可见文本必须走 i18n；如果项目启用了 `messages/zh-CN.json` 与 `messages/en-US.json`，修改文案时必须同步更新。
 - 代码注释中文，日志消息英文。
@@ -47,6 +31,8 @@
 
 ## 质量门禁
 
+先核对 package.json，按影响范围执行已有脚本；文档检查引用，UI/路由变更再运行 E2E。未运行项说明原因。
+
 ```bash
 pnpm typecheck
 pnpm lint
@@ -63,8 +49,8 @@ pnpm test:e2e
 
 ## Skills 路由
 
-- `hai-build/SKILL.md`：架构、构建和质量门禁。
-- `hai-app-create/SKILL.md`：应用骨架、路由、页面与 API 模板。
-- `hai-app-review/SKILL.md`：应用代码审查。
-- `hai-app-tests/SKILL.md`：Vitest / Playwright 测试策略。
+- `.agents/skills/hai-build/SKILL.md`：架构、构建和质量门禁。
+- `.agents/skills/hai-app-create/SKILL.md`：应用骨架、路由、页面与 API 模板。
+- `.agents/skills/hai-app-review/SKILL.md`：应用代码审查。
+- `.agents/skills/hai-app-tests/SKILL.md`：Vitest / Playwright 测试策略。
 - 具体模块按需读取对应 `hai-*` Skill。

package/templates/skills/CLAUDE.md

@@ -4,21 +4,8 @@
 
 > Claude Code 项目指引。共享规范通过 `@AGENTS.md` 复用；本文件用于 generic fallback 场景，模块和工作流参考资料位于 `.agents/skills/`。
 
-如果当前运行环境未自动展开 `@AGENTS.md`，必须先手动阅读 `AGENTS.md`，再开始修改代码或文档。
+共享规则见项目根 [AGENTS.md](AGENTS.md)；若未自动加载，先读取该文件。模块/流程按需读取项目根 .agents/skills/<name>/SKILL.md 及其相邻参考文件。
 
-## 开始工作前
+## 质量门禁
 
-- 回复第一行保持：`规模: 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`。
-- 在最终回复里说明门禁结果、文档 / 测试同步情况与未完成项。
+按 AGENTS.md 和实际 package.json 选择 typecheck、lint、build、test、test:e2e；最终说明已执行结果、未运行原因及同步文档/依赖方。

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

@@ -4,22 +4,7 @@
 
 ## 行为契约
 
-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 任务必须输出）
+先读 README、package.json、相关实现/测试和所需 .agents/skills；不要加载整个 skill 树。新增抽象前确认复用路径与真实需求；保留用户改动。跨文件任务简述影响和验证计划，无须固定规模标签或重复问卷。
 
 - 直接影响：哪些 `+page.svelte`、`+layout.svelte`、`+page.server.ts`、`+server.ts`、service、messages、README、测试会变。
 - 间接影响：哪些角色权限、导航入口、共享组件、表单流程和依赖模块需要同步。
@@ -45,6 +30,8 @@
 
 ## 质量门禁
 
+先核对 package.json，按影响范围执行已有脚本；文档检查引用，UI/路由变更再运行 E2E。未运行项说明原因。
+
 ```bash
 pnpm typecheck
 pnpm lint

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

@@ -4,16 +4,8 @@
 
 > Claude Code 管理后台项目指引。共享规范通过 `@AGENTS.md` 复用；具体模块用法按需读取 `.agents/skills/`。
 
-如果当前运行环境未自动展开 `@AGENTS.md`，必须先手动阅读 `AGENTS.md`，再开始修改代码或文档。
+共享规则见项目根 [AGENTS.md](AGENTS.md)；若未自动加载，先读取该文件。模块/流程按需读取项目根 .agents/skills/<name>/SKILL.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。
+按 AGENTS.md 和实际 package.json 选择 typecheck、lint、build、test、test:e2e；最终说明已执行结果、未运行原因及同步文档/依赖方。

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

@@ -2,45 +2,8 @@
 
 > 管理后台工程指引。详细模块用法按需读取 `.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. 不要把未运行或失败的门禁写成“已通过”。
+共享规则见项目根 [AGENTS.md](../AGENTS.md)；若未自动加载，先读取该文件。模块/流程按需读取项目根 .agents/skills/<name>/SKILL.md 及其相邻参考文件。
 
 ## 质量门禁
 
-```bash
-pnpm typecheck
-pnpm lint
-pnpm build
-pnpm test
-pnpm test:e2e
-```
-
-## 完成条件
-
-- 页面、API、认证相关改动同步更新测试、README 和 i18n。
-- 最终交付说明要列出门禁状态、已更新页面 / API / 文档与未完成项。
+按 AGENTS.md 和实际 package.json 选择 typecheck、lint、build、test、test:e2e；最终说明已执行结果、未运行原因及同步文档/依赖方。

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

@@ -4,22 +4,7 @@
 
 ## 行为契约
 
-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 任务必须输出）
+先读 README、package.json、相关实现/测试和所需 .agents/skills；不要加载整个 skill 树。新增抽象前确认复用路径与真实需求；保留用户改动。跨文件任务简述影响和验证计划，无须固定规模标签或重复问卷。
 
 - 直接影响：哪些 `apps/*-contract`、`apps/*-service`、config、README、测试会变。
 - 间接影响：哪些 typed client、部署脚本、环境变量说明和断言需要同步。
@@ -33,7 +18,7 @@
 - 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`。
+- 返回 `HaiResult<T>` 的业务 API 先判断 `success`；纯函数、工厂与流按实际签名处理。
 - 不生成用户页面；不要引入 UI 专属依赖或页面文案。
 - 配置和密钥来自 `apps/*-service/config/` 与环境变量，禁止硬编码。
 
@@ -41,10 +26,12 @@
 
 1. 先搜索现有 contract、procedures、init、config 和测试。
 2. 修改 contract、响应格式、安全策略或配置时，同步 README、typed client 调用方与测试。
-3. 每次改动后运行质量门禁，不能留下“已知失败”。
+3. 按改动范围验证，修复本次引入的失败；已有问题与未运行项明确报告。
 
 ## 质量门禁
 
+先核对 package.json，按影响范围执行已有脚本；文档检查引用，UI/路由变更再运行 E2E。未运行项说明原因。
+
 ```bash
 pnpm typecheck
 pnpm lint

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

@@ -4,16 +4,8 @@
 
 > Claude Code API 服务项目指引。共享规范通过 `@AGENTS.md` 复用；具体模块用法按需读取 `.agents/skills/`。
 
-如果当前运行环境未自动展开 `@AGENTS.md`，必须先手动阅读 `AGENTS.md`，再开始修改代码或文档。
+共享规则见项目根 [AGENTS.md](AGENTS.md)；若未自动加载，先读取该文件。模块/流程按需读取项目根 .agents/skills/<name>/SKILL.md 及其相邻参考文件。
 
-## 开始工作前
+## 质量门禁
 
-- 回复第一行保持：`规模: XS|S|M|L — <一句话意图>`。
-- 任务规模 ≥ M 时，先输出 Q1-Q7 必要性自检与影响分析。
-- 修改前先看 `src/routes/api/**`、`src/lib/server/**`、配置文件和测试。
-
-## API 特有提醒
-
-- `+server.ts` 只能导出 handler 与允许的配置项。
-- 输入校验、安全头、环境变量说明和错误响应要一起维护。
-- 不要把 UI 页面、营销文案或客户端状态管理带进 API 项目。
+按 AGENTS.md 和实际 package.json 选择 typecheck、lint、build、test、test:e2e；最终说明已执行结果、未运行原因及同步文档/依赖方。

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

@@ -2,45 +2,10 @@
 
 > API 服务工程指引。详细模块用法按需读取 `.agents/skills/`。
 
-## 行为契约
+使用 `@h-ai/serv` + 共享 contract 装配服务；不要退回到 SvelteKit API routes。
 
-- 每次响应第一行写：`规模: 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. 不要把未运行或失败的门禁写成“已通过”。
+共享规则见项目根 [AGENTS.md](../AGENTS.md)；若未自动加载，先读取该文件。模块/流程按需读取项目根 .agents/skills/<name>/SKILL.md 及其相邻参考文件。
 
 ## 质量门禁
 
-```bash
-pnpm typecheck
-pnpm lint
-pnpm build
-pnpm test
-pnpm test:e2e
-```
-
-## 完成条件
-
-- API、配置和测试同步更新。
-- 交付说明中列出门禁状态、受影响 route / 配置 / 文档与未完成项。
+按 AGENTS.md 和实际 package.json 选择 typecheck、lint、build、test、test:e2e；最终说明已执行结果、未运行原因及同步文档/依赖方。

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

@@ -1,61 +1,34 @@
 # AGENTS.md
 
-> Fullstack 多包工程 AI 编程助手入口。优先结合 `README.md`、`.agents/skills/`、根工作区脚本、`packages/*`、`apps/*` 与 e2e 工作。
+Fullstack 多包工程入口。先读 README、根 workspace 脚本与相关 package/app；模块用法按需读取 `.agents/skills/*/SKILL.md` 及其引用。
 
 ## 行为契约
 
-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/{{projectName}}-contract`、`packages/{{projectName}}-serv`、`packages/{{projectName}}-shared`、`apps/{{projectName}}-*`、README、测试、打包脚本会变。
-- 间接影响：哪些 workspace 依赖、typed client、Capacitor/Tauri 配置、i18n 编译和 e2e 需要同步。
-
-## 项目概述
-
-本项目是 hai-framework fullstack 工作区：
-
-- `packages/{{projectName}}-contract`：前后端共享 API contract、Zod schema 与类型。
-- `packages/{{projectName}}-serv`：后端服务，使用 `@h-ai/serv` 实现业务 API。
-- `packages/{{projectName}}-shared`：跨端共享 UI Shell、主题、语言切换和 typed API client。
-- `apps/{{projectName}}-web`：Svelte 5 + Vite Web 前端。
-- `apps/{{projectName}}-app`：Svelte 5 + Vite + Capacitor 移动端 SPA。
-- `apps/{{projectName}}-desktop`：Svelte 5 + Vite + Tauri v2 桌面端。
-
-前端只做 UI 与请求编排；后端业务逻辑放在 `packages/{{projectName}}-serv`，不要写进前端组件。
+- 修改前检索实现、调用方、测试和文档，优先复用现有 contract、procedure、共享组件与脚本。
+- 跨包变更先明确受影响的 contract、serv、shared、前端及交付流程，再同步调用方；不必输出固定问卷。
+- 禁止 `any`、`console.log`、硬编码密钥。代码注释中文，日志英文；用户文本走 i18n。
 
 ## 架构边界
 
-- Contract、serv、shared、各端页面必须同步演进。
-- 公共 API 返回 `HaiResult<T>`，错误直接透传，不重新包装。
-- 用户可见文本走 i18n：shared 放跨端文案，各 app 放本端文案。
-- 移动端 token 使用 Capacitor 安全存储；Web 使用 httpOnly cookie；桌面端按 Tauri 安全边界配置。
-- Web / App / Desktop 前端不承载后端业务逻辑；服务端逻辑统一放在 `packages/{{projectName}}-serv`。
-- 共享 UI、typed API client、主题与语言切换放在 `packages/{{projectName}}-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。
+| 路径 | 职责 |
+| --- | --- |
+| `packages/{{projectName}}-contract` | API contract、Zod schema 与共享类型 |
+| `packages/{{projectName}}-serv` | 使用 `@h-ai/serv` 实现后端业务 API |
+| `packages/{{projectName}}-shared` | 共享 UI Shell、主题、i18n 和 typed API client |
+| `apps/{{projectName}}-web` | Svelte 5 + Vite Web 前端，按选择生成 |
+| `apps/{{projectName}}-app` | Svelte 5 + Vite + Capacitor 移动端 SPA，按选择生成 |
+| `apps/{{projectName}}-desktop` | Svelte 5 + Vite + Tauri v2 桌面端，按选择生成 |
+| `apps/{{projectName}}-miniapp` | 选择 miniapp 时生成的预留说明与文案，当前不是可运行应用 |
+
+- 前端负责 UI 与请求编排；后端业务放 serv，共享能力放 shared。本样板默认不用 `@h-ai/kit`，不要混入 SvelteKit load / route 结构。
+- 返回 `HaiResult<T>` 的业务 API 先判断 `success`，业务错误直接透传；纯函数、工厂和流按实际签名使用，不能假定都返回 HaiResult。
+- 用户文本按 shared 跨端文案与各 app 专属文案分工，同步现有 locale。
+- 认证接入前检查现有实现；样板不意味着已配好 Cookie 或安全 token 存储。新增认证时 Web 明确 Cookie/内存方案，App 原生端配置安全 TokenStorage，Desktop 按 Tauri 安全边界实现。
 
 ## 质量门禁
 
+按影响范围执行，跨包契约从根工作区验证：
+
 ```bash
 pnpm typecheck
 pnpm lint
@@ -64,21 +37,13 @@ pnpm test
 pnpm test:e2e
 ```
 
-涉及发布时还要运行：
-
-```bash
-pnpm compile
-pnpm package
-```
+发布或原生壳改动另检查 Capacitor/Tauri 配置、根脚本，并按目标平台执行 `pnpm compile`、`pnpm package`。浏览器测试不能代替原生包验证。
 
 ## 完成条件
 
-- 修改 contract / serv / shared 后，全局检索并同步所有 `packages/*` 和 `apps/*`。
-- 修改 Web/App/Desktop 页面时，同步对应 README、messages 和测试。
-- 最终回复说明门禁状态、未执行项原因、已同步文档和依赖方。
+- 同步受影响的 contract、serv procedure、shared client、各端调用方、README、messages、skills 和测试。
+- 报告实际门禁结果、受影响 package/app、未执行项及原因；不得将跳过或失败写成通过。
 
 ## 优先 Skills
 
-- `hai-build`、`hai-app-review`、`hai-app-tests`
-- `hai-core`、`hai-ui`、`hai-serv`、`hai-api-contract`、`hai-api-client`、`hai-capacitor`
-- 其它 `hai-*` 模块按需读取
+构建与验收：`hai-build`、`hai-app-review`、`hai-app-tests`。模块使用：`hai-core`、`hai-ui`、`hai-serv`、`hai-api-contract`、`hai-api-client`、`hai-capacitor`；其余按需选择。

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

@@ -2,18 +2,4 @@
 
 @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/{{projectName}}-serv` 才是后端业务逻辑主场，不要把逻辑写进前端组件。
-- contract、shared client、各端页面改动必须成套同步。
-- App/Desktop 还要关注 Capacitor / Tauri 的原生壳配置与打包脚本。
+共享规范见 [AGENTS.md](AGENTS.md)；若未自动展开，先手动阅读。fullstack 后端业务在 `packages/{{projectName}}-serv`；contract、shared client 与前端调用方同步修改。模块用法按需读取 `.agents/skills/`。

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

@@ -1,54 +1,14 @@
 # GitHub Copilot 项目指令
 
-> Fullstack 工程指引。详细模块用法按需读取 `.agents/skills/`。
+共享工作规范见 [AGENTS.md](../AGENTS.md)，模块用法按需读取 `.agents/skills/`。
 
-## 行为契约
-
-- 每次响应第一行写：`规模: XS|S|M|L — <一句话意图>`。
-- 任务规模 ≥ M 时，先输出 Q1-Q7 必要性自检与影响分析，再开始修改。
-- 修改前先阅读 `AGENTS.md`、`README.md`、相关 `packages/*` / `apps/*` / 测试与 `.agents/skills/*/SKILL.md`。
-
-## 技术栈要点
-
-- Contract：`packages/{{projectName}}-contract` 定义 API contract、schema 与共享类型。
-- Fullstack 服务端：`packages/{{projectName}}-serv` 使用 `@h-ai/serv` 实现业务 API。
-- Shared：`packages/{{projectName}}-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. 修改公共契约后，全局检索并更新 serv procedure、shared client、所有受影响的 `packages/*`、`apps/*` 和 e2e。
-3. 修改 App / Desktop 时，同时检查 Capacitor / Tauri v2 原生壳配置与打包脚本。
-4. 不要把未运行或失败的门禁写成“已通过”。
+- `packages/{{projectName}}-contract` 定义 API；Fullstack 服务端 `packages/{{projectName}}-serv` 实现业务；`packages/{{projectName}}-shared` 共享 UI、i18n 和 typed client。
+- 前端按选择生成；App 使用 Capacitor，Desktop 使用 Tauri v2。miniapp 当前仅预留说明，不是可运行应用。
 
 ## 质量门禁
 
-```bash
-pnpm typecheck
-pnpm lint
-pnpm build
-pnpm test
-pnpm test:e2e
-pnpm compile
-pnpm package
-```
+按根 AGENTS 执行 typecheck、lint、build、test 和 test:e2e；原生或发布变更另执行对应 compile/package。
 
 ## 完成条件
 
-- README、`.agents/skills/**/SKILL.md`、i18n、测试与实现同步。
-- 修改公共契约后，全局检索并更新所有受影响的 `packages/*`、`apps/*` 和 e2e。
-- 交付说明中列出门禁状态、受影响 package/app 与未完成项。
+同步受影响的 contract、serv、shared、各端调用方及文档与测试，报告门禁结果和未执行原因。

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

@@ -4,22 +4,7 @@
 
 ## 行为契约
 
-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 任务必须输出）
+先读 README、package.json、相关实现/测试和所需 .agents/skills；不要加载整个 skill 树。新增抽象前确认复用路径与真实需求；保留用户改动。跨文件任务简述影响和验证计划，无须固定规模标签或重复问卷。
 
 - 直接影响：哪些页面、layout、导航、API、messages、README、测试会变。
 - 间接影响：哪些移动端流程、权限入口、共享组件和接口断言需要同步。
@@ -41,10 +26,12 @@
 
 1. 先搜索现有移动端页面、导航、messages、API 和测试。
 2. 修改导航、触屏交互、API 或认证流程时，同步 README、i18n 和测试。
-3. 每次改动后运行质量门禁，不能留下“已知失败”。
+3. 按改动范围验证，修复本次引入的失败；已有问题与未运行项明确报告。
 
 ## 质量门禁
 
+先核对 package.json，按影响范围执行已有脚本；文档检查引用，UI/路由变更再运行 E2E。未运行项说明原因。
+
 ```bash
 pnpm typecheck
 pnpm lint

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

@@ -4,16 +4,8 @@
 
 > Claude Code H5 项目指引。共享规范通过 `@AGENTS.md` 复用；具体模块用法按需读取 `.agents/skills/`。
 
-如果当前运行环境未自动展开 `@AGENTS.md`，必须先手动阅读 `AGENTS.md`，再开始修改代码或文档。
+共享规则见项目根 [AGENTS.md](AGENTS.md)；若未自动加载，先读取该文件。模块/流程按需读取项目根 .agents/skills/<name>/SKILL.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 样板的默认主架构。
+按 AGENTS.md 和实际 package.json 选择 typecheck、lint、build、test、test:e2e；最终说明已执行结果、未运行原因及同步文档/依赖方。