agentworkshop 0.2.1

package/server/services/workshop/daq/storage/timescale.adapter.ts

@@ -0,0 +1,185 @@
+/**
+ * TimescaleAdapter —— 生产级 TimescaleDB 实现(端口契约见 tsdb-port)。
+ *
+ * 由 DAQ_TSDB_URL(postgres://user:pass@host:5432/db)启用。首次 init 幂等建表
+ * 并调用 create_hypertable(ts 列,chunk 按天);写走参数化批量 INSERT,
+ * 读按 time_bucket 降采样(Timescale 原生函数)。连接失败由工厂捕获降级仿真库。
+ */
+import { createRequire } from 'node:module'
+import type { Pool } from 'pg'
+import type { DaqQueryOpts, DaqSampleRow, TsdbPoint, TsdbPort } from './tsdb-port'
+
+/* nitro(Windows)dev 下对 external 的动态 import 会生成绝对盘符路径 → ESM loader
+ * 拒绝 'd:' scheme;用 createRequire 走 CJS require 由 Node 原生解析(生产亦同)。 */
+const requirePg = createRequire(import.meta.url)
+
+export class TimescaleAdapter implements TsdbPort {
+  readonly backend = 'timescale'
+  private pool: Pool | null = null
+  private retentionTimer: NodeJS.Timeout | null = null
+  /** 保留期(默认 7 天,DAQ_TS_RETENTION_H 可调) */
+  private readonly retentionH = Number(process.env.DAQ_TS_RETENTION_H ?? 168)
+
+  constructor(private readonly url: string) {}
+
+  async init(): Promise<void> {
+    const mod = requirePg('pg') as typeof import('pg')
+    this.pool = new mod.Pool({ connectionString: this.url, max: 4 })
+    await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS daq_samples (
+        node_id text        NOT NULL,
+        ts       timestamptz NOT NULL,
+        value    double precision NOT NULL,
+        state    text        NOT NULL DEFAULT 'ok',
+        PRIMARY KEY (node_id, ts)
+      );
+    `)
+    // hypertable 幂等创建(未装 timescaledb 扩展时报错 → 由工厂降级)
+    await this.pool.query(
+      `SELECT create_hypertable('daq_samples', 'ts', if_not_exists => TRUE, migrate_data => TRUE)`,
+    )
+    await this.pool.query(`CREATE INDEX IF NOT EXISTS idx_daq_samples_node_ts ON daq_samples (node_id, ts DESC)`)
+    // 存量库迁移:先补打标列(幂等;已存在时报错吞掉),再建依赖列的索引
+    for (const ddl of [
+      'ALTER TABLE daq_samples ADD COLUMN IF NOT EXISTS line_id text',
+      'ALTER TABLE daq_samples ADD COLUMN IF NOT EXISTS product_id text',
+      'ALTER TABLE daq_samples ADD COLUMN IF NOT EXISTS recipe_id text',
+      'ALTER TABLE daq_samples ADD COLUMN IF NOT EXISTS run_id text',
+    ]) {
+      await this.pool.query(ddl).catch(() => {})
+    }
+    await this.pool.query(`CREATE INDEX IF NOT EXISTS idx_daq_samples_tag ON daq_samples (product_id, recipe_id, ts DESC)`).catch(() => {})
+    // 保留期:drop_chunks 周期执行(30min;未装扩展时静默跳过)
+    void this.sweepRetention()
+    if (!this.retentionTimer) {
+      this.retentionTimer = setInterval(() => void this.sweepRetention(), 30 * 60_000)
+      this.retentionTimer.unref?.()
+    }
+  }
+
+  private async sweepRetention(): Promise<void> {
+    if (!this.pool) return
+    try {
+      await this.pool.query(
+        `SELECT drop_chunks('daq_samples', older_than => now() - ($1 || ' hours')::interval)`,
+        [this.retentionH],
+      )
+    }
+    catch { /* 非 hypertable(扩展缺失)→ 静默 */ }
+  }
+
+  async close(): Promise<void> {
+    if (this.retentionTimer) {
+      clearInterval(this.retentionTimer)
+      this.retentionTimer = null
+    }
+    await this.pool?.end().catch(() => {})
+    this.pool = null
+  }
+
+  async writeSamples(rows: DaqSampleRow[]): Promise<void> {
+    if (!this.pool || rows.length === 0) return
+    const values: unknown[] = []
+    const tuples = rows.map((r, i) => {
+      values.push(r.nodeId, new Date(r.tsMs).toISOString(), r.value, r.state, r.lineId ?? null, r.productId ?? null, r.recipeId ?? null, r.runId ?? null)
+      const b = i * 8
+      return `($${b + 1}, $${b + 2}, $${b + 3}, $${b + 4}, $${b + 5}, $${b + 6}, $${b + 7}, $${b + 8})`
+    })
+    await this.pool.query(
+      `INSERT INTO daq_samples (node_id, ts, value, state, line_id, product_id, recipe_id, run_id) VALUES ${tuples.join(',')}
+       ON CONFLICT (node_id, ts) DO NOTHING`,
+      values,
+    )
+  }
+
+  async query(nodeId: string, opts: DaqQueryOpts): Promise<TsdbPoint[]> {
+    if (!this.pool) return []
+    const limit = Math.min(opts.limit ?? 500, 5000)
+    if (opts.bucketMs && opts.bucketMs >= 100) {
+      const { rows } = await this.pool.query(
+        `SELECT time_bucket($1::interval, ts) AS bucket,
+                avg(value)::double precision AS avg, min(value) AS min, max(value) AS max, count(*) AS cnt
+         FROM daq_samples WHERE node_id = $2 AND ts >= $3 AND ts <= $4
+         GROUP BY bucket ORDER BY bucket DESC LIMIT $5`,
+        [`${opts.bucketMs} milliseconds`, nodeId, new Date(opts.fromMs ?? 0).toISOString(), new Date(opts.toMs ?? Date.now()).toISOString(), limit],
+      )
+      return rows.map(r => ({ at: Date.parse(r.bucket), avg: Number(r.avg), min: Number(r.min), max: Number(r.max), cnt: Number(r.cnt) }))
+    }
+    const { rows } = await this.pool.query(
+      `SELECT ts, value, state FROM daq_samples WHERE node_id = $1 AND ts >= $2 AND ts <= $3
+       ORDER BY ts DESC LIMIT $4`,
+      [nodeId, new Date(opts.fromMs ?? 0).toISOString(), new Date(opts.toMs ?? Date.now()).toISOString(), limit],
+    )
+    return rows.map(r => ({ at: Date.parse(r.ts), value: Number(r.value), state: String(r.state) }))
+  }
+
+  async queryTagged(q: import('./tsdb-port').TsdbTagQuery): Promise<Map<string, import('./tsdb-port').TsdbPoint[]>> {
+    const out = new Map<string, import('./tsdb-port').TsdbPoint[]>()
+    if (!this.pool) return out
+    const where: string[] = []
+    const params: unknown[] = []
+    if (q.lineId) {
+      where.push(`line_id = $${params.length + 1}`)
+      params.push(q.lineId)
+    }
+    if (q.productId) {
+      where.push(`product_id = $${params.length + 1}`)
+      params.push(q.productId)
+    }
+    if (q.recipeId) {
+      where.push(`recipe_id = $${params.length + 1}`)
+      params.push(q.recipeId)
+    }
+    if (q.runId) {
+      where.push(`run_id = $${params.length + 1}`)
+      params.push(q.runId)
+    }
+    if (q.nodeIds?.length) {
+      where.push(`node_id = ANY($${params.length + 1})`)
+      params.push(q.nodeIds)
+    }
+    where.push(`ts >= $${params.length + 1}`)
+    params.push(new Date(q.fromMs ?? 0).toISOString())
+    where.push(`ts <= $${params.length + 1}`)
+    params.push(new Date(q.toMs ?? Date.now()).toISOString())
+    const limit = Math.min(q.limit ?? 2000, 10_000)
+    const whereSql = where.join(' AND ')
+    if (q.bucketMs && q.bucketMs >= 100) {
+      const { rows } = await this.pool.query(
+        `SELECT node_id, time_bucket($${params.length + 1}::interval, ts) AS b_at,
+                avg(value)::double precision AS avg, min(value) AS min, max(value) AS max, count(*) AS cnt
+         FROM daq_samples WHERE ${whereSql}
+         GROUP BY node_id, b_at ORDER BY b_at ASC LIMIT $${params.length + 2}`,
+        [...params, `${q.bucketMs} milliseconds`, limit],
+      )
+      for (const r of rows as Array<{ node_id: string, b_at: string, avg: string, min: string, max: string, cnt: string }>) {
+        const list = out.get(String(r.node_id)) ?? []
+        list.push({ at: Date.parse(r.b_at), avg: Number(r.avg), min: Number(r.min), max: Number(r.max), cnt: Number(r.cnt) })
+        out.set(String(r.node_id), list)
+      }
+      return out
+    }
+    const { rows } = await this.pool.query(
+      `SELECT node_id, ts, value FROM daq_samples WHERE ${whereSql} ORDER BY ts ASC LIMIT $${params.length + 1}`,
+      [...params, limit],
+    )
+    for (const r of rows as Array<{ node_id: string, ts: string, value: number }>) {
+      const list = out.get(String(r.node_id)) ?? []
+      list.push({ at: Date.parse(r.ts), value: Number(r.value) })
+      out.set(String(r.node_id), list)
+    }
+    return out
+  }
+
+  async latest(): Promise<Map<string, DaqSampleRow>> {
+    const out = new Map<string, DaqSampleRow>()
+    if (!this.pool) return out
+    const { rows } = await this.pool.query(
+      `SELECT DISTINCT ON (node_id) node_id, ts, value, state FROM daq_samples ORDER BY node_id, ts DESC`,
+    )
+    for (const r of rows) {
+      out.set(String(r.node_id), { nodeId: String(r.node_id), tsMs: Date.parse(r.ts), value: Number(r.value), state: String(r.state) })
+    }
+    return out
+  }
+}

package/server/services/workshop/daq/storage/tsdb-port.ts

@@ -0,0 +1,74 @@
+/**
+ * TsdbPort —— 时序数据库端口(hexagonal seam)。
+ *
+ * 数采读数的唯一持久化出口;采集管线只依赖此接口:
+ *   采集(生产者) → MQTT 队列 → 消费者 → writeSamples() 落时序库
+ *                                                ↘ query()/latest() → 前端历史/图表
+ *
+ * 实现:
+ *  - timescale.adapter —— 生产级 TimescaleDB(PostgreSQL + timescaledb 扩展),
+ *    由环境变量 DAQ_TSDB_URL(postgres://…)启用;自动建表 + create_hypertable。
+ *  - sqlite.adapter   —— 开发仿真:同一契约落在本地 SQLite(WAL),结构对齐
+ *    时序语义(ts_ms 主键、按段聚合)。缺省后端,保证 mock 环境全链路可跑。
+ */
+
+export interface DaqSampleRow {
+  nodeId: string
+  /** epoch 毫秒(内部统一时间轴) */
+  tsMs: number
+  value: number
+  state: string
+  /** 产线批次打标(活动 LineRun 窗口内的样本逐条携带;null = 线体空闲段) */
+  lineId?: string | null
+  productId?: string | null
+  recipeId?: string | null
+  runId?: string | null
+}
+
+export interface DaqQueryOpts {
+  fromMs?: number
+  toMs?: number
+  /** 降采样桶宽(ms);给出则返回桶聚合(avg/min/max/cnt) */
+  bucketMs?: number
+  /** 原始点上限(降采样模式下为桶数上限) */
+  limit?: number
+}
+
+/** 原始点(raw)或桶聚合(bucket)两种形态 */
+export interface TsdbPoint {
+  at: number
+  value?: number
+  avg?: number
+  min?: number
+  max?: number
+  cnt?: number
+  state?: string
+}
+
+/** 跨通道打标查询(产线数据隔离:产品/配方/批次/通道/时间/桶) */
+export interface TsdbTagQuery {
+  lineId?: string
+  productId?: string
+  recipeId?: string
+  runId?: string
+  /** 限定通道(缺省全部) */
+  nodeIds?: string[]
+  fromMs?: number
+  toMs?: number
+  bucketMs?: number
+  limit?: number
+}
+
+export interface TsdbPort {
+  /** 后端标识(sqlite-emulated | timescale)——REST meta 直报前端 */
+  readonly backend: string
+  init(): Promise<void>
+  writeSamples(rows: DaqSampleRow[]): Promise<void>
+  query(nodeId: string, opts: DaqQueryOpts): Promise<TsdbPoint[]>
+  /** 按产线打标跨通道查询(产品/配方隔离) */
+  queryTagged(q: TsdbTagQuery): Promise<Map<string, TsdbPoint[]>>
+  /** 各节点最近一个样本(列表页值列兜底) */
+  latest(): Promise<Map<string, DaqSampleRow>>
+  /** 释放底层连接池/句柄(rebuild 换池时由工厂调用;可选) */
+  close?(): Promise<void> | void
+}

package/server/services/workshop/db/agent.repo.ts

@@ -0,0 +1,105 @@
+/**
+ * Agent 仓储:agents 表 CRUD(全局 Agent 元数据定义,无 channel 绑定)。
+ * Channel 成员关系见 channel-agent.repo.ts。
+ * 工厂接收 DatabaseSync(依赖注入),不持有任何单例。
+ * 可见性(v10):private 仅属主可见;public 全员可读可用;owner NULL = 内置(恒 public,不可变更)。
+ */
+import { randomUUID } from 'node:crypto'
+import type { DatabaseSync } from 'node:sqlite'
+import type { AgentRow } from './database'
+
+const COLS = 'id, name, harness, config_json AS configJson, enabled, visibility, owner_user_id AS ownerUserId, created_at AS createdAt, updated_at AS updatedAt'
+
+export interface AgentCreateInput {
+  name: string
+  harness: string
+  config?: Record<string, unknown>
+  /** 可见性(缺省 private) */
+  visibility?: string
+  /** 归属用户(null = 内置公共) */
+  ownerUserId?: string | null
+}
+
+export interface AgentPatch {
+  name?: string
+  harness?: string
+  config?: Record<string, unknown>
+  enabled?: number
+  visibility?: string
+}
+
+export type AgentRepo = ReturnType<typeof createAgentRepo>
+
+export function createAgentRepo(db: DatabaseSync) {
+  const insert = db.prepare(
+    `INSERT INTO agents (id, name, harness, config_json, enabled, visibility, owner_user_id, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+  )
+  const selectAll = db.prepare(`SELECT ${COLS} FROM agents ORDER BY createdAt ASC`)
+  const selectByOwner = db.prepare(`SELECT ${COLS} FROM agents WHERE owner_user_id = ? OR owner_user_id IS NULL ORDER BY createdAt ASC`)
+  const selectVisible = db.prepare(`SELECT ${COLS} FROM agents WHERE owner_user_id = ? OR visibility = 'public' ORDER BY createdAt ASC`)
+  const selectById = db.prepare(`SELECT ${COLS} FROM agents WHERE id = ?`)
+  const updateStmt = db.prepare(
+    `UPDATE agents SET name = ?, harness = ?, config_json = ?, enabled = ?, visibility = ?, updated_at = ? WHERE id = ?`,
+  )
+  const removeStmt = db.prepare(`DELETE FROM agents WHERE id = ?`)
+
+  return {
+    /** 创建 agent 定义(config 缺省 {};visibility 缺省 private) */
+    create(input: AgentCreateInput): AgentRow {
+      const now = new Date().toISOString()
+      const row: AgentRow = {
+        id: randomUUID(),
+        name: input.name,
+        harness: input.harness,
+        configJson: JSON.stringify(input.config ?? {}),
+        enabled: 1,
+        visibility: input.visibility ?? 'private',
+        ownerUserId: input.ownerUserId ?? null,
+        createdAt: now,
+        updatedAt: now,
+      }
+      insert.run(row.id, row.name, row.harness, row.configJson, row.enabled, row.visibility, row.ownerUserId, row.createdAt, row.updatedAt)
+      return row
+    },
+
+    list(): AgentRow[] {
+      return selectAll.all() as unknown as AgentRow[]
+    },
+
+    /** 按 owner 过滤(含 NULL 内置公共行) */
+    listForOwner(ownerUserId: string): AgentRow[] {
+      return selectByOwner.all(ownerUserId) as unknown as AgentRow[]
+    },
+
+    /** 用户可见集:本人(任意可见性)+ 全部 public(含内置) */
+    listVisible(userId: string): AgentRow[] {
+      return selectVisible.all(userId) as unknown as AgentRow[]
+    },
+
+    findById(id: string): AgentRow | undefined {
+      return selectById.get(id) as unknown as AgentRow | undefined
+    },
+
+    /** 局部更新;config 提供时重新序列化;未命中返回 undefined */
+    update(id: string, patch: AgentPatch): AgentRow | undefined {
+      const current = selectById.get(id) as unknown as AgentRow | undefined
+      if (!current) return undefined
+      const next: AgentRow = {
+        ...current,
+        name: patch.name ?? current.name,
+        harness: patch.harness ?? current.harness,
+        configJson: patch.config !== undefined ? JSON.stringify(patch.config) : current.configJson,
+        enabled: patch.enabled ?? current.enabled,
+        visibility: patch.visibility ?? current.visibility,
+        updatedAt: new Date().toISOString(),
+      }
+      updateStmt.run(next.name, next.harness, next.configJson, next.enabled, next.visibility, next.updatedAt, id)
+      return next
+    },
+
+    remove(id: string): void {
+      removeStmt.run(id)
+    },
+  }
+}

package/server/services/workshop/db/channel-agent.repo.ts

@@ -0,0 +1,119 @@
+/**
+ * ChannelAgent 仓储:channel_agents 表(Channel 中的 Agent 实例)。
+ * 每次把 Agent 模板放入 channel 都创建一个全新实例:独立身份 id + 复制自模板的
+ * name/harness/config + 独立 role + token。
+ * 工厂接收 DatabaseSync(依赖注入),不持有任何单例。
+ */
+import { randomUUID } from 'node:crypto'
+import type { DatabaseSync } from 'node:sqlite'
+import type { ChannelAgentRow } from './database'
+
+export interface ChannelAgentCreateInput {
+  channelId: string
+  templateId: string | null
+  name: string
+  harness: string
+  config?: Record<string, unknown>
+  role: 'lead' | 'worker'
+  token?: string
+}
+
+export interface ChannelAgentPatch {
+  name?: string
+  harness?: string
+  config?: Record<string, unknown>
+  role?: 'lead' | 'worker'
+  enabled?: number
+}
+
+export type ChannelAgentRepo = ReturnType<typeof createChannelAgentRepo>
+
+const COLS
+  = 'id, channel_id AS channelId, template_id AS templateId, name, harness, config_json AS configJson, role, token, enabled, created_at AS createdAt, updated_at AS updatedAt'
+
+export function createChannelAgentRepo(db: DatabaseSync) {
+  const insert = db.prepare(
+    `INSERT INTO channel_agents (id, channel_id, template_id, name, harness, config_json, role, token, enabled, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+  )
+  const selectByChannel = db.prepare(`SELECT ${COLS} FROM channel_agents WHERE channel_id = ? ORDER BY created_at ASC`)
+  const selectById = db.prepare(`SELECT ${COLS} FROM channel_agents WHERE id = ?`)
+  const selectByChannelAgent = db.prepare(`SELECT ${COLS} FROM channel_agents WHERE channel_id = ? AND id = ?`)
+  const selectByToken = db.prepare(`SELECT ${COLS} FROM channel_agents WHERE token = ?`)
+  const selectByTemplate = db.prepare(`SELECT ${COLS} FROM channel_agents WHERE template_id = ? ORDER BY created_at ASC`)
+  const updateStmt = db.prepare(
+    `UPDATE channel_agents SET name = ?, harness = ?, config_json = ?, role = ?, enabled = ?, updated_at = ? WHERE id = ?`,
+  )
+  const removeStmt = db.prepare(`DELETE FROM channel_agents WHERE channel_id = ? AND id = ?`)
+
+  return {
+    /** 创建实例(独立身份 id;token 缺省自动生成 UUIDv4) */
+    create(input: ChannelAgentCreateInput): ChannelAgentRow {
+      const now = new Date().toISOString()
+      const row: ChannelAgentRow = {
+        id: randomUUID(),
+        channelId: input.channelId,
+        templateId: input.templateId,
+        name: input.name,
+        harness: input.harness,
+        configJson: JSON.stringify(input.config ?? {}),
+        role: input.role,
+        token: input.token ?? randomUUID(),
+        enabled: 1,
+        createdAt: now,
+        updatedAt: now,
+      }
+      insert.run(
+        row.id, row.channelId, row.templateId, row.name, row.harness, row.configJson, row.role, row.token, row.enabled, row.createdAt, row.updatedAt,
+      )
+      return row
+    },
+
+    /** channel 内全部实例 */
+    listByChannel(channelId: string): ChannelAgentRow[] {
+      return selectByChannel.all(channelId) as unknown as ChannelAgentRow[]
+    },
+
+    /** 按实例 id 查找 */
+    findById(id: string): ChannelAgentRow | undefined {
+      return selectById.get(id) as unknown as ChannelAgentRow | undefined
+    },
+
+    /** channel 内的某个实例 */
+    findByChannelAgent(channelId: string, id: string): ChannelAgentRow | undefined {
+      return selectByChannelAgent.get(channelId, id) as unknown as ChannelAgentRow | undefined
+    },
+
+    /** 实例级 token → 实例(MCP/REST caller 解析) */
+    findByToken(token: string): ChannelAgentRow | undefined {
+      return selectByToken.get(token) as unknown as ChannelAgentRow | undefined
+    },
+
+    /** 某模板克隆出的全部实例(跨 channel) */
+    listByTemplate(templateId: string): ChannelAgentRow[] {
+      return selectByTemplate.all(templateId) as unknown as ChannelAgentRow[]
+    },
+
+    /** 局部更新;config 提供时重新序列化;未命中返回 undefined */
+    update(id: string, patch: ChannelAgentPatch): ChannelAgentRow | undefined {
+      const current = selectById.get(id) as unknown as ChannelAgentRow | undefined
+      if (!current) return undefined
+      const next: ChannelAgentRow = {
+        ...current,
+        name: patch.name ?? current.name,
+        harness: patch.harness ?? current.harness,
+        configJson: patch.config !== undefined ? JSON.stringify(patch.config) : current.configJson,
+        role: patch.role ?? current.role,
+        enabled: patch.enabled ?? current.enabled,
+        updatedAt: new Date().toISOString(),
+      }
+      updateStmt.run(next.name, next.harness, next.configJson, next.role, next.enabled, next.updatedAt, id)
+      return next
+    },
+
+    /** 移除实例(仅删实例,不删模板) */
+    remove(channelId: string, id: string): void {
+      removeStmt.run(channelId, id)
+    },
+  }
+}

package/server/services/workshop/db/channel-event.repo.ts

@@ -0,0 +1,154 @@
+/**
+ * ChannelEvent 仓储:AEP 事件持久化(channel_events)。
+ * hub publish 同步写入(server 驱动);时间线/lane 历史经 REST 拉取渲染,与 client 无关。
+ *
+ * 过滤查询(EventQueryOpts):lane 按需加载按 agent 维度拉取(避免单 agent 的
+ * 高频流式帧淹没全局 200 帧窗口);excludeTypes 剔除过程帧(agent.delta 的
+ * 打字机增量在历史回放里由落定 agent.message 携带全文,无需逐帧重放)。
+ */
+import type { DatabaseSync, SQLInputValue } from 'node:sqlite'
+import type { ChannelEventRow } from './database'
+
+export interface StoredAepEvent {
+  seq: number
+  type: string
+  at: string
+  agentId: string | null
+  taskId: string | null
+  payload: unknown
+}
+
+/** 历史查询过滤(lane 按需加载 / 历史窗口提质) */
+export interface EventQueryOpts {
+  /** 仅该 agent 的事件(a2a.message 归发送方,与 WS 信封 agentId 同口径) */
+  agentId?: string
+  /** 排除的事件类型(如 ['agent.delta']) */
+  excludeTypes?: readonly string[]
+}
+
+export type ChannelEventRepo = ReturnType<typeof createChannelEventRepo>
+
+const COLS = `id, channel_id AS channelId, seq, type, at, agent_id AS agentId, task_id AS taskId, payload_json AS payloadJson`
+
+export function createChannelEventRepo(db: DatabaseSync) {
+  const insertStmt = db.prepare(
+    `INSERT OR IGNORE INTO channel_events (channel_id, seq, type, at, agent_id, task_id, payload_json)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`,
+  )
+  /** 动态条件语句缓存(opts 变体有限,按 SQL 文本缓存命中稳定) */
+  const stmtCache = new Map<string, ReturnType<DatabaseSync['prepare']>>()
+
+  /** WHERE 追加过滤(agentId / excludeTypes),返回 [sql片段, 绑定参数] */
+  const filterClause = (opts?: EventQueryOpts): [string, SQLInputValue[]] => {
+    let sql = ''
+    const params: SQLInputValue[] = []
+    if (opts?.agentId !== undefined) {
+      sql += ' AND agent_id = ?'
+      params.push(opts.agentId)
+    }
+    if (opts?.excludeTypes && opts.excludeTypes.length > 0) {
+      sql += ` AND type NOT IN (${opts.excludeTypes.map(() => '?').join(', ')})`
+      params.push(...opts.excludeTypes)
+    }
+    return [sql, params]
+  }
+
+  const select = (baseWhere: string, tail: string, baseParams: SQLInputValue[], tailParams: SQLInputValue[], opts?: EventQueryOpts) => {
+    const [filterSql, filterParams] = filterClause(opts)
+    const sql = `SELECT ${COLS} FROM channel_events WHERE ${baseWhere}${filterSql} ${tail}`
+    let stmt = stmtCache.get(sql)
+    if (!stmt) {
+      stmt = db.prepare(sql)
+      stmtCache.set(sql, stmt)
+    }
+    // 绑定顺序与 SQL 文本一致:WHERE 基础参数 → 过滤参数 → 排序/分页参数
+    return stmt.all(...baseParams, ...filterParams, ...tailParams) as unknown as ChannelEventRow[]
+  }
+
+  /** hub publish 同步写库(INSERT OR IGNORE:hub 内存 seq 与库重放幂等) */
+  function insert(channelId: string, e: StoredAepEvent): void {
+    insertStmt.run(channelId, e.seq, e.type, e.at, e.agentId, e.taskId, JSON.stringify(e.payload))
+  }
+
+  /** 批量写(单事务一次 fsync;hub 400ms 聚合缓冲的刷盘出口) */
+  function insertMany(channelId: string, events: StoredAepEvent[]): void {
+    if (events.length === 0) return
+    db.exec('BEGIN')
+    try {
+      for (const e of events) {
+        insertStmt.run(channelId, e.seq, e.type, e.at, e.agentId, e.taskId, JSON.stringify(e.payload))
+      }
+      db.exec('COMMIT')
+    }
+    catch (err) {
+      try {
+        db.exec('ROLLBACK')
+      }
+      catch { /* 事务已终结 */ }
+      throw err
+    }
+  }
+
+  /** 保留期清理:分批 DELETE(单批 5000 行,防长事务锁库);返回清理行数 */
+  function sweepRetention(retentionDays = 7): number {
+    const cutoff = new Date(Date.now() - retentionDays * 86_400_000).toISOString()
+    let removed = 0
+    for (;;) {
+      const r = db.prepare(
+        'DELETE FROM channel_events WHERE rowid IN (SELECT rowid FROM channel_events WHERE at < ? LIMIT 5000)',
+      ).run(cutoff) as { changes: number | bigint }
+      const n = Number(r.changes)
+      removed += n
+      if (n < 5000) break
+    }
+    return removed
+  }
+
+  /** 最近 N 条(倒序取→正序返回,时间线顺序) */
+  function listRecent(channelId: string, limit: number, opts?: EventQueryOpts): StoredAepEvent[] {
+    return select('channel_id = ?', 'ORDER BY seq DESC LIMIT ?', [channelId], [limit], opts)
+      .map(rowToEvent)
+      .reverse()
+  }
+
+  /** 翻页:seq < beforeSeq 的最近 N 条(正序返回) */
+  function listBefore(channelId: string, beforeSeq: number, limit: number, opts?: EventQueryOpts): StoredAepEvent[] {
+    return select('channel_id = ? AND seq < ?', 'ORDER BY seq DESC LIMIT ?', [channelId, beforeSeq], [limit], opts)
+      .map(rowToEvent)
+      .reverse()
+  }
+
+  function maxSeq(channelId: string): number {
+    return ((db.prepare('SELECT MAX(seq) AS maxSeq FROM channel_events WHERE channel_id = ?')
+      .get(channelId) as { maxSeq: number | null } | undefined)?.maxSeq) ?? 0
+  }
+
+  function count(channelId: string, opts?: EventQueryOpts): number {
+    const [filterSql, filterParams] = filterClause(opts)
+    const sql = `SELECT COUNT(*) AS n FROM channel_events WHERE channel_id = ?${filterSql}`
+    let stmt = stmtCache.get(sql)
+    if (!stmt) {
+      stmt = db.prepare(sql)
+      stmtCache.set(sql, stmt)
+    }
+    return ((stmt.get(channelId, ...filterParams) as { n: number } | undefined)?.n) ?? 0
+  }
+
+  return { insert, insertMany, sweepRetention, listRecent, listBefore, maxSeq, count }
+}
+
+function rowToEvent(row: ChannelEventRow): StoredAepEvent {
+  let payload: unknown = null
+  try {
+    payload = JSON.parse(row.payloadJson)
+  }
+  catch { /* 损坏 payload 容错为 null */ }
+  return {
+    seq: row.seq,
+    type: row.type,
+    at: row.at,
+    agentId: row.agentId,
+    taskId: row.taskId,
+    payload,
+  }
+}