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

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

@@ -19,7 +19,8 @@ description: "使用 @h-ai/core 配置、日志、i18n、ID、Zod 错误本地
 
 - Node 启动用 core.init({ configDir }) 加载配置；勿传 logging 覆盖 _core.yml 中的日志设置，除非任务明确要求。
 - 应用名称、版本、环境、默认语言和日志设置统一从 `_core.yml` 经 core.config 获取，日志使用 core.logger；UI 不另维护硬编码副本。SvelteKit layout / fullstack app.info 仅下发公开字段白名单；独立 Vite mobile-app 在 Node 构建时解析并注入公开值，修改配置后重新构建。浏览器不加载 YAML，不接收完整模块配置、密钥或日志脱敏上下文。
-- HAI_<配置名>_<路径> 可整体覆盖根/对象/数组；父节点优先，未覆盖时才遍历已有叶子。camelCase 不拆词，约定变量优先于显式插值。
+- `HAI_<配置名>_<路径>` 可整体覆盖根/对象/数组；父节点优先，未覆盖时才遍历已有叶子。camelCase 不拆词，约定变量优先于显式插值。
+- 环境文件采用六类：`.env.example` 完整列出字段用途、默认值、枚举和范围；`.env` 为公共基础；`.env.dev`、`.env.test`、`.env.prod` 为公共环境覆盖，这五类均提交 Git。`.env.local` 为本机私有配置，不提交 Git。优先级为进程环境 > `.env.local` > 环境文件 > `.env`；Vite 在 Node 配置阶段调用 `core.config.loadEnvFiles({ mode, envDir })` 并检查 success 后注入进程，Node 脚本按相同顺序传入 `--env-file`。`core.init` 不自行读取 dotenv。
 - 配置 getter 与 ID/logger 方法不是 HaiResult；validate/load 等须检查 success。
 - 初始化前创建的默认、模块与嵌套 child Logger 在后续输出中应用当前全局 logging；configure/setLevel 也作用于已有实例。create 的显式 level/format/context 优先，未指定项动态继承。浏览器 json/pretty 与附加 redact 路径实际生效，消息文本仍由调用方脱敏。
 

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

@@ -19,13 +19,15 @@ description: "使用 @h-ai/deploy 部署应用：Vercel 云平台或 docker-ssh
 
 > `@h-ai/deploy` 提供两种部署方式：
 > 1. **vercel** — 将 SvelteKit（adapter-vercel）应用部署到 Vercel，并自动开通 Neon/Upstash/R2/Resend/阿里云等云基础设施；
-> 2. **docker-ssh** — 将 SvelteKit（adapter-node）应用容器化后经 SSH 部署到任意具备 docker/podman + compose 的 Linux 主机，按所选功能自动生成 compose sidecar。
+> 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
@@ -37,37 +39,39 @@ description: "使用 @h-ai/deploy 部署应用：Vercel 云平台或 docker-ssh
 
 ## 使用步骤
 
+部署前按 [环境与中间件向导](middleware.md) 先选择环境并检查对应文件，再逐项选择默认配置、自定义连接或保持不变。用户确认配置已完备时，可选择直接部署或传 `--skip-middleware` 跳过全部中间件处理。SSH 地址、端口、密钥路径及平台 Token 首次填写后仅保存 `.env.local`，后续自动复用。该文档列出模块依赖、后端、连接字段、云开通边界和启动验证要求。
+
 ### 1. 配置
 
 ```yaml
 # config/_deploy.yml
 provider:
   type: vercel
-  token: ${HAI_DEPLOY_VERCEL_TOKEN}
+  token: ${HAI_DEPLOY_PROVIDER_TOKEN}
 
 services:
   db:
     provisioner: neon
-    apiKey: ${HAI_DEPLOY_NEON_API_KEY}
+    apiKey: ${HAI_DEPLOY_SERVICES_DB_APIKEY}
   cache:
     provisioner: upstash
-    email: ${HAI_DEPLOY_UPSTASH_EMAIL}
-    apiKey: ${HAI_DEPLOY_UPSTASH_API_KEY}
+    email: ${HAI_DEPLOY_SERVICES_CACHE_EMAIL}
+    apiKey: ${HAI_DEPLOY_SERVICES_CACHE_APIKEY}
   storage:
     provisioner: cloudflare-r2
-    accountId: ${HAI_DEPLOY_CF_ACCOUNT_ID}
-    apiToken: ${HAI_DEPLOY_CF_API_TOKEN}
-    accessKeyId: ${HAI_DEPLOY_R2_ACCESS_KEY_ID}
-    secretAccessKey: ${HAI_DEPLOY_R2_SECRET_ACCESS_KEY}
+    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_RESEND_API_KEY}
-    from: ${HAI_DEPLOY_RESEND_FROM}
+    apiKey: ${HAI_DEPLOY_SERVICES_EMAIL_APIKEY}
+    from: ${HAI_DEPLOY_SERVICES_EMAIL_FROM}
   sms:
     provisioner: aliyun
-    accessKeyId: ${HAI_DEPLOY_ALIYUN_ACCESS_KEY_ID}
-    accessKeySecret: ${HAI_DEPLOY_ALIYUN_ACCESS_KEY_SECRET}
-    signName: ${HAI_DEPLOY_ALIYUN_SIGN_NAME}
+    accessKeyId: ${HAI_DEPLOY_SERVICES_SMS_ACCESSKEYID}
+    accessKeySecret: ${HAI_DEPLOY_SERVICES_SMS_ACCESSKEYSECRET}
+    signName: ${HAI_DEPLOY_SERVICES_SMS_SIGNNAME}
 ```
 
 这些凭证名由 `deploy.credentials` 管理，属于显式特殊映射；若同时设置
@@ -82,10 +86,10 @@ services:
 provider:
   type: docker-ssh
   ssh:
-    host: ${HAI_DEPLOY_SSH_HOST}
+    host: ${HAI_DEPLOY_PROVIDER_SSH_HOST}
     port: 22
     username: deploy
-    identityFile: ${HAI_DEPLOY_SSH_KEY} # 私钥文件路径，省略则用 ssh-agent
+    identityFile: ${HAI_DEPLOY_PROVIDER_SSH_IDENTITYFILE} # 私钥文件路径，省略则用 ssh-agent
   remote:
     baseDir: /opt/hai/apps
     runtime: auto # auto 优先 podman，其次 docker
@@ -98,22 +102,22 @@ container:
   runtime: auto # 本地构建运行时，可选
 
 services:
-  # 启用的服务会被加入远程 compose sidecar（postgres/redis/minio）
+  # 启用的服务会被加入远程 compose sidecar（postgres/redis/rustfs 或 minio）
   # 若配置了云 Provisioner（如 neon），则优先用云资源，不再自建 sidecar
   db:
     provisioner: neon
