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

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

@@ -1,6 +1,6 @@
 ---
 name: hai-reach
-description: "接入邮件、短信、API 通知与模板，处理发送结果、免打扰和可选持久化。"
+description: "接入邮件、短信、API 通知与模板，处理发送结果、免打扰和可靠延迟入队。"
 ---
 
 # hai-reach
@@ -17,8 +17,10 @@ description: "接入邮件、短信、API 通知与模板，处理发送结果
 
 ## 使用路径
 
-- 先配置并注册 Provider，再保存绑定 Provider 的模板；模板发送只传 template/to/vars 即可，显式 provider 可覆盖；直接发送须提供 provider。发送结果须检查，DND/禁用与成功发送区分。
+- 先配置并注册 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 不能重排。
 
 ## 按需参考
 
@@ -31,6 +33,7 @@ description: "接入邮件、短信、API 通知与模板，处理发送结果
 - 核心 API
 - 错误码
 - 常见模式
+- 租约、接收端幂等与未知结果
 - 相关 Skills
 
 IAM 通知使用 `otp_email`、`otp_sms`、`password_reset`、`password_reset_sms` 标准模板；将已初始化的 `reach` 传入 `iam.init`。Console Provider 只记录元数据，不输出验证码/令牌，不代替实际邮件/短信发送。

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

@@ -12,7 +12,7 @@
 
 | 模块 | 用途 | 是否必需 | 初始化要求 |
 | --- | --- | --- | --- |
-| `@h-ai/reldb` | 数据库（发送日志与模板持久化） | 可选 | 已初始化时自动启用持久化 |
+| `@h-ai/reldb` | 数据库（发送日志与模板持久化） | DND delay 必需；其他场景可选 | 启用 delay 前先初始化，队列表不可用则 reach.init 返回 CONFIG_ERROR |
 | `@h-ai/cache` | 缓存（DND delay 策略分布式锁） | 可选 | 已初始化时自动启用分布式锁 |
 
 ## 适用场景
@@ -48,6 +48,7 @@ providers:
   - name: webhook
     type: api
     url: ${HAI_REACH_WEBHOOK_URL:}
+    idempotent: false # 只有接收端按 Idempotency-Key 原子、持久化去重时才能设 true
 
 # 模板（可选，也可通过代码注册）
 templates:
@@ -62,7 +63,7 @@ templates:
 # 免打扰（可选）
 dnd:
   enabled: true
-  strategy: delay # discard（丢弃）或 delay（延时，DND 结束后集中发送）
+  strategy: delay # 必须先初始化 reldb；确认持久化成功后才返回 deferred 与 queueId
   start: '22:00'
   end: '08:00'
 ```
@@ -80,12 +81,18 @@ 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 策略分布式锁
+// 当前配置启用了 delay：数据库和队列表为必需依赖。
+const database = await reldb.init(core.config.get('db'))
+if (!database.success)
+  throw new Error(database.error.message)
+const cached = await cache.init(core.config.get('cache')) // 可选，启用 flush 分布式锁
+if (!cached.success)
+  throw new Error(cached.error.message)
 
 // 再初始化触达模块（自动检测已初始化的 reldb/cache 单例）
-await reach.init(core.config.get('reach'))
+const initialized = await reach.init(core.config.get('reach'))
+if (!initialized.success)
+  throw new Error(initialized.error.message)
 // ... 使用触达服务
 await reach.close()
 ```
@@ -119,6 +126,12 @@ const result = await reach.send({
   template: 'verification_code',
   vars: { code: '123456', minutes: '5' },
 })
