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

package/templates/skills/hai-pr-review/SKILL.md

@@ -1,104 +1,37 @@
 ---
 name: hai-pr-review
-description: "审查 PR 范围、风险、验证证据和合并准备度。"
+description: "审查 PR、提交或分支的实际差异、调用影响、需求符合性、风险与验证证据，评估交付准备度。"
 ---
 
-# hai-pr-review — PR 审查与 AI Review 规范
+# hai-pr-review
 
 ## 能力契约
 
 | 项目 | 契约 |
 | --- | --- |
-| 能力 | 审查 PR 范围、风险、验证证据和合并准备度 |
-| 适用场景 | 用户要求 PR 审查或合并准备度评估 |
-| 输入 | PR diff、相关实现、CI 结果及仓库合并规则 |
-| 输出 | 可定位的问题、验证缺口与审查结论 |
-| 限制 | AI 建议不等于 CI 通过；不代替用户批准合并，不因审查擅自发布评论。 |
+| 能力 | 对固定 PR/提交/分支差异进行审查，核对需求、调用影响与交付条件 |
+| 适用场景 | 用户要求差异审查、开发后的交付自查或 PR 准备度评估 |
+| 输入 | 实际 base/head、需求与计划、完整 diff、相关实现和 CI/运行证据 |
+| 输出 | 可定位发现、实际覆盖范围、验证缺口和交付结论 |
+| 限制 | 只读审查不自动改代码或发布评论；已有修复授权持续有效。审查不赋予远端推送、合并或发布授权。 |
 
-> PR 是团队协作和 AI 辅助开发的交付边界。AI 可以帮助发现问题，但不能替代确定性 CI 和人类最终责任。
+## 审查路径
 
-## 适用场景
+1. 读取仓库入口和 PR/任务目标，确认比较对象。按 [差异审查](../hai-app-review/differential.md) 固定 base/head、列全文件与重命名，说明 staged/unstaged 和截断限制。
+2. 先将需求、验收与实际 diff 对照，检查遗漏、范围扩张和陈旧模板断言。代码符合性、安全、框架复用和生命周期沿 [hai-app-review](../hai-app-review/SKILL.md)；界面涉及交互或布局时调用已交付的 hai-ui-review，纯 API 不需要它。
+3. 按风险读取调用方、类型、配置、迁移、历史和测试；删除校验、事务、资源归属检查时核验真实替代约束。两行权限改动仍可能需要深入分析。
+4. 核对测试证明了什么、是否对应最终代码和真实环境。CI required checks 查询实际状态：成功、失败、运行中、未执行或无权读取分别报告。本地通过不能替代远端 CI；分支规则不可读取时保留该限制。
+5. 对每条发现复核触发路径和反证，合并同根因问题；按 [工作交接契约](../hai-spec-implement/handoff.md) 报告。已授权修复时完成本次范围修复，重验受影响项并针对最终 head 更新结论。
 
-- 审查 AI-generated / AI-assisted PR
-- 审查 Pull Request 的 scope、风险、验证方式、issue 关联与合并准备度
-- 判断 AI Review 是 advisory 还是 blocking，以及是否需要人工复核
-- 新增或修改 `.github/pull_request_template.md`
-- 配置 CODEOWNERS、required review、branch protection
-- 设计 AI PR Review 方案
-- 选择 Copilot、CodeRabbit、reviewdog、DangerJS、Claude Code Action、Codex Action 等工具
+## 交付条件
 
-代码级框架复用、安全与风格审查交给 [hai-app-review](../hai-app-review/SKILL.md)，测试用例设计交给 `hai-app-tests`，workflow 触发/权限/secret 细节交给 `hai-ci`。
+- 需求与验收有完成/已有满足/排除/阻塞的实际结论，公共变化同步服务、客户端、迁移、配置、UI/i18n、测试、README 和 skills。
+- PR 描述围绕具体问题、最终行为、验证和剩余边界，按仓库规则关联 issue 或明确需求与验收。要求披露 AI 使用时说明辅助范围与实际复核，不粘贴聊天原文、凭据或私有上下文。
+- 适用门禁对最终代码有效通过；已确认的阻塞发现已解决；项目所需人工审批和 required checks 状态真实可查。未完成项明确列出，不能仅由 AI 建议数量判定可合并。
+- workflow、依赖或发布流程变化按 [hai-ci](../hai-ci/SKILL.md) 检查来源、权限、secret 和执行边界。不得在不可信 PR 代码执行环境暴露密钥。
 
-## 审查分层
+## 报告格式
 
-### 第 1 层：确定性检查（必须）
+先写实际结论和比较范围，再按严重程度列可行动发现；每条包含文件/当前差异行、触发条件、后果、依据和最小验收。最后列已检查路径、CI/本地/浏览器的实际证据和未验证边界。无发现时直接说明本次范围未确认问题，不补泛泛建议凑数。
 
