minimal-agent 0.8.2 → 0.10.0

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

@@ -1,56 +1,491 @@
 /**
  * ============================================================
- *  src/workflows/workflowState.ts —— workflow 运行状态持久化
+ *  plugins/workflow-runner/src/workflowState.ts —— 工作流状态持久化
  * ------------------------------------------------------------
- *  与 GoalState 类似的轻量目录模型，但只用于 debug / 中断恢复（P0 不实现
- *  恢复，只写出现场）。目录结构：
+ *  Phase 1 升级：支持断点续执行、任务身份判定、capture 回放、产物管理。
  *
- *    <cwd>/.minimal-agent-workflow/
- *      ├── current.json    # { name, startedAt }
- *      ├── inputs.json     # 用户传入的 inputs 快照
- *      ├── vars.json       # 最后一次成功 step 后的 VarStack.snapshot()
- *      └── progress.md     # 时间戳追加的 step 完成日志
+ *  核心变更：
+ *    - init() 不再无条件清空，而是先读旧状态 → 判定任务身份 → 分发 4 种模式
+ *    - 新增 checkpoints/ 目录记录每步完成状态和 capture 变量
+ *    - 产物生命周期：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 死代码」。
  *
- *  init() 进 workflow 前 reset 一次；cleanup() 在 finally 把文件删掉
- *  + rmdir（保持 /new 扫描 .minimal-agent-* 子目录的语义一致）。
- *
- *  与 GoalState 的核心区别：workflow 不需要 PHASE / completion / learnings 文件，
- *  因为执行流程是确定性的，没有 LLM 自规划过程。
+ *  目录结构（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 { mkdir, writeFile, appendFile, rm, rename } from 'node:fs/promises';
+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';
-const STATE_DIR = '.minimal-agent-workflow';
+import { computeTaskId, extractGoal, workflowStateDir, } from './taskIdentity.js';
 const DONE_SUFFIX = '.done';
+const CHECKPOINTS_DIR = 'checkpoints';
+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);
     }
-    async init(name, inputs) {
-        // 启动新 workflow 时清理旧状态（含之前的归档）
-        await rm(this.dir, { recursive: true, force: true }).catch(() => { });
-        await rm(this.dir + DONE_SUFFIX, { recursive: true, force: true }).catch(() => { });
-        await mkdir(this.dir, { recursive: true });
-        await writeFile(join(this.dir, 'current.json'), JSON.stringify({ name, startedAt: new Date().toISOString() }, null, 2), 'utf8');
-        await writeFile(join(this.dir, 'inputs.json'), JSON.stringify(inputs, null, 2), 'utf8');
-        await writeFile(join(this.dir, 'progress.md'), `# ${name}\n\n`, 'utf8');
+    /**
+     * 初始化工作流状态 —— 核心入口，返回恢复信息。
+     *
+     * 4 种模式：
+     *   1. fresh      — 首次运行此工作流（无旧状态）
+     *   2. new-task  — 不同任务 → 清理旧产物后全新开始
+     *   3. completed — 同一任务已完成 → 返回产物列表
+     *   4. resume    — 同一任务未完成 → 扫描 checkpoint 决定恢复点
+     *
+     * hash 相等 = 同任务（权威信号，与时间无关）。hash 不等且旧任务【未完成】时
+     * 不再一票否决 new-task：若提供了 arbitrate（语义仲裁器，见 taskIdentity.ts），
+     * 由它判定新输入是「旧任务的延续指令（如"继续"）→ resume」还是「全新任务 → new-task」。
+     */
+    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) {
+            // 活动目录无状态 —— 可能是「上次成功已归档到 .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. 有活动状态（上次中断 / 失败 / 进行中，未归档）—— 用 hash 判同/异任务
+        if (!identity.isSameTask) {
+            // 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. 同一任务 —— 检查完成状态（兜底：正常成功会 archive，故活动目录 done 少见）
+        if (oldState.status === 'done') {
+            return {
+                mode: 'completed',
+                artifacts: this.existingArtifacts(oldState.artifacts ?? declaredArtifacts),
+            };
+        }
+        // 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);
+        // 恢复点 = 最后一个已完成步在 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,
+            completedStepIds: completedSteps,
+            failedStep: oldState.lastFailedStep,
+            recoveryStart,
+            lastError: oldState.lastError,
+            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) {
+        const cpDir = join(this.dir, CHECKPOINTS_DIR);
+        await mkdir(cpDir, { recursive: true }).catch(() => { });
+        const data = {
+            stepId,
+            completedAt: new Date().toISOString(),
+            output,
+            captures,
+            varsSnapshot,
+        };
+        await writeFile(join(cpDir, `${stepId}.json`), JSON.stringify(data, null, 2), 'utf-8');
+    }
+    /** 记录步骤失败：更新 current.json 的 lastFailedStep 和 lastError */
+    async recordFailure(stepId, error) {
+        const current = await this.readCurrentState();
+        if (current) {
+            current.lastFailedStep = stepId;
+            current.lastError = error;
+            current.status = 'failed';
+            await this.writeCurrent(current);
+        }
+    }
+    /** 标记整个工作流完成 */
+    async markDone() {
+        const current = await this.readCurrentState();
+        if (current) {
+            current.status = 'done';
+            await this.writeCurrent(current);
+        }
+    }
+    // ---- 公共方法：进度与变量（保持原有签名兼容） ----
+    /** 追加进度日志 */
     async appendProgress(line) {
         const ts = new Date().toISOString().replace('T', ' ').slice(0, 19);
-        await appendFile(join(this.dir, 'progress.md'), `- ${ts} ${line}\n`, 'utf8').catch(() => { });
+        await appendFile(join(this.dir, 'progress.md'), `- ${ts} ${line}\n`, 'utf-8').catch(() => { });
     }
+    /** 写入 vars 快照 */
     async writeVars(snapshot) {
-        await writeFile(join(this.dir, 'vars.json'), JSON.stringify(snapshot, null, 2), 'utf8').catch(() => { });
+        await writeFile(join(this.dir, 'vars.json'), JSON.stringify(snapshot, null, 2), 'utf-8').catch(() => { });
+    }
+    /**
+     * 扫描 checkpoints/ 目录，返回按 steps 数组顺序排列的已完成 step id 列表。
+     * 只返回在 steps[] 中存在的 id（防止 YAML 改动后 orphaned checkpoint 干扰恢复）。
+     */
+    async scanCheckpoints(steps) {
+        const cpDir = join(this.dir, CHECKPOINTS_DIR);
+        const validIds = new Set(steps.map((s) => s.id));
+        try {
+            const files = await readdir(cpDir);
+            const ids = [];
+            for (const f of files) {
+                if (!f.endsWith('.json'))
+                    continue;
+                const stepId = f.replace(/\.json$/, '');
+                if (validIds.has(stepId))
+                    ids.push(stepId);
+            }
+            // 按 steps 数组中的原始顺序排列（非文件系统顺序）
+            return ids.sort((a, b) => {
+                const ai = steps.findIndex((s) => s.id === a);
+                const bi = steps.findIndex((s) => s.id === b);
+                return ai - bi;
+            });
+        }
+        catch {
+            return [];
+        }
+    }
+    /** 加载最近一次成功的 vars 快照 */
+    async loadLastGoodVars() {
+        try {
+            const raw = await readFile(join(this.dir, 'vars.json'), 'utf-8');
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** 加载所有已完成步骤的 capture 变量（用于 resume 时回放到 VarStack） */
+    async loadAllCaptures(stepIds) {
+        const result = {};
+        const cpDir = join(this.dir, CHECKPOINTS_DIR);
+        for (const sid of stepIds) {
+            try {
+                const raw = await readFile(join(cpDir, `${sid}.json`), 'utf-8');
+                const cp = JSON.parse(raw);
+                if (cp.captures && Object.keys(cp.captures).length > 0) {
+                    result[sid] = cp.captures;
+                }
+            }
+            catch {
+                // 单个 checkpoint 读失败不阻断整体
+            }
+        }
+        return result;
     }
+    // ---- 私有方法：声明式产物生命周期 ----
+    /** 删除工作流【声明】的产物文件（相对 cwd），用于 new-task 清理旧任务残留（如旧 PLAN.md）。
+     *  仅删工作流自己声明的产物、仅 force-rm 文件，scoped 安全。返回清理过的路径列表。 */
+    async cleanupDeclaredArtifacts(paths) {
+        for (const p of paths) {
+            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));
+    }
+    // ---- 公共方法：归档与清理（保持原有签名兼容） ----
     /**
      * 归档（成功完成时调用）：重命名状态目录为 .done 后缀，保留所有中间产物。
-     * vars.json / progress.md / inputs.json 全部保留——供后续对话 Read 回溯。
+     * vars.json / progress.md / inputs.json / checkpoints/ 全部保留——供后续对话 Read 回溯。
      */
     async archive() {
         const doneDir = this.dir + DONE_SUFFIX;
         try {
-            // 先清理旧的归档（如果存在）
             await rm(doneDir, { recursive: true, force: true });
         }
         catch {
@@ -63,12 +498,60 @@ export class WorkflowState {
             // rename 失败时静默（某些文件系统/权限问题），保留原目录
         }
     }
-    /**
-     * 强制清理（/new 或新 workflow init 时调用）：删除状态目录（含 .done 归档）。
-     */
+    /** 强制清理（/new 或新任务 init 时调用）：删除状态目录（含 .done 归档） */
     async cleanup() {
         await rm(this.dir, { recursive: true, force: true }).catch(() => { });
-        // 同时清理可能的归档目录
         await rm(this.dir + DONE_SUFFIX, { recursive: true, force: true }).catch(() => { });
     }
+    // ---- 私有方法 ----
+    /** 创建全新的空白状态目录（含 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 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 {
+            const raw = await readFile(join(this.dir, 'current.json'), 'utf-8');
+            return JSON.parse(raw);
+        }
+        catch {
+            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/adversarial-review/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: adversarial-review
 description: 质疑一个结论 / 计划 / 既有评审 / 设计方案是否站得住脚——默认怀疑、逼出证据，把发现分成「真问题 / 误报 / 待澄清」。注意：若用户只是想给代码找冗余 / 反模式 / 做常规质量改进，用 /simplify 而非本 skill。
-triggers: 对抗审查、反向提问、红队、挑战这个结论、验证某结论或方案是否站得住脚、哪些是误报哪些是真问题、审稿、复核这个判断
 ---
 
 # /adversarial-review —— 对抗式审查（反向提问，默认怀疑）