minimal-agent 0.8.2 → 0.9.0

package/plugins/workflow-runner/src/stepExecutors/skill.js

@@ -1,28 +1,24 @@
-// NOTE: output_schema 不支持 skill 节点——loader 现已直接拒绝 skill+output_schema 组合
-// （见 loader.ts validateSteps，P3 修复：静默 no-op 改为加载期报错）。
-// 仅 llm 节点支持 provider-native structured output；vote 通过 runVoter 调 execLlmStep（llm 虚拟步骤）。
 /**
  * ============================================================
- *  plugins/workflow-runner/src/stepExecutors/skill.ts —— skill step 执行
+ *  plugins/workflow-runner/src/stepExecutors/skill.ts —— skill 步骤执行器
  * ------------------------------------------------------------
- *  把一个具名 skill（skills/<name>/SKILL.md）当作"迷你 ReAct 子循环"
- *  跑一次：复用 src/loop.ts::runQuery，让模型在子 history 内 T-A-O-R。
+ *  v0.9 重构：不再使用独立 subHistory 隔离子循环，而是委托主 TAOR 引擎
+ *  （runQuery / src/loop.ts）在共享 ctx.history 上执行。
  *
  *  实现要点：
- *    - 双源查找：cwd/skills/<name>/SKILL.md 优先，packageRoot/skills/ fallback；
- *      支持按目录名 or 按 frontmatter::name 匹配
- *    - 剥掉 frontmatter，body 作 system 指令；step.input 插值后作为 user
- *    - 子 history 与外层 ctx.history 隔离，避免污染主对话
- *    - 流式转发：runQuery yield 的事件直接 yield 出去（让 UI 看到子循环进度）
- *    - 收集 text 事件累计为 raw.text，供 capture 绑变量使用
- *    - maxTurns 可在 step 里覆盖，默认走 runQuery 自带（50）
+ *    - 双源查找：cwd/skills/<name>/SKILL.md 优先，packageRoot/skills/ fallback
+ *    - SKILL.md body 作为用户提示的一部分（系统提示词已在 history[0]）
+ *    - 执行结果直接写入共享 ctx.history，上下文自然积累
+ *    - 流式转发：runQuery yield 的事件直接透传给 UI
+ *    - maxTurns 可在 step 里覆盖（默认 25）
  *
  *  capture：{ text: var_name } / { result: var_name }
  * ============================================================
  */
 import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { getResourceSearchPaths, runQuery, } from '../../../../src/plugin-sdk.js';