-    apiKey: ${HAI_DEPLOY_NEON_API_KEY}
+    apiKey: ${HAI_DEPLOY_SERVICES_DB_APIKEY}
 ```
 
 docker-ssh 要点：
 
-- 应用镜像使用工程自带的 `Dockerfile`（`@sveltejs/adapter-node`），缺少 adapter-node 会返回 `ADAPTER_MISSING`
+- 应用镜像优先使用工程自带的 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`→minio → `HAI_STORAGE`
+  - `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`
+- sidecar 密码写被忽略的本机私有配置及远程 `.env.runtime`（权限 600），不入公共环境文件或 `compose.yml`
 - `identityFile` 是私钥**路径**（非私钥内容）；禁止把私钥内容写进 `_deploy.yml`
 
 ### 2. 初始化与关闭
@@ -137,7 +141,7 @@ await deploy.close()
 ### 3. 扫描应用
 
 ```typescript
-const scanResult = await deploy.scan('./apps/my-app')
+const scanResult = await deploy.scan('./apps/my-app', { environment: 'test' })
 if (scanResult.success) {
   const { appName, isSvelteKit, requiredServices } = scanResult.data
 }
@@ -179,8 +183,8 @@ if (result.success) {
 | `deploy.credentials.getPath` | `() => string`                                                         | 获取凭证文件路径 |
 | `deploy.init`          | `(config: DeployConfigInput) => Promise<HaiResult<void>>`        | 初始化模块   |
 | `deploy.close`         | `() => Promise<void>`                                                      | 关闭模块     |
-| `deploy.scan`          | `(appDir: string) => Promise<HaiResult<ScanResult>>`             | 扫描应用（不依赖 init） |
-| `deploy.provisionAll`  | `(projectName: string) => Promise<HaiResult<ProvisionResult[]>>` | 开通所有服务 |
+| `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`                                                                  | 初始化状态   |
@@ -191,6 +195,12 @@ if (result.success) {
 
 > `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               | 说明                     |
