@h-ai/cli 0.1.0-alpha5

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

@@ -0,0 +1,459 @@
+---
+name: hai-reldb
+description: 使用 @h-ai/reldb 进行 SQLite/PostgreSQL/MySQL 的初始化、SQL/DDL/CRUD/事务与分页操作；当需求涉及数据库访问、CRUD 仓库、事务处理、分页查询或 HaiReldbError 分支处理时使用。
+---
+
+# hai-reldb
+
+> `@h-ai/reldb` 提供统一的数据库操作接口，支持 SQLite、PostgreSQL、MySQL，包含 DDL、SQL、CRUD 抽象、事务与分页。
+
+---
+
+## 适用场景
+
+- 新增或修改数据库访问逻辑（SQL/DDL/CRUD/事务）
+- 使用 `reldb.crud.table` 或 `BaseReldbCrudRepository` 构建数据仓库
+- 处理分页查询与分页结果规范化
+- 基于 `HaiReldbError` 做错误分支处理
+- JSON 列的路径提取、设置、插入、删除、合并操作（跨数据库统一语法）
+
+---
+
+## 使用步骤
+
+### 1. 配置
+
+```yaml
+# config/_db.yml
+type: ${HAI_RELDB_TYPE:sqlite}
+database: ${HAI_RELDB_DATABASE:./data/app.db}
+# PostgreSQL/MySQL 额外字段：
+# host: ${HAI_RELDB_HOST:localhost}
+# port: ${HAI_RELDB_PORT:5432}
+# user: ${HAI_RELDB_USER:postgres}
+# password: ${HAI_RELDB_PASSWORD:}
+```
+
+### 2. 初始化与关闭
+
+```typescript
+import { core } from '@h-ai/core'
+import { reldb } from '@h-ai/reldb'
+
+await reldb.init(core.config.get('db'))
+// ... 使用数据库
+await reldb.close()
+```
+
+### 3. 选择操作接口
+
+| 接口 | 用途               | 入口                         |
+| ---- | ------------------ | ---------------------------- |
+| DDL  | 建表/索引/字段变更 | `reldb.ddl`                     |
+| SQL  | 原始查询/执行/分页 | `reldb.sql`                     |
+| CRUD | 通用增删改查       | `reldb.crud.table(config)`      |
+| 仓库 | 业务数据仓库封装   | `extends BaseReldbCrudRepository` |
+| 事务 | 事务管理           | `reldb.tx`                      |
+| 分页 | 分页参数与结果     | `reldb.pagination`              |
+| JSON | JSON 路径操作      | `reldb.json`                    |
+
+---
+
+## 核心 API
+
+### DDL — `reldb.ddl`
+
+| 方法          | 签名                                                                    | 说明                       |
+| ------------- | ----------------------------------------------------------------------- | -------------------------- |
+| `createTable` | `(tableName, columns: TableDef, ifNotExists?: boolean) => HaiResult<void>` | 建表（默认 IF NOT EXISTS） |
+| `dropTable`   | `(tableName, ifExists?: boolean) => HaiResult<void>`                       | 删除表（默认 IF EXISTS）   |
+| `addColumn`   | `(tableName, columnName, columnDef: ColumnDef) => HaiResult<void>`         | 添加列                     |
+| `dropColumn`  | `(tableName, columnName) => HaiResult<void>`                               | 删除列                     |
+| `renameTable` | `(oldName, newName) => HaiResult<void>`                                    | 重命名表                   |
+| `createIndex` | `(tableName, indexName, indexDef: IndexDef) => HaiResult<void>`            | 创建索引                   |
+| `dropIndex`   | `(indexName, ifExists?: boolean) => HaiResult<void>`                       | 删除索引                   |
+| `raw`         | `(sql: string) => HaiResult<void>`                                         | 执行原始 DDL               |
+
+> 所有方法均返回 `Promise<HaiResult<void>>`，上表省略异步与错误类型。
+
+**TableDef**（列名到列定义的映射）：
+
+```typescript
+const columns: TableDef = {
+  id: { type: 'INTEGER', primaryKey: true, autoIncrement: true },
+  name: { type: 'TEXT', notNull: true },
+  email: { type: 'TEXT', unique: true },
+  score: { type: 'REAL', defaultValue: 0 },
+  active: { type: 'BOOLEAN' },
+  metadata: { type: 'JSON' },
+  created_at: { type: 'TIMESTAMP' },
+}
+```
+
+**ColumnDef**（列类型与约束）：
+
+```typescript
+interface ColumnDef {
+  type: 'TEXT' | 'INTEGER' | 'REAL' | 'BLOB' | 'BOOLEAN' | 'TIMESTAMP' | 'JSON'
+  primaryKey?: boolean
+  autoIncrement?: boolean
+  notNull?: boolean
+  unique?: boolean
+  defaultValue?: string | number | boolean | null
+  references?: { table: string, column: string, onDelete?: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION', onUpdate?: '...' }
+}
+```
+
+**跨数据库类型映射**：
+
+| 类型      | SQLite  | PostgreSQL       | MySQL        |
+| --------- | ------- | ---------------- | ------------ |
+| TEXT      | TEXT    | TEXT             | VARCHAR(255) |
+| INTEGER   | INTEGER | INTEGER/SERIAL   | INT/BIGINT   |
+| REAL      | REAL    | DOUBLE PRECISION | DOUBLE       |
+| BLOB      | BLOB    | BYTEA            | BLOB         |
+| BOOLEAN   | INTEGER | BOOLEAN          | TINYINT(1)   |
+| TIMESTAMP | INTEGER | TIMESTAMP        | DATETIME     |
+| JSON      | TEXT    | JSONB            | JSON         |
+
+> MySQL 将 TEXT 映射为 VARCHAR(255) 以支持索引和 UNIQUE 约束。INTEGER + autoIncrement 在 MySQL 映射为 BIGINT。
+
+### SQL — `reldb.sql`
+
+| 方法        | 签名                                                              | 说明         |
+| ----------- | ----------------------------------------------------------------- | ------------ |
+| `query`     | `<T>(sql, params?) => HaiResult<T[]>`                                | 查询返回多行 |
+| `get`       | `<T>(sql, params?) => HaiResult<T \| null>`                          | 查询返回单行 |
+| `execute`   | `(sql, params?) => HaiResult<ExecuteResult>`                         | 执行写操作   |
+| `batch`     | `(statements: Array<{ sql, params? }>) => HaiResult<void>`           | 批量执行     |
+| `queryPage` | `<T>(options: PaginationQueryOptions) => HaiResult<PaginatedResult>` | 分页查询     |
+
+> 所有方法均返回 `Promise<HaiResult<T>>`，上表省略异步与错误类型。
+
+**参数占位符统一使用 `?`**（PostgreSQL 的 `$n` 由 Provider 自动转换）：
+
+```typescript
+const result = await reldb.sql.query<User>(
+  'SELECT * FROM users WHERE status = ? AND age > ?',
+  ['active', 18],
+)
+```
+
+**ExecuteResult**：
+
+```typescript
+interface ExecuteResult {
+  changes: number // 影响的行数
+  lastInsertRowid?: number | bigint // INSERT 时生效（PostgreSQL 不返回此字段）
+}
+```
+
+**分页查询**：
+
+```typescript
+const page = await reldb.sql.queryPage<User>({
+  sql: 'SELECT * FROM users WHERE status = ? ORDER BY id',
+  params: ['active'],
+  pagination: { page: 1, pageSize: 20 },
+  overrides: { maxPageSize: 100 }, // 可选：限制最大页大小
+})
+// page.data => { items, total, page, pageSize }
+```
+
+### CRUD — `reldb.crud.table(config)`
+
+通过配置创建单表 CRUD 仓库，免写 SQL：
+
+```typescript
+const userCrud = reldb.crud.table<{ id: number, name: string, email: string }>({
+  table: 'users',
+  idColumn: 'id',           // 主键列，默认 'id'
+  select: ['id', 'name', 'email'],   // 查询列，默认 '*'
+  createColumns: ['name', 'email'],   // 允许插入的列
+  updateColumns: ['name', 'email'],   // 允许更新的列
+})
+```
+
+返回的 ReldbCrudRepository 方法：
+
+| 方法         | 签名                                           | 说明         |
+| ------------ | ---------------------------------------------- | ------------ |
+| `create`     | `(data, tx?) => HaiResult<ExecuteResult>`         | 创建单条     |
+| `createMany` | `(items, tx?) => HaiResult<void>`                 | 批量创建     |
+| `findById`   | `(id, tx?) => HaiResult<T \| null>`               | 按 ID 查询   |
+| `findAll`    | `(options?, tx?) => HaiResult<T[]>`               | 条件查询     |
+| `findPage`   | `(options, tx?) => HaiResult<PaginatedResult<T>>` | 分页查询     |
+| `updateById` | `(id, data, tx?) => HaiResult<ExecuteResult>`     | 按 ID 更新   |
+| `deleteById` | `(id, tx?) => HaiResult<ExecuteResult>`           | 按 ID 删除   |
+| `count`      | `(options?, tx?) => HaiResult<number>`            | 计数         |
+| `exists`     | `(options?, tx?) => HaiResult<boolean>`           | 条件是否存在 |
+| `existsById` | `(id, tx?) => HaiResult<boolean>`                 | ID 是否存在  |
+
+> 所有方法均支持可选 `tx` 事务参数。`create`/`updateById` 中的 `data` 会根据 `createColumns`/`updateColumns` 白名单过滤列。
+
+**使用示例**：
+
+```typescript
+// 单条插入
+const result = await userCrud.create({ name: '张三', email: 'test@example.com' })
+// result.data → { changes: 1, lastInsertRowid: 1 }
+
+// 批量插入
+await userCrud.createMany([
+  { name: '用户A', email: 'a@test.com' },
+  { name: '用户B', email: 'b@test.com' },
+])
+
+// 主键查找
+const user = await userCrud.findById(1)
+// user.data → { id: 1, name: '张三', email: 'test@example.com' } | null
+
+// 条件查询（where + params 占位符）
+const actives = await userCrud.findAll({
+  where: 'name LIKE ?',
+  params: ['%张%'],
+  orderBy: 'id DESC',
+  limit: 10,
+  offset: 0,
+})
+
+// 分页查询
+const page = await userCrud.findPage({
+  where: 'name LIKE ?',
+  params: ['%张%'],
+  orderBy: 'id DESC',
+  pagination: { page: 1, pageSize: 20 },
+})
+// page.data → { items: [...], total: 100, page: 1, pageSize: 20 }
+
+// 更新 / 删除
+await userCrud.updateById(1, { name: '新名字' })
+await userCrud.deleteById(1)
+
+// 计数 / 存在性
+const total = await userCrud.count({ where: 'name LIKE ?', params: ['%张%'] })
+const has = await userCrud.exists({ where: 'email = ?', params: ['test@example.com'] })
+const found = await userCrud.existsById(1)
+
+// 事务中使用（所有方法均支持 tx 参数）
+await reldb.tx.wrap(async (tx) => {
+  await userCrud.create({ name: '用户A', email: 'a@test.com' }, tx)
+  await userCrud.updateById(1, { name: '新名字' }, tx)
+  const user = await userCrud.findById(1, tx)
+})
+```
+
+### BaseReldbCrudRepository
+
+业务仓库基类，提供字段映射、自动建表与类型转换能力：
+
+```typescript
+import { BaseReldbCrudRepository } from '@h-ai/reldb'
+
+interface User { id: number, name: string, email: string, createdAt: Date, updatedAt: Date }
+
+class UserRepository extends BaseReldbCrudRepository<User> {
+  constructor() {
+    super(db, {
+      table: 'users',
+      idColumn: 'id',
+      fields: [
+        { fieldName: 'id', columnName: 'id', def: { type: 'INTEGER', primaryKey: true, autoIncrement: true }, select: true, create: false, update: false },
+        { fieldName: 'name', columnName: 'name', def: { type: 'TEXT', notNull: true }, select: true, create: true, update: true },
+        { fieldName: 'email', columnName: 'email', def: { type: 'TEXT', notNull: true }, select: true, create: true, update: true },
+        { fieldName: 'createdAt', columnName: 'created_at', def: { type: 'TIMESTAMP', notNull: true }, select: true, create: true, update: false },
+        { fieldName: 'updatedAt', columnName: 'updated_at', def: { type: 'TIMESTAMP', notNull: true }, select: true, create: true, update: false },
+      ],
+    })
+  }
+
+  /** 自定义查询示例 */
+  async findByEmail(email: string, tx?: DmlWithTxOperations) {
+    return this.sql(tx).get<User>('SELECT * FROM users WHERE email = ?', [email])
+  }
+}
+```
+
+**`this.sql(tx?)`**：返回 `DmlOperations`（`reldb.sql` 或传入的事务句柄），自动适配事务场景。
+
+**自动能力**：
+
+- `createdAt` / `updatedAt` 字段自动填充时间戳
+- 主键生成（非 autoIncrement 主键默认使用 `crypto.randomUUID()`）
+- BOOLEAN → 1/0（SQLite/MySQL）或 true/false（PostgreSQL）
+- TIMESTAMP → 毫秒时间戳（SQLite）或 Date（PG/MySQL）
+- JSON → 字符串序列化（SQLite/MySQL）或原生 JSONB（PG）
+
+### 事务 — `reldb.tx`
+
+```typescript
+// 方式1：wrap（自动 commit/rollback）
+const result = await reldb.tx.wrap(async (tx) => {
+  await tx.execute('INSERT INTO users (name) VALUES (?)', ['张三'])
+  await tx.execute('INSERT INTO logs (action) VALUES (?)', ['user_created'])
+  return 'done'
+})
+// result.data === 'done'（正常返回自动 commit）
+// 回调抛异常 → 自动 rollback → result.success === false
+
+// 方式2：手动管理
+const txResult = await reldb.tx.begin()
+if (txResult.success) {
+  const tx = txResult.data
+  try {
+    await tx.execute('INSERT INTO users (name) VALUES (?)', ['李四'])
+    await tx.commit()
+  }
+  catch {
+    await tx.rollback()
+  }
+}
+```
+
+**事务内可用操作**（`DmlWithTxOperations` 继承 `DmlOperations`）：
+
+- `tx.query / tx.get / tx.execute / tx.batch / tx.queryPage`
+- `tx.crud.table(config)` — 事务内的 CRUD 仓库
+- `tx.commit() / tx.rollback()`
+
+### 分页 — `reldb.pagination`
+
+| 方法        | 签名                                                  | 说明                                   |
+| ----------- | ----------------------------------------------------- | -------------------------------------- |
+| `normalize` | `(options?, overrides?) => NormalizedPagination`      | 规范化分页参数（含 offset/limit 计算） |
+| `build`     | `<T>(items, total, pagination) => PaginatedResult<T>` | 构建分页结果对象                       |
+
+```typescript
+// PaginatedResult 结构
+interface PaginatedResult<T> {
+  items: T[]
+  total: number
+  page: number
+  pageSize: number
+}
+
+// 默认值：page=1, pageSize=20, maxPageSize=200
+```
+
+---
+
+### JSON — `reldb.json`
+
+通过 `reldb.json` 构建跨数据库统一的 JSON 路径操作 SQL 表达式，返回 `{ sql, params }` 可直接嵌入 `reldb.sql.*`。
+
+路径格式遵循 SQL/JSON Path 标准，以 `$` 开头（如 `$.key`、`$.key.subkey`、`$[0]`）。
+
+| 操作      | SQLite             | PostgreSQL               | MySQL                  |
+| --------- | ------------------ | ------------------------ | ---------------------- |
+| `extract` | `json_extract`     | `#>` (text[])            | `JSON_EXTRACT`         |
+| `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`     |
+
+```typescript
+// 提取 JSON 字段值（用于 WHERE 条件）
+const { sql, params } = reldb.json.extract('settings', '$.theme')
+const rows = await reldb.sql.query(
+  `SELECT * FROM users WHERE ${sql} = ?`,
+  [...params, '"dark"'],
+)
+
+// 设置 JSON 字段路径（创建或替换）
+const { sql, params } = reldb.json.set('settings', '$.theme', 'dark')
+await reldb.sql.execute(
+  `UPDATE users SET settings = ${sql} WHERE id = ?`,
+  [...params, userId],
+)
+
+// 删除 JSON 字段路径
+const { sql, params } = reldb.json.remove('settings', '$.deprecated')
+await reldb.sql.execute(`UPDATE users SET settings = ${sql} WHERE id = ?`, [...params, id])
+
+// 合并 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])
+```
+
+> `column` 参数为列名，**禁止传入用户输入**（开发者负责安全性）。
+
+---
+
+## 错误码 — `HaiReldbError`
+
+| 错误码 | code | 说明 |
+|--------|------|------|
+| `HaiReldbError.CONNECTION_FAILED`    | `hai:reldb:001`  | 数据库连接失败     |
+| `HaiReldbError.QUERY_FAILED`         | `hai:reldb:002`  | 查询或执行失败     |
+| `HaiReldbError.CONSTRAINT_VIOLATION` | `hai:reldb:003`  | 约束违反           |
+| `HaiReldbError.TRANSACTION_FAILED`   | `hai:reldb:004`  | 事务失败           |
+| `HaiReldbError.MIGRATION_FAILED`     | `hai:reldb:005`  | 迁移失败           |
+| `HaiReldbError.RECORD_NOT_FOUND`     | `hai:reldb:006`  | 记录不存在         |
+| `HaiReldbError.DUPLICATE_ENTRY`      | `hai:reldb:007`  | 重复条目           |
+| `HaiReldbError.DEADLOCK`             | `hai:reldb:008`  | 死锁               |
+| `HaiReldbError.TIMEOUT`              | `hai:reldb:009`  | 超时               |
+| `HaiReldbError.POOL_EXHAUSTED`       | `hai:reldb:010`  | 连接池耗尽         |
+| `HaiReldbError.NOT_INITIALIZED`      | `hai:reldb:011`  | 数据库未初始化     |
+| `HaiReldbError.DDL_FAILED`           | `hai:reldb:012`  | DDL 操作失败       |
+| `HaiReldbError.UNSUPPORTED_TYPE`     | `hai:reldb:013`  | 不支持的数据库类型 |
+| `HaiReldbError.CONFIG_ERROR`         | `hai:reldb:014`  | 配置错误           |
+
+---
+
+## 常见模式
+
+### API 端点中使用
+
+```typescript
+import { reldb, HaiReldbError } from '@h-ai/reldb'
+import { kit } from '@h-ai/kit'
+
+export async function GET(event) {
+  const { valid, data } = kit.validate.query(event.url, PageSchema)
+  if (!valid)
+    return kit.response.badRequest('Invalid params')
+
+  const result = await userCrud.findPage({
+    pagination: data,
+    orderBy: 'id ASC',
+  })
+  if (!result.success)
+    return kit.response.internalError()
+
+  return kit.response.ok(result.data)
+}
+```
+
+### 事务跨仓库
+
+```typescript
+const result = await reldb.tx.wrap(async (tx) => {
+  const user = await userRepo.create(userData, tx)
+  if (!user.success)
+    throw new Error(user.error.message)
+
+  await profileRepo.create({ userId: user.data.lastInsertRowid, ...profileData }, tx)
+  return user.data
+})
+```
+
+### BaseReldbCrudRepository 事务集成
+
+```typescript
+const txResult = await reldb.tx.begin()
+if (txResult.success) {
+  const tx = txResult.data
+  await userRepo.create({ name: '用户A', email: 'a@test.com' }, tx)
+  await userRepo.create({ name: '用户B', email: 'b@test.com' }, tx)
+  await tx.commit()
+}
+```
+
+---
+
+## 相关 Skills
+
+- `hai-build`：模块初始化顺序
+- `hai-core`：配置管理、HaiResult 模型
+- `hai-iam`：IAM 模块内部使用 reldb 进行用户/角色/权限存储
+- `hai-cache`：缓存穿透保护中配合 reldb 使用

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

