minimal-agent 0.9.0 → 0.10.0

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

@@ -13,14 +13,14 @@
  *    5. 中断后上下文完整：已完成的步骤全在 history 里，可继续/调整
  *
  *  与 llm 步的区别：
- *    - agent 有 maxTurns 上限（默认 12），允许多轮工具调用
+ *    - agent 有 maxTurns 上限（默认 25），允许多轮工具调用
  *    - agent 的产出经过验证闸门（interpretMiniReActResult）
  *    - llm 只跑单轮 chat（maxTurns=1）
  * ============================================================
  */
-import { runQuery } from '../../../../src/loop.js';
-import { interpolate } from '../expressions.js';
-import { describeCaptureContract, interpretMiniReActResult, } from '../agentCommon.js';
+import { describeCaptureContract, describeLlmFailure, describeMaxTurnsCutoff, effectiveGoalAnchor, interpretMiniReActResult, runStepQuery, } from '../agentCommon.js';
+import { evalExpr, interpolate } from '../expressions.js';
+import { resolveWorkflowMultimodalOptions } from '../multimodal.js';
 /**
  * 执行一个 agent 步骤：构造 step prompt → 委托 runQuery(TAOR) → 提取结果。
  *
@@ -31,54 +31,143 @@ import { describeCaptureContract, interpretMiniReActResult, } from '../agentComm
  *   4. yield UI 事件（text_delta / tool_start / tool_end / ...）
  */
 export async function* execAgentStep(step, vars, ctx) {
-    const maxTurns = step.maxTurns ?? 12;
+    // 默认 25（与 skill 步 skill.ts 对齐）。agent 步本就是「开放多工具任务」执行器，
+    // 弱模型常一轮只调一个工具（Read/Grep/Glob 各占一轮），旧默认 12 对探索类步骤
+    // （如 plan.yaml stage1_research）太紧——12 轮还没收集完就撞顶截断、误判失败。
+    // 这是安全阀不是性能阀；要更紧的步显式写小值即可。
+    const maxTurns = step.maxTurns ?? 25;
+    // 未定义变量插值可见化（裸 ${goal} 这类拼写/命名空间错的病根，静默空串会坑死下游）
+    const missing = [];
+    const iopts = { onMissing: (e) => missing.push(e) };
     // 构造用户提示：包含步骤指令 + 变量 + capture 约束 + 内部标记防护
-    const userPrompt = interpolate(step.agent ?? '', vars) +
-        describeCaptureContract(step) +
-        (step.input ? `\n\n上下文变量：${interpolate(step.input, vars)}` : '') +
-        '\n\n⚠️ 输出规范：直接输出你的工作成果即可，不要在输出中包含任何类似「放弃」、' +
-        '「GIVEUP」、' +
-        '「__AGENT__」或' +
-        '「[wf-internal」的内部标记文本。';
+    const userPrompt = `${interpolate(step.agent ?? '', vars, iopts)}${describeCaptureContract(step)}${step.input ? `\n\n上下文变量：${interpolate(step.input, vars, iopts)}` : ''}\n\n⚠️ 输出规范：直接输出你的工作成果即可，不要在输出中包含任何类似「放弃」、「GIVEUP」、「__AGENT__」或「[wf-internal」的内部标记文本。`;
     // 如果有 output_schema，把 schema 约束嵌入 prompt（runQuery 不原生支持 responseFormat）
     const schemaHint = step.output_schema
         ? `\n\n【结构化输出约束】请严格按照以下 JSON Schema 输出结果（不要包裹在 markdown 代码块中）：\n${JSON.stringify(step.output_schema, null, 2)}`
         : '';
     const fullPrompt = userPrompt + schemaHint;
-    // 通用目标锚定：如果 runner 提供了 goalAnchor（从 inputs 自动提取），
-    // 前置注入到 prompt。确保每步 LLM 都能看到用户原始目标，
+    // 通用目标锚定（原始目标 + 累积的用户补充要求），前置注入 prompt。
+    // 确保每步 LLM 都能看到用户原始目标与运行中的补充要求，
     // 避免长上下文 / fresh_context 导致目标被稀释或遗忘。
-    const effectivePrompt = ctx.goalAnchor
-        ? `${ctx.goalAnchor}\n\n${fullPrompt}`
-        : fullPrompt;
-    // 记录 runQuery 开始前的 history 长度，用于之后提取本步的 assistant 输出
-    const historyLenBefore = ctx.history.length;
-    // 委托 TAOR 引擎执行（携带 sessionState 以启用上下文压缩）
-    yield* runQuery(effectivePrompt, {
-        provider: ctx.provider,
-        history: ctx.history,
-        signal: ctx.signal,
+    const anchor = effectiveGoalAnchor(ctx);
+    const effectivePrompt = anchor ? `${anchor}\n\n${fullPrompt}` : fullPrompt;
+    const multimodal = resolveWorkflowMultimodalOptions(step, vars, ctx, (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）`,
+        };
+    }
+    // 委托 TAOR 引擎执行（共享消费层 runStepQuery：携带 sessionState 以启用上下文压缩，
+    // 并统一侦测终结错误——runQuery 遇 LLM 失败是 yield error 后 return 不 throw）。
+    const { rawText, sawToolCall, toolNames, toolOkCount, toolFailCount, aborted, sawLlmError, sawMaxTurns, llmErrorDetail, } = yield* runStepQuery(effectivePrompt, step, ctx, {
         maxTurns,
-        chat: ctx.chat,
-        executeTool: ctx.executeTool,
-        sessionState: ctx.sessionState,
+        ...multimodal,
     });
-    // 从 history 中提取本步产生的最后一条 assistant message 内容（用于 capture 绑定）
-    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 stepResult = {
         raw: { text: rawText, result: rawText },
         preview: rawText.length > 200 ? `${rawText.slice(0, 200)}...` : rawText,
     };
+    // 用户中断导致的空产出：不过验证闸门（否则会误抛「放弃: 没有产出任何结果」），
+    // 直接返回当前（可能为空的）结果，由 runner 据 signal.aborted 收口（不当作可重试失败）。
+    if (aborted)
+        return stepResult;
+    // P0-1（同 llm.ts / skill.ts）：LLM 失败（超时/网络错）且本步无任何产出 →
+    // 抛「可重试失败」交给 runner 的 in-run retry。必须在验证闸门之前——
+    // 否则 provider 故障会被闸门误归因为「agent 步骤放弃: 没有产出任何结果」，
+    // 混淆「provider 失败（该重试）」与「模型真放弃/空答（诚实 halt）」。
+    if (!rawText.trim() && sawLlmError) {
+        // 抛错文案附带 provider 真实报错（经 runner 落 progress.md，刷屏后仍可排障）
+        throw new Error(describeLlmFailure(step.id, llmErrorDetail));
+    }
+    // 撞 maxTurns 截断：截断时刻的文本是半截工作叙述，不是可信交付——
+    // 即使非空也不能过闸门（曾被静默当成功：半成品 PPTX 被整条链当真交付）。
+    // 抛可重试失败 → in-run retry 在共享 history 上续作（模型看到已有进度接着干）。
+    if (sawMaxTurns) {
+        throw new Error(describeMaxTurnsCutoff(step.id, maxTurns));
+    }
+    // done_when 验收兜底（K3/A2）：弱模型常「宣告要干活」却不调工具就 end_turn
+    //（announce-not-do，2026-06-12 plan 工作流实跑事故的执行步烂尾根因之一）。
+    // yaml 作者声明确定性完成条件（如 fileExists('./doc/x.pptx')），不满足时
+    // 引擎自动 nudge 同一 agent 在共享 history 上继续干（看得到自己刚才的半截工作），
+    // 把「对抗模型不可靠」从每个 yaml 的 prompt 工程收回引擎单点。
+    if (step.done_when) {
+        const NUDGES = 2; // 提醒上限：超过说明模型真干不动，交给 onError/max_retries
+        let result = resultIfTextLooksDeliverable(step, rawText);
+        let lastOutcome = {
+            rawText,
+            sawToolCall,
+            toolNames,
+            toolOkCount,
+            toolFailCount,
+        };
+        for (let n = 0;; n++) {
+            if (evalDoneWhen(step, vars)) {
+                return result ?? doneWhenSatisfiedResult(step);
+            }
+            if (n >= NUDGES) {
+                throw new Error(`agent 步骤 "${step.id}" 完成条件未满足（done_when: ${step.done_when}），已提醒 ${NUDGES} 次仍未达成。${describeAttemptForDoneWhen(lastOutcome)}`);
+            }
+            yield {
+                type: 'warning',
+                message: `⏩ step "${step.id}" 完成条件未满足（${step.done_when}），提醒 agent 继续执行（第 ${n + 1}/${NUDGES} 次）。${describeAttemptForDoneWhen(lastOutcome)}`,
+            };
+            const nudge = yield* runStepQuery(`检查发现这一步还没有真正完成：完成条件 \`${step.done_when}\` 仍不成立。不要解释、不要宣告计划——继续实际执行（调用工具落盘/操作），直到完成条件成立，然后给出简短完成报告。`, step, ctx, { maxTurns });
+            if (nudge.aborted)
+                return result ?? stepResult;
+            if (!nudge.rawText.trim() && nudge.sawLlmError) {
+                throw new Error(describeLlmFailure(step.id, nudge.llmErrorDetail));
+            }
+            if (nudge.sawMaxTurns) {
+                throw new Error(describeMaxTurnsCutoff(step.id, maxTurns));
+            }
+            lastOutcome = nudge;
+            if (nudge.rawText.trim()) {
+                result = resultIfTextLooksDeliverable(step, nudge.rawText) ?? result;
+            }
+        }
+    }
+    // 验证闸门：判断结果是"真交付"还是"放弃"。注意：带 done_when 的步骤已在上方
+    // 由确定性条件验收，避免"文件已落盘但最终空文本"或"还没落盘但空文本"绕过 nudge。
     const outcome = interpretMiniReActResult(stepResult, !!step.output_schema);
     if (!outcome.ok)
         throw new Error(`agent 步骤放弃: ${outcome.reason}`);
     return outcome.value;
 }
+function evalDoneWhen(step, vars) {
+    try {
+        return Boolean(evalExpr(step.done_when ?? '', vars));
+    }
+    catch (e) {
+        // 表达式坏了是 yaml 作者错误：响亮失败（同 max_iterations 解析失败哲学），
+        // 不能静默当 false 把好结果 nudge 死、也不能静默当 true 放走烂尾。
+        throw new Error(`step "${step.id}" 的 done_when 表达式求值失败: ${e.message}`);
+    }
+}
+function doneWhenSatisfiedResult(step) {
+    const text = `完成条件已满足：${step.done_when}`;
+    return { raw: { text, result: text, content: text }, preview: text };
+}
+function resultIfTextLooksDeliverable(step, text) {
+    if (!text.trim())
+        return null;
+    const outcome = interpretMiniReActResult({
+        raw: { text, result: text },
+        preview: text.length > 200 ? `${text.slice(0, 200)}...` : text,
+    }, !!step.output_schema);
+    return outcome.ok ? outcome.value : null;
+}
+function describeAttemptForDoneWhen(outcome) {
+    const textState = outcome.rawText.trim()
+        ? '本轮有文本报告'
+        : '本轮没有文本报告';
+    if (!outcome.sawToolCall) {
+        return `${textState}，且没有观察到工具调用；请不要只宣告计划，必须调用工具完成产物。`;
+    }
+    const names = outcome.toolNames.length ? outcome.toolNames.join('、') : '未知工具';
+    const wrote = outcome.toolNames.some((name) => ['Write', 'Edit', 'MultiEdit', 'Bash'].includes(name));
+    const writeHint = wrote
+        ? '已观察到写入类工具调用，但完成条件仍未满足，请检查路径或实际写入结果'
+        : '未观察到写入类工具调用，请立即调用 Write/Edit/Bash 落盘产物';
+    return `${textState}；本轮工具调用：${names}（成功 ${outcome.toolOkCount}，失败 ${outcome.toolFailCount}）。${writeHint}。`;
+}

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

@@ -1,6 +1,6 @@
 /**
  * ============================================================
- *  src/workflows/stepExecutors/assert.ts —— assert step 执行
+ *  plugins/workflow-runner/src/stepExecutors/assert.ts —— assert step 执行
  * ------------------------------------------------------------
  *  evalExpr(condition) → 真值通过；假值抛错（带 onFail 自定义信息）。
  *
@@ -28,7 +28,8 @@ export function execAssertStep(step, vars, ctx) {
     }
     // ════ v0.9.3：上下文统一 —— assert 通过也留痕 ════
     // 让后续 LLM 步骤知道某个前置条件/不变量已确认满足。
-    if (ctx?.history) {
+    // ctx 必填（签名强制，runner 唯一调用点 dispatchActionStep 始终传），直接访问 history。
+    if (ctx.history) {
         ctx.history.push({
             role: 'assistant',
             content: `[workflow:${step.id}] ✅ 断言通过：${step.condition}`,

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

@@ -6,8 +6,8 @@
  *  （runQuery / src/loop.ts）执行。
  *
  *  与 agent 步的区别：
- *    - llm 默认单轮（maxTurns=1），不期望工具调用（但 runQuery 允许模型自主决定）
- *    - 有 context_files 时允许少量轮次读取文件后输出
+ *    - llm 默认单轮（maxTurns=1），不下发工具
+ *    - 有 context_files 或 allowed_tools 时允许少量轮次读取文件后输出
  *    - output_schema 嵌入 prompt 作为结构化约束
  *    - 不经过 interpretMiniReActResult 验证闸门（直接信任 LLM 输出）
  *
@@ -16,19 +16,23 @@
  *    - `{ <field>: var_name }` 当 output_schema 存在时按 JSON 字段取值
  * ============================================================
  */
-import { runQuery } from '../../../../src/loop.js';
-import { extractJsonPayload } from '../jsonPayload.js';
+import { describeLlmFailure, describeMaxTurnsCutoff, effectiveGoalAnchor, runStepQuery, } from '../agentCommon.js';
 import { interpolate } from '../expressions.js';
+import { extractJsonPayload } from '../jsonPayload.js';
+import { resolveWorkflowMultimodalOptions } from '../multimodal.js';
 export async function* execLlmStep(step, vars, ctx) {
     if (typeof step.llm !== 'string')
         throw new Error(`step ${step.id}: 缺少 llm 字段`);
-    const prompt = interpolate(step.llm, vars);
+    // 未定义变量插值可见化（静默空串是下游 prompt 留白的病根）
+    const missing = [];
+    const iopts = { onMissing: (e) => missing.push(e) };
+    const prompt = interpolate(step.llm, vars, iopts);
     // 有 context_files → 在 prompt 中附上文件列表，runQuery 的 TAOR 循环中
     // 模型可自主用 Read 工具读取（ALL_TOOLS 全量可用）
     let fullPrompt = prompt;
     if (step.context_files && step.context_files.length > 0) {
         const fileList = step.context_files
-            .map((f) => `- ${interpolate(f.path, vars)}${f.hint ? ` — ${f.hint}` : ''}`)
+            .map((f) => `- ${interpolate(f.path, vars, iopts)}${f.hint ? ` — ${f.hint}` : ''}`)
             .join('\n');
         fullPrompt = `${prompt}\n\n**以下上下文文件可用，请用 Read 工具按需读取**：\n${fileList}`;
     }
@@ -37,34 +41,38 @@ export async function* execLlmStep(step, vars, ctx) {
         ? `\n\n【结构化输出约束】请严格按照以下 JSON Schema 输出有效 JSON 对象本身（不要 markdown 代码块包裹）：\n${JSON.stringify(step.output_schema, null, 2)}`
         : '';
     fullPrompt += schemaHint;
-    // 通用目标锚定：同 agent.ts，确保每步 LLM 不偏离原始目标
-    const effectivePrompt = ctx.goalAnchor
-        ? `${ctx.goalAnchor}\n\n${fullPrompt}`
-        : fullPrompt;
-    // llm 步默认单轮；有 context_files 时允许多轮（读文件→输出）
+    // 通用目标锚定（原始目标 + 补充要求）：同 agent.ts，确保每步 LLM 不偏离
+    const anchor = effectiveGoalAnchor(ctx);
+    const effectivePrompt = anchor ? `${anchor}\n\n${fullPrompt}` : fullPrompt;
+    const needsTools = !!step.context_files?.length || step.allowed_tools !== undefined;
+    const queryStep = needsTools ? step : { ...step, allowed_tools: [] };
+    // llm 步默认单轮；需要工具时允许多轮（读文件→输出）
     const maxTurns = step.maxTurns ?? (step.context_files?.length ? 10 : 1);
-    // 记录 history 长度用于提取本步输出
-    const historyLenBefore = ctx.history.length;
-    // 委托 TAOR 引擎执行（携带 sessionState 以启用上下文压缩）
-    yield* runQuery(effectivePrompt, {
-        provider: ctx.provider,
-        history: ctx.history,
-        signal: ctx.signal,
+    const multimodal = resolveWorkflowMultimodalOptions(step, vars, ctx, (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）`,
+        };
+    }
+    // 委托 TAOR 引擎执行（共享消费层 runStepQuery：携带 sessionState 以启用上下文压缩，
+    // 并统一侦测终结错误——runQuery 遇 LLM 失败是 yield error 后 return 不 throw，
+    // 直透会让本步静默返回空文本、runner 的 in-run retry 不触发 → 产出空如空 PLAN.md）。
+    const { rawText, aborted, sawLlmError, sawMaxTurns, llmErrorDetail } = yield* runStepQuery(effectivePrompt, queryStep, ctx, {
         maxTurns,
-        chat: ctx.chat,
-        executeTool: ctx.executeTool,
-        sessionState: ctx.sessionState,
+        ...multimodal,
     });
-    // 从 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();
+    // P0-1：LLM 失败（超时/网络错）且本步无任何产出 → 抛异常，触发 runner 的 max_retries 重跑。
+    // 必须放在 output_schema 解析之前（空文本本就无法解析），且只在 !aborted 时抛
+    // （用户中断不该被当成可重试失败；aborted 时按现状返回空结果即可）。
+    if (!trimmed && sawLlmError && !aborted) {
+        throw new Error(describeLlmFailure(step.id, llmErrorDetail));
+    }
+    // 撞 maxTurns 截断 → 截断时产出不可信，抛可重试失败（续作语义，同 agent.ts）
+    if (sawMaxTurns && !aborted) {
+        throw new Error(describeMaxTurnsCutoff(step.id, maxTurns));
+    }
     // 结构化输出模式：解析 JSON
     if (step.output_schema) {
         const payload = extractJsonPayload(trimmed);

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

@@ -17,8 +17,8 @@
  */
 import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { runQuery } from '../../../../src/loop.js';
 import { getResourceSearchPaths } from '../../../../src/plugin-sdk.js';
+import { describeLlmFailure, describeMaxTurnsCutoff, effectiveGoalAnchor, runStepQuery, } from '../agentCommon.js';
 import { interpolate } from '../expressions.js';
 function stripFrontmatter(content) {
     return content.replace(/^---\n[\s\S]*?\n---\n?/, '');
@@ -33,10 +33,7 @@ function parseFrontmatterName(content) {
     return nm[1].trim().replace(/^["']|["']$/g, '');
 }
 async function findSkillFile(skillName, cwd) {
-    const roots = getResourceSearchPaths('skills', import.meta.url);
-    // 优先搜索 cwd/skills（工作目录下的 skills 优先于包内 skills）
-    const cwdSkills = join(cwd, 'skills');
-    roots.unshift(cwdSkills);
+    const roots = getResourceSearchPaths('skills', import.meta.url, cwd);
     for (const root of roots) {
         let entries;
         try {
@@ -76,46 +73,38 @@ export async function* execSkillStep(step, vars, ctx) {
     // 构造用户提示：skill 指令 + 步骤 input
     // 系统提示词已在 history[0] 中（含完整 skill 列表和描述），
     // 这里不需要再拼 system message——把 SKILL.md body 作为操作指令即可
+    const missing = [];
     const userInput = step.input
-        ? interpolate(step.input, vars)
+        ? interpolate(step.input, vars, { onMissing: (e) => missing.push(e) })
         : `请按以下 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;
+    // 通用目标锚定（原始目标 + 补充要求）：确保 skill 执行时也不偏离
+    const anchor = effectiveGoalAnchor(ctx);
+    const effectivePrompt = anchor ? `${anchor}\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: ctx.history,
-        signal: ctx.signal,
+    if (missing.length > 0) {
+        yield {
+            type: 'warning',
+            message: `step "${step.id}": 模板变量未定义，已按空串插值：${[...new Set(missing)].map((m) => `\${${m}}`).join('、')}（裸名请用 inputs.<name> 或先 capture/set）`,
+        };
+    }
+    // 委托 TAOR 引擎在共享 history 上执行（共享消费层 runStepQuery）。
+    // suppressTurnDone：turn_done 是 runQuery 单次调用的终结标记，不是 workflow 终结，
+    // 外泄会导致 gateway broker / -p json 模式误判 workflow 中途结束。
+    const { rawText, aborted, sawLlmError, sawMaxTurns, llmErrorDetail } = yield* runStepQuery(effectivePrompt, step, ctx, {
         maxTurns,
-        chat: ctx.chat,
-        executeTool: ctx.executeTool,
-        sessionState: ctx.sessionState,
-    })) {
-        // turn_done 是 runQuery 单次调用的终结标记，不是 workflow 终结。
-        // 外泄会导致 gateway broker / -p json 模式误判 workflow 中途结束。
-        if (ev.type === 'turn_done')
-            continue;
-        // error / interrupted 应该冒泡让 runner 处理
-        yield ev;
+        suppressTurnDone: true,
+    });
+    const trimmed = rawText.trim();
+    // P0-1：LLM 失败（超时/网络错）且本步无任何产出 → 抛异常，触发 runner 的 max_retries 重跑。
+    // 用户中断（aborted）不该被当成可重试失败，按现状返回空结果即可。
+    if (!trimmed && sawLlmError && !aborted) {
+        throw new Error(describeLlmFailure(step.id, llmErrorDetail));
     }
-    // 从 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;
-        }
+    // 撞 maxTurns 截断 → 截断时产出不可信，抛可重试失败（续作语义，同 agent.ts）
+    if (sawMaxTurns && !aborted) {
+        throw new Error(describeMaxTurnsCutoff(step.id, maxTurns));
     }
-    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

@@ -1,6 +1,6 @@
 /**
  * ============================================================
- *  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 处理。
@@ -21,7 +21,9 @@
  *    - `{ 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)
@@ -29,7 +31,17 @@ export async function* execToolStep(step, vars, ctx) {
     const tool = getToolByName(step.tool);
     if (!tool)
         throw new Error(`step ${step.id}: 未知工具 "${step.tool}"`);
-    const args = interpolateDeep(step.args ?? {}, vars);
+    // 未定义变量插值可见化（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;
@@ -40,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',
@@ -70,6 +90,39 @@ export async function* execToolStep(step, vars, ctx) {
         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 行用）。
  */

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,27 +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) {
-    // 兼容两种格式：YAML 数组 或逗号分隔字符串
+    // 兼容两种格式：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;
+        rawChecks = step.checks
+            .flatMap((s) => interpolate(s, vars).split(','))
+            .map((s) => s.trim())
+            .filter(Boolean);
     }
     else if (typeof step.checks === 'string' && step.checks.trim() !== '') {
-        rawChecks = step.checks.split(',').map((s) => s.trim()).filter(Boolean);
+        rawChecks = interpolate(step.checks, vars)
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean);
     }
     else {
         throw new Error(`step ${step.id}: verify 缺少 checks（需要数组或逗号分隔字符串）`);
     }
-    // 解析并插值每条 check 字符串
+    // 解析每条已插值的 check 字符串（插值后若整体为空——如 ${verify_checks} 取到空串——
+    // 则 checks 为空，runVerification 视为"无检查项"通过；ralph-loop 另有 when 守卫不会走到这）
     const checks = [];
     for (const raw of rawChecks) {
-        const interpolated = interpolate(raw, vars);
-        const check = parseCheckString(interpolated);
+        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);
     }