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

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

@@ -1,6 +1,6 @@
 ---
 name: hai-datapipe
-description: 使用 @h-ai/datapipe 进行文本清洗（HTML/URL/空白移除）、多模式分块（句子/段落/Markdown/字符/自定义）和管线组合；当需求涉及文本预处理、文档分块、数据清洗或 RAG 入库前处理时使用。
+description: "使用 @h-ai/datapipe 清洗文本、分块并组合 RAG 入库管线。"
 ---
 
 # hai-datapipe
@@ -9,22 +9,18 @@ description: 使用 @h-ai/datapipe 进行文本清洗（HTML/URL/空白移除）
 
 | 项目 | 契约 |
 | --- | --- |
-| 能力 | 使用 @h-ai/datapipe 进行文本清洗（HTML/URL/空白移除）、多模式分块（句子/段落/Markdown/字符/自定义）和管线组合；当需求涉及文本预处理、文档分块、数据清洗或 RAG 入库前处理时使用。 |
-| 适用场景 | 当任务与 `hai-datapipe` 的能力描述匹配，并且需要遵循本 Skill 的流程和边界时 |
-| 输入 | 模块配置、类型化业务参数、依赖初始化状态和目标运行环境 |
-| 输出 | 符合模块公共 API 的实现或示例；业务结果使用 HaiResult，并同步必要测试与文档 |
-| 限制 | 遵守 init → use → close 生命周期与运行环境边界；不绕过类型、授权、输入校验或敏感信息保护 |
+| 能力 | 使用 @h-ai/datapipe 清洗文本、分块并组合 RAG 入库管线 |
+| 适用场景 | 文档进入检索/知识库前的文本预处理 |
+| 输入 | 文本、清洗/分块选项、管线步骤 |
+| 输出 | 清洗/分块的 HaiResult；管线工厂按签名使用 |
+| 限制 | 纯函数，无 init/close；区分字符数和模型 token 数，分块结果不等于已生成 embedding。 |
 
 > `@h-ai/datapipe` 提供文本清洗（clean）、多模式分块（chunk）和可组合管线（pipeline），纯函数模块，无需初始化。
 
----
-
 ## 运行环境
 
 > **服务端模块（Node.js only）。** 通常在 AI 知识库入库或文档预处理场景中使用，由 `@h-ai/ai` 内部调用或在服务端显式调用。
 
----
-
 ## 适用场景
 
 - 文本清洗：移除 HTML 标签、URL、Email，标准化空白
@@ -32,8 +28,6 @@ description: 使用 @h-ai/datapipe 进行文本清洗（HTML/URL/空白移除）
 - RAG 入库前的文档预处理管线
 - 管线模式组合多步清洗 + 分块 + 自定义转换
 
----
-
 ## 使用步骤
 
 ### 直接调用（无需 init）
@@ -63,13 +57,11 @@ if (result.success) {
 }
 ```
 
----
-
 ## 核心 API
 
 ### 清洗 — `datapipe.clean`
 
-```typescript
+```text
 datapipe.clean(text: string, options?: CleanOptionsInput): HaiResult<string>
 ```
 
@@ -86,7 +78,7 @@ datapipe.clean(text: string, options?: CleanOptionsInput): HaiResult<string>
 
 ### 分块 — `datapipe.chunk`
 
-```typescript
+```text
 datapipe.chunk(text: string, options: ChunkOptionsInput): HaiResult<DataChunk[]>
 ```
 
@@ -127,7 +119,7 @@ interface DataChunk {
 
 ```typescript
 datapipe.pipeline()
-  .clean(options?)              // 添加清洗步骤
+  .clean(options)              // 添加清洗步骤
   .transform(fn)                // 添加文本转换步骤（同步/异步）
   .chunk(options)               // 添加分块步骤
   .chunkTransform(fn)           // 添加分块后处理步骤
