llm-api-gateway-cli 1.0.0

package/lib/plandoc.js

@@ -0,0 +1,178 @@
+/**
+ * 计划模式的计划落盘（P1–P3）
+ *
+ * 计划模式原来只是「模型在对话里给一段计划」—— 关掉页面、任务过期就没了，
+ * 切到自动模式后也没法让模型「照那份计划做」。这里把计划变成工作目录里的真实文件：
+ *
+ *   <workDir>/docs/YYYYMMDD-<概要>.md
+ *
+ * 三条硬约束：
+ *   1. 目录不存在就**自动创建**（含中间层级），不要求用户先建 docs/；
+ *   2. 文件名带**日期 + 调整内容概要**，概要优先取计划自己的 `# 标题`；
+ *   3. 同名文件**只追加不覆盖** —— 同一主题同一天再计划一次，记成「更新」而不是把上文冲掉；
+ *      内容完全一致则直接不写盘（幂等）。
+ *
+ * 本模块不碰网络、不碰会话，纯文件逻辑，便于单测。
+ */
+
+import path from 'node:path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+
+/** 计划统一落在工作目录下的这个子目录 */
+export const PLAN_DIR = 'docs';
+
+/** 概要最长多少个字符 —— 文件名不是标题，够认出来就行 */
+const SUMMARY_MAX = 30;
+
+/** 单份计划正文上限（防止模型把整篇代码贴进来把会话目录撑爆） */
+const PLAN_MAX_BYTES = 512 * 1024;
+
+/** 文件名里不允许出现的字符：Windows 比 POSIX 更严，按 Windows 来 */
+// eslint-disable-next-line no-control-regex
+const ILLEGAL_IN_NAME = /[\\/:*?"<>|\u0000-\u001f]/g;
+
+/** markdown 标题里常见的装饰字符，概要里留着只会让文件名难认 */
+const DECORATION = /[`*_~#「」【】\[\]()（）]/g;
+
+/**
+ * 把一段文字压成可以当文件名用的「概要」。
+ * 空白折成 `-`，去掉非法字符与首尾的点/横线（Windows 不允许文件名以点结尾）。
+ */
+export function sanitizeSummary(raw) {
+  let s = typeof raw === 'string' ? raw : '';
+  s = s.replace(/\r?\n+/g, ' ').replace(/\s+/g, '-');
+  s = s.replace(DECORATION, '').replace(ILLEGAL_IN_NAME, '');
+  s = s.replace(/-{2,}/g, '-').replace(/^[-.\s]+|[-.\s]+$/g, '');
+  if (s.length > SUMMARY_MAX) s = s.slice(0, SUMMARY_MAX).replace(/[-.\s]+$/, '');
+  return s;
+}
+
+/**
+ * 从计划正文里抽「调整内容概要」。
+ *
+ * 三级回落，任何一级拿不到都不会让落盘失败：
+ *   计划里的第一个 `# 标题`（模型被要求把概要写在第一行） → 传入的备用标题 → '计划'
+ *
+ * 顺带剥掉「迭代计划：」这类前缀 —— 日期已经在文件名前面了，再重复一次很难看。
+ */
+export function summarizeTitle(plan, fallback = '') {
+  const text = typeof plan === 'string' ? plan : '';
+  const m = text.match(/^[ \t]{0,3}#{1,6}[ \t]+(.+?)[ \t]*#*[ \t]*$/m);
+  const raw = (m ? m[1] : '') || fallback || '';
+  const stripped = String(raw)
+    // 只剥「标签 + 分隔符」这种前缀：「迭代计划：xxx」→「xxx」。
+    // 不能只看开头是不是「计划」二字 —— 那样「计划模式落盘」会被削成「模式落盘」。
+    .replace(/^(?:迭代|优化|实施|执行|修复|重构|开发)?\s*计划\s*[:：\-—]\s*/, '')
+    .replace(/^[:：\-—\s]+/, '');
+  return sanitizeSummary(stripped) || '计划';
+}
+
+/** 本地时区的 YYYYMMDD —— 用户看的日期必须是「他今天的日期」，不能用 UTC */
+export function dateStamp(now = new Date()) {
+  const d = now instanceof Date ? now : new Date(now);
+  const p = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}`;
+}
+
+/** 本地时区的 HH:MM，用于「更新」小节 */
+function timeStamp(now = new Date()) {
+  const d = now instanceof Date ? now : new Date(now);
+  const p = (n) => String(n).padStart(2, '0');
+  return `${p(d.getHours())}:${p(d.getMinutes())}`;
+}
+
+/** `YYYYMMDD-<概要>.md` */
+export function planFileName(now, summary) {
+  return `${dateStamp(now)}-${summary || '计划'}.md`;
+}
+
+/**
+ * 目标路径必须落回工作目录内 —— 与 `lib/tools.js` 的沙箱同口径。
+ * 概要已经清掉了分隔符，这里是第二道闸：模型给的标题再怎么花也出不去。
+ */
+function resolveInWorkDir(workDir, relPath) {
+  const root = path.resolve(workDir);
+  const abs = path.resolve(root, relPath);
+  const rel = path.relative(root, abs);
+  if (rel !== '' && (rel.startsWith('..') || path.isAbsolute(rel))) {
+    throw new Error(`路径越界：${relPath} 不在工作目录内`);
+  }
+  return abs;
+}
+
+/** 计划正文规范化：统一换行 + 末尾留一个换行（git diff 干净） */
+function normalizePlan(plan) {
+  let body = String(plan).replace(/\r\n/g, '\n').trim();
+  if (body.length > PLAN_MAX_BYTES) body = `${body.slice(0, PLAN_MAX_BYTES)}\n\n…（计划过长已截断）`;
+  return `${body}\n`;
+}
+
+/**
+ * 把一份计划写入 `<workDir>/docs/`。
+ *
+ * @param {object}      o
+ * @param {string}      o.workDir 工作目录（任务模式下必填）
+ * @param {string}      o.plan    计划正文（markdown）
+ * @param {string=}     o.title   备用概要：计划里没有 `# 标题` 时用（任务标题等）
+ * @param {Date|number=} o.now    注入时间，便于测试
+ * @returns {{relPath:string, absPath:string, summary:string, bytes:number, action:'created'|'updated'|'unchanged'}}
+ */
+export function savePlanDoc({ workDir, plan, title = '', now = new Date() } = {}) {
+  if (typeof workDir !== 'string' || !workDir.trim()) throw new Error('未指定工作目录，计划无法落盘');
+  if (typeof plan !== 'string' || !plan.trim()) throw new Error('计划正文为空，没有可落盘的内容');
+
+  const body = normalizePlan(plan);
+  const summary = summarizeTitle(plan, title);
+  const fileName = planFileName(now, summary);
+  const relPath = `${PLAN_DIR}/${fileName}`;
+  const absPath = resolveInWorkDir(workDir, relPath);
+  const dir = path.dirname(absPath);
+
+  // P2：没有 docs/ 就自动建 —— 这是用户最容易踩的一步，不能让他先手动 mkdir
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  let content = body;
+  let action = 'created';
+  if (existsSync(absPath)) {
+    let old = '';
+    try {
+      old = readFileSync(absPath, 'utf8');
+    } catch {
+      old = ''; // 读不出来就当空的：写盘本身会报错，这里不掩盖
+    }
+    if (old.trim() === body.trim()) {
+      // 幂等：同一份计划重复落盘不产生第二条记录
+      return { relPath, absPath, summary, bytes: Buffer.byteLength(old, 'utf8'), action: 'unchanged' };
+    }
+    // 只追加不覆盖：用户/上一轮写在里面的内容不能被冲掉
+    content = `${old.trimEnd()}\n\n---\n\n## 更新（${timeStamp(now)}）\n\n${body}`;
+    action = 'updated';
+  }
+
+  writeFileSync(absPath, content, 'utf8');
+  return { relPath, absPath, summary, bytes: Buffer.byteLength(content, 'utf8'), action };
+}
+
+/**
+ * 取「模型给出的那份计划」：最后一条**有正文且没有工具调用**的 assistant 消息。
+ * 工具轮的 content 常常是 null（或一句过渡话），拿它当计划就错了。
+ */
+export function lastAssistantText(messages) {
+  if (!Array.isArray(messages)) return '';
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (!m || m.role !== 'assistant') continue;
+    if (Array.isArray(m.tool_calls) && m.tool_calls.length) continue;
+    if (typeof m.content === 'string' && m.content.trim()) return m.content;
+  }
+  return '';
+}
+
+/** 会话里第一条用户消息 —— 任务标题之外的备用概要来源 */
+export function firstUserText(messages) {
+  if (!Array.isArray(messages)) return '';
+  for (const m of messages) {
+    if (m && m.role === 'user' && typeof m.content === 'string' && m.content.trim()) return m.content;
+  }
+  return '';
+}

package/lib/pricing.js

@@ -0,0 +1,52 @@
+/**
+ * 成本估算（M4）
+ *
+ * 网关通常接的是本地/自建上游（按 0 计），但也可能是转发到云端付费模型。
+ * 这里只做一件小事：给一个「按百万 token 单价 × 用量」的粗估，让 /cost 有数可看。
+ *
+ * 几点刻意为之：
+ *  · 单价表内置在代码里，不联网、不引入依赖；
+ *  · 认不出的模型**不猜**：返回 known=false，界面只说 token 数，不编美元数字；
+ *  · 价格会变，所以这里只当量级参考，措辞上不承诺精确。
+ */
+
+/** 单价单位：美元 / 百万 token */
+const PRICE_TABLE = [
+  { match: /gpt-4o-mini/i, prompt: 0.15, completion: 0.6 },
+  { match: /gpt-4o/i, prompt: 2.5, completion: 10 },
+  { match: /gpt-4\.1-mini/i, prompt: 0.4, completion: 1.6 },
+  { match: /gpt-4\.1/i, prompt: 2, completion: 8 },
+  { match: /o4-mini|o3-mini/i, prompt: 1.1, completion: 4.4 },
+  { match: /claude-3-5-haiku|claude-3\.5-haiku/i, prompt: 0.8, completion: 4 },
+  { match: /claude-3-5-sonnet|claude-3\.5-sonnet|claude-3-7-sonnet/i, prompt: 3, completion: 15 },
+  { match: /claude-(opus|sonnet)-4|claude-4/i, prompt: 3, completion: 15 },
+  { match: /deepseek-chat|deepseek-v3/i, prompt: 0.27, completion: 1.1 },
+  { match: /deepseek-reasoner|deepseek-r1/i, prompt: 0.55, completion: 2.19 },
+];
+
+/** 找出模型对应的单价；认不出返回 null（不要瞎猜） */
+export function priceFor(model) {
+  const name = String(model || '');
+  return PRICE_TABLE.find((r) => r.match.test(name)) || null;
+}
+
+/**
+ * @returns {{known:boolean, usd:number|null, prompt:number, completion:number, model:string}}
+ */
+export function estimateCost(usage, model) {
+  const prompt = Number(usage?.prompt) || 0;
+  const completion = Number(usage?.completion) || 0;
+  const price = priceFor(model);
+  if (!price) return { known: false, usd: null, prompt, completion, model: String(model || '') };
+  const usd = (prompt / 1e6) * price.prompt + (completion / 1e6) * price.completion;
+  return { known: true, usd, prompt, completion, model: String(model || '') };
+}
+
+/** 给 /cost 用的一行摘要（中文，认不出模型时只说 token） */
+export function formatCost(usage, model) {
+  const c = estimateCost(usage, model);
+  const tokens = `输入 ${c.prompt} / 输出 ${c.completion} / 合计 ${c.prompt + c.completion} tokens`;
+  if (!c.known) return `${tokens}（模型 ${c.model || '未知'} 无内置单价，本地/自建上游按 0 计，这里只报 token）`;
+  const shown = c.usd < 0.01 ? c.usd.toFixed(6) : c.usd.toFixed(4);
+  return `${tokens} ≈ $${shown}（按月单价粗估，仅供参考）`;
+}

package/lib/runner.js

@@ -0,0 +1,234 @@
+/**
+ * 传输无关的 Agent 运行器（M1）
+ *
+ * 把 lib/agent.js 的工具循环包成「建会话 → 发起任务 → 遇写入挂起 → 等批准 → 断点续跑」
+ * 的可复用流程。Web（task-server.js）与 CLI（cli-agent.js）都基于它，
+ * 这样两边处理挂起态、续跑与用量统计的方式保持一致，不会各自抄一遍后行为漂移。
+ *
+ * 关键点：runAgent 挂起时调用方必须自己保留会话（这里用内存对象承载）；
+ * resumeWithApproval 会从断点继续，并且**可能再次挂起**（模型连续写多个文件），
+ * 所以续跑要放在循环里，直到不再挂起为止。
+ *
+ * M2 追加：会话可以被「恢复」——createSession 接受外部 id，restoreSession 从落盘记录
+ * 还原成可继续跑的会话对象，runTurn 通过 persist 回调把最新状态交回调用方（由它决定存哪）。
+ * 运行器本身仍然不认识存储实现，Web 与 CLI 各自接自己的 store。
+ */
+
+import { randomUUID } from 'node:crypto';
+import { runAgent, resumeWithApproval } from './agent.js';
+
+/** 会话 id 必须是 UUID 形状：它同时是落盘文件名，形状不对就有目录穿越风险 */
+const ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+export const isSessionId = (id) => typeof id === 'string' && ID_RE.test(id);
+
+/**
+ * 任务模式的系统提示词：讲清工作目录、工具用法与写入约束。
+ * mode 会改变对模型的约束 —— 计划模式必须明确「只读、只出计划」，
+ * 否则模型很容易一边调研一边就动手改了。
+ *
+ * `planFile` 是这条任务已经落盘的计划的**相对路径**（见 lib/plandoc.js）。
+ * 带上它以后：
+ *   · 计划模式 → 在这份文档上继续完善；
+ *   · 自动 / 手动 → 先读这份计划，按其中的步骤执行并把结果回填进去。
+ * 这正是「切到自动模式后依据上下文和计划处理」的落点：计划不在模型脑子里，在磁盘上。
+ *
+ * @param {string=} opts.planFile 已落盘计划的相对路径（如 `docs/20260916-xx.md`）
+ */
+export function buildTaskSystemPrompt(workDir, userSystem, mode = 'manual', { planFile } = {}) {
+  const base = `你是一个在用户本机工作目录内执行任务的编程助手，可以读写文件。
+
+工作目录：${workDir}
+所有文件工具都只能作用于该目录之内。调用工具时请一律使用**相对工作目录的相对路径**（例如 "src/index.js"），不要使用绝对路径。
+
+工作方式：
+1. 先用 list_dir / search_files 摸清结构，再用 read_file 读具体文件；
+2. write_file 是**整体覆盖写入**，不是增量修改 —— 改文件前必须先 read_file 拿到完整内容，然后写入改动后的完整内容；只改几处优先用 apply_patch；
+3. 不要臆测文件内容，需要什么就读什么；不确定就先搜索；
+4. 完成或告一段落后，用简短的中文说明你做了什么、改了哪些文件。`;
+
+  const modeNote =
+    mode === 'plan'
+      ? `
+
+【当前是计划模式】
+你现在**只能读取和搜索，不能修改任何文件**（写入工具没有提供给你，写了也会被拒绝）。
+请先充分调研，然后给出一份**具体可执行的计划**，包含：
+  · 要改动哪些文件（写清相对路径）；
+  · 每个文件具体改什么、为什么；
+  · 有没有风险或需要用户拍板的地方。
+给出计划后停下等用户确认，不要试图开始动手。计划要具体到用户看完就能说「照这个做」。
+
+【计划本身要写成一份完整文档】
+你输出的这段计划会被系统**原样落盘**成工作目录里的 \`docs/YYYYMMDD-<概要>.md\`，所以：
+  · 第一行必须是 \`# <概要标题>\`：简短中文，不超过 30 字，概括这次要调整什么 —— 它就是文件名里的概要；
+  · 用标准 markdown 组织：需求 / 变更清单、改动方案（逐文件，路径写相对路径）、执行步骤、验收方式、风险；
+  · 执行步骤写成可勾选的清单（\`- [ ] 步骤\`），后续按计划执行时会被逐项勾掉；
+  · 不要写「我会先看看」这类过程话，只写这份文档本身。
+你不用自己调用工具去建目录或写文件（计划模式也没有写入工具），落盘由系统完成。`
+      : mode === 'auto'
+        ? `
+
+【当前是自动模式】
+用户已授权你**直接写入文件，不需要逐个确认**。请保持克制：
+  · 只改与当前任务直接相关的文件，不要顺手重构无关代码；
+  · 覆盖已有文件前务必先 read_file，避免把用户的内容冲掉；
+  · 每完成一步用一句话说明改了什么。`
+        : '';
+
+  // 已落盘的计划：切模式之后模型必须接着那份文档干，而不是凭记忆重来
+  const planNote = planFile
+    ? `
+
+【已落盘的计划】${planFile}
+这条任务已经有一份写进工作目录的计划文档，它就是**本轮的作业依据**：
+  · 先用 read_file 读它，按其中的文件清单与执行步骤推进，不要另起炉灶；
+  · 每完成一项，用 apply_patch 把对应的 \`- [ ]\` 改成 \`- [x]\`；
+  · 在文档末尾的「执行结果」里补一行：改了什么、验证结果如何；
+  · 如果实际做法与计划不一致，**先更新这份文档**再继续，不要静默偏离。${
+    mode === 'plan' ? '\n  · 当前是计划模式：在这一份上继续完善，落盘时会更新同一个文件。' : ''
+  }`
+    : '';
+
+  const extra = typeof userSystem === 'string' && userSystem.trim() ? `\n\n用户附加要求：\n${userSystem.trim()}` : '';
+  return base + modeNote + planNote + extra;
+}
+
+/**
+ * 建一个会话对象。它就是 lib/agent.js 里的 run（含 messages / usage / pending），
+ * 额外带上模型与会话元数据，便于调用方持久化或复用。
+ *
+ * @param {string=} id 显式指定会话 id（--resume 时用）；不合法就换一个新的，
+ *                     绝不把外部字符串直接当文件名用。
+ */
+export function createSession({ workingDir, model, temperature, maxTokens, system, mode, id } = {}) {
+  return {
+    id: isSessionId(id) ? id : randomUUID(),
+    workingDir: workingDir || '',
+    model,
+    mode: mode || 'manual',
+    temperature: Number.isFinite(temperature) ? temperature : undefined,
+    maxTokens: Number.isFinite(maxTokens) && maxTokens > 0 ? maxTokens : undefined,
+    messages: [{ role: 'system', content: buildTaskSystemPrompt(workingDir, system, mode) }],
+    usage: { prompt: 0, completion: 0 },
+    pending: null,
+    pendingPreview: null,
+    touchedAt: Date.now(),
+  };
+}
+
+/**
+ * 从落盘的记录还原会话（--continue / --resume）。
+ *
+ * 与 createSession 的区别：**不重建 system 消息**，直接沿用存下来的 messages ——
+ * 那里面第一条就是当时的 system，重建反而会把当前的工作目录与模式混进去，
+ * 让「上次那个会话」变成另一个会话。overrides 只覆盖元数据。
+ *
+ * 记录不可用（缺 id / messages 不是数组）时返回 null，由调用方提示并新建。
+ */
+export function restoreSession(record, overrides = {}) {
+  if (!record || typeof record !== 'object' || !isSessionId(record.id) || !Array.isArray(record.messages)) return null;
+  return {
+    id: record.id,
+    workingDir: overrides.workingDir || record.workingDir || '',
+    model: overrides.model || record.model || '',
+    mode: overrides.mode || record.mode || 'manual',
+    temperature: Number.isFinite(record.temperature) ? record.temperature : undefined,
+    maxTokens: Number.isFinite(record.maxTokens) && record.maxTokens > 0 ? record.maxTokens : undefined,
+    messages: record.messages,
+    usage: { prompt: Number(record.usage?.prompt) || 0, completion: Number(record.usage?.completion) || 0 },
+    // 挂起态一并恢复：进程退出再回来时，那条待批准的工具调用还在
+    pending: record.pending && typeof record.pending === 'object' ? record.pending : null,
+    pendingPreview: record.pendingPreview && typeof record.pendingPreview === 'object' ? record.pendingPreview : null,
+    touchedAt: Number(record.touchedAt) || Date.now(),
+  };
+}
+
+/** 会话里已有多少条对话（不含 system），给「已恢复会话（N 条消息）」这类提示用 */
+export function countTurns(session) {
+  return Array.isArray(session?.messages) ? session.messages.filter((m) => m?.role !== 'system').length : 0;
+}
+
+/** 往会话里追加一条用户消息（空串会被忽略，返回 false） */
+export function pushUser(session, text) {
+  const content = typeof text === 'string' ? text : '';
+  if (!content.trim()) return false;
+  session.messages.push({ role: 'user', content });
+  return true;
+}
+
+/**
+ * 跑一轮对话（可含多步工具调用与多次写入批准）。
+ *
+ * @param {object}   opts
+ * @param {object}   opts.cfg          { baseUrl, key }
+ * @param {object}   opts.session      createSession / restoreSession 的产物
+ * @param {string=}  opts.prompt       本轮用户输入（省略则用会话里已有的 messages）
+ * @param {Function} opts.onEvent      事件回调，收到 lib/agent.js 发出的原始事件
+ * @param {Function} opts.askApproval  写入挂起时调用，签名 (pending, preview) => Promise<boolean>
+ * @param {Function=} opts.persist     每轮结束时回调（成功/失败/挂起都会调），由调用方落盘
+ * @param {AbortSignal=} opts.signal   中止信号
+ * @returns {Promise<{status:'done'|'aborted', hitLimit?:boolean}>}
+ */
+export async function runTurn({ cfg, session, prompt, onEvent, askApproval, persist, signal }) {
+  if (prompt != null && !pushUser(session, prompt)) {
+    throw Object.assign(new Error('本轮输入为空'), { status: 400 });
+  }
+
+  // 落盘一律放在 finally：挂起、中止、报错都各有各的「下次要接着跑」，
+  // 只在成功路径上写，等于挂起态永远不会被记住（这正是 M2 要修的）。
+  const save = () => {
+    if (typeof persist !== 'function') return;
+    session.touchedAt = Date.now();
+    try {
+      persist(session);
+    } catch {
+      /* 落盘失败不该影响这一轮的对话 */
+    }
+  };
+
+  try {
+    let outcome = await runAgent({ cfg, run: session, send: onEvent, signal });
+
+    // 挂起 → 询问 → 续跑；续跑可能再次挂起（连续写多个文件），因此循环处理
+    while (outcome.status === 'awaiting-approval') {
+      save(); // 挂起瞬间先存一次，用户此时关掉终端也还能回来批准
+      const approved = await askApproval(outcome.pending, outcome.preview);
+      outcome = await resumeWithApproval({ cfg, run: session, send: onEvent, signal, approved });
+    }
+
+    return outcome;
+  } finally {
+    save();
+  }
+}
+
+/**
+ * 「恢复一个挂起态」：进程退出前那条待批准的工具调用还在会话里，
+ * 回来时先问用户批不批，再接着跑。没有挂起态则返回 null（调用方照常开新一轮）。
+ */
+export async function resumePendingTurn({ cfg, session, onEvent, askApproval, persist, signal }) {
+  if (!session?.pending) return null;
+  const save = () => {
+    if (typeof persist !== 'function') return;
+    session.touchedAt = Date.now();
+    try {
+      persist(session);
+    } catch {
+      /* 忽略 */
+    }
+  };
+  try {
+    const approved = await askApproval(session.pending, session.pendingPreview || { path: '?', content: '' });
+    // 不要把 session.pending 提前清掉：resumeWithApproval 正是靠 run.pending 找到
+    // 「要执行哪个调用」，它自己会在开头清空。提前清会让它抛 409「没有待批准的写入」。
+    let outcome = await resumeWithApproval({ cfg, run: session, send: onEvent, signal, approved });
+    while (outcome.status === 'awaiting-approval') {
+      save();
+      const again = await askApproval(outcome.pending, outcome.preview);
+      outcome = await resumeWithApproval({ cfg, run: session, send: onEvent, signal, approved: again });
+    }
+    return outcome;
+  } finally {
+    save();
+  }
+}

package/lib/runstore.js

@@ -0,0 +1,96 @@
+/**
+ * 挂起态（待批准的工具调用）落盘
+ *
+ * 原来挂起态只在内存里存 10 分钟，刷新页面或重启服务就没了，用户走开一会儿回来
+ * 就得重跑整个任务。现在把它写到磁盘上，TTL 也放宽到 60 分钟：
+ * 刷新页面、甚至重启服务，待批准的写入都还在，回来点一下就能接着跑。
+ *
+ * 文件布局：<dir>/<runId>.json，内容就是 agent 循环里的 run 对象。
+ */
+
+import path from 'node:path';
+import { existsSync, mkdirSync, readFileSync, unlinkSync, readdirSync } from 'node:fs';
+import { isSafeId } from './taskstore.js';
+import { writeJsonAtomic } from './jsonstore.js';
+
+export function createRunStore(dir) {
+  mkdirSync(dir, { recursive: true });
+  const file = (id) => path.join(dir, `${id}.json`);
+
+  const write = (run) => {
+    if (!isSafeId(run?.id)) throw new Error('挂起态 id 非法');
+    writeJsonAtomic(file(run.id), run);
+  };
+
+  const read = (id) => {
+    if (!isSafeId(id)) return null;
+    const f = file(id);
+    if (!existsSync(f)) return null;
+    try {
+      const data = JSON.parse(readFileSync(f, 'utf8'));
+      return data && typeof data === 'object' ? data : null;
+    } catch {
+      // 损坏的挂起态没有保留价值，清掉免得每次启动都报
+      try {
+        unlinkSync(f);
+      } catch {
+        /* 忽略 */
+      }
+      return null;
+    }
+  };
+
+  const drop = (id) => {
+    if (!isSafeId(id)) return false;
+    try {
+      unlinkSync(file(id));
+      return true;
+    } catch {
+      return false;
+    }
+  };
+
+  /** 列出全部挂起态；顺带按 TTL 清掉过期的 */
+  const list = (ttlMs) => {
+    const out = [];
+    let names = [];
+    try {
+      names = readdirSync(dir);
+    } catch {
+      return out;
+    }
+    const now = Date.now();
+    for (const n of names) {
+      if (n.endsWith('.tmp')) {
+        // 上次写一半留下的残骸
+        try {
+          unlinkSync(path.join(dir, n));
+        } catch {
+          /* 忽略 */
+        }
+        continue;
+      }
+      if (!n.endsWith('.json')) continue;
+      const id = n.slice(0, -'.json'.length);
+      // 这个目录只归我们写，名字不是 UUID 的 .json 一定是垃圾（手滑、别的工具），直接清掉
+      if (!isSafeId(id)) {
+        try {
+          unlinkSync(path.join(dir, n));
+        } catch {
+          /* 忽略 */
+        }
+        continue;
+      }
+      const run = read(id);
+      if (!run) continue;
+      if (ttlMs && now - (run.touchedAt || 0) > ttlMs) {
+        drop(id);
+        continue;
+      }
+      out.push(run);
+    }
+    return out;
+  };
+
+  return { dir, write, read, drop, list };
+}