@xiaobuyu/nodesign 0.0.1

package/server/engine/runs/live-turn.js

@@ -0,0 +1,252 @@
+/**
+ * server/engine/runs/live-turn.js — 进行中 turn 的物化快照（内存态）
+ *
+ * 解决的问题：EventBus 是 fire-and-forget + ring buffer（2000 条），token 级
+ * streaming 一个 turn 就上万条事件 —— 刷新 / 断线重连后"进行中的 turn"在任何
+ * 可恢复的地方都不存在（jsonl 只在 turn 边界 flush）。老架构靠 ?since= 游标 +
+ * ring 回放，重连几秒就 gap，gap 补 hydrate 又把已渲染内容反向覆盖。
+ *
+ * 新范式（快照 + 尾随，2026-07-27 重构）：
+ *   - 本模块订阅每个 project bus，把进行中 turn 的事件**同步折叠**成前端
+ *     display-message 形态的物化状态（跟 ProjectWorkspace handleEvent 的累加
+ *     逻辑同构）
+ *   - WS 连接时：jsonl hydrate（已完成 turn）→ ws.live_turn 快照（进行中 turn）
+ *     → 从快照 seq 起订阅实时流。ring buffer 大小从此只影响极小的同步窗口，
+ *     不再影响正确性
+ *   - turn 结束（done / error / cancelled）或 session 结束即清，内存占用 =
+ *     活跃 turn 数 × 单 turn 消息体量（tool output 截断到 16k）
+ *
+ * 折叠规则跟前端 handleEvent 对齐（改前端渲染逻辑时两边同步改）：
+ *   run.delta.text / thinking       → 同 role 连续累加一条消息
+ *   run.tool_use.started            → push tool 消息 status='running'
+ *   run.delta.tool_use              → 补 toolInput
+ *   run.delta.tool_result           → 补 status / output / error（images 不进快照，太大）
+ *   run.todo.updated                → todos 覆盖
+ *   run.context_usage               → contextUsage 覆盖
+ *   run.done / error / cancelled    → 标记 ended（保留 GRACE 毫秒，见下），不再折叠
+ *   run.query.end                   → 清
+ *
+ * turn 结束后为什么还留一小会（2026-07-28）：jsonl 是 SDK 子进程按 block 逐条写的，
+ * 我们读 jsonl 与 turn 收尾之间有几百毫秒的错位窗口。这段时间内重连，若快照已经
+ * 没了，尾随订阅会把已经落进 jsonl 的那几条 delta 再放一遍 → 正文重复。留 GRACE
+ * 毫秒让"本轮由快照权威、hydrate 裁掉本轮"这条规则在收尾瞬间同样成立。
+ */
+
+const MAX_TOOL_TEXT = 16_000;
+// 3s：够盖住"读 jsonl 的几百毫秒"这个错位窗口，又短到收尾后的重连基本不会
+// 落在里面（快照不带 tool_result 的图片，长时间用快照顶替 hydrate 会丢缩略图）。
+const ENDED_GRACE_MS = 3_000;
+
+/** @type {Map<string, object>} sessionId → live turn state */
+const liveTurns = new Map();
+
+/**
+ * sessionId → 最近一次 run.context_usage 事件（2026-07-30）
+ *
+ * 跟 liveTurns 分开活着：turn 一结束 liveTurns 就清，但"这个会话现在装了多少上下文"
+ * 在两轮之间照样成立 —— 而那恰恰是用户最想看它的时刻（要不要先压缩再开新活）。
+ *
+ * query 结束也**不清**：关掉标签页就会触发 grace 超时关 session，而下次打开这个会话
+ * 时 SDK 从同一份 jsonl resume，上下文体量基本还是那么大。这时给个带"当前没有活跃
+ * 会话"标注的旧数字（live:false），比一句"还没开始对话"有用得多。只有 query 活着时才向 SDK 现问
+ * （见 GET /sessions/:sid/context-usage），所以准确的那条路一直优先。
+ *
+ * 只活在内存里：进程重启就没了，下一轮 turn 自然补上。
+ */
+const lastUsage = new Map();
+const LAST_USAGE_CAP = 200;
+
+export function getLastContextUsage(sessionId) {
+  return lastUsage.get(sessionId) || null;
+}
+
+/**
+ * 不变量守卫：只记 Events.contextUsage 构造出来的那种形状。
+ *
+ * `run.context_usage` 曾经有两个生产者，字段名对不上：session-loop 每条 assistant
+ * message 后发 { totalTokens, maxTokens, percentage }（前端读这套），hooks.js 的 Stop
+ * handler 每轮收尾发 { used, max, percent, categories }。前端靠 store 的"不覆盖已有值"
+ * 侥幸没显形，但每轮的**最后**一条恰好总是后者，凡是"取最新一条"的下游拿到的都是
+ * 一片 undefined —— 这个记忆层就是这么栽的。两个生产者已经合并成一个构造函数
+ * （2026-07-30），这里留一道守卫：以后再冒出第三种形状，是它被丢掉，不是这里出错数。
+ */
+function rememberUsage(sid, evt) {
+  if (typeof evt.totalTokens !== 'number') return;
+  if (lastUsage.size >= LAST_USAGE_CAP && !lastUsage.has(sid)) {
+    // 先进先出丢一条：进程活得久了不至于攒着所有历史 session
+    const oldest = lastUsage.keys().next().value;
+    if (oldest) lastUsage.delete(oldest);
+  }
+  lastUsage.set(sid, evt);
+}
+
+function truncate(s) {
+  if (typeof s !== 'string') return s;
+  if (s.length <= MAX_TOOL_TEXT) return s;
+  return s.slice(0, MAX_TOOL_TEXT) + `\n…[截断，共 ${s.length} 字符]`;
+}
+
+/**
+ * 给 project bus 挂折叠订阅（幂等 —— broker.getProjectBus 每次创建 bus 时调）。
+ */
+export function attachLiveTurnTracker(bus) {
+  if (bus.__liveTurnTracked) return;
+  bus.__liveTurnTracked = true;
+  bus.subscribe('*', fold);
+}
+
+/**
+ * 取 session 当前 turn 的快照；没有在跑、且上一轮已过 grace 期 → null。
+ * 返回值直接可作 ws.live_turn 帧 payload（messages 是前端 display 形态）。
+ *
+ * running=false 表示这是刚结束那一轮的尾巴（grace 期内），前端据此**只合并消息、
+ * 不把自己切回 streaming 态**。
+ */
+export function getLiveTurnSnapshot(sessionId) {
+  const st = liveTurns.get(sessionId);
+  if (!st) return null;
+  if (st.endedAt && Date.now() - st.endedAt > ENDED_GRACE_MS) {
+    liveTurns.delete(sessionId);
+    return null;
+  }
+  return {
+    runId: st.runId,
+    seq: st.seq,
+    startedAt: st.startedAt,
+    running: !st.endedAt,
+    messages: st.messages,
+    todos: st.todos,
+    contextUsage: st.contextUsage,
+  };
+}
+
+function fold(evt) {
+  const sid = evt.sessionId;
+  if (!sid) return;
+
+  // 记在 liveTurns 之外：turn 结束、快照删掉之后，这个数字还要继续给 composer
+  // 的 [+] 菜单用。放在 st 判空之前，快照已经清了也照记。
+  if (evt.type === 'run.context_usage') rememberUsage(sid, evt);
+
+  if (evt.type === 'run.start') {
+    liveTurns.set(sid, {
+      runId: evt.runId || null,
+      startedAt: evt.ts || new Date().toISOString(),
+      seq: evt.seq || 0,
+      messages: [],
+      todos: [],
+      contextUsage: null,
+      endedAt: null,
+      _msgCounter: 0,
+    });
+    return;
+  }
+
+  const st = liveTurns.get(sid);
+  if (!st) return;
+
+  // 已收尾的那一轮只留着给 grace 期内的重连当权威快照，不再吸新事件
+  // （新一轮由上面的 run.start 整块换掉）。seq 照常推进，免得尾随订阅从旧游标
+  // 起把这轮已经放过的事件再放一遍。
+  if (st.endedAt) {
+    if (evt.type === 'run.query.end' || Date.now() - st.endedAt > ENDED_GRACE_MS) {
+      liveTurns.delete(sid);
+      return;
+    }
+    if (typeof evt.seq === 'number' && evt.seq > st.seq) st.seq = evt.seq;
+    return;
+  }
+
+  // stale 事件（老 turn 的尾巴）不折叠也不清新 turn 的状态
+  const runMatches = !evt.runId || !st.runId || evt.runId === st.runId;
+
+  switch (evt.type) {
+    case 'run.delta.text':
+      if (runMatches) appendText(st, 'assistant', evt.text, evt.parentToolUseId);
+      break;
+    case 'run.delta.thinking':
+      if (runMatches) appendText(st, 'thinking', evt.text, evt.parentToolUseId);
+      break;
+    case 'run.tool_use.started':
+      if (runMatches && evt.blockId && !st.messages.some(m => m.id === evt.blockId)) {
+        st.messages.push({
+          id: evt.blockId, role: 'tool', toolName: evt.name,
+          toolInput: undefined, status: 'running', runId: st.runId,
+          ...(evt.parentToolUseId ? { parentToolUseId: evt.parentToolUseId } : {}),
+        });
+      }
+      break;
+    case 'run.delta.tool_use': {
+      if (!runMatches) break;
+      const existing = st.messages.find(m => m.role === 'tool' && m.id === evt.blockId);
+      if (existing) existing.toolInput = evt.input;
+      else if (evt.blockId) {
+        st.messages.push({
+          id: evt.blockId, role: 'tool', toolName: evt.name,
+          toolInput: evt.input, status: 'running', runId: st.runId,
+          ...(evt.parentToolUseId ? { parentToolUseId: evt.parentToolUseId } : {}),
+        });
+      }
+      break;
+    }
+    case 'run.delta.tool_result': {
+      if (!runMatches) break;
+      const tool = st.messages.find(m => m.role === 'tool' && m.id === evt.blockId);
+      if (tool) {
+        tool.status = evt.ok ? 'success' : 'error';
+        if (evt.output !== undefined) tool.toolOutput = truncate(typeof evt.output === 'string' ? evt.output : JSON.stringify(evt.output));
+        if (evt.error) tool.toolError = truncate(typeof evt.error === 'string' ? evt.error : JSON.stringify(evt.error));
+        // images 不进快照：base64 体积大，turn 结束后 jsonl hydrate 会带回来
+      }
+      break;
+    }
+    case 'run.tool_use_summary': {
+      if (!runMatches || !evt.summary) break;
+      const ids = Array.isArray(evt.blockIds) ? evt.blockIds : [];
+      const hit = st.messages.find(m => m.role === 'tool' && ids.includes(m.id));
+      if (hit) hit.groupSummary = evt.summary;
+      break;
+    }
+    case 'run.todo.updated':
+      if (runMatches && Array.isArray(evt.todos)) st.todos = evt.todos;
+      break;
+    case 'run.context_usage':
+      if (runMatches) st.contextUsage = evt;
+      break;
+    case 'run.done':
+    case 'run.error':
+    case 'run.cancelled':
+      // 不立刻删：留 grace 期给"收尾瞬间重连"当权威快照（见文件头说明）
+      if (runMatches) {
+        st.endedAt = Date.now();
+        if (typeof evt.seq === 'number' && evt.seq > st.seq) st.seq = evt.seq;
+      }
+      return;
+    case 'run.query.end':
+      liveTurns.delete(sid);
+      return;
+    default:
+      break;
+  }
+
+  // 所有本 session 事件都推进快照游标（包括未折叠类型）——
+  // 重连订阅从 seq 起，不折叠的事件类型（queue depth 等）丢了也无碍（幂等 UI 状态）
+  if (typeof evt.seq === 'number' && evt.seq > st.seq) st.seq = evt.seq;
+}
+
+function appendText(st, role, text, parentToolUseId = null) {
+  if (!text) return;
+  const last = st.messages[st.messages.length - 1];
+  // 子代理时间轴：不同 parent 的流不互吸（跟前端 lib/chat-stream.js 同构）
+  if (last && last.role === role && (last.parentToolUseId || null) === (parentToolUseId || null)) {
+    last.content = (last.content || '') + text;
+    return;
+  }
+  st.messages.push({
+    id: `${st.runId || 'live'}:m${st._msgCounter++}`,
+    ...(parentToolUseId ? { parentToolUseId } : {}),
+    role,
+    content: text,
+    runId: st.runId,
+  });
+}

