@h-ai/cli 0.1.0-alpha9 → 1.0.0-beta.2

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

@@ -1,315 +1,43 @@
 ---
 name: hai-reach
-description: 使用 @h-ai/reach 进行邮件、短信和 API 回调发送；当需求涉及用户触达、消息通知、验证码发送、多渠道模板管理时使用。
+description: "接入邮件、短信、API 通知与模板，处理发送结果、免打扰和可靠延迟入队。"
 ---
 
 # hai-reach
 
-> `@h-ai/reach` 提供统一的用户触达接口，支持同时注册多个 Provider（SMTP 邮件、短信、API 回调），内置模板引擎与免打扰（DND）机制。
+## 能力契约
 
----
-
-## 运行环境
-
-> ⚠️ **服务端模块（Node.js only）。** 浏览器端不直接发送邮件/短信，而是通过 API 端点触发服务端 `reach.send()`。
-
----
-
-## 依赖
-
-| 模块 | 用途 | 是否必需 | 初始化要求 |
-| --- | --- | --- | --- |
-| `@h-ai/reldb` | 数据库（发送日志与模板持久化） | 可选 | 已初始化时自动启用持久化 |
-| `@h-ai/cache` | 缓存（DND delay 策略分布式锁） | 可选 | 已初始化时自动启用分布式锁 |
-
----
-
-## 适用场景
-
-- 同时使用邮件、短信、API 回调发送通知
-- 发送邮件通知（注册欢迎、密码重置、告警等）
-- 发送短信验证码或通知
-- 通过 HTTP API 回调触发第三方通知
-- 定义和管理消息模板（模板绑定到具体 Provider，支持配置文件定义）
-- 免打扰时段控制
-- 基于 `HaiReachError` 做错误分支处理
-
----
-
-## 使用步骤
+| 项目 | 契约 |
+| --- | --- |
+| 能力 | 使用 @h-ai/reach 配置邮件、短信、API 通知和多渠道消息模板 |
+| 适用场景 | 配置业务通知、验证码渠道或发送模板 |
+| 输入 | ReachConfigInput、Provider、模板、收件人与模板参数 |
+| 输出 | 发送和模板操作的 HaiResult |
+| 限制 | 仅服务端；模板绑定 Provider，遵守 DND。区分测试与真实发送，不记录验证码或收件人敏感内容。 |
 
-### 1. 配置
+API 空 2xx 表示受理成功；非空 JSON 回执上限 64 KiB。redirect 默认 error，敏感消息始终拒绝跳转；requireHttps:true 与 follow 互斥，生产敏感消息省略时要求 HTTPS。未知副作用不自动重投，不输出接收端正文。
 
