minimal-agent 0.8.2 → 0.10.0

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

@@ -1,16 +1,18 @@
 /**
  * ============================================================
- *  src/workflows/stepExecutors/tool.ts —— tool step 执行
+ *  plugins/workflow-runner/src/stepExecutors/tool.ts —— tool step 执行
  * ------------------------------------------------------------
  *  把 step.args 递归 ${var} 插值后 JSON.stringify，转发到 executeTool。
  *  失败（ok=false）抛 Error，让 runner 走 onError 处理。
  *
  *  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（工具回执文本）
@@ -19,15 +21,27 @@
  *    - `{ args.<任意字段>: var_name }` 绑入参的具名字段
  * ============================================================
  */
-import { executeTool, getToolByName, } from '../../../../src/plugin-sdk.js';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { executeTool, getToolByName, recordRead, } from '../../../../src/plugin-sdk.js';
 import { interpolateDeep } from '../expressions.js';
 export async function* execToolStep(step, vars, ctx) {
     if (!step.tool)
         throw new Error(`step ${step.id}: 缺少 tool 字段`);
     const tool = getToolByName(step.tool);
     if (!tool)
-        throw new Error(`step ${step.id}: 未知 tool "${step.tool}"`);
-    const args = interpolateDeep(step.args ?? {}, vars);
+        throw new Error(`step ${step.id}: 未知工具 "${step.tool}"`);
+    // 未定义变量插值可见化（args 里静默空串会让工具拿到空路径/空内容）
+    const missing = [];
+    const args = interpolateDeep(step.args ?? {}, vars, {
+        onMissing: (e) => missing.push(e),
+    });
+    if (missing.length > 0) {
+        yield {
+            type: 'warning',
+            message: `step "${step.id}": 模板变量未定义，已按空串插值：${[...new Set(missing)].map((m) => `\${${m}}`).join('、')}（裸名请用 inputs.<name> 或先 capture/set）`,
+        };
+    }
     const argsJson = JSON.stringify(args);
     const toolCallId = `wf_${step.id}`;
     const argsPreview = argsJson.length > 80 ? `${argsJson.slice(0, 80)}…` : argsJson;
@@ -38,6 +52,14 @@ export async function* execToolStep(step, vars, ctx) {
         argsPreview,
         argsFriendly: friendlyToolDesc(tool.name, args),
     };
+    // ════ 声明产物覆盖判定（解 Write/Edit 的 pre-read 守卫） ════
+    // 内核写类工具有「文件已存在必须先 Read」守卫（fileState 进程级 Map，
+    // 跨进程 / resume / 残留旧产物时必空）。确定性 tool 步的 args 是 yaml 作者
+    // 写死的，模型没有机会先 Read —— 目标文件若是工作流**声明的产物**
+    // （def 级 + step 级 artifacts:，= 工作流自己拥有、本就要覆盖的文件），
+    // 这里自动 pre-Read 一次解除守卫（管线动作，不 yield 事件、结果丢弃）。
+    // 非声明产物的盲写保护原样生效；pre-Read 失败也不拦，让写工具自己报错。
+    await preReadDeclaredArtifact(tool, args, step, ctx);
     const result = await executeTool(tool.name, argsJson, ctx.signal);
     yield {
         type: 'tool_end',
@@ -50,15 +72,59 @@ 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,
     };
 }
