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

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

@@ -1,215 +1,38 @@
 ---
 name: hai-scheduler
-description: "使用 @h-ai/scheduler 注册 cron/API/JS/Hook 任务、手工触发并查询执行日志。"
+description: "注册或排查 cron/API/JS/Hook 任务、手工触发、执行日志、重试取消与多节点调度。"
 ---
 
 # hai-scheduler
 
 ## 能力契约
 
-持久化动态任务每个 `tickInterval`（默认 1000ms）在运行节点刷新；API 操作及获锁后的每次尝试重读定义，读取失败或任务已禁用/删除/改期时中断执行。`tasks` 仅表示最近成功刷新快照，已开始的外部副作用不会回滚。跨节点任务使用 `register()` 与共享数据库、Redis；`init({ tasks })` 是节点本地配置，memory cache 不支持跨进程防重。
-
-`refreshTasks()` 主动刷新而不执行，同一快照的并发读取合并；保存、更新和删除落库成功后才发布内存投影。清空可选策略使用 `retry: null` / `handler: null`。Hook 业务异常为 `failed` 并重试，缺处理器、取消或 `SchedulerTaskSkippedError` 为 `interrupted`；一次性任务只在成功后删除。`event.context.occurrenceId` 在一次发生的重试期间不变，宿主用其绑定持久幂等回执；跨周期长任务使用宿主持久租约。配置被替换时旧发生停止重试，成功清理前再次核对定义。
-
-关闭必须 `await scheduler.close()` 后再关闭数据库和缓存：关闭会拒绝新任务、取消 HTTP/Worker/重试并等待执行链退出。生命周期回调通过事件 `signal` 协作取消，必须自行停止外部副作用，禁止在 Hook 阻塞主线程。旧任务取消后不重试、不删除新实例同 ID 的任务。
-
-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 注册 cron/API/JS/Hook 任务、手工触发并查询执行日志 |
 | 适用场景 | 服务端任务调度、持久化和手工触发 |
 | 输入 | SchedulerConfigInput、任务定义、已初始化依赖与 hooks |
 | 输出 | 任务管理、触发和日志查询的 HaiResult |