-```yaml
-# config/_reach.yml
-providers:
-  - name: email
-    type: smtp
-    host: ${HAI_REACH_SMTP_HOST:smtp.example.com}
-    port: ${HAI_REACH_SMTP_PORT:465}
-    secure: true
-    user: ${HAI_REACH_SMTP_USER:}
-    pass: ${HAI_REACH_SMTP_PASS:}
-    from: ${HAI_REACH_SMTP_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:}
-  - name: webhook
-    type: api
-    url: ${HAI_REACH_WEBHOOK_URL:}
+## 使用路径
 
-# 模板（可选，也可通过代码注册）
-templates:
-  - name: verification_code
-    provider: email
-    subject: '验证码: {code}'
-    body: '您的验证码是 {code}，有效期 {minutes} 分钟。'
-  - name: sms_code
-    provider: sms
-    body: '验证码: {code}，{minutes} 分钟内有效。'
+- 先配置并注册 Provider，再保存绑定 Provider 的模板；模板发送只传 template/to/vars 即可，显式 provider 可覆盖；直接发送须提供 provider。启用 DND delay 必须先初始化 reldb 并确保队列表可用；成功时 `deferred: true` 与 `queueId` 表示可靠入队，尚未投递；缺库、断连或插入失败须按 HaiResult 失败处理。即时投递与排队状态须区分。
+- 验证模板替换和错误分支时使用隔离测试收件人；真实通知须在用户授权范围内。
+- 缓存锁只减少扫描，按实际执行逐条领取并在途续租。API 只有接收端真正具备原子持久去重时才能声明 idempotent=true，全部请求固定用 queueId 作为 Idempotency-Key；旧节点迟到请求也必须去重。SMTP/短信/默认 API 的在途失败或过期转 unknown，禁止自动重发；可信服务端用 queue.get/resolveUnknown 在人工隔离旧 worker、核对外部记录后裁定 sent/discarded。
+- queue 重试策略随消息持久保存，默认最多领取 5 次，指数退避 60 秒至 1 小时；永久失败/超限进 dead，满批失败不会原地自旋。可信服务端用 queue.list 查询 dead/unknown；修复根因后以最新 updatedAt 调用 requeueDead，只能恢复 dead，保留同一 queueId 和接收端幂等要求。unknown 不能重排。
 
-# 免打扰（可选）
-dnd:
-  enabled: true
-  strategy: delay # discard（丢弃）或 delay（延时，DND 结束后集中发送）
-  start: '22:00'
-  end: '08:00'
-```
-
-### 2. 初始化与关闭
-
-```typescript
-import { cache } from '@h-ai/cache'
-import { core } from '@h-ai/core'
-import { reach } from '@h-ai/reach'
-import { reldb } from '@h-ai/reldb'
-
-// 先初始化可选依赖（按需）
-await reldb.init(core.config.get('db')) // 可选，启用发送日志与模板持久化
-await cache.init(core.config.get('cache')) // 可选，启用 DND delay 策略分布式锁
-
-// 再初始化触达模块（自动检测已初始化的 reldb/cache 单例）
-await reach.init(core.config.get('reach'))
-// ... 使用触达服务
-await reach.close()
-```
-
-### 3. 保存模板（模板绑定 Provider）
-
-```typescript
-// 通过代码保存（配置文件中的模板在 init 时自动注册）
-await reach.template.save({
-  name: 'verification_code',
-  provider: 'email',
-  subject: '验证码: {code}',
-  body: '您的验证码是 {code}，有效期 {minutes} 分钟。',
-})
-
-await reach.template.saveBatch([
-  { name: 'welcome', provider: 'email', subject: '欢迎 {userName}', body: '亲爱的 {userName}，欢迎使用 {appName}！' },
-  { name: 'sms_code', provider: 'sms', body: '验证码: {code}，{minutes} 分钟内有效。' },
-])
-```
-
-### 4. 发送消息
-
-```typescript
-// 使用模板发送邮件（指定 provider）
-const result = await reach.send({
-  provider: 'email',
-  to: 'user@example.com',
-  template: 'verification_code',
-  vars: { code: '123456', minutes: '5' },
-})
-
-// 直接发送邮件（无模板）
-await reach.send({
-  provider: 'email',
-  to: 'user@example.com',
-  subject: '通知',
-  body: '<h1>Hello</h1>',
-})
-
-// 发送短信（通过 extra 传递 Provider 特有参数）
-await reach.send({
-  provider: 'sms',
-  to: '13800138000',
-  extra: { templateCode: 'SMS_123456' },
-  vars: { code: '654321' },
-})
-
-// API 回调
-await reach.send({
-  provider: 'webhook',
-  to: 'user@example.com',
-  body: '{"event":"signup"}',
-})
-```
-
----
+## 按需参考
 
-## 核心 API
+按任务读取 [reference.md](reference.md) 的对应小节；签名以当前源码或安装版本的公开类型为准，不默认加载全部资料。示例中的业务变量由应用提供。
 
