minimal-agent 0.9.0 → 0.10.0

package/plugins/workflow-runner/src/workflowState.js

@@ -7,71 +7,261 @@
  *  核心变更：
  *    - init() 不再无条件清空，而是先读旧状态 → 判定任务身份 → 分发 4 种模式
  *    - 新增 checkpoints/ 目录记录每步完成状态和 capture 变量
- *    - 新增 artifacts/ 目录管理产出物
+ *    - 产物生命周期：current.json.artifacts 记录工作流【声明】的产物路径（相对 cwd，
+ *      来自 yaml 的 def.artifacts / step.artifacts）；new-task 时据此清旧产物（如旧 PLAN.md），
+ *      completed 时据此报实际存在的产物。不再用从不写入的 artifacts/ 子目录。
  *    - resume 模式时回放已完成步骤的 capture 到 vars 中
+ *    - completed 检测：成功后 archive() 把目录改名 .done，故 init() 在活动目录缺失时
+ *      回退读 .done/current.json（status=done + taskId 匹配 → completed），修活「completed 死代码」。
  *
- *  目录结构：
- *    <cwd>/.minimal-agent-workflow/
- *      ├── current.json    # { name, taskId, status, startedAt, lastFailedStep?, lastError? }
- *      ├── inputs.json     # 用户传入的 inputs 快照
- *      ├── vars.json       # 最后一次成功 step 后的 VarStack.snapshot()
- *      ├── progress.md     # 时间戳追加的 step 完成日志
- *      ├── checkpoints/    # 每步一个 JSON：{ stepId, completedAt, output, captures, varsSnapshot }
- *      └── artifacts/      # 产出物文件（PLAN.md 等）
+ *  目录结构（E6：按 workflow 名隔离，跨工作流互不可见/互不干扰）：
+ *    <cwd>/.minimal-agent-workflow/<name>/   （成功后改名为 <name>.done/）
+ *      ├── current.json     # { name, taskId, status, startedAt, artifacts?, lastFailedStep?, lastError? }
+ *      ├── inputs.json      # 用户传入的 inputs 快照
+ *      ├── vars.json        # 最后一次成功 step 后的 VarStack.snapshot()
+ *      ├── progress.md      # 时间戳追加的 step 完成日志
+ *      ├── supplements.json # 贯穿补充要求（pause 反馈/澄清结论，resume 恢复进锚定）
+ *      └── checkpoints/     # 每步一个 JSON：{ stepId, completedAt, output, captures, varsSnapshot }
+ *                           #   顶层步用原名；顶层 loop 内步用复合名 loopId@@迭代号@@stepId
+ *                           #   （resume 可恢复到迭代中间，见 scanLoopResume）
+ *    /new 按 .minimal-agent 前缀清理父目录，行为不变。
  * ============================================================
  */