@@ -143,8 +135,6 @@ interface PipelineResult {
 }
 ```
 
----
-
 ## 错误码 — `HaiDatapipeError`
 
 | 错误码 | code | 说明 |
@@ -156,8 +146,6 @@ interface PipelineResult {
 | `HaiDatapipeError.CONFIG_ERROR` | `hai:datapipe:005` | 配置错误 |
 | `HaiDatapipeError.MISSING_SEPARATOR` | `hai:datapipe:006` | 自定义分隔符缺失 |
 
----
-
 ## 常见模式
 
 ### RAG 文档入库前处理
@@ -221,8 +209,6 @@ if (!result.success) {
 }
 ```
 
----
-
 ## 相关 Skills
 
 - `hai-vecdb`：向量数据库存储（分块后入库）

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

@@ -1,6 +1,6 @@
 ---
 name: hai-deploy
-description: 使用 @h-ai/deploy 进行自动化部署：Vercel 部署 + 基础设施开通（Neon/Upstash/R2/Resend/Aliyun）；当需求涉及应用部署、环境配置、凭证管理或云服务开通时使用。
+description: "使用 @h-ai/deploy 部署应用：Vercel 云平台或 docker-ssh 容器化部署到任意 Linux 主机，并按需开通/生成基础设施。"
 ---
 
 # hai-deploy
@@ -11,32 +11,30 @@ description: 使用 @h-ai/deploy 进行自动化部署：Vercel 部署 + 基础
 
 | 项目 | 契约 |
 | --- | --- |
-| 能力 | 使用 @h-ai/deploy 进行自动化部署：Vercel 部署 + 基础设施开通（Neon/Upstash/R2/Resend/Aliyun）；当需求涉及应用部署、环境配置、凭证管理或云服务开通时使用。 |
-| 适用场景 | 当任务与 `hai-deploy` 的能力描述匹配，并且需要遵循本 Skill 的流程和边界时 |
-| 输入 | 用户目标、仓库与运行环境上下文、现有配置、授权范围和质量门禁 |
-| 输出 | 与目标匹配的配置/代码/文档或审查结论，以及可复现的验证结果 |
-| 限制 | 不扩张用户授权，不输出或固化密钥，不跳过失败门禁，不假定外部服务状态 |
+| 能力 | 使用 @h-ai/deploy 部署应用：Vercel 云平台或 docker-ssh 容器化部署到任意 Linux 主机 |
+| 适用场景 | 部署目标配置、云资源开通、SSH 主机容器部署或部署故障排查 |
+| 输入 | 项目构建产物、部署目标（vercel / docker-ssh）、环境配置与凭据引用 |
+| 输出 | 部署/资源操作结果和可验证的目标状态（含访问 URL 与健康检查） |
+| 限制 | 核对实际 provider 与应用运行时；开通收费资源、发布或删除必须在用户授权范围内，凭据不写入仓库。 |
 
-> `@h-ai/deploy` 提供自动化部署能力，将 SvelteKit 应用部署到 Vercel，并自动开通 PostgreSQL (Neon)、Redis (Upstash)、S3 (Cloudflare R2)、邮件 (Resend)、短信 (阿里云) 等基础设施服务。
-
----
+> `@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。
 
 ## 运行环境
 
 > ⚠️ **Node.js CLI / 服务端模块。** 通过 `hai deploy` CLI 命令或在 Node.js 脚本中使用。
-
----
+> docker-ssh 方式要求本地安装 docker 或 podman（`auto` 优先 podman）。
 
 ## 适用场景
 
 - 一键部署 SvelteKit 应用到 Vercel
-- 自动开通 PostgreSQL、Redis、S3 等云服务
+- 容器化后经 SSH 部署到自有服务器 / 云主机 / 内网虚拟机（docker-ssh）
+- 自动开通 PostgreSQL、Redis、S3 等云服务，或按功能生成自建 sidecar
 - 管理部署凭证（~/.hai/credentials.yml）
 - 扫描应用依赖，自动检测所需服务
 - CLI 部署流程（`hai deploy`）
 
----
-
 ## 使用步骤
 
 ### 1. 配置
@@ -75,6 +73,49 @@ services:
 这些凭证名由 `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_SSH_HOST}
