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

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

@@ -1,292 +1,49 @@
 ---
 name: hai-deploy
-description: "使用 @h-ai/deploy 部署应用：Vercel 云平台或 docker-ssh 容器化部署到任意 Linux 主机，并按需开通/生成基础设施。"
+description: "构建并发布或交付已有镜像：完整离线包、按服务更新、SSH 与跨平台手工部署、失败恢复；也支持 Vercel prebuilt。"
 ---
 
 # hai-deploy
 
 ## 能力契约
 
-`hai deploy` 在模块/配置缺失或凭证、扫描、初始化、部署、关闭失败时返回非零退出码。自动化流程必须以退出码判断成功，不要只判断命令是否完成或是否输出日志。
-
 | 项目 | 契约 |
 | --- | --- |
-| 能力 | 使用 @h-ai/deploy 部署应用：Vercel 云平台或 docker-ssh 容器化部署到任意 Linux 主机 |
-| 适用场景 | 部署目标配置、云资源开通、SSH 主机容器部署或部署故障排查 |
-| 输入 | 项目构建产物、部署目标（vercel / docker-ssh）、环境配置与凭据引用 |
-| 输出 | 部署/资源操作结果和可验证的目标状态（含访问 URL 与健康检查） |
-| 限制 | 核对实际 provider 与应用运行时；开通收费资源、发布或删除必须在用户授权范围内，凭据不写入仓库。 |
-
-> `@h-ai/deploy` 提供两种部署方式：
-> 1. **vercel** — 将 SvelteKit（adapter-vercel）应用部署到 Vercel，并自动开通 Neon/Upstash/R2/Resend/阿里云等云基础设施；
-> 2. **docker-ssh** — 将原生 fullstack API 或 SvelteKit（adapter-node）应用容器化后经 SSH 部署到任意具备 docker/podman + compose 的 Linux 主机，按所选功能自动生成 compose sidecar。
-
-## 运行环境
-
-> ⚠️ **Node.js CLI / 服务端模块。** 通过 `hai deploy` CLI 命令或在 Node.js 脚本中使用。
-> docker-ssh 方式要求本地安装 docker 或 podman（`auto` 优先 podman）。
-
-当前 Node 要求 `^22.22.2 || ^24.15.0 || >=26.0.0`，生成工程固定 pnpm 12.11.2；Node 20 / pnpm 9.5.0 不受支持。Windows 必须有已启动、能构建目标 Linux 架构的容器引擎，不能把仅安装客户端或远程有 Docker 当作本地可构建。
-
-## 适用场景
-
-- 一键部署 SvelteKit 应用到 Vercel
-- 容器化后经 SSH 部署到自有服务器 / 云主机 / 内网虚拟机（docker-ssh）
-- 自动开通 PostgreSQL、Redis、S3 等云服务，或按功能生成自建 sidecar
-- 管理部署凭证（~/.hai/credentials.yml）
-- 扫描应用依赖，自动检测所需服务
-- CLI 部署流程（`hai deploy`）
-
-## 使用步骤
+| 能力 | 配置环境与中间件，交付完整离线包或发布选中服务 |
+| 适用场景 | 一体化构建发布、独立打包、隔离网络手工部署、增量更新与故障排查 |
+| 输入 | package.json、hai.build.json、运行依赖锁文件、目标环境、已有制品或明确构建要求 |
+| 输出 | 带校验和的 tar、跨平台部署入口与分步结果，或经过 HTTP 检查的部署结果 |
+| 限制 | SDK 只消费产物；CLI --build 显式先构建。首次安装必须完整交付，packaged 不代表服务器 ready。云资源需要外网。 |
 
-部署前按 [环境与中间件向导](middleware.md) 先选择环境并检查对应文件，再逐项选择默认配置、自定义连接或保持不变。用户确认配置已完备时，可选择直接部署或传 `--skip-middleware` 跳过全部中间件处理。SSH 地址、端口、密钥路径及平台 Token 首次填写后仅保存 `.env.local`，后续自动复用。该文档列出模块依赖、后端、连接字段、云开通边界和启动验证要求。
+## 操作流程
 
-### 1. 配置
+1. 读取项目 scripts、images/ 中的 Dockerfile、hai.build.json 与服务目录配置。创建默认带开发期部署工具；用户明确 --no-deploy 时不生成部署入口。构建细节见 [hai-build](../hai-build/SKILL.md)。
+2. 选择环境，验证 .env.<mode> 存在，再处理 SSH 与必要中间件。使用人类可读字段说明，复用有效配置；私有参数写 .env.local，私钥仅引用路径。环境规则见 [middleware.md](middleware.md)。
+3. 先校验所选制品、版本、服务和 SHA-256。--build 只构建所选应用镜像；不带它时缺产物明确失败，不隐式补构建。格式版本 3 记录 appVersion、buildId、partial、hasWeb、镜像归档及显式配置的 appContainerPort/webContainerPort；部分构建也保留未选镜像端口，缺省使用部署默认值。同一应用版本可重建，镜像引用区分实际内容；禁止 latest 与无版本镜像。
+4. 完整包自动导出实际自建中间件镜像并去重；只更新 Web 不重新打包 API/中间件。打包机需容器引擎导出中间件，服务器仅 load，禁止 pull/build。外部连接及云开通不能伪称为离线自包含服务。
+5. --services 使用目标服务器最后成功状态为基线，检查端口/拓扑及未选依赖，保留未选配置、凭据、网络和卷。脚本先按项目/服务标签仅删除选中旧容器（保留卷），再 up -d --no-deps --no-build --pull never --no-recreate 创建新容器并保留其他容器，避免 Compose Provider 连带重建反向依赖，禁止整个项目 down。storage-init 是一次性创建 S3 桶，涉及存储初始化才运行。仅更新 storage 也需含 app 镜像的制品运行初始化；最近为 web-only 时，用 --artifact-dir 选择原完整制品，或先 pnpm build --target docker --images app，不会更新运行中的 app 服务。
+6. --bundle-only 不连接 SSH，同时输出 tar 和 -deploy/ 操作目录。Windows deploy.ps1、Linux/macOS deploy.sh 上传并执行包内 apply.sh；完全隔离时搬运 tar，独立目录解包执行 sh apply.sh，可传部署根目录。脚本不依赖源码、Node 或 pnpm。
+7. 工具预检、基线、上传、校验、镜像导入、服务更新和 HTTP 检查分别报告。失败返回非零退出码，结果文件保留失败阶段；只有检查成功才更新服务器 current。已有部署失败尝试恢复所选服务的旧容器和配置；数据卷保留，已写业务数据不回退，恢复后仍需验证健康。禁止把本地打包记录当服务器成功状态。
 
