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

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

@@ -0,0 +1,256 @@
+# hai-payment 参考
+
+> `@h-ai/payment` 是 hai-framework 的统一支付模块，通过 Provider 模式支持微信支付、支付宝、Stripe。服务端处理订单和回调，客户端调起支付。
+
+## 运行环境
+
+> **服务端 + 浏览器分工模块。** `payment.createOrder` / `payment.handleNotify` / `payment.refund` 等操作在 Node.js 端执行。浏览器端使用 `invokePayment()`（从 `@h-ai/payment/client` 导入）调起支付。
+
+## 依赖
+
+| 模块 | 用途 | 是否必需 | 初始化要求 |
+| --- | --- | --- | --- |
+| `@h-ai/audit` | 审计日志（支付操作自动审计） | 可选 | 已初始化时自动写入审计日志 |
+
+## 适用场景
+
+- 接入微信支付（JSAPI / H5 / Native / App）
+- 接入支付宝（H5 / App / PC）
+- 接入 Stripe（Checkout Session）
+- 支付回调验签与通知处理
+- 订单查询与退款
+- 客户端调起支付（Web / H5 / App）
+
+## 使用步骤
+
+### 1. 配置
+
+```yaml
+# config/_payment.yml（自行创建）
+wechat:
+  appId: ''
+  mchId: ''
+  apiV3Key: ''
+  privateKey: ''
+  serialNo: ''
+  platformCert: ''  # 可选，回调验签需要
+
+alipay:
+  appId: ''
+  privateKey: ''
+  alipayPublicKey: ''
+  signType: RSA2  # 可选，默认 RSA2
+  sandbox: false   # 可选，默认 false
+
+stripe:
+  secretKey: ''
+  webhookSecret: ''
+  webhookToleranceSeconds: 300  # 可选，默认 300 秒
+```
+
+约定环境变量优先于 YAML，例如 `HAI_PAYMENT_WECHAT_APIV3KEY`、
+`HAI_PAYMENT_STRIPE_WEBHOOKSECRET`。生产密钥只放环境或密钥管理器。
+
+### 2. 初始化（服务端）
+
+```typescript
+import { payment } from '@h-ai/payment'
+
+const initResult = await payment.init({
+  wechat: {
+    appId: 'wx1234567890',
+    mchId: '1600000000',
+    apiV3Key: 'your-api-key-v3',
+    privateKey: '-----BEGIN RSA PRIVATE KEY-----...',
+    serialNo: 'CERT_SERIAL_NO',
+  },
+  alipay: {
+    appId: '2021000000000000',
+    privateKey: '-----BEGIN RSA PRIVATE KEY-----...',
+    alipayPublicKey: '-----BEGIN PUBLIC KEY-----...',
+  },
+})
+if (!initResult.success) {
+  // 处理初始化错误
+}
+```
+
+### 3. 创建订单
+
+```typescript
+const result = await payment.createOrder('wechat', {
+  orderNo: 'ORDER_20250101_001',
+  amount: 9900, // 单位：分
+  description: '商品名称',
+  tradeType: 'jsapi',
+  userId: 'user_openid',
+  notifyUrl: 'https://example.com/payment/notify/wechat',
+  metadata: { source: 'web' },
+})
+
+if (result.success) {
+  // result.data: PaymentOrder { provider, tradeType, clientParams, prepayId? }
+  // clientParams 包含调起支付所需参数
+}
+
+// amount / totalAmount 必须是正整数（单位：分）
+```
+
+### 4. 处理支付回调
+
+```typescript
+// API 路由：POST /payment/notify/:provider
+const result = await payment.handleNotify('wechat', {
+  body: await request.text(),
+  headers: Object.fromEntries(request.headers),
+})
+
+if (result.success) {
+  // result.data: { orderNo, transactionId, amount, status, paidAt? }
+  // 更新订单状态...
+}
+```
+
+### 5. 查询订单
+
+```typescript
+const result = await payment.queryOrder('wechat', 'ORDER_20250101_001')
+
+if (result.success) {
+  // result.data.status: 'pending' | 'paid' | 'closed' | 'refunded' | 'failed'
+}
+```
+
+### 6. 退款
+
+```typescript
+const result = await payment.refund('wechat', {
+  orderNo: 'ORDER_20250101_001',
+  refundNo: 'REFUND_20250101_001',
+  amount: 9900,
+  totalAmount: 9900, // 微信退款必填
+  reason: '用户退款',
+})
+```
+
+### 7. 客户端调起支付（浏览器）
+
+```typescript
+import { invokePayment } from '@h-ai/payment/client'
+
+// 前端拿到服务端返回的 PaymentOrder 后调起支付
+const payResult = await invokePayment(orderResult.data)
+```
+
+## 核心 API（服务端）
+
+| API                                              | 用途     | 返回值                        |
+| ------------------------------------------------ | -------- | ----------------------------- |
+| `payment.init(config)`                           | 初始化   | `HaiResult<void>`                |
+| `payment.close()`                                | 关闭     | `void`                        |
+| `payment.createOrder(providerName, input)`       | 创建订单 | `HaiResult<PaymentOrder>`        |
+| `payment.handleNotify(providerName, request)`    | 处理回调 | `HaiResult<PaymentNotifyResult>` |
+| `payment.queryOrder(providerName, orderNo)`      | 查询订单 | `HaiResult<OrderStatus>`         |
+| `payment.refund(providerName, input)`            | 退款     | `HaiResult<RefundResult>`        |
+| `payment.closeOrder(providerName, orderNo)`      | 关闭订单 | `HaiResult<void>`                |
+| `payment.getProvider(name)`                      | 获取 Provider | `PaymentProvider \| undefined` |
+| `payment.registerProvider(provider)`             | 注册自定义 Provider | `void`              |
+
+## 客户端 API
+
+| API                      | 用途     | 返回值                        |
+| ------------------------ | -------- | ----------------------------- |
+| `invokePayment(options)` | 调起支付 | `HaiResult<InvokePaymentResult>` |
+
+## 错误码 — `HaiPaymentError`
+
+| 错误码 | code | 说明 |
+|--------|------|------|
+| `HaiPaymentError.CREATE_ORDER_FAILED` | `hai:payment:001` | 创建订单失败 |
+| `HaiPaymentError.QUERY_ORDER_FAILED` | `hai:payment:002` | 查询订单失败 |
+| `HaiPaymentError.REFUND_FAILED` | `hai:payment:003` | 退款失败 |
+| `HaiPaymentError.CLOSE_ORDER_FAILED` | `hai:payment:004` | 关闭订单失败 |
+| `HaiPaymentError.NOT_INITIALIZED` | `hai:payment:010` | 模块未初始化 |
+| `HaiPaymentError.SIGN_FAILED` | `hai:payment:020` | 签名失败 |
+| `HaiPaymentError.PROVIDER_NOT_FOUND` | `hai:payment:030` | Provider 未注册 |
+| `HaiPaymentError.INVALID_AMOUNT` | `hai:payment:040` | 金额无效 |
+| `HaiPaymentError.NOTIFY_VERIFY_FAILED` | `hai:payment:050` | 回调验签失败 |
+| `HaiPaymentError.NOTIFY_PARSE_FAILED` | `hai:payment:051` | 回调解析失败 |
+| `HaiPaymentError.INVOKE_WEB_FAILED` | `hai:payment:060` | Web 端调起支付失败 |
+| `HaiPaymentError.INVOKE_APP_FAILED` | `hai:payment:061` | App 端调起支付失败 |
+| `HaiPaymentError.CONFIG_ERROR` | `hai:payment:070` | 配置无效 |
+
+## Provider 模式
+
+内置 Provider：
+
+- **wechat** — 微信支付 API v3
+- **alipay** — 支付宝开放平台
+- **stripe** — Stripe Checkout Session 模式
+
+自定义 Provider 通过 `payment.registerProvider(provider)` 注册。
+
+### HTTP API 契约
+
+```typescript
+import { apiContract } from '@h-ai/api-contract'
+
+// apiContract.payment.orders.create        — POST /payment/orders
+// apiContract.payment.orders.get           — GET  /payment/orders/{orderNo}
+// apiContract.payment.orders.refund        — POST /payment/orders/{orderNo}/refunds
+// apiContract.payment.notifications.wechat — POST /payment/notifications/wechat
+```
+
+## 常见模式
+
+### 服务端路由（SvelteKit）
+
+```typescript
+import { kit } from '@h-ai/kit'
+// src/routes/api/v1/payment/create/+server.ts
+import { payment } from '@h-ai/payment'
+
+export const POST = kit.handler(async ({ request, locals }) => {
+  const body = await request.json()
+  const result = await payment.createOrder(body.provider, {
+    orderNo: body.orderNo,
+    amount: body.amount,
+    description: body.description,
+    tradeType: body.tradeType,
+    userId: body.userId,
+    notifyUrl: body.notifyUrl,
+  })
+
+  if (!result.success) {
+    return kit.response.internalError(result.error.message)
+  }
+
+  return kit.response.ok(result.data, locals.requestId)
+})
+```
+
+### 完整支付流程
+
+```
+1. 客户端 → 服务端：创建订单（api.payment.orders.create({...})）
+2. 服务端 → 支付平台：调用 Provider 创建预支付
+3. 服务端 → 客户端：返回 providerData（含调起参数）
+4. 客户端：invokePayment(providerData) 调起支付
+5. 支付平台 → 服务端：异步回调通知
+6. 服务端：handleNotify() 验签 + 更新订单状态
+7. 客户端：轮询或回调查询订单状态
+```
+
+## 审计日志
+
+关键支付操作（创建订单、回调、退款、关闭订单）成功后自动写入审计日志（依赖 `@h-ai/audit`），无需额外配置。`queryOrder` 为只读操作，不写审计日志。
+
+内置 Provider 的 HTTP 请求默认带 15 秒超时；Stripe 可通过 `webhookToleranceSeconds` 调整 webhook 时间戳容忍窗口。
+
+## 相关 Skills
+
+- `hai-kit`：服务端 API 路由与契约处理
+- `hai-api-client`：客户端契约调用
+- `hai-reldb`：订单持久化存储
+- `hai-audit`：审计日志（payment 内部自动调用）
+- `hai-core`：HaiResult 类型、日志、配置

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