+    port: 22
+    username: deploy
+    identityFile: ${HAI_DEPLOY_SSH_KEY} # 私钥文件路径，省略则用 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/minio）
+  # 若配置了云 Provisioner（如 neon），则优先用云资源，不再自建 sidecar
+  db:
+    provisioner: neon
+    apiKey: ${HAI_DEPLOY_NEON_API_KEY}
+```
+
+docker-ssh 要点：
+
+- 应用镜像使用工程自带的 `Dockerfile`（`@sveltejs/adapter-node`），缺少 adapter-node 会返回 `ADAPTER_MISSING`
+- compose 按 `deploy.scan()` 识别的服务**及其后端类型**生成匹配 sidecar 并注入 `HAI_*` 覆盖变量：
+  - `db`：`postgresql`→postgres、`mysql`→mysql、`sqlite`→数据卷（无 sidecar）→ `HAI_DB`
+  - `cache`：`redis`→redis → `HAI_CACHE`；`storage`：`s3`→minio → `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
@@ -128,8 +169,6 @@ if (result.success) {
 }
 ```
 
----
-
 ## 核心 API
 
 | 方法                   | 签名                                                                       | 说明         |
@@ -146,16 +185,12 @@ if (result.success) {
 | `deploy.config`        | `DeployConfig \| null`                                                     | 当前配置     |
 | `deploy.isInitialized` | `boolean`                                                                  | 初始化状态   |
 
----
-
 ## 凭证管理
 
 所有凭证操作都通过 `deploy.credentials.*` 访问，模块入口不再单独导出自由函数。
 
 > `deploy.credentials.*()` 与 `deploy.scan()` 都不依赖 `deploy.init()`，可用于 CLI 在读取 `_deploy.yml` 之前准备环境。
 
----
-
 ## 错误码 — `HaiDeployError`
 
 | 错误码                                  | code               | 说明                     |
@@ -174,8 +209,12 @@ if (result.success) {
 | `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 命令
 
@@ -196,7 +235,8 @@ hai deploy --skip-build
 hai deploy --project-name my-custom-name
 ```
 
----
+> 部署方式由 `config/_deploy.yml` 的 `provider.type` 决定（vercel / docker-ssh），
+> CLI 命令相同。docker-ssh 成功后输出的访问地址为 `http://<host>:<hostPort>`。
 
 ## 常见模式
 
