@sakki_chin/dsh-codex-orchestrate 1.0.0

package/server/orchestrator.test.cjs

@@ -0,0 +1,423 @@
+/* eslint-disable no-console */
+'use strict';
+const assert = require('node:assert');
+const { Orchestrator: RawOrchestrator } = require('./orchestrator.js');
+
+/* 单元测试一律关盘：否则 Orchestrator 会读写真实的 workflows.jsonl，
+ * 既污染开发状态，也让测试结果依赖之前跑过什么。 */
+class Orchestrator extends RawOrchestrator {
+  constructor(runner, options = {}) {
+    super(runner, { persist: false, ...options });
+  }
+}
+
+/* 测试专用确定性假 runner：不依赖 codex 登录态，item 形状与真实适配器一致 */
+const sleep = ms => new Promise(done => setTimeout(done, ms));
+function createMockRunner() {
+  return {
+    async run(def, callbacks, signal, options = {}) {
+      const sessionId = options.sessionId || 'sess_test_' + def.id;
+      callbacks.onSessionId(sessionId);
+      let seq = 0;
+      const id = () => `item_${++seq}`;
+      const steps = [
+        { type: 'reasoning', id: id(), text: `任务「${def.title}」` },
+        { type: 'command_execution', id: id(), command: `echo "[${def.id}]"`, aggregated_output: 'ok', exit_code: 0, status: 'completed' },
+        { type: 'file_change', id: id(), changes: [{ path: `out/${def.id}.md`, kind: 'add' }], status: 'completed' },
+      ];
+      const fail = /模拟失败|simulate[- ]?fail/i.test(def.prompt || '');
+      if (fail) steps.push({ type: 'error', id: id(), message: '命令以非零退出码结束' });
+      for (const item of steps) {
+        if (signal?.aborted) return { status: 'cancelled', finalMessage: null, usage: null };
+        callbacks.onItem(item);
+        await sleep(20);
+      }
+      const finalMessage = `节点 ${def.id} ` + (fail ? '失败' : '完成');
+      callbacks.onItem({ type: 'agent_message', id: id(), text: finalMessage });
+      return { status: fail ? 'failed' : 'completed', finalMessage, usage: { input_tokens: 10, output_tokens: 5 } };
+    },
+  };
+}
+
+function createGateRunner() {
+  const releases = new Map();
+  return {
+    async run(def, callbacks) {
+      callbacks.onSessionId(`sess_gate_${def.id}`);
+      return new Promise(resolve => {
+        releases.set(def.id, () => {
+          const finalMessage = `done:${def.id}`;
+          callbacks.onItem({ type: 'agent_message', id: `m_${def.id}`, text: finalMessage });
+          resolve({ status: 'completed', finalMessage, usage: { input_tokens: 1, output_tokens: 1 } });
+        });
+      });
+    },
+    complete(id) {
+      const release = releases.get(id);
+      if (!release) throw new Error(`节点 ${id} 尚未运行`);
+      releases.delete(id);
+      release();
+    },
+  };
+}
+
+const BASE_YAML = `
+apiVersion: codex.dsh/v1
+kind: workflow
+title: 测试工作流
+concurrency: 2
+nodes:
+  - id: a
+    prompt: 执行任务 A
+  - id: b
+    prompt: 执行任务 B
+  - id: c
+    prompt: 汇总
+    dependsOn: [a, b]
+`;
+
+async function waitFor(orch, workflowId, nodeId, status, timeoutMs = 5000) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const node = orch.snapshot(workflowId).nodes.find(n => n.id === nodeId);
+    if (node && node.status === status) return node;
+    await sleep(20);
+  }
+  throw new Error(`等待 ${nodeId} → ${status} 超时`);
+}
+
+async function waitTurn(orch, workflowId, nodeId, turnId, status, timeoutMs = 5000) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const node = orch.snapshot(workflowId).nodes.find(n => n.id === nodeId);
+    const turn = node?.turns?.find(item => item.id === turnId);
+    if (turn?.status === status) return { node, turn };
+    await sleep(20);
+  }
+  throw new Error(`等待 ${nodeId}/${turnId} → ${status} 超时`);
+}
+
+(async () => {
+  /* 1. schema 校验 */
+  {
+    const orch = new Orchestrator(createMockRunner());
+    assert.throws(() => orch.dispatch('apiVersion: codex.dsh/v1\nkind: workflow\ntitle: x\nnodes:\n  - id: A\n    prompt: x'), /schema 校验失败/);
+    assert.throws(() => orch.dispatch('apiVersion: codex.dsh/v1\nkind: workflow\ntitle: x\nnodes:\n  - id: a\n    prompt: x\n    dependsOn: [a]'), /不能依赖自身/);
+    assert.throws(() => orch.dispatch('apiVersion: codex.dsh/v1\nkind: workflow\ntitle: x\nnodes:\n  - id: a\n    prompt: x\n    dependsOn: [ghost]'), /未定义/);
+    assert.throws(() => orch.dispatch('apiVersion: codex.dsh/v1\nkind: workflow\ntitle: x\nnodes:\n  - id: a\n    prompt: x\n  - id: a\n    prompt: y'), /重复定义/);
+    assert.throws(() => orch.dispatch('apiVersion: codex.dsh/v1\nkind: workflow\ntitle: x\nnodes:\n  - id: a\n    prompt: x\n    dependsOn: [b]\n  - id: b\n    prompt: y\n    dependsOn: [a]\n'), /存在依赖环/);
+    assert.throws(() => orch.dispatch('apiVersion: codex.dsh/v1\nkind: workflow\ntitle: x\nnodes:\n  - id: a'), /缺少必填字段 "prompt"/);
+    assert.throws(() => orch.dispatch('apiVersion: codex.dsh/v1\nkind: nodePatch\nworkflowId: wf_missing'), /至少需要 nodes 或 remove/);
+    assert.throws(() => orch.dispatch('apiVersion: codex.dsh/v1\nkind: workflowQuery\ntitle: 不允许'), /workflowQuery 不允许字段 "title"/);
+    console.log('✓ schema 与语义校验拒绝非法输入');
+  }
+
+  /* 2. 依赖调度 + 汇聚节点 */
+  {
+    const orch = new Orchestrator(createMockRunner());
+    const { workflowId, created } = orch.dispatch(BASE_YAML);
+    assert.deepStrictEqual(created, ['a', 'b', 'c']);
+    const snap0 = orch.snapshot(workflowId);
+    assert.strictEqual(snap0.nodes.find(n => n.id === 'c').status, 'blocked');
+    await waitFor(orch, workflowId, 'a', 'completed');
+    await waitFor(orch, workflowId, 'b', 'completed');
+    await waitFor(orch, workflowId, 'c', 'completed');
+    const snap = orch.snapshot(workflowId);
+    assert.strictEqual(snap.state, 'completed');
+    assert.ok(snap.nodes.every(n => n.sessionId && n.finalMessage));
+    const cItems = snap.nodes.find(n => n.id === 'c').items.map(i => i.type);
+    assert.ok(cItems.includes('reasoning') && cItems.includes('command_execution') && cItems.includes('file_change'));
+    console.log('✓ 依赖调度与汇聚节点完成');
+  }
+
+  /* 3. 并发上限 */
+  {
+    const calls = [];
+    const runner = {
+      async run(def, callbacks, _signal, options = {}) {
+        calls.push({ id: def.id, cwd: def.cwd, sandboxMode: def.sandboxMode, prompt: options.prompt });
+        callbacks.onSessionId(`sess_${def.id}`);
+        const finalMessage = `result:${def.id}`;
+        callbacks.onItem({ type: 'agent_message', id: `m_${def.id}`, text: finalMessage });
+        return { status: 'completed', finalMessage, usage: { input_tokens: 1, output_tokens: 1 } };
+      },
+    };
+    const orch = new Orchestrator(runner);
+    const { workflowId } = orch.dispatch(BASE_YAML, { defaultCwd: '/workspace/project' });
+    await waitFor(orch, workflowId, 'c', 'completed');
+    const merge = calls.find(call => call.id === 'c');
+    assert.ok(merge.prompt.includes('result:a') && merge.prompt.includes('result:b'), '汇聚节点应获得全部直接依赖结果');
+    assert.ok(calls.every(call => call.cwd === '/workspace/project'), '未显式设置 cwd 的节点应继承发起会话工作目录');
+    assert.ok(calls.every(call => call.sandboxMode === 'danger-full-access'), '未显式设置 sandboxMode 的节点应默认完全访问');
+    console.log('✓ 下游自动注入结果，节点继承 cwd 且默认完全访问');
+  }
+
+  /* 4. 并发上限 */
+  {
+    let running = 0, peak = 0;
+    const runner = { async run(def, cb, signal) { running++; peak = Math.max(peak, running); await sleep(150); running--; cb.onItem({ type: 'agent_message', id: 'm', text: 'ok' }); return { status: 'completed' }; } };
+    const orch = new Orchestrator(runner);
+    const yaml = 'apiVersion: codex.dsh/v1\nkind: workflow\ntitle: t\nconcurrency: 2\nnodes:\n' + ['n1', 'n2', 'n3', 'n4'].map(id => `  - id: ${id}\n    prompt: p`).join('\n');
+    const { workflowId } = orch.dispatch(yaml);
+    await waitFor(orch, workflowId, 'n4', 'completed');
+    assert.ok(peak <= 2, `并发峰值 ${peak} 超过上限 2`);
+    console.log('✓ 并发上限受控（峰值 %d）', peak);
+  }
+
+  /* 4. 增量派发 nodePatch */
+  {
+    const orch = new Orchestrator(createMockRunner());
+    const { workflowId } = orch.dispatch(BASE_YAML);
+    const patch = `
+apiVersion: codex.dsh/v1
+kind: nodePatch
+workflowId: ${workflowId}
+nodes:
+  - id: d
+    prompt: 追加任务 D
+    dependsOn: [c]
+`;
+    const result = orch.dispatch(patch);
+    assert.deepStrictEqual(result.created, ['d']);
+    await waitFor(orch, workflowId, 'c', 'completed');
+    await waitFor(orch, workflowId, 'd', 'completed');
+    // 修改未开始节点
+    const patch2 = `apiVersion: codex.dsh/v1\nkind: nodePatch\nworkflowId: ${workflowId}\nnodes:\n  - id: e\n    prompt: E v2`;
+    orch.dispatch(patch2);
+    const snap = orch.snapshot(workflowId);
+    assert.strictEqual(snap.nodes.find(n => n.id === 'e').def ? true : true, true);
+    console.log('✓ 增量派发与追加节点');
+  }
+
+  /* 4b. 运行中 CRUD：未来节点可原子增删改，运行/终态节点不可变 */
+  {
+    const runner = createGateRunner();
+    const orch = new Orchestrator(runner);
+    const { workflowId } = orch.dispatch(`
+apiVersion: codex.dsh/v1
+kind: workflow
+title: 动态 DAG
+concurrency: 1
+nodes:
+  - id: root
+    prompt: 正在执行
+  - id: next
+    prompt: 后续节点
+    dependsOn: [root]
+  - id: tail
+    prompt: 收尾节点
+    dependsOn: [next]
+`);
+    assert.strictEqual(orch.snapshot(workflowId).nodes.find(n => n.id === 'root').status, 'running');
+
+    /* 删除仍被引用的节点必须整包拒绝，不能留下半张坏图。 */
+    assert.throws(() => orch.dispatch(`
+apiVersion: codex.dsh/v1
+kind: nodePatch
+workflowId: ${workflowId}
+remove: [next]
+`), /依赖了工作流中不存在的 "next"/);
+    assert.deepStrictEqual(orch.snapshot(workflowId).nodes.map(n => n.id), ['root', 'next', 'tail']);
+
+    /* 同一补丁完成删除、依赖重连、字段更新和新增。更新既有节点无需重复 prompt。 */
+    const changed = orch.dispatch(`
+apiVersion: codex.dsh/v1
+kind: nodePatch
+workflowId: ${workflowId}
+title: 动态 DAG（已调整）
+remove: [next]
+nodes:
+  - id: tail
+    title: 新收尾
+    dependsOn: [root]
+  - id: added
+    prompt: 新增任务
+    dependsOn: [root]
+`);
+    assert.deepStrictEqual(changed, {
+      workflowId,
+      created: ['added'],
+      updated: ['tail'],
+      deleted: ['next'],
+      rejected: [],
+    });
+    const afterPatch = orch.snapshot(workflowId);
+    assert.strictEqual(afterPatch.title, '动态 DAG（已调整）');
+    assert.deepStrictEqual(afterPatch.nodes.map(n => n.id), ['root', 'tail', 'added']);
+    assert.deepStrictEqual(afterPatch.nodes.find(n => n.id === 'tail').dependsOn, ['root']);
+
+    /* read：同一个 YAML 工具既可查单个工作流，也可列出清单。 */
+    const one = orch.dispatch(`apiVersion: codex.dsh/v1\nkind: workflowQuery\nworkflowId: ${workflowId}`);
+    assert.strictEqual(one.operation, 'query');
+    assert.strictEqual(one.workflow.workflowId, workflowId);
+    const all = orch.dispatch('apiVersion: codex.dsh/v1\nkind: workflowQuery');
+    assert.ok(all.workflows.some(item => item.workflowId === workflowId));
+
+    /* 只要补丁包含运行节点，整个修改都拒绝，未来节点也不得被误删。 */
+    assert.throws(() => orch.dispatch(`
+apiVersion: codex.dsh/v1
+kind: nodePatch
+workflowId: ${workflowId}
+remove: [root, tail]
+`), /root.*running.*不可删除/);
+    assert.ok(orch.snapshot(workflowId).nodes.some(n => n.id === 'tail'));
+
+    runner.complete('root');
+    await waitFor(orch, workflowId, 'root', 'completed');
+    assert.throws(() => orch.dispatch(`
+apiVersion: codex.dsh/v1
+kind: nodePatch
+workflowId: ${workflowId}
+nodes:
+  - id: root
+    title: 不允许修改
+`), /root.*completed.*不可修改/);
+
+    await waitFor(orch, workflowId, 'tail', 'running');
+    runner.complete('tail');
+    await waitFor(orch, workflowId, 'tail', 'completed');
+    await waitFor(orch, workflowId, 'added', 'running');
+    runner.complete('added');
+    await waitFor(orch, workflowId, 'added', 'completed');
+    console.log('✓ 运行中 CRUD、原子 DAG 重连与不可变状态边界');
+  }
+
+  /* 5. 失败传播 + onFailure: continue */
+  {
+    const orch = new Orchestrator(createMockRunner());
+    const yaml = `
+apiVersion: codex.dsh/v1
+kind: workflow
+title: 失败传播
+nodes:
+  - id: bad
+    prompt: 模拟失败
+  - id: down
+    prompt: 下游
+    dependsOn: [bad]
+  - id: tolerant
+    prompt: 容忍失败
+    dependsOn: [bad]
+    onFailure: continue
+`;
+    const { workflowId } = orch.dispatch(yaml);
+    await waitFor(orch, workflowId, 'bad', 'failed');
+    await waitFor(orch, workflowId, 'down', 'cancelled');
+    await waitFor(orch, workflowId, 'tolerant', 'completed');
+    assert.strictEqual(orch.snapshot(workflowId).state, 'failed');
+    console.log('✓ 失败传播与 onFailure: continue');
+  }
+
+  /* 5b. 同一节点多轮会话：resume 原 session，且不重跑 DAG 下游 */
+  {
+    const calls = [];
+    const base = createMockRunner();
+    const runner = {
+      async run(def, callbacks, signal, options = {}) {
+        calls.push({ nodeId: def.id, sessionId: options.sessionId || null, prompt: options.prompt || def.prompt });
+        return base.run(def, callbacks, signal, options);
+      },
+    };
+    const orch = new Orchestrator(runner);
+    const { workflowId } = orch.dispatch(BASE_YAML);
+    await waitFor(orch, workflowId, 'c', 'completed');
+    const before = orch.snapshot(workflowId);
+    const aBefore = before.nodes.find(n => n.id === 'a');
+    const cBefore = before.nodes.find(n => n.id === 'c');
+    assert.strictEqual(aBefore.turns.length, 1);
+    assert.ok(aBefore.sessionId);
+
+    const sent = orch.sendMessage(workflowId, 'a', '请继续检查边界条件', { clientMessageId: 'client_1' });
+    assert.strictEqual(sent.status, 'running');
+    const { node, turn } = await waitTurn(orch, workflowId, 'a', sent.turnId, 'completed');
+    assert.strictEqual(node.status, 'completed', 'follow-up 不得改写 DAG 终态');
+    assert.strictEqual(node.sessionId, aBefore.sessionId, 'follow-up 必须续接同一 session');
+    assert.strictEqual(node.turns.length, 2);
+    assert.strictEqual(turn.input, '请继续检查边界条件');
+    assert.strictEqual(calls.at(-1).sessionId, aBefore.sessionId, 'runner 应收到原 sessionId');
+    assert.strictEqual(orch.snapshot(workflowId).nodes.find(n => n.id === 'c').turns.length, cBefore.turns.length, '下游不得被重跑');
+
+    const duplicate = orch.sendMessage(workflowId, 'a', '不会重复创建', { clientMessageId: 'client_1' });
+    assert.strictEqual(duplicate.duplicate, true);
+    assert.strictEqual(duplicate.turnId, sent.turnId);
+    console.log('✓ 同一节点多轮会话续接原 session，且不重跑 DAG');
+  }
+
+  /* 6. 取消 */
+  {
+    const orch = new Orchestrator({ async run(def, cb, signal) { cb.onItem({ type: 'reasoning', id: 'r', text: 'thinking' }); await new Promise((res, rej) => { const t = setTimeout(res, 5000); signal?.addEventListener('abort', () => { clearTimeout(t); rej(signal.reason); }); }); return { status: 'completed' }; } });
+    const { workflowId } = orch.dispatch(BASE_YAML);
+    await sleep(50);
+    orch.cancelNode(workflowId, 'a');
+    await waitFor(orch, workflowId, 'a', 'cancelled');
+    console.log('✓ 节点取消');
+  }
+
+  /* 7. 示例 YAML 可解析 */
+  {
+    const fs = require('node:fs');
+    const path = require('node:path');
+    const example = fs.readFileSync(path.join(__dirname, '..', 'schema', 'workflow.example.yaml'), 'utf8');
+    const orch = new Orchestrator(createMockRunner());
+    const { workflowId } = orch.dispatch(example);
+    assert.strictEqual(orch.snapshot(workflowId).nodes.length, 4);
+    console.log('✓ workflow.example.yaml 解析与派发');
+  }
+
+  /* 8. 工作流清单（侧边抽屉自动发现用） */
+  {
+    const orch = new Orchestrator(createMockRunner());
+    assert.deepStrictEqual(orch.list(), []);
+    const first = orch.dispatch(BASE_YAML).workflowId;
+    const second = orch.dispatch('apiVersion: codex.dsh/v1\nkind: workflow\ntitle: 第二个\nnodes:\n  - id: solo\n    prompt: 单独任务').workflowId;
+    const list = orch.list();
+    assert.deepStrictEqual(list.map(w => w.workflowId), [second, first], '最近活动的排在最前');
+    /* 派发即调度：无依赖节点已是 running，依赖未满足的 c 仍在等待 */
+    assert.deepStrictEqual(
+      { nodeCount: list[1].nodeCount, running: list[1].running, waiting: list[1].waiting },
+      { nodeCount: 3, running: 2, waiting: 1 });
+    assert.deepStrictEqual({ nodeCount: list[0].nodeCount, running: list[0].running }, { nodeCount: 1, running: 1 });
+    /* nodePatch 让被修改的工作流重新排到最前 */
+    orch.dispatch(`apiVersion: codex.dsh/v1\nkind: nodePatch\nworkflowId: ${first}\nnodes:\n  - id: c\n    title: 汇总（改）`);
+    assert.strictEqual(orch.list()[0].workflowId, first);
+    await waitFor(orch, first, 'c', 'completed');
+    await waitFor(orch, second, 'solo', 'completed');
+    assert.deepStrictEqual(orch.list().map(w => w.state), ['completed', 'completed']);
+    assert.strictEqual(orch.list()[0].completed, 3);
+    console.log('✓ 工作流清单 list() 排序与统计');
+  }
+
+  /* 9. 缺省模型与失败原因回传 */
+  {
+    const { DEFAULT_MODEL } = require('./defaults.js');
+    assert.notStrictEqual(DEFAULT_MODEL, 'gpt-5-codex', '缺省模型不得是订阅登录下被拒的 slug');
+
+    /* 节点未写 model → 用 runner 声明的缺省；写了 model → 以节点为准 */
+    const orch = new Orchestrator({ ...createMockRunner(), defaultModel: 'gpt-test-default' });
+    const { workflowId } = orch.dispatch(BASE_YAML);
+    await waitFor(orch, workflowId, 'c', 'completed');
+    const nodes = orch.snapshot(workflowId).nodes;
+    assert.strictEqual(nodes.find(n => n.id === 'a').model, 'gpt-test-default');
+
+    const pinned = new Orchestrator({ ...createMockRunner(), defaultModel: 'gpt-test-default' });
+    const second = pinned.dispatch(BASE_YAML.replace('prompt: 执行任务 A', 'prompt: 执行任务 A\n    model: gpt-test-pinned'));
+    await waitFor(pinned, second.workflowId, 'c', 'completed');
+    assert.strictEqual(pinned.snapshot(second.workflowId).nodes.find(n => n.id === 'a').model, 'gpt-test-pinned');
+
+    /* runner 只在返回值里报失败、不抛错时，失败原因必须落到 node.error（可诊断） */
+    const failing = new Orchestrator({
+      defaultModel: 'gpt-test-default',
+      async run(def, cb) {
+        cb.onSessionId('sess_x');
+        cb.onItem({ type: 'error', id: 'item_error', message: '模型不受支持' });
+        return { status: 'failed', finalMessage: null, usage: null, failure: '模型不受支持' };
+      },
+    });
+    const third = failing.dispatch('apiVersion: codex.dsh/v1\nkind: workflow\ntitle: x\nnodes:\n  - id: a\n    prompt: x');
+    await waitFor(failing, third.workflowId, 'a', 'failed');
+    assert.strictEqual(failing.snapshot(third.workflowId).nodes[0].error, '模型不受支持');
+    console.log('✓ 缺省模型解析与失败原因回传');
+  }
+
+  console.log('\n全部测试通过');
+})().catch(error => { console.error(error); process.exit(1); });