-| 限制 | 仅服务端；vm 不是安全沙箱，JS 任务只执行可信代码。多节点需要共享锁，关闭释放调度资源。 |
-
-> `@h-ai/scheduler` 使用统一任务模型管理 API / JS / Hook 三类执行路径，支持持久化、手工触发来源记录、分布式锁与全局生命周期回调。
-
-## 运行环境
-
-> ⚠️ **服务端模块（Node.js only）。** 浏览器端通过 API 端点触发 `scheduler.trigger()` 或查询任务日志。
-
-## 依赖
-
-| 模块 | 用途 | 是否必需 | 初始化要求 |
-| --- | --- | --- | --- |
-| `@h-ai/reldb` | 任务定义与执行日志持久化 | `enableDb: true` 时必需 | 需在 `scheduler.init()` 前初始化 |
-| `@h-ai/cache` | 分布式锁 | 可选 | 初始化后自动启用 |
-
-## 使用步骤
-
-### 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,
-  maxLogs: 1000,
-  retentionDays: 30,
-  hooks: {
-    onTaskStart(event) {
-      core.logger.info('Task started', { taskId: event.task.id, trigger: event.trigger })
-    },
-    onTaskInterrupted(event) {
-      core.logger.warn('Task interrupted', { taskId: event.task.id, reason: event.reason })
-    },
-    onTaskFinish(event) {
-      core.logger.info('Task finished', { status: event.log.status })
-    },
-  },
-})
-```
-
-### 2. 注册任务
-
-```ts
-await scheduler.register({
-  id: 'health-check',
-  name: '健康检查',
-  description: '每 5 分钟巡检一次接口健康状态',
-  cron: '*/5 * * * *',
-  params: { channel: 'ops' },
-  retry: { maxAttempts: 3, backoffMs: [1000, 5000] },
-  handler: {
-    kind: 'api',
-    url: 'https://api.example.com/health',
-    method: 'GET',
-  },
-})
-
-await scheduler.register({
-  id: 'cleanup',
-  name: '清理过期数据',
-  description: '夜间单次清理任务',
-  cron: '0 2 * * *',
-  deleteAfterRun: true,
-  params: { source: 'nightly' },
-  handler: {
-    kind: 'js',
-    code: '(context) => ({ taskId: context.taskId, params: context.params })',
-  },
-})
-```
-
-> ⚠️ **安全警示**：`kind: 'js'` 仅允许受信任的服务端代码。当前实现使用 Node.js `vm` 便捷执行，不是安全沙箱；禁止把用户、租户或运营后台自由输入的 JS 字符串直接注册为任务。需要可配置执行逻辑时，优先改用 `kind: 'api'` 或 `hooks.onTaskExecute`。
-
-### 3. 使用全局 execute hook 处理无 handler 任务
-
-```ts
-await scheduler.setHooks({
-  async onTaskExecute(event) {
-    return { via: 'hook', source: event.context.trigger.source }
-  },
-})
-
-await scheduler.register({
-  id: 'hook-task',
-  name: 'Hook 任务',
-  cron: '* * * * *',
-})
-```
-
-### 4. 手工触发与日志查询
-
-```ts
-const result = await scheduler.trigger('cleanup', { source: 'admin-console' })
-
-const logs = await scheduler.getLogs({
-  taskId: 'cleanup',
-  triggerType: 'manual',
-  triggerSource: 'admin-console',
-  startedAfter: Date.now() - 24 * 60 * 60 * 1000,
-  startedBefore: Date.now(),
-  pagination: { page: 1, pageSize: 20 },
-})
-```
-
-## 核心 API
-
-| 方法 / 属性 | 签名 | 说明 |
-| --- | --- | --- |
-| `init` | `(config?) => Promise<HaiResult<void>>` | 初始化调度器 |
-| `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>>` | 手工触发并记录来源 |
-| `getLogs` | `(options?) => Promise<HaiResult<PaginatedResult<TaskExecutionLog>>>` | 支持按 trigger + startedAfter/startedBefore 过滤日志 |
-| `setHooks` | `(hooks) => HaiResult<void>` | 设置全局生命周期回调 |
-| `clearHooks` | `() => HaiResult<void>` | 清空全局生命周期回调 |
-| `start / stop` | `() => HaiResult<void>` | 启动 / 停止调度 |
-| `close` | `() => Promise<void>` | 关闭调度器 |
-
-## 常见模式
-
-### 持久化 JS 任务
-
-```ts
-await scheduler.init({ enableDb: true })
-
-await scheduler.register({
-  id: 'persisted-js',
-  name: '持久化 JS 任务',
-  cron: '*/10 * * * *',
-  handler: {
-    kind: 'js',
-    code: '(context) => ({ taskId: context.taskId })',
-  },
-})
-```
-
-### 手工触发来源审计
-
-```ts
-await scheduler.trigger('cleanup', { source: 'admin-console' })
-await scheduler.trigger('cleanup', { source: 'cli' })
+| 限制 | 仅服务端；vm 不是安全沙箱，JS 任务只执行可信代码。共享RelDB强制持久journal/租约；unknown保留槽直至可信人工裁定。 |
 
