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

package/README.md

@@ -1,312 +1,121 @@
 # @h-ai/cli
 
-[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
+[简体中文](README.md) | [English](README.en.md) | [日本語](README.ja.md)
 
-[框架首页](../../README.md) · 相关模块：[@h-ai/core](../core/README.md)
+[框架首页](../../README.md)
 
-从创建、手工/AI first 开发到编译、打包、部署与升级，见[完整使用指南](../../docs/usage/README.md)。本页提供 CLI 命令与模板的详细参考。
+## 简介
 
-> hai Agent Framework CLI — 交互式项目脚手架与代码生成工具。
+用 `hai` 创建应用、添加模块、生成基础代码，再构建和交付应用。支持 SvelteKit、独立 API 和前后端分离工程。第一次使用可按[完整使用指南](../../docs/usage/README.md)从创建走到部署。
 
-`pnpm build` 默认编译源码；`pnpm build --target docker` 构建并导出 API/可选 Web 镜像，优先 Podman、其次 Docker。启用 Desktop 时用 `pnpm build --target desktop --platform windows|linux|macos` 在对应系统调用 Tauri。构建不选择部署环境。`hai deploy` 消费已有产物并上传一个 Compose tar；`--bundle-only --output release.tar` 仅生成包供手工搬运。fullstack 的 `pnpm run deploy --env test` 一并发布 API/Web。见 [部署用法与离线准备](../deploy/README.md)。测试临时产物由 finally/teardown 清理，失败也执行。
+## 核心功能清单
 
-## 支持的能力
+- 创建管理后台、企业官网、H5、API、移动应用或多端 fullstack 工程。
+- 为已有项目添加模块、补齐配置和 AI 开发指引。
+- 生成页面、组件、接口、模型和迁移骨架。
+- 按镜像构建，完整离线交付，或只更新选中的服务。
 
-`hai deploy` 的缺失模块/配置、凭证加载、扫描、初始化、部署和关闭失败均以非零退出码结束；脚本必须检查退出码。只有完整部署成功才可作为后续步骤的成功条件。
-
-- **项目创建** — 交互式引导创建 SvelteKit 应用、Svelte 5 移动/桌面前端与 hai 后端项目
-- **模块添加** — 向现有项目增量启用模块，自动解析依赖
-- **配置初始化** — 校验项目配置完整性，补全缺失的配置文件
-- **代码生成** — 快速生成页面、组件、API 端点、数据模型、数据库迁移
-- **模板选择** — 最小 / 标准 / 完整 / 自定义四种项目模板
-- **功能组合** — 按需启用 IAM、DB、AI、Storage、Crypto 等模块
-- **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。模板生成测试会核对参考文件的完整交付。
-
-业务以用户当前明确要求及其指定的需求/设计文档为准。模板 AGENTS、README、skills、生成代码及测试中的角色/权限、流程、限额和架构是可调整的初始方案。审查将差异列为模板适配项，不因偏离模板判定需求错误；实施按授权同步修改冲突代码、测试和过期规则。框架 API 仍以安装版本公开契约为准，服务端授权、资源隔离、输入校验和凭据保护仍需落实。已有项目需显式合并这些规则，`hai init` 不覆盖现有文件。
-
-所有应用类型均交付 `hai-spec-review`：生成前严格检查需求/设计文档的完备性、歧义、技术及框架使用错误、命名一致性，给出带位置和修正建议的问题清单；问题解决且证据充分后才判定可以进入 AI 生成。`hai init` / `hai add` 同时为已有项目补齐该工作流 skill，保留自定义文件。
-
-审查后的文档实施使用独立的 `hai-spec-implement`，同样交付到所有应用并由 `hai init` / `hai add` 补齐。AI 按可独立验收的功能和实际依赖决定是否拆分，默认写入 `docs/task-list.md` 与 `docs/tasks/<编号>-<slug>.md`；每项在独立 Git 分支走 TDD、门禁、本地合并，记录真实合并提交后更新清单。返修复用原任务编号、文件和分支，追加轮次并关联此前证据。流程复用 Markdown、Git 和已有开发/测试 skills，无新增运行依赖或工作流引擎。可以请求“只根据 docs/需求.md 拆分任务”“根据该文档生成代码”“执行 T003”或“T002 返修后合并”；仅规划时不实施，指定任务先核验依赖，远端操作依实际授权。
-
-需求/设计文档提交后，可以请求“我修改了 docs/需求.md、docs/设计.md，请帮我更新实现”。Skill 在原清单中区分已验收文档 SHA、固定目标文档 SHA 与已验收实现 SHA，比较完整文档集合的净差异（含增删、重命名及关联影响），更新原任务或新建任务，逐项在对应分支测试、合并。全部差异处理且整体验收通过后，才提交新的已验收基线；部分完成或中断保留旧基线。旧项目缺少可信基线时先追溯/核验，不猜测版本。详见 [文档差异与基线流程](templates/skills/hai-spec-implement/changes.md)。`hai init` / `hai add` 会补齐新增参考文件，已存在的入口、执行流程和任务范本仍须对照模板合并。
-
-日常新增、修改、修复功能由 `AGENTS.md` 引导读取 `hai-app-create/SKILL.md` 与 `development.md`：先把需求映射到框架现成功能、配置和扩展点，再依据当前安装版本的 exports/类型实现。适用能力优先复用；能力不足时说明具体缺口，不为模块覆盖率安装无关依赖。Codex 使用 `.agents/skills/`，仍需遵循项目根 `AGENTS.md` 的常驻规则。
-
-工具入口共享同一份规则与技能：Codex/Cursor 使用 AGENTS 与 `.agents/skills/`；Copilot 的 `.github/copilot-instructions.md` 只引用共享 `AGENTS.md`，不另保存各应用类型规则；OpenCode 的 opencode.json 通过 `instructions: ["AGENTS.md"]` 直接引用共享规则。Claude Code 的根 CLAUDE.md 仅包含 `@AGENTS.md`，通过共享规则的任务导航按需读取 `.agents/skills/` 正文和参考文件。CLI 不创建 `.claude/`，无需重复技能或符号链接。此模式不提供 Claude 原生技能自动发现或 `/skill` 命令；项目已有的 Claude 设置与技能保留。依据：[Claude 项目指引](https://code.claude.com/docs/en/memory)、[Claude 原生 skills](https://code.claude.com/docs/en/skills)、[Copilot](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills)、[OpenCode](https://docs.opencode.ai/docs/skills/)、[Cursor](https://cursor.com/docs/skills)。
-
-Codex 原生发现 `.agents/skills/` 并按任务自动选择，也可显式输入 `$hai-app-create`、`$hai-app-review` 等名称调用；入口和参考文件保持按需读取。无需额外 `.codex/skills` 或 Copilot 设置。依据：[Codex skills](https://learn.chatgpt.com/docs/build-skills)、[AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md)。
-
-Claude Code v2.1.277 起也可直接读取根 `AGENTS.md`（没有更高优先级项目 CLAUDE 文件且相关内置插件启用时）。保留这一行导入可兼容旧版及未开启该能力的会话，官方说明导入不会重复加载规则；仍无须 `.claude/` 目录。参见 [AGENTS.md 支持](https://code.claude.com/docs/en/memory#agentsmd)。
-
-生成项目共享 `eslint-rules.js`，lint 拦截显式 `any`、console、无理由抑制、双重 unknown 断言、框架内部源码导入及明确的 localStorage 敏感键写入；合理的第三方 workaround 需局部说明。静态规则不能证明权限隔离、输入安全、事务或日志脱敏，相关行为仍需测试与审查。
-
-已有项目先更新 CLI，再运行 `hai init` 补齐缺失的流程 skill、参考资源和入口；该操作保留现有文件，即使 `--force` 也不覆盖 AI 规则。旧入口、已存在的 skills、ESLint 配置与脚本需要对照新生成项目合并，缺失的 .npmrc/.gitignore 也需补齐；只补文件不会自动升级旧规则。模板变更未发布前可通过本仓库构建的 CLI 生成对照项目，不要把未发布能力当作已安装包能力。
-
-AI 文件写入前会解析已有文件和目录链接；共享技能与项目桥接文件均限制在当前项目内。链接指向项目外时停止写入。已有 `.claude/` 目录及其链接不参与生成，`hai init` / `hai add` 不修改或删除其中的内容。
-
-交付验证同时检查发布归档和生成项目。`.npmrc` / `.gitignore` 在模板源中使用 `.hbs` 后缀，避免打包时被排除；生成时仍恢复正常文件名，保留依赖布局与敏感产物忽略规则。归档回归检查全部模板都进入 `.tgz`，不能仅验证源码目录中的 create。
-
-## 快速开始
-
-要求 Node.js 22.22.2+ / 24.15.0+ / 26+；生成的根项目和工作区包均声明相同最低版本。
+## 使用入门
 
 ### 安装 CLI
 
-先全局安装 `@h-ai/cli`，它提供 `hai` 命令；以下快速开始示例均以完成安装为前提。
+需要符合项目 `engines` 的 Node.js（`^22.22.2 || ^24.15.0 || >=26.0.0`）与 pnpm 12.11.2。PowerShell 使用 `pnpm.cmd`。
 
-```bash
+```sh
 pnpm add -g @h-ai/cli
 hai --version
+hai --help
 ```
 
-PowerShell 中使用 `pnpm.cmd add -g @h-ai/cli`。已安装 CLI 时，执行相同安装命令可更新到当前发布版本；使用 `hai --help` 核对可用命令。仓库内未发布的模板按下方“开发阶段本地使用”构建并运行。
+生成的框架依赖固定到 CLI 对应版本；安装失败会显示命令、退出码与输出，保留已生成文件供重试。未发布的源码功能请按下方本地开发方式验证。
 
 ### 创建项目
 
-生成项目的 `@h-ai/*` 依赖固定为 CLI 对应版本；pnpm 通过 `catalog:` 引用该精确版本。升级时统一更新框架包并验证 lockfile 中实际解析的版本。
-
-在应用仓库对 AI 说“升级 Hai-framework 到最新版本”，项目入口会引导读取 [hai-framework-sync](templates/skills/hai-framework-sync/SKILL.md)：在线确认发布版本、比较累计差异与应用影响，需要用户选择或处理阻塞时提示，随后迁移依赖/代码/配置、合并 skills 与 AI 入口并验证。仅要求比较时不会修改应用。`hai init` / `hai add` 为旧项目补齐升级 skill、相邻资源及引用的 CI/PR 流程技能，即使无法识别原模板也会交付；已有文件保留，旧版 skill 及入口仍须合并。
-
-创建提示直接输出到终端；安装失败会显示包管理器命令、退出码和 stdout/stderr，已生成文件保留，可进入目录重试安装。`prebuild-install@7.1.3` 的弃用警告来自 `better-sqlite3` 的上游安装依赖，单独的警告不会令安装失败；不要为隐藏警告覆盖或删除原生安装器。
-
-```bash
-# 交互式创建（推荐）
-hai create my-admin-app
-
-# 指定模板与功能
-hai create my-app -t full
-hai create my-app -t custom -f iam,db,ai
+```sh
+hai create my-app --type fullstack --frontends web --yes
+cd my-app
+pnpm dev
 ```
 
-交互流程：
+省略选项时按向导选择，`--yes` 使用默认值。默认安装依赖并初始化 Git，`--no-install` / `--no-git` 可关闭。部署工具默认作为开发依赖安装，不需要时加 `--no-deploy`。
 
-1. 输入项目名称
-2. 选择模板（minimal / default / full / custom）
-3. 选择功能模块（custom 模板下）
-4. 是否添加示例代码
-5. 选择包管理器（pnpm / npm / yarn）
-6. 是否安装依赖
-7. 是否初始化 Git
+### 项目模板
 
-### 添加模块
+| 类型                       | 生成内容                                                          |
+| -------------------------- | ----------------------------------------------------------------- |
+| `admin` / `website` / `h5` | SvelteKit 管理后台、官网、移动网页                                |
+| `api`                      | 共享 contract + API service 的 pnpm workspace                     |
+| `mobile-app`               | Svelte + Vite + Capacitor                                         |
+| `fullstack`                | contract、API、共享界面与所选 Web/App/Desktop；miniapp 仅预留说明 |
 
-```bash
-# 交互式选择
-hai add
+`--template minimal|default|full|custom` 选择模块预设，`--features iam,db,...` 选择业务模块。Fullstack 始终保留默认管理界面所需的 IAM、数据库、缓存、加密、存储和审计；默认不安装 AI/ONNX/CUDA。
 
-# 指定模块
-hai add iam
-hai add storage
-```
-
-向现有项目增量添加模块。自动更新 `package.json`、生成配置文件、解析依赖。
+### Fullstack mini 管理后台
 
-### 初始化/校验配置
+提供用户管理、角色、审计日志、头像和个人设置，以及主题、语言、引导和帮助中心。首次登录使用 `admin`，随机密码在根 `.env.local` 的 `HAI_ADMIN_DEFAULT_PASSWORD`；已有用户时不会重设密码。模板业务可按需求修改，权限检查始终在服务端执行。
 
-```bash
-# 校验配置完整性，补全缺失配置
-hai init
-
-# 强制重新生成所有配置
-hai init --force
-```
+### 应用配置与显示
 
-### 代码生成
+运行参数见 `.env.example`。公共基础 `.env` 与 `.env.dev/.env.test/.env.prod` 提交 Git，私有值放 `.env.local`。覆盖顺序为进程环境 > 本机私有文件 > 所选环境 > 公共基础。API 模板在服务目录放环境文件，fullstack 在工程根。模块 YAML、环境覆盖和显示信息说明见[使用指南](../../docs/usage/README.md#3-配置环境再开始开发)。
 
-名称必须以字母开头，仅含字母、数字、短横线或下划线，不接受路径。默认先预检全部输出并拒绝覆盖；显式 `--force` 才替换文件。输出及符号链接目标必须留在工作目录内。
+### 已有项目与代码生成
 
-页面/API 生成器适用于 SvelteKit；组件使用 Svelte 5 children snippet。API 使用 `kit.handler` 与 Zod 输入校验。迁移输出显式 `up()` / `down()`，调用前初始化 `reldb`，调用后检查 HaiResult；它不是自动迁移运行器，`down()` 会删除表，需应用确认后执行。
-
-```bash
-# 交互式生成
-hai generate
-
-# 指定类型
-hai generate page users
+```sh
+hai add storage
+hai init
+hai generate page dashboard
 hai generate component UserCard
-hai generate api users
-hai generate model user
-hai generate migration add-users
-
-# 快捷命令
-hai g:page dashboard
-hai g:component StatusBadge
-hai g:api orders
-hai g:model order
+hai generate api orders
+hai generate model order
+hai generate migration add-orders
 ```
 
-## 项目模板
+`hai add` 解析模块依赖并补充配置。`hai init` 补齐缺失配置和 AI 文件，保留已有自定义内容；`--force` 可重建模块配置，使用前检查差异。
 
-| 模板      | 说明     | 包含功能                                            |
-| --------- | -------- | --------------------------------------------------- |
-| `minimal` | 最小模板 | 基础 SvelteKit/hai 骨架（移动端为 Svelte 5 + Vite） |
-| `default` | 标准模板 | IAM + DB + Cache + Crypto                           |
-| `full`    | 完整模板 | 全量业务模块 + API Service / contract 机制          |
-| `custom`  | 自定义   | 按需选择                                            |
+page/api 生成器面向 SvelteKit，fullstack/API workspace 沿自己的 contract/procedure 结构扩展。名称不能包含路径，默认拒绝覆盖，`--force` 才替换。迁移只生成 up/down 函数，不自动执行；运行前确认数据影响。
 
-## Fullstack mini 管理后台
+### 构建与部署
 
-默认管理界面启用 `@h-ai/ui/guide` 新手引导与帮助中心：首次邀请、页面逐步高亮、搜索使用说明、手动重看和个人设置导览。Web/App/Desktop 共用 guide-store 和业务翻译，Web 用 Cookie、原生 WebView 用 localStorage，按用户和引导版本记录。新增页面只需补共享内容与 data-guide 锚点，见 [引导 skill](templates/skills/hai-ui/guide.md)。
+`pnpm build` 只编译源码。镜像使用 `images/` 中独立 Dockerfile，由 `hai.build.json` 指定文件；`--images` 决定构建哪些镜像，`--services` 决定更新哪些服务。容器引擎 auto 优先 Podman，再尝试 Docker。下载、安装和整理生产依赖共用包缓存与 SQLite 驱动缓存，避免重复下载。
 
-`--type fullstack` 默认生成包含 IAM、reldb、cache、audit、storage、crypto 的管理工程；即使选择 minimal，管理所需模块也会保留。`--frontends` 选择 Web、Capacitor App 和 Tauri Desktop；miniapp 仍是说明占位，不参与运行或构建。
+默认容器用于 CPU 运行或连接远程 AI 服务，不额外下载 GPU 运行库。需要使用部署机器上的 GPU 时，自行定制镜像和容器运行参数。
 
-```powershell
-hai create mini-admin --type fullstack --frontends web,app,desktop
-cd mini-admin
-pnpm.cmd install
-pnpm.cmd dev
+```sh
+pnpm build --target docker
+pnpm run deploy --env prod
+pnpm run deploy --env prod --build --services web
+pnpm run deploy --env prod --build --bundle-only --output release-prod.tar
 ```
 
-需要自动部署时添加 `--features deploy`，在工程根安装对应版本的 `@h-ai/deploy` 开发依赖，部署命令会使用项目本地版本。fullstack 默认不安装 AI/ONNX/CUDA；SQLite 在镜像构建时下载匹配版本、Node ABI、架构和 libc 的官方预编译包，重试并加载校验后复用缓存；不预装编译工具链，缺包或网络失败时明确停止。
-
-CLI 自动生成根目录 `.env.local`，其中 `HAI_ADMIN_DEFAULT_PASSWORD` 是每个项目独立的随机强密码；直接运行 `dev` / `start` 即可。首次登录使用 `admin` 和 `.env.local` 中的密码，同名环境变量可以覆盖它。密码遵循 `_iam.yml` 策略，默认至少 8 位；不符合策略时启动日志显示具体校验原因与错误码。已有用户后，该变量不会重设账号或密码。`.env.local` 被 Git 和容器构建忽略，`.env.example` 仅保留占位；部署时设置目标环境自己的密码。
-
-- 管理员可搜索、分页、新增、编辑、启禁用、删除用户并上传头像；服务端保护当前管理员，管理写操作在锁内重新鉴权，防止并发操作使管理员全部失权。
-- 初始角色为 `admin` / `user`，角色页显示人数并编辑说明，用户页分配角色。默认普通用户仅进入个人设置，直接请求管理接口也会被服务端拒绝；这些业务规则可按实际需求调整。
-- 审计页按操作、资源与日期查询记录；成功登录、退出、密码变更和管理写操作写入审计，记录不含密码、token 或头像内容。
-- 个人设置提供资料、头像、语言、主题和密码修改；偏好保存到 IAM 用户 metadata。头像接受 PNG/JPEG/WebP，最大 512 KiB，服务端验证图片内容并生成 storage key。
-
-前端 typed api-client 与 serv 的 crypto transport 统一加解密 JSON 业务、登录与刷新。Web 使用内存 access token 和 HttpOnly refresh Cookie；App 原生端使用 Capacitor 安全 TokenStorage，Desktop 原生端仅在内存保存 token，重启后重新登录。原生刷新 body 通道校验客户端标识、显式传输头和受信 Origin；浏览器预览沿用 Cookie。公开头像是白名单内的二进制图片资源。
-
-Web/App/Desktop 复用同一个 `AdminWorkspace`、management store 和 typed client。当前用户与刷新直接选用框架默认 IAM procedures，主题缓存与 DOM 更新复用 `@h-ai/ui/theme`；应用编排初始角色、自我保护、头像与审计等示例业务，这些规则可按实际需求调整。
-
-默认 SQLite、本地 storage 与 memory cache 适用于单实例 mini 后台。管理写入仅支持单写实例；多实例读取需要共享数据库、存储、Redis cache 和传输会话粘性路由，管理写请求仍须路由至同一实例。仅更换 Redis 不能保证任意多写副本的最后管理员原子保护。生成后的根脚本提供 typecheck、lint、build、test、test:e2e；Capacitor/Tauri 交付另执行对应原生构建和打包。
-
-## 应用配置与显示
-
-配置字段使用显式 `HAI_<配置名>_<路径>` 引用。每个项目的 `.env.example` 包含已启用参数和可选字段的用途、枚举、范围；框架根 [`.env.example`](../../.env.example) 是完整总表。分环境加载和命令见 [环境配置](templates/skills/hai-app-create/development.md#环境配置)。
-
-所有生成项目的 `.gitignore` 都包含 `**/data/`，忽略根目录及嵌套 workspace 的运行数据，包括 `.gitkeep`；运行时会创建需要的数据目录。
-
-Fullstack 的 `packages/<project>-serv/config/` 始终保留 13 份配置：`_core`、`_serv`、`_db`、`_cache`、`_iam`、`_storage`、`_audit`、`_reach`、`_ai`、`_vecdb`、`_payment`、`_scheduler`、`_deploy`（均为 `.yml`）。已用模块保留有效默认值，未启用模块整份注释，各模块的可选字段和替代 Provider 也以注释保留。`.env.example` 同时提供未启用模块的注释凭据示例。创建时填写的模块选项会保留。
-
-扩展时先在服务端 workspace 安装所需模块，在 `src/server/runtime.ts` 按公开 Schema 校验配置、初始化并反序关闭，再取消所需配置的注释。整份注释的文件先去掉一层外层注释，可选块继续按需开启；配置文件存在并不等于业务能力已接入。数据库、缓存和存储可通过环境变量切换 Provider 并填写连接字段；Reach Provider 使用标准配置数组，同名 Provider 只保留一个。`crypto.init()` 无配置参数，datapipe 是纯函数，不生成虚构的 YAML 配置。
-
-所有模板从 `_core.yml` 统一读取 `name`、`version`、`env`、`defaultLocale` 和 `logging`，通过 `core.config` 获取元信息并使用 `core.logger`。单应用配置在 `config/`；API workspace 在 `apps/<project>-service/config/`；fullstack 在 `packages/<project>-serv/config/`。日志级别与格式由 YAML 决定，不在初始化时另写固定 `logging` 覆盖。
+完整包包含应用和自建中间件镜像。仅打包会同时生成 tar 与 Windows `deploy.ps1`、Linux/macOS `deploy.sh`；完全隔离的 Linux 服务器解包后运行 `sh apply.sh`。首次部署必须完整；部分更新保留未选服务和数据卷。每步报告结果，失败返回非零并尝试恢复。前置工具、缓存、版本和恢复流程见[部署说明](../deploy/README.md)。
 
-环境变量可按 core 约定覆盖，如 `HAI_CORE_NAME`、`HAI_CORE_VERSION`、`HAI_CORE_ENV`、`HAI_CORE_LOGGING_LEVEL`；整体 `HAI_CORE` 覆盖遵循父节点优先规则。服务端配置变更后重启服务，容器显式设置 `HAI_CORE_ENV=production`，由该值启用生产安全策略。
+桌面安装包用 `pnpm build --target desktop --platform windows|linux|macos --arch x64|arm64`，在对应系统准备工具链并验证。容器里的 Web 页面不代替原生安装包。
 
-叶子环境变量只覆盖 YAML 中已有的路径；注释掉的键须先取消注释，或使用 `HAI_DB`、`HAI_CACHE` 等整体对象覆盖。camelCase 不拆词，例如 `connectTimeout` 对应 `HAI_CACHE_CONNECTTIMEOUT`。语言列表由各前端与 shared 的 `project.inlang/settings.json` 维护，`_core.yml` 只配置默认语言。
+### 使用 AI 辅助开发
 
-Fullstack 的 `.env` 启用当前模块的运行参数；YAML 引用同名变量并保留本地回退。未启用模块的变量和可选 Schema 字段保留注释。使用 `dev:test` / `dev:prod` 与服务端 `start:test` / `start:prod` 加载环境覆盖。
+生成工程根的 `AGENTS.md` 导航到 `.agents/skills/`；Claude、Copilot、OpenCode 的入口引用同一套规则。普通功能用 [应用开发](templates/skills/hai-app-create/SKILL.md)，较大文档先[审查](templates/skills/hai-spec-review/SKILL.md)再[逐项实施](templates/skills/hai-spec-implement/SKILL.md)，框架升级用[升级与同步](templates/skills/hai-framework-sync/SKILL.md)。
 
-SvelteKit 的服务端 layout 只下发名称、版本、环境和默认语言等公开白名单。独立 mobile-app 的 Vite 配置在 Node 构建阶段通过 core 解析 YAML，再注入公开值及浏览器日志级别/格式；修改 YAML 或覆盖变量后需要重新构建。Fullstack 前端通过加密的 `app.info` 获取服务端公开元信息。任何模板都不能把完整 core/模块配置、密钥或日志脱敏上下文注入浏览器。
+Skill 入口保存任务边界，相邻参考按需读取。`hai init` / `hai add` 只补齐缺失内容，已有技能与自定义规则需合并；同步时复制完整目录。
 
-## 全局选项
+## 开发测试
 
-构建和部署参数的含义、默认值与示例见[使用指南](../../docs/usage/README.md)。交付文件使用应用根 package.json 的版本，CLI 版本不会代替应用版本。
+### 开发阶段本地使用
 
-| 选项               | 说明          | 默认值   | 示例                          |
-| ------------------ | ------------- | -------- | ----------------------------- |
-| `-v, --verbose`    | 显示详细输出  | false    | `hai create my-app --verbose` |
-| `-C, --cwd <path>` | 指定工作目录  | 当前目录 | `hai build --cwd ../my-app`   |
-| `-h, --help`       | 显示命令帮助  | false    | `hai build --help`            |
-| `-V, --version`    | 显示 CLI 版本 | false    | `hai --version`               |
+在框架仓库根执行，用当前源码生成项目。完整测试命令如下，部署门禁另需可用 Podman/Docker。
 
-## 开发阶段本地使用
-
-> 适用于尚未发布到 npm、在 monorepo 中本地调试 CLI 的场景。
-
-### 1. 构建
-
-```bash
-# 构建 CLI（生成 dist/）
+```sh
 pnpm --filter @h-ai/cli build
-
-# 或启动 watch 模式（修改源码后自动重建）
-pnpm --filter @h-ai/cli dev
-```
-
-### 2. 直接运行（无需安装）
-
-构建完成后，可以用 `node` 直接调用 `dist/index.js`：
-
-```bash
-# 从仓库根目录运行
-node packages/cli/dist/index.js create my-app
-node packages/cli/dist/index.js create my-app --type admin --features iam,db
-```
-
-或者在任意目录通过绝对路径调用：
-
-```bash
-node /path/to/hai-framework/packages/cli/dist/index.js create my-app
-```
-
-### 3. 全局链接（`pnpm link`）
-
-如果希望在终端里直接用 `hai` 命令，可以全局链接：
-
-```bash
-# 在 packages/cli 目录下执行
-cd packages/cli
-pnpm link --global
-
-# 验证
-hai --version
-hai create my-app
-```
-
-> 使用完毕后可解除链接：`pnpm unlink --global @h-ai/cli`
-
-### 4. 在 monorepo 内的其他 app 中使用
-
-monorepo 内的 `apps/*` 项目已通过 `workspace:*` 协议引用本地包，可直接使用：
-
-```bash
-# 在仓库根目录执行，对任意 app 类型生成项目
-node packages/cli/dist/index.js create ../my-new-project
-```
-
-## 分环境部署
-
-运行 `hai deploy --env test`，先检查 `.env.test`，再逐项选择中间件默认配置、自定义连接或保持不变。`--yes` 保留目标环境的完整配置并为其余项采用当前后端默认值，`--env-dir` 指定环境文件目录。明确传入目标服务目录，如 `hai deploy packages/my-app-serv --env test`，不猜测 workspace 布局；容器启动脚本保留明确环境标识。公共连接项写目标环境文件，凭据写 `.env.local` 并脱敏显示。
-
-配置已完备时可在向导中选择“直接部署”，或执行 `hai deploy packages/my-app-serv --env prod --yes --skip-middleware`，跳过全部中间件提示、配置写入和资源开通。部署目标缺失时引导填写 SSH/Vercel 参数；SSH 地址、端口、密钥路径、远程目录及 Token 只保存到被 Git 忽略的 `.env.local`，下次自动复用。可编辑其中的 `HAI_DEPLOY_PROVIDER` 更新目标；私钥只填写路径。
-
-失败与降级提示也必须国际化：官网 API 按请求 locale 生成 AI 降级/邮件送达状态；未送达不能称为已接收。CLI 部署状态使用 cliM，Gallery 加密能力限制使用双语消息。中文与英文分别验证未配置、失败和成功路径，无需调用付费服务。
-
-云资源配置消费：Neon 输出 HAI_DB（PostgreSQL JSON），Upstash 输出 HAI_CACHE（Redis rediss URL JSON），R2 输出 HAI_STORAGE（扁平 S3 JSON）。邮件/短信输出 HAI_REACH_PROVIDERS 数组，deployApp 合并两个渠道并保留 YAML 中的消息模板；此覆盖替换原 providers 数组。Core 支持整体对象/数组覆盖，父节点优先于叶子变量，仍执行 Schema 校验；开通结果只进入目标运行环境，不传入构建进程。R2 必须提供已有 S3 accessKeyId/secretAccessKey；Resend 必须提供已验证域名的 from；阿里云必须提供已审核 signName/模板。应用须已有相应\_db/\_cache/\_storage/\_reach.yml 并在启动时加载，网络客户端需要 Node 运行时。
-
-部署失败恢复：`ProvisionResult.resourceStatus` 标记 created/reused；`getDeployRecovery(result.error)` 读取 projectName、stage、platformProjectId 和资源清单，unknown 表示请求结果不确定，必须先在服务商控制台核对。失败资源已返回 ID 时保留该 ID。恢复结果不含 envVars、原始异常或连接凭证，CLI 会展示清单和建议。同名重试复用现有资源；不自动删除复用资源，新建资源仅在人工确认未被使用后清理。
-
-## 配置驱动认证页面
-
-协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
-
-选用 IAM 的 admin/h5/website 模板提供 AuthPanel 和标准认证路由；mobile-app 与 fullstack Web/App/Desktop 使用 API 客户端共享动作。修改服务端 config/_iam.yml 控制登录方式、注册、重置、协议弹窗和品牌。LDAP/Reach 均可选：默认 LDAP 客户端需要应用安装 ldapts，再启用 login.ldap 并配置连接；短信/邮件可选择 Reach 模板或自定义发送回调。表单预留 header/extraFields/footer，AuthPanel 透传 login*/register* snippet。分布式部署使用共享数据库与 Redis。
-
-[完整 IAM 配置 / IAM configuration](../iam/README.md)
-
-### 6. 运行测试
-
-```bash
-# 单元测试 + E2E 模板生成测试
+node packages/cli/dist/index.js create ../my-app
+pnpm --filter @h-ai/cli typecheck
+pnpm --filter @h-ai/cli lint
 pnpm --filter @h-ai/cli test
-
-# 真实脚手架 E2E 门禁（生成项目后执行 install/typecheck/lint/build/test/e2e）
-pnpm --filter @h-ai/cli test:e2e
-
-# watch 模式
-pnpm --filter @h-ai/cli test:watch
-
-# 覆盖率
-pnpm --filter @h-ai/cli test:coverage
+pnpm check:skills
+pnpm --filter @h-ai/cli test:scaffold-gates
+pnpm --filter @h-ai/cli test:deploy-gates
 ```
 
-Admin 与 fullstack 门禁还用实际安装的本地 tarball 验证公开类型和运行行为：流式文件/checksum/拒覆盖、API Key scope 与撤销、当前授权、批量用户/角色分页、Reach 模板路由和 Audit 分页元数据；fullstack 同时验证可信对端 IP。
-
-成功截图默认保存在 CLI 的 `test-results/scaffold-evidence/`，可通过 `HAI_AUTH_EVIDENCE_DIR` 指定独立目录，生成项目清理后仍保留。fullstack E2E 启动所有已选 Web/App/Desktop 浏览器预览，并验证各端的登录、导览、帮助与个人设置；小程序和原生壳仍需要对应平台验收。
-
-## 生成项目的表单布局
-
-website 联系页与 fullstack 管理界面复用 UI 的 FormLayout/FormField：支持一列/双列、标签独立成行/同行、自动跨列和窄容器回落。用户编辑、资料与密码表单使用同组参数，校验提示由 UI 内置中英文处理；完整配置随生成项目的 hai-ui skill 提供。
+脚手架门禁生成真实项目，执行安装、typecheck、lint、build、test 和浏览器测试。部署门禁验证离线包、SSH/人工发布及部分更新。测试自动清理本轮资源；按需保留的截图写入指定证据目录。原生壳和真实云服务单独验收。
 
-## License
+## 许可证
 
 Apache-2.0

package/dist/{chunk-QYX6V7H2.js → chunk-7DSURTJ4.js}

@@ -2065,7 +2065,7 @@ var cli_config_catalog_default = [
     path: "deploy.provider.remote.baseDir",
     description: "\u8FDC\u7A0B\u5E94\u7528\u6839\u76EE\u5F55",
     value: "/opt/hai/apps",
-    constraint: "\u5B57\u7B26\u4E32\uFF1B\u6700\u5C0F\u5B57\u7B26\u6570 1"
+    constraint: "\u5B57\u7B26\u4E32\uFF1B\u6B63\u5219 ^\\/[\\w/. -]+$"
   },
   {
     name: "HAI_DEPLOY_PROVIDER_REMOTE_RUNTIME",
@@ -2097,7 +2097,7 @@ var cli_config_catalog_default = [
     path: "deploy.provider.ssh.host",
     description: "\u8FDC\u7A0B\u4E3B\u673A\u5730\u5740\u6216 ~/.ssh/config \u4E2D\u7684 Host \u522B\u540D",
     value: "",
-    constraint: "\u5B57\u7B26\u4E32\uFF1B\u6700\u5C0F\u5B57\u7B26\u6570 1"
+    constraint: "\u5B57\u7B26\u4E32\uFF1B\u6B63\u5219 ^[a-z0-9][a-z0-9.:-]*$"
   },
   {
     name: "HAI_DEPLOY_PROVIDER_SSH_IDENTITYFILE",
@@ -2137,7 +2137,7 @@ var cli_config_catalog_default = [
     path: "deploy.provider.ssh.username",
     description: "SSH \u7528\u6237\u540D",
     value: "deploy",
-    constraint: "\u5B57\u7B26\u4E32\uFF1B\u6700\u5C0F\u5B57\u7B26\u6570 1"
+    constraint: "\u5B57\u7B26\u4E32\uFF1B\u6B63\u5219 ^[a-z_][\\w-]*$"
   },
   {
     name: "HAI_DEPLOY_PROVIDER_TOKEN",
@@ -5352,83 +5352,26 @@ ${commented(optional)}`);
 `;
 }
 function generateDeployConfig() {
-  return `# =============================================================================
-# \u90E8\u7F72\u914D\u7F6E (@h-ai/deploy)
-# =============================================================================
-# \u90E8\u7F72\u5E73\u53F0\u51ED\u8BC1\u901A\u8FC7 ~/.hai/credentials.yml \u7BA1\u7406
-# \u73AF\u5883\u53D8\u91CF\u5F15\u7528\u683C\u5F0F: \${VAR_NAME:default_value}
-
-# \u90E8\u7F72\u5E73\u53F0
+  return `# \u90E8\u7F72\u5DF2\u6709\u955C\u50CF\uFF1B\u8FD0\u884C pnpm run deploy --build \u53EF\u5148\u6784\u5EFA\u518D\u53D1\u5E03\u3002
+# SSH \u53C2\u6570\u7531\u5411\u5BFC\u4FDD\u5B58\u5728\u672C\u673A .env.local\uFF1B\u79BB\u7EBF\u6253\u5305\u4E0D\u8981\u6C42 SSH\u3002
 provider:
-  type: vercel
-  token: \${HAI_DEPLOY_PROVIDER_TOKEN}
-
-# ---------------------------------------------------------------------------
-# \u65B9\u5F0F\u4E8C\uFF1Adocker-ssh \u2014 \u5C06\u5E94\u7528\u5BB9\u5668\u5316\u540E\u901A\u8FC7 SSH \u90E8\u7F72\u5230\u4EFB\u610F Linux \u4E3B\u673A
-# \u8FDC\u7A0B\u4E3B\u673A\u53EA\u9700\u5177\u5907 SSH + docker/podman + compose\uFF0C\u672C\u5730\u9700 docker \u6216 podman
-# \u5207\u6362\u65F6\u7528\u4E0B\u65B9 provider \u66FF\u6362\u4E0A\u9762\u7684 vercel provider
-# ---------------------------------------------------------------------------
-# provider:
-#   type: docker-ssh
-#   ssh:
-#     host: \${HAI_DEPLOY_PROVIDER_SSH_HOST}
-#     port: 22
-#     username: deploy
-#     identityFile: \${HAI_DEPLOY_PROVIDER_SSH_IDENTITYFILE}   # \u79C1\u94A5\u6587\u4EF6\u8DEF\u5F84\uFF08\u7701\u7565\u5219\u7528 ssh-agent\uFF09
-#     knownHostsFile: \${HAI_DEPLOY_PROVIDER_SSH_KNOWNHOSTSFILE}
-#     strictHostKeyChecking: true
-#     connectTimeoutSeconds: 10
-#   remote:
-#     baseDir: /opt/hai/apps
-#     runtime: auto                          # auto \u4F18\u5148 podman\uFF0C\u5176\u6B21 docker
-#   expose:
-#     type: port
-#     containerPort: 3000
-#     hostPort: 18080                        # \u8BBF\u95EE\u5730\u5740 http://<host>:18080
-
-# Compose \u4E2D\u95F4\u4EF6\u53C2\u6570\uFF1B\u955C\u50CF\u6784\u5EFA\u8BBE\u7F6E\u5728\u5DE5\u7A0B hai.build.json\u3002
-# container:
-#   s3Engine: rustfs # rustfs | minio\uFF1B\u5E94\u7528\u4F7F\u7528 storage.type=s3
-
-# \u57FA\u7840\u8BBE\u65BD\u670D\u52A1\uFF08\u6309\u9700\u5F00\u542F\uFF09
-# services:
-  # PostgreSQL \u6570\u636E\u5E93 (Neon)
-  # db:
-  #   provisioner: neon
-  #   apiKey: \${HAI_DEPLOY_SERVICES_DB_APIKEY}
-
-  # Redis \u7F13\u5B58 (Upstash)
-  # cache:
-  #   provisioner: upstash
-  #   email: \${HAI_DEPLOY_SERVICES_CACHE_EMAIL}
-  #   apiKey: \${HAI_DEPLOY_SERVICES_CACHE_APIKEY}
+  type: docker-ssh
+  remote:
+    baseDir: /opt/hai/apps
+    runtime: auto # \u4F18\u5148 Podman\uFF0C\u5176\u6B21 Docker
+  expose:
+    hostPort: 18080
+    containerPort: 3000
 
-  # S3 \u5B58\u50A8 (Cloudflare R2)
-  # storage:
-  #   provisioner: cloudflare-r2
-  #   accountId: \${HAI_DEPLOY_SERVICES_STORAGE_ACCOUNTID}
-  #   apiToken: \${HAI_DEPLOY_SERVICES_STORAGE_APITOKEN}
-  #   accessKeyId: \${HAI_DEPLOY_SERVICES_STORAGE_ACCESSKEYID}
-  #   secretAccessKey: \${HAI_DEPLOY_SERVICES_STORAGE_SECRETACCESSKEY}
+container:
+  s3Engine: \${HAI_DEPLOY_CONTAINER_S3ENGINE:rustfs} # rustfs | minio
 
-  # \u90AE\u4EF6 (Resend)
-  # email:
-  #   provisioner: resend
-  #   apiKey: \${HAI_DEPLOY_SERVICES_EMAIL_APIKEY}
-  #   from: \${HAI_DEPLOY_SERVICES_EMAIL_FROM}
-
-  # \u77ED\u4FE1 (\u963F\u91CC\u4E91)
-  # sms:
-  #   provisioner: aliyun
-  #   accessKeyId: \${HAI_DEPLOY_SERVICES_SMS_ACCESSKEYID}
-  #   accessKeySecret: \${HAI_DEPLOY_SERVICES_SMS_ACCESSKEYSECRET}
-  #   signName: \${HAI_DEPLOY_SERVICES_SMS_SIGNNAME}
-
-# docker-ssh \u8BF4\u660E\uFF1A
-# - \u5148 pnpm build --target docker\uFF1Bdeploy \u6D88\u8D39\u5DF2\u6709\u955C\u50CF\u5E76\u751F\u6210\u4E00\u4E2A Compose tar \u540E\u4E0A\u4F20
-# - compose \u6309\u5B9E\u9645\u540E\u7AEF\u751F\u6210\u4E2D\u95F4\u4EF6\uFF1BS3 \u9ED8\u8BA4 RustFS\uFF0C\u53EF\u901A\u8FC7 s3Engine \u9009\u62E9 MinIO
-# - \u955C\u50CF\u6E05\u5355\u542B Web \u65F6\u4E00\u5E76\u90E8\u7F72\uFF0CWeb \u4E0D\u63A5\u6536 API \u7684\u79C1\u6709\u53D8\u91CF\uFF1B--bundle-only \u53EF\u624B\u5DE5\u642C\u8FD0
-# - \u82E5\u540C\u65F6\u914D\u7F6E\u4E86\u5BF9\u5E94\u4E91 Provisioner\uFF0C\u5219\u4F18\u5148\u4F7F\u7528\u4E91\u8D44\u6E90\uFF0C\u4E0D\u518D\u81EA\u5EFA sidecar
+# \u5B8C\u6574\u5305\u5305\u542B\u81EA\u5EFA\u4E2D\u95F4\u4EF6\u955C\u50CF\uFF0C\u670D\u52A1\u5668\u542F\u52A8\u7981\u6B62\u62C9\u53D6\u3002
+# \u5916\u90E8\u6570\u636E\u5E93/\u5B58\u50A8\u7B49\u8FDE\u63A5\u5728\u5BF9\u5E94\u6A21\u5757\u914D\u7F6E\u548C\u73AF\u5883\u6587\u4EF6\u4E2D\u8BBE\u7F6E\u3002
+# Vercel \u4EC5\u6D88\u8D39\u5DF2\u6709 .vercel/output\uFF0C\u4E91 Provider/Provisioner \u4E0D\u9002\u7528\u4E8E\u5B8C\u5168\u79BB\u7EBF\u3002
+# provider:
+#   type: vercel
+#   token: \${HAI_DEPLOY_PROVIDER_TOKEN}
 `;
 }
 function generateVecdbConfig() {
@@ -5609,5 +5552,5 @@ function generatePaymentConfig() {
 }
 
 export { generateConfigFile, generateEnvExample, moduleEnvironmentVariables, parameterizeConfig, renderEnvironment, runtimeEnvironmentVariables };
-//# sourceMappingURL=chunk-QYX6V7H2.js.map
-//# sourceMappingURL=chunk-QYX6V7H2.js.map
+//# sourceMappingURL=chunk-7DSURTJ4.js.map
+//# sourceMappingURL=chunk-7DSURTJ4.js.map