agentworkshop 0.2.1

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

@@ -0,0 +1,249 @@
+/**
+ * Memory 仓储:agent_memories(持久记忆)+ FTS5 全文索引。
+ * upsert 经 (agent_id, dedup_key) 去重(AFTER UPDATE 触发器同步 FTS);
+ * search 的 bm25 检索恒含团队共享行(agent_id='__team__');list* 严格本人。
+ * 向量方法(vec*)在 P1 扩展;本文件保持纯 node:sqlite 同步。
+ */
+import { randomUUID } from 'node:crypto'
+import type { DatabaseSync, StatementSync } from 'node:sqlite'
+import type { MemoryRow } from './database'
+
+/** 团队共享记忆域 sentinel(单 channel 内全员可读) */
+export const TEAM_AGENT_ID = '__team__'
+
+export interface MemoryUpsertInput {
+  channelId: string
+  agentId: string
+  kind: 'episodic-task' | 'episodic-peer' | 'semantic'
+  title: string
+  /** title 的 CJK 切分副本(FTS 索引用;调用方经 AgentMemory.segmentCJK 处理,V8) */
+  titleFts: string
+  /** 已 CJK 单字切分的存储文本(AgentMemory.segmentCJK 处理) */
+  content: string
+  importance: number
+  taskId?: string | null
+  dedupKey: string
+}
+
+export type MemoryRepo = ReturnType<typeof createMemoryRepo>
+
+const COLS = `m.id, m.channel_id AS channelId, m.agent_id AS agentId, m.kind, m.title, m.content,
+  m.importance, m.task_id AS taskId, m.access_count AS accessCount,
+  m.last_accessed_at AS lastAccessedAt, m.created_at AS createdAt`
+
+export function createMemoryRepo(db: DatabaseSync) {
+  const upsertStmt = db.prepare(
+    `INSERT INTO agent_memories
+       (id, channel_id, agent_id, kind, title, title_fts, content, importance, task_id, dedup_key, access_count, last_accessed_at, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0, NULL, ?)
+    ON CONFLICT(agent_id, dedup_key, channel_id) DO UPDATE SET
+      channel_id = excluded.channel_id, kind = excluded.kind, title = excluded.title, title_fts = excluded.title_fts,
+      content = excluded.content, importance = excluded.importance, created_at = excluded.created_at`,
+  )
+  const searchStmt = db.prepare(
+    `SELECT ${COLS}, f.rank AS bm25
+     FROM agent_memories_fts f
+     JOIN agent_memories m ON m.rowid = f.memory_rowid
+     WHERE agent_memories_fts MATCH ? AND m.agent_id IN (?, ?)
+     ORDER BY f.rank LIMIT ?`,
+  )
+  const listRecentStmt = db.prepare(
+    `SELECT id, channel_id AS channelId, agent_id AS agentId, kind, title, content,
+            importance, task_id AS taskId, access_count AS accessCount,
+            last_accessed_at AS lastAccessedAt, created_at AS createdAt
+     FROM agent_memories WHERE agent_id = ? ORDER BY created_at DESC LIMIT ?`,
+  )
+  const findByDedupStmt = db.prepare(
+    `SELECT id, rowid FROM agent_memories WHERE channel_id = ? AND agent_id = ? AND dedup_key = ?`,
+  )
+  const listByAgentChannelStmt = db.prepare(
+    `SELECT id, channel_id AS channelId, agent_id AS agentId, kind, title, content,
+       importance, task_id AS taskId, access_count AS accessCount,
+       last_accessed_at AS lastAccessedAt, created_at AS createdAt
+     FROM agent_memories WHERE channel_id = ? AND agent_id = ? ORDER BY created_at DESC LIMIT ?`,
+  )
+  const listByAgentRowidStmt = db.prepare(
+    `SELECT rowid, id, channel_id AS channelId, agent_id AS agentId, kind, title, content,
+       importance, task_id AS taskId, access_count AS accessCount,
+       last_accessed_at AS lastAccessedAt, created_at AS createdAt
+     FROM agent_memories WHERE agent_id = ? ORDER BY created_at DESC LIMIT ?`,
+  )
+  const touchStmt = db.prepare(
+    `UPDATE agent_memories SET access_count = access_count + 1, last_accessed_at = ? WHERE id = ?`,
+  )
+  const deleteStmt = db.prepare(`DELETE FROM agent_memories WHERE id = ?`)
+  const agentIdsStmt = db.prepare(
+    `SELECT DISTINCT agent_id FROM agent_memories WHERE agent_id != ?`,
+  )
+  // ===== 向量方法(P1;vec0 分区表 + mem_rowid 辅助列映射)=====
+  // 已实测事实:
+  // - vec0 分区表不支持显式 rowid 插入 → 以 +mem_rowid 辅助列映射 agent_memories.rowid
+  // - node:sqlite 把 number 绑定为 REAL → 一切整数绑定(vec 辅助列/rowid/k)必须 BigInt(n),
+  //   否则 "Auxiliary column type mismatch"
+  // - 刷新语义 = SELECT rowid WHERE mem_rowid → DELETE → 重插(分区表 rowid 不可控)
+  // - 语句在建表成功后才 prepare(vec0 DDL 不进 SCHEMA_SQL:维度运行时才知)
+  let vecDims: number | null = null
+  let vecFindRowStmt: StatementSync | null = null
+  let vecDeleteRowStmt: StatementSync | null = null
+  let vecInsertStmt: StatementSync | null = null
+  let vecSearchStmt: StatementSync | null = null
+
+  function vecEnsureTable(dims: number): boolean {
+    try {
+      db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS agent_memories_vec USING vec0(
+        embedding float[${dims}], agent_id TEXT partition key, +mem_rowid INTEGER)`)
+      // 维度校验探针:已存表若维度不同,试插会炸 → 返回 false(不破坏已有数据)
+      // ('__probe__' 分区即刻删除,无害)
+      vecInsertStmt = db.prepare(`INSERT INTO agent_memories_vec(embedding, agent_id, mem_rowid) VALUES (?, ?, ?)`)
+      vecInsertStmt.run(new Float32Array(dims), '__probe__', BigInt(-1))
+      db.prepare(`DELETE FROM agent_memories_vec WHERE mem_rowid = ?`).run(BigInt(-1))
+      vecFindRowStmt = db.prepare(`SELECT rowid FROM agent_memories_vec WHERE mem_rowid = ?`)
+      vecDeleteRowStmt = db.prepare(`DELETE FROM agent_memories_vec WHERE rowid = ?`)
+      vecSearchStmt = db.prepare(
+        `SELECT mem_rowid, distance FROM agent_memories_vec WHERE agent_id = ? AND embedding MATCH ? AND k = ?`)
+      return true
+    }
+    catch {
+      vecFindRowStmt = vecDeleteRowStmt = vecInsertStmt = vecSearchStmt = null
+      return false
+    }
+  }
+
+  return {
+    upsert(input: MemoryUpsertInput): void {
+      upsertStmt.run(
+        randomUUID(), input.channelId, input.agentId, input.kind,
+        input.title, input.titleFts, input.content, input.importance,
+        input.taskId ?? null, input.dedupKey, new Date().toISOString(),
+      )
+    },
+
+    /** bm25 检索(恒含 team 共享行;matchQuery 为 OR 连接切分词) */
+    search(agentId: string, matchQuery: string, limit: number): Array<MemoryRow & { bm25: number }> {
+      return searchStmt.all(matchQuery, agentId, TEAM_AGENT_ID, limit) as unknown as Array<MemoryRow & { bm25: number }>
+    },
+
+    listRecent(agentId: string, limit: number): MemoryRow[] {
+      return listRecentStmt.all(agentId, limit) as unknown as MemoryRow[]
+    },
+
+    listByAgent(agentId: string, limit: number): MemoryRow[] {
+      return listRecentStmt.all(agentId, limit) as unknown as MemoryRow[]
+    },
+
+    /** 按 rowid 批量取主表行(向量 kNN 命中 → 主表;空数组返回 []) */
+    listByRowids(rowids: number[]): Array<MemoryRow & { rowid: number }> {
+      if (rowids.length === 0) return []
+      const placeholders = rowids.map(() => '?').join(', ')
+      return db.prepare(
+        `SELECT rowid, id, channel_id AS channelId, agent_id AS agentId, kind, title, content,
+           importance, task_id AS taskId, access_count AS accessCount,
+           last_accessed_at AS lastAccessedAt, created_at AS createdAt
+         FROM agent_memories WHERE rowid IN (${placeholders})`,
+      ).all(...rowids.map(BigInt)) as unknown as Array<MemoryRow & { rowid: number }>
+    },
+
+    /** upsert 后取定位置(供向量写回 rowid;按 channel 作用域——team 哨兵行跨 channel 各自独立) */
+    findByAgentDedup(channelId: string, agentId: string, dedupKey: string): { id: string, rowid: number } | null {
+      return (findByDedupStmt.get(channelId, agentId, dedupKey) as { id: string, rowid: number } | undefined) ?? null
+    },
+
+    /** channel × agent 双键列表(team 行按 channel 隔离的正确口径;listByAgent 为全局 agent 域) */
+    listByAgentChannel(channelId: string, agentId: string, limit: number): MemoryRow[] {
+      return listByAgentChannelStmt.all(channelId, agentId, limit) as unknown as MemoryRow[]
+    },
+
+    /** listByAgent + rowid(维护专用:过期/淘汰删除需联动 vec 行) */
+    listByAgentWithRowid(agentId: string, limit: number): Array<MemoryRow & { rowid: number }> {
+      return listByAgentRowidStmt.all(agentId, limit) as unknown as Array<MemoryRow & { rowid: number }>
+    },
+
+    touch(id: string): void {
+      touchStmt.run(new Date().toISOString(), id)
+    },
+
+    /** 删除(FTS 触发器自动清理;向量行由上层先 vecDelete);返回是否删除 */
+    delete(id: string): boolean {
+      return deleteStmt.run(id).changes > 0
+    },
+
+    /** 删除某 channel 全部记忆(channel 级联删除:成员私有行 + team 公共行;vec 残留由维护任务清理);返回删除数 */
+    deleteByChannel(channelId: string): number {
+      const rows = db.prepare(
+        `SELECT rowid FROM agent_memories WHERE channel_id = ?`,
+      ).all(channelId) as Array<{ rowid: number | bigint }>
+      for (const r of rows) {
+        try {
+          // 与 vecDelete 同语义:按 mem_rowid 反查 vec 行后删(分区表 rowid 不可控)
+          const old = vecFindRowStmt?.get(BigInt(r.rowid)) as { rowid: number | bigint } | undefined
+          if (old) vecDeleteRowStmt?.run(BigInt(old.rowid))
+        }
+        catch { /* vec 未启用 */ }
+      }
+      return Number(db.prepare(`DELETE FROM agent_memories WHERE channel_id = ?`).run(channelId).changes)
+    },
+
+    /** 有记忆的 agent 清单(维护任务迭代;排除 team) */
+    listMemoryAgentIds(): string[] {
+      return (agentIdsStmt.all(TEAM_AGENT_ID) as Array<{ agent_id: string }>).map(r => r.agent_id)
+    },
+
+    // ===== vec:延迟建表(vecInit)/ 刷新写入(vecSet)/ 删除(vecDelete)/ 分区 kNN(vecSearch)=====
+
+    /** 首次调用按 dims 建表;同 dims 幂等 true;不同 dims 拒绝 false(禁用向量,绝不重建) */
+    vecInit(dims: number): boolean {
+      if (vecDims === dims) return true
+      if (vecDims !== null) return false
+      if (!vecEnsureTable(dims)) return false
+      vecDims = dims
+      return true
+    },
+
+    /** 向量层是否可用(建表成功即 true) */
+    get vecReady(): boolean {
+      return vecDims !== null
+    },
+
+    /** 写/覆盖某记忆行的向量(按 mem_rowid 刷新:删旧插新;失败静默不阻塞主流程) */
+    vecSet(memRowid: number, agentId: string, vec: Float32Array): void {
+      if (vecFindRowStmt === null || vecDeleteRowStmt === null || vecInsertStmt === null) return
+      try {
+        const old = vecFindRowStmt.get(BigInt(memRowid)) as { rowid: number | bigint } | undefined
+        if (old) vecDeleteRowStmt.run(BigInt(old.rowid))
+        vecInsertStmt.run(vec, agentId, BigInt(memRowid))
+      }
+      catch { /* 向量写失败不阻塞主流程 */ }
+    },
+
+    /** 删除某记忆行的向量(删除记忆联动;不存在/失败均静默) */
+    vecDelete(memRowid: number): void {
+      if (vecFindRowStmt === null || vecDeleteRowStmt === null) return
+      try {
+        const old = vecFindRowStmt.get(BigInt(memRowid)) as { rowid: number | bigint } | undefined
+        if (old) vecDeleteRowStmt.run(BigInt(old.rowid))
+      }
+      catch { /* 同上 */ }
+    },
+
+    /** agent 域内 kNN(分区键隔离;禁用时返回空) */
+    vecSearch(agentId: string, vec: Float32Array, k: number): Array<{ memRowid: number, distance: number }> {
+      if (vecSearchStmt === null) return []
+      try {
+        const rows = vecSearchStmt.all(agentId, vec, BigInt(k)) as Array<{ mem_rowid: number | bigint, distance: number }>
+        return rows.map(r => ({ memRowid: Number(r.mem_rowid), distance: r.distance }))
+      }
+      catch { return [] }
+    },
+
+    /** 清孤儿 vec 行(mem_rowid 已不在主表;维护任务统一收口;vec 未启用/失败 → 0) */
+    vecCleanOrphans(): number {
+      if (vecDims === null) return 0
+      try {
+        return Number(db.prepare(
+          `DELETE FROM agent_memories_vec WHERE mem_rowid NOT IN (SELECT rowid FROM agent_memories)`,
+        ).run().changes)
+      }
+      catch { return 0 }
+    },
+  }
+}

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

@@ -0,0 +1,149 @@
+/**
+ * Message 仓储:messages 表(mailbox 持久化队列)。
+ * 工厂接收 DatabaseSync(依赖注入),不持有任何单例。
+ */
+import { randomUUID } from 'node:crypto'
+import type { DatabaseSync } from 'node:sqlite'
+import type { MessageRow } from './database'
+
+const COLS
+  = 'id, channel_id AS channelId, task_id AS taskId, from_agent_id AS fromAgentId, to_agent_id AS toAgentId, role, parts_json AS partsJson, metadata_json AS metadataJson, state, created_at AS createdAt, consumed_at AS consumedAt'
+
+export interface MessageCreateInput {
+  /** 落库 id;缺省生成。A2A 入队时传发送方 messageId,保证 API 返回 id 与历史 id 一致 */
+  id?: string
+  channelId: string
+  taskId?: string | null
+  fromAgentId?: string | null
+  toAgentId?: string | null
+  role: string
+  parts: unknown[]
+  metadata?: Record<string, unknown>
+}
+
+export type MessageRepo = ReturnType<typeof createMessageRepo>
+
+export function createMessageRepo(db: DatabaseSync) {
+  const insert = db.prepare(
+    `INSERT INTO messages (id, channel_id, task_id, from_agent_id, to_agent_id, role, parts_json, metadata_json, state, created_at, consumed_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+  )
+  const selectPending = db.prepare(
+    // rowid 决胜:同一毫秒内批量入队(连发任务/调度批量派发)也保持严格入队顺序(FIFO)
+    `SELECT ${COLS} FROM messages WHERE channel_id = ? AND to_agent_id = ? AND state = 'pending' ORDER BY createdAt ASC, rowid ASC`,
+  )
+  /** 队头单条(dequeue 热路径;idx_messages_queue 覆盖,LIMIT 1 免全量拉取) */
+  const firstPending = db.prepare(
+    `SELECT ${COLS} FROM messages WHERE channel_id = ? AND to_agent_id = ? AND state = 'pending' ORDER BY createdAt ASC, rowid ASC LIMIT 1`,
+  )
+  const markConsumingStmt = db.prepare(
+    `UPDATE messages SET state = 'consuming' WHERE id = ? AND state = 'pending'`,
+  )
+  const markConsumedStmt = db.prepare(
+    `UPDATE messages SET state = 'consumed', consumed_at = ? WHERE id = ?`,
+  )
+  const resetConsumingStmt = db.prepare(
+    `UPDATE messages SET state = 'pending' WHERE state = 'consuming'`,
+  )
+  const requeueStmt = db.prepare(
+    `UPDATE messages SET state = 'pending' WHERE id = ? AND state = 'consuming'`,
+  )
+  const consumePendingByTaskStmt = db.prepare(
+    `UPDATE messages SET state = 'consumed', consumed_at = ? WHERE task_id = ? AND state = 'pending'`,
+  )
+  const selectRecent = db.prepare(
+    `SELECT ${COLS} FROM messages WHERE channel_id = ? ORDER BY createdAt DESC LIMIT ?`,
+  )
+  const selectPendingTargets = db.prepare(
+    `SELECT DISTINCT channel_id AS channelId, to_agent_id AS toAgentId
+     FROM messages WHERE to_agent_id IS NOT NULL AND state = 'pending'`,
+  )
+  const existsPendingAssignStmt = db.prepare(
+    `SELECT 1 AS hit FROM messages
+     WHERE task_id = ? AND state = 'pending' AND metadata_json LIKE '%"x-aw-task-kind":"assign"%'
+     LIMIT 1`,
+  )
+
+  return {
+    /** 创建消息(state=pending,parts/metadata 序列化存储) */
+    create(input: MessageCreateInput): MessageRow {
+      const now = new Date().toISOString()
+      const row: MessageRow = {
+        id: input.id ?? randomUUID(),
+        channelId: input.channelId,
+        taskId: input.taskId ?? null,
+        fromAgentId: input.fromAgentId ?? null,
+        toAgentId: input.toAgentId ?? null,
+        role: input.role,
+        partsJson: JSON.stringify(input.parts),
+        metadataJson: JSON.stringify(input.metadata ?? {}),
+        state: 'pending',
+        createdAt: now,
+        consumedAt: null,
+      }
+      insert.run(
+        row.id, row.channelId, row.taskId, row.fromAgentId, row.toAgentId, row.role, row.partsJson, row.metadataJson, row.state, row.createdAt, row.consumedAt,
+      )
+      return row
+    },
+
+    /** 拉取某 channel 内某 Agent 的未消费消息(FIFO;limit 给出则只取前 N 条) */
+    listPendingByChannelAgent(channelId: string, toAgentId: string, limit?: number): MessageRow[] {
+      if (limit != null) {
+        return db.prepare(
+          `SELECT ${COLS} FROM messages WHERE channel_id = ? AND to_agent_id = ? AND state = 'pending' ORDER BY createdAt ASC, rowid ASC LIMIT ?`,
+        ).all(channelId, toAgentId, limit) as unknown as MessageRow[]
+      }
+      return selectPending.all(channelId, toAgentId) as unknown as MessageRow[]
+    },
+
+    /** 队头单条(dequeue 热路径:WHERE+ORDER 走 idx_messages_queue,LIMIT 1 免全量) */
+    firstPendingByChannelAgent(channelId: string, toAgentId: string): MessageRow | undefined {
+      return (firstPending.get(channelId, toAgentId) as MessageRow | undefined) ?? undefined
+    },
+
+    /**
+     * 原子认领:pending → consuming(WHERE state='pending' 守卫)。
+     * 返回是否认领成功——多方竞争(steer 注入 / poll_messages 读即取 / 消费循环
+     * dequeue)下只有第一个认领者获得消息所有权,保证恰好一次投递。
+     */
+    claim(id: string): boolean {
+      return markConsumingStmt.run(id).changes > 0
+    },
+
+    /** consuming → consumed(记录消费时间) */
+    markConsumed(id: string): void {
+      markConsumedStmt.run(new Date().toISOString(), id)
+    },
+
+    /** 启动恢复:所有 consuming 重置回 pending(重新投递) */
+    resetConsuming(): void {
+      resetConsumingStmt.run()
+    },
+
+    /** 单条重投:consuming → pending(回合失败重试);返回是否实际重投 */
+    requeue(id: string): boolean {
+      return requeueStmt.run(id).changes > 0
+    },
+
+    /** 按 channel 倒序列出最近消息 */
+    listRecentByChannel(channelId: string, limit: number): MessageRow[] {
+      return selectRecent.all(channelId, limit) as unknown as MessageRow[]
+    },
+
+    /** 启动恢复:全部未消费消息的目标 agent(供 restore 唤醒,重投的 assign 才能被消费) */
+    listPendingTargets(): Array<{ channelId: string, toAgentId: string }> {
+      return selectPendingTargets.all() as unknown as Array<{ channelId: string, toAgentId: string }>
+    },
+
+    /** 作废某任务的全部 pending 消息(cancel/reassign/update 后清理旧 assignee 队列中的过期投递) */
+    consumePendingByTask(taskId: string): void {
+      consumePendingByTaskStmt.run(new Date().toISOString(), taskId)
+    },
+
+    /** 某任务是否存在未消费的 assign 投递(restore 断线重连判定:无则需重投) */
+    hasPendingAssign(taskId: string): boolean {
+      return existsPendingAssignStmt.get(taskId) !== undefined
+    },
+  }
+}