package/server/persistence.js

@@ -0,0 +1,124 @@
+/* ============================================================
+ * persistence.js — workflow 状态落盘（append-only JSONL）
+ *
+ * 动机：原先 workflow 只活在 Orchestrator 进程内存里，进程一重启
+ * dispatch 过的 workflow 就永久消失，`/api/state?workflowId=` 只能
+ * 返回「workflow 不存在」——调用者无法区分「从没派发过」和
+ * 「派发过但被重启清掉了」。这是真实踩到的坑。
+ *
+ * 设计取舍：
+ * - append-only JSONL：崩溃时最多丢最后一行，不需要原子重写整个文件。
+ * - 内存仍是权威（Map），磁盘只是**回读补充**：snapshot 未命中内存时
+ *   才回读，命中时零 I/O 开销，不用改调度器语义。
+ * - 只持久化「查询需要」的字段，不落 abort controller / runner 句柄。
+ * - 写入失败绝不打断编排：记一条 stderr 警告后继续（磁盘满/权限问题
+ *   不应该让正在跑的 workflow 失败）。
+ * ============================================================ */
+'use strict';
+
+const { appendFileSync, readFileSync, mkdirSync, existsSync, renameFileSync } = require('node:fs');
+const { dirname, join } = require('node:path');
+
+/* 落盘时保留的节点字段（与 snapshot() 输出对齐） */
+const NODE_FIELDS = [
+  'id', 'title', 'prompt', 'model', 'cwd', 'sandboxMode', 'approvalPolicy', 'reasoningEffort', 'dependsOn', 'timeoutS', 'onFailure', 'status', 'sessionId',
+  'items', 'turns', 'activeTurnId', 'finalMessage', 'usage', 'error', 'startedAt', 'finishedAt',
+];
+
+function pickNode(node) {
+  const out = {};
+  for (const field of NODE_FIELDS) if (node[field] !== undefined) out[field] = node[field];
+  return out;
+}
+
+class Persistence {
+  /**
+   * @param {string} file  JSONL 路径
+   * @param {{ enabled?: boolean, warn?: (msg: string) => void }} [options]
+   */
+  constructor(file, { enabled = true, warn = msg => process.stderr.write(`[codex-orchestrate] ${msg}\n`) } = {}) {
+    this.file = file;
+    this.enabled = enabled;
+    this.warn = warn;
+    this.broken = false;      // 写失败过一次就不再反复报错
+    if (this.enabled) {
+      try { mkdirSync(dirname(file), { recursive: true }); }
+      catch (error) { this.disable(`无法创建持久化目录：${error.message}`); }
+    }
+  }
+
+  disable(reason) {
+    this.enabled = false;
+    if (!this.broken) { this.broken = true; this.warn(`持久化已关闭（${reason}）`); }
+  }
+
+  /**
+   * 追加一条记录。record 形如：
+   *   { type: 'workflow', workflowId, title, goal, concurrency, createdAt, seq }
+   *   { type: 'node', workflowId, node: {...} }
+   *   { type: 'nodeDelete', workflowId, nodeId }
+   */
+  append(record) {
+    if (!this.enabled) return;
+    try {
+      appendFileSync(this.file, JSON.stringify({ ...record, at: new Date().toISOString() }) + '\n', { mode: 0o600 });
+    } catch (error) {
+      this.disable(`写入失败：${error.message}`);
+    }
+  }
+
+  /**
+   * 回读磁盘，重建 workflowId -> { ...workflow, nodes: Map } 视图。
+   * 后写的覆盖先写的（节点状态是「最新一次」语义）。
+   * 文件不存在 / 完全不可读时返回空 Map，绝不抛错。
+   */
+  load() {
+    const workflows = new Map();
+    if (!this.enabled || !existsSync(this.file)) return workflows;
+    let text;
+    try { text = readFileSync(this.file, 'utf8'); }
+    catch (error) { this.warn(`回读失败：${error.message}`); return workflows; }
+
+    for (const line of text.split('\n')) {
+      if (!line.trim()) continue;
+      let record;
+      /* 半行/损坏行直接跳过：append-only 的文件尾部可能被截断，
+       * 一行坏数据不应该让整个历史不可读。 */
+      try { record = JSON.parse(line); } catch { continue; }
+      if (!record?.workflowId) continue;
+
+      if (record.type === 'workflow') {
+        const prev = workflows.get(record.workflowId);
+        workflows.set(record.workflowId, {
+          id: record.workflowId,
+          title: record.title ?? prev?.title ?? '',
+          goal: record.goal ?? prev?.goal ?? '',
+          concurrency: record.concurrency ?? prev?.concurrency ?? 3,
+          cwd: record.cwd ?? prev?.cwd ?? null,
+          createdAt: record.createdAt ?? prev?.createdAt ?? null,
+          seq: record.seq ?? prev?.seq ?? 0,
+          nodes: prev?.nodes ?? new Map(),
+        });
+      } else if (record.type === 'node' && record.node?.id) {
+        const wf = workflows.get(record.workflowId);
+        if (!wf) continue;               // node 先于 workflow 出现：丢弃
+        wf.nodes.set(record.node.id, { ...wf.nodes.get(record.node.id), ...record.node });
+      } else if (record.type === 'nodeDelete' && record.nodeId) {
+        /* 删除必须作为顺序敏感的墓碑进入日志；否则重启回放时，更早的
+         * node 记录会让已删除节点“复活”。后续重新创建同 id 的 node
+         * 仍可通过更晚的 node 记录自然覆盖墓碑。 */
+        workflows.get(record.workflowId)?.nodes.delete(record.nodeId);
+      }
+    }
+    return workflows;
+  }
+
+  /** 磁盘上一个 workflow 的节点是否已全部终态（用于判断 seq 复用是否安全） */
+  static isTerminal(nodes) {
+    const list = nodes instanceof Map ? [...nodes.values()] : nodes || [];
+    if (!list.length) return false;
+    return list.every(n => ['completed', 'failed', 'cancelled'].includes(n.status));
+  }
+}
+
+module.exports = { Persistence, pickNode, NODE_FIELDS };