+if (!result.success)
+  throw new Error(result.error.message)
+if (result.data.deferred) {
+  // queueId 是 hai_reach_send_log.queue_id 中的回执 UUID；此时尚未投递。
+  await savePendingReceipt(result.data.queueId)
+}
 
 // 直接发送邮件（无模板）
 await reach.send({
@@ -152,6 +165,10 @@ await reach.send({
 | --------------------- | -------------------------------------------------------- | ---------------------------------- |
 | `reach.init`          | `(config: ReachConfigInput) => Promise<HaiResult<void>>`    | 初始化（注册多个 Provider）        |
 | `reach.send`          | `(message: ReachMessage) => Promise<HaiResult<SendResult>>` | 发送消息（通过 provider 字段路由） |
+| `reach.queue.get` | `(queueId: string) => Promise<HaiResult<ReachQueueEntry \| null>>` | 不含正文/收件人的队列状态 |
+| `reach.queue.list` | `(options: ReachQueueListOptions) => Promise<HaiResult<ReachQueueEntry[]>>` | 可信服务端分页查询 dead/unknown，每页至多 100 条 |
+| `reach.queue.requeueDead` | `(queueId: string, options: ReachDeadRequeue) => Promise<HaiResult<void>>` | 按 expectedUpdatedAt 条件恢复 dead；unknown 禁止重排 |
+| `reach.queue.resolveUnknown` | `(queueId: string, resolution: ReachUnknownResolution) => Promise<HaiResult<void>>` | 人工核对后将 unknown 裁定为 sent/discarded，不发送 |
 | `reach.template`      | `ReachTemplateRegistry`                                  | 模板注册表                         |
 | `reach.config`        | `ReachConfig \| null`                                    | 当前脱敏配置快照                   |
 | `reach.isInitialized` | `boolean`                                                | 是否已初始化                       |
@@ -183,6 +200,7 @@ interface ReachConfigInput {
 | `template` | `string`                  | —    | 模板名称（模板发送时）              |
 | `vars`     | `Record<string, string>`  | —    | 模板变量                            |
 | `extra`    | `Record<string, unknown>` | —    | Provider 扩展参数（如短信模板编码） |
+| `idempotencyKey` | `string` | — | 直接 API 请求可指定；队列投递由框架固定为 queueId |
 
 ### ReachTemplate（模板绑定 Provider）
 
@@ -198,18 +216,63 @@ interface ReachConfigInput {
 | 错误码 | code | 说明 |
 |--------|------|------|
 | `HaiReachError.SEND_FAILED`            | `hai:reach:001`   | 发送失败        |
+| `HaiReachError.DELIVERY_REJECTED`      | `hai:reach:020`   | API 明确永久拒绝 |
 | `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`   | 配置错误        |
 
 ## 常见模式
 
+### 可靠延迟入队
+
+启用 delay 后，只有数据库确认插入一条 pending 记录才返回 `deferred: true` 和 `queueId`。缺库、断连、插入失败返回失败 HaiResult，不能向用户报告已入队。`queueId` 对应 `hai_reach_send_log.queue_id`，同一行的 `status` 为 pending / processing / sending / unknown / sent / discarded / dead。节点重启后连接同一数据库、配置同名 Provider，可在 DND 时段外恢复投递。即时发送后的普通日志仍为可选，日志失败不会使已发送消息返回失败。
+
+验证码和密码重置等有时效的通知应明确选择 DND 策略；可靠入队成功不代表用户已收到验证码。
+
+队列 `created_at` / `updated_at` / `locked_until` / `next_attempt_at` 均为 Unix 毫秒 `BIGINT`（SQLite 为 64 位 INTEGER）；仓库把 driver 的字符串/数字归一化为安全整数 number，并拒绝负数、小数和不安全整数。模板仓库的 TIMESTAMP 时间返回 Date。已有表须在部署时同步列结构，包含次数、退避策略和失败分类，模块不自动迁移旧表；跨库验收必须运行 PostgreSQL/MySQL 用例，SQLite 无法证明 32 位溢出已经消除。
+
+### 租约、接收端幂等与未知结果
+
+每轮最多 100 条，逐条 claim，发送前原子写入 sending 并在途续租；过期 owner 的开始、续租、确认和释放均被拒绝。DND 时段外每分钟恢复遗留任务。cache 锁只是扫描优化，不能提供外部副作用的 exactly-once。
+
+API `idempotent: true` 是接收端能力声明：接收方必须把 queueId 对应的去重记录与业务副作用原子、持久化提交。所有尝试用相同 `Idempotency-Key` 头和 `idempotencyKey` 正文，覆盖响应丢失和旧节点恢复；去重记录须覆盖所有迟到请求，迟到无上界时不能过期。同名 Provider 的目标与幂等存储保持一致。只有此模式能自动接管已开始的 API 投递。
+
+SMTP、短信和默认 API 一旦开始投递，失败或过期转 unknown，不自动重发。未连接按持久策略退避；发送前解析失败直接进入 dead。unknown 必须在可信服务端管理流程里，先停止/隔离旧 worker 并核对第三方投递记录，再执行以下二选一裁定；discarded 不撤销已开始请求。需要补发时，先确保旧请求不可能继续生效，再创建新消息。
+
+```ts
+const state = await reach.queue.get(queueId)
+const resolved = await reach.queue.resolveUnknown(queueId, { status: 'sent', messageId: verifiedMessageId })
+if (!resolved.success)
+  throw new Error(resolved.error.message)
+```
+
+管理入口校验回执 UUID、status 与 messageId 长度，只能从 unknown 条件更新为 sent/discarded；不提供重排队选项，并发裁定仅一个成功。
+
+### 有限重试与死信运维
+
+`queue.maxAttempts` 默认 5（1–100），`retryDelayMs` 默认 60000，`maxRetryDelayMs` 默认 3600000；两项毫秒配置范围 1000–86400000，最大退避不得小于首次退避。策略随入队记录保存，不随新节点配置重置；领取（含崩溃恢复）原子累加 attemptCount。暂时故障保存 nextAttemptAt，按 `min(maxRetryDelayMs, retryDelayMs × 2^(attemptCount−1))` 退避。DND 外每分钟扫描，一轮最多 100 条且固定资格时间，失败行不会在同一轮反复领取。缺失/未连接 Provider、网络错误、HTTP 408/425/429/5xx 允许有限重试；坏 JSON、幂等 API 其它 4xx 直接 dead；超限（含最后一次领取后崩溃）停止自动处理。非幂等在途仍隔离 unknown，不能借重试预算重发。
+
+queue.get/list 返回 attemptCount、maxAttempts、nextAttemptAt、lastFailure、updatedAt 等安全元数据。lastFailure 为 provider_unavailable、invalid_message、permanent_rejection、transient_failure 或 attempts_exhausted，不保存响应正文。可信服务端以 `list({ status: 'dead', limit: 50, offset: 0 })` 分页查询，status 也可选 unknown；limit 1–100，offset 0–1000000。
+
+```ts
+// 应用先校验运维权限并修复根因；不向浏览器直接暴露队列管理。
+const state = await reach.queue.get(queueId)
+if (!state.success)
+  throw new Error(state.error.message)
+if (state.data?.status === 'dead' && state.data.updatedAt !== undefined) {
+  const restored = await reach.queue.requeueDead(queueId, { expectedUpdatedAt: state.data.updatedAt })
+  if (!restored.success)
+    throw new Error(restored.error.message)
+}
+```
+
+恢复仅匹配当前 dead 版本，过时/并发请求失败；重置次数但保留 queueId 和原策略。unknown 永远不能通过此入口重排。dead 不代表外部副作用未发生，旧幂等 API 请求仍可能迟到，恢复前确认接收端持久去重；不可修复的坏消息留在 dead 人工排查。
+
 ### 多渠道验证码发送
 
 ```typescript
@@ -244,7 +307,7 @@ import { iam } from '@h-ai/iam'
 import { reach } from '@h-ai/reach'
 
 // 初始化 reach（注册 email 和 sms Provider）
-await reach.init({
+const initializedReach = await reach.init({
   providers: [
     { name: 'email', type: 'smtp', host: 'smtp.example.com', from: 'noreply@example.com' },
     { name: 'sms', type: 'aliyun-sms', accessKeyId: '...', accessKeySecret: '...', signName: '...' },
@@ -255,23 +318,17 @@ await reach.init({
     { name: 'otp_sms', provider: 'sms', body: 'Your code is {code}' },
   ],
 })
+if (!initializedReach.success)
+  throw new Error(initializedReach.error.message)
 
-// 初始化 IAM，使用 reach 发送通知
-await iam.init({
-  db,
-  cache,
-  onPasswordResetRequest: async (user, token, expiresAt) => {
-    await reach.send({ to: user.email ?? '', template: 'password_reset', vars: { token, expiresAt: expiresAt.toISOString() } })
-  },
-  onOtpSendEmail: async (email, code) => {
-    await reach.send({ to: email, template: 'otp_email', vars: { code } })
-  },
-  onOtpSendSms: async (phone, code) => {
-    await reach.send({ to: phone, template: 'otp_sms', vars: { code } })
-  },
-})
+// 先确认 reldb/cache/Reach 已初始化成功，再注入 Reach；内置适配器传播发送失败。
+const initializedIam = await iam.init({ ...iamSettings, reach })
+if (!initializedIam.success)
+  throw new Error(initializedIam.error.message)
 ```
 
+若使用显式通知回调覆盖内置适配器，必须检查 `reach.send()` 的 HaiResult，失败时拒绝 Promise；不得吞掉入队失败。需要即时送达的验证码不应启用延迟策略。
+
 ### 错误处理
 
 ```typescript
@@ -300,3 +357,7 @@ if (!result.success) {
 - `hai-core` — 配置加载、日志、HaiResult 模式
 - `hai-reldb` — 数据库操作（存储发送记录等）
 - `hai-cache` — 缓存操作、分布式锁（DND flush 互斥）
+
+## 生产共享状态
+
+生产拒绝 console Provider，须配置真实 SMTP/短信/API 服务。console 的日志成功不是外部投递成功；非幂等服务的未知结果必须核对，不能自动重发证明 exactly-once。 NODE_ENV 或 HAI_CORE_ENV 为 production 时在初始化成功前检查，只有 HAI_E2E=1/HAI_E2E_MOCK=1 明确测试豁免。不要将租约当作最终写入条件，外部未知效果须按稳定业务键核对。

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

@@ -13,14 +13,15 @@ description: "使用 @h-ai/reldb 访问 SQLite/PostgreSQL/MySQL，编写 SQL、C
 | 适用场景 | 关系数据读写、仓库封装或事务一致性 |
 | 输入 | ReldbConfigInput、参数化 SQL、CRUD 配置、事务句柄 |
 | 输出 | DB 操作为 HaiResult；crud.table 和分页/JSON 工具按签名返回 |
-| 限制 | 仅服务端；tx.wrap 只在回调抛错时回滚，返回失败 HaiResult 不会触发回滚。动态值参数化，标识符用白名单。 |
+| 限制 | 运行时仅服务端，纯 schemas 入口可用于浏览器；tx.wrap 只在回调抛错时回滚，返回失败 HaiResult 不会触发回滚。动态值参数化，标识符用白名单。 |
 
 ## 使用路径
 
-- `_db.yml` 对应 core.config 的 db；先校验 ReldbConfigSchema，再 init 并检查 success。
+- `_db.yml` 对应 core.config 的 db；先校验 ReldbConfigSchema，再 init 并检查 success。仅做配置校验可从 `@h-ai/reldb/schemas` 导入，纯入口只依赖 Zod，不加载数据库实例/驱动，可用于 CLI 和浏览器；运行时数据库操作仍仅服务端。
 - `reldb.crud.table` / `tx.crud.table` 的 `dbType` 必填并与实际后端一致；`BaseReldbCrudRepository` 自动读取已初始化的配置。
 - 事务每步检查结果，避免把失败当普通返回值提交；同一事务操作须共享 tx。
 - SQL 值参数化；where/orderBy/json 列名不是任意用户输入。分页使用 PaginatedResult。
+- MySQL 的 pool 仅 max/acquireTimeout/queueLimit；超时返回 TIMEOUT 并移除排队项，队列满返回 POOL_EXHAUSTED，迟到建连结算前仍占槽位。min/idleTimeout/timezone 不支持。URL 优先于分字段且禁止 query/fragment；TLS 仅 false 或严格对象，默认验证证书和 DNS 身份，验证开启的 IP 目标拒绝，cert/key 成对。详见 reference 的配置章节。
 
 ## 按需参考
 
@@ -33,3 +34,5 @@ description: "使用 @h-ai/reldb 访问 SQLite/PostgreSQL/MySQL，编写 SQL、C
 - 错误码 — `HaiReldbError`
 - 常见模式
 - 相关 Skills
+
+JSON 对象合并使用 RFC 7396 补丁，必须将返回的 SQL/params 放在同一次 UPDATE 内；禁止先读对象再覆盖整个列来模拟跨节点原子合并。路径函数的后端差异和完整可类型检查示例见 [reference.md](reference.md)。

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

@@ -4,6 +4,9 @@
 
 > `@h-ai/reldb` 提供统一的数据库操作接口，支持 SQLite、PostgreSQL、MySQL，包含 DDL、SQL、CRUD 抽象、事务与分页。
 
+
+派生 `BaseReldbCrudRepository` 的自定义 SQL 方法先检查 `await this.ensureReady()`；构造函数启动自动建表不等于仓库就绪，服务 init 必须等待候选仓库的就绪入口再发布。PostgreSQL 并发首次 `CREATE TABLE IF NOT EXISTS` 的 `23505/pg_type_typname_nsp_index` 目录冲突仅重执行相同 DDL 一次，其他错误继续失败。
+
 ## 运行环境
 
 > ⚠️ **服务端模块（Node.js only）。** 浏览器端请通过 `@h-ai/api-contract` + `@h-ai/serv` 暴露的 API 端点间接访问数据库。
@@ -20,6 +23,8 @@
 
 ### 1. 配置
 
+只做校验时从 `@h-ai/reldb/schemas` 导入同一组 Schema/类型；该入口只依赖 Zod，无数据库实例或驱动。MySQL `ssl` 只接受 `false` 或严格对象；`{}` 默认开启证书链和 DNS 身份验证，不能用 `true` 或 PostgreSQL 字符串模式。实际连接仍需服务端驱动。
+
 ```yaml
 # config/_db.yml
 type: sqlite
@@ -39,20 +44,46 @@ operationLog:
 约定环境变量优先于 YAML，例如 `HAI_DB_TYPE`、`HAI_DB_DATABASE`、
 `HAI_DB_OPERATIONLOG_LEVEL`。
 
-`operationLog` 在 reldb provider-base 的 DML 操作层统一输出日志，不要在 `reldb-main.ts`、各 raw provider 或调用方重复包装。`read` 覆盖 `query/get/queryPage`，`write` 覆盖 DDL、`execute/batch` 与 `tx.begin/commit/rollback`，`maxLength` 用于截断序列化后的 SQL 参数和批量语句，`level` 默认 `debug`。
+`operationLog` 在 reldb provider-base 的 DML 操作层统一输出日志，不要在 `reldb-main.ts`、各 raw provider 或调用方重复包装。`read` 覆盖 `query/get/queryPage`，`write` 覆盖 DDL、`execute/batch` 与 `tx.begin/commit/rollback`，`maxLength` 限制安全数量摘要的字符数（0省略摘要）；SQL原文、参数值、DDL默认值和驱动错误内容不写入日志，`level` 默认 `debug`。
 
 ### 2. 初始化与关闭
 
+MySQL `pool` 仅支持 `{ max: 10, acquireTimeout: 10000, queueLimit: 1000 }`（也是省略时默认值）。`acquireTimeout` 为 1–2147483647 毫秒的整数，覆盖排队和建连；queueLimit 为正整数。SQL/DDL/CRUD/batch/tx 共用有界 FIFO，超时移除并返回 `TIMEOUT`，满额返回 `POOL_EXHAUSTED`；迟到建连结算前仍占槽位，只归还连接，不执行 SQL。close 立即取消排队，再等待借用/事务和驱动有界建连完成，不中止已启动 SQL。min/idleTimeout/mysql.timezone 明确拒绝，不承诺 MySQL 最小保留或可配置空闲回收；PostgreSQL 保留自己的 min/idleTimeout/acquireTimeout=0 契约，min 不会预建连接。
+
+MySQL 仅传 mysql:// URL 即可连接，优先于 host/port/database/user/password；无 URL 时 database 必填。禁止 URL query/fragment，pool/mysql.charset/ssl/operationLog 仍独立适用。ssl 仅 false 或严格对象，空对象默认校验证书链和 DNS 身份；ca/cert/key 为 PEM 内容，cert/key 必须成对。当前驱动不验证 IP 身份，验证开启的 IP 目标返回 CONFIG_ERROR；关闭验证有固定风险日志，加密不代表身份认证。环境变量为 HAI_DB_POOL_* / HAI_DB_SSL_*，min/idleTimeout 仅适用 PostgreSQL，queueLimit/verifyIdentity 仅适用 MySQL。
+
+```ts
+// trustedCaPem 从部署信任配置提供。
+const result = await reldb.init({ type: 'mysql', host: 'db.example.com', database: 'app', pool: { max: 10, acquireTimeout: 5000, queueLimit: 100 }, ssl: { ca: trustedCaPem } })
+if (!result.success) return result
+```
+
+PostgreSQL 空闲连接错误已监听，由池移除并在下一次查询替换；日志仅含固定说明与安全 code/name，不记录驱动错误原文。关闭会等待已借出事务完成，应用必须提交/回滚并释放句柄。
+
 ```typescript
 import { core } from '@h-ai/core'
 import { reldb } from '@h-ai/reldb'
 
 await reldb.init(core.config.get('db'))
 // ... 使用数据库
-await reldb.close()
+const closed = await reldb.close()
+if (!closed.success) throw new Error(closed.error.message)
+```
+
+
+初始化只在健康检查成功后发布连接；失败时释放候选资源。若清理仍失败，初始化错误的 `error.ext.cleanupPending` 为 `true`。`reldb.close()` 返回 `Promise<HaiResult<void>>`，等待正在进行的初始化，并合并并发关闭。开始清理后 `isInitialized` 为 `false`，配置与业务操作不再可用；清理失败仍保留资源，后续 `close()` 或 `init()` 先重试释放，成功前不会创建替代连接。调用方必须检查关闭结果。
+
+```ts
+const closed = await reldb.close()
+if (!closed.success) {
+  // 处理清理故障后有限重试；再次失败应向应用报告。
+  const retried = await reldb.close()
+  if (!retried.success) throw new Error(retried.error.message)
+}
 ```
 
-`reldb.config` 返回的是脱敏后的配置快照；数据库密码与 URL 内嵌凭证会自动隐藏。
+
+`reldb.config` 返回脱敏后的配置快照；数据库密码、URL 内嵌凭证和 TLS 私钥 `ssl.key` 会隐藏，不能用快照回放原始连接配置。
 
 ### 3. 选择操作接口
 
@@ -103,7 +134,7 @@ const columns: ReldbTableDef = {
 
 ```typescript
 interface ReldbColumnDef {
-  type: 'TEXT' | 'INTEGER' | 'REAL' | 'BLOB' | 'BOOLEAN' | 'TIMESTAMP' | 'JSON'
+  type: 'TEXT' | 'INTEGER' | 'BIGINT' | 'REAL' | 'BLOB' | 'BOOLEAN' | 'TIMESTAMP' | 'JSON'
   primaryKey?: boolean
   autoIncrement?: boolean
   notNull?: boolean
@@ -118,7 +149,8 @@ interface ReldbColumnDef {
 | 类型      | SQLite  | PostgreSQL       | MySQL        |
 | --------- | ------- | ---------------- | ------------ |
 | TEXT      | TEXT    | TEXT             | VARCHAR(255) |
-| INTEGER   | INTEGER | INTEGER/SERIAL   | INT/BIGINT   |
+| INTEGER   | INTEGER | INTEGER/BIGSERIAL | INT/BIGINT   |
+| BIGINT    | INTEGER（64 位） | BIGINT | BIGINT |
 | REAL      | REAL    | DOUBLE PRECISION | DOUBLE       |
 | BLOB      | BLOB    | BYTEA            | BLOB         |
 | BOOLEAN   | INTEGER | BOOLEAN          | TINYINT(1)   |
@@ -127,6 +159,8 @@ interface ReldbColumnDef {
 
 > MySQL 将 TEXT 映射为 VARCHAR(255) 以支持索引和 UNIQUE 约束。INTEGER + autoIncrement 在 MySQL 映射为 BIGINT。
 
+Unix 毫秒使用 BIGINT，不能使用 PostgreSQL/MySQL 的普通 INTEGER。原始 SQL/CRUD 与 BaseReldbCrudRepository 的 BIGINT 保留 driver 的 number/string/bigint 类型；业务需要 number 时须在读取边界校验非负整数和 Number.isSafeInteger，拒绝精度丢失。TIMESTAMP 经 BaseReldbCrudRepository 映射为 Date。
+
 ### SQL — `reldb.sql`
 
 | 方法        | 签名                                                              | 说明         |
@@ -356,7 +390,7 @@ interface PaginatedResult<T> {
 
 通过 `reldb.json` 构建跨数据库统一的 JSON 路径操作 SQL 表达式，返回 `{ sql, params }` 可直接嵌入 `reldb.sql.*`。
 
-路径格式遵循 SQL/JSON Path 标准，以 `$` 开头（如 `$.key`、`$.key.subkey`、`$[0]`）。
+支持简单路径 `$.key`、`$.key.subkey`、`$[0]`。
 
 | 操作      | SQLite             | PostgreSQL               | MySQL                  |
 | --------- | ------------------ | ------------------------ | ---------------------- |
@@ -364,30 +398,33 @@ interface PaginatedResult<T> {
 | `set`     | `json_set`         | `jsonb_set`              | `JSON_SET`             |
 | `insert`  | `json_insert`      | `jsonb_insert`           | `JSON_INSERT`          |
 | `remove`  | `json_remove`      | `#-` (text[])            | `JSON_REMOVE`          |
-| `merge`   | `json_patch`       | `|| ::jsonb`              | `JSON_MERGE_PATCH`     |
+| `merge`   | `json_patch`       | 参数化递归 CTE           | `JSON_MERGE_PATCH`     |
+
+`merge` 的补丁根限于可 JSON 序列化对象：三种后端均按 RFC 7396 递归保留未变键、用 null 删除指定键、整体替换数组；PostgreSQL 使用参数化递归 CTE，在同一次 SQL 内更新当前行，不做应用先读再写。路径和值全部参数化，column 只能由开发者静态编写。路径解析只支持简单点号/方括号形式，不是完整 SQL/JSON Path 校验器；PostgreSQL set 要求父路径存在，insert 对已有对象键报错且数组按原生位置插入，不应把不同后端的原生路径行为视为完全相同。
 
 ```typescript
-// 提取 JSON 字段值（用于 WHERE 条件）
-const { sql, params } = reldb.json.extract('settings', '$.theme')
-const rows = await reldb.sql.query(
-  `SELECT * FROM users WHERE ${sql} = ?`,
-  [...params, '"dark"'],
-)
+import { reldb, type ReldbFunctions } from '@h-ai/reldb'
 
-// 设置 JSON 字段路径（创建或替换）
-const { sql, params } = reldb.json.set('settings', '$.theme', 'dark')
-await reldb.sql.execute(
-  `UPDATE users SET settings = ${sql} WHERE id = ?`,
-  [...params, userId],
-)
+// db 已初始化，users 表已有 settings/profile JSON 列。
+async function updateSettings(db: ReldbFunctions, userId: string) {
+  const extracted = db.json.extract('settings', '$.theme')
+  const rows = await db.sql.query(`SELECT * FROM users WHERE ${extracted.sql} = ?`, [...extracted.params, '"dark"'])
+  if (!rows.success) return rows
 
-// 删除 JSON 字段路径
-const { sql, params } = reldb.json.remove('settings', '$.deprecated')
-await reldb.sql.execute(`UPDATE users SET settings = ${sql} WHERE id = ?`, [...params, id])
+  const changed = db.json.set('settings', '$.theme', 'dark')
+  const updated = await db.sql.execute(`UPDATE users SET settings = ${changed.sql} WHERE id = ?`, [...changed.params, userId])
+  if (!updated.success) return updated
 
-// 合并 JSON 对象（RFC 7396：null 值表示删除对应键）
-const { sql, params } = reldb.json.merge('profile', { bio: '新简介', avatar: null })
-await reldb.sql.execute(`UPDATE users SET profile = ${sql} WHERE id = ?`, [...params, userId])
+  const removed = db.json.remove('settings', '$.deprecated')
+  const deleted = await db.sql.execute(`UPDATE users SET settings = ${removed.sql} WHERE id = ?`, [...removed.params, userId])
+  if (!deleted.success) return deleted
+
+  const patch = db.json.merge('profile', { bio: '新简介', avatar: null })
+  return db.sql.execute(`UPDATE users SET profile = ${patch.sql} WHERE id = ?`, [...patch.params, userId])
+}
+
+const result = await updateSettings(reldb, 'u1')
+if (!result.success) throw new Error(result.error.message)
 ```
 
 > `column` 参数为列名，**禁止传入用户输入**（开发者负责安全性）。
@@ -453,3 +490,9 @@ const result = await reldb.tx.wrap(async (tx) => {
 - `hai-core`：配置管理、HaiResult 模型
 - `hai-iam`：IAM 模块内部使用 reldb 进行用户/角色/权限存储
 - `hai-cache`：缓存穿透保护中配合 reldb 使用
+
+## 生产共享状态
+
+生产仅使用 PostgreSQL/MySQL；SQLite（含磁盘文件）只用于开发/明确测试，不能作为跨主机共享状态。 NODE_ENV 或 HAI_CORE_ENV 为 production 时在初始化成功前检查，只有 HAI_E2E=1/HAI_E2E_MOCK=1 明确测试豁免。不要将租约当作最终写入条件，外部未知效果须按稳定业务键核对。
+
+MySQL 空 url（含空环境变量占位）按未配置处理，使用分字段；非空仍严格校验。

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

@@ -13,15 +13,18 @@ description: "注册或排查 cron/API/JS/Hook 任务、手工触发、执行日
 | 适用场景 | 服务端任务调度、持久化和手工触发 |
 | 输入 | SchedulerConfigInput、任务定义、已初始化依赖与 hooks |
 | 输出 | 任务管理、触发和日志查询的 HaiResult |
-| 限制 | 仅服务端；vm 不是安全沙箱，JS 任务只执行可信代码。多节点需要共享锁，关闭释放调度资源。 |
+| 限制 | 仅服务端；vm 不是安全沙箱，JS 任务只执行可信代码。共享RelDB强制持久journal/租约；unknown保留槽直至可信人工裁定。 |
 
 ## 使用路径
 
-1. 持久化模式先初始化 reldb；多节点需共享数据库与 Redis，Memory 只用于单进程。检查 scheduler.init 的 HaiResult。
+1. 始终先初始化同一共享 reldb；enableDb 只能 true，跨主机生产使用 PostgreSQL/MySQL，不需要缓存。检查 scheduler.init 的 HaiResult。
 2. 动态共享任务通过 register 管理，不与 init.tasks 重复声明；读取失败、禁用、删除或改期时不得继续旧任务。
-3. 根据可信逻辑选择 API/JS/Hook。Worker/vm 不是安全沙箱；Hook 监听 signal，业务以 occurrenceId 处理幂等。
-4. 明确 timeout、响应大小、重试与执行状态；关闭时 await scheduler.close，再关闭数据库和缓存。
-5. 验证手动/定时、并发抢锁、失败重试、取消与定义更新。
+3. 根据可信逻辑选择 API/JS/Hook。Worker/vm 不是安全沙箱；Hook 监听 signal，业务以 occurrenceId 原子持久去重，只有实际满足该约束才设 idempotent:true；API 自动覆盖幂等头。
+4. 明确 timeout、响应大小、重试与执行状态；关闭时 await scheduler.close，再关闭数据库；unknown须先确认旧runner终止并核对副作用，按版本人工resolveUnknown，禁止直接重排。
+5. 验证手动/定时、跨周期租约、手动/cron竞争及暂停接管、失败重试、取消与定义更新；共享租约必须在 SQL 内用存储时钟原子检查，cron 分钟身份也取 DB 时间且默认 UTC；补上节点 ±2h、不同 TZ 与真实行锁跨期限的多进程用例。
+6. 检查业务 status 与独立 persistence.status；pending 通过 execution.listLogFailures/repairLog 从已发布 journal 补写，不能重新触发业务。失租 unconfirmed 不能作为成功证据；验证丢回执和双节点并发补写。
+
+7. 核对 JSDoc 示例的真实入口与返回值：HaiResult 先分支，close 直接 await；标注“模块内部上下文”的仓库/runner 不属于根 API。示例编译与共享 DB/进程行为验证分别记录。
 
 ## 按需参考
 

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

@@ -1,20 +1,12 @@
 # hai-scheduler 参考
 
-持久化动态任务每个 `tickInterval`（默认 1000ms）在运行节点刷新；API 操作及获锁后的每次尝试重读定义，读取失败或任务已禁用/删除/改期时中断执行。`tasks` 仅表示最近成功刷新快照，已开始的外部副作用不会回滚。跨节点任务使用 `register()` 与共享数据库、Redis；`init({ tasks })` 是节点本地配置，memory cache 不支持跨进程防重。
+所有节点必须先初始化同一共享 RelDB（跨主机生产使用 PostgreSQL/MySQL；SQLite 文件只适合可正确共享同一文件的本机进程）。数据库保存任务、执行 journal、全局任务占位和租约，`enableDb` 只能为 true；不再依赖缓存。`leaseMs` 默认 300000，范围 1000～86400000 毫秒，执行中自动续期。cron、手动和跨周期执行均争用同一任务槽，过期 owner 不能续活或提交。节点每个 `tickInterval` 刷新定义，`tasks` 只是最近成功快照；定义读取失败、删除、禁用、改期均中断旧尝试，已发生副作用不会回滚。
 
-`refreshTasks()` 主动刷新而不执行，同一快照的并发读取合并；保存、更新和删除落库成功后才发布内存投影。清空可选策略使用 `retry: null` / `handler: null`。Hook 业务异常为 `failed` 并重试，缺处理器、取消或 `SchedulerTaskSkippedError` 为 `interrupted`；一次性任务只在成功后删除。`event.context.occurrenceId` 在一次发生的重试期间不变，宿主用其绑定持久幂等回执；跨周期长任务使用宿主持久租约。配置被替换时旧发生停止重试，成功清理前再次核对定义。
+`context.occurrenceId` 是持久发生标识；同一 cron 分钟跨节点一致，手动可传 1～128 字符 `idempotencyKey` 重用原记录，省略时每次独立。`executionToken` 每次领取变化，`sequence` / `attempt` 提供执行代信息。API 会覆盖 `Idempotency-Key`、`X-Scheduler-Sequence`、`X-Scheduler-Attempt`、`X-Scheduler-Task`（任务 ID 使用 percent-encoding）。Hook 及生命周期回调已领取时的 `event.context` 使用同一发生标识；观测回调若产生副作用也须去重。
 
-关闭必须 `await scheduler.close()` 后再关闭数据库和缓存：关闭会拒绝新任务、取消 HTTP/Worker/重试并等待执行链退出。生命周期回调通过事件 `signal` 协作取消，必须自行停止外部副作用，禁止在 Hook 阻塞主线程。旧任务取消后不重试、不删除新实例同 ID 的任务。
+`idempotent` 默认为 false；只有接收端已将幂等账本和全部副作用原子持久提交，才声明 true。租约过期的已执行任务仅在 true 时以同 occurrenceId 接管；非幂等或耗尽本 occurrence 保存的 retry.maxAttempts（默认 1，范围 1–100，包含首次执行及恢复）时进入 `unknown` 并继续占住任务槽。租约无法强制撤销暂停进程已发出的外部操作，单有 HTTP 头不构成去重实现。重试同样受幂等声明约束。
 
-JS 任务每次调用独立 Worker，默认 30000 毫秒期限包含线程启动；超时后等待线程终止才返回失败或重试，同步死循环不会占用主事件循环。上下文和结果须支持结构化克隆。Worker/vm 不构成安全沙箱，仍只接受受信任的服务端代码。
-
-初始化为全有或全无：必须检查 `init()` 的 HaiResult。空 ID、重复 ID（包括与数据库记录重复）、无效 cron、持久化读取或解析失败均使初始化失败并清理状态；修正后重试，不会静默跳过任务。
-
-API 任务 `timeout` 默认 30000 毫秒，覆盖请求及完整响应体读取；`maxResponseBytes` 指定实际接收字节上限（正安全整数，默认 1048576 即 1 MiB），例如 `maxResponseBytes: 10 * 1024 * 1024` 允许最大 10 MiB；非法值在请求前失败。超时、超限和非成功 HTTP 状态均失败，重试由任务 retry 策略控制。
-
-
-
-> `@h-ai/scheduler` 使用统一任务模型管理 API / JS / Hook 三类执行路径，支持持久化、手工触发来源记录、分布式锁与全局生命周期回调。
+`scheduler.execution.get(occurrenceId)` 查询权威状态；`listUnknown({ limit, offset })` 分页获取未知结果，limit 为 1～100，offset 为 0～1000000。可信人工先核实外部效果、确认旧 runner 已终止，再按 `expectedUpdatedAt` CAS 调用 `resolveUnknown(id, { status: 'success' | 'discarded', expectedUpdatedAt })` 释放占位；不能直接把 unknown 重排。`log.occurrenceId` 可作查询回执；`getLogs` 仅为尝试观测日志，日志保留策略不删除 journal/幂等历史。
 
 ## 运行环境
 
@@ -24,21 +16,18 @@ API 任务 `timeout` 默认 30000 毫秒，覆盖请求及完整响应体读取
 
 | 模块 | 用途 | 是否必需 | 初始化要求 |
 | --- | --- | --- | --- |
-| `@h-ai/reldb` | 任务定义与执行日志持久化 | `enableDb: true` 时必需 | 需在 `scheduler.init()` 前初始化 |
-| `@h-ai/cache` | 分布式锁 | 可选 | 初始化后自动启用 |
+| `@h-ai/reldb` | 任务/执行 journal/租约 | 始终必需 | 先初始化同一共享数据库 |
 
 ## 使用步骤
 
 ### 1. 初始化
 
 ```ts
-import { cache } from '@h-ai/cache'
 import { core } from '@h-ai/core'
 import { reldb } from '@h-ai/reldb'
 import { scheduler } from '@h-ai/scheduler'
 
 await reldb.init({ type: 'sqlite', database: './scheduler.db' })
-await cache.init({ type: 'memory' })
 
 await scheduler.init({
   enableDb: true,
@@ -67,7 +56,6 @@ await scheduler.register({
   description: '每 5 分钟巡检一次接口健康状态',
   cron: '*/5 * * * *',
   params: { channel: 'ops' },
-  retry: { maxAttempts: 3, backoffMs: [1000, 5000] },
   handler: {
     kind: 'api',
     url: 'https://api.example.com/health',
@@ -130,8 +118,9 @@ const logs = await scheduler.getLogs({
 | `register` | `(task) => Promise<HaiResult<void>>` | 注册统一任务模型 |
 | `updateTask` | `(taskId, updates) => Promise<HaiResult<void>>` | 更新 cron / params / handler |
 | `refreshTasks` | `() => Promise<HaiResult<void>>` | 主动刷新共享定义，不执行任务 |
-| `register` 扩展字段 | `description / deleteAfterRun / retry` | 支持任务描述、一次性任务、失败重试策略 |
-| `trigger` | `(taskId, { source? }) => Promise<HaiResult<TaskExecutionLog>>` | 手工触发并记录来源 |
+| `register` 扩展字段 | `description / deleteAfterRun / retry / idempotent` | 支持任务描述、一次性任务、失败重试策略 |
+| `trigger` | `(taskId, { source?, idempotencyKey? }) => Promise<HaiResult<TaskExecutionLog>>` | 手工触发并记录来源 |
+| `execution.listLogFailures / repairLog` | `(options?) / (occurrenceId)` | 有界监控并幂等补写已发布 journal，不重执行业务 |
 | `getLogs` | `(options?) => Promise<HaiResult<PaginatedResult<TaskExecutionLog>>>` | 支持按 trigger + startedAfter/startedBefore 过滤日志 |
 | `setHooks` | `(hooks) => HaiResult<void>` | 设置全局生命周期回调 |
 | `clearHooks` | `() => HaiResult<void>` | 清空全局生命周期回调 |
@@ -165,20 +154,41 @@ await scheduler.trigger('cleanup', { source: 'cli' })
 const adminLogs = await scheduler.getLogs({ triggerSource: 'admin-console' })
 ```
 
-### 分布式锁
+### 共享执行租约
 
 ```ts
-await cache.init({ type: 'redis', host: 'localhost', port: 6379 })
 await reldb.init({ type: 'sqlite', database: './scheduler.db' })
 await scheduler.init({
   enableDb: true,
   maxLogs: 500,
   retentionDays: 14,
-  lockExpireMs: 300000,
+  leaseMs: 300000,
   nodeId: 'node-1',
 })
 ```
 
+### 日志失败与补写
+
+日志的 `id` 是每次尝试固定的 UUID，`persistence.status` 与业务 `status` 独立：`persisted` 表示日志及确认回执已持久化；`pending` 表示业务终态已提交但日志待补写；`unconfirmed` 表示没有已确认的业务终态，不能据此补写成功。只有 owner 与有效租约条件提交的终态会发布完整尝试列表，随后才投影日志；失租节点不能投影成功。日志失败不会把业务成功改成失败，也不会因此重跑业务。
+
+补写会缩小 pending 列表；批量补写应反复读取 offset=0，避免一边补写一边增加 offset 跳过记录。
+
+可信服务端用 `execution.listLogFailures({ limit, offset })` 监控 pending（范围与 listUnknown 相同），用 `execution.repairLog(occurrenceId)` 从共享 journal 幂等补写；可跨节点、重启及并发调用。写入已提交但回执丢失时通过固定主键和完整内容核对去重。补写返回 `LOG_PERSIST_FAILED`（032）时继续保留 pending，并输出安全告警；全部数据库不可用且终态未提交时仍按 unknown 核对外部效果，不能假定存在可恢复结果。补写与日志保留均不调用业务 Hook。保留策略失败仅告警，不撤销已保存日志。`onTaskFinish` 是本地业务完成通知，其 unconfirmed 状态不是持久化确认；以 trigger 返回值及 execution.get 的 logPersistence 为准。
+
+领取前竞争/跳过的 interrupted 仅为观测日志，没有可补写的终态；其写入未确认时返回 unconfirmed。JSON 大载荷保存完整结果和全部重试记录，避免 MySQL 的 255 字符截断；新 schema 不自动迁移旧日志/执行表。关闭会等待在途补写，先关闭 scheduler 再关闭数据库。
+
+```ts
+const result = await scheduler.trigger('cleanup', { idempotencyKey: 'cleanup-2026-10-23' })
+if (!result.success)
+  return result
+if (result.data.persistence.status === 'pending' && result.data.occurrenceId) {
+  const repaired = await scheduler.execution.repairLog(result.data.occurrenceId)
+  if (!repaired.success)
+    return repaired
+}
+// 不用日志补写失败重新 trigger 业务；定期按页扫描 listLogFailures。
+```
+
 ## 错误码 — `HaiSchedulerError`
 
 | 错误码 | code | 说明 |
@@ -195,8 +205,12 @@ await scheduler.init({
 | `HaiSchedulerError.DB_SAVE_FAILED` | `hai:scheduler:026` | DB 保存失败 |
 | `HaiSchedulerError.ALREADY_RUNNING` | `hai:scheduler:027` | 已在运行 |
 | `HaiSchedulerError.NOT_RUNNING` | `hai:scheduler:028` | 未在运行 |
-| `HaiSchedulerError.LOCK_ACQUIRE_FAILED` | `hai:scheduler:029` | 锁获取失败 |
 | `HaiSchedulerError.JS_COMPILE_FAILED` | `hai:scheduler:030` | JS 编译失败 |
 | `HaiSchedulerError.HOOK_EXECUTION_FAILED` | `hai:scheduler:031` | Hook 执行失败 |
+| `HaiSchedulerError.LOG_PERSIST_FAILED` | `hai:scheduler:032` | 日志持久化未确认 |
+
+调度循环按分钟匹配 cron，同一分生成稳定的持久 occurrenceId。
+
+数据库是共享租约的时间权威：claim/begin/renew/finish/expired/isolate 均在执行 SQL 内取存储端时钟并原子核验期限，不用节点 Date.now 或“先查 now 再写”的结果授权。PostgreSQL clock_timestamp、MySQL SYSDATE(3)、SQLite now 在真实锁等待后仍拒绝过期提交；updatedAt 条件版本使用同一数据库时钟并单调推进。cron 从 DB 时间生成分钟身份并匹配；默认 timezone 为 UTC，显式 IANA 时区只改变墙上时间解释，不读取节点 TZ。节点偏差 ±2h、不同 TZ 下同一分钟身份、过期但未接管、接管后的旧 owner 和行锁跨期限均须真实多进程验证。应用仍维护 DB 时钟与外部接收端的持久幂等/fence；未知效果不能靠补写日志或重新 trigger 重做。
 
-调度循环按分钟时间点匹配 cron，并用同一分钟生成分布式锁键；启动或 tick 延迟至非零秒仍检查当前分钟，同一轮运行不会每个 tick 重复调度。
+公开使用以 @h-ai/scheduler 的实际入口与声明为准。声明 JSDoc 的公开示例检查 HaiResult，关闭调用使用 await scheduler.close()（返回 Promise<void>）；内部 repository/runner/compiler/cron 示例标注“模块内部上下文”，不能照抄为根导入。业务 status 与 persistence 分开，pending 补写不会重跑业务；unknown/unconfirmed 先核对共享 journal 与外部效果。应用使用所安装版本的公开类型，并通过本应用已有的类型检查验证使用示例。