-### reach 对象
-
-| 方法 / 属性           | 签名                                                     | 说明                               |
-| --------------------- | -------------------------------------------------------- | ---------------------------------- |
-| `reach.init`          | `(config: ReachConfigInput) => Promise<HaiResult<void>>`    | 初始化（注册多个 Provider）        |
-| `reach.send`          | `(message: ReachMessage) => Promise<HaiResult<SendResult>>` | 发送消息（通过 provider 字段路由） |
-| `reach.template`      | `ReachTemplateRegistry`                                  | 模板注册表                         |
-| `reach.config`        | `ReachConfig \| null`                                    | 当前配置                           |
-| `reach.isInitialized` | `boolean`                                                | 是否已初始化                       |
-| `reach.close`         | `() => Promise<void>`                                    | 关闭所有连接                       |
-
-### ReachConfigInput
-
-```typescript
-interface ReachConfigInput {
-  providers: ProviderConfig[] // 多个 Provider 配置
-  templates?: TemplateConfig[] // 通过配置文件定义的模板
-  dnd?: {
-    enabled: boolean // 是否启用
-    strategy: 'discard' | 'delay' // discard 丢弃 / delay 延时发送
-    start: string // 开始时间 HH:mm
-    end: string // 结束时间 HH:mm
-  }
-}
-```
-
-### ReachMessage
-
-| 字段       | 类型                      | 必填 | 说明                                |
-| ---------- | ------------------------- | ---- | ----------------------------------- |
-| `provider` | `string`                  | ✅   | 目标 Provider 名称                  |
-| `to`       | `string`                  | ✅   | 接收方（邮箱或手机号）              |
-| `subject`  | `string`                  | —    | 邮件主题（直接发送时）              |
-| `body`     | `string`                  | —    | 消息正文（直接发送时）              |
-| `template` | `string`                  | —    | 模板名称（模板发送时）              |
-| `vars`     | `Record<string, string>`  | —    | 模板变量                            |
-| `extra`    | `Record<string, unknown>` | —    | Provider 扩展参数（如短信模板编码） |
-
-### ReachTemplate（模板绑定 Provider）
-
-| 字段       | 类型     | 必填 | 说明                 |
-| ---------- | -------- | ---- | -------------------- |
-| `name`     | `string` | ✅   | 模板名称             |
-| `provider` | `string` | ✅   | 绑定的 Provider 名称 |
-| `subject`  | `string` | —    | 邮件主题模板         |
-| `body`     | `string` | ✅   | 正文模板             |
-
----
-
-## 错误码
-
-| 错误码 | code | 说明 |
-|--------|------|------|
-| `HaiReachError.SEND_FAILED`            | `hai:reach:001`   | 发送失败        |
-| `HaiReachError.TEMPLATE_NOT_FOUND`     | `hai:reach:002`   | 模板未找到      |
-| `HaiReachError.TEMPLATE_RENDER_FAILED` | `hai:reach:003`   | 模板渲染失败    |
-| `HaiReachError.INVALID_RECIPIENT`      | `hai:reach:004`   | 无效接收方      |
-| `HaiReachError.PROVIDER_NOT_FOUND`     | `hai:reach:005`   | Provider 未找到 |
-| `HaiReachError.DND_BLOCKED`            | `hai:reach:006`   | 免打扰丢弃      |
-| `HaiReachError.DND_DEFERRED`           | `hai:reach:007`   | 免打扰延时暂存  |
-| `HaiReachError.NOT_INITIALIZED`        | `hai:reach:010`   | 模块未初始化    |
-| `HaiReachError.UNSUPPORTED_TYPE`       | `hai:reach:011`   | 不支持的类型    |
-| `HaiReachError.CONFIG_ERROR`           | `hai:reach:012`   | 配置错误        |
-
----
-
-## 常见模式
-
-### 多渠道验证码发送
-
-```typescript
-reach.template.save({
-  name: 'email_code',
-  provider: 'email',
-  subject: '验证码: {code}',
-  body: '您的验证码是 {code}，有效期 {minutes} 分钟。',
-})
-
-reach.template.save({
-  name: 'sms_code',
-  provider: 'sms',
-  body: '验证码: {code}，{minutes} 分钟内有效。',
-})
-
-// 根据用户选择的渠道发送
-async function sendCode(channel: 'email' | 'sms', target: string, code: string) {
-  const template = channel === 'email' ? 'email_code' : 'sms_code'
-  return reach.send({
-    provider: channel,
-    to: target,
-    template,
-    vars: { code, minutes: '5' },
-  })
-}
-```
-
-### 与 IAM 集成（密码重置 / OTP 验证码）
-
-```typescript
-import { iam } from '@h-ai/iam'
-import { reach } from '@h-ai/reach'
-
-// 初始化 reach（注册 email 和 sms Provider）
-await reach.init({
-  providers: [
-    { name: 'email', type: 'smtp', host: 'smtp.example.com', from: 'noreply@example.com' },
-    { name: 'sms', type: 'aliyun-sms', accessKeyId: '...', accessKeySecret: '...', signName: '...' },
-  ],
-  templates: [
-    { name: 'password_reset', provider: 'email', subject: 'Password Reset', body: 'Token: {token}, expires: {expiresAt}' },
-    { name: 'otp_email', provider: 'email', subject: 'Code: {code}', body: 'Your code is {code}' },
-    { name: 'otp_sms', provider: 'sms', body: 'Your code is {code}' },
-  ],
-})
-
-// 初始化 IAM，使用 reach 发送通知
-await iam.init({
-  db,
-  cache,
-  onPasswordResetRequest: async (user, token, expiresAt) => {
-    await reach.send({ provider: 'email', to: user.email ?? '', template: 'password_reset', vars: { token, expiresAt: expiresAt.toISOString() } })
-  },
-  onOtpSendEmail: async (email, code) => {
-    await reach.send({ provider: 'email', to: email, template: 'otp_email', vars: { code } })
-  },
-  onOtpSendSms: async (phone, code) => {
-    await reach.send({ provider: 'sms', to: phone, template: 'otp_sms', vars: { code } })
-  },
-})
-```
-
-### 错误处理
-
-```typescript
-import { HaiReachError } from '@h-ai/reach'
-
-const result = await reach.send(message)
-if (!result.success) {
-  switch (result.error.code) {
-    case HaiReachError.NOT_INITIALIZED.code:
-      break
-    case HaiReachError.PROVIDER_NOT_FOUND.code:
-      break
-    case HaiReachError.DND_BLOCKED.code:
-      // 免打扰时段（discard 策略），消息已丢弃
-      break
-    case HaiReachError.TEMPLATE_NOT_FOUND.code:
-      break
-    case HaiReachError.SEND_FAILED.code:
-      break
-  }
-}
-```
-
----
+- 运行环境
+- 依赖
+- 适用场景
+- 使用步骤
+- 核心 API
+- 错误码
+- 常见模式
+- 租约、接收端幂等与未知结果
+- 相关 Skills
 
-## 相关 Skills
+IAM 通知使用 `otp_email`、`otp_sms`、`password_reset`、`password_reset_sms` 标准模板；将已初始化的 `reach` 传入 `iam.init`。Console Provider 只记录元数据，不输出验证码/令牌，不代替实际邮件/短信发送。
 
-- `hai-core` — 配置加载、日志、HaiResult 模式
-- `hai-reldb` — 数据库操作（存储发送记录等）
-- `hai-cache` — 缓存操作、分布式锁（DND flush 互斥）
+凭据通知用 sensitive:true、Unix 毫秒 expiresAt 和无凭据的稳定 idempotencyKey。共享 DB 仅存元数据回执，不存正文/变量/凭据摘要，不延迟重投；成功返回 receiptId，不明结果不自动重发。开发 Console 明确允许的输出与持久观察器隔离，生产 Console 限制不变。普通通知可用 deferPolicy: reject 将排队交给调用方。升级先 migrateReach({dryRun:true})，旧载荷一次性退役，旧在途 unknown，先备份停旧写入。