@@ -225,13 +235,13 @@ if (result.success) {
 hai deploy
 
 # 部署指定应用
-hai deploy ./apps/admin-console
+hai deploy ./apps/admin-console --env test
 
 # 跳过基础设施开通
-hai deploy --skip-provision
+hai deploy --env prod --skip-provision
 
-# 跳过构建
-hai deploy --skip-build
+# 仅 Vercel：跳过应用构建；docker-ssh 仍会构建镜像
+hai deploy --env prod --skip-build
 
 # 自定义项目名
 hai deploy --project-name my-custom-name
@@ -240,6 +250,10 @@ 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` 能离线发布容器，也不得将联网部署测试作为断网证明。
+
 ## 常见模式
 
 ### 仅部署（跳过基础设施）
@@ -276,9 +290,3 @@ const result = await deploy.deployApp('./apps/my-app')
 - **hai-core** — 配置加载、日志、HaiResult 类型
 - **hai-reldb** — 数据库（Neon PostgreSQL）
 - **hai-cache** — 缓存（Upstash Redis）
-
-失败与降级提示也必须国际化：官网 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 会展示清单和建议。同名重试复用现有资源；不自动删除复用资源，新建资源仅在人工确认未被使用后清理。

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

@@ -0,0 +1,94 @@
+# 部署环境与中间件
+
+## 环境先行
+
+`hai deploy` 首先输入部署环境，或用 `hai deploy --env test` 指定。`.env.test` / `.env.prod` 必须由用户先创建；缺失时停止，不代替用户创建一个空文件继续部署。指定要部署的目录，例如 `hai deploy packages/my-app-serv --env test`，该目录必须对应 lockfile 的一个 importer；不遍历 apps/packages 或猜测 fullstack 布局。环境文件默认取当前目录（有 `.env` 时）或 lockfile 根目录，必要时传 `--env-dir`。
+
+环境文件遵循项目的六文件规范：`.env.example` 为带说明/枚举/范围的完整清单，`.env` 为公共基础，`.env.dev/test/prod` 为公共环境覆盖，以上五类提交 Git；`.env.local` 为忽略 Git 的本机私有覆盖。加载顺序为进程 > `.env.local` > 目标环境 > `.env`。真实密码、API Key、含认证信息的连接 URL 写 `.env.local`，公共后端和地址写目标环境文件；日志展示脱敏值。调用 deploy API 时显式传 `{ environment: 'test', envDir: '/workspace/app' }`，不要用调用者的 `NODE_ENV` 猜测部署目标。
+
+## 识别与逐项选择
+
+先用 `deploy.scan(appDir, { environment, envDir })` 核对实际依赖、配置与环境值。扫描从目标 workspace 的 `pnpm-lock.yaml` importer 出发，沿 dependencies/optionalDependencies 遍历，排除 devDependencies、peerDependencies 和其他应用未被引用的依赖；workspace link 只沿运行依赖继续。pnpm 12 的工具链 YAML 文档不能混入应用图。lockfile、目标 importer 或依赖节点缺失时先执行 `pnpm install` 修复；依赖图不读取 package.json、pnpm-workspace.yaml 或项目目录布局。配置文件决定已识别模块的后端，保留的旧配置不能自行启用未依赖的模块。
+
+`ScanResult.haiModules` 列出所有实际运行依赖中的 Hai 模块；`ScanResult.middlewares` 提供服务、后端、来源、配置路径和变量前缀；连接配置可能含凭据，不能整体记入日志。`DEPLOY_MIDDLEWARE` 是后端和连接字段的公共目录，字段名称、类型与约束须与模块 Schema 同步。
+
+| 来源 | 后端选项 | 默认 Compose 行为 | 云自动开通 |
+| --- | --- | --- | --- |
+| reldb；IAM/audit；启用 DB 日志的 scheduler | SQLite / MySQL / PostgreSQL | SQLite 数据卷；mysql / postgres 服务 | PostgreSQL → Neon |
+| cache；IAM；scheduler 可选分布式锁 | memory / Redis | memory 无服务；redis 服务 | Redis → Upstash |
+| storage | local / S3 | 本地数据卷；RustFS（默认）/MinIO + bucket 初始化 | S3 → Cloudflare R2 |
+| vecdb | LanceDB / pgvector / Qdrant / Chroma | 本地卷或对应容器 | 自定义已有服务 |
+| IAM 可选目录认证 | disabled / LDAP | 禁用无服务；OpenLDAP | 自定义已有目录 |
+| Reach Provider 数组 | console / SMTP / HTTP API；阿里云 SMS | console 无服务；SMTP 用 Mailpit 捕获测试邮件；HTTP/SMS 自定义 | SMTP → Resend；SMS → 阿里云凭据接入 |
+
+`serv` 声明 AI peer 不代表应用启用了 AI，不应因此安装 AI/ONNX/CUDA 或开通向量服务。LDAP 需要在应用安装 IAM 的可选 peer `ldapts`，并显式设置 `login.ldap=true`；安装 IAM 不代表启用了 LDAP。Reach 保留 Provider 的数组索引及名称，不能把 HTTP 回调当作 SMTP。默认目录没有业务账号；Mailpit 不会对外投递生产邮件。生产应配置企业 LDAP/SMTP，或使用对应云服务。
+
+每项都展示当前生效后端和用途，例如 `HAI_DB_TYPE=postgresql` 显示 PostgreSQL，再选择：
+
+1. **使用默认配置**：选择后端；Compose 生成匹配容器/卷，云平台调用已支持的 Provisioner，并保存实际连接配置。MySQL、LDAP、向量库等没有云自动开通器时，明确提示改用自定义连接；不能声称已经创建云资源。Resend 需要已验证的发件域名，R2 需要已有 S3 访问密钥，阿里云短信需要签名/模板与额度。
+2. **使用自定义配置**：逐项输入所选后端的连接字段，展示变量名、字段用途与约束，校验必填项、端口、布尔和 URL；凭据用密码输入。保存配置后跳过该服务的开通与 sidecar。
+3. **保持不变**：仅在目标 `.env.<mode>` 显式声明当前后端及完整连接配置时出现；私有凭据可来自 `.env.local`/进程。选择后不修改该项、不认证其 Provisioner、不创建或移除已有中间件容器，继续下一项。只有 `.env` 或其他环境有配置不满足此条件。
+
+逐项配置前提供“环境配置已完备，直接部署”。选择后跳过全部中间件提示、变量改写、云资源与 sidecar 创建，保留已有服务；仍执行应用构建、部署及健康检查。命令行可用 `--skip-middleware`（或 `--skip-provision`）明确选择。不要因为缺少某项中间件的目标文件声明而阻止用户主动跳过。
+
+`--yes` 用于已授权的自动化：目标环境已有完整配置时保持不变，否则使用当前后端默认配置；不支持的云后端或缺少必需凭据直接失败。自动化直接部署用 `hai deploy packages/my-app-serv --env prod --yes --skip-middleware`。跳过不作为配置完整性或连接成功的证明。
+
+部署目标不完整时，先引导选择 SSH/Vercel。SSH 逐项输入主机、端口、用户名、私钥文件路径、known_hosts 路径、远程目录/运行时及容器/主机端口；端口范围 1–65535。密钥路径留空使用 ssh-agent/默认密钥，known_hosts 留空使用 OpenSSH 默认文件。完整目标自动复用；修改 `.env.local` 的 `HAI_DEPLOY_PROVIDER` 可切换连接。首次填写的整个目标对象（包括地址、端口、路径、Token）只保存 `.env.local` 并添加 Git 忽略，不把机器信息写公共环境文件。SDK 使用 `saveDeploymentEnvironment(snapshot, variables, { private: true })` 可显式保存本机参数。禁止读取、复制或打印私钥内容。
+
+### Hai 模块与中间件的关系
+
+识别依据是运行图中的所有节点，不按应用直接依赖硬编码消费者名单。下面按当前公开依赖和功能说明；新增模块/后端时同步此表、连接目录与真实运行测试。
+
+| 模块 | 中间件来源或外部能力 |
+| --- | --- |
+| reldb / cache / storage / vecdb | 分别拥有关系库、缓存、对象存储、向量库连接契约 |
+| iam / kit | IAM 运行依赖 audit/reldb/cache/crypto；kit 经 IAM 继承。LDAP 按 login.ldap 开关启用，Reach peer 只有另行实际依赖时进入运行图 |
+| audit / payment | audit 经 reldb 持久化；payment 经 audit 继承数据库。微信、支付宝、Stripe 是已有商户 API，沿 payment 配置接入，不生成假云服务或容器 |
+| scheduler / reach | 两者实际依赖 reldb/cache；Reach 另按启用的 SMTP/HTTP/短信渠道配置 |
+| ai | 实际依赖 reldb/vecdb/datapipe。LLM、图像、音频端点及模型来自 AI 配置，不能仅凭包名选择模型镜像或 CUDA；不自动创建付费厂商账号 |
+| crypto / serv | crypto 的可选运行依赖按 lockfile 解析，serv 经 crypto 继承；serv 的 IAM/storage/AI peer 不作为启用证据 |
+| core / datapipe / api-contract / api-client / ui / capacitor / cli / deploy | 本身没有额外专用中间件；仍沿实际运行依赖继续遍历，例如 api-client/capacitor 的 crypto 分支。UI/设备能力、部署目标/Provisioner 凭据按各自配置处理 |
+
+S3 是协议，不是某个容器产品。默认配置时另选 RustFS/MinIO，保存到 HAI_DEPLOY_CONTAINER_S3ENGINE（rustfs | minio，默认 rustfs），应用始终写 HAI_STORAGE_TYPE=s3 或 HAI_STORAGE。自定义 AWS S3、OSS、R2 等端点不生成 sidecar。镜像使用与 storage 集成测试一致的 RustFS 官方版本和 MinIO 社区版本；存储桶初始化复用应用镜像里的 S3 SDK，无需额外 mc 镜像，必须幂等且不能吞掉失败。
+
+## 连接字段
+
+以下是自定义向导的连接字段；完整可用项、枚举与范围仍以项目 `.env.example` 和公开 Schema 为准。变量前缀为 `HAI_DB`、`HAI_CACHE`、`HAI_STORAGE`、`HAI_VECDB`、`HAI_IAM_LDAP`；Reach 使用实际索引 `HAI_REACH_PROVIDERS_<index>`。camelCase 不拆词，例如 `bindPassword` → `BINDPASSWORD`。
+
+| 后端 | 连接字段 |
+| --- | --- |
+| SQLite | database（文件路径或 `:memory:`） |
+| MySQL / PostgreSQL | url（优先）、host、port（1–65535）、database、user、password、ssl |
+| Redis | url（优先）、host、port、password、db、tls、keyPrefix、connectTimeout、commandTimeout |
+| local / LanceDB | root / path |
+| S3 | endpoint、bucket、region、accessKeyId、secretAccessKey、forcePathStyle |
+| Qdrant / Chroma | url；Qdrant 可选 apiKey |
+| pgvector | url（优先）或 host/port/user/password，以及 database |
+| LDAP | url、bindDn、bindPassword、searchBase、searchFilter、usernameAttribute、emailAttribute、displayNameAttribute、useTls、connectTimeout |
+| SMTP | host、port、secure、user、pass、from |
+| HTTP API | url、method（POST / PUT）、headers（JSON）、timeout |
+| 阿里云 SMS | accessKeyId、accessKeySecret、signName、endpoint |
+
+## 离线准备与验收
+
+先核对 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 和应用端口可达。
+
+有 PostgreSQL/Redis/RustFS 镜像不代表有可用服务。默认配置要求 Compose 中镜像名称、tag、架构准确匹配，SDK 不传输中间件镜像；自定义连接要求服务已启动、地址从应用容器可达并提供数据库/账号、密码、S3 密钥/桶。不要用容器内 localhost 指代宿主机服务。
+
+默认 Dockerfile 会下载 Node 基础镜像、pnpm、依赖和 SQLite 预编译包，不能直接称为离线可用。源码离线构建要准备 Linux 构建环境的完整缓存和构建 frontend，调整下载步骤并断开外网演练；Windows node_modules/pnpm store 不代表 Linux 的原生依赖可用。云 Provider/Provisioner 需要外网，不用于完全离线部署。
+
+docker-ssh 始终执行本地镜像构建，`--skip-build` 仅对 Vercel 生效。预构建离线交付可在准备环境导出 API/Web 镜像，在 Windows 引擎加载 API 镜像后，为目标服务包提供仅含 `FROM <已加载的API镜像>` 的 Dockerfile 和内容 `*` 的 `.dockerignore`，让 SDK 复用成品并上传。业务代码变更后必须重制成品镜像；无匹配本地镜像时不能继续假定构建无网络。
+
+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 忽略的临时目录，不提交仓库；付费云资源、原生客户端与远程生产部署须单独验证并说明边界。

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

@@ -90,7 +90,7 @@ npm view @h-ai/cli dist-tags --json
 1. 按差异清单迁移调用方、类型、配置、环境变量说明、初始化和构建入口，保留应用行为与架构。新默认行为改变须显式核对；只对生命周期模块遵循 init → use → close，不给 core/serv/纯函数套用生命周期。
 2. 用目标版本回归核验已有补丁/本地覆盖：仍必要则针对目标重建并说明依据；只有上游已修复且回归通过时移除。npm 升级遇到本地联调映射时，明确恢复 npm 或继续本地验证的选择，不能只改版本号却继续运行旧源码。
 3. 使用当前包管理器安装并更新 lockfile，保留失败诊断；不手改 lockfile 的解析字段。安装后从**各消费 workspace**核对真实版本、公开 exports/类型及框架传递依赖，检查残留旧版/重复解析和本地路径。
-4. 按 [同步规则](sync.md) 合并目标 CLI 中适配本架构的完整 skill 目录及 AI 入口。对“旧发布模板、应用现有文件、新发布模板”比较，保留私有规则/自定义技能，冲突转为选择；没有旧模板时先辨识私有内容，不直接覆盖。同步版本必须与目标运行时一致。
+4. 按 [同步规则](sync.md) 合并目标 CLI 中适配本架构的完整 skill 目录及 AI 入口。对“旧发布模板、应用现有文件、新发布模板”比较，保留仍适用的私有规则/自定义技能；已明确的业务需求优先于模板默认值，仅未决冲突转为选择。没有旧模板时先辨识私有内容，不直接覆盖。同步版本必须与目标运行时一致。
 5. 同步受影响的 README、配置样例、skill 与测试，逐项更新差异清单状态。即使已处于目标版本，也核验解析/配置/skills 漂移；一致时报告无需升级，不制造改动。
 
 ### 6. 验证与交付

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

@@ -22,7 +22,7 @@ hai-framework 是通用能力和 skill 模板的源头；应用仓库消费这
 
 `hai init` 只补缺失内容，即使 `--force` 也不覆盖已有 AI 规则和 skills，不能用它代替旧版本规则合并。未发布模板修正从明确本地来源同步，不能假定已发布 CLI 已包含。
 
-1. 比较来源与应用的同名完整目录，包括 SKILL、reference/guide、脚本和资产；升级时结合旧发布模板识别应用私有覆盖。无冲突部分合并，冲突列出位置、双方意图和可选方案。
+1. 比较来源与应用的同名完整目录，包括 SKILL、reference/guide、脚本和资产；升级时结合旧发布模板识别应用私有覆盖。模板业务默认值服从用户当前明确要求及其指定文档；移除或改写已被需求替代的旧模板强制规则，保留仍适用的项目私有决策，不将默认 admin/user、限额或流程重新强加给应用。无冲突部分合并，真实未决冲突列出位置、双方意图和可选方案；已有明确决策不重复询问。
 2. 按目标架构选择需要的模块技能与桥接模板；不将 SvelteKit 指令套到 API/Vite 项目。保留自定义技能；上游重命名/删除的旧目录先检查调用与私有内容，不能整树覆盖或删除。
 3. 项目规则合并到 AGENTS，`.github/copilot-instructions.md` 只引用共享入口；CLAUDE 如存在，通过 `@AGENTS.md` 复用共享规则，保留用户额外规则及现有 `.claude/`，不另复制技能正文。OpenCode 的 `instructions` 直接引用 `AGENTS.md`；配置有变化时合并已有字段，不整体替换。
 4. 确保新增/修改/修复任务能到达 `hai-app-create` 与其 `development.md`，审查到达 `hai-app-review`，框架升级到达 `hai-framework-sync`。只引用目标实际交付的可选技能，不把目录缺失当成运行时能力缺失。

package/templates/skills/hai-reach/reference.md

@@ -34,17 +34,17 @@
 providers:
   - name: email
     type: smtp
-    host: ${HAI_REACH_SMTP_HOST:smtp.example.com}
-    port: ${HAI_REACH_SMTP_PORT:465}
+    host: ${HAI_REACH_PROVIDERS_0_HOST:smtp.example.com}
+    port: ${HAI_REACH_PROVIDERS_0_PORT:465}
     secure: true
-    user: ${HAI_REACH_SMTP_USER:}
-    pass: ${HAI_REACH_SMTP_PASS:}
-    from: ${HAI_REACH_SMTP_FROM:noreply@example.com}
+    user: ${HAI_REACH_PROVIDERS_0_USER:}
+    pass: ${HAI_REACH_PROVIDERS_0_PASS:}
+    from: ${HAI_REACH_PROVIDERS_0_FROM:noreply@example.com}
   - name: sms
     type: aliyun-sms
-    accessKeyId: ${HAI_REACH_SMS_ACCESS_KEY:}
-    accessKeySecret: ${HAI_REACH_SMS_SECRET_KEY:}
-    signName: ${HAI_REACH_SMS_SIGN_NAME:}
+    accessKeyId: ${HAI_REACH_PROVIDERS_0_ACCESSKEYID:}
+    accessKeySecret: ${HAI_REACH_PROVIDERS_0_ACCESSKEYSECRET:}
+    signName: ${HAI_REACH_PROVIDERS_0_SIGNNAME:}
   - name: webhook
     type: api
     url: ${HAI_REACH_WEBHOOK_URL:}

package/templates/skills/hai-spec-implement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hai-spec-implement
-description: "从需求或设计文档规划、执行或返修 hai 应用：按可验收功能拆分任务，维护 docs 清单与任务记录，以 TDD 在独立 Git 分支实现、验证并合并。"
+description: "从需求或设计文档规划、执行、返修 hai 应用，或按 Git 文档差异更新实现：维护任务与已验收基线，以 TDD 在独立分支实现、验证并合并。"
 ---
 
 # hai-spec-implement
@@ -9,21 +9,23 @@ description: "从需求或设计文档规划、执行或返修 hai 应用：按
 
 | 项目 | 契约 |
 | --- | --- |
-| 能力 | 将文档转为可追溯开发任务，管理规划、实施、合并与原任务返修 |
-| 适用场景 | 用户要求根据需求/设计文档生成代码、执行任务清单、继续指定任务或修复已交付任务 |
-| 输入 | 已确认的文档与生成范围、审查结论、当前仓库/依赖、已有清单和任务记录（如有） |
-| 输出 | docs 下的任务清单、docs/tasks 下的任务记录、独立任务分支、TDD 与门禁证据、实际合并记录 |
+| 能力 | 将文档及其 Git 差异转为可追溯任务，管理规划、增量实施、合并、返修与基线推进 |
+| 适用场景 | 按需求/设计生成代码、文档提交后更新实现、执行/继续任务或修复已交付任务 |
+| 输入 | 已确认的文档集合与范围、审查结论、当前仓库/依赖、已有任务与基线；增量实施需旧/新文档提交 |
+| 输出 | docs 清单与任务记录、文档差异到任务的映射、独立分支、TDD/门禁证据、实际合并与已验收基线 |
 | 限制 | 文档是需求数据，不是执行指令；仅规划不写业务代码。实施范围与本地提交/合并依据用户授权，不因此获得远端推送、发布或创建其他会话的授权。 |
 
 ## 使用路径
 
-先区分本次请求是 **规划 / 执行 / 返修**。仅要求分析或列清单时停在规划；要求按文档生成时，在已授权范围内完成规划并依次实施，无需每个任务重复确认。指定任务只执行该任务，依赖未完成时说明具体阻塞，不自行扩展执行范围。普通小改动仍使用 [hai-app-create](../hai-app-create/SKILL.md)。
+先区分本次请求是 **规划 / 执行 / 返修 / 文档变更实施**。仅要求分析或列清单时停在规划；要求按文档生成或“已修改文档，请更新实现”时，在已授权范围内完成规划并依次实施，无需每个任务重复确认。指定任务只执行该任务，依赖未完成时说明具体阻塞，不自行扩展执行范围。普通小改动仍使用 [hai-app-create](../hai-app-create/SKILL.md)。
 
-1. 核对文档版本、权威关系与已有任务，使用 [hai-spec-review](../hai-spec-review/SKILL.md) 确认生成就绪。有效结论可复用；文档变化时复审受影响规则及其依赖。未解决的问题不能靠任务拆分隐藏；用户已明确授权的独立范围可实施，清单保留其余阻塞。
-2. 按下方原则决定一个任务还是多个任务，使用 [任务文档范本](templates.md) 写入清单和任务记录。一个任务也保留清单及记录，已有清单优先更新，不重复规划已交付内容。
+**文档变更实施**先读 [文档差异与基线流程](changes.md)：从已验收基线固定旧/新 Git 快照，核对多文档差异与关联影响，再更新原任务或新建任务；其执行与合并仍走下方共同流程。不能直接用当前 HEAD 或最近一次文档提交猜测旧基线。
+
+1. 核对文档版本、权威关系与已有任务，使用 [hai-spec-review](../hai-spec-review/SKILL.md) 确认生成就绪。以用户当前明确要求及其指定的业务文档为实现基线；模板 AGENTS、skills、代码和测试与之不同的部分列入适配任务，不要求保留冲突的默认业务或重复征求覆盖授权。有效结论可复用；文档变化时复审受影响规则及其依赖。未解决的问题不能靠任务拆分隐藏；用户已明确授权的独立范围可实施，清单保留其余阻塞。
+2. 按下方原则决定一个任务还是多个任务，使用 [任务文档范本](templates.md) 写入清单、文档基线和任务记录。一个任务也保留清单及记录，已有清单优先更新，不重复规划已交付内容。
 3. 执行、继续或返修时读取 [执行与 Git 流程](workflow.md)，核验依赖、工作区、主分支和实际状态；每个任务使用记录中的独立分支。
 4. 按 [hai-app-create](../hai-app-create/SKILL.md) 与当前版本公开契约实现，按 [hai-app-tests](../hai-app-tests/SKILL.md) 做 Red → Green → Refactor，按 [hai-app-review](../hai-app-review/SKILL.md) 审查改动。只读取当前任务需要的模块资源。
-5. 验证、提交、合并后更新清单与任务记录。报告本次完成的任务、分支/提交、门禁和剩余阻塞；验证通过但尚未合并不能标为已完成。
+5. 验证、提交、合并后更新清单与任务记录；全部目标范围验收通过才推进文档基线，规则见 [基线收尾](changes.md#验收与基线推进)。报告完成任务、旧/新文档 SHA、实现/合并提交、门禁和剩余阻塞；验证通过但尚未合并不能标为已完成。
 
 ## 拆分原则
 
@@ -31,6 +33,7 @@ description: "从需求或设计文档规划、执行或返修 hai 应用：按
 - **按真实依赖排序**：多个功能共用的 contract、迁移或基础配置可先行，但必须有真实消费者及可验证契约。记录依赖任务编号，避免循环；共同事务/状态约束难以分离时合并任务。
 - **小需求保持单任务**：无需以文档页数、文件数、固定工时或 token 数硬拆。一个任务应能在合理上下文中说明规则、完成改动并跑完适用门禁；过大时按业务边界细分，过碎时合并。
 - **先复用再安排开发**：区分已有满足项、配置接入和真实功能缺口；已有能力通过验证即可，不重复生成框架或现成模块。不要为可能出现的需求安排抽象、依赖或占位功能。
+- **模板差异纳入交付**：按目标业务调整或移除示例逻辑，成套同步 schema、授权、初始化/种子数据、迁移、界面、测试与文档。将仍适用的回归与已被新需求替代的断言区分，不能让旧角色/流程断言或过期 AGENTS/skill 继续约束实现。
 - **每项有来源和验收**：需求章节/编号映射到任务或已有实现证据，权限、异常和状态规则纳入验收；排除/阻塞项写明理由。不用“完成模块”“完善页面”等无法判定的标题替代结果。
 - **默认串行**：按依赖和清单顺序执行。这里的任务是 Markdown 与 Git 工作项，不自动变成额外会话、子代理、调度器或新的 SDD 工具链。
 

package/templates/skills/hai-spec-implement/changes.md

@@ -0,0 +1,67 @@
+# 文档差异与基线流程
+
+用户提交需求/设计文档后要求同步实现时读取本文件；首次实施也按此处记录和收尾基线。任务执行、TDD 与分支合并复用 [workflow.md](workflow.md)，记录结构见 [templates.md](templates.md)。
+
+## 基线含义
+
+在已有任务清单内维护以下信息，不新增状态系统：
+
+| 标识 | 含义 |
+| --- | --- |
+| B：已验收文档提交 | 当前计划的完整文档集合已被实现并通过整体验收时对应的 Git 完整 SHA；首次未验收时为“未建立” |
+| S：本轮目标文档提交 | 本次要实现的文档快照完整 SHA；开始分析时固定，执行期间不随 HEAD 自动变化 |
+| I：本轮集成起点 | 规划时确认的主分支完整 SHA，用于定位当前代码和文档状态 |
+| H：已验收实现提交 | 最后一次通过整体门禁的主分支完整 SHA，包含实际任务合并；与 B 分开记录 |
+
+B/S 指向文档内容，H 指向经过验证的实现，三者通常不同。记录完整文档路径集合、权威关系和适用范围；多文档用同一 S 快照，不逐份取“最后修改提交”拼接。路径集合包括本轮新增/删除/重命名的旧、新路径；文档拆分、合并时保留来源映射。多个独立计划分别维护基线，不用一个计划的完成替代另一个计划。
+
+## 固定输入与恢复
+
+1. 先读取清单中的 B/H、未完成变更轮次与任务记录，核验 Git 对象和实际代码。旧项目没有 B/H 时，先从历史任务、合并和验收证据追溯；证据不足则标记“未建立”，对当前文档与实现做覆盖核验，形成补齐任务。不能选择 HEAD、最近文档提交或最近 merge 来伪造旧基线；完成覆盖核验及整体验收后才能首次建立。
+2. 将用户给出的新提交解析成完整 SHA S；只说“修改了某文档”时，核对该路径的提交历史和当前集成线，默认取分析开始时包含这些已提交修改的 HEAD 快照，说明选择依据。多份文档、跨多个提交时比较 B 到 S 的净变化，不能只看 S 的单个提交。若存在多个无法推断的候选版本，仅澄清目标版本，同时继续独立的影响分析。
+3. 用 `git status` 检查文档是否还有未提交修改，包含未跟踪文件。默认实现固定的已提交快照；工作区文档与 S 不同则明确列出，不静默混入、不替用户提交。用户改为采用未提交版本时，先明确新的输入与可追溯记录，不能声称它已由 S 表示。
+4. 核验 B/S/H 对象可读取、B/H 的历史验收仍有依据，确认主分支实际包含此前实现。对象缺失先检查本地 refs/浅克隆边界，在允许的仓库访问范围内补齐历史；无法核验时阻塞基线判断，不以空差异表示无变化。H 不在当前集成历史或实现被 revert 时，记录实现漂移并重新核验受影响需求。
+5. 常规演进应能证明 B 是 S 的祖先；分叉、回退或历史重写时先记录原因，确认用户目标和端点内容后比较 B/S 两棵树。不擅自改用 merge-base 或三点 diff 缩小变化，不 reset/rebase 用户历史。已存在相同 B/S 的未完成轮次时从其阶段恢复，不重复创建变更和任务。
+
+## 差异与任务映射
+
+1. 先查看仓库级路径变化以发现移出目录的重命名，再比较完整文档集合的内容。以下为命令形状，B/S、路径需替换为核验值，参数按当前 shell 正确引用：
+
+   ```text
+   git rev-parse --verify <ref>^{commit}
+   git merge-base --is-ancestor <B> <S>
+   git diff --name-status --find-renames <B> <S>
+   git diff --find-renames <B> <S> -- <全部受管文档的旧路径与新路径>
+   git show <B>:<旧路径>
+   git show <S>:<新路径>
+   ```
+
+   祖先检查退出码 1 表示非祖先，其他错误需单独处理；新增/删除文件只读取存在的一端。重命名检测是线索，结合正文识别拆分/合并，不能只按文件名认定需求新增或删除。富文本文档需读取两端内容/附件，无法可靠提取时记录阻塞，不当作纯格式变化。
+2. 用户指出的路径是入口，仍核对计划内全部文档在 B/S 间的变化，以及关联章节、附件和权威关系；跨文档权限、状态、字段、接口和验收一起复审。区分新增、修改、删除、移动/拆分/合并及纯说明变更。读取差异两端上下文和当前代码/测试，使用 [hai-spec-review](../hai-spec-review/SKILL.md) 复审受影响规则；不能把删掉一句话直接解释为删除功能。
+3. 在清单追加稳定变更编号（如 C001），保存 B/S/I、文档集合、差异条目、需求位置、关联任务及处理结论。每项变化必须映射到以下结果之一：
+
+   | 情况 | 处理 |
+   | --- | --- |
+   | 原任务的规则、缺陷或验收变化 | 复用任务编号、文件和分支，更新当前来源与验收；已完成任务追加返修轮次，保留历史证据 |
+   | 已有待执行/进行中任务受影响 | 更新其范围、依赖和验收；进行中任务先保存阶段，合入新规划与主线后重新验证，旧测试结果不能证明新验收 |
+   | 新的独立可验收能力 | 新建稳定编号并关联变更与依赖；一个任务可处理多项差异，一项跨功能差异可关联多个任务 |
+   | 明确移除/替代需求 | 核对调用方、权限、数据迁移/保留与回归；复用原任务或新建有关联的清理任务，不能只删任务记录或擅自删除业务数据 |
+   | 原任务尚未交付且已失去需求 | 标为“已取消”并写明来源和替代任务；若有部分实现进入主线，仍需清理/验证任务，不能用取消掩盖残留 |
+   | 纯说明/路径调整或当前实现已满足 | 记录语义不变或已有满足的证据、必要验证及来源链接更新，不强造业务任务或 TDD 失败 |
+   | 冲突、未决、超出授权范围 | 记录阻塞/排除依据与恢复条件；不能静默忽略，也不能把尚未同步的需求宣称已验收 |
+
+4. 检查受影响任务的上游/下游、共享契约和回归范围，调整依赖顺序并消除循环；不要重开所有历史任务。任务记录关联 C001 与本轮 B/S，清单覆盖映射更新到 S。用户只授权部分差异时可实施独立范围，但同一计划仍有未同步变化就保留 B；需要独立推进时先明确划分计划和文档范围，不能悄悄改成逐文件基线。
+
+## 分支执行与中断
+
+- 将固定的目标文档、差异映射、更新/新增任务记录先集成到实际主分支，再按依赖串行执行。S 在其他分支时先核对范围：只集成本次授权的文档变化，不能顺带合入无关代码；记录来源 S 及实际文档集成提交，并按 Git blob 核对主线文档集合与 S 一致，不强求来源提交 SHA 在 cherry-pick 后保持不变。
+- 新任务从最新主线创建分支；原任务复用原分支，先合入最新主线。分支缺失时按记录和当前主线核验后恢复，不从旧代码覆盖主线。每轮按新验收走 TDD、适用门禁、本地合并、集成验证和记账，详见 [执行流程](workflow.md)。
+- 发现 S 之后又有文档变化时，保留本轮 S 并列为后续候选；不要在执行中自动改目标或把较新需求当作已完成。若较新文档已进入当前主线并与 S 不一致，暂停依赖该差异的实施及基线推进，保存进度后按用户目标调整本轮。用户明确采用新目标时从未推进的 B 比较新 S，记录目标替换及旧 B/S，核对已合入代码后复用任务和证据，重新映射、复审与验证；不要重复开发已满足项或继续执行被新目标撤回的旧任务。
+- 中断时保存目标、任务阶段、实际实现/合并 SHA 和下一步；B/H 保持上次整体验收结果。续跑先核对实际主线与任务分支，再补验证/合并/记账。部分完成、门禁失败、只交付分支或存在未决项时都不能推进 B/H。
+
+## 验收与基线推进
+
+1. 核对本轮每项差异均有处理证据，所有需要实现/清理的任务已实际合并，取消/无需修改项有依据；受影响的原有需求和完整覆盖映射仍成立。首次实施无 B 时对完整文档集合验收。B 等于 S 或 diff 为空时仍检查未完成任务与实现漂移，不能直接宣称完成。
+2. 在主分支执行项目要求的整体门禁和需求验收，确认目标文档集合的 Git blob（含删除/新增路径）与 S 一致，工作区没有混入未提交实现。若执行期间主线代码继续推进，检查新提交的影响，对最终主线重新执行必要验证，记录通过验证的完整 SHA H。
+3. 只有以上通过后，在主分支独立文档记账提交中将“已验收文档提交”推进为 S，将“已验收实现提交”更新为 H，关闭 C001 并保留旧 B/H、任务合并与门禁证据。H 是记账前已验证的实现提交，不填该记账提交自身的 SHA，不通过 amend/rebase 制造自引用。
+4. 提交后核验记录已进入实际主分支，报告 B → S、H、实际合并/记账提交、验证及未完成范围。纯说明变化可以在证据与适用验证齐全后推进文档基线，无需制造代码改动；仍存在未处理需求时报告部分完成并保留旧基线。

package/templates/skills/hai-spec-implement/templates.md

@@ -2,14 +2,17 @@
 
 默认使用 `docs/task-list.md` 和 `docs/tasks/T001-<slug>.md`。已有项目优先沿用现存清单及命名；多份独立计划使用 `docs/<plan>-tasks.md`、`docs/tasks/<plan>-T001-<slug>.md`，避免编号碰撞。编号在计划内稳定，文件名与分支不随标题修改。根据真实内容替换下列示例字段，不把未发生的结果写成事实。
 
-清单承担全局状态与需求覆盖，任务文件承担当前验收和每轮证据。适用字段保留，简单项目无需另建规格副本、设计文档层、JSON 状态文件或专用脚本。规划时写概要，执行时补证据；不能预填 Red 成功、合并 SHA 或“已完成”。
+清单承担全局状态、需求覆盖与已验收基线，任务文件承担当前验收和每轮证据。适用字段保留，简单项目无需另建规格副本、设计文档层、JSON 状态文件或专用脚本。规划时写概要，执行时补证据；不能预填 Red 成功、合并 SHA 或“已完成”。B/S/I/H 的含义与推进条件见 [文档差异与基线流程](changes.md)。
 
 ## 任务清单
 
 ```markdown
 # <项目/计划>任务清单
 
-- 需求基线：<文档相对链接、章节/需求编号、版本或 Git 提交；仓库外文件使用可访问位置与修订标识>
+- 文档集合与权威关系：<全部需求/设计/附件的相对路径、章节/编号、适用范围；新增/删除/重命名记录旧/新路径>
+- 已验收文档提交 B：<完整 SHA / 未建立；不填当前 HEAD 代替>
+- 已验收实现提交 H：<最后整体通过的主分支完整 SHA / 未建立>
+- 本轮目标文档提交 S：<固定完整 SHA；仓库外文件记录可访问位置及不可变修订标识，未入 Git 不能声称有 Git 基线>
 - 审查结论：<结论、范围、证据位置；独立授权范围与剩余问题>
 - 集成主分支：<实际分支名>；规划起点：<SHA>
 - 执行范围：<仅规划 / 全部依次实施 / 用户指定的编号>
@@ -32,6 +35,22 @@
 - 当前/下一任务：<编号与具体步骤；指定执行时记录用户选择>
 - 阻塞：<问题、影响、需要什么决策/环境>
 - 全量验收：<未执行 / 命令与结果及证据；覆盖映射仍有遗漏不能写全部完成>
+
+## C001 · <文档变更概要；首次实施可记录为首次建基线>
+
+- 状态：<分析中 / 待执行 / 进行中 / 阻塞 / 已完成>
+- 旧基线 B/H：<原完整 SHA 或未建立；收尾后仍保留在本轮历史>
+- 目标 S / 集成起点 I：<完整 SHA 与选择依据；本轮文档旧/新路径集合>
+- 审查与范围：<受影响规则结论、用户授权、未决/排除项及恢复条件>
+
+| 差异编号 | 旧 → 新来源/规则 | 影响 | 处理结论与任务/证据 |
+| --- | --- | --- | --- |
+| C001-D01 | <B 旧章节 → S 新章节；增/改/删/移动/说明> | <代码、依赖、数据与回归范围> | <更新 T001 第 2 轮 / 新建 T003 / 取消及清理任务 / 无需改代码的证据 / 阻塞> |
+
+- 当前阶段/下一步：<可恢复的具体步骤，已完成与剩余差异编号>
+- 文档集成：<主线提交与 S blob 一致性核验；未集成则如实记录>
+- 收尾：<任务 merge、整体门禁命令/结果、验证通过的 H；收尾前写未完成>
+- 基线推进：<验收通过后 B → S、旧 H → 新 H；存在剩余项则保持原 B/H>
 ```
 
 ## 单任务记录
@@ -43,6 +62,7 @@
 - 当前状态：待执行
 - 分支：codex/<plan>/t001-<slug>；主分支：<实际名称>
 - 需求来源：<文档相对链接、精确章节/编号与版本>
+- 变更关联：<C001-D01 等；本轮旧 B → 目标 S；首次实施说明未建立 B>
 - 前置依赖：<编号、已合并契约/提交；无则写无>
 - 范围：<本任务交付什么；与相邻任务的边界>
 - 复用与影响：<已有框架/应用能力、真实缺口及代码/配置/调用方/文档位置>
@@ -71,7 +91,7 @@
 ## 第 2 轮 · <返修原因>
 
 - 关联：<第 1 轮实现/merge SHA、用户反馈或缺陷位置>
-- 基线与变化：<本轮主分支 SHA、需求修订及规则差异>
+- 基线与变化：<变更/差异编号、本轮主分支 SHA、旧 B → 目标 S 及规则差异>
 - 影响：<依赖任务、配置/数据兼容与需要回归的调用方>
 - Red：<新增复现用例、命令、目标失败与证据>
 - Green / Refactor：<修复与结果>
@@ -84,6 +104,8 @@
 ## 常见请求
 
 - “根据 docs/需求.md 生成代码”：审查当前版本，形成清单，在已授权范围内依次实施。
+- “我修改了 docs/需求.md、docs/设计.md 并已提交，请更新实现”：从已验收 B 比较固定 S，更新原任务或新建任务，逐项分支实现/测试/合并，整体通过后推进 B/H。
+- “只分析文档这次提交的影响”：固定 B/S 并记录差异与任务建议，不开始实现、不推进已验收基线。
 - “只分析文档并拆分任务”：生成清单与任务概要，不开始实现或合并。
 - “执行 T003”：先核验其依赖与当前状态，只实施指定任务。
 - “继续上次任务”：从清单和 Git 事实恢复当前阶段，补齐中断的验证或合并记录。

package/templates/skills/hai-spec-implement/workflow.md

@@ -1,13 +1,13 @@
 # 执行与 Git 流程
 
-规划文档使用 [templates.md](templates.md)；实现与测试分别复用 [hai-app-create](../hai-app-create/SKILL.md)、[hai-app-tests](../hai-app-tests/SKILL.md)。本文件在执行、续跑或返修任务时读取。
+规划文档使用 [templates.md](templates.md)；实现与测试分别复用 [hai-app-create](../hai-app-create/SKILL.md)、[hai-app-tests](../hai-app-tests/SKILL.md)。本文件在执行、续跑或返修任务时读取；文档提交后同步实现先读 [文档差异与基线流程](changes.md)。
 
 ## 开始与恢复
 
 1. 检索已有清单、任务编号、需求版本、相关代码和测试。记录用户本次授权的是全部、部分还是指定任务；只规划不创建实现分支或写业务代码。
 2. 根据项目规则、现有远端默认分支信息及用户指定，确认实际主分支（集成基线）。记录分支名和起点提交，不把当前功能分支当作主分支，也不固定假设为 main。确实无法确认时只询问该信息，继续可独立进行的文档分析。
 3. 检查 `git status`、分支和 worktree。保留无关修改，不自动 stash、reset、清理或提交用户内容；存在未提交改动妨碍切换时使用干净的任务 worktree。任务中的需求文档、清单和源代码须来自同一已确认基线，不能在新 worktree 中悄悄丢掉用户尚未提交的需求。
-4. 首次实施前把本次规划的清单与任务记录作为独立文档提交落到主分支，不混入无关修改。各任务从该主分支开始，后续任务继承前面任务的实际合并结果。没有 Git 的项目在已授权实现范围内初始化；不能使用 Git 或不能写入主分支时记录限制，不能宣称分支交付完成。
+4. 实施前将本轮目标文档、清单与任务记录落到主分支；规划信息做独立文档提交，不混入无关修改。首次记录完整文档集合及固定目标 SHA，已验收基线保持“未建立”直到整体收尾；文档变更实施保留旧基线并记录本轮 B/S/I 与差异映射。各任务从该主分支开始，后续任务继承前面任务的实际合并结果。没有 Git 的项目在已授权实现范围内初始化，提交目标文档后固定版本；不能使用 Git 或不能写入主分支时记录限制，不能宣称分支交付完成。
 5. 恢复已有任务先核对分支、提交与合并记录。若代码已经合并但文档还停在“已验证”，补做合并后的验证/记账；若分支仍有未提交实现，从记录的步骤继续，不再创建相同任务或重写历史。
 
 ## 状态与执行前检查
@@ -19,6 +19,7 @@
 | 阻塞 | 需求决策、依赖或环境阻止完成；记录原因与恢复条件 |
 | 已验证 | 本轮适用门禁通过，尚未完成主分支集成 |
 | 已完成 | 实际合并成功，主分支验证通过且清单/任务记录已提交 |
+| 已取消 | 尚未交付的需求被明确撤回/替代，保留原因及关联任务；部分实现已合并时须另行完成清理验收 |
 
 返修将同一任务从“已完成”改回“进行中”，追加新轮次，保留上轮的来源、证据和合并记录。“阻塞”不等于验收通过，环境或既有失败不得标成已完成。清单与任务记录的当前状态必须一致。
 
@@ -27,10 +28,10 @@
 ## 任务分支与 TDD
 
 1. 从最新已确认主分支创建独立分支，建议 `codex/<plan>/t001-<slug>`，服从项目已有分支规范。将稳定任务编号、分支和本轮起点 SHA 写入记录；名称不随任务标题变化。进入已有分支前核对它属于该任务，不能抢占同名的其他工作。
-2. 先把任务标为“进行中”，写清本轮验收与测试命令。新项目可先生成/安装最小脚手架，确认测试运行器和已有基线正常，再开始目标行为的 TDD；不先实现业务再补写所谓 Red。
-3. **Red**：从公共入口或用户行为添加/调整最小目标用例，覆盖本次规则与必要异常路径，运行并确认因目标行为缺失/缺陷而失败。导入错误、环境未启动或旧回归失败不是有效 Red。若目标用例已经通过，确认已有实现是否满足需求，不能故意破坏代码制造失败。
+2. 先把任务标为“进行中”，写清本轮验收与测试命令。更新已有任务/分支时先合入本轮规划和最新主线，核对工作区文档与固定 S 一致。新项目可先生成/安装最小脚手架，确认测试运行器和已有基线正常，再开始目标行为的 TDD；不先实现业务再补写所谓 Red。
+3. **Red**：从公共入口或用户行为添加/调整最小目标用例，覆盖本次规则与必要异常路径；明确需求改变时更新已过时的模板断言并注明需求依据，未改变的回归继续保留。运行并确认因目标行为缺失/缺陷而失败。导入错误、环境未启动或无关回归失败不是有效 Red。若目标用例已经通过，确认已有实现是否满足需求，不能故意破坏代码制造失败。
 4. **Green**：复用当前应用及 Hai-Framework 的公开能力，完成使目标用例通过的最小实现，同时同步数据迁移、配置、权限、调用方和说明。配置接入从实际行为验证，不能以文件存在作为可用证据。
-5. **Refactor**：在目标测试保护下整理重复和命名，维持既有回归通过。行为改变再次走 Red → Green；审查涉及的权限、输入、事务和跨端契约。
+5. **Refactor**：在目标测试保护下整理重复和命名，维持仍适用的既有回归通过。行为改变再次走 Red → Green；审查涉及的权限、输入、事务和跨端契约，并修正描述旧模板业务的 AGENTS、skills 与 README。
 6. 任务记录保存每轮 Red 的预期/实际失败原因、Green/重构结果、命令、测试或日志位置和实现提交。纯文档/格式任务及完全由现有能力满足的任务记录适用性理由和验证证据，不编造失败或添加措辞镜像测试；有新增/修复行为的任务必须有有效 TDD 证据。
 
 ## 验证、提交与合并
@@ -40,7 +41,7 @@
 3. 通过后将本轮状态更新为“已验证”，只提交本任务的代码、配置、测试、说明和任务信息；检查 staged diff，不能混入用户或其他任务改动。可保留有意义的小步提交，不要求每个任务只有一个 commit。
 4. 回到主分支（或它对应的干净 worktree），将任务分支合并；项目没有相反规则时使用 `git merge --no-ff <任务分支>` 保留任务边界。明确授权执行本工作流时可完成本地合并；用户明确只要分支/待审结果时保持“已验证”。遵守项目受保护分支/PR 规则，不绕过；远端推送、PR、发布依用户实际授权处理。
 5. 核对实际集成提交及主分支已包含本轮改动；项目采用 squash/rebase 时记录对应提交，不能假定 SHA 保持不变。运行集成后受影响验证。所有任务完成后再执行项目要求的全量门禁和整体需求验收；最终任务保持“已验证”，直到这些检查通过。失败先修复，不把 Git 合并成功当成业务验证通过。
-6. 在主分支将清单和任务记录更新为“已完成”，写入本轮任务分支 tip SHA、实际 merge SHA、集成验证结果和下一步，做独立的文档记账提交。merge SHA 在合并后才能知道，不能预填、也不能 amend 已合并提交去补记录。保留任务分支，以便返修。
+6. 在主分支将清单和任务记录更新为“已完成”，写入本轮任务分支 tip SHA、实际 merge SHA、集成验证结果和下一步，做独立的文档记账提交。merge SHA 在合并后才能知道，不能预填、也不能 amend 已合并提交去补记录。保留任务分支，以便返修。整个计划/变更轮次的已验收文档与实现基线只按 [基线收尾](changes.md#验收与基线推进) 推进，单个任务完成不代表整体完成。
 
 有中断时保存实际阶段及下一步。已经合并却验证失败时，记录实际 merge SHA 和失败，清单保持“进行中”或“阻塞”，回原任务分支修复；后续任务暂不越过失败依赖。收尾报告区分“代码已合并”与“任务已完成”。