@@ -49,11 +49,11 @@ description: "审查 PR 范围、风险、验证证据和合并准备度。"
 
 - AI Review 默认只评论、不阻塞 merge。
 - 只有在 CI 稳定、误报可控、团队明确同意后，才考虑将特定静态规则设为 blocking。
-- AI 的建议必须由人类判断，不得自动 merge。
+- AI 建议须用实现与测试核实；执行合并必须有用户授权并满足仓库规则。
 
 ## AI-assisted PR 要求
 
-PR 描述必须说明：
+按仓库 PR 模板说明；要求披露 AI 使用时包含：
 
 - 是否使用 AI 辅助
 - AI 负责了哪部分：搜索、实现、测试、review、文档
@@ -62,7 +62,7 @@ PR 描述必须说明：
 
 ## Issue 关联与上下文交接
 
-- PR 必须关联 issue 或说明为什么不需要 issue。
+- 按当前仓库规则关联 issue；没有 issue 时清楚描述需求与验收。
 - PR scope 必须与 issue 的目标、验收标准和明确不做事项一致。
 - AI-assisted PR 必须说明 AI 负责了哪些阶段，以及人类如何复核。
 - 多人或多 agent 协作时，PR 描述必须列出 reviewer focus，避免重复 review。
@@ -82,7 +82,7 @@ PR 描述必须说明：
 
 - ❌ 不在 `pull_request_target` 中运行 AI agent 读取 PR 代码和 secrets。
 - ❌ 不给 AI Review workflow 默认 `contents: write`、`pull-requests: write`，除非只用于评论且触发源可信。
