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

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

@@ -1,6 +1,6 @@
 ---
 name: hai-datapipe
-description: "使用 @h-ai/datapipe 清洗文本、分块并组合 RAG 入库管线。"
+description: "使用 @h-ai/datapipe 清洗和分块文本、组合预处理管线；用于 RAG 入库前处理，不负责 embedding。"
 ---
 
 # hai-datapipe
@@ -15,202 +15,21 @@ description: "使用 @h-ai/datapipe 清洗文本、分块并组合 RAG 入库管
 | 输出 | 清洗/分块的 HaiResult；管线工厂按签名使用 |
 | 限制 | 纯函数，无 init/close；区分字符数和模型 token 数，分块结果不等于已生成 embedding。 |
 
-> `@h-ai/datapipe` 提供文本清洗（clean）、多模式分块（chunk）和可组合管线（pipeline），纯函数模块，无需初始化。
+## 使用路径
 
-## 运行环境
+1. 直接使用 clean/chunk/pipeline，无 init/close；清洗或分块失败后不读 data。
+2. 根据原文结构选择模式，明确 maxSize、overlap 与字符/词边界；这里不负责模型 token 预算。
+3. 自定义正则仅来自可信配置。入库前先检查管线结果，再生成 embedding，并验证向量维度与集合匹配。
+4. 验证空文本、非法配置、边界切分与自定义转换失败；保留文档内容及必要元数据。
 
-> **服务端模块（Node.js only）。** 通常在 AI 知识库入库或文档预处理场景中使用，由 `@h-ai/ai` 内部调用或在服务端显式调用。
+## 按需参考
 
-## 适用场景
+按本次操作读取对应小节；以已安装版本的公开类型核验签名，示例中的业务变量由应用提供。
 