-const adminLogs = await scheduler.getLogs({ triggerSource: 'admin-console' })
-```
+## 使用路径
 
-### 分布式锁
+1. 始终先初始化同一共享 reldb；enableDb 只能 true，跨主机生产使用 PostgreSQL/MySQL，不需要缓存。检查 scheduler.init 的 HaiResult。
+2. 动态共享任务通过 register 管理，不与 init.tasks 重复声明；读取失败、禁用、删除或改期时不得继续旧任务。
+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 不能作为成功证据；验证丢回执和双节点并发补写。
 
-```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,
-  nodeId: 'node-1',
-})
-```
+7. 核对 JSDoc 示例的真实入口与返回值：HaiResult 先分支，close 直接 await；标注“模块内部上下文”的仓库/runner 不属于根 API。示例编译与共享 DB/进程行为验证分别记录。
 
-## 错误码 — `HaiSchedulerError`
+## 按需参考
 
-| 错误码 | code | 说明 |
-|--------|------|------|
-| `HaiSchedulerError.NOT_INITIALIZED` | `hai:scheduler:010` | 未初始化 |
-| `HaiSchedulerError.INIT_FAILED` | `hai:scheduler:011` | 初始化失败 |
-| `HaiSchedulerError.CONFIG_ERROR` | `hai:scheduler:012` | 配置错误 |
-| `HaiSchedulerError.TASK_NOT_FOUND` | `hai:scheduler:020` | 任务不存在 |
-| `HaiSchedulerError.TASK_ALREADY_EXISTS` | `hai:scheduler:021` | 任务已存在 |
-| `HaiSchedulerError.INVALID_CRON` | `hai:scheduler:022` | Cron 表达式无效 |
-| `HaiSchedulerError.EXECUTION_FAILED` | `hai:scheduler:023` | 执行失败 |
-| `HaiSchedulerError.JS_EXECUTION_FAILED` | `hai:scheduler:024` | JS 执行失败 |
-| `HaiSchedulerError.API_EXECUTION_FAILED` | `hai:scheduler:025` | API 执行失败 |
-| `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 执行失败 |
+按本次操作读取对应小节；以已安装版本的公开类型核验签名，示例中的业务变量由应用提供。
 
