@h-ai/cli 0.1.0-alpha.10

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

@@ -0,0 +1,220 @@
+---
+name: hai-datapipe
+description: 使用 @h-ai/datapipe 进行文本清洗（HTML/URL/空白移除）、多模式分块（句子/段落/Markdown/字符/自定义）和管线组合；当需求涉及文本预处理、文档分块、数据清洗或 RAG 入库前处理时使用。
+---
+
+# 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 })
+
+// 分块
+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`
+
+```typescript
+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`
+
+```typescript
+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 模型

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

@@ -0,0 +1,216 @@
+---
+name: hai-deploy
+description: 使用 @h-ai/deploy 进行自动化部署：Vercel 部署 + 基础设施开通（Neon/Upstash/R2/Resend/Aliyun）；当需求涉及应用部署、环境配置、凭证管理或云服务开通时使用。
+---
+
+# hai-deploy
+
+> `@h-ai/deploy` 提供自动化部署能力，将 SvelteKit 应用部署到 Vercel，并自动开通 PostgreSQL (Neon)、Redis (Upstash)、S3 (Cloudflare R2)、邮件 (Resend)、短信 (阿里云) 等基础设施服务。
+
+---
+
+## 运行环境
+
+> ⚠️ **Node.js CLI / 服务端模块。** 通过 `hai deploy` CLI 命令或在 Node.js 脚本中使用。
+
+---
+
+## 适用场景
+
+- 一键部署 SvelteKit 应用到 Vercel
+- 自动开通 PostgreSQL、Redis、S3 等云服务
+- 管理部署凭证（~/.hai/credentials.yml）
+- 扫描应用依赖，自动检测所需服务
+- CLI 部署流程（`hai deploy`）
+
+---
+
+## 使用步骤
+
+### 1. 配置
+
+```yaml
+# config/_deploy.yml
+provider:
+  type: vercel
+  token: ${HAI_DEPLOY_VERCEL_TOKEN}
+
+services:
+  db:
+    provisioner: neon
+    apiKey: ${HAI_DEPLOY_NEON_API_KEY}
+  cache:
+    provisioner: upstash
+    email: ${HAI_DEPLOY_UPSTASH_EMAIL}
+    apiKey: ${HAI_DEPLOY_UPSTASH_API_KEY}
+  storage:
+    provisioner: cloudflare-r2
+    accountId: ${HAI_DEPLOY_CF_ACCOUNT_ID}
+    apiToken: ${HAI_DEPLOY_CF_API_TOKEN}
+  email:
+    provisioner: resend
+    apiKey: ${HAI_DEPLOY_RESEND_API_KEY}
+  sms:
+    provisioner: aliyun
+    accessKeyId: ${HAI_DEPLOY_ALIYUN_ACCESS_KEY_ID}
+    accessKeySecret: ${HAI_DEPLOY_ALIYUN_ACCESS_KEY_SECRET}
+```
+
+### 2. 初始化与关闭
+
+```typescript
+import { deploy } from '@h-ai/deploy'
+
+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')
+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 — 已设置的环境变量列表
+}
+```
+
+---
+
+## 核心 API
+
+| 方法                   | 签名                                                                       | 说明         |
+| ---------------------- | -------------------------------------------------------------------------- | ------------ |
+| `deploy.init`          | `(config: DeployConfigInput) => Promise<HaiResult<void>>`        | 初始化模块   |
+| `deploy.close`         | `() => Promise<void>`                                                      | 关闭模块     |
+| `deploy.scan`          | `(appDir: string) => Promise<HaiResult<ScanResult>>`             | 扫描应用     |
+| `deploy.provisionAll`  | `(projectName: string) => Promise<HaiResult<ProvisionResult[]>>` | 开通所有服务 |
+| `deploy.deployApp`     | `(appDir: string, options?) => Promise<HaiResult<DeployResult>>` | 完整部署     |
+| `deploy.config`        | `DeployConfig \| null`                                                     | 当前配置     |
+| `deploy.isInitialized` | `boolean`                                                                  | 初始化状态   |
+
+---
+
+## 凭证管理
+
+| 函数                         | 说明                                       |
+| ---------------------------- | ------------------------------------------ |
+| `loadCredentials()`          | 加载 ~/.hai/credentials.yml 到 process.env |
+| `saveCredential(key, value)` | 保存单个凭证                               |
+| `saveCredentials(entries)`   | 批量保存凭证                               |
+| `getCredentialsPath()`       | 获取凭证文件路径                           |
+
+---
+
+## 错误码 — `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.ENV_VAR_FAILED`        | `hai:deploy:010`   | 环境变量设置失败         |
+| `HaiDeployError.NOT_INITIALIZED`       | `hai:deploy:011`   | 模块未初始化             |
+| `HaiDeployError.UNSUPPORTED_TYPE`      | `hai:deploy:012`   | 不支持的类型             |
+| `HaiDeployError.CONFIG_ERROR`          | `hai:deploy:013`   | 配置错误                 |
+| `HaiDeployError.CREDENTIAL_ERROR`      | `hai:deploy:014`   | 凭证读写失败             |
+
+---
+
+## CLI 命令
+
+```bash
+# 部署当前目录
+hai deploy
+
+# 部署指定应用
+hai deploy ./apps/admin-console
+
+# 跳过基础设施开通
+hai deploy --skip-provision
+
+# 跳过构建
+hai deploy --skip-build
+
+# 自定义项目名
+hai deploy --project-name my-custom-name
+```
+
+---
+
+## 常见模式
+
+### 仅部署（跳过基础设施）
+
+```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
+
+- **hai-core** — 配置加载、日志、HaiResult 类型
+- **hai-reldb** — 数据库（Neon PostgreSQL）
+- **hai-cache** — 缓存（Upstash Redis）