-- 文本清洗：移除 HTML 标签、URL、Email，标准化空白
-- 文本分块：句子、段落、Markdown 标题、字数、字符、自定义分隔符
-- RAG 入库前的文档预处理管线
-- 管线模式组合多步清洗 + 分块 + 自定义转换
-
-## 使用步骤
-
-### 直接调用（无需 init）
-
-```typescript
-import { datapipe } from '@h-ai/datapipe'
-
-// 清洗
-const cleaned = datapipe.clean(htmlText, { removeHtml: true, removeUrls: true })
-
-// 分块
-const chunks = datapipe.chunk(cleaned.data, { mode: 'markdown', maxSize: 2000, overlap: 200 })
-```
-
-### 管线模式
-
-```typescript
-const result = await datapipe.pipeline()
-  .clean({ removeHtml: true, removeUrls: true })
-  .transform(text => text.toLowerCase())
-  .chunk({ mode: 'paragraph', maxSize: 1000, overlap: 100 })
-  .chunkTransform(chunks => chunks.filter(c => c.content.length > 50))
-  .run(rawText)
-
-if (result.success) {
-  // result.data => { text: string, chunks: DataChunk[] }
-}
-```
-
-## 核心 API
-
-### 清洗 — `datapipe.clean`
-
-```text
-datapipe.clean(text: string, options?: CleanOptionsInput): HaiResult<string>
-```
-
-**CleanOptionsInput**：
-
-| 字段                 | 类型               | 默认  | 说明                     |
-| -------------------- | ------------------ | ----- | ------------------------ |
-| `removeHtml`         | `boolean`          | true  | 移除 HTML 标签           |
-| `removeUrls`         | `boolean`          | false | 移除 URL                 |
-| `removeEmails`       | `boolean`          | false | 移除 Email 地址          |
-| `normalizeWhitespace`| `boolean`          | true  | 多空格→单空格、去多余空行 |
-| `trim`               | `boolean`          | true  | 去除首尾空白             |
-| `customReplacements` | `{ pattern, replacement }[]` | — | 自定义正则替换规则 |
-
-### 分块 — `datapipe.chunk`
-
-```text
-datapipe.chunk(text: string, options: ChunkOptionsInput): HaiResult<DataChunk[]>
-```
-
-**ChunkOptionsInput**：
-
-| 字段               | 类型      | 默认 | 说明                           |
-| ------------------ | --------- | ---- | ------------------------------ |
-| `mode`             | `ChunkMode` | —   | 分块模式（必填）               |
-| `maxSize`          | `number`  | 1000 | 分块最大大小                   |
-| `overlap`          | `number`  | 0    | 重叠大小（上下文衔接）         |
-| `separator`        | `string`  | —    | 自定义分隔符正则（mode=custom）|
-| `markdownMinLevel` | `number`  | 2    | Markdown 最低标题级别（1-6）   |
-| `markdownKeepTitle`| `boolean` | true | 分块中保留 Markdown 标题       |
-
-**分块模式**：
-
-| 模式        | 说明                        |
-| ----------- | --------------------------- |
-| `sentence`  | 按句子（中英文句号/问号/感叹号） |
-| `paragraph` | 按段落（双换行）            |
-| `markdown`  | 按 Markdown 标题层级        |
-| `page`      | 按分页符（\f）              |
-| `word`      | 按字数                      |
-| `character` | 按字符数                    |
-| `custom`    | 自定义正则分隔符            |
-
-**DataChunk**：
-
-```typescript
-interface DataChunk {
-  index: number                      // 分块索引（从 0 开始）
-  content: string                    // 分块内容
-  metadata?: Record<string, unknown> // 元数据（Markdown 模式含 title、level）
-}
-```
-
-### 管线 — `datapipe.pipeline()`
-
-```typescript
-datapipe.pipeline()
-  .clean(options)              // 添加清洗步骤
-  .transform(fn)                // 添加文本转换步骤（同步/异步）
-  .chunk(options)               // 添加分块步骤
-  .chunkTransform(fn)           // 添加分块后处理步骤
-  .run(text)                    // 执行管线 → Promise<HaiResult<PipelineResult>>
-```
-
-**PipelineResult**：
-
-```typescript
-interface PipelineResult {
-  text: string        // 处理后的文本（分块前的最终文本）
-  chunks: DataChunk[] // 分块列表（如果管线包含 chunk 步骤）
-}
-```
-
-## 错误码 — `HaiDatapipeError`
-
-| 错误码 | code | 说明 |
-|--------|------|------|
-| `HaiDatapipeError.CLEAN_FAILED` | `hai:datapipe:001` | 清洗失败 |
-| `HaiDatapipeError.CHUNK_FAILED` | `hai:datapipe:002` | 分块失败 |
-| `HaiDatapipeError.TRANSFORM_FAILED` | `hai:datapipe:003` | 转换失败 |
-| `HaiDatapipeError.PIPELINE_FAILED` | `hai:datapipe:004` | 管线执行失败 |
-| `HaiDatapipeError.CONFIG_ERROR` | `hai:datapipe:005` | 配置错误 |
-| `HaiDatapipeError.MISSING_SEPARATOR` | `hai:datapipe:006` | 自定义分隔符缺失 |
-
-## 常见模式
-
-### RAG 文档入库前处理
-
-```typescript
-import { datapipe } from '@h-ai/datapipe'
-import { ai } from '@h-ai/ai'
-import { vecdb } from '@h-ai/vecdb'
-
-// 清洗 + Markdown 分块
-const result = await datapipe.pipeline()
-  .clean({ removeHtml: true, removeUrls: true })
-  .chunk({ mode: 'markdown', maxSize: 1000, overlap: 100 })
-  .run(rawDocument)
-
-if (!result.success) return result
-
-// 生成嵌入
-const embeddings = await ai.embedding.embedBatch(
-  result.data.chunks.map(c => c.content),
-)
-if (!embeddings.success) return embeddings
-
-// 入库
-const docs = result.data.chunks.map((chunk, i) => ({
-  id: `chunk-${i}`,
-  vector: embeddings.data[i],
-  content: chunk.content,
-  metadata: chunk.metadata,
-}))
-await vecdb.vector.insert('knowledge', docs)
-```
-
-### 多步清洗管线
-
-```typescript
-const result = await datapipe.pipeline()
-  .clean({ removeHtml: true, removeEmails: true })
-  .transform(text => text.replace(/\[.*?\]/g, ''))        // 移除 [注释]
-  .transform(text => text.replace(/\(https?:.*?\)/g, '')) // 移除 Markdown 链接 URL
-  .chunk({ mode: 'paragraph', maxSize: 800 })
-  .chunkTransform(chunks => chunks.filter(c => c.content.length > 20)) // 过滤过短分块
-  .run(rawText)
-```
-
-### 错误分支处理
-
-```typescript
-import { datapipe, HaiDatapipeError } from '@h-ai/datapipe'
-
-const result = datapipe.chunk(text, { mode: 'custom' })
-if (!result.success) {
-  switch (result.error.code) {
-    case HaiDatapipeError.MISSING_SEPARATOR.code:
-      // mode='custom' 时需提供 separator
-      break
-    case HaiDatapipeError.CONFIG_ERROR.code:
-      // 配置参数校验失败
-      break
-  }
-}
-```
-
-## 相关 Skills
-
-- `hai-vecdb`：向量数据库存储（分块后入库）
-- `hai-ai`：LLM 与 Embedding 能力
-- `hai-core`：HaiResult 模型
+- [运行环境](reference.md#运行环境)
+- [适用场景](reference.md#适用场景)
+- [使用步骤](reference.md#使用步骤)
+- [核心 API](reference.md#核心-api)
+- [错误码 — `HaiDatapipeError`](reference.md#错误码--haidatapipeerror)
+- [常见模式](reference.md#常见模式)
+- [相关 Skills](reference.md#相关-skills)

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

@@ -0,0 +1,202 @@
+# hai-datapipe 参考
+
+> `@h-ai/datapipe` 提供文本清洗（clean）、多模式分块（chunk）和可组合管线（pipeline），纯函数模块，无需初始化。
+
+## 运行环境
+
+> **服务端模块（Node.js only）。** 通常在 AI 知识库入库或文档预处理场景中使用，由 `@h-ai/ai` 内部调用或在服务端显式调用。
+
+## 适用场景
+
+- 文本清洗：移除 HTML 标签、URL、Email，标准化空白
+- 文本分块：句子、段落、Markdown 标题、字数、字符、自定义分隔符
+- RAG 入库前的文档预处理管线
+- 管线模式组合多步清洗 + 分块 + 自定义转换
+
+## 使用步骤
+
+### 直接调用（无需 init）
+
+```typescript
+import { datapipe } from '@h-ai/datapipe'
+
+// 清洗
+const cleaned = datapipe.clean(htmlText, { removeHtml: true, removeUrls: true })
+
+// 分块
+if (!cleaned.success) return cleaned
+const chunks = datapipe.chunk(cleaned.data, { mode: 'markdown', maxSize: 2000, overlap: 200 })
+```
+
+### 管线模式
+
+```typescript
+const result = await datapipe.pipeline()
+  .clean({ removeHtml: true, removeUrls: true })
+  .transform(text => text.toLowerCase())
+  .chunk({ mode: 'paragraph', maxSize: 1000, overlap: 100 })
+  .chunkTransform(chunks => chunks.filter(c => c.content.length > 50))
+  .run(rawText)
+
+if (result.success) {
+  // result.data => { text: string, chunks: DataChunk[] }
+}
+```
+
+## 核心 API
+
+### 清洗 — `datapipe.clean`
+
+```text
+datapipe.clean(text: string, options?: CleanOptionsInput): HaiResult<string>
+```
+
+**CleanOptionsInput**：
+
+| 字段                 | 类型               | 默认  | 说明                     |
+| -------------------- | ------------------ | ----- | ------------------------ |
+| `removeHtml`         | `boolean`          | true  | 移除 HTML 标签           |
+| `removeUrls`         | `boolean`          | false | 移除 URL                 |
+| `removeEmails`       | `boolean`          | false | 移除 Email 地址          |
+| `normalizeWhitespace`| `boolean`          | true  | 多空格→单空格、去多余空行 |
+| `trim`               | `boolean`          | true  | 去除首尾空白             |
+| `customReplacements` | `{ pattern, replacement }[]` | — | 自定义正则替换规则 |
+
+### 分块 — `datapipe.chunk`
+
+```text
+datapipe.chunk(text: string, options: ChunkOptionsInput): HaiResult<DataChunk[]>
+```
+
+**ChunkOptionsInput**：
+
+| 字段               | 类型      | 默认 | 说明                           |
+| ------------------ | --------- | ---- | ------------------------------ |
+| `mode`             | `ChunkMode` | —   | 分块模式（必填）               |
+| `maxSize`          | `number`  | 1000 | 分块最大大小                   |
+| `overlap`          | `number`  | 0    | 重叠大小（上下文衔接）         |
+| `separator`        | `string`  | —    | 自定义分隔符正则（mode=custom）|
+| `markdownMinLevel` | `number`  | 2    | Markdown 最低标题级别（1-6）   |
+| `markdownKeepTitle`| `boolean` | true | 分块中保留 Markdown 标题       |
+
+**分块模式**：
+
+| 模式        | 说明                        |
+| ----------- | --------------------------- |
+| `sentence`  | 按句子（中英文句号/问号/感叹号） |
+| `paragraph` | 按段落（双换行）            |
+| `markdown`  | 按 Markdown 标题层级        |
+| `page`      | 按分页符（\f）              |
+| `word`      | 按字数                      |
+| `character` | 按字符数                    |
+| `custom`    | 自定义正则分隔符            |
+
+**DataChunk**：
+
+```typescript
+interface DataChunk {
+  index: number                      // 分块索引（从 0 开始）
+  content: string                    // 分块内容
+  metadata?: Record<string, unknown> // 元数据（Markdown 模式含 title、level）
+}
+```
+
+### 管线 — `datapipe.pipeline()`
+
+```typescript
+datapipe.pipeline()
+  .clean(options)              // 添加清洗步骤
+  .transform(fn)                // 添加文本转换步骤（同步/异步）
+  .chunk(options)               // 添加分块步骤
+  .chunkTransform(fn)           // 添加分块后处理步骤
+  .run(text)                    // 执行管线 → Promise<HaiResult<PipelineResult>>
+```
+
+**PipelineResult**：
+
+```typescript
+interface PipelineResult {
+  text: string        // 处理后的文本（分块前的最终文本）
+  chunks: DataChunk[] // 分块列表（如果管线包含 chunk 步骤）
+}
+```
+
+## 错误码 — `HaiDatapipeError`
+
+| 错误码 | code | 说明 |
+|--------|------|------|
+| `HaiDatapipeError.CLEAN_FAILED` | `hai:datapipe:001` | 清洗失败 |
+| `HaiDatapipeError.CHUNK_FAILED` | `hai:datapipe:002` | 分块失败 |
+| `HaiDatapipeError.TRANSFORM_FAILED` | `hai:datapipe:003` | 转换失败 |
+| `HaiDatapipeError.PIPELINE_FAILED` | `hai:datapipe:004` | 管线执行失败 |
+| `HaiDatapipeError.CONFIG_ERROR` | `hai:datapipe:005` | 配置错误 |
+| `HaiDatapipeError.MISSING_SEPARATOR` | `hai:datapipe:006` | 自定义分隔符缺失 |
+
+## 常见模式
+
+### RAG 文档入库前处理
+
+```typescript
+import { datapipe } from '@h-ai/datapipe'
+import { ai } from '@h-ai/ai'
+import { vecdb } from '@h-ai/vecdb'
+
+// 清洗 + Markdown 分块
+const result = await datapipe.pipeline()
+  .clean({ removeHtml: true, removeUrls: true })
+  .chunk({ mode: 'markdown', maxSize: 1000, overlap: 100 })
+  .run(rawDocument)
+
+if (!result.success) return result
+
+// 生成嵌入
+const embeddings = await ai.embedding.embedBatch(
+  result.data.chunks.map(c => c.content),
+)
+if (!embeddings.success) return embeddings
+
+// 入库
+const docs = result.data.chunks.map((chunk, i) => ({
+  id: `chunk-${i}`,
+  vector: embeddings.data[i],
+  content: chunk.content,
+  metadata: chunk.metadata,
+}))
+await vecdb.vector.insert('knowledge', docs)
+```
+
+### 多步清洗管线
+
+```typescript
+const result = await datapipe.pipeline()
+  .clean({ removeHtml: true, removeEmails: true })
+  .transform(text => text.replace(/\[.*?\]/g, ''))        // 移除 [注释]
+  .transform(text => text.replace(/\(https?:.*?\)/g, '')) // 移除 Markdown 链接 URL
+  .chunk({ mode: 'paragraph', maxSize: 800 })
+  .chunkTransform(chunks => chunks.filter(c => c.content.length > 20)) // 过滤过短分块
+  .run(rawText)
+```
+
+### 错误分支处理
+
+```typescript
+import { datapipe, HaiDatapipeError } from '@h-ai/datapipe'
+
+const result = datapipe.chunk(text, { mode: 'custom' })
+if (!result.success) {
+  switch (result.error.code) {
+    case HaiDatapipeError.MISSING_SEPARATOR.code:
+      // mode='custom' 时需提供 separator
+      break
+    case HaiDatapipeError.CONFIG_ERROR.code:
+      // 配置参数校验失败
+      break
+  }
+}
+```
+
+## 相关 Skills
+
+- `hai-vecdb`：向量数据库存储（先生成 embedding，再入库）
+- `hai-ai`：LLM 与 Embedding 能力
+- `hai-core`：HaiResult 模型

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

@@ -1,6 +1,6 @@
 ---
 name: hai-deploy
-description: "部署已有构建产物：配置环境与中间件，生成 Compose tar 并通过 SSH 或手工搬运发布；也支持 Vercel。"
+description: "构建并发布或交付已有镜像：完整离线包、按服务更新、SSH 与跨平台手工部署、失败恢复；也支持 Vercel prebuilt。"
 ---
 
 # hai-deploy
@@ -9,76 +9,41 @@ description: "部署已有构建产物：配置环境与中间件，生成 Compo
 
 | 项目 | 契约 |
 | --- | --- |
-| 能力 | 消费已有镜像或平台产物，配置环境、中间件并部署 |
-| 适用场景 | SSH 自动部署、离线手工交付、Vercel 发布和部署故障排查 |
-| 输入 | 完整构建产物、pnpm-lock.yaml、目标环境文件、部署配置和私有凭据引用 |
-| 输出 | Compose tar 与手工说明，或已检查的在线部署结果 |
-| 限制 | deploy 不编译/构建，不提供 skip-build 兼容路径；收费开通/发布/删除须在用户授权范围内。packaged 不代表 ready。 |
+| 能力 | 配置环境与中间件，交付完整离线包或发布选中服务 |
+| 适用场景 | 一体化构建发布、独立打包、隔离网络手工部署、增量更新与故障排查 |
+| 输入 | package.json、hai.build.json、运行依赖锁文件、目标环境、已有制品或明确构建要求 |
+| 输出 | 带校验和的 tar、跨平台部署入口与分步结果，或经过 HTTP 检查的部署结果 |
+| 限制 | SDK 只消费产物；CLI --build 显式先构建。首次安装必须完整交付，packaged 不代表服务器 ready。云资源需要外网。 |
 
 ## 操作流程
 
-1. 读取当前 package.json、`hai.build.json`、构建清单和 `_deploy.yml`；构建入口见 [hai-build](../hai-build/SKILL.md)。先显式运行 `pnpm build --target docker`，缺产物不得在 deploy 中隐式补构建。
-2. 选择环境，检查 `.env.<mode>`；缺失则让用户创建后再继续。六类环境文件和变量优先级见 [中间件与环境](middleware.md)。
-3. 逐项展示 lockfile 运行依赖要求的中间件、当前后端与默认用途，提供默认/自定义/完整配置时保持不变。用户表示配置齐全或传 `--skip-middleware` 时跳过全部处理，不重写连接或开通资源。
-4. 检查已有镜像清单和 SHA-256，再生成对应环境的 Compose tar。含 app/web 时一起发布，公开 Web 同源代理 API；私有 env 仅挂载 API。
-   版本以清单 appVersion 为准，不从当前源码猜测；Compose 使用 docker-compose-<版本>.yml，tar 自动补版本后缀，启动与手工 ps/logs 都显式 -f 指定。保留稳定的项目/卷身份，跨版本跳过中间件时复用上次 Compose。CLI 仅使用 --skip-middleware，SDK 仅使用 skipMiddleware。
-5. 在线模式上传一个 tar，远程解包、导入、compose up，再检查 API/Web；手工模式 `--bundle-only` 不要求 SSH 配置、不连接远端，输出准确的复制/解包/启动步骤及所需镜像标签。
-6. 失败返回非零退出码；SDK 返回 HaiResult，先检查 success。保留已创建资源的恢复信息，不擅自删除。测试资源在 finally/teardown 清理。
+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。已有部署失败尝试恢复所选服务的旧容器和配置；数据卷保留，已写业务数据不回退，恢复后仍需验证健康。禁止把本地打包记录当服务器成功状态。
 
 ## CLI
 
-使用 `pnpm run deploy` 明确执行项目脚本，避免与 pnpm 自身的 deploy 命令混淆。
-
 ```sh
+pnpm run deploy --env prod --build
 pnpm build --target docker
-pnpm run deploy --env test
-pnpm run deploy --env prod --skip-middleware
 pnpm run deploy --env prod --artifact-dir .hai/build/docker/<buildId>
 pnpm run deploy --env prod --bundle-only --output release-prod.tar
-# fullstack 的 deploy 脚本等价于
-pnpm exec hai deploy packages/my-app-serv --env prod --env-dir .
-```
-
-API workspace 的服务目录为 apps/my-app-service。单包使用当前目录。Node/pnpm 版本以项目 engines/packageManager 为准，Windows 用 pnpm.cmd。
-
-```yaml
-# 服务包 config/_deploy.yml
-provider:
-  type: docker-ssh
-  expose:
-    hostPort: 18080
-container:
-  s3Engine: rustfs # rustfs | minio
+pnpm build --target docker --images web
+pnpm run deploy --env prod --services web
 ```
 
-SSH/平台参数可在向导输入后存入 `.env.local` 的 `HAI_DEPLOY_PROVIDER` 整体 JSON；私钥只存路径，不记录内容。仅打包可省 SSH；在线部署需要 ssh/scp、主机信任和运行权限。完整字段、可选云 Provisioner 及中间件配置见 [middleware.md](middleware.md)。
+使用 pnpm run deploy，避免与 pnpm 自带 deploy 混淆。fullstack 指向 packages/<项目>-serv，API workspace 指向 apps/<项目>-service；这是扫描入口，不是镜像选择。--services 负责选择；--skip-middleware 只跳过配置及开通。--yes 复用有效配置，缺值时不盲目继续。
 
 ## SDK
 
-```ts
-import { deploy } from '@h-ai/deploy'
-
-const initialized = await deploy.init({ provider: { type: 'docker-ssh', expose: { hostPort: 18080 } } })
-if (!initialized.success) throw new Error(initialized.error.message)
-try {
-  const result = await deploy.deployApp('./packages/my-app-serv', {
-    environment: 'prod', envDir: '.', bundleOnly: true,
-    artifactDir: './.hai/build/docker/<buildId>', skipMiddleware: true,
-  })
-  if (!result.success) throw new Error(result.error.message)
-  // bundlePath/instructions；只有在线部署才有健康检查和可访问 URL。
-}
-finally {
-  await deploy.close()
-}
-```
-
-`deploy.scan`、`deploy.credentials.getPath/load/save/saveAll` 不依赖 init。Vercel 使用 prebuilt 协议只上传 Build Output API v3 的 .vercel/output，不运行 build 命令；云认证和开通需要外网。
+deploy.init 后检查 HaiResult.success，deploy.deployApp 接收 artifactDir、bundleOnly、selectedServices、runtime 与 onProgress；finally 中 deploy.close。deploy.scan 和 deploy.credentials.* 不依赖 init。Vercel 只消费已有 .vercel/output，不执行源码构建，也不支持 Compose 离线/部分更新。
 
 ## 离线交付与验证
 
-部署器不需要本地容器引擎；提前从构建机复制完整 `.hai/build/docker/<buildId>`。Linux 准备 Docker/Podman、compose、sh、tar、sha256sum、所需中间件镜像的准确标签及数据目录权限。手工包含私有配置，权限受限，不提交 Git。启动脚本校验文件、加载 app/web、检查镜像存在并导出环境标识；缺镜像时停止，不联网拉取。
-
-完全离线构建另需基础镜像、Linux 依赖缓存、pnpm 和匹配 ABI/libc 的 SQLite 预编译包；Windows node_modules 不能替代。生产 HTTPS、CORS、证书和 DNS 另行配置。实际断网后验收登录、刷新、重启与持久化，不能将联网测试当作离线证明。
+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 不能替代。
 
-改动后执行 typecheck、lint、build、test，模板执行 scaffold gates，部署流程执行 test:deploy-gates；真实 Tauri 安装包按系统单独验证。所有测试临时工程、镜像、容器、辅助进程、截图、日志和报告必须在 finally/teardown 自动清理，失败/取消同样清理。不得把验收产物提交 Git，也不得清理用户既有资源。
+按 [分轮验证与集中修复](../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

@@ -71,18 +71,12 @@ S3 是协议，不是某个容器产品。默认配置时另选 RustFS/MinIO，
 
 ## 离线准备与验收
 
-构建与部署分开：先在构建机运行 `pnpm build --target docker`，将完整 `.hai/build/docker/<buildId>` 复制到部署电脑。deploy 只读取这些已校验的镜像 tar，不需要本地 Docker/Podman、基础镜像、pnpm store 或 SQLite 下载。Node/pnpm 版本以工程 engines/packageManager 为准。
+构建与部署可分开，也可通过 pnpm run deploy --build 明确串联。构建保持环境无关；部署选择环境并只消费所选镜像。完整包自动包含 Compose 自建中间件镜像，因此导出阶段需要本地 Podman/Docker，缺镜像在打包阶段准备，不能留给隔离服务器下载。
 
-`pnpm run deploy --env prod --bundle-only --output release-prod.tar` 按清单 appVersion 自动生成 release-prod-1.2.3.tar（示例版本 1.2.3），包含 app/web、docker-compose-1.2.3.yml、manifest.json、私有 env、校验和、README 与 start-prod.sh，不连接 SSH。搬到 Linux 后，创建权限 700 的目录，`tar -xf release-prod-1.2.3.tar -C release`，`cd release && sh start-prod.sh`。脚本自动指定带版本的 Compose；手工状态检查使用 `docker compose -f docker-compose-1.2.3.yml --env-file .env.runtime ps`。启动脚本可用 HAI_DEPLOY_PROVIDER_REMOTE_RUNTIME=docker/podman 选择运行时，镜像缺少时停止，不尝试联网。
+--bundle-only 生成带版本 tar 与 -deploy/ 目录。操作目录含 Windows deploy.ps1、Linux/macOS deploy.sh 和目标配置。隔离服务器搬运并解包后执行 sh apply.sh。每步失败返回非零，结果写 result-<部署ID>.json；只有 HTTP 检查通过才更新服务器 current。
 
-Linux 需要 compose、sh、tar、sha256sum 和容器/目录/持久化磁盘权限；中间件镜像另行 docker load，名称、tag 和架构须与包内清单一致。自定义连接要求现有服务可从应用容器访问，并备好账号、数据库、S3 桶与密钥。云 Provider/Provisioner 需要网络，不能用于完全离线。
+部分更新通过 --services 指定，使用服务器成功基线保留未选服务和中间件凭据。首次安装不能使用部分包。storage-init 复用应用镜像及 S3 SDK 检查/创建桶，不清空数据；只有涉及存储初始化时执行，并检查退出码。仅更新 storage 仍需含 app 镜像的制品；最近为 web-only 时，用 --artifact-dir 选择原完整制品，或先 pnpm build --target docker --images app。app 镜像仅用于初始化，不会更新 app 服务。失败恢复尝试还原容器和配置，保留数据卷，不回退已写业务数据。
 
-如连构建也需离线，构建机另准备 Linux 容器引擎、Node/Nginx 基础镜像、pnpm/Corepack、完整 Linux 依赖缓存和匹配 SQLite 驱动/Node ABI/架构/libc 的预编译包。可用构建参数 `--sqlite-prebuild-mirror <可信HTTP(S)地址>` 指定二进制根目录；失败应修复缓存/网络，不能让 deploy 下载编译环境。构建无需选择环境；Podman 代理不可达时用 `pnpm build --target docker --no-http-proxy`，不修改系统代理。
+服务器需要 Linux、Docker/Podman、Compose、sh、tar、sha256sum、awk、curl、持久化磁盘和容器/目录权限。完整交付包含自建服务镜像；自定义外部连接仍需准备服务、账号和网络可达性。云 Provider/Provisioner 需要外网，不能用于完全离线。
 
-## 启动与验证
-
-fullstack 的 hai.build.json 含 app/web 时，两镜像共用构建 ID，部署生成一个 Compose 和同源代理。API 前缀来自当前服务配置，缺省 CORS 填公开入口，明确 Origin 保留；Web 不挂载 .env.runtime。线上成功要求 API/Web 健康，手工模式返回 packaged 并提示用户自行验收。生产登录刷新还需 HTTPS、正确 CORS、受信证书与 DNS/hosts，模块不配置 TLS。
-
-容器运行期 NODE_ENV=production；HAI_DEPLOY_ENVIRONMENT 保存文件模式，HAI_CORE_ENV 映射 development/test/production/staging。资源名附环境后缀，卷按环境隔离；私有 env 权限 600。构建上下文排除 .env.local、环境覆盖、.env.runtime、.hai/build、.hai/deploy 和 data，不把运行期凭据写入镜像。
-
-修改后运行 deploy/CLI typecheck、lint、build、test、scaffold gates 和 test:deploy-gates。测试应分别证明构建/环境选择、SSH 上传及手工包启动、Web 登录/刷新；断网能力另做实际断网验收。测试的临时工程、容器、镜像、日志、截图、报告与辅助进程必须 finally/teardown 自动清理，失败也清理；不得删除用户已有资源。原生客户端及付费云资源单独验收并报告边界。
+完全离线构建另需基础镜像、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) 的对应小节；签名以当前源码或安装版本的公开类型为准，不默认加载全部资料。示例中的业务变量由应用提供。
 
 - 运行环境
 - 依赖