-调度循环按分钟时间点匹配 cron，并用同一分钟生成分布式锁键；启动或 tick 延迟至非零秒仍检查当前分钟，同一轮运行不会每个 tick 重复调度。
+- [运行环境](reference.md#运行环境)
+- [依赖](reference.md#依赖)
+- [使用步骤](reference.md#使用步骤)
+- [核心 API](reference.md#核心-api)
+- [常见模式](reference.md#常见模式)
+- [错误码 — `HaiSchedulerError`](reference.md#错误码--haischedulererror)

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

@@ -0,0 +1,216 @@
+# hai-scheduler 参考
+
+所有节点必须先初始化同一共享 RelDB（跨主机生产使用 PostgreSQL/MySQL；SQLite 文件只适合可正确共享同一文件的本机进程）。数据库保存任务、执行 journal、全局任务占位和租约，`enableDb` 只能为 true；不再依赖缓存。`leaseMs` 默认 300000，范围 1000～86400000 毫秒，执行中自动续期。cron、手动和跨周期执行均争用同一任务槽，过期 owner 不能续活或提交。节点每个 `tickInterval` 刷新定义，`tasks` 只是最近成功快照；定义读取失败、删除、禁用、改期均中断旧尝试，已发生副作用不会回滚。
+
+`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` 使用同一发生标识；观测回调若产生副作用也须去重。
+
+`idempotent` 默认为 false；只有接收端已将幂等账本和全部副作用原子持久提交，才声明 true。租约过期的已执行任务仅在 true 时以同 occurrenceId 接管；非幂等或耗尽本 occurrence 保存的 retry.maxAttempts（默认 1，范围 1–100，包含首次执行及恢复）时进入 `unknown` 并继续占住任务槽。租约无法强制撤销暂停进程已发出的外部操作，单有 HTTP 头不构成去重实现。重试同样受幂等声明约束。
+
+`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/幂等历史。
+
+## 运行环境
+
+> ⚠️ **服务端模块（Node.js only）。** 浏览器端通过 API 端点触发 `scheduler.trigger()` 或查询任务日志。
+
+## 依赖
+
+| 模块 | 用途 | 是否必需 | 初始化要求 |
+| --- | --- | --- | --- |
+| `@h-ai/reldb` | 任务/执行 journal/租约 | 始终必需 | 先初始化同一共享数据库 |
+
+## 使用步骤
+
+### 1. 初始化
+
+```ts
+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 scheduler.init({
+  enableDb: true,
+  maxLogs: 1000,
+  retentionDays: 30,
+  hooks: {
+    onTaskStart(event) {
+      core.logger.info('Task started', { taskId: event.task.id, trigger: event.trigger })
+    },
+    onTaskInterrupted(event) {
+      core.logger.warn('Task interrupted', { taskId: event.task.id, reason: event.reason })
+    },
+    onTaskFinish(event) {
+      core.logger.info('Task finished', { status: event.log.status })
+    },
+  },
+})
+```
+
+### 2. 注册任务
+
+```ts
+await scheduler.register({
+  id: 'health-check',
+  name: '健康检查',
+  description: '每 5 分钟巡检一次接口健康状态',
+  cron: '*/5 * * * *',
+  params: { channel: 'ops' },
+  handler: {
+    kind: 'api',
+    url: 'https://api.example.com/health',
+    method: 'GET',
+  },
+})
+
+await scheduler.register({
+  id: 'cleanup',
+  name: '清理过期数据',
+  description: '夜间单次清理任务',
+  cron: '0 2 * * *',
+  deleteAfterRun: true,
+  params: { source: 'nightly' },
+  handler: {
+    kind: 'js',
+    code: '(context) => ({ taskId: context.taskId, params: context.params })',
+  },
+})
+```
+
+> ⚠️ **安全警示**：`kind: 'js'` 仅允许受信任的服务端代码。当前实现在线程内使用 Node.js `vm`，超时可终止 Worker，但不构成安全沙箱；禁止把用户、租户或运营后台自由输入的 JS 字符串直接注册为任务。需要可配置执行逻辑时，优先改用 `kind: 'api'` 或 `hooks.onTaskExecute`。
+
+### 3. 使用全局 execute hook 处理无 handler 任务
+
+```ts
+await scheduler.setHooks({
+  async onTaskExecute(event) {
+    return { via: 'hook', source: event.context.trigger.source }
+  },
+})
+
+await scheduler.register({
+  id: 'hook-task',
+  name: 'Hook 任务',
+  cron: '* * * * *',
+})
+```
+
+### 4. 手工触发与日志查询
+
+```ts
+const result = await scheduler.trigger('cleanup', { source: 'admin-console' })
+
+const logs = await scheduler.getLogs({
+  taskId: 'cleanup',
+  triggerType: 'manual',
+  triggerSource: 'admin-console',
+  startedAfter: Date.now() - 24 * 60 * 60 * 1000,
+  startedBefore: Date.now(),
+  pagination: { page: 1, pageSize: 20 },
+})
+```
+
+## 核心 API
+
+| 方法 / 属性 | 签名 | 说明 |
+| --- | --- | --- |
+| `init` | `(config?) => Promise<HaiResult<void>>` | 初始化调度器 |
+| `register` | `(task) => Promise<HaiResult<void>>` | 注册统一任务模型 |
+| `updateTask` | `(taskId, updates) => Promise<HaiResult<void>>` | 更新 cron / params / handler |
+| `refreshTasks` | `() => Promise<HaiResult<void>>` | 主动刷新共享定义，不执行任务 |
+| `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>` | 清空全局生命周期回调 |
+| `start / stop` | `() => HaiResult<void>` | 启动 / 停止调度 |
+| `close` | `() => Promise<void>` | 关闭调度器 |
+
+## 常见模式
+
+### 持久化 JS 任务
+
+```ts
+await scheduler.init({ enableDb: true })
+
+await scheduler.register({
+  id: 'persisted-js',
+  name: '持久化 JS 任务',
+  cron: '*/10 * * * *',
+  handler: {
+    kind: 'js',
+    code: '(context) => ({ taskId: context.taskId })',
+  },
+})
+```
+
+### 手工触发来源审计
+
+```ts
+await scheduler.trigger('cleanup', { source: 'admin-console' })
+await scheduler.trigger('cleanup', { source: 'cli' })
+
+const adminLogs = await scheduler.getLogs({ triggerSource: 'admin-console' })
+```
+
+### 共享执行租约
+
+```ts
+await reldb.init({ type: 'sqlite', database: './scheduler.db' })
+await scheduler.init({
+  enableDb: true,
+  maxLogs: 500,
+  retentionDays: 14,
+  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 | 说明 |
+|--------|------|------|
+| `HaiSchedulerError.NOT_INITIALIZED` | `hai:scheduler:010` | 未初始化 |
+| `HaiSchedulerError.INIT_FAILED` | `hai:scheduler:011` | 初始化失败 |
+| `HaiSchedulerError.CONFIG_ERROR` | `hai:scheduler:012` | 配置错误 |
+| `HaiSchedulerError.TASK_NOT_FOUND` | `hai:scheduler:020` | 任务不存在 |
+| `HaiSchedulerError.TASK_ALREADY_EXISTS` | `hai:scheduler:021` | 任务已存在 |
+| `HaiSchedulerError.INVALID_CRON` | `hai:scheduler:022` | Cron 表达式无效 |
+| `HaiSchedulerError.EXECUTION_FAILED` | `hai:scheduler:023` | 执行失败 |
+| `HaiSchedulerError.JS_EXECUTION_FAILED` | `hai:scheduler:024` | JS 执行失败 |
+| `HaiSchedulerError.API_EXECUTION_FAILED` | `hai:scheduler:025` | API 执行失败 |
+| `HaiSchedulerError.DB_SAVE_FAILED` | `hai:scheduler:026` | DB 保存失败 |
+| `HaiSchedulerError.ALREADY_RUNNING` | `hai:scheduler:027` | 已在运行 |
+| `HaiSchedulerError.NOT_RUNNING` | `hai:scheduler:028` | 未在运行 |
+| `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 重做。
+
+公开使用以 @h-ai/scheduler 的实际入口与声明为准。声明 JSDoc 的公开示例检查 HaiResult，关闭调用使用 await scheduler.close()（返回 Promise<void>）；内部 repository/runner/compiler/cron 示例标注“模块内部上下文”，不能照抄为根导入。业务 status 与 persistence 分开，pending 补写不会重跑业务；unknown/unconfirmed 先核对共享 journal 与外部效果。应用使用所安装版本的公开类型，并通过本应用已有的类型检查验证使用示例。

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

@@ -1,31 +1,40 @@
 ---
 name: hai-serv
-description: "使用 @h-ai/serv 装配 contract/procedures、认证守卫、OpenAPI、HTTP 与语音 WebSocket。"
+description: "为独立 API 服务装配 contract/procedures、认证守卫、Node/Fetch、OpenAPI 与语音 WebSocket。"
 ---
 
 # hai-serv
 
+transport 仅支持 v2：SM2 发送方签名、独立密钥的 Encrypt-then-HMAC、HTTP 上下文/响应状态绑定及共享原子防重放。GET/HEAD、空 POST 与空响应也认证；无降级开关。TLS 信任边界、5 分钟窗口、nonce 持久化与实现示例见 [参考](reference.md)。
+
 ## 能力契约
 
-| 项目 | 契约 |
-| --- | --- |
-| 能力 | 使用 @h-ai/serv 装配 contract/procedures、认证守卫、OpenAPI、HTTP 与语音 WebSocket |
-| 适用场景 | 独立 HTTP 服务装配、请求守卫或运行时适配 |
-| 输入 | contract、procedures、已初始化 features、ServConfigInput |
-| 输出 | HTTP App、Node listener 或 Fetch handler |
-| 限制 | 无 init/close；createApp 配置错误可抛出。依赖先初始化，onClose 反序释放。Hono 为内部实现，业务授权由 route guard 执行。 |
+| 项目     | 契约                                                                                                                    |
+| -------- | ----------------------------------------------------------------------------------------------------------------------- |
+| 能力     | 使用 @h-ai/serv 装配 contract/procedures、认证守卫、OpenAPI、HTTP 与语音 WebSocket                                      |
+| 适用场景 | 独立 HTTP 服务装配、请求守卫或运行时适配                                                                                |
+| 输入     | contract、procedures、已初始化 features、ServConfigInput                                                                |
+| 输出     | HTTP App、Node listener 或 Fetch handler                                                                                |
+| 限制     | 无 init/close；createApp 配置错误可抛出。依赖先初始化，onClose 反序释放。Hono 为内部实现，业务授权由 route guard 执行。 |
 
 ## 使用路径
 
-- 先确定 Node listen 还是 Fetch adapter，再从共享 contract 装配 procedures；不要直接暴露 Hono。Node 自动提供 socket 对端；Fetch 通过 app.fetch 的 remoteAddress 元数据提供可信平台对端。http.trustedProxies 默认为空，仅显式代理 IP/CIDR 可以提供转发头；自定义 context 传递完整 input 保留解析后的 ip。
+- 在满足包 Node API 依赖的宿主中选择 listen 或标准 Fetch adapter，再从共享 contract 装配 procedures；不要直接暴露 Hono。Node 自动提供 socket 对端；Fetch 通过 app.fetch 的 remoteAddress 元数据提供可信平台对端。http.trustedProxies 默认为空，仅显式代理 IP/CIDR 可以提供转发头；自定义 context 传递完整 input 保留解析后的 ip。
+- Storage 默认 procedures 必须注入 authorize 资源策略，使用可信 session 校验全部 key/prefix；缺失策略默认拒绝，混合批量全量授权后才执行。
+- AI 默认 feature 以可信 session.userId 绑定 objectId，所有读写和记忆按主体隔离；跨主体访问必须显式 authorizeObject，同名 sessionId 不代表同一用户。
 - 认证绑定 route 的 auth/permission/role；启动配置错误与正常请求领域错误分别处理。
 - 普通 procedure 的失败 HaiResult 默认通过 HTTP 200 返回，必须检查 success 与 error.code；error.httpStatus 是领域错误元数据。contract 输入校验失败为 HTTP 400，HTTP middleware、刷新 cookie 等响应另按自身契约处理，不能混为同一种状态映射。
 - 浏览器 Cookie、CORS、apiPrefix、transport 须与 api-client 同步；语音 ticket 单独核验。
+- transport 服务端显式注入受管 serverKeyRing 和共享 keyStore；请求带协商 serverKeyId。私钥只从 Secret/私有环境加载，不放公开配置；轮换、重启与跨节点要求见 hai-crypto。
 - 缺失路由返回本地化 HaiResult JSON 404；加密传输保留该状态。默认 feature 可按需选用，contract 与挂载的 procedures 保持一致。
 
+传输加密按实际请求/响应 body 判断空正文，不信任 Content-Type/Length；非空明文不能借缺头、chunked 或伪造零长度旁路，实际空流保留无 input POST 行为。
+
+transport 与 kit/客户端共享固定 UTF-8 字节预算：握手 JSON 16 KiB、公钥 4 KiB、明文 1 MiB、密文 JSON 2 MiB + 32 KiB。原流有界读取，超限立即取消并释放 reader；请求超限 413、响应超限 500。重建 Request 保留 signal 并清空 Hono bodyCache，移除旧长度/编码头；不新增 YAML/环境变量开关。
+
 ## 按需参考
 
-详细配置、API 签名、错误码和范本在 [reference.md](reference.md)。按下列标题定位所需小节，不默认通读；用例中的业务变量需结合当前应用补齐。
+按任务读取 [reference.md](reference.md) 的对应小节；签名以当前源码或安装版本的公开类型为准，不默认加载全部资料。示例中的业务变量由应用提供。
 
 - 运行环境
 - 适用场景
@@ -37,3 +46,9 @@ description: "使用 @h-ai/serv 装配 contract/procedures、认证守卫、Open
 - 错误码
 - httpOnly Cookie 认证
 - 测试
+
+标准登出入口 `auth.logout` 从 input.accessToken 或 Authorization Bearer 取得要撤销的完整令牌，不要求 access 仍有效。它不接受 userId 授权或撤销目标；缺少令牌返回失败，未知令牌幂等成功。共享存储故障原样保留失败 HaiResult，Cookie middleware 只对成功结果清理 refresh Cookie。普通 procedure 继续使用既有 HTTP 200 / HaiResult 协议，客户端必须检查 success，不能只检查状态码。
+
+JSDoc 公开例子按实际根入口/features 声明编译；“模块内部上下文”不能照抄为根 API。工厂配置异常、领域 HaiResult 与 HTTP middleware 的状态分别处理；listener.close 仅关闭 HTTP，onClose 为信号关闭回调，业务资源仍由宿主管理。
+
+使用 toFetch 注入时，Request 输入同样应用 RequestInit 覆盖，并按标准构造器拒绝非法/已消费/锁定正文；取消会停止派发或响应等待并传给应用，不回滚副作用。Response 交付后的流由应用监听 request.signal 清理。