-```yaml
-# config/_deploy.yml
-provider:
-  type: vercel
-  token: ${HAI_DEPLOY_PROVIDER_TOKEN}
+## CLI
 
-services:
-  db:
-    provisioner: neon
-    apiKey: ${HAI_DEPLOY_SERVICES_DB_APIKEY}
-  cache:
-    provisioner: upstash
-    email: ${HAI_DEPLOY_SERVICES_CACHE_EMAIL}
-    apiKey: ${HAI_DEPLOY_SERVICES_CACHE_APIKEY}
-  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}
-  email:
-    provisioner: resend
-    apiKey: ${HAI_DEPLOY_SERVICES_EMAIL_APIKEY}
-    from: ${HAI_DEPLOY_SERVICES_EMAIL_FROM}
-  sms:
-    provisioner: aliyun
-    accessKeyId: ${HAI_DEPLOY_SERVICES_SMS_ACCESSKEYID}
-    accessKeySecret: ${HAI_DEPLOY_SERVICES_SMS_ACCESSKEYSECRET}
-    signName: ${HAI_DEPLOY_SERVICES_SMS_SIGNNAME}
+```sh
+pnpm run deploy --env prod --build
+pnpm build --target docker
+pnpm run deploy --env prod --artifact-dir .hai/build/docker/<buildId>
+pnpm run deploy --env prod --bundle-only --output release-prod.tar
+pnpm build --target docker --images web
+pnpm run deploy --env prod --services web
 ```
 
-这些凭证名由 `deploy.credentials` 管理，属于显式特殊映射；若同时设置
-`HAI_DEPLOY_PROVIDER_TOKEN` 等约定变量，约定变量仍拥有最高优先级。
-
-#### docker-ssh 配置
-
-将上面的 `provider` 替换为 docker-ssh（远程主机需 SSH + docker/podman + compose）：
-
-```yaml
-# config/_deploy.yml
-provider:
-  type: docker-ssh
-  ssh:
-    host: ${HAI_DEPLOY_PROVIDER_SSH_HOST}
-    port: 22
-    username: deploy
-    identityFile: ${HAI_DEPLOY_PROVIDER_SSH_IDENTITYFILE} # 私钥文件路径，省略则用 ssh-agent
-  remote:
-    baseDir: /opt/hai/apps
-    runtime: auto # auto 优先 podman，其次 docker
-  expose:
-    type: port
-    containerPort: 3000
-    hostPort: 18080 # 访问地址 http://<host>:18080
-
-container:
-  runtime: auto # 本地构建运行时，可选
-
-services:
-  # 启用的服务会被加入远程 compose sidecar（postgres/redis/rustfs 或 minio）
-  # 若配置了云 Provisioner（如 neon），则优先用云资源，不再自建 sidecar
-  db:
-    provisioner: neon
-    apiKey: ${HAI_DEPLOY_SERVICES_DB_APIKEY}
-```
-
-docker-ssh 要点：
-
-- 应用镜像优先使用工程自带的 Dockerfile；SvelteKit 需要 adapter-node，原生 fullstack 服务自动生成以 `dist/index.js` 启动的镜像。
-- compose 按 `deploy.scan()` 识别的服务**及其后端类型**生成匹配 sidecar 并注入 `HAI_*` 覆盖变量：
-  - `db`：`postgresql`→postgres、`mysql`→mysql、`sqlite`→数据卷（无 sidecar）→ `HAI_DB`
-  - `cache`：`redis`→redis → `HAI_CACHE`；`storage`：`s3`→RustFS/MinIO（container.s3Engine） → `HAI_STORAGE`
-  - `vecdb`：`qdrant`/`pgvector`/`chroma`→对应 sidecar、`lancedb`→数据卷 → `HAI_VECDB`
-- 若同一服务已配置云 Provisioner（如 neon 提供 `HAI_DB`），优先用云资源，不再自建 sidecar
-- sidecar 密码写被忽略的本机私有配置及远程 `.env.runtime`（权限 600），不入公共环境文件或 `compose.yml`
-- `identityFile` 是私钥**路径**（非私钥内容）；禁止把私钥内容写进 `_deploy.yml`
-
-### 2. 初始化与关闭
-
-```typescript
-import { deploy } from '@h-ai/deploy'
-
-deploy.credentials.load()
-
-await deploy.init({
-  provider: { type: 'vercel', token: 'vel_xxx' },
-  services: {
-    db: { provisioner: 'neon', apiKey: 'neon_xxx' },
-  },
-})
-
-// 使用后关闭
-await deploy.close()
-```
-
-### 3. 扫描应用
-
-```typescript
-const scanResult = await deploy.scan('./apps/my-app', { environment: 'test' })
-if (scanResult.success) {
-  const { appName, isSvelteKit, requiredServices } = scanResult.data
-}
-```
-
-### 4. 开通基础设施
-
-```typescript
-const provResults = await deploy.provisionAll('my-project')
-if (provResults.success) {
-  for (const prov of provResults.data) {
-    // prov.envVars 包含需要注入的环境变量
-  }
-}
-```
-
-### 5. 完整部署
-
-```typescript
-const result = await deploy.deployApp('./apps/my-app', {
-  projectName: 'my-project',
-  skipProvision: false,
-  skipBuild: false,
-})
-if (result.success) {
-  // result.data.url — 部署地址
-  // result.data.deploymentId — 部署 ID
-  // result.data.envVarsSet — 已设置的环境变量列表
-}
-```
+使用 pnpm run deploy，避免与 pnpm 自带 deploy 混淆。fullstack 指向 packages/<项目>-serv，API workspace 指向 apps/<项目>-service；这是扫描入口，不是镜像选择。--services 负责选择；--skip-middleware 只跳过配置及开通。--yes 复用有效配置，缺值时不盲目继续。
 
-## 核心 API
+## SDK
 
-| 方法                   | 签名                                                                       | 说明         |
-| ---------------------- | -------------------------------------------------------------------------- | ------------ |
-| `deploy.credentials.load` | `() => HaiResult<string[]>`                                             | 加载凭证到 `process.env` |
-| `deploy.credentials.save` | `(key: string, value: string) => HaiResult<void>`                        | 保存单个凭证 |
-| `deploy.credentials.saveAll` | `(entries: Record<string, string>) => HaiResult<void>`                | 批量保存凭证 |
-| `deploy.credentials.getPath` | `() => string`                                                         | 获取凭证文件路径 |
-| `deploy.init`          | `(config: DeployConfigInput) => Promise<HaiResult<void>>`        | 初始化模块   |
-| `deploy.close`         | `() => Promise<void>`                                                      | 关闭模块     |
-| `deploy.scan`          | `(appDir: string, options?: DeployScanOptions) => Promise<HaiResult<ScanResult>>` | 按环境扫描（不依赖 init） |
-| `deploy.provisionAll`  | `(projectName: string, services?: ServiceType[]) => Promise<HaiResult<ProvisionResult[]>>` | 开通指定或全部已配置服务 |
-| `deploy.deployApp`     | `(appDir: string, options?) => Promise<HaiResult<DeployResult>>` | 完整部署     |
-| `deploy.config`        | `DeployConfig \| null`                                                     | 当前配置     |
-| `deploy.isInitialized` | `boolean`                                                                  | 初始化状态   |
+deploy.init 后检查 HaiResult.success，deploy.deployApp 接收 artifactDir、bundleOnly、selectedServices、runtime 与 onProgress；finally 中 deploy.close。deploy.scan 和 deploy.credentials.* 不依赖 init。Vercel 只消费已有 .vercel/output，不执行源码构建，也不支持 Compose 离线/部分更新。
 
-## 凭证管理
-
-所有凭证操作都通过 `deploy.credentials.*` 访问，模块入口不再单独导出自由函数。
-
-> `deploy.credentials.*()` 与 `deploy.scan()` 都不依赖 `deploy.init()`，可用于 CLI 在读取 `_deploy.yml` 之前准备环境。
-
-## 配置消费与失败恢复
-
-云资源配置消费：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 会展示清单和建议。同名重试复用现有资源；不自动删除复用资源，新建资源仅在人工确认未被使用后清理。
-
-## 错误码 — `HaiDeployError`
-
-| 错误码                                  | code               | 说明                     |
-| --------------------------------------- | ------------------ | ------------------------ |
-| `HaiDeployError.DEPLOY_FAILED`         | `hai:deploy:001`   | 部署失败（通用）         |
-| `HaiDeployError.PROJECT_CREATE_FAILED` | `hai:deploy:002`   | 平台项目创建失败         |
-| `HaiDeployError.BUILD_FAILED`          | `hai:deploy:003`   | 应用构建失败             |
-| `HaiDeployError.UPLOAD_FAILED`         | `hai:deploy:004`   | 构建产物上传失败         |
-| `HaiDeployError.AUTH_REQUIRED`         | `hai:deploy:005`   | 未认证                   |
-| `HaiDeployError.AUTH_FAILED`           | `hai:deploy:006`   | 认证失败                 |
-| `HaiDeployError.PROVISION_FAILED`      | `hai:deploy:007`   | 基础设施开通失败         |
-| `HaiDeployError.ADAPTER_MISSING`       | `hai:deploy:008`   | SvelteKit adapter 未安装 |
-| `HaiDeployError.SCAN_FAILED`           | `hai:deploy:009`   | 应用扫描失败             |
-| `HaiDeployError.NOT_INITIALIZED`       | `hai:deploy:010`   | 模块未初始化             |
-| `HaiDeployError.ENV_VAR_FAILED`        | `hai:deploy:011`   | 环境变量设置失败         |
-| `HaiDeployError.UNSUPPORTED_TYPE`      | `hai:deploy:012`   | 不支持的类型             |
-| `HaiDeployError.CONFIG_ERROR`          | `hai:deploy:013`   | 配置错误                 |
-| `HaiDeployError.CREDENTIAL_ERROR`      | `hai:deploy:014`   | 凭证读写失败             |
-| `HaiDeployError.CONTAINER_RUNTIME_NOT_FOUND` | `hai:deploy:015` | 未找到容器运行时     |
-| `HaiDeployError.CONTAINER_BUILD_FAILED` | `hai:deploy:016`  | 镜像构建失败             |
-| `HaiDeployError.REMOTE_CONNECT_FAILED` | `hai:deploy:017`   | 远程连接失败             |
-| `HaiDeployError.REMOTE_COMMAND_FAILED` | `hai:deploy:018`   | 远程命令失败             |
-| `HaiDeployError.IMAGE_TRANSFER_FAILED` | `hai:deploy:019`   | 镜像传输失败             |
-| `HaiDeployError.HEALTH_CHECK_FAILED`   | `hai:deploy:020`   | 健康检查未通过           |
-
-## CLI 命令
-
-通过 CLI 部署前，先按 [CLI 安装与命令](../hai-app-create/development.md#cli-安装与命令) 全局安装 `@h-ai/cli`，确认 `hai --version` 可运行后再执行下列命令。在 Node.js 脚本中直接使用 `@h-ai/deploy` API 时无需安装 CLI。
-
-```bash
-# 部署当前目录
-hai deploy
-
-# 部署指定应用
-hai deploy ./apps/admin-console --env test
-
-# 跳过基础设施开通
-hai deploy --env prod --skip-provision
-
-# 仅 Vercel：跳过应用构建；docker-ssh 仍会构建镜像
-hai deploy --env prod --skip-build
-
-# 自定义项目名
-hai deploy --project-name my-custom-name
-```
-
-> 部署方式由 `config/_deploy.yml` 的 `provider.type` 决定（vercel / docker-ssh），
-> CLI 命令相同。docker-ssh 成功后输出的访问地址为 `http://<host>:<hostPort>`。
-
-fullstack 需明确部署服务包；`hai deploy packages/my-app-serv --env prod` 不会发布 Web。根 Dockerfile 的 `runtime` / `web` target 分别构建 API / Web；Web 单独转移、运行，设置浏览器可访问的 `PUBLIC_API_BASE` 和 API 的 CORS。模板 `pnpm run deploy` 是打包脚本，不等于 CLI 发布。
-
-离线部署先按 [离线准备与验收](middleware.md#离线准备与验收) 检查材料。docker-ssh 在本地构建并导出镜像 tar，再分别上传镜像、Compose、运行环境和启动脚本，不在远程构建源码。当前无直接指定预构建镜像的参数；不得声称 `--skip-build` 能离线发布容器，也不得将联网部署测试作为断网证明。
-
-## 常见模式
-
-### 仅部署（跳过基础设施）
-
-```typescript
-await deploy.deployApp('./apps/my-app', { skipProvision: true })
-```
-
-### 仅开通基础设施
-
-```typescript
-await deploy.init(config)
-const result = await deploy.provisionAll('my-project')
-// 手动使用 result.data 中的环境变量
-await deploy.close()
-```
-
-### 自定义部署流程
-
-```typescript
-import { deploy } from '@h-ai/deploy'
-
-// Provider 通过 init 配置自动创建，不需要手动导入
-await deploy.init({
-  provider: { type: 'vercel', token: 'vel_xxx' },
-})
-
-// 使用 deploy API 部署
-const result = await deploy.deployApp('./apps/my-app')
-```
+## 离线交付与验证
 
-## 相关 Skills
+Linux 预备 Docker/Podman、支持 --pull never 的 Compose（Docker Compose v2 或 podman-compose 1.6.0 及以上）、sh、tar、sha256sum、awk、curl 及目录/容器权限。完整 tar 包含全部自建中间件归档；目标架构须匹配。包中有私有配置，安全搬运，不提交 Git。离线构建额外准备基础镜像、Linux 依赖缓存、工具链与原生预编译包；Windows node_modules 不能替代。
 
-- **hai-core** — 配置加载、日志、HaiResult 类型
-- **hai-reldb** — 数据库（Neon PostgreSQL）
-- **hai-cache** — 缓存（Upstash Redis）
+按 [分轮验证与集中修复](../hai-app-tests/validation.md) 收集适用的 typecheck、lint、build、test、scaffold gates 和 test:deploy-gates，汇总后集中修复、再验证。实际验证无 registry 网络的首次部署、登录刷新、同版本重发、只更新 Web/API、损坏归档、缺基线、健康失败与恢复。Windows/Linux/macOS 上传入口分别执行验收；原生安装包在对应 OS 验证。测试临时工程、容器、镜像、数据和进程在 finally/teardown 清理，只清理测试拥有的资源；日志、截图和报告保留到分析和交付结束再清理。

package/templates/skills/hai-deploy/middleware.md

@@ -29,7 +29,7 @@
 2. **使用自定义配置**：逐项输入所选后端的连接字段，展示变量名、字段用途与约束，校验必填项、端口、布尔和 URL；凭据用密码输入。保存配置后跳过该服务的开通与 sidecar。
 3. **保持不变**：仅在目标 `.env.<mode>` 显式声明当前后端及完整连接配置时出现；私有凭据可来自 `.env.local`/进程。选择后不修改该项、不认证其 Provisioner、不创建或移除已有中间件容器，继续下一项。只有 `.env` 或其他环境有配置不满足此条件。
 
-逐项配置前提供“环境配置已完备，直接部署”。选择后跳过全部中间件提示、变量改写、云资源与 sidecar 创建，保留已有服务；仍执行应用构建、部署及健康检查。命令行可用 `--skip-middleware`（或 `--skip-provision`）明确选择。不要因为缺少某项中间件的目标文件声明而阻止用户主动跳过。
+逐项配置前提供“环境配置已完备，直接部署”。选择后跳过全部中间件提示、变量改写、云资源与 sidecar 创建，保留已有服务；仍校验已有构建产物并执行部署及健康检查。命令行使用唯一的 `--skip-middleware`，SDK 使用 `skipMiddleware`。不要因为缺少某项中间件的目标文件声明而阻止用户主动跳过。
 
 `--yes` 用于已授权的自动化：目标环境已有完整配置时保持不变，否则使用当前后端默认配置；不支持的云后端或缺少必需凭据直接失败。自动化直接部署用 `hai deploy packages/my-app-serv --env prod --yes --skip-middleware`。跳过不作为配置完整性或连接成功的证明。
 
@@ -71,24 +71,12 @@ S3 是协议，不是某个容器产品。默认配置时另选 RustFS/MinIO，
 
 ## 离线准备与验收
 
-先核对 Node、pnpm 与目标 Linux 架构。当前要求 Node `^22.22.2 || ^24.15.0 || >=26.0.0`，生成工程固定 pnpm 12.11.2。Windows 本地需已初始化的 Linux 容器引擎、OpenSSH、完整项目及已安装的 CLI/SDK 依赖；Linux 需容器引擎和 Compose、SSH 授权与权限。无互联网仍需 Windows 到 Linux 的 SSH 和应用端口可达。
+构建与部署可分开，也可通过 pnpm run deploy --build 明确串联。构建保持环境无关；部署选择环境并只消费所选镜像。完整包自动包含 Compose 自建中间件镜像，因此导出阶段需要本地 Podman/Docker，缺镜像在打包阶段准备，不能留给隔离服务器下载。
 
-有 PostgreSQL/Redis/RustFS 镜像不代表有可用服务。默认配置要求 Compose 中镜像名称、tag、架构准确匹配，SDK 不传输中间件镜像；自定义连接要求服务已启动、地址从应用容器可达并提供数据库/账号、密码、S3 密钥/桶。不要用容器内 localhost 指代宿主机服务。
+--bundle-only 生成带版本 tar 与 -deploy/ 目录。操作目录含 Windows deploy.ps1、Linux/macOS deploy.sh 和目标配置。隔离服务器搬运并解包后执行 sh apply.sh。每步失败返回非零，结果写 result-<部署ID>.json；只有 HTTP 检查通过才更新服务器 current。
 
-默认 Dockerfile 会下载 Node 基础镜像、pnpm、依赖和 SQLite 预编译包，不能直接称为离线可用。源码离线构建要准备 Linux 构建环境的完整缓存和构建 frontend，调整下载步骤并断开外网演练；Windows node_modules/pnpm store 不代表 Linux 的原生依赖可用。云 Provider/Provisioner 需要外网，不用于完全离线部署。
+部分更新通过 --services 指定，使用服务器成功基线保留未选服务和中间件凭据。首次安装不能使用部分包。storage-init 复用应用镜像及 S3 SDK 检查/创建桶，不清空数据；只有涉及存储初始化时执行，并检查退出码。仅更新 storage 仍需含 app 镜像的制品；最近为 web-only 时，用 --artifact-dir 选择原完整制品，或先 pnpm build --target docker --images app。app 镜像仅用于初始化，不会更新 app 服务。失败恢复尝试还原容器和配置，保留数据卷，不回退已写业务数据。
 
-docker-ssh 始终执行本地镜像构建，`--skip-build` 仅对 Vercel 生效。预构建离线交付可在准备环境导出 API/Web 镜像，在 Windows 引擎加载 API 镜像后，为目标服务包提供仅含 `FROM <已加载的API镜像>` 的 Dockerfile 和内容 `*` 的 `.dockerignore`，让 SDK 复用成品并上传。业务代码变更后必须重制成品镜像；无匹配本地镜像时不能继续假定构建无网络。
+服务器需要 Linux、Docker/Podman、Compose、sh、tar、sha256sum、awk、curl、持久化磁盘和容器/目录权限。完整交付包含自建服务镜像；自定义外部连接仍需准备服务、账号和网络可达性。云 Provider/Provisioner 需要外网，不能用于完全离线。
 
-fullstack 的 Web 不在服务包 `hai deploy` 中发布，需单独加载/运行 Web 镜像并设置 PUBLIC_API_BASE、API CORS。生产禁止通配 CORS，refresh Cookie 启用 Secure；须准备 HTTPS 入口、内网证书/信任与 DNS/hosts，SDK 不自动配置 TLS/反向代理。离线验收须包含断外网构建/上传/启动、API 健康、真实 Web 登录、页面与会话刷新、重启和持久化；分别报告 API 部署、Web 发布和断网证据，不能互相替代。
-
-## 启动与验证
-
-fullstack 创建时可通过 `--features deploy` 安装对应版本的本地部署工具。SQLite 在模板及兜底 Dockerfile 中先按驱动版本、Node ABI、架构和 libc 下载官方预编译包，最多尝试三次，加载验证后由生产依赖安装复用缓存；不预装 Python/make/C++，无匹配包或下载失败时停止构建。受限网络可预置 prebuild-install 缓存，或配置 container.sqlitePrebuildMirror（HAI_DEPLOY_CONTAINER_SQLITEPREBUILDMIRROR；自带 Dockerfile 使用 SQLITE_PREBUILD_MIRROR build arg）。镜像根地址后附 /v<驱动版本>/<匹配 ABI 的包名>，不得包含认证信息。不能把更换下载命令当成解决网络不可达，也不能用 CUDA 开关掩盖无关 AI 依赖。
-
-Podman 构建默认继承运行时代理。代理地址在容器内不可达时，在 `_deploy.yml` 配置 `container.httpProxy: false`（已声明该节点时也可使用 `HAI_DEPLOY_CONTAINER_HTTPPROXY=false`），不要修改用户的系统代理。`loadDeploymentEnvironment`、`loadDeploymentConfig`、`saveDeploymentEnvironment` 可用于脚本显式读取、解析和保存同一份部署配置，均返回 HaiResult。
-
-构建上下文必须排除 `.env.local`、`.env.*.local`、`.env.runtime` 和 `.hai/deploy`（含镜像归档与凭据）；公共环境文件仍可进入上下文。兜底 Dockerfile 使用伴随忽略文件，Podman 通过 `--ignorefile` 显式指定，避免使用 workspace 根规则后把上次部署的归档或运行配置重新打进构建层。
-
-容器运行期设置 `NODE_ENV=production`，`HAI_DEPLOY_ENVIRONMENT` 保存文件模式，`HAI_CORE_ENV` 映射为 development/test/production/staging。显式环境部署的资源名追加环境后缀，避免 test/prod 复用同一数据卷。启动脚本位于服务包 `.hai/deploy/<mode>/start-<mode>.sh`，显式导出环境并执行 compose；私有 `.env.runtime` 权限为 600。自带 Dockerfile 可读取同名 build args；不得把私有环境文件或运行凭据复制进镜像。
-
-修改此流程后执行 deploy/CLI 的 typecheck、lint、build、test，以及 `pnpm --filter @h-ai/cli test:deploy-gates`（当前源码 tarball → fullstack → Podman/SSH → 健康检查、环境标识、登录和重复部署）。模板变动另执行受影响的 scaffold gates。日志、截图、验收报告保存在 Git 忽略的临时目录，不提交仓库；付费云资源、原生客户端与远程生产部署须单独验证并说明边界。
+完全离线构建另需基础镜像、Linux 依赖缓存、pnpm 和匹配驱动/Node ABI/架构/libc 的原生预编译包。构建可用 --sqlite-prebuild-mirror，Podman 代理不可达可用 --no-http-proxy；不要改系统代理或让 deploy 下载编译环境。生产 HTTPS、CORS、证书、DNS 另行准备。实际断网验收登录、刷新、重启和数据持久化。

package/templates/skills/hai-framework-sync/SKILL.md

@@ -75,7 +75,7 @@ npm view @h-ai/cli dist-tags --json
 | --- | --- |
 | 自动处理 | 目标明确、可保持现有行为的依赖更新、兼容性修正、无冲突的 skills 合并和验证，直接执行 |
 | 用户选择 | 存在多个有意义的方案且影响产品行为、架构、成本、Provider 或运维方式，展示证据、选项、推荐与取舍，等待回答 |
-| 阻塞 | 无法取得必要产物、依赖不兼容、无法无损合并、必要工具/服务/授权缺失或关键验证失败，先诊断并修复可自行解决的原因；仍无法推进时说明具体处理步骤 |
+| 阻塞 | 无法取得必要产物、依赖不兼容、无法无损合并、必要工具/服务/授权缺失等导致后续无法执行，先处理可自行解决的原因；仍无法推进时说明具体步骤。普通门禁失败先记录，继续独立检查，本轮汇总后集中修复；必要门禁未通过仍不能交付完成 |
 | 不适用 | 当前应用未使用且不影响其依赖/运行的变化，记录依据；不要求用户逐项确认 |
 
 - 尽量合并相互独立的选择，明确每个回答控制哪项改动；已给出的目标、授权和选择持续有效，不重复询问。
@@ -95,7 +95,7 @@ npm view @h-ai/cli dist-tags --json
 
 ### 6. 验证与交付
 
-按应用实际 scripts 和 [hai-ci](../hai-ci/SKILL.md) 执行 `typecheck → lint → build → test`，优先受影响 workspace；跨包契约验证所有消费者。按 [hai-app-tests](../hai-app-tests/SKILL.md) 选择受影响的集成/E2E，覆盖启动/关闭、变更 API、认证、持久化等实际路径。
+按应用实际 scripts 和 [分轮验证与集中修复](../hai-app-tests/validation.md) 先收集一轮适用门禁，汇总根因后集中修复、再验证；优先受影响 workspace，跨包契约验证所有消费者。按 [hai-app-tests](../hai-app-tests/SKILL.md) 选择集成/E2E，覆盖启动/关闭、变更 API、认证、持久化等实际路径；CI/发布按 [hai-ci](../hai-ci/SKILL.md) 保留失败阻断。
 
 - 依赖升级后另核对 lockfile 与安装版本、公开入口、配置加载和关键业务流程；build 通过不能替代 typecheck 或运行验收。
 - 检查同步后的全部相邻资源、相对引用和各工具入口；目标存在 `check:skills` 时运行，不假定应用具有框架仓库私有脚本。

package/templates/skills/hai-framework-sync/sync.md

@@ -45,5 +45,5 @@ PowerShell 使用 `pnpm.cmd`；占位包名替换后执行。本地来源先验
 
 - 仅 skills/入口变更：检查 diff、完整目录、目标实际存在的入口及相邻资源、相对引用；排除框架仓库私有绝对路径/命令。
 - 框架模板维护：运行已有 `check:skills` 和 CLI `test:scaffold-gates`，确认资源与路由在生成项目中可达。
-- 同步应用依赖或运行时：按入口升级流程和 [hai-ci](../hai-ci/SKILL.md) 选择应用门禁，不以模板已同步代替运行验收。
+- 同步应用依赖或运行时：按入口升级流程和 [分轮验证与集中修复](../hai-app-tests/validation.md) 收集适用门禁、集中修复并复测；CI/发布遵守 [hai-ci](../hai-ci/SKILL.md)，不以模板已同步代替运行验收。
 - 双仓改动时说明来源版本/提交、改动顺序、应用私有覆盖和双方验证；涉及 PR 时按 [hai-pr-review](../hai-pr-review/SKILL.md) 关联同步说明。仅授权一个仓库时记录另一方待同步，不擅自修改。

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

@@ -28,14 +28,12 @@ description: "使用 @h-ai/iam 实现登录、注册、会话、OTP/LDAP/API Key
 - LDAP/Reach 均可选：基础认证无需安装；默认 LDAP 关闭，选用默认客户端才安装 ldapts 并设置 login.ldap + ldap。OTP 邮件/短信由 otp.email/sms 控制，选择 Reach 标准模板或自定义发送回调；具体签名与失败处理见参考中的“可选 LDAP 与通知”。
 - 多节点共享 DB + Redis，Memory 只用于单进程。重置的策略失败计入 maxAttempts；OTP 消费不解除 resendInterval。管理员 createUser 不受自助注册开关限制。
 
-- 协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
-
 - 受保护请求使用 `iam.auth.verifyToken`：当前用户状态 + 角色 JOIN + 批量权限读取，失败即拒绝；`iam.session.verifyToken` 仅验证会话快照。serv 内置 IAM 注入默认使用当前授权入口，无需手动补查。
 - 用户批量读取用 `iam.user.getUsers(ids, { include: ['roles'] })`（最多 1000，去重保留输入顺序，缺失省略）；角色筛选用 `listUsers({ roleCode })`，在分页前执行，避免 N+1 和分页后过滤。
 
 ## 按需参考
 
-详细配置、API 签名、错误码和范本在 [reference.md](reference.md)。按下列标题定位所需小节，不默认通读；用例中的业务变量需结合当前应用补齐。
+按任务读取 [reference.md](reference.md) 的对应小节；签名以当前源码或安装版本的公开类型为准，不默认加载全部资料。示例中的业务变量由应用提供。
 
 - 运行环境
 - 依赖

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

@@ -1,6 +1,6 @@
 ---
 name: hai-kit
-description: "使用 @h-ai/kit 集成 SvelteKit hooks、守卫、校验、响应及同源客户端传输。"
+description: "在 SvelteKit 中接入 hooks、认证守卫、输入校验、响应和同源加密客户端；不用于独立 serv 服务。"
 ---
 
 # hai-kit
@@ -15,173 +15,18 @@ description: "使用 @h-ai/kit 集成 SvelteKit hooks、守卫、校验、响应
 | 输出 | handle、Response、校验值和客户端请求结果 |
 | 限制 | 无 init/close；保留 SvelteKit 控制流异常。跨端共享 HTTP contract 用 api-contract + serv，勿复制到 kit。 |
 
-> `@h-ai/kit` 只负责 SvelteKit 集成：`handle` hook、guard、response、validate、client、auth、crud、A2A。公共跨端 HTTP API 契约统一使用 `@h-ai/api-contract` + `@h-ai/serv`，不要在 kit 中定义业务 API contract。
+## 使用路径
 
-## 使用步骤
+1. 仅在 SvelteKit 集成；先查现有 hooks、配置、守卫与路由，不将其套用于独立 serv 应用。
+2. 用 createHandle 编排已初始化模块；认证 API 与公开路径复用 kit.auth，客户端复用框架动作。
+3. 区分返回 HaiResult 的业务操作与抛 Response/redirect/error 的框架控制流，不吞掉控制流。
+4. 对齐 Cookie/CSRF/transport 与服务端配置，验证匿名、登录、权限拒绝和表单失败。
 
-### 1. 请求管道
+## 按需参考
 
-```ts
-import type { Handle } from '@sveltejs/kit'
-import { kit } from '@h-ai/kit'
+按本次操作读取对应小节；以已安装版本的公开类型核验签名，示例中的业务变量由应用提供。
 
-const haiHandle = kit.createHandle({
-  auth: {
-    verifyToken: async token => token ? { userId: 'u_1', roles: ['admin'], permissions: ['user:read'] } : null,
-    loginUrl: '/auth/login',
-    protectedPaths: ['/admin/*'],
-  },
-  rateLimit: { windowMs: 60_000, maxRequests: 100 },
-  logging: true,
-})
-
-export const handle: Handle = haiHandle
-```
-
-### 2. SvelteKit API endpoint
-
-```ts
-import { kit } from '@h-ai/kit'
-import { z } from 'zod'
-
-const CreateUserSchema = z.object({ name: z.string().min(1) })
-
-export const POST = kit.handler(async ({ request, locals }) => {
-  kit.guard.require(locals.session, 'user:create')
-  const payload = await kit.validate.body(request, CreateUserSchema)
-  return kit.response.created(payload)
-})
-```
-
-### 3. 浏览器同源请求
-
-```ts
-import { kit } from '@h-ai/kit'
-
-const client = kit.client.create()
-export const { apiFetch } = client
-```
-
-> 同源 endpoint 优先使用 httpOnly Cookie；`auth: true` 只读取 `kit.auth.setBrowserToken()` 写入的页面内存 Token，不会默认读写 localStorage。确需 Bearer Header 时，显式传入 `BrowserTokenStore`，禁止把敏感 Token 存入 localStorage。
-
-### 4. 同源传输加密
-
-kit 不再维护本地传输加密实现；服务端和客户端都统一委托 `@h-ai/crypto` 的 `crypto.transport`。
-
-```ts
-// hooks.server.ts
-import { cache } from '@h-ai/cache'
-import { createRedisTransportKeyStore, crypto } from '@h-ai/crypto'
-import { kit } from '@h-ai/kit'
-
-await crypto.init()
-await cache.init({ type: 'redis', host: '127.0.0.1', port: 6379 })
-
-export const handle = kit.createHandle({
-  auth: {
-    verifyToken,
-    protectedPaths: ['/api/*'],
-    publicPaths: ['/api/_hai/*'],
-  },
-  crypto: {
-    crypto,
-    transport: {
-      requireEncryption: true,
-      keyStore: createRedisTransportKeyStore({ cache, ttlSeconds: 3600 }),
-    },
-  },
-})
-```
-
-需要保护会话 Cookie 时配置 `crypto.encryptedCookies`，并通过 `crypto.cookieEncryptionKey` 或 `HAI_KIT_COOKIE_KEY` 提供密钥。缺少密钥会在 `createHandle()` 时失败；加解密错误不会回退到明文 Cookie。
-
-```ts
-// routes/+layout.svelte
-<script lang='ts'>
-  import { browser } from '$app/environment'
-  import { crypto } from '@h-ai/crypto'
-  import { kit } from '@h-ai/kit'
-  import { appKitConfig } from '$lib/config/kit-config'
-
-  // 一次性安装：内部按 appKitConfig.transport 是否启用决定行为，并预热 crypto
-  if (browser) {
-    kit.client.installBrowserTransport(appKitConfig, { crypto })
-  }
-</script>
-```
-
-```ts
-// lib/utils/api.ts —— 业务层只看到 apiFetch
-import { kit } from '@h-ai/kit'
-
-export const { apiFetch } = kit.client.create()
-```
-
-默认协商端点：`/api/_hai/key-exchange`。如 `keyExchangePath` 自定义，浏览器端同步设置 `keyExchangeUrl`。
-
-多节点部署时，可在 `kit.createHandle({ crypto: { transport } })` 的运行时对象里直接传 `keyStore`；推荐使用 `@h-ai/crypto` 根入口导出的 `createRedisTransportKeyStore()` / `createReldbTransportKeyStore()`。这类对象依赖不要写进 `_kit.yml`。
-
-transport 默认保护同源 `/api/*` endpoint 与 SvelteKit `__data.json` 页面数据请求；页面文档、静态资源与 `multipart/form-data` 上传请求保持明文透传。
-
-安全策略默认 fail-closed：`requireEncryption: true` 时，受保护路径缺少 `X-Client-Id` 必须返回 400；服务端 transport 管理器不可用、响应体无法加密或超过单次加密上限时返回错误，禁止明文业务响应回退。`requireEncryption: false` 只适合迁移期灰度。
-
-### 5. 使用 `_kit.yml` 统一 transport 配置
-
-`@h-ai/kit` 现在提供 `KitConfigSchema` / `resolveKitConfig()`，适合同一份 `_kit.yml`
-同时驱动 `hooks.server.ts` 与浏览器端 `kit.client.installBrowserTransport()`：
-
-```yml
-server:
-  host: 127.0.0.1
-  port: 3000
-
-transport:
-  keyExchangePath: /api/_hai/key-exchange
-  requireEncryption: true
-  encryptResponse: true
-  excludePaths:
-    - /api/storage
-    - /api/public
-    - /api/auth/profile/avatar
-  maxClients: 10000
-```
-
-```ts
-import { resolveKitConfig } from '@h-ai/kit'
-import { parse } from 'yaml'
-import rawKitConfig from '../config/_kit.yml?raw'
-
-export const appKitConfig = resolveKitConfig(parse(rawKitConfig) ?? {})
-```
-
-`resolveKitConfig()` 同时解析 `server`（host/port）与 `transport`；host/port 优先级为 `HOST` / `PORT` 环境变量 > `_kit.yml` 的 `server` > 默认 `127.0.0.1:3000`（与 `@h-ai/serv` 同构）。
-`_kit.yml` 只放公开的 server/transport 路径/开关，不放密钥；如自定义 `keyExchangePath`，浏览器端必须同步映射为 `keyExchangeUrl`。
-
-## 核心 API
-
-| API | 用途 |
-| --- | --- |
-| `kit.createHandle()` | 创建 SvelteKit Handle |
-| `kit.sequence()` | 组合多个 Handle |
-| `kit.handler()` | API endpoint 错误边界 |
-| `kit.guard.require()` | 权限守卫 |
-| `kit.response.*` | 统一响应工厂 |
-| `kit.validate.*` | Zod 请求校验 |
-| `kit.auth.*` | Cookie / Token 辅助 |
-| `kit.client.create()` | 浏览器端同源 apiFetch |
-| `kit.client.installBrowserTransport(config, { crypto })` | 推荐入口：按解析后的 `_kit.yml` 一键安装浏览器端传输加密 |
-| `kit.client.installBrowserTransportFetch()` | 底层入口：直接传 transport 配置安装浏览器全局 fetch 包装 |
-| `kit.crud.define()` | 声明式 CRUD 资源 |
-
-## 常见模式
-
-- SvelteKit 应用内同源请求用 `kit.client.create().apiFetch`。
-- SvelteKit 应用启用 transport 时，在 `+layout.svelte` 的 `if (browser)` 分支调用一次 `kit.client.installBrowserTransport(appKitConfig, { crypto })`，无需重复连线 `keyExchangeUrl` / `excludePaths`。
-- Web/App/小程序跨域访问公共 API 用 `@h-ai/api-client` typed client。
-- 传输加密只通过 `crypto.transport` 间接装配，不在 kit 中新增本地加密工厂或鸭子类型。
-- 服务端业务模块直接调用模块 API，不通过 HTTP 自环。
-- API endpoint 必须用 Zod 校验用户输入，并设置认证/权限边界。
-
-## 声明式 CRUD 表单字段
-
-`kit.crud.define` 的字段支持 `colSpan: 'auto' | 1 | 2`，以及 `validation.message: string | (() => string)`。布局通过 UI 的 `CrudPage.form` 配置；客户端校验用于交互提示，服务端仍使用 Zod 验证和现有权限守卫。UI 公共契约见相邻 [hai-ui skill](../hai-ui/SKILL.md)。
+- [使用步骤](reference.md#使用步骤)
+- [核心 API](reference.md#核心-api)
+- [常见模式](reference.md#常见模式)
+- [声明式 CRUD 表单字段](reference.md#声明式-crud-表单字段)