+/**
+ * 写类 tool 步的目标文件若命中声明产物且已存在 → pre-Read 解除内核守卫。
+ *
+ * 路径归一化：artifacts 声明相对 cwd；args.file_path 可能是 ./相对 或 绝对，
+ * 双方都 resolve(cwd, …) 后比较（win32 文件系统大小写不敏感 → lowercase 比较；
+ * 其余平台保持大小写敏感，避免 Plan.md / plan.md 误判同文件）。
+ */
+async function preReadDeclaredArtifact(tool, args, step, ctx) {
+    if (tool.isReadOnly !== false)
+        return; // 只对写类工具生效
+    if (typeof args.file_path !== 'string')
+        return;
+    const norm = (p) => {
+        const abs = resolve(ctx.cwd, p);
+        return process.platform === 'win32' ? abs.toLowerCase() : abs;
+    };
+    const target = norm(args.file_path);
+    const declared = [...(ctx.declaredArtifacts ?? []), ...(step.artifacts ?? [])];
+    if (!declared.some((a) => norm(a) === target))
+        return;
+    const abs = resolve(ctx.cwd, args.file_path);
+    if (!existsSync(abs))
+        return; // 新建文件不需要解守卫
+    // 直接登记一次「完整已读」状态解除内核 pre-read 守卫——不真正 Read 内容：
+    //   1. 声明产物本就要被本步整体覆盖，旧内容无需进上下文/烧 token；
+    //   2. 真 Read 大文件会触发字符上限截断（read.ts → recordRead({truncated:true})），
+    //      反而踩中 Write 的「截断禁写」硬守卫（write.ts: existsSync && wasTruncated → 拒绝），
+    //      正是本步要解除的同一道墙——曾导致 plan.yaml 回写变长的 PLAN.md 时 halt
+    //      （首轮新建 PLAN.md 不存在直接放行，审批反馈后回写已存在的大 PLAN.md 被挡死）。
+    //   两道守卫（never-read + truncated）必须一并解除，声明产物的整体覆盖才算真正授权。
+    // recordRead 内部自带 statSync 失败兜底（返回 1、不抛），无需再包 try/catch。
+    recordRead(abs, { truncated: false });
+}
 /**
  * 给 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

@@ -1,8 +1,8 @@
 /**
  * ============================================================
- *  stepExecutors/verify.ts —— verify step 执行
+ *  plugins/workflow-runner/src/stepExecutors/verify.ts —— verify step 执行
  * ------------------------------------------------------------
- *  复用 src/infra/verification.ts 共享验证基础设施，
+ *  复用内核共享验证基础设施（经 plugin-sdk 门面取 runVerification/parseCheckString），
  *  支持 shell / file_exists / file_contains / test_count 四种检查。
  *
  *  与 assert 的区别：
@@ -10,19 +10,36 @@
  *    - verify: 完整检查器（重量，支持命令执行/正则匹配/测试计数）
  * ============================================================
  */
-import { parseCheckString, runVerification } from '../../../../src/infra/verification.js';
+import { parseCheckString, runVerification } from '../../../../src/plugin-sdk.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 数组 或逗号分隔字符串。
+    // 关键：【先插值再按逗号分割】。checks 可能是 "${verify_checks}" 这类模板，插值后才
+    // 展开成逗号分隔的多项（如 "shell:bun test,file_exists:x"）。若先分割再插值，整段模板
+    // 会被当成一项，解析时 value 混入逗号、多项检查失效（ralph-loop 的 run_verify 即如此）。
+    let rawChecks;
+    if (Array.isArray(step.checks) && step.checks.length > 0) {
+        rawChecks = step.checks
+            .flatMap((s) => interpolate(s, vars).split(','))
+            .map((s) => s.trim())
+            .filter(Boolean);
     }
-    // 解析并插值每条 check 字符串
+    else if (typeof step.checks === 'string' && step.checks.trim() !== '') {
+        rawChecks = interpolate(step.checks, vars)
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean);
+    }
+    else {
+        throw new Error(`step ${step.id}: verify 缺少 checks（需要数组或逗号分隔字符串）`);
+    }
+    // 解析每条已插值的 check 字符串（插值后若整体为空——如 ${verify_checks} 取到空串——
+    // 则 checks 为空，runVerification 视为"无检查项"通过；ralph-loop 另有 when 守卫不会走到这）
     const checks = [];