-- CI required checks 必须全绿。
-- 具体 workflow、权限、secret scan 与 required check 配置由 `hai-ci` 定义。
-- 测试覆盖策略与失败用例设计由 `hai-app-tests` 定义。
-
-### 第 2 层：结构化人工审查（必须）
-
-- scope 是否清晰且与 issue 对齐
-- 测试是否覆盖成功路径、失败路径、边界条件
-- 本次需求是否复用适用框架能力/feature/配置，自定义或新依赖是否有已安装版本的缺口依据（见 [development.md](../hai-app-create/development.md)）
-- 是否符合实际返回契约、i18n、日志、分层、当前 lint 风格，以及输入/越权/失败等适用行为验收；不能以导入包数量或 CI 全绿替代代码与安全审查
-- 是否引入密钥、权限扩大、workflow 风险或两仓漂移
-
-### 第 3 层：AI Review（默认 advisory）
-
-- AI Review 默认只评论、不阻塞 merge。
-- 只有在 CI 稳定、误报可控、团队明确同意后，才考虑将特定静态规则设为 blocking。
-- AI 的建议必须由人类判断，不得自动 merge。
-
-## AI-assisted PR 要求
-
-PR 描述必须说明：
-
-- 是否使用 AI 辅助
-- AI 负责了哪部分：搜索、实现、测试、review、文档
-- 人类如何验证：命令、截图、日志或 reviewer 重点
-- 是否复制了聊天记录；若有，只能复制脱敏后的结论，禁止包含 token、cookie、私有 URL、账号密码
-
-## Issue 关联与上下文交接
-
-- PR 必须关联 issue 或说明为什么不需要 issue。
-- PR scope 必须与 issue 的目标、验收标准和明确不做事项一致。
-- AI-assisted PR 必须说明 AI 负责了哪些阶段，以及人类如何复核。
-- 多人或多 agent 协作时，PR 描述必须列出 reviewer focus，避免重复 review。
-
-## 自动 Review 工具选择
-
-| 工具 | 推荐定位 | 是否适合 blocking |
-| --- | --- | --- |
-| reviewdog | 把 lint/static analyzer 结果贴到 PR | 适合，前提是规则稳定 |
-| DangerJS | PR 元数据、模板、标签、变更范围规则 | 适合，前提是规则明确 |
-| GitHub Copilot Code Review | 通用 AI 代码建议 | 默认 advisory |
-| CodeRabbit | 上下文型 AI review | 默认 advisory |
-| Claude Code Action | 定制化深度 review / 修改建议 | 默认 advisory，严格限制权限 |
-| Codex Action | 定制化 review / 修复建议 | 默认 advisory，严格控制 API key |
-
-## 权限与安全红线
-
-- ❌ 不在 `pull_request_target` 中运行 AI agent 读取 PR 代码和 secrets。
-- ❌ 不给 AI Review workflow 默认 `contents: write`、`pull-requests: write`，除非只用于评论且触发源可信。
-- ❌ 不允许 AI 自动合并 PR。
-- ❌ 不把私有提示词、聊天原文、token、cookie、连接串写入 PR。
-- ✅ AI Review 的 prompt 必须限制任务范围、禁止执行 secrets、要求引用具体文件/行。
-
-## PR Review 检查清单
-
-- [ ] PR 关联 issue，scope 单一
-- [ ] PR 模板完整填写
-- [ ] CI required checks 全绿
-- [ ] 新行为有测试，失败路径有覆盖
-- [ ] 框架能力选择、代码风格与适用安全边界已由 `hai-app-review` 覆盖，有行为证据或明确未验证项
-- [ ] 文档 / skill / README 与代码同步
-- [ ] workflow 权限或 secrets 变化已由 `hai-ci` 审查
-- [ ] AI-assisted 内容已由人类复核
-
-## 相关 Skills
-
-- `hai-ci` — CI/CD 与 workflow 安全
-- `hai-app-review` — 应用代码质量与框架复用审查
-- `hai-framework-sync` — 框架升级差异与双仓同步审查
+仅要求审查时在报告处结束；已获修复授权则修复并复核。提交评论、创建 PR、远端推送、合并与发布按用户的实际授权继续，遵守项目规则。

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

@@ -1,6 +1,6 @@
 ---
 name: hai-reach
-description: "使用 @h-ai/reach 配置邮件、短信、API 通知和多渠道消息模板。"
+description: "接入邮件、短信、API 通知与模板，处理发送结果、免打扰和可靠延迟入队。"
 ---
 
 # hai-reach
@@ -17,12 +17,14 @@ description: "使用 @h-ai/reach 配置邮件、短信、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 不能重排。
 
 ## 按需参考
 
-详细配置、API 签名、错误码和范本在 [reference.md](reference.md)。按下列标题定位所需小节，不默认通读；用例中的业务变量需结合当前应用补齐。
+按任务读取 [reference.md](reference.md) 的对应小节；签名以当前源码或安装版本的公开类型为准，不默认加载全部资料。示例中的业务变量由应用提供。
 
 - 运行环境
 - 依赖
@@ -31,6 +33,7 @@ description: "使用 @h-ai/reach 配置邮件、短信、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,18 +13,19 @@ 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 的配置章节。
 
 ## 按需参考
 
-详细配置、API 签名、错误码和范本在 [reference.md](reference.md)。按下列标题定位所需小节，不默认通读；用例中的业务变量需结合当前应用补齐。
+按任务读取 [reference.md](reference.md) 的对应小节；签名以当前源码或安装版本的公开类型为准，不默认加载全部资料。示例中的业务变量由应用提供。
 
 - 运行环境
 - 适用场景
@@ -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（含空环境变量占位）按未配置处理，使用分字段；非空仍严格校验。