+import { runQuery } from '../../../../src/loop.js';
+import { getResourceSearchPaths } from '../../../../src/plugin-sdk.js';
 import { interpolate } from '../expressions.js';
 function stripFrontmatter(content) {
     return content.replace(/^---\n[\s\S]*?\n---\n?/, '');
@@ -36,8 +32,11 @@ function parseFrontmatterName(content) {
         return null;
     return nm[1].trim().replace(/^["']|["']$/g, '');
 }
-async function findSkillFile(skillName) {
+async function findSkillFile(skillName, cwd) {
     const roots = getResourceSearchPaths('skills', import.meta.url);
+    // 优先搜索 cwd/skills（工作目录下的 skills 优先于包内 skills）
+    const cwdSkills = join(cwd, 'skills');
+    roots.unshift(cwdSkills);
     for (const root of roots) {
         let entries;
         try {
@@ -58,7 +57,7 @@ async function findSkillFile(skillName) {
                     return skillFile;
             }
             catch {
-                // 该子目录无 SKILL.md，跳过
+                continue;
             }
         }
     }
@@ -68,43 +67,55 @@ export async function* execSkillStep(step, vars, ctx) {
     if (!step.skill)
         throw new Error(`step ${step.id}: 缺少 skill 字段`);
     const skillName = interpolate(step.skill, vars);
-    const skillFile = await findSkillFile(skillName);
+    const skillFile = await findSkillFile(skillName, ctx.cwd);
     if (!skillFile) {
         throw new Error(`step ${step.id}: 未找到 skill "${skillName}"（cwd/skills/ 与 packageRoot/skills/ 双源均未命中）`);
     }
     const md = await readFile(skillFile, 'utf8');
     const body = stripFrontmatter(md).trim();
+    // 构造用户提示：skill 指令 + 步骤 input
+    // 系统提示词已在 history[0] 中（含完整 skill 列表和描述），
+    // 这里不需要再拼 system message——把 SKILL.md body 作为操作指令即可
     const userInput = step.input
         ? interpolate(step.input, vars)
-        : `请按 SKILL "${skillName}" 的指示完成任务。`;
-    const subHistory = [
-        {
-            role: 'system',
-            content: `下面是要遵循的 SKILL 指示（来源：${skillFile}）：\n\n${body}`,
-        },
-    ];
-    let text = '';
-    for await (const ev of runQuery(userInput, {
+        : `请按以下 SKILL "${skillName}" 的指示完成任务。`;
+    const fullPrompt = `【执行 Skill：${skillName}】\n\n${body}\n\n---\n\n当前任务：\n${userInput}`;
+    // 通用目标锚定：确保 skill 执行时也不偏离原始目标
+    const effectivePrompt = ctx.goalAnchor
+        ? `${ctx.goalAnchor}\n\n${fullPrompt}`
+        : fullPrompt;
+    const maxTurns = step.maxTurns ?? 25;
+    // 记录 history 长度用于提取本步输出
+    const historyLenBefore = ctx.history.length;
+    // 委托 TAOR 引擎在共享 history 上执行
+    // 注意：需要过滤掉 turn_done 事件（它是 runQuery 内部的终结标记，
+    // 不应外泄为 workflow 的终结——workflow 的收口由 index.ts 统一处理）
+    for await (const ev of runQuery(effectivePrompt, {
         provider: ctx.provider,
-        history: subHistory,
+        history: ctx.history,
         signal: ctx.signal,
-        maxTurns: step.maxTurns,
+        maxTurns,
+        chat: ctx.chat,
+        executeTool: ctx.executeTool,
+        sessionState: ctx.sessionState,
     })) {
-        if (ev.type === 'text')
-            text += ev.delta;
-        if (ev.type === 'interrupted')
-            throw new Error('用户中断');
-        if (ev.type === 'error')
-            throw new Error(ev.error);
-        // 子 skill 内部那次 runQuery 的 turn_done 是它自己的终结标记，不是整个 workflow 的终结。
-        // 不外泄——否则把 turn_done 当终结的消费者（-p --output-format json / gateway broker）
-        // 会在 workflow 中途（如 critic 步之后、verify 步之前）误判结束、漏掉后续步骤。
-        // workflow 的对外收口由 index.ts::runWorkflowFromCommand 末尾统一补发。
+        // turn_done 是 runQuery 单次调用的终结标记，不是 workflow 终结。
+        // 外泄会导致 gateway broker / -p json 模式误判 workflow 中途结束。
         if (ev.type === 'turn_done')
             continue;
+        // error / interrupted 应该冒泡让 runner 处理
         yield ev;
     }
-    const trimmed = text.trim();
+    // 从 history 提取本步最后一条 assistant 消息
+    let rawText = '';
+    for (let i = ctx.history.length - 1; i >= historyLenBefore; i--) {
+        const msg = ctx.history[i];
+        if (msg.role === 'assistant' && typeof msg.content === 'string' && msg.content.trim()) {
+            rawText = msg.content;
+            break;
+        }
+    }
+    const trimmed = rawText.trim();
     return {
         raw: { text: trimmed, result: trimmed },
         preview: trimmed.length > 200 ? `${trimmed.slice(0, 200)}...` : trimmed,

package/plugins/workflow-runner/src/stepExecutors/tool.js

@@ -7,10 +7,12 @@
  *
  *  v2（P1 TUI 可见）：本执行器改为 AsyncGenerator，在调 executeTool 前后
  *  yield 通用 tool_start / tool_end LoopEvent —— 这样 workflow 的 tool 步骤
- *  在 TUI 里像普通 ReAct 工具调用一样显示（runningTools spinner + 人话描述），
- *  不再"无声"。**不** yield tool_messages_committed：workflow 步骤不进主 history，
- *  其 live 态由 useChat 的 submit finally(resetTurnState) 在事件流末尾统一清理；
- *  tool_end 自身已把该 callId 从 runningTools 里摘除，无需额外 commit 语义。
+ *  在 TUI 里像普通 ReAct 工具调用一样显示（runningTools spinner + 人话描述）。
+ *
+ *  v0.9.3（上下文统一修复）：tool 步骤执行后把工具调用摘要写入 ctx.history，
+ *  让后续 agent/llm/skill 步骤（走 runQuery → LLM）能自然看到前面步骤的工作成果，
+ *  不再依赖 VarStack 变量插值作为唯一的信息传递通道。
+ *  这实现了"一套上下文"架构：workflow 的每一步都在共享的 TAOR history 中留痕。
  *
  *  capture 字段（支持点路径）：
  *    - `{ content: var_name }`      绑 ToolResult.content（工具回执文本）
@@ -26,7 +28,7 @@ export async function* execToolStep(step, vars, ctx) {
         throw new Error(`step ${step.id}: 缺少 tool 字段`);
     const tool = getToolByName(step.tool);
     if (!tool)
-        throw new Error(`step ${step.id}: 未知 tool "${step.tool}"`);
+        throw new Error(`step ${step.id}: 未知工具 "${step.tool}"`);
     const args = interpolateDeep(step.args ?? {}, vars);
     const argsJson = JSON.stringify(args);
     const toolCallId = `wf_${step.id}`;
@@ -50,6 +52,19 @@ export async function* execToolStep(step, vars, ctx) {
         throw new Error(result.error);
     }
     const content = result.content;
+    // ════ v0.9.3：上下文统一 —— 把工具调用写入共享 history ════
+    // 后续 agent/llm/skill 步骤走 runQuery() 时，LLM 能在上下文中看到
+    // 这步做了什么（与正常 TAOR 循环中 tool_call → tool_result 的记录方式一致）。
+    // 只记录精简摘要（不把完整工具回执塞入 history，避免 token 浪费）。
+    const summary = content.length > 500
+        ? `${content.slice(0, 500)}…（已截断，共 ${content.length} 字符）`
+        : content;
+    ctx.history.push({
+        role: 'assistant',
+        content: `[workflow:${step.id}] ✅ ${tool.name} 执行完成：${summary}`,
+        timestamp: Date.now(),
+        id: crypto.randomUUID(),
+    });
     return {
         raw: { content, result: content, args },
         preview: content.length > 200 ? `${content.slice(0, 200)}...` : content,
@@ -57,8 +72,6 @@ export async function* execToolStep(step, vars, ctx) {
 }
 /**
  * 给 tool_start 生成人话描述（LiveArea spinner 行用）。
- * 取常见入参键（file_path/command/query/...）拼成 "Write greetings/a/hello.txt"
- * 这样的短句；都没命中就回退到工具名本身。
  */
 function friendlyToolDesc(toolName, args) {
     const key = ['file_path', 'command', 'query', 'pattern', 'path', 'url'].find((k) => typeof args[k] === 'string');

package/plugins/workflow-runner/src/stepExecutors/verify.js

@@ -13,12 +13,20 @@
 import { parseCheckString, runVerification } from '../../../../src/infra/verification.js';
 import { interpolate } from '../expressions.js';
 export async function execVerifyStep(step, vars) {
-    if (!Array.isArray(step.checks) || step.checks.length === 0) {
-        throw new Error(`step ${step.id}: verify 缺少 checks 数组`);
+    // 兼容两种格式：YAML 数组 或逗号分隔字符串
+    let rawChecks;
+    if (Array.isArray(step.checks) && step.checks.length > 0) {
+        rawChecks = step.checks;
+    }
+    else if (typeof step.checks === 'string' && step.checks.trim() !== '') {
+        rawChecks = step.checks.split(',').map((s) => s.trim()).filter(Boolean);
+    }
+    else {
+        throw new Error(`step ${step.id}: verify 缺少 checks（需要数组或逗号分隔字符串）`);
     }
     // 解析并插值每条 check 字符串
     const checks = [];
-    for (const raw of step.checks) {
+    for (const raw of rawChecks) {
         const interpolated = interpolate(raw, vars);
         const check = parseCheckString(interpolated);
         if (!check) {

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

@@ -0,0 +1,141 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * 默认时间窗口：30 分钟内同名 workflow 视为同任务（毫秒）
+ */
+const DEFAULT_TIME_WINDOW_MS = 30 * 60 * 1000;
+/**
+ * 计算任务身份 hash。
+ *
+ * 策略（双重信号）：
+ *   1. 内容 hash：对 goal 做归一化后 SHA256 → 取前 16 位
+ *   2. 时间窗口：读取 .minimal-agent-workflow/current.json 的 startedAt，
+ *      如果在窗口期内且 workflow 名相同 → 强制视为同一任务（覆盖 hash 差异）
+ *
+ * 归一化规则：
+ *   - 转小写
+ *   - 去除所有标点符号（保留中文、英文、数字、空格）
+ *   - 去除多余空格（连续空格→单空格，首尾 trim）
+ *   - 截断到 200 字符（防止超长输入导致不必要的差异）
+ */
+export function computeTaskId(workflowName, inputs, workingDir) {
+    // 1. 提取 goal 文本（与 buildGoalAnchor 同策略）
+    const rawGoal = extractGoal(inputs);
+    // 2. 归一化 goal
+    const normalizedGoal = normalizeGoal(rawGoal);
+    // 3. 计算 contentHash = SHA256(`${workflowName}::${normalizedGoal}`)[:16]
+    const contentHash = createHash('sha256')
+        .update(`${workflowName}::${normalizedGoal}`)
+        .digest('hex')
+        .slice(0, 16);
+    // 4. 如果没有提供 workingDir，只返回 hash，不做比较
+    if (!workingDir) {
+        return {
+            hash: contentHash,
+            isSameTask: false,
+            reason: 'no_previous',
+        };
+    }
+    // 5. 尝试读取旧状态文件
+    const stateFilePath = join(workingDir, '.minimal-agent-workflow', 'current.json');
+    if (!existsSync(stateFilePath)) {
+        return {
+            hash: contentHash,
+            isSameTask: false,
+            reason: 'no_previous',
+        };
+    }
+    try {
+        const stateContent = readFileSync(stateFilePath, 'utf-8');
+        const prevState = JSON.parse(stateContent);
+        // a. 不同 workflow → 不同任务
+        if (prevState.name && prevState.name !== workflowName) {
+            return {
+                hash: contentHash,
+                isSameTask: false,
+                reason: 'different_workflow',
+            };
+        }
+        // b. 检查时间窗口
+        if (prevState.startedAt) {
+            const startedAt = new Date(prevState.startedAt).getTime();
+            const now = Date.now();
+            const timeDiff = now - startedAt;
+            // 在时间窗口内 → 强制视为同一任务（即使 hash 不同）
+            if (timeDiff >= 0 && timeDiff <= DEFAULT_TIME_WINDOW_MS) {
+                return {
+                    hash: contentHash,
+                    isSameTask: true,
+                    reason: 'time_window',
+                };
+            }
+        }
+        // c. 时间窗口过期但 taskId 与当前 hash 匹配
+        if (prevState.taskId === contentHash) {
+            return {
+                hash: contentHash,
+                isSameTask: true,
+                reason: 'hash_match',
+            };
+        }
+        // d. 时间窗口过期且 hash 不匹配
+        return {
+            hash: contentHash,
+            isSameTask: false,
+            reason: 'expired',
+        };
+    }
+    catch (error) {
+        // 解析失败时返回默认结果
+        return {
+            hash: contentHash,
+            isSameTask: false,
+            reason: 'no_previous',
+        };
+    }
+}
+/**
+ * 从 inputs 中提取 goal 文本
+ *
+ * 策略：
+ * - 优先 inputs.goal
+ * - 其次第一个 length > 2 的 string 值
+ * - 最后 JSON.stringify 整个 inputs
+ */
+function extractGoal(inputs) {
+    // 优先级1：直接使用 inputs.goal
+    if (typeof inputs.goal === 'string') {
+        return inputs.goal;
+    }
+    // 优先级2：查找第一个长度 > 2 的字符串值
+    for (const value of Object.values(inputs)) {
+        if (typeof value === 'string' && value.length > 2) {
+            return value;
+        }
+    }
+    // 优先级3：JSON 序列化整个 inputs
+    return JSON.stringify(inputs);
+}
+/**
+ * 归一化 goal 字符串
+ *
+ * 规则：
+ * - toLowerCase()
+ * - 去除所有标点符号（保留中文、英文、数字、空格）
+ * - 去除多余空格（连续空格→单空格）
+ * - 首尾 trim
+ * - 截断到 200 字符
+ */
+function normalizeGoal(raw) {
+    return (raw
+        .toLowerCase()
+        // 保留中文、英文、数字、空格，去除其他字符（标点等）
+        .replace(/[^\p{L}\p{N}\s]/gu, '')
+        // 连续空格替换为单空格
+        .replace(/\s+/g, ' ')
+        // 首尾去空格
+        .trim()
+        // 截断到 200 字符
+        .slice(0, 200));
+}

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

@@ -2,8 +2,7 @@
  * ============================================================
  *  src/workflows/types.ts —— workflow runner 核心类型
  * ------------------------------------------------------------
- *  ralph-loop 让 LLM 自规划；workflow 反过来 —— 外层确定性 step 列表
- *  驱动执行，LLM 只在 llm: / skill: 节点出场。本文件定义 YAML 解析
+ *  外层确定性 step 列表驱动执行，LLM 只在 llm: / skill: / agent: 节点出场。
  *  后的内存形态（WorkflowDef / StepDef），以及运行时上下文（VarStack /
  *  RunContext）和 UI 事件（WorkflowEvent）。
  *

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

@@ -1,56 +1,212 @@
 /**
  * ============================================================
- *  src/workflows/workflowState.ts —— workflow 运行状态持久化
+ *  plugins/workflow-runner/src/workflowState.ts —— 工作流状态持久化
  * ------------------------------------------------------------
- *  与 GoalState 类似的轻量目录模型，但只用于 debug / 中断恢复（P0 不实现
- *  恢复，只写出现场）。目录结构：
+ *  Phase 1 升级：支持断点续执行、任务身份判定、capture 回放、产物管理。
  *
+ *  核心变更：
+ *    - init() 不再无条件清空，而是先读旧状态 → 判定任务身份 → 分发 4 种模式
+ *    - 新增 checkpoints/ 目录记录每步完成状态和 capture 变量
+ *    - 新增 artifacts/ 目录管理产出物
+ *    - resume 模式时回放已完成步骤的 capture 到 vars 中
+ *
+ *  目录结构：
  *    <cwd>/.minimal-agent-workflow/
- *      ├── current.json    # { name, startedAt }
+ *      ├── current.json    # { name, taskId, status, startedAt, lastFailedStep?, lastError? }
  *      ├── inputs.json     # 用户传入的 inputs 快照
  *      ├── vars.json       # 最后一次成功 step 后的 VarStack.snapshot()
- *      └── progress.md     # 时间戳追加的 step 完成日志
- *
- *  init() 进 workflow 前 reset 一次；cleanup() 在 finally 把文件删掉
- *  + rmdir（保持 /new 扫描 .minimal-agent-* 子目录的语义一致）。
- *
- *  与 GoalState 的核心区别：workflow 不需要 PHASE / completion / learnings 文件，
- *  因为执行流程是确定性的，没有 LLM 自规划过程。
+ *      ├── progress.md     # 时间戳追加的 step 完成日志
+ *      ├── checkpoints/    # 每步一个 JSON：{ stepId, completedAt, output, captures, varsSnapshot }
+ *      └── artifacts/      # 产出物文件（PLAN.md 等）
  * ============================================================
  */
-import { mkdir, writeFile, appendFile, rm, rename } from 'node:fs/promises';
+import { mkdir, writeFile, appendFile, rm, rename, readFile, readdir } from 'node:fs/promises';
 import { join } from 'node:path';
+import { computeTaskId } from './taskIdentity.js';
 const STATE_DIR = '.minimal-agent-workflow';
 const DONE_SUFFIX = '.done';
+const CHECKPOINTS_DIR = 'checkpoints';
+const ARTIFACTS_DIR = 'artifacts';
 export class WorkflowState {
     dir;
     constructor(workingDir) {
         this.dir = join(workingDir, STATE_DIR);
     }
-    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  — 不同任务（hash 或时间窗口不匹配）→ 清理旧产物后全新开始
+     *   3. completed — 同一任务已完成 → 返回产物列表
+     *   4. resume    — 同一任务未完成 → 扫描 checkpoint 决定恢复点
+     */
+    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
+        const oldState = await this.readCurrentState();
+        if (!oldState) {
+            // 模式 1: fresh —— 无旧状态，首次运行
+            await this.cleanSlate(name, inputs, identity.hash);
+            return { mode: 'fresh', startFrom: 0 };
+        }
+        // 3. 用 computeTaskId 的 isSameTask 结果判断
+        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 };
+        }
+        // 4. 同一任务 —— 检查完成状态
+        if (oldState.status === 'done') {
+            // 模式 3: completed —— 同一任务已完成
+            const artifacts = await this.listArtifacts();
+            return { mode: 'completed', artifacts };
+        }
+        // 5. 模式 4: resume —— 同一任务未完成，扫描 checkpoint 决定恢复点
+        const completedSteps = await this.scanCheckpoints(steps);
+        const selfHealBackoff = 1; // 默认回退 1 步，runner 可通过 WorkflowDef.self_heal.backoff 覆盖
+        const recoveryStart = Math.max(0, completedSteps.length - selfHealBackoff);
+        // 加载 capturedVars 用于回放
+        const capturedVars = await this.loadAllCaptures(completedSteps);
+        return {
+            mode: 'resume',
+            startFrom: recoveryStart,
+            completedStepIds: completedSteps,
+            failedStep: oldState.lastFailedStep,
+            recoveryStart,
+            lastError: oldState.lastError,
+            capturedVars,
+        };
+    }
+    // ---- 公共方法：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;
+    }
+    // ---- 公共方法：产物管理 ----
+    /** 列出 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);
+        for (const p of paths) {
+            await rm(join(artDir, p), { force: true }).catch(() => { });
+        }
+    }
+    // ---- 公共方法：归档与清理（保持原有签名兼容） ----
     /**
      * 归档（成功完成时调用）：重命名状态目录为 .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 +219,39 @@ 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/ 和 artifacts/ 子目录） */
+    async cleanSlate(name, inputs, taskId) {
+        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(),
+        });
+        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');
+    }
+    /** 读取 current.json，解析失败或文件不存在返回 null */
+    async readCurrentState() {
+        try {
+            const raw = await readFile(join(this.dir, '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 —— 对抗式审查（反向提问，默认怀疑）