package/server/engine/runs/store.js

@@ -0,0 +1,364 @@
+/**
+ * engine/runs/store.js — Run 数据库层（SQLite + better-sqlite3）
+ *
+ * Run 是 engine 的最小工作单元：一次 brief 触发，agent 自驱跑完 deskskill-engine 这类
+ * skill，输出产物（deck.html）。每条 run 在 DB 里一行 + 在文件系统里一个 workspace 目录。
+ *
+ * 状态机（朴素版，MVP 够用，后续若加 cancel 优雅终止再改）：
+ *   pending → running → succeeded
+ *                    ↘ failed
+ *                    ↘ cancelled
+ *
+ * 设计选择：
+ *  - sync API：better-sqlite3 是有意 sync，社区共识是直接用，不假装 async
+ *  - DB 路径：DB_PATH env > server/db/nodesign.db；目录不存在自动 mkdir
+ *  - metadata 字段是 JSON TEXT：保留扩展空间（token usage / round / tool 摘要 / 关键日志），
+ *    不强行落字段，等真实数据形态稳定后再 promote 成列
+ *  - 不做 run_events 表：MVP 阶段 SSE 流即时推给前端就行；持久化审计是 P3+ 的事
+ *  - id 形如 `run_<timestamp36>_<rand4>`：天然 sortable，方便 listRuns 默认逆序
+ */
+
+import Database from 'better-sqlite3';
+import { mkdirSync } from 'fs';
+import { tmpdir } from 'os';
+import { fileURLToPath } from 'url';
+import { dirname, join, resolve } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// 默认放在 server/db/nodesign.db，跟 .env.example 的 DB_PATH 默认值对齐。
+// ⛔ 但测试进程绝不许摸到这个默认值：vitest.server.config.js 里虽然配了测试库，
+// **裸跑** `npx vitest run xxx.test.js`（不带 -c）根本不读那份配置 —— 08-17/08-18
+// 两次就是这么把脏数据写进生产问题库的。config 层的兜底只护"跑对了命令"的人，
+// 治本要在库自己身上：认出 VITEST 环境（vitest 恒设这个 env）就落到 tmp。
+const DEFAULT_DB_PATH = process.env.VITEST
+  ? join(tmpdir(), 'nodesign-vitest-bare.db')
+  : resolve(__dirname, '../../db/nodesign.db');
+const DB_PATH = process.env.DB_PATH ? resolve(process.env.DB_PATH) : DEFAULT_DB_PATH;
+
+// 自动 mkdir 父目录（干净部署首次启动不 ENOENT）
+mkdirSync(dirname(DB_PATH), { recursive: true });
+
+const db = new Database(DB_PATH);
+db.pragma('journal_mode = WAL');
+db.pragma('foreign_keys = ON');
+
+// ── Schema ──
+db.exec(`
+  CREATE TABLE IF NOT EXISTS runs (
+    id              TEXT PRIMARY KEY,
+    skill_id        TEXT NOT NULL,
+    brief           TEXT NOT NULL,
+    status          TEXT NOT NULL
+                    CHECK(status IN ('pending', 'running', 'succeeded', 'failed', 'cancelled'))
+                    DEFAULT 'pending',
+    artifact_path   TEXT,                         -- 主产物相对路径（相对 workspace），如 'deck.html'
+    error           TEXT,                         -- 失败时的错误消息
+    metadata        TEXT NOT NULL DEFAULT '{}',   -- JSON：token usage / rounds / 关键摘要等
+    started_at      TEXT,                         -- 进入 running 的时间
+    finished_at     TEXT,                         -- 进入终态的时间
+    created_at      TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at      TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_runs_status_created ON runs(status, created_at DESC);
+  CREATE INDEX IF NOT EXISTS idx_runs_skill_created ON runs(skill_id, created_at DESC);
+
+  -- 分模型用量明细（2026-07-31）。数据源 = SDK result.modelUsage 的会话内差分
+  -- （modelUsage 是会话累计值，context.absorbResult 做差分后经 finishTurn 落这里）。
+  -- model 键是 SDK 上报的原始模型串（如 'claude-sonnet-5'）；家族归并（sonnet/opus）
+  -- 在查询侧做（lib/quota.js modelFamily），表里存原始值不丢信息。
+  CREATE TABLE IF NOT EXISTS run_model_usage (
+    run_id              TEXT NOT NULL,
+    model               TEXT NOT NULL,
+    input_tokens        INTEGER NOT NULL DEFAULT 0,
+    output_tokens       INTEGER NOT NULL DEFAULT 0,
+    cache_read_tokens   INTEGER NOT NULL DEFAULT 0,
+    cache_create_tokens INTEGER NOT NULL DEFAULT 0,
+    cost_usd            REAL NOT NULL DEFAULT 0,
+    created_at          TEXT NOT NULL DEFAULT (datetime('now')),
+    PRIMARY KEY (run_id, model)
+  );
+`);
+
+console.log(`[engine/runs] SQLite ready at ${DB_PATH}`);
+
+/**
+ * 清扫僵尸 run：上个进程留下的 pending/running 行（server 重启时 SDK 子进程全死，
+ * 这些 run 不可能再推进）标成 failed，否则永久停在 running（丢状态路径 P12）。
+ *
+ * **只能由 server 进程在启动时调一次**（server/index.js）。
+ *
+ * 2026-07-31 之前它是模块加载的副作用，后果是任何 import 到这个模块的东西都会
+ * 把线上正在跑的 run 全部标成 failed —— 不只是调试用的 `node -e`，`invite.mjs`
+ * 这种日常脚本也会（实测误杀了同一个用户的两轮对话，他那两轮的计量也一起丢了）。
+ * 更糟的是 notice.mjs：它存在的意义就是在服务活着的时候发重启预告，一跑就清场。
+ *
+ * 判据很简单：清扫的前提是"上个进程已经死了"，只有 server 自己启动时才知道这件事
+ * 成立。一个连接数据库的脚本对此一无所知，它凭什么替 server 宣布所有 run 都完了。
+ */
+export function sweepOrphanRuns() {
+  try {
+    const swept = db.prepare(`
+      UPDATE runs SET status = 'failed', error = 'server restarted while run in flight',
+        finished_at = datetime('now'), updated_at = datetime('now')
+      WHERE status IN ('pending', 'running')
+    `).run();
+    if (swept.changes > 0) {
+      console.log(`[engine/runs] swept ${swept.changes} orphaned run(s) from previous process`);
+    }
+    return swept.changes;
+  } catch (err) {
+    console.warn(`[engine/runs] orphan sweep failed:`, err.message);
+    return 0;
+  }
+}
+
+// ── ID 生成 ──
+
+/**
+ * `run_<base36-timestamp>_<rand4>`
+ * 例：run_lwx8mq3p_a7f2
+ * 天然按时间字典序排序；不依赖 UUID 库。
+ */
+export function newRunId() {
+  const ts = Date.now().toString(36);
+  const rand = Math.random().toString(36).slice(2, 6);
+  return `run_${ts}_${rand}`;
+}
+
+// ── 行 ↔ 对象 ──
+
+function rowToRun(row) {
+  if (!row) return null;
+  return {
+    id: row.id,
+    skillId: row.skill_id,
+    brief: row.brief,
+    status: row.status,
+    artifactPath: row.artifact_path,
+    error: row.error,
+    metadata: safeParseJson(row.metadata, {}),
+    // 归属 + 计量真列（2026-07-30 多用户；列由 projects/store.js 幂等 ALTER 加）
+    projectId: row.project_id ?? null,
+    userId: row.user_id ?? null,
+    sessionId: row.session_id ?? null,
+    inputTokens: row.input_tokens ?? null,
+    outputTokens: row.output_tokens ?? null,
+    cacheReadTokens: row.cache_read_tokens ?? null,
+    cacheCreateTokens: row.cache_create_tokens ?? null,
+    totalCostUsd: row.total_cost_usd ?? null,
+    startedAt: row.started_at,
+    finishedAt: row.finished_at,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+function safeParseJson(text, fallback) {
+  if (!text) return fallback;
+  try { return JSON.parse(text); } catch { return fallback; }
+}
+
+// ── 写入：CRUD ──
+
+/**
+ * 创建一个 pending 状态的 run。
+ * @param {object} input
+ * @param {string} input.skillId           - 要加载的 skill 名
+ * @param {string} input.brief             - 用户输入
+ * @param {string} [input.projectId=null]  - 归属 project（P0 turn endpoint 必传）
+ * @param {object} [input.metadata={}]     - 初始元信息（如 client / requestId）
+ * @returns {object} 完整 run 对象
+ */
+export function createRun({ skillId, brief, projectId = null, userId = null, sessionId = null, metadata = {} }) {
+  if (!skillId || typeof skillId !== 'string') throw new Error('createRun: skillId 必填');
+  if (!brief || typeof brief !== 'string') throw new Error('createRun: brief 必填');
+
+  const id = newRunId();
+  db.prepare(`
+    INSERT INTO runs (id, skill_id, brief, project_id, user_id, session_id, status, metadata)
+    VALUES (?, ?, ?, ?, ?, ?, 'pending', ?)
+  `).run(id, skillId, brief, projectId, userId, sessionId, JSON.stringify(metadata));
+
+  return getRun(id);
+}
+
+/**
+ * 落计量真列（2026-07-30）：turn 收尾时从 ctx.counters 写。列是配额 sum 的
+ * 数据源（metadata JSON 里同样有一份完整 counters 做审计）。
+ */
+export function setRunMetrics(id, {
+  inputTokens, outputTokens, cacheReadTokens, cacheCreateTokens, totalCostUsd,
+} = {}) {
+  db.prepare(`
+    UPDATE runs SET
+      input_tokens = ?, output_tokens = ?,
+      cache_read_tokens = ?, cache_create_tokens = ?,
+      total_cost_usd = ?,
+      updated_at = datetime('now')
+    WHERE id = ?
+  `).run(
+    inputTokens ?? 0, outputTokens ?? 0,
+    cacheReadTokens ?? 0, cacheCreateTokens ?? 0,
+    totalCostUsd ?? 0, id,
+  );
+}
+
+/**
+ * 落分模型明细（2026-07-31）。deltasByModel 形如
+ * { 'claude-sonnet-5': { inputTokens, outputTokens, cacheReadTokens, cacheCreateTokens, costUsd } }
+ * 值语义是"本 turn 增量"（差分在 context.absorbResult 做完）。用 upsert 覆盖而非
+ * 累加：一个 turn 只有一条 result，防御性重复调用不应把数字翻倍。
+ */
+const upsertModelUsage = db.prepare(`
+  INSERT INTO run_model_usage (run_id, model, input_tokens, output_tokens, cache_read_tokens, cache_create_tokens, cost_usd)
+  VALUES (?, ?, ?, ?, ?, ?, ?)
+  ON CONFLICT(run_id, model) DO UPDATE SET
+    input_tokens = excluded.input_tokens,
+    output_tokens = excluded.output_tokens,
+    cache_read_tokens = excluded.cache_read_tokens,
+    cache_create_tokens = excluded.cache_create_tokens,
+    cost_usd = excluded.cost_usd
+`);
+
+export function setRunModelUsage(runId, deltasByModel) {
+  if (!runId || !deltasByModel || typeof deltasByModel !== 'object') return;
+  for (const [model, d] of Object.entries(deltasByModel)) {
+    if (!model || !d) continue;
+    upsertModelUsage.run(
+      runId, model,
+      d.inputTokens ?? 0, d.outputTokens ?? 0,
+      d.cacheReadTokens ?? 0, d.cacheCreateTokens ?? 0,
+      d.costUsd ?? 0,
+    );
+  }
+}
+
+/** 某 run 的分模型明细（审计 / 前端展示用） */
+export function getRunModelUsage(runId) {
+  return db.prepare(
+    'SELECT model, input_tokens AS inputTokens, output_tokens AS outputTokens, cache_read_tokens AS cacheReadTokens, cache_create_tokens AS cacheCreateTokens, cost_usd AS costUsd FROM run_model_usage WHERE run_id = ?',
+  ).all(runId);
+}
+
+/** 读单条 */
+export function getRun(id) {
+  const row = db.prepare('SELECT * FROM runs WHERE id = ?').get(id);
+  return rowToRun(row);
+}
+
+/**
+ * 列出最近的 runs。
+ * @param {object} [opts]
+ * @param {number} [opts.limit=50]
+ * @param {string} [opts.status]   - 可选状态过滤
+ * @param {string} [opts.skillId]  - 可选 skill 过滤
+ */
+export function listRuns({ limit = 50, status, skillId } = {}) {
+  const where = [];
+  const args = [];
+  if (status) { where.push('status = ?'); args.push(status); }
+  if (skillId) { where.push('skill_id = ?'); args.push(skillId); }
+  const whereSql = where.length ? `WHERE ${where.join(' AND ')}` : '';
+  args.push(limit);
+  const rows = db.prepare(
+    `SELECT * FROM runs ${whereSql} ORDER BY created_at DESC LIMIT ?`
+  ).all(...args);
+  return rows.map(rowToRun);
+}
+
+// ── 状态转移：语义化函数（防止裸 SQL 散布到调用方）──
+
+const updateStatusStmt = db.prepare(`
+  UPDATE runs SET status = ?, updated_at = datetime('now') WHERE id = ?
+`);
+
+/** pending → running */
+export function markRunStarted(id) {
+  const row = db.prepare(`
+    UPDATE runs
+       SET status = 'running',
+           started_at = datetime('now'),
+           updated_at = datetime('now')
+     WHERE id = ? AND status = 'pending'
+     RETURNING *
+  `).get(id);
+  if (!row) throw new Error(`markRunStarted: run ${id} 不存在或不在 pending 状态`);
+  return rowToRun(row);
+}
+
+/** running → succeeded（带产物路径）*/
+export function markRunSucceeded(id, { artifactPath } = {}) {
+  const row = db.prepare(`
+    UPDATE runs
+       SET status = 'succeeded',
+           artifact_path = ?,
+           finished_at = datetime('now'),
+           updated_at = datetime('now')
+     WHERE id = ? AND status = 'running'
+     RETURNING *
+  `).get(artifactPath || null, id);
+  if (!row) throw new Error(`markRunSucceeded: run ${id} 不存在或不在 running 状态`);
+  return rowToRun(row);
+}
+
+/** running → failed（带错误消息）*/
+export function markRunFailed(id, errorMessage) {
+  const msg = String(errorMessage || 'unknown error').slice(0, 4000); // 防爆
+  const row = db.prepare(`
+    UPDATE runs
+       SET status = 'failed',
+           error = ?,
+           finished_at = datetime('now'),
+           updated_at = datetime('now')
+     WHERE id = ? AND status IN ('pending', 'running')
+     RETURNING *
+  `).get(msg, id);
+  if (!row) throw new Error(`markRunFailed: run ${id} 不存在或已是终态`);
+  return rowToRun(row);
+}
+
+/** running/pending → cancelled（用户主动取消）*/
+export function markRunCancelled(id) {
+  const row = db.prepare(`
+    UPDATE runs
+       SET status = 'cancelled',
+           finished_at = datetime('now'),
+           updated_at = datetime('now')
+     WHERE id = ? AND status IN ('pending', 'running')
+     RETURNING *
+  `).get(id);
+  if (!row) throw new Error(`markRunCancelled: run ${id} 不存在或已是终态`);
+  return rowToRun(row);
+}
+
+// ── metadata 合并 ──
+
+/**
+ * 合并 metadata（浅合并）。常见用法：
+ *   mergeRunMetadata(id, { roundCount: 3 })
+ *   mergeRunMetadata(id, { tokenUsage: { input: 1234, output: 567 } })
+ */
+export function mergeRunMetadata(id, partial) {
+  if (!partial || typeof partial !== 'object') return getRun(id);
+  const current = getRun(id);
+  if (!current) throw new Error(`mergeRunMetadata: run ${id} 不存在`);
+  const merged = { ...current.metadata, ...partial };
+  db.prepare(`
+    UPDATE runs SET metadata = ?, updated_at = datetime('now') WHERE id = ?
+  `).run(JSON.stringify(merged), id);
+  return getRun(id);
+}
+
+// ── 调试用：清空（仅测试）──
+
+/** ⚠️ 仅测试用 */
+export function _truncateRunsTable() {
+  if (process.env.NODE_ENV === 'production') {
+    throw new Error('_truncateRunsTable: 禁止在 production 调用');
+  }
+  db.prepare('DELETE FROM runs').run();
+}
+
+export default db;