-    for (const raw of step.checks) {
-        const interpolated = interpolate(raw, vars);
-        const check = parseCheckString(interpolated);
+    for (const raw of rawChecks) {
+        const check = parseCheckString(raw);
         if (!check) {
-            throw new Error(`step ${step.id}: 无法解析 check "${interpolated}"，格式应为 "type:value"`);
+            throw new Error(`step ${step.id}: 无法解析 check "${raw}"，格式应为 "type:value"`);
         }
         checks.push(check);
     }

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

@@ -0,0 +1,296 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { chat as sdkChat, executeTool as sdkExecuteTool, } from '../../../src/plugin-sdk.js';
+import { truncate } from './agentCommon.js';
+import { extractJsonPayload } from './jsonPayload.js';
+// ============================================================
+//  工作流状态目录布局（E6 修复：按 workflow 名隔离）
+// ------------------------------------------------------------
+//  <cwd>/.minimal-agent-workflow/<name>/      ← 每个工作流独立状态
+//  <cwd>/.minimal-agent-workflow/<name>.done/ ← 成功归档
+//  曾经一个 cwd 单例目录：A（如 /plan）未完成时跑不同名工作流 B，
+//  init 的 new-task 路径会清掉 A 的声明产物 + 整个状态目录，A 永久失去
+//  resume 能力——与「不同任务中间文件互不干扰」需求直接冲突。
+//  按名隔离后跨工作流互不可见，互踩从结构上消失。
+//  /new 的前缀清理（.minimal-agent*）作用于父目录，行为不变。
+// ============================================================
+/** 工作流状态目录的父目录名（/new 按 .minimal-agent 前缀整体清理）。 */
+export const WF_STATE_PARENT = '.minimal-agent-workflow';
+/** 把 workflow 名清洗成安全的目录名（保留字母数字._-，其余替换为 -）。 */
+export function sanitizeWorkflowDirName(name) {
+    return name.replace(/[^\w.-]/g, '-');
+}
+/** 某 workflow 的状态目录绝对路径。workflowState / taskIdentity 共用唯一权威实现。 */
+export function workflowStateDir(workingDir, workflowName) {
+    return join(workingDir, WF_STATE_PARENT, sanitizeWorkflowDirName(workflowName));
+}
+/**
+ * 计算任务身份 hash。
+ *
+ * 策略（内容 hash 是【唯一权威信号】）：
+ *   - 对「workflow 名 + 归一化 goal」做 SHA256 → 取前 16 位 = taskId。
+ *   - 同 hash → 同一任务（无论隔了多久）；hash 不同 → 不同任务。
+ *   - recency（上次 startedAt 的时间窗口）【不】参与身份判定：30 分钟内换一个
+ *     完全不同的 goal 重跑同名 workflow，必须判「全新任务」清理重开，而不是
+ *     错误地 resume 旧任务把旧变量混进新目标（需求 3.2「不相关新任务自动清理重开」）。
+ *     旧版「时间窗口覆盖 hash 差异」是 bug，已移除。
+ *
+ * 归一化规则：
+ *   - 转小写
+ *   - 去除所有标点符号（保留中文、英文、数字、空格）
+ *   - 去除多余空格（连续空格→单空格，首尾 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. 尝试读取旧状态文件（按 workflow 名隔离的状态目录）
+    const stateFilePath = join(workflowStateDir(workingDir, workflowName), '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. 内容 hash 一致 → 同一任务（唯一权威信号，与时间无关）
+        if (prevState.taskId === contentHash) {
+            return {
+                hash: contentHash,
+                isSameTask: true,
+                reason: 'hash_match',
+            };
+        }
+        // c. hash 不一致 → 不同任务（goal 变了）。recency 不覆盖此判定（见函数头注）。
+        return {
+            hash: contentHash,
+            isSameTask: false,
+            reason: 'hash_diff',
+        };
+    }
+    catch {
+        // 解析失败时返回默认结果
+        return {
+            hash: contentHash,
+            isSameTask: false,
+            reason: 'no_previous',
+        };
+    }
+}
+/**
+ * 从 inputs 中提取 goal 文本
+ *
+ * 策略：
+ * - 优先 inputs.goal
+ * - 其次第一个 length > 2 的 string 值
+ * - 最后 JSON.stringify 整个 inputs
+ */
+export 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);
+}
+/** 延续短语白名单（归一化后精确匹配；短输入再放宽到前缀匹配）。 */
+const CONTINUATION_PHRASES = new Set([
+    '继续',
+    '继续吧',
+    '继续执行',
+    '继续任务',
+    '继续上次',
+    '继续刚才',
+    '接着',
+    '接着做',
+    '接着干',
+    '接着来',
+    '做完它',
+    '接着执行',
+    'continue',
+    'resume',
+    'go on',
+    'keep going',
+    'carry on',
+]);
+/** 新输入是否是「延续上次任务」的指令（仲裁快路径，不花 LLM）。 */
+export function isContinuationPhrase(rawGoal) {
+    const norm = normalizeGoal(rawGoal);
+    if (!norm)
+        return false;
+    if (CONTINUATION_PHRASES.has(norm))
+        return true;
+    // 短输入且以延续词开头（如「继续干活」「continue please」）也算
+    if (norm.length <= 12 &&
+        (norm.startsWith('继续') ||
+            norm.startsWith('接着') ||
+            norm.startsWith('continue') ||
+            norm.startsWith('resume'))) {
+        return true;
+    }
+    return false;
+}
+/**
+ * 构建复合仲裁器（短语快路径 → LLM 单轮仲裁 → AskUserQuestion → 兜底 new）。
+ * runner 在 state.init 前构建并传入；任何一级抛错都降级到下一级，绝不让仲裁本身 halt 工作流。
+ */
+export function buildTaskArbitrator(deps) {
+    const note = (m) => {
+        deps.notes?.push(m);
+    };
+    return async (actx) => {
+        // a. 延续短语快路径
+        if (isContinuationPhrase(actx.newGoal)) {
+            note(`任务仲裁：新输入「${truncate(actx.newGoal, 40)}」命中延续短语 → 继续旧任务（目标：${truncate(actx.prevGoal, 60)}）`);
+            return 'resume';
+        }
+        // b. LLM 单轮仲裁
+        try {
+            const verdict = await llmArbitrate(deps, actx);
+            if (verdict !== 'unsure') {
+                note(`任务仲裁：LLM 判定新输入${verdict === 'resume' ? '是旧任务的延续 → 续跑' : '是全新任务 → 清理旧产物重开'}`);
+                return verdict;
+            }
+        }
+        catch {
+            // LLM 不可用 → 降级到提问
+        }
+        // c. AskUserQuestion（TUI 弹界面；非交互宿主 askBridge 自动选推荐项=全新开始）
+        try {
+            const verdict = await askUserArbitrate(deps, actx);
+            note(`任务仲裁：经用户确认 → ${verdict === 'resume' ? '继续旧任务' : '全新开始'}`);
+            return verdict;
+        }
+        catch {
+            // 提问被取消/不可用 → 兜底
+        }
+        // d. 兜底 = 旧红线行为（hash 不等 → new-task），最小惊讶
+        note('任务仲裁：无法判定（LLM 与提问均不可用）→ 按全新任务处理');
+        return 'new';
+    };
+}
+/** LLM 单轮仲裁：旧 goal + 新输入 + 进度摘要 → {verdict, reason}。解析失败按 unsure。 */
+async function llmArbitrate(deps, actx) {
+    const chatFn = deps.chat ?? sdkChat;
+    const progress = `${actx.completedStepIds.length}/${actx.totalSteps}`;
+    const prompt = [
+        `你是工作流引擎的任务身份仲裁器。同名工作流「${actx.workflowName}」存在一个未完成的旧任务，`,
+        `用户刚发起了一次新调用，新输入的文本与旧任务目标不同。请判断新输入是「旧任务的延续指令」还是「全新任务」。`,
+        '',
+        `旧任务目标：${truncate(actx.prevGoal, 300)}`,
+        `旧任务进度：已完成 ${progress} 步${actx.completedStepIds.length ? `（${actx.completedStepIds.join(', ')}）` : ''}`,
+        actx.artifacts.length ? `旧任务产物：${actx.artifacts.join(', ')}` : '',
+        `新输入：${truncate(actx.newGoal, 300)}`,
+        '',
+        '判断标准：新输入若是「继续 / 接着做 / 把它做完 / 对旧任务的补充修改意见」类延续语义 → resume；',
+        '若是与旧目标无关的新需求 → new；真不确定 → unsure。',
+        '只输出一行 JSON（不要 markdown 代码块、不要解释）：{"verdict":"resume"|"new"|"unsure","reason":"一句话"}',
+    ]
+        .filter((l) => l !== '')
+        .join('\n');
+    let text = '';
+    for await (const ev of chatFn({
+        provider: deps.provider,
+        messages: [
+            { role: 'user', content: prompt, timestamp: Date.now(), id: crypto.randomUUID() },
+        ],
+        tools: [],
+        signal: deps.signal,
+    })) {
+        if (ev.type === 'text_delta')
+            text += ev.delta;
+    }
+    try {
+        const parsed = JSON.parse(extractJsonPayload(text.trim()));
+        if (parsed.verdict === 'resume' || parsed.verdict === 'new') {
+            return parsed.verdict;
+        }
+    }
+    catch {
+        // 解析失败按 unsure
+    }
+    return 'unsure';
+}
+/** 经 AskUserQuestion 问用户（推荐项=全新开始，与兜底语义一致；非交互自动按推荐项）。 */
+async function askUserArbitrate(deps, actx) {
+    const exec = deps.executeTool ?? sdkExecuteTool;
+    const progress = `${actx.completedStepIds.length}/${actx.totalSteps}`;
+    const args = {
+        questions: [
+            {
+                question: `检测到工作流「${actx.workflowName}」有一个未完成的任务（目标：${truncate(actx.prevGoal, 80)}，` +
+                    `进度 ${progress} 步）。本次输入「${truncate(actx.newGoal, 80)}」是要继续该任务，还是开始全新任务？`,
+                header: '任务仲裁',
+                options: [
+                    {
+                        label: '全新开始 (推荐)',
+                        description: '清理旧任务的中间产物，按本次输入重新规划执行',
+                    },
+                    {
+                        label: '继续上次任务',
+                        description: '从断点续跑旧任务，本次输入作为补充指令',
+                    },
+                ],
+            },
+        ],
+    };
+    const r = await exec('AskUserQuestion', JSON.stringify(args), deps.signal);
+    if (!r.ok)
+        throw new Error(r.error);
+    return r.content.includes('继续上次任务') ? 'resume' : 'new';
+}
+/**
+ * 归一化 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

@@ -1,9 +1,8 @@
 /**
  * ============================================================
- *  src/workflows/types.ts —— workflow runner 核心类型
+ *  plugins/workflow-runner/src/types.ts —— workflow runner 核心类型
  * ------------------------------------------------------------
- *  ralph-loop 让 LLM 自规划；workflow 反过来 —— 外层确定性 step 列表
- *  驱动执行，LLM 只在 llm: / skill: 节点出场。本文件定义 YAML 解析
+ *  外层确定性 step 列表驱动执行，LLM 只在 llm: / skill: / agent: 节点出场。
  *  后的内存形态（WorkflowDef / StepDef），以及运行时上下文（VarStack /
  *  RunContext）和 UI 事件（WorkflowEvent）。
  *
@@ -52,14 +51,25 @@ export class VarStack {
         if (this.frames.length > 1)
             this.frames.pop();
     }
-    /** ADR-05: parallel 用——给子 fork 一份深拷贝栈；子 fork 的 set/push/pop 不污染父栈。 */
-    fork() {
-        const child = new VarStack();
-        child.frames = this.frames.map((f) => ({ ...f }));
-        return child;
-    }
     /** 合并所有帧为一个普通对象（外层覆盖内层），用于 vars 持久化与事件 */
     snapshot() {
         return Object.assign({}, ...this.frames);
     }
 }
+/**
+ * 把 yaml 的 capture 归一化成 { resultField: varName } map。支持两种写法
+ * （通用 DSL，根治「裸字符串 capture 被 Object.entries/values 迭代成单字符」的静默 footgun）：
+ *   - map 形式：   capture: { text: foo, args.content: bar }
+ *   - 简写字符串： capture: foo  ≡  capture: { result: foo }
+ *     绑 StepResult.raw.result —— llm/agent=文本、tool=回执，各 executor 都提供 result 别名。
+ *
+ * 放在 types.ts（零依赖）供 runner.ts（bindCapture）与 agentCommon.ts（describeCaptureContract）
+ * 共用，避免 runner↔agentCommon 循环引用。
+ */
+export function normalizeCapture(cap) {
+    if (cap == null)
+        return {};
+    if (typeof cap === 'string')
+        return { result: cap };
+    return cap;
+}