@h-ai/cli 0.1.0-alpha5

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

@@ -0,0 +1,183 @@
+---
+name: hai-crypto
+description: 使用 @h-ai/crypto 进行加密（非对称/哈希/对称）与密码哈希；当需求涉及加密、解密、签名、验签、哈希、密码存储或密钥管理时使用。
+---
+
+# hai-crypto
+
+> `@h-ai/crypto` 提供非对称加密、哈希、对称加密与密码哈希能力，支持 Node.js 与浏览器双端。
+
+---
+
+## 适用场景
+
+- 非对称加密/解密、签名/验签、密钥生成
+- 哈希计算与 HMAC
+- 对称加密/解密（ECB/CBC 模式）
+- 密码存储与验证（加盐迭代哈希）
+
+---
+
+## 使用步骤
+
+### 1. 初始化与关闭
+
+```typescript
+import { crypto } from '@h-ai/crypto'
+
+await crypto.init()
+
+// 使用后关闭
+await crypto.close()
+```
+
+---
+
+## 核心 API
+
+### 非对称加密 — `crypto.asymmetric`
+
+| 方法                | 签名                                                        | 说明         |
+| ------------------- | ----------------------------------------------------------- | ------------ |
+| `generateKeyPair`   | `() => HaiResult<KeyPair>`                                     | 生成密钥对   |
+| `encrypt`           | `(data, publicKey, options?) => HaiResult<string>`             | 公钥加密     |
+| `decrypt`           | `(ciphertext, privateKey, options?) => HaiResult<string>`      | 私钥解密     |
+| `sign`              | `(data, privateKey, options?) => HaiResult<string>`            | 私钥签名     |
+| `verify`            | `(data, signature, publicKey, options?) => HaiResult<boolean>` | 公钥验签     |
+| `isValidPublicKey`  | `(key: string) => boolean`                                  | 校验公钥格式 |
+| `isValidPrivateKey` | `(key: string) => boolean`                                  | 校验私钥格式 |
+
+```typescript
+const keyPair = crypto.asymmetric.generateKeyPair()
+if (keyPair.success) {
+  const { publicKey, privateKey } = keyPair.data
+
+  const encrypted = crypto.asymmetric.encrypt('敏感数据', publicKey)
+  if (encrypted.success) {
+    const decrypted = crypto.asymmetric.decrypt(encrypted.data, privateKey)
+  }
+
+  const signature = crypto.asymmetric.sign('待签名数据', privateKey)
+  if (signature.success) {
+    const valid = crypto.asymmetric.verify('待签名数据', signature.data, publicKey)
+  }
+}
+```
+
+**AsymmetricEncryptOptions**：`{ cipherMode?: 0 | 1, outputFormat?: 'hex' | 'base64' }`
+**SignOptions**：`{ hash?: boolean, userId?: string }`
+
+### 哈希 — `crypto.hash`
+
+| 方法     | 签名                                                       | 说明     |
+| -------- | ---------------------------------------------------------- | -------- |
+| `hash`   | `(data: string \| Uint8Array, options?) => HaiResult<string>` | 哈希     |
+| `hmac`   | `(data, key) => HaiResult<string>`                            | HMAC     |
+| `verify` | `(data, expectedHash) => HaiResult<boolean>`                  | 验证哈希 |
+
+```typescript
+const hash = crypto.hash.hash('hello')
+const hmac = crypto.hash.hmac('hello', 'secret-key')
+const valid = crypto.hash.verify('hello', hash.data!)
+```
+
+**HashOptions**：`{ inputEncoding?: 'utf8' | 'hex' }`
+
+### 对称加密 — `crypto.symmetric`
+
+| 方法            | 签名                                            | 说明                        |
+| --------------- | ----------------------------------------------- | --------------------------- |
+| `generateKey`   | `() => string`                                  | 生成 128-bit 密钥（32 hex） |
+| `generateIV`    | `() => string`                                  | 生成随机 IV（32 hex）       |
+| `encrypt`       | `(data, key, options?) => HaiResult<string>`       | 加密                        |
+| `decrypt`       | `(ciphertext, key, options?) => HaiResult<string>` | 解密                        |
+| `encryptWithIV` | `(data, key) => HaiResult<EncryptWithIVResult>`    | CBC 模式加密（自动生成 IV） |
+| `decryptWithIV` | `(ciphertext, key, iv) => HaiResult<string>`       | CBC 模式解密                |
+| `deriveKey`     | `(password, salt) => string`                    | 从密码和盐值派生密钥        |
+| `isValidKey`    | `(key: string) => boolean`                      | 校验密钥格式                |
+| `isValidIV`     | `(iv: string) => boolean`                       | 校验 IV 格式                |
+
+```typescript
+const key = crypto.symmetric.generateKey()
+const result = crypto.symmetric.encryptWithIV('明文数据', key)
+if (result.success) {
+  const decrypted = crypto.symmetric.decryptWithIV(result.data.ciphertext, key, result.data.iv)
+}
+```
+
+**SymmetricOptions**：`{ mode?: 'ecb' | 'cbc', iv?: string, inputEncoding?: 'utf8' | 'hex', outputFormat?: 'hex' | 'base64' }`
+
+### 密码哈希 — `crypto.password`
+
+| 方法     | 签名                                    | 说明     |
+| -------- | --------------------------------------- | -------- |
+| `hash`   | `(password, config?) => HaiResult<string>` | 密码哈希 |
+| `verify` | `(password, hash) => HaiResult<boolean>`   | 验证密码 |
+
+```typescript
+const hashed = crypto.password.hash('MyPassword123')
+if (hashed.success) {
+  const valid = crypto.password.verify('MyPassword123', hashed.data)
+}
+```
+
+哈希格式：`$hai$<iterations>$<salt>$<hash>`
+**PasswordConfig**：`{ saltLength?: number, iterations?: number }`
+
+---
+
+## 错误码 — `HaiCryptoError`
+
+| 错误码 | code | 说明 |
+|--------|------|------|
+| `HaiCryptoError.INVALID_INPUT` | `hai:crypto:002` | 无效输入 |
+| `HaiCryptoError.INVALID_KEY` | `hai:crypto:003` | 无效密钥 |
+| `HaiCryptoError.NOT_INITIALIZED` | `hai:crypto:010` | 未初始化 |
+| `HaiCryptoError.INIT_FAILED` | `hai:crypto:011` | 初始化失败 |
+| `HaiCryptoError.KEY_GENERATION_FAILED` | `hai:crypto:020` | 密钥生成失败 |
+| `HaiCryptoError.ENCRYPTION_FAILED` | `hai:crypto:021` | 加密失败 |
+| `HaiCryptoError.DECRYPTION_FAILED` | `hai:crypto:022` | 解密失败 |
+| `HaiCryptoError.SIGN_FAILED` | `hai:crypto:023` | 签名失败 |
+| `HaiCryptoError.VERIFY_FAILED` | `hai:crypto:024` | 验签失败 |
+| `HaiCryptoError.HASH_FAILED` | `hai:crypto:040` | 哈希计算失败 |
+| `HaiCryptoError.HMAC_FAILED` | `hai:crypto:041` | HMAC 计算失败 |
+| `HaiCryptoError.INVALID_IV` | `hai:crypto:060` | 无效 IV |
+
+---
+
+## 常见模式
+
+### 数据加密存储
+
+```typescript
+const key = process.env.HAI_CRYPTO_DATA_KEY!
+const encrypted = crypto.symmetric.encrypt(sensitiveData, key)
+// 存入数据库
+
+// 读取时解密
+const decrypted = crypto.symmetric.decrypt(storedData, key)
+```
+
+### 密码存储与验证
+
+```typescript
+// 注册时哈希存储
+const hashResult = crypto.password.hash(userPassword)
+if (hashResult.success) {
+  // 存储 hashResult.data 到数据库
+}
+
+// 登录时验证
+const verifyResult = crypto.password.verify(inputPassword, storedHash)
+if (verifyResult.success && verifyResult.data) {
+  // 密码匹配
+}
+```
+
+---
+
+## 相关 Skills
+
+- `hai-core`：配置与 HaiResult 模型
+- `hai-iam`：密码哈希（内部自动调用 crypto.password）
+- `hai-kit`：SvelteKit 集成（传输加密）

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

@@ -0,0 +1,214 @@
+---
+name: hai-datapipe
+description: 使用 @h-ai/datapipe 进行文本清洗（HTML/URL/空白移除）、多模式分块（句子/段落/Markdown/字符/自定义）和管线组合；当需求涉及文本预处理、文档分块、数据清洗或 RAG 入库前处理时使用。
+---
+
+# hai-datapipe
+
+> `@h-ai/datapipe` 提供文本清洗（clean）、多模式分块（chunk）和可组合管线（pipeline），纯函数模块，无需初始化。
+
+---
+
+## 适用场景
+
+- 文本清洗：移除 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,210 @@
+---
+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)、短信 (阿里云) 等基础设施服务。
+
+---
+
+## 适用场景
+
+- 一键部署 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）