@@ -229,8 +269,6 @@ await deploy.init({
 const result = await deploy.deployApp('./apps/my-app')
 ```
 
----
-
 ## 相关 Skills
 
 - **hai-core** — 配置加载、日志、HaiResult 类型

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

@@ -1,6 +1,6 @@
 ---
 name: hai-framework-sync
-description: 管理 hai-framework 与应用仓库之间的依赖、技能模板、Copilot/AGENTS 指令和本地联调同步；当需求涉及 hai-framework 源头修改、skills 同步、framework:use:local、framework:watch、版本漂移或双仓 PR 时使用。
+description: "同步 hai-framework 通用 skills、AI 入口与应用依赖，排查 npm/本地联调漂移。"
 ---
 
 # hai-framework-sync — hai-framework 与应用仓库同步规范
@@ -9,16 +9,14 @@ description: 管理 hai-framework 与应用仓库之间的依赖、技能模板
 
 | 项目 | 契约 |
 | --- | --- |
-| 能力 | 管理 hai-framework 与应用仓库之间的依赖、技能模板、Copilot/AGENTS 指令和本地联调同步；当需求涉及 hai-framework 源头修改、skills 同步、framework:use:local、framework:watch、版本漂移或双仓 PR 时使用。 |
-| 适用场景 | 当任务与 `hai-framework-sync` 的能力描述匹配，并且需要遵循本 Skill 的流程和边界时 |
-| 输入 | 用户目标、仓库与运行环境上下文、现有配置、授权范围和质量门禁 |
-| 输出 | 与目标匹配的配置/代码/文档或审查结论，以及可复现的验证结果 |
-| 限制 | 不扩张用户授权，不输出或固化密钥，不跳过失败门禁，不假定外部服务状态 |
+| 能力 | 同步 hai-framework 通用 skills、AI 入口与应用依赖，排查 npm/本地联调漂移 |
+| 适用场景 | 有明确源/目标仓库的模板或版本同步 |
+| 输入 | 框架源目录、应用目录、版本、现有本地覆盖 |
+| 输出 | 同步后的完整 skill 目录、入口及版本验证结果 |
+| 限制 | 仅操作授权仓库；保留应用私有规则。先查 scripts，不假定 framework:* 联调命令存在；未发布行为不能当 npm 已支持。 |
 
 > hai-framework 是能力与 skill 模板源头；应用仓库消费这些能力，并可以有少量项目本地覆盖。同步的目标是减少漂移，而不是把两个仓库混成一个仓库。
 
----
-
 ## 适用场景
 
 - 修改 `.agents/skills/**`，且内容应成为所有 hai-framework 应用通用规范
@@ -28,8 +26,6 @@ description: 管理 hai-framework 与应用仓库之间的依赖、技能模板
 - 排查应用仓库与 hai-framework npm 版本不一致
 - 规划双仓 PR 或同步发布
 
----
-
 ## 同步原则
 
 1. **通用规范先改 hai-framework**：可复用的 skill、模板、AI 工作流从 `packages/cli/templates/skills/` 起源。
@@ -38,8 +34,6 @@ description: 管理 hai-framework 与应用仓库之间的依赖、技能模板
 4. **双仓改动要成套**：framework 模板、应用本地 `.agents/skills`、AGENTS/Copilot 路由同时更新。
 5. **不复制敏感聊天记录**：只同步脱敏后的团队规则和流程。
 
----
-
 ## 标准同步流程
 
 ### 1. 判断来源
@@ -57,7 +51,7 @@ description: 管理 hai-framework 与应用仓库之间的依赖、技能模板
 
 ### 3. 同步到应用仓库
 
-把源头 skill 复制到应用仓库 `.agents/skills/<skill>/SKILL.md`，并同步入口引用：
+把源头完整 skill 目录（含 reference.md 等被引用资源）复制到应用仓库 `.agents/skills/<skill>/`，并同步入口引用：
 
 - `AGENTS.md`
 - `.github/copilot-instructions.md`
@@ -70,7 +64,7 @@ description: 管理 hai-framework 与应用仓库之间的依赖、技能模板
 
 - 仅模板 / skill 变更：检查 diff、入口引用与模板泛化程度。
 - 同步到应用仓库：按 `hai-ci` 定义的质量门禁运行。
-- 涉及 framework runtime 时，再选择：
+- 涉及 framework runtime 时，先确认应用 package.json 已定义下列脚本；没有时按 README 的本地联调方式操作：
 
 ```bash
 pnpm framework:status
@@ -78,8 +72,6 @@ pnpm framework:use:local <package>
 pnpm framework:watch <package>
 ```
 
----
-
 ## 漂移检查清单
 
 - [ ] framework 模板和应用 `.agents/skills` 对同名 skill 内容一致，除非 PR 明确说明本地覆盖
@@ -89,8 +81,6 @@ pnpm framework:watch <package>
 - [ ] 本地联调结束后可恢复 npm 模式
 - [ ] README 或 PR 描述说明双仓改动顺序
 
----
-
 ## 禁止事项
 
 - ❌ 只改应用 `.agents/skills`，忘记更新 hai-framework 模板中的通用规范
@@ -99,8 +89,6 @@ pnpm framework:watch <package>
 - ❌ 把聊天记录原文、token、私有 URL 写入模板
 - ❌ 双仓 PR 没有关联 issue 或同步说明
 
----
-
 ## 相关 Skills
 
 - `hai-ci` — CI 对 npm/local framework 模式的验证策略