+import { createHash } from 'node:crypto';
 import { mkdir, writeFile, appendFile, rm, rename, readFile, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { computeTaskId } from './taskIdentity.js';
-const STATE_DIR = '.minimal-agent-workflow';
+import { computeTaskId, extractGoal, workflowStateDir, } from './taskIdentity.js';
 const DONE_SUFFIX = '.done';
 const CHECKPOINTS_DIR = 'checkpoints';
-const ARTIFACTS_DIR = 'artifacts';
+const SUPPLEMENTS_FILE = 'supplements.json';
+/**
+ * 顶层 loop 内步的复合 checkpoint 文件名分隔符。
+ * 选 '@@'：yaml step id 习惯用 [a-z0-9_]，不会撞；且对文件系统安全。
+ */
+export const LOOP_CP_SEP = '@@';
+/** 复合 checkpoint 名：<loopId>@@<迭代号>@@<stepId>（runner 的 CpScope 与本模块扫描共用）。 */
+export function loopCheckpointName(loopId, iteration, stepId) {
+    return `${loopId}${LOOP_CP_SEP}${iteration}${LOOP_CP_SEP}${stepId}`;
+}
+/** 解析复合 checkpoint 文件名；非复合名（普通顶层步）返回 null。 */
+function parseLoopCheckpointName(name) {
+    const parts = name.split(LOOP_CP_SEP);
+    if (parts.length !== 3)
+        return null;
+    const iteration = Number(parts[1]);
+    if (!Number.isInteger(iteration) || iteration < 0)
+        return null;
+    return { loopId: parts[0], iteration, stepId: parts[2] };
+}
+/**
+ * 工作流定义的**结构指纹**：步骤 id + 执行形态 + 嵌套块（then/else/do）骨架的 hash。
+ * prompt 文案、args、condition 等内容字段不参与——改提示词/参数不应作废断点；
+ * 改结构（增删步/换 id/换类型/调嵌套）才作废：resume 的恢复点是**索引**、循环断点是
+ * 复合名（loopId@@迭代@@stepId），结构一变旧 checkpoint 就对不上，按旧断点续跑会错跳步
+ * （曾真实发生：plan.yaml v3→v4 重构后同 goal 重跑提示「从第 2 步续跑」，跳过的步与
+ * 新结构毫无对应关系）。current.json 记录运行时的指纹，init 同任务重跑时比对。
+ */
+export function computeDefFingerprint(steps) {
+    const skeleton = (list) => (list ?? []).map((s) => ({
+        id: s.id,
+        kind: s.type ??
+            (s.tool ? 'tool' : s.skill ? 'skill' : s.agent ? 'agent' : s.llm ? 'llm' : '?'),
+        then: s.then ? skeleton(s.then) : undefined,
+        else: s.else ? skeleton(s.else) : undefined,
+        do: s.do ? skeleton(s.do) : undefined,
+    }));
+    return createHash('sha1')
+        .update(JSON.stringify(skeleton(steps)))
+        .digest('hex')
+        .slice(0, 16);
+}
 export class WorkflowState {
     dir;
-    constructor(workingDir) {
-        this.dir = join(workingDir, STATE_DIR);
+    workingDir;
+    constructor(workingDir, workflowName) {
+        this.workingDir = workingDir;
+        // 按 workflow 名隔离（与 taskIdentity.computeTaskId 读的是同一权威路径）
+        this.dir = workflowStateDir(workingDir, workflowName);
     }
     /**
      * 初始化工作流状态 —— 核心入口，返回恢复信息。
      *
      * 4 种模式：
      *   1. fresh      — 首次运行此工作流（无旧状态）
-     *   2. new-task  — 不同任务（hash 或时间窗口不匹配）→ 清理旧产物后全新开始
+     *   2. new-task  — 不同任务 → 清理旧产物后全新开始
      *   3. completed — 同一任务已完成 → 返回产物列表
      *   4. resume    — 同一任务未完成 → 扫描 checkpoint 决定恢复点
+     *
+     * hash 相等 = 同任务（权威信号，与时间无关）。hash 不等且旧任务【未完成】时
+     * 不再一票否决 new-task：若提供了 arbitrate（语义仲裁器，见 taskIdentity.ts），
+     * 由它判定新输入是「旧任务的延续指令（如"继续"）→ resume」还是「全新任务 → new-task」。
      */
-    async init(name, inputs, steps) {
-        // 1. 计算当前任务的 identity
-        const workingDir = this.dir.replace(`/${STATE_DIR}`, '') || process.cwd();
-        const identity = computeTaskId(name, inputs, workingDir);
-        // 2. 尝试读取旧 current.json
+    async init(name, inputs, steps, 
+    // 跨次重跑回退步数（= WorkflowDef.self_heal.backoff），runWorkflow 注入；缺省 1。
+    selfHealBackoff = 1, 
+    // 工作流【声明】的产物路径（相对 cwd，= def.artifacts + step.artifacts），runWorkflow 注入。
+    declaredArtifacts = [], 
+    // 语义仲裁器（hash 不等 + 旧任务未完成时的二审），runWorkflow 注入；缺省直接 new-task。
+    arbitrate) {
+        // 1. 计算当前任务的 identity（goal 内容 hash 是唯一权威信号）
+        // 与本次定义的结构指纹（resume 兼容性信号：yaml 结构变了旧断点即作废）
+        const identity = computeTaskId(name, inputs, this.workingDir);
+        const fp = computeDefFingerprint(steps);
+        // 2. 尝试读取活动目录的 current.json
         const oldState = await this.readCurrentState();
         if (!oldState) {
-            // 模式 1: fresh —— 无旧状态，首次运行
-            await this.cleanSlate(name, inputs, identity.hash);
-            return { mode: 'fresh', startFrom: 0 };
+            // 活动目录无状态 —— 可能是「上次成功已归档到 .done」。读归档判定 completed / 不同 goal 新任务。
+            const archived = await this.readArchivedState();
+            if (archived && archived.name === name) {
+                if (archived.taskId === identity.hash) {
+                    // 模式 3: completed —— 同任务此前已成功（报实际存在的声明产物）
+                    return {
+                        mode: 'completed',
+                        artifacts: this.existingArtifacts(archived.artifacts ?? declaredArtifacts),
+                    };
+                }
+                // 同名 workflow 但 goal 不同 → 全新任务：清旧归档声明产物后 fresh
+                // （legacy 归档无 artifacts 字段时用本次声明清单兜底——同名 workflow 的声明产物
+                //   语义稳定，旧任务的产物路径与本次一致的概率极高，残留比误删危害大）
+                const cleaned = await this.cleanupDeclaredArtifacts(archived.artifacts ?? declaredArtifacts);
+                await this.cleanSlate(name, inputs, identity.hash, declaredArtifacts, fp);
+                return {
+                    mode: 'new-task',
+                    startFrom: 0,
+                    cleanedArtifacts: [
+                        ...cleaned,
+                        ...(await this.cleanupStaleDeclared(declaredArtifacts)),
+                    ],
+                };
+            }
+            // 模式 1: fresh —— 活动 + 归档都没有，首次运行。
+            // 声明产物若已存在于磁盘 = 残留孤儿（如 /new 删状态目录后的旧 PLAN.md，
+            // artifacts 清单随 current.json 一起被删，引擎无从知道它属于谁）。
+            // 用户约定：全新任务开始时清理残留与中间文件——删除范围**仅限本工作流
+            // 声明的产物**（与运行自身对它们的覆盖写权限一致，不碰用户其他文件）。
+            await this.cleanSlate(name, inputs, identity.hash, declaredArtifacts, fp);
+            return {
+                mode: 'fresh',
+                startFrom: 0,
+                cleanedArtifacts: await this.cleanupStaleDeclared(declaredArtifacts),
+            };
         }
-        // 3. 用 computeTaskId 的 isSameTask 结果判断
+        // 3. 有活动状态（上次中断 / 失败 / 进行中，未归档）—— 用 hash 判同/异任务
         if (!identity.isSameTask) {
-            // 模式 2: new-task —— 不同任务，清理旧产物后全新开始
-            const artifacts = await this.listArtifacts();
-            await this.cleanupArtifacts(artifacts);
-            await this.cleanSlate(name, inputs, identity.hash);
-            return { mode: 'new-task', cleanedArtifacts: artifacts, startFrom: 0 };
+            // hash 不等 + 同名 workflow + 旧任务未完成 → 语义仲裁二审：
+            // 新输入可能是「继续」这类延续指令（goal 文本必然与旧任务不同，按旧规则
+            // 会被误判 new-task 把没做完的产物清掉重开）。不同名 workflow / 旧任务已
+            // 完成 / 未提供仲裁器 → 维持 new-task。仲裁器自身抛错也兜底 new-task。
+            if (arbitrate &&
+                identity.reason === 'hash_diff' &&
+                oldState.name === name &&
+                oldState.status !== 'done' &&
+                // 定义结构已变（或 legacy 无指纹）→ 旧断点不可续，仲裁 resume 无意义，
+                // 跳过仲裁直接走 new-task
+                oldState.defFingerprint === fp) {
+                const prevGoal = extractGoal((await this.readInputs()) ?? {});
+                const newGoal = extractGoal(inputs);
+                let verdict = 'new';
+                try {
+                    verdict = await arbitrate({
+                        workflowName: name,
+                        prevGoal,
+                        newGoal,
+                        completedStepIds: await this.scanCheckpoints(steps),
+                        totalSteps: steps.length,
+                        artifacts: oldState.artifacts ?? [],
+                    });
+                }
+                catch {
+                    verdict = 'new';
+                }
+                if (verdict === 'resume') {
+                    // 延续旧任务：状态目录原样保留（taskId 仍是旧 goal 的 hash——
+                    // 下次再输「继续」依然 hash 不等 → 再次仲裁快路径命中，语义自洽）。
+                    const info = await this.buildResumeInfo(oldState, steps, selfHealBackoff);
+                    info.prevGoal = prevGoal;
+                    info.supplementaryGoal = newGoal;
+                    return info;
+                }
+            }
+            // 模式 2: new-task —— 不同任务，清旧声明产物 + 旧状态后全新开始。
+            // legacy 状态文件无 artifacts 字段时：仅当同名 workflow 用本次声明清单兜底
+            //（不同名 workflow 的产物不是我们的，不能殃及）。
+            const cleaned = await this.cleanupDeclaredArtifacts(oldState.artifacts ?? (oldState.name === name ? declaredArtifacts : []));
+            await this.cleanSlate(name, inputs, identity.hash, declaredArtifacts, fp);
+            return {
+                mode: 'new-task',
+                startFrom: 0,
+                cleanedArtifacts: [
+                    ...cleaned,
+                    ...(await this.cleanupStaleDeclared(declaredArtifacts)),
+                ],
+            };
         }
-        // 4. 同一任务 —— 检查完成状态
+        // 4. 同一任务 —— 检查完成状态（兜底：正常成功会 archive，故活动目录 done 少见）
         if (oldState.status === 'done') {
-            // 模式 3: completed —— 同一任务已完成
-            const artifacts = await this.listArtifacts();
-            return { mode: 'completed', artifacts };
+            return {
+                mode: 'completed',
+                artifacts: this.existingArtifacts(oldState.artifacts ?? declaredArtifacts),
+            };
         }
-        // 5. 模式 4: resume —— 同一任务未完成，扫描 checkpoint 决定恢复点
+        // 4.5 定义结构变更守卫：同任务但 yaml 结构改过（增删步/换 id/调嵌套）——
+        // resume 恢复点是索引、循环断点是复合名，结构一变旧 checkpoint 全对不上，
+        // 按旧断点续跑会错跳步（曾真实发生：plan v3→v4 重构后同 goal 重跑
+        // 「从第 2 步续跑」，用户困惑是 bug 还是残留）。旧现场作废、全新开始，
+        // runner 经 defChanged 旗标向用户明示。legacy 状态（无 defFingerprint
+        // 字段）无从验证兼容性，同样按变更处理（一次性升级成本，安全优先）。
+        if (oldState.defFingerprint !== fp) {
+            const cleaned = await this.cleanupDeclaredArtifacts(oldState.artifacts ?? declaredArtifacts);
+            await this.cleanSlate(name, inputs, identity.hash, declaredArtifacts, fp);
+            return {
+                mode: 'new-task',
+                startFrom: 0,
+                defChanged: true,
+                cleanedArtifacts: [
+                    ...cleaned,
+                    ...(await this.cleanupStaleDeclared(declaredArtifacts)),
+                ],
+            };
+        }
+        // 5. 模式 4: resume —— 同一任务未完成，扫描 checkpoint 决定恢复点。
+        return this.buildResumeInfo(oldState, steps, selfHealBackoff);
+    }
+    /**
+     * 构建 resume 信息：扫描 checkpoint 决定恢复点 + 加载 capture 回放数据。
+     * 回退步数由 WorkflowDef.self_heal.backoff 经 runWorkflow 传入（缺省 1）。
+     * 同 goal resume（hash 相等）与仲裁延续 resume（hash 不等但判定延续）共用。
+     */
+    async buildResumeInfo(oldState, steps, selfHealBackoff) {
         const completedSteps = await this.scanCheckpoints(steps);
-        const selfHealBackoff = 1; // 默认回退 1 步，runner 可通过 WorkflowDef.self_heal.backoff 覆盖
-        const recoveryStart = Math.max(0, completedSteps.length - selfHealBackoff);
+        // 恢复点 = 最后一个已完成步在 steps[] 中的【索引】+1 - backoff。
+        // 不能用 checkpoint【计数】当索引：when=false 跳过步 / pause 步不记 checkpoint，
+        // 计数会低估位置 → resume 重复执行已跑过的步（对非幂等 tool 步有实害）。
+        // 已完成步是连续前缀时索引法与计数法等价（向后兼容）。
+        const lastCompletedId = completedSteps[completedSteps.length - 1];
+        const lastIdx = lastCompletedId !== undefined
+            ? steps.findIndex((s) => s.id === lastCompletedId)
+            : -1;
+        const recoveryStart = Math.max(0, lastIdx + 1 - selfHealBackoff);
         // 加载 capturedVars 用于回放
         const capturedVars = await this.loadAllCaptures(completedSteps);
+        // 循环级恢复：中断发生在某顶层 loop 的迭代中间（该 loop 自身无完成 checkpoint、
+        // 但有复合迭代 checkpoint）→ 顶层直接定位到该 loop、迭代内续跑，
+        // 不再整条循环从头重来（plan.yaml 95% 的工作都在一个 loop 里，此前粒度形同虚设）。
+        const loopResume = await this.scanLoopResume(steps, completedSteps, selfHealBackoff);
+        if (loopResume) {
+            return {
+                mode: 'resume',
+                startFrom: loopResume.loopIndex,
+                completedStepIds: completedSteps,
+                failedStep: oldState.lastFailedStep,
+                recoveryStart: loopResume.loopIndex,
+                lastError: oldState.lastError,
+                capturedVars,
+                loopResume,
+            };
+        }
         return {
             mode: 'resume',
             startFrom: recoveryStart,
@@ -82,6 +272,97 @@ export class WorkflowState {
             capturedVars,
         };
     }
+    /**
+     * 扫描复合迭代 checkpoint（loopId@@iter@@stepId），产出进行中循环的恢复信息。
+     * 候选条件：顶层 type=loop 步 + 自身无完成 checkpoint（completedTopIds 不含它）。
+     * 多个候选（罕见，前一循环中断后又跑到后一循环）取顶层索引最大者（最远进度）。
+     */
+    async scanLoopResume(steps, completedTopIds, selfHealBackoff) {
+        const cpDir = join(this.dir, CHECKPOINTS_DIR);
+        let files;
+        try {
+            files = await readdir(cpDir);
+        }
+        catch {
+            return null;
+        }
+        const completedTop = new Set(completedTopIds);
+        // loopId → iteration → stepId 集合
+        const byLoop = new Map();
+        for (const f of files) {
+            if (!f.endsWith('.json'))
+                continue;
+            const parsed = parseLoopCheckpointName(f.replace(/\.json$/, ''));
+            if (!parsed)
+                continue;
+            let iters = byLoop.get(parsed.loopId);
+            if (!iters)
+                byLoop.set(parsed.loopId, (iters = new Map()));
+            let ids = iters.get(parsed.iteration);
+            if (!ids)
+                iters.set(parsed.iteration, (ids = new Set()));
+            ids.add(parsed.stepId);
+        }
+        if (byLoop.size === 0)
+            return null;
+        let best = null;
+        for (const [loopId, iters] of byLoop) {
+            const loopIndex = steps.findIndex((s) => s.id === loopId && s.type === 'loop');
+            if (loopIndex === -1)
+                continue; // yaml 改动后的孤儿 checkpoint，忽略
+            if (completedTop.has(loopId))
+                continue; // 该循环已整体完成
+            const loopDef = steps[loopIndex];
+            const doSteps = loopDef.do ?? [];
+            const validInner = new Set(doSteps.map((s) => s.id));
+            const iteration = Math.max(...iters.keys());
+            const innerIds = [...(iters.get(iteration) ?? [])]
+                .filter((id) => validInner.has(id))
+                .sort((a, b) => doSteps.findIndex((s) => s.id === a) - doSteps.findIndex((s) => s.id === b));
+            if (innerIds.length === 0)
+                continue;
+            const lastInnerIdx = doSteps.findIndex((s) => s.id === innerIds[innerIds.length - 1]);
+            const innerStartFrom = Math.max(0, lastInnerIdx + 1 - selfHealBackoff);
+            // 中断时刻最近的 vars 快照（迭代内最后一个完成步的 checkpoint）
+            let lastVarsSnapshot;
+            try {
+                const raw = await readFile(join(cpDir, `${loopCheckpointName(loopId, iteration, innerIds[innerIds.length - 1])}.json`), 'utf-8');
+                lastVarsSnapshot = JSON.parse(raw).varsSnapshot;
+            }
+            catch {
+                // 快照读失败不阻断：仍可定位迭代，变量靠顶层 capture 回放兜底
+            }
+            const candidate = {
+                loopId,
+                loopIndex,
+                iteration,
+                innerStartFrom,
+                completedInnerIds: innerIds,
+                lastVarsSnapshot,
+            };
+            if (!best || candidate.loopIndex > best.loopIndex)
+                best = candidate;
+        }
+        return best;
+    }
+    // ---- 公共方法：贯穿补充要求持久化（goalSupplements，runner 写/读） ----
+    /** 追加一条用户补充要求到 supplements.json（resume 跨进程不丢）。 */
+    async appendSupplement(text) {
+        const list = await this.readSupplements();
+        list.push(text);
+        await writeFile(join(this.dir, SUPPLEMENTS_FILE), JSON.stringify(list, null, 2), 'utf-8').catch(() => { });
+    }
+    /** 读取已累积的补充要求列表（无文件 / 解析失败返回 []）。 */
+    async readSupplements() {
+        try {
+            const raw = await readFile(join(this.dir, SUPPLEMENTS_FILE), 'utf-8');
+            const parsed = JSON.parse(raw);
+            return Array.isArray(parsed) ? parsed.filter((x) => typeof x === 'string') : [];
+        }
+        catch {
+            return [];
+        }
+    }
     // ---- 公共方法：checkpoint / 失败 / 完成 ----
     /** 记录单个步骤成功完成（含 capture 变量和 vars 快照） */
     async recordCheckpoint(stepId, output, captures, varsSnapshot) {
@@ -180,24 +461,22 @@ export class WorkflowState {
         }
         return result;
     }
-    // ---- 公共方法：产物管理 ----
-    /** 列出 artifacts/ 目录中的产物文件路径 */
-    async listArtifacts() {
-        const artDir = join(this.dir, ARTIFACTS_DIR);
-        try {
-            const files = await readdir(artDir);
-            return files.filter((f) => f !== '.gitkeep');
-        }
-        catch {
-            return [];
-        }
-    }
-    /** 清理指定的产物文件 */
-    async cleanupArtifacts(paths) {
-        const artDir = join(this.dir, ARTIFACTS_DIR);
+    // ---- 私有方法：声明式产物生命周期 ----
+    /** 删除工作流【声明】的产物文件（相对 cwd），用于 new-task 清理旧任务残留（如旧 PLAN.md）。
+     *  仅删工作流自己声明的产物、仅 force-rm 文件，scoped 安全。返回清理过的路径列表。 */
+    async cleanupDeclaredArtifacts(paths) {
         for (const p of paths) {
-            await rm(join(artDir, p), { force: true }).catch(() => { });
+            await rm(join(this.workingDir, p), { force: true }).catch(() => { });
         }
+        return paths;
+    }
+    /** 从声明产物路径里过滤出 cwd 下【实际存在】的文件（completed 报真实产物用）。 */
+    existingArtifacts(paths) {
+        return paths.filter((p) => existsSync(join(this.workingDir, p)));
+    }
+    /** 清理【实际存在】的本次声明产物（fresh/new-task 启动时清残留孤儿），返回真正删掉的路径。 */
+    async cleanupStaleDeclared(declaredArtifacts) {
+        return this.cleanupDeclaredArtifacts(this.existingArtifacts(declaredArtifacts));
     }
     // ---- 公共方法：归档与清理（保持原有签名兼容） ----
     /**
@@ -225,21 +504,32 @@ export class WorkflowState {
         await rm(this.dir + DONE_SUFFIX, { recursive: true, force: true }).catch(() => { });
     }
     // ---- 私有方法 ----
-    /** 创建全新的空白状态目录（含 checkpoints/ 和 artifacts/ 子目录） */
-    async cleanSlate(name, inputs, taskId) {
+    /** 创建全新的空白状态目录（含 checkpoints/ 子目录），并记录声明产物清单。 */
+    async cleanSlate(name, inputs, taskId, declaredArtifacts = [], defFingerprint) {
         await this.cleanup();
         await mkdir(this.dir, { recursive: true });
         await mkdir(join(this.dir, CHECKPOINTS_DIR), { recursive: true });
-        await mkdir(join(this.dir, ARTIFACTS_DIR), { recursive: true });
         await this.writeCurrent({
             name,
             taskId,
             status: 'running',
             startedAt: new Date().toISOString(),
+            artifacts: declaredArtifacts,
+            defFingerprint,
         });
         await writeFile(join(this.dir, 'inputs.json'), JSON.stringify(inputs, null, 2), 'utf-8');
         await writeFile(join(this.dir, 'progress.md'), `# ${name}\n\n`, 'utf-8');
     }
+    /** 读取旧任务的 inputs.json（仲裁时取旧 goal 用），失败返回 null */
+    async readInputs() {
+        try {
+            const raw = await readFile(join(this.dir, 'inputs.json'), 'utf-8');
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
     /** 读取 current.json，解析失败或文件不存在返回 null */
     async readCurrentState() {
         try {
@@ -250,6 +540,16 @@ export class WorkflowState {
             return null;
         }
     }
+    /** 读取归档目录（.done）的 current.json，用于 completed 检测（成功后 dir 被 archive 改名）。 */
+    async readArchivedState() {
+        try {
+            const raw = await readFile(join(this.dir + DONE_SUFFIX, 'current.json'), 'utf-8');
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
     /** 写入 current.json */
     async writeCurrent(data) {
         await writeFile(join(this.dir, 'current.json'), JSON.stringify(data, null, 2), 'utf-8');

package/skills/ai-image/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: ai-image
+description: 当用户说"生成图片"、"画一张图"、"配图"、"插画/插图"、"AI 生图"、"图生图"、"参考这张图改图/扩图/增强"或者你判断出客户实际上的要求等价于用AI生成或编辑图片时使用（OPENAI_IMAGE_* 配置那一路）。支持文生图和带输入图的图生图/参考图生成，支持指定宽高比。与 image-gen-openrouter（OPENROUTER_API_KEY）是两套独立机制，按用户配置选用，别混用。
+---
+
+# ai-image —— 文生图 / 图生图
+
+> 生图能力住在本技能的脚本 `scripts/generate.mjs`（零依赖、裸 fetch、自己落盘），
+> 走 `OPENAI_IMAGE_*` 配置。工作流批量生图优先用内核 `GenerateImage` 工具（无 Bash 120s 帽），
+> 手动调试或单张生成时用 Bash 调脚本即可。
+> 如果用户明确点名 OpenRouter / nano banana 且用 `OPENROUTER_API_KEY`，那是另一个技能
+> `image-gen-openrouter`（curl 版），别混用。
+
+## 怎么干
+
+用 **Bash 工具**跑本技能目录下的脚本（**用 node 跑，不是 bun**）：
+
+```bash
+node "<本技能目录>/scripts/generate.mjs" \
+  --prompt "A serene mountain lake at sunrise, soft mist, photorealistic, wide cinematic shot" \
+  --out ./assets/lake.png \
+  --aspect 16:9
+```
+
+图生图 / 参考图增强：
+
+```bash
+node "<本技能目录>/scripts/generate.mjs" \
+  --prompt "Extend this product photo into a clean 16:9 hero background, preserve the main product, premium soft light, no text, no logos" \
+  --input-image ./assets/source.png \
+  --out ./assets/source_enhanced.png \
+  --aspect 16:9
+```
+
+批量 PPT 配图不要让 agent 循环手写 Bash；在 workflow 中优先调用 `GenerateImage` 工具。手动调试时，
+让计划脚本读取 `img_plan.json` 确定性执行：
+
+```bash
+node "<本技能目录>/scripts/generate_from_plan.mjs" \
+  --plan ./build/img_plan.json \
+  --assets ./build/assets \
+  --timeout-ms 600000 \
+  --size 1K
+```
+
+- `<本技能目录>` = 系统提示「可用技能」列表里本技能（ai-image）后面给出的**绝对目录**，直接拼 `/scripts/generate.mjs` 或 `/scripts/generate_from_plan.mjs`。
+- 路径含空格时给整条路径加引号。
+- **调 Bash 时务必把 `timeout` 设成 `600000`（10 分钟）**：图像模型很慢（一张常要 1 分钟、重模型几分钟），
+  Bash 默认只给 120s，会把还没出图的进程当超时掐断。脚本运行时会往 stderr 打 `[ai-image] attempt k/N …` 进度，
+  看到它就说明在正常等待、不是卡死。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--prompt` | ✅ | 图片提示词。**英文通常效果更好**；用户给的是中文就保留，不要主动翻译。越具体（主体/风格/光线/构图/负空间）越好。 |
+| `--out` | ✅ | 落盘路径。绝对或相对（相对当前工作目录）。**建议 `.png` 后缀**。父目录自动创建。 |
+| `--aspect` | ⬜ | 宽高比，如 `16:9` / `9:16` / `4:5` / `1:1`。脚本会同时①发 provider 原生 `image_config.aspect_ratio`、②在提示词里追加构图提示，双保险。 |
+| `--size` | ⬜ | 分辨率档，如 `1K` / `2K` / `4K`（部分模型/端点支持；不支持则忽略）。 |
+| `--model` | ⬜ | 临时覆盖 `OPENAI_IMAGE_MODEL`（想换更快/更便宜的模型试一张时用）。 |
+| `--input-image` | ⬜ | 输入参考图，本地路径 / URL / data URL 均可。本地图片会转成 `data:image/...;base64,...`。用于图生图、扩图、换背景、比例修复、质感增强。 |
+
+成功后脚本在 stdout 打**一行**：`saved: <path> (model=<m>, bytes=<n>, aspect=<a>)`；失败信息走 stderr，退出码非 0。
+
+## 注意事项
+
+- **先确认配置**：脚本需要 `.env`/环境里有 `OPENAI_IMAGE_BASE_URL` / `OPENAI_IMAGE_API_KEY` / `OPENAI_IMAGE_MODEL`。
+  缺了脚本以**退出码 3** + 明确文案报错——如实转告用户补好配置再试，别瞎重试。
+- **协议自动选（无需关心）**：脚本支持两套生图协议并按 provider 自动切——OpenRouter 的多模态图模型走
+  `chat/completions`（图在 `message.images[]`，输入图作为 `image_url` 内容块）；OpenAI / Azure / **火山方舟 Seedream** 走官方 Images API
+  `images/generations`（图在 `data[0].b64_json`，输入图通过 `image` 扩展参数传入）。`OPENAI_IMAGE_PROVIDER ∈ {volces,volces-plan,ark,doubao,seedream,openai,azure}`
+  → images，其余 → chat；可用 `OPENAI_IMAGE_PROTOCOL=chat|images` 显式覆盖。用户只换 `.env` 即可切 provider，
+  调脚本的命令行参数完全不变。
+- **火山 Seedream 注意 base URL**：图片生成/图生图用 `https://ark.cn-beijing.volces.com/api/v3`；不要用聊天/识图的
+  `https://ark.cn-beijing.volces.com/api/coding/v3`。若开通了「流量包」套餐（`OPENAI_IMAGE_PROVIDER=volces-plan`），
+  base URL 改用 `https://ark.cn-beijing.volces.com/api/plan/v3`（按套餐计费，模型 ID 需与套餐支持列表一致，别混用 v3 端点否则产生套餐外费用）。
+- **图生图用途**：客户图比例不适合、主体太小、背景杂乱、需要扩成 16:9 hero、需要统一光影或增强清晰度时使用。不要把图生图当作结构图生成器；流程、架构、表格、模块图仍用 HTML/SVG/图表。
+- **速度取决于模型**：flash 类（如 `google/gemini-3.1-flash-image-preview`）约数十秒/张；重模型（如 `openai/gpt-5.4-image-2`）可达 ~3 分钟/张。生成期间耐心等其返回再发下一张；批量会成倍变慢，按需克制数量。
+- **鉴权失败**（401/403，退出码 1）：脚本返回「API key 可能失效/无权」诊断；转告用户检查 key，别重试烧钱。
+- **不要回显 API key**：脚本本身绝不打印 key；你转述错误时也别把 `OPENAI_IMAGE_API_KEY` 带出来。
+- **绿色版**：脚本随 `skills/` 分发到 exe 同级，但执行需机器装有 **Node**（与 ui-design 的 PPTX 导出脚本同样要求）。
+- **校验产物**：生成后可用 `Read`（offset=0 limit=1）触发二进制嗅探，或 `Bash` 看文件 size > 10KB 确认是真图。
+- 一次一张；多张就多次调用、每次换 `--out` 路径。
+
+## 关于宽高比（重要）
+
+`--aspect` 决定**生成图的构图**（主体摆放、负空间留给谁）。当生图是为了放进 PPT/网页的固定槽位时，
+**aspect 应贴合槽位的宽高比**——这样 CSS `object-fit:cover` 裁切最少、构图意图（如给文字留的净空）能保住。
+怎么按版面选 aspect 见 ui-design 的 `references/layout-composition.md`（图文混排方法论）。