-- ❌ 不允许 AI 自动合并 PR。
+- ❌ 不因收到审查任务就擅自合并 PR。
 - ❌ 不把私有提示词、聊天原文、token、cookie、连接串写入 PR。
 - ✅ AI Review 的 prompt 必须限制任务范围、禁止执行 secrets、要求引用具体文件/行。
 

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

@@ -1,6 +1,6 @@
 ---
 name: hai-reach
-description: "使用 @h-ai/reach 配置邮件、短信、API 通知和多渠道消息模板。"
+description: "接入邮件、短信、API 通知与模板，处理发送结果、免打扰和可选持久化。"
 ---
 
 # hai-reach
@@ -22,7 +22,7 @@ description: "使用 @h-ai/reach 配置邮件、短信、API 通知和多渠道
 
 ## 按需参考
 
-详细配置、API 签名、错误码和范本在 [reference.md](reference.md)。按下列标题定位所需小节，不默认通读；用例中的业务变量需结合当前应用补齐。
+按任务读取 [reference.md](reference.md) 的对应小节；签名以当前源码或安装版本的公开类型为准，不默认加载全部资料。示例中的业务变量由应用提供。
 
 - 运行环境
 - 依赖

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

@@ -24,7 +24,7 @@ description: "使用 @h-ai/reldb 访问 SQLite/PostgreSQL/MySQL，编写 SQL、C
 
 ## 按需参考
 
-详细配置、API 签名、错误码和范本在 [reference.md](reference.md)。按下列标题定位所需小节，不默认通读；用例中的业务变量需结合当前应用补齐。
+按任务读取 [reference.md](reference.md) 的对应小节；签名以当前源码或安装版本的公开类型为准，不默认加载全部资料。示例中的业务变量由应用提供。
 
 - 运行环境
 - 适用场景

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

@@ -1,24 +1,12 @@
 ---
 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 任务、手工触发并查询执行日志 |
@@ -27,189 +15,21 @@ API 任务 `timeout` 默认 30000 毫秒，覆盖请求及完整响应体读取
 | 输出 | 任务管理、触发和日志查询的 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' })
-
-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,
-  nodeId: 'node-1',
-})
-```
+1. 持久化模式先初始化 reldb；多节点需共享数据库与 Redis，Memory 只用于单进程。检查 scheduler.init 的 HaiResult。
+2. 动态共享任务通过 register 管理，不与 init.tasks 重复声明；读取失败、禁用、删除或改期时不得继续旧任务。
+3. 根据可信逻辑选择 API/JS/Hook。Worker/vm 不是安全沙箱；Hook 监听 signal，业务以 occurrenceId 处理幂等。
+4. 明确 timeout、响应大小、重试与执行状态；关闭时 await scheduler.close，再关闭数据库和缓存。
+5. 验证手动/定时、并发抢锁、失败重试、取消与定义更新。
 
-## 错误码 — `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)