llm-api-gateway-cli 1.0.0

package/lib/taskstore.js

@@ -0,0 +1,740 @@
+/**
+ * 任务持久化（模式五）
+ *
+ * 任务记录原本存在浏览器的 localStorage 里，但一次任务可能产生十几条工具输出、
+ * 每条都带文件正文，localStorage 那 ~5MB 根本不够，只能一路截断降级。
+ * 改成落到磁盘后这些限制就不存在了，而且换浏览器、清缓存都不会丢。
+ *
+ * 目录布局：
+ *   <store>/index.json          任务索引（只存元信息，列表用，很小）
+ *   <store>/tasks/<id>.json     单条任务的完整数据
+ *
+ * 索引与数据分开是为了列表页不必把每条任务的正文都读出来；索引丢了也能靠扫描
+ * tasks/ 重建，所以不会出现「索引坏了数据就全没了」。
+ */
+
+import path from 'node:path';
+import os from 'node:os';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  copyFileSync,
+  unlinkSync,
+  readdirSync,
+  statSync,
+} from 'node:fs';
+// 模式的唯一真相在 agent 那边，这里只用来校验落盘字段，避免两处各写一份清单
+import { MODES } from './agent.js';
+
+export const TTL_DAYS = 15; // 滑动 15 天
+export const TTL_MS = TTL_DAYS * 24 * 60 * 60 * 1000;
+export const MAX_TASKS = 20; // 最多保留 20 条
+export const MAX_MESSAGES = 2000; // 单条任务的消息数上限
+export const MAX_STEPS = 200; // 单条消息里的工具调用数上限
+
+/** 任务 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 function isSafeId(id) {
+  return typeof id === 'string' && ID_RE.test(id);
+}
+
+/** 目录比较用：去掉尾部分隔符、Windows 上大小写不敏感 */
+const normDir = (d) => (typeof d === 'string' && d ? d.replace(/[\\/]+$/, '').toLowerCase() : '');
+
+/* ---------- 存储目录探测 ---------- */
+
+/** 数据根目录名：统一放用户主目录下的这一个点目录 */
+export const DATA_DIR_NAME = '.llm-api-gateway-cli';
+
+/**
+ * 数据根目录：**用户主目录**下的 `.llm-api-gateway-cli`，各平台一致。
+ *
+ * 以前按平台惯例分散在 `%LOCALAPPDATA%` / `~/Library/Application Support` / `$XDG_DATA_HOME`，
+ * 外面还挂一个「脚本目录下的 `.tasks`」当便携兜底 —— 结果是同一台机器上数据可能出现在两三个
+ * 地方，用户根本不知道去哪儿找；而 `.tasks` 落在项目目录里还会弄脏仓库（打包时都得专门排除）。
+ * 现在统一成主目录里的一个点目录，跟 `.npm` / `.config` 这些做邻居：找得到、删得掉、拷得走。
+ *
+ * 想整根换地方用 `LLM_GATEWAY_DATA_DIR`；只想换任务目录用 `--store` / `store.dir`。
+ */
+export function defaultStoreRoot(env = process.env, home = os.homedir()) {
+  const custom = typeof env.LLM_GATEWAY_DATA_DIR === 'string' ? env.LLM_GATEWAY_DATA_DIR.trim() : '';
+  if (custom) return path.resolve(custom);
+  return path.join(home, DATA_DIR_NAME);
+}
+
+/** 平台惯例的数据目录（旧版本的落点之一） */
+function legacyPlatformRoot(env = process.env, home = os.homedir()) {
+  if (process.platform === 'win32') {
+    return path.join(env.LOCALAPPDATA || path.join(home, 'AppData', 'Local'), 'llm-api-gateway-cli');
+  }
+  if (process.platform === 'darwin') {
+    return path.join(home, 'Library', 'Application Support', 'llm-api-gateway-cli');
+  }
+  return path.join(env.XDG_DATA_HOME || path.join(home, '.local', 'share'), 'llm-api-gateway-cli');
+}
+
+/** 数一个存储目录的索引里记了几条任务；不存在/坏文件都算 0（只用来排序，不该把启动搞挂） */
+function indexedTaskCount(storeDir) {
+  try {
+    const data = JSON.parse(readFileSync(path.join(storeDir, 'index.json'), 'utf8'));
+    return Array.isArray(data?.tasks) ? data.tasks.length : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/** 数一个存储目录里实际有几个任务文件 */
+function taskFileCount(storeDir) {
+  try {
+    return readdirSync(path.join(storeDir, 'tasks')).filter((f) => f.endsWith('.json')).length;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * 旧版本可能用过的地方 —— **只在搬家时读，不再写入**。kind 决定它对应新根里的什么位置：
+ *   'root'     平台数据目录（当年是整根：tasks/ sessions/ config.json 都在里面）
+ *   'store'    脚本目录下的 `.tasks`（它本身就是一个存储目录）
+ *   'sessions' 脚本目录下的 `.sessions`
+ */
+export function legacyLocations(scriptDir, dataRoot, env = process.env, home = os.homedir()) {
+  const out = [];
+  const push = (from, to, kind) => {
+    if (!from || path.resolve(from) === path.resolve(to)) return;
+    if (out.some((x) => path.resolve(x.from) === path.resolve(from))) return;
+    out.push({ from, to, kind });
+  };
+  push(legacyPlatformRoot(env, home), dataRoot, 'root');
+  if (scriptDir) {
+    push(path.join(scriptDir, '.tasks'), path.join(dataRoot, 'tasks'), 'store');
+    push(path.join(scriptDir, '.sessions'), path.join(dataRoot, 'sessions'), 'sessions');
+  }
+  return out;
+}
+
+/** 某个旧位置里的「任务存储目录」在哪；纯会话位置没有任务目录 */
+function taskStoreDirOf(loc) {
+  if (loc.kind === 'root') return path.join(loc.from, 'tasks');
+  if (loc.kind === 'store') return loc.from;
+  return null;
+}
+
+/** 旧版本可能用过的**任务存储目录**（主目录不可写时的保命通道，有数据的排前面） */
+export function legacyStoreDirs(scriptDir, dataRoot, env = process.env, home = os.homedir()) {
+  return legacyLocations(scriptDir, dataRoot, env, home)
+    .map(taskStoreDirOf)
+    .filter((d) => d && path.resolve(d) !== path.resolve(dataRoot, 'tasks'))
+    .filter((d, i, a) => a.indexOf(d) === i)
+    .sort((a, b) => indexedTaskCount(b) - indexedTaskCount(a));
+}
+
+/** 真写一个探针文件再删掉，比只看权限位可靠（Windows 上权限位基本没用） */
+export function isWritable(dir) {
+  const probe = path.join(dir, `.write-probe-${process.pid}`);
+  try {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(probe, 'ok');
+    unlinkSync(probe);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** 递归复制，**已存在的目标文件一律不覆盖**（搬家的口径：新位置先来的算数） */
+function copyTreeIfMissing(from, to) {
+  const stat = { copied: 0, failed: 0 };
+  let entries;
+  try {
+    entries = readdirSync(from, { withFileTypes: true });
+  } catch {
+    return stat;
+  }
+  try {
+    mkdirSync(to, { recursive: true });
+  } catch {
+    return { copied: 0, failed: 1 };
+  }
+  for (const e of entries) {
+    // 探针与临时文件不是数据，别搬过去
+    if (e.name.startsWith('.write-probe-') || e.name.endsWith('.tmp')) continue;
+    const src = path.join(from, e.name);
+    const dst = path.join(to, e.name);
+    if (e.isDirectory()) {
+      const sub = copyTreeIfMissing(src, dst);
+      stat.copied += sub.copied;
+      stat.failed += sub.failed;
+    } else if (e.isFile()) {
+      try {
+        if (existsSync(dst)) continue;
+        copyFileSync(src, dst);
+        stat.copied++;
+      } catch {
+        // 单个文件搬不动（被杀软锁住之类）不该毁掉整个启动，记下来继续
+        stat.failed++;
+      }
+    }
+  }
+  return stat;
+}
+
+/** 搬过一次就留个记号，之后不再搬 —— 否则用户在新位置删掉的任务会被旧目录「复活」 */
+const MIGRATION_MARK = '.legacy-migrated.json';
+
+/**
+ * 把旧位置的数据**复制**到新的数据根目录。
+ *
+ * 为什么是复制而不是移动：搬家途中失败（权限、占用）不能让用户两头都没有 —— 复制成功
+ * 新位置就是完整的一份，旧目录爱留不留都由用户自己决定（横幅里会写明）。
+ * 幂等：不覆盖已存在的目标文件，且成功后留记号文件，所以第二次跑什么也不做。
+ */
+export function migrateLegacyData(dataRoot, { scriptDir = '', env = process.env, home = os.homedir() } = {}) {
+  const markFile = path.join(dataRoot, MIGRATION_MARK);
+  if (existsSync(markFile)) return [];
+
+  const locs = legacyLocations(scriptDir, dataRoot, env, home).filter((l) => existsSync(l.from));
+  if (!locs.length) return [];
+  if (!isWritable(dataRoot)) return [];
+
+  // 谁的任务多谁先搬：旧的平台数据目录里常常只剩一个**空索引**，真正的历史在别处
+  // （比如脚本目录下的 .tasks）。按固定顺序硬搬的话，空索引会先占住 index.json，
+  // 把有数据的挡在外面 —— 用户看到的就是「任务一条都没了」。所以按数据量排序。
+  locs.sort((a, b) => {
+    const da = taskStoreDirOf(a);
+    const db = taskStoreDirOf(b);
+    return (db ? indexedTaskCount(db) : -1) - (da ? indexedTaskCount(da) : -1);
+  });
+
+  const moved = [];
+  let failed = 0;
+  for (const loc of locs) {
+    const stat = copyTreeIfMissing(loc.from, loc.to);
+    failed += stat.failed;
+    if (stat.copied > 0) moved.push({ from: loc.from, to: loc.to, files: stat.copied });
+  }
+
+  // 从多个来源合并过来之后，索引可能只列了其中一部分任务（也可能反过来，列着几个已经不在
+  // 磁盘上的）。索引里全是能从任务文件推出来的元信息，所以只要对不上就删掉，让它按 tasks/
+  // 重建 —— 免得出现「文件明明在、侧边栏却不显示」，或者点进去 404 的幽灵条目。
+  const storeDir = path.join(dataRoot, 'tasks');
+  if (taskFileCount(storeDir) !== indexedTaskCount(storeDir)) {
+    try {
+      unlinkSync(path.join(storeDir, 'index.json'));
+    } catch {
+      /* 删不掉就按索引读，最多少显示几条，不影响数据本身 */
+    }
+  }
+
+  if (!failed && moved.length) {
+    try {
+      writeFileSync(markFile, `${JSON.stringify({ at: new Date().toISOString(), moved }, null, 2)}\n`, 'utf8');
+    } catch {
+      /* 记号写不上就下次再搬一遍；「不覆盖」保证不会重复计数 */
+    }
+  }
+  return moved;
+}
+
+/**
+ * 挑一个能写的任务存储目录。候选顺序：
+ *   1. 用户显式指定的 --store（指定了就必须能写，否则直接报错，不偷偷换地方）
+ *   2. 用户主目录下的 `.llm-api-gateway-cli/tasks`（新家；顺手把旧位置的数据搬过来）
+ *   3. 旧位置里**有数据**且能写的那个（主目录不可写时的保命通道，见下）
+ *   4. 系统临时目录（最后兜底）
+ * 返回 { dir, source, warning, notice, moved }：warning 是「没按预期落位」，
+ * notice 是「搬了家」这类正常但要让人知道的事。
+ *
+ * 特别注意 2 → 3：主目录可不可写会随环境变（受限沙箱里不可写、普通终端里可写）。
+ * 所以当主目录用不了、而旧位置里明明有历史任务时，继续用旧位置并说清楚 —— 宁可
+ * 让数据留在原地，也不能让用户看见一个空的任务列表。
+ */
+export function resolveStoreDir(explicit, scriptDir, env = process.env, home = os.homedir()) {
+  if (explicit) {
+    const dir = path.resolve(explicit);
+    if (!isWritable(dir)) throw new Error(`指定的存储目录不可写：${dir}`);
+    return { dir, source: 'explicit', warning: null, notice: null, moved: [] };
+  }
+
+  const dataRoot = defaultStoreRoot(env, home);
+  const preferred = path.join(dataRoot, 'tasks');
+
+  if (isWritable(preferred)) {
+    const moved = migrateLegacyData(dataRoot, { scriptDir, env, home });
+    const notice = moved.length
+      ? `已把旧位置的数据搬到 ${dataRoot}：${moved.map((m) => `${m.from}（${m.files} 个文件）`).join('、')}；确认无误后旧目录可以自己删掉。`
+      : null;
+    return { dir: preferred, source: 'user-data', warning: null, notice, moved };
+  }
+
+  // 主目录不可写：先看旧位置里有没有数据，有就继续用那儿（总比给一个空列表强）
+  for (const candidate of legacyStoreDirs(scriptDir, dataRoot, env, home)) {
+    // 索引没了、但 tasks/ 里还躺着任务文件的也算「有数据」—— 那种情况索引是可以重建的
+    const hasData = existsSync(path.join(candidate, 'index.json')) || taskFileCount(candidate) > 0;
+    if (!hasData) continue;
+    if (!isWritable(candidate)) continue;
+    return {
+      dir: candidate,
+      source: 'legacy',
+      warning: `用户主目录下的存储目录不可写（${preferred}），继续使用旧位置：${candidate}。想固定下来请用 --store 指定。`,
+      notice: null,
+      moved: [],
+    };
+  }
+
+  const tmp = path.join(os.tmpdir(), 'llm-api-gateway-cli-tasks');
+  if (isWritable(tmp)) {
+    return {
+      dir: tmp,
+      source: 'temp',
+      warning: `主目录与旧位置都不可写，已改用临时目录（重启后可能被系统清理）：${tmp}`,
+      notice: null,
+      moved: [],
+    };
+  }
+
+  throw new Error(`找不到可写的存储目录，试过：${preferred} / ${legacyStoreDirs(scriptDir, dataRoot, env, home).join(' / ')} / ${tmp}`);
+}
+
+/* ---------- 数据清洗 ---------- */
+
+/** 从消息里生成标题（服务端也算一遍，保证不依赖前端） */
+export function titleFromMessages(messages) {
+  const first = (Array.isArray(messages) ? messages : []).find((m) => m?.role === 'user' && m.content);
+  if (!first) return '新任务';
+  const t = String(first.content).replace(/\s+/g, ' ').trim();
+  if (!t) return '新任务';
+  return t.length > 24 ? `${t.slice(0, 24)}…` : t;
+}
+
+/** 已完成几轮回答（有 assistant 消息就算「已完成」），用于侧边栏状态 */
+function countReplies(messages) {
+  return (Array.isArray(messages) ? messages : []).filter((m) => m?.role === 'assistant').length;
+}
+
+/**
+ * 两份**已清洗**的消息是不是一模一样。
+ * 两边都过了 sanitizeMessages，字段与顺序一致，所以逐条比 JSON 就够；
+ * 逐条比也避免把几十 MB 的历史拼成一个巨大的字符串。
+ */
+function sameMessages(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (JSON.stringify(a[i]) !== JSON.stringify(b[i])) return false;
+  }
+  return true;
+}
+
+function sanitizeStep(s) {
+  if (!s || typeof s !== 'object') return null;
+  return {
+    id: typeof s.id === 'string' ? s.id.slice(0, 120) : '',
+    name: typeof s.name === 'string' ? s.name.slice(0, 60) : '',
+    label: typeof s.label === 'string' ? s.label.slice(0, 300) : '',
+    status: ['ok', 'fail', 'running'].includes(s.status) ? s.status : 'ok',
+    summary: typeof s.summary === 'string' ? s.summary.slice(0, 1000) : '',
+    content: typeof s.content === 'string' ? s.content : undefined,
+    // 调用参数也留着（`id` 就是模型的 tool_call_id）：任务记录因此始终能还原出
+    // 原生 tool_calls —— 会话文件被清掉、或换个 store 目录时，还能拿它把上下文接回去，
+    // 不至于退化成「把工具记录折成一段文本」那种有损形态。
+    args: typeof s.args === 'string' ? s.args.slice(0, 4000) : undefined,
+  };
+}
+
+function sanitizePending(p) {
+  if (!p || typeof p !== 'object' || typeof p.runId !== 'string') return null;
+  return {
+    runId: p.runId.slice(0, 120),
+    callId: typeof p.callId === 'string' ? p.callId.slice(0, 120) : '',
+    name: typeof p.name === 'string' ? p.name.slice(0, 60) : '',
+    args: typeof p.args === 'string' ? p.args : '',
+    preview: typeof p.preview === 'string' ? p.preview.slice(0, 4000) : '',
+  };
+}
+
+/** 只接受认识的字段，避免把页面传来的任意对象原样写盘 */
+function sanitizeMessage(m) {
+  if (!m || typeof m !== 'object') return null;
+  const content = typeof m.content === 'string' ? m.content : '';
+  const reasoning = typeof m.reasoning === 'string' ? m.reasoning : '';
+  const steps = Array.isArray(m.steps) ? m.steps.slice(0, MAX_STEPS).map(sanitizeStep).filter(Boolean) : [];
+  const pending = sanitizePending(m.pending);
+  // 提示与「继续执行」入口也要落盘：撞到上限后刷新页面，不该既没了说明也没了按钮
+  const notices = Array.isArray(m.notices)
+    ? m.notices.filter((t) => typeof t === 'string' && t).slice(0, 10).map((t) => t.slice(0, 500))
+    : [];
+  const canResume = m.canResume === true;
+  if (!content && !reasoning && !steps.length && !notices.length) return null;
+  return { role: m.role === 'assistant' ? 'assistant' : 'user', content, reasoning, steps, pending, notices, canResume };
+}
+
+export function sanitizeMessages(input) {
+  if (!Array.isArray(input)) return [];
+  return input.slice(-MAX_MESSAGES).map(sanitizeMessage).filter(Boolean);
+}
+
+/* ---------- 存储实现 ---------- */
+
+function readJsonFile(file, fallback = null) {
+  try {
+    if (!existsSync(file)) return fallback;
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+/** 同步睡一会儿（rename 重试用） */
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/**
+ * 先写 .tmp 再 rename —— 进程被杀也不会留下半截 JSON。
+ *
+ * Windows 上 rename 覆盖已存在的目标会偶发 EPERM（杀软或索引器短暂占用文件句柄），
+ * 短时间连续写索引时尤其容易撞上，所以重试几次；实在不行退回直接覆盖写，
+ * 宁可牺牲这一轮的原子性，也不能让保存整个失败。
+ */
+function writeJsonAtomic(file, value) {
+  const tmp = `${file}.tmp`;
+  const text = JSON.stringify(value, null, 2);
+  writeFileSync(tmp, text, 'utf8');
+  for (let i = 0; i < 5; i++) {
+    try {
+      renameSync(tmp, file);
+      return;
+    } catch (e) {
+      if (e.code !== 'EPERM' && e.code !== 'EACCES' && e.code !== 'EBUSY') throw e;
+      sleepSync(5 * (i + 1));
+    }
+  }
+  try {
+    writeFileSync(file, text, 'utf8');
+  } finally {
+    try {
+      unlinkSync(tmp);
+    } catch {
+      /* 忽略 */
+    }
+  }
+}
+
+export class TaskStore {
+  constructor(dir) {
+    this.dir = dir;
+    this.tasksDir = path.join(dir, 'tasks');
+    this.indexFile = path.join(dir, 'index.json');
+    this.tasks = [];
+    this.warnings = [];
+  }
+
+  /** 建目录 + 载入索引；索引缺失或损坏时扫描 tasks/ 重建 */
+  init() {
+    mkdirSync(this.tasksDir, { recursive: true });
+    // readJsonFile 对「文件不存在」和「文件损坏」都返回 null，这里要分开对待：
+    // 前者是首次使用（正常），后者是数据受损（必须告诉用户，不能静默吞掉）
+    const existed = existsSync(this.indexFile);
+    const raw = readJsonFile(this.indexFile, null);
+    if (raw && Array.isArray(raw.tasks)) {
+      this.tasks = raw.tasks.map((t) => this.#normalizeMeta(t)).filter(Boolean);
+      this.#backfillReplies(raw.tasks);
+    } else {
+      if (existed) this.warnings.push('index.json 无法解析（可能上次写入被中断），已按 tasks/ 目录重建索引');
+      this.tasks = this.#scan();
+      this.#writeIndex();
+    }
+    return this;
+  }
+
+  /**
+   * 老索引里没有 replies 字段（这个字段是后加的），#normalizeMeta 会把它补成 0，
+   * 那样已有的、明明回答过的任务会被显示成「未开始」。这里按需读一次任务文件补上，
+   * 读不到就维持 0 —— 只是少一个标记，不影响任务本身。
+   */
+  #backfillReplies(rawTasks) {
+    let changed = false;
+    for (const raw of rawTasks) {
+      if (!raw || Number.isInteger(raw.replies)) continue;
+      const meta = this.#meta(raw.id);
+      if (!meta) continue;
+      const data = readJsonFile(this.#taskFile(meta.id), null);
+      if (!data) continue;
+      const n = countReplies(data.messages);
+      if (n !== meta.replies) {
+        meta.replies = n;
+        changed = true;
+      }
+    }
+    if (changed) this.#writeIndex();
+  }
+
+  /** 从任务文件里扫出元信息（索引丢了才发现，所以尽量容错） */
+  #scan() {
+    const found = [];
+    let files = [];
+    try {
+      files = readdirSync(this.tasksDir).filter((f) => f.endsWith('.json'));
+    } catch {
+      return found;
+    }
+    for (const f of files) {
+      const id = f.slice(0, -'.json'.length);
+      if (!isSafeId(id)) continue;
+      const data = readJsonFile(path.join(this.tasksDir, f), null);
+      if (!data) {
+        this.warnings.push(`任务文件损坏已跳过：${f}`);
+        continue;
+      }
+      const meta = this.#normalizeMeta({ ...data, id });
+      if (meta) found.push(meta);
+    }
+    return found;
+  }
+
+  #normalizeMeta(t) {
+    if (!t || !isSafeId(t.id)) return null;
+    const created = Number(t.createdAt);
+    const updated = Number(t.updatedAt);
+    const base = Number.isFinite(created) ? created : Date.now();
+    return {
+      id: t.id,
+      title: typeof t.title === 'string' && t.title.trim() ? t.title.trim().slice(0, 60) : '未命名任务',
+      workDir: typeof t.workDir === 'string' && t.workDir ? t.workDir : null,
+      // 审批模式跟着任务走：切回某个任务时还是当初用的那个模式
+      mode: MODES.includes(t.mode) ? t.mode : 'manual',
+      createdAt: base,
+      updatedAt: Number.isFinite(updated) ? updated : base,
+      renamed: Boolean(t.renamed),
+      // 侧边栏据此显示「已完成 / 未开始」；只记数量，不把正文拖进索引
+      replies: Number.isInteger(t.replies) && t.replies > 0 ? t.replies : 0,
+      // 派生关系：形成任务树。只保证形状合法，父任务是否还在由渲染端容错
+      // （父任务被删掉时，这条会自然退回顶层，而不是从列表里消失）
+      parentId: typeof t.parentId === 'string' && isSafeId(t.parentId) && t.parentId !== t.id ? t.parentId : null,
+    };
+  }
+
+  #writeIndex() {
+    writeJsonAtomic(this.indexFile, {
+      version: 3,
+      updatedAt: Date.now(),
+      tasks: this.tasks,
+    });
+  }
+
+  #meta(id) {
+    return this.tasks.find((t) => t.id === id) || null;
+  }
+
+  /**
+   * 父任务必须真实存在、且与子任务在同一个工作目录下。
+   * 不满足就退回顶层 —— 宁可少一层层级，也不要留下指向虚空（或跨目录）的引用，
+   * 否则删掉父任务后列表里会出现「谁也找不到归属」的孤儿行。
+   */
+  #resolveParent(parentId, workDir) {
+    if (!isSafeId(parentId)) return null;
+    const parent = this.#meta(parentId);
+    if (!parent) return null;
+    return normDir(parent.workDir) === normDir(workDir) ? parentId : null;
+  }
+
+  #taskFile(id) {
+    // id 已过 isSafeId，这里再 resolve 一次做双保险
+    const file = path.join(this.tasksDir, `${id}.json`);
+    if (path.dirname(path.resolve(file)) !== path.resolve(this.tasksDir)) {
+      throw Object.assign(new Error('任务 id 非法'), { status: 400 });
+    }
+    return file;
+  }
+
+  list() {
+    return [...this.tasks].sort((a, b) => b.updatedAt - a.updatedAt).map((t) => ({ ...t }));
+  }
+
+  /**
+   * 读一条任务的消息体。`ok` 表示文件真的读出来了 —— 文件丢了或坏了时
+   * 调用方（save）要知道「盘上其实没有这份数据」，不能把它当成「内容一样」。
+   */
+  #read(id) {
+    const data = readJsonFile(this.#taskFile(id), null);
+    if (!data) return { ok: false, messages: [] };
+    return { ok: true, messages: sanitizeMessages(data.messages) };
+  }
+
+  get(id) {
+    if (!isSafeId(id)) throw Object.assign(new Error('任务 id 非法'), { status: 400 });
+    const meta = this.#meta(id);
+    if (!meta) return null;
+    return { ...meta, messages: this.#read(id).messages };
+  }
+
+  /** 新建一条任务，id 由服务端生成；parentId 非空时派生到某条已有任务之下（任务树） */
+  create({ id, title, workDir, mode, messages, parentId }) {
+    const now = Date.now();
+    const clean = sanitizeMessages(messages);
+    // 没显式给标题时从首条用户消息取，否则会先落成「未命名任务」再等下次保存才改名
+    const meta = this.#normalizeMeta({
+      id,
+      title: typeof title === 'string' && title.trim() ? title.trim() : titleFromMessages(clean),
+      workDir,
+      mode,
+      createdAt: now,
+      updatedAt: now,
+      renamed: false,
+      replies: countReplies(clean),
+      parentId,
+    });
+    if (!meta) throw Object.assign(new Error('任务 id 非法'), { status: 400 });
+    if (this.#meta(meta.id)) throw Object.assign(new Error('任务已存在'), { status: 409 });
+    // 父任务必须在同目录下真实存在，否则当顶层任务
+    meta.parentId = this.#resolveParent(meta.parentId, meta.workDir);
+    this.#put(meta, clean);
+    this.tasks.unshift(meta);
+    this.prune();
+    this.#writeIndex();
+    return { ...meta, messages: clean };
+  }
+
+  /**
+   * 覆盖保存一条任务；title 只在没被用户改过名时才自动更新。
+   *
+   * **什么都没变的保存不算一次「更新」**：updatedAt 不动，文件也不重写。
+   * 页面在切任务、切模式、点目录时都会顺手保存一次，如果每次都把时间戳刷新，
+   * 侧边栏那个「N 分钟前」就会因为「点了下标题」变成「刚刚」—— 看着像发生了什么事，
+   * 其实什么都没发生。判断依据是这条记录到底变没变（标题 / 目录 / 模式 / 改名标记 / 回答数 / 消息）。
+   */
+  save(id, { title, workDir, mode, messages, renamed }) {
+    const meta = this.#meta(id);
+    if (!meta) return null;
+    const clean = sanitizeMessages(messages);
+
+    // 先算出「这次要变成什么样」，再和盘上的逐项比
+    const next = {
+      workDir: typeof workDir === 'string' && workDir ? workDir : meta.workDir,
+      mode: MODES.includes(mode) ? mode : meta.mode,
+      renamed: meta.renamed || renamed === true,
+      title: meta.title,
+      replies: countReplies(clean),
+    };
+    if (typeof title === 'string' && title.trim() && next.renamed) next.title = title.trim().slice(0, 60);
+    else if (!next.renamed && clean.length) next.title = titleFromMessages(clean);
+
+    const stored = this.#read(id);
+    const unchanged =
+      stored.ok &&
+      next.title === meta.title &&
+      next.workDir === meta.workDir &&
+      next.mode === meta.mode &&
+      next.renamed === meta.renamed &&
+      next.replies === meta.replies &&
+      sameMessages(stored.messages, clean);
+    // 一样就到此为止：不写文件、不写索引、updatedAt 保持原值（盘上文件丢了/坏了则照常补写）
+    if (unchanged) return { ...meta, messages: stored.messages };
+
+    meta.title = next.title;
+    meta.workDir = next.workDir;
+    meta.mode = next.mode;
+    meta.renamed = next.renamed;
+    meta.replies = next.replies;
+    meta.updatedAt = Date.now();
+    this.#put(meta, clean);
+    this.#writeIndex();
+    return { ...meta, messages: clean };
+  }
+
+  #put(meta, messages) {
+    writeJsonAtomic(this.#taskFile(meta.id), {
+      version: 2,
+      ...meta,
+      messages: sanitizeMessages(messages),
+    });
+  }
+
+  remove(id) {
+    if (!isSafeId(id)) throw Object.assign(new Error('任务 id 非法'), { status: 400 });
+    const before = this.tasks.length;
+    this.tasks = this.tasks.filter((t) => t.id !== id);
+    try {
+      unlinkSync(this.#taskFile(id));
+    } catch {
+      /* 文件可能已经不在了 */
+    }
+    if (this.tasks.length === before) return false;
+    // 父任务没了，子任务上的 parentId 就成了悬空引用。渲染端虽然有容错（悬空当顶层），
+    // 但盘上的数据自己也该是自洽的 —— 这里把子任务升到顶层并写回。
+    this.#orphanChildren([id]);
+    this.#writeIndex();
+    return true;
+  }
+
+  /**
+   * 把「父任务已不在」的子任务升到顶层并落盘，返回被处理的 id。
+   * parentIds 是这一轮消失的父任务；调用方可能是手动删除（remove）或自动清理（prune）。
+   * 只改 parentId、不动 updatedAt：删的是别人，不该让幸存任务的「N 分钟前」跳一下。
+   * 任务文件读不出来（损坏 / 丢失）时就只改索引里的元信息，不凭空造一个空任务文件。
+   */
+  #orphanChildren(parentIds) {
+    const gone = new Set(parentIds);
+    const ids = [];
+    for (const kid of this.tasks) {
+      if (!kid.parentId || !gone.has(kid.parentId)) continue;
+      kid.parentId = null;
+      ids.push(kid.id);
+      const stored = this.#read(kid.id);
+      if (stored.ok) this.#put(kid, stored.messages);
+    }
+    return ids;
+  }
+
+  /** 滑动 15 天 + 最多 20 条；返回被清掉的 id */
+  prune(now = Date.now()) {
+    const removed = [];
+    const kept = [];
+    for (const t of this.tasks) {
+      if (now - t.updatedAt > TTL_MS) removed.push(t);
+      else kept.push(t);
+    }
+    kept.sort((a, b) => b.updatedAt - a.updatedAt);
+    removed.push(...kept.splice(MAX_TASKS));
+    for (const t of removed) {
+      try {
+        unlinkSync(this.#taskFile(t.id));
+      } catch {
+        /* 忽略 */
+      }
+    }
+    this.tasks = kept;
+    if (removed.length) {
+      // 被清掉的可能正好是某个任务的父任务（父任务通常更老，先到期）：同样不能留下悬空引用
+      this.#orphanChildren(removed.map((t) => t.id));
+      this.#writeIndex();
+    }
+    return removed.map((t) => t.id);
+  }
+
+  stats() {
+    let bytes = 0;
+    for (const t of this.tasks) {
+      try {
+        bytes += statSync(this.#taskFile(t.id)).size;
+      } catch {
+        /* 忽略 */
+      }
+    }
+    const oldest = this.tasks.length
+      ? this.tasks.reduce((a, b) => (a.updatedAt < b.updatedAt ? a : b))
+      : null;
+    return {
+      dir: this.dir,
+      taskCount: this.tasks.length,
+      maxTasks: MAX_TASKS,
+      ttlDays: TTL_MS / 86400000,
+      bytes,
+      oldestExpiresAt: oldest ? oldest.updatedAt + TTL_MS : null,
+    };
+  }
+}