@@ -0,0 +1,242 @@
+---
+name: hai-scheduler
+description: 使用 @h-ai/scheduler 进行统一定时任务管理、任务持久化、手工触发、触发来源审计、全局生命周期回调与执行日志查询；当需求涉及 cron 调度、JS 函数字符串任务、API 任务、分布式锁或任务事件回调时使用。
+---
+
+# hai-scheduler
+
+> `@h-ai/scheduler` 使用统一任务模型管理 API / JS / Hook 三类执行路径，支持持久化、手工触发来源记录、分布式锁与全局生命周期回调。
+
+## 依赖
+
+| 模块 | 用途 | 是否必需 | 初始化要求 |
+| --- | --- | --- | --- |
+| `@h-ai/reldb` | 任务定义与执行日志持久化 | `enableDb: true` 时必需 | 需在 `scheduler.init()` 前初始化 |
+| `@h-ai/cache` | 分布式锁 | 可选 | 初始化后自动启用 |
+
+## 使用步骤
+
+### 1. 初始化
+
+```ts
+import { cache } from '@h-ai/cache'
+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) {
+      console.info('start', event.task.id, event.trigger)
+    },
+    onTaskInterrupted(event) {
+      console.warn('interrupted', event.task.id, event.reason)
+    },
+    onTaskFinish(event) {
+      console.info('finish', 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 })',
+  },
+})
+```
+
+### 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 },
+})
+```
+
+## 核心类型
+
+### TaskDefinition
+
+```ts
+interface TaskDefinition {
+  id: string
+  name: string
+  description?: string
+  cron: string
+  enabled?: boolean
+  deleteAfterRun?: boolean
+  retry?: {
+    maxAttempts: number
+    backoffMs?: number[]
+  }
+  params?: Record<string, unknown>
+  handler?: ApiTaskConfig | JsTaskConfig
+}
+```
+
+### Handler 配置
+
+```ts
+interface ApiTaskConfig {
+  kind: 'api'
+  url: string
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'
+  headers?: Record<string, string>
+  body?: unknown
+  timeout?: number
+}
+
+interface JsTaskConfig {
+  kind: 'js'
+  code: string
+  timeout?: number
+}
+```
+
+### TaskExecutionLog
+
+```ts
+interface TaskExecutionLog {
+  id: number
+  taskId: string
+  taskName: string
+  taskType: 'api' | 'js' | 'hook'
+  triggerType: 'scheduled' | 'manual'
+  triggerSource: string | null
+  status: 'success' | 'failed' | 'interrupted'
+  result: string | null
+  error: string | null
+  startedAt: number
+  finishedAt: number
+  duration: number
+}
+```
+
+## 核心 API
+
+| 方法 / 属性 | 签名 | 说明 |
+| --- | --- | --- |
+| `init` | `(config?) => Promise<HaiResult<void>>` | 初始化调度器 |
+| `register` | `(task) => Promise<HaiResult<void>>` | 注册统一任务模型 |
+| `updateTask` | `(taskId, updates) => Promise<HaiResult<void>>` | 更新 cron / params / handler |
+| `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',
+})
+```
+
+## 错误码 — `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 执行失败 |