minimal-agent 0.10.0 → 0.12.0

package/plugins/workflow-runner/plugin.ts

@@ -0,0 +1,113 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/plugin.ts
+ * ------------------------------------------------------------
+ *  workflow-runner 插件入口。接管 /workflow 与 /workflows 两个命令的执行：
+ *  不走声明式 markdown→LLM 通道，而是直接调插件内置的 YAML DAG 执行器。
+ *
+ *  执行器与全部依赖都住在本插件目录 ./src/，外部 src/ 一行不改。
+ *  插件只通过 src/plugin-sdk.ts 取框架运行时（runQuery / chat / executeTool 等）。
+ *
+ *  契约：default export 一个 PluginApi 对象。框架 pluginLoader 会按 pluginRoot
+ *  缓存这次 import，所以 cold start 后 dynamic import 只跑一次。
+ * ============================================================
+ */
+
+import type { PluginApi } from '../../src/plugin-sdk.js';
+import {
+  ALL_TOOLS,
+  buildTransientPromptBundle,
+  createAgentRuntimeContext,
+  derivePromptCacheContext,
+  filterToolsForRuntime,
+  getWorkingDir,
+} from '../../src/plugin-sdk.js';
+import { runWorkflowFromCommand, runWorkflowsList } from './src/index.js';
+
+const api: PluginApi = {
+  async *runCommand(commandName, args, ctx) {
+    if (commandName === 'workflows') {
+      yield* runWorkflowsList();
+      return;
+    }
+
+    if (commandName === 'workflow') {
+      const cwd = getWorkingDir();
+      const workflowRuntime = createAgentRuntimeContext({
+        ...(ctx.runtimeContext ?? {
+          profile: 'main' as const,
+          interactiveAsk: false,
+        }),
+        // The command runs inside the workflow's async-scoped workspace. A
+        // parent Desktop/CLI runtime may have been created before that scope.
+        cwd,
+        surface: 'workflow',
+        owner: ctx.runtimeContext?.owner ?? 'untrusted',
+        memoryAccess:
+          ctx.runtimeContext?.memoryAccess === 'denied'
+            ? 'denied'
+            : 'read-only',
+      });
+      const hostToolNames = ctx.allowedTools
+        ? new Set(ctx.allowedTools)
+        : undefined;
+      const hostTools = hostToolNames
+        ? ALL_TOOLS.filter((tool) => hostToolNames.has(tool.name))
+        : ALL_TOOLS;
+      const workflowTools = filterToolsForRuntime(hostTools, workflowRuntime);
+      const transientBundle =
+        ctx.transientBundle ??
+        (await buildTransientPromptBundle({
+          cwd,
+          tools: workflowTools,
+          profile: 'main',
+          includeProjectInstructions: true,
+          includePlugins: true,
+          runtime: {
+            surface: 'workflow',
+            cwd,
+            workspaceId: workflowRuntime.workspaceId,
+            interactiveAsk: workflowRuntime.interactiveAsk,
+            memoryAccess: workflowRuntime.memoryAccess,
+            currentUserInput: args,
+          },
+        }).catch(() => undefined));
+      yield* runWorkflowFromCommand(args, {
+        provider: ctx.provider,
+        history: ctx.history,
+        signal: ctx.signal,
+        sessionState: ctx.sessionState,
+        cwd,
+        tools: workflowTools,
+        runtimeContext: workflowRuntime,
+        executeTool: ctx.executeTool,
+        toolContext: {
+          history: ctx.history,
+          sessionState: ctx.sessionState,
+          provider: ctx.provider,
+          toolGate: ctx.host?.toolGate,
+          promptCache: ctx.promptCache,
+          workspaceId: workflowRuntime.workspaceId,
+          sessionId: workflowRuntime.sessionId,
+          memoryAccess: workflowRuntime.memoryAccess,
+        },
+        // 宿主授权上下文原样带上；引擎按各步 `uses:` 切片后才转给工具，不整份下发。
+        host: ctx.host,
+        transientContext: ctx.transientContext,
+        transientBundle,
+        promptCache: derivePromptCacheContext(
+          ctx.promptCache,
+          `workflow:${args.trim() || 'interactive'}`,
+        ),
+      });
+      return;
+    }
+
+    yield {
+      type: 'error',
+      error: `workflow-runner: 未知命令 /${commandName}`,
+    };
+  },
+};
+
+export default api;

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

@@ -19,7 +19,8 @@
  *       ③ 检测逻辑增加内容长度启发式（reason > 80 字符视为误报）
  * ============================================================
  */
-import { runQuery, stripThinkBlocks, } from '../../../src/plugin-sdk.js';
+import { createAgentRuntimeContext, runQuery, stripThinkBlocks, } from '../../../src/plugin-sdk.js';
+import { effectiveWorkflowCwd } from './toolRuntime.js';
 import { normalizeCapture, } from './types.js';
 /**
  * agent 显式放弃的唯一标记；recover 与 agent 节点共用。
@@ -59,7 +60,9 @@ export function effectiveGoalAnchor(ctx) {
     if (supps.length === 0)
         return base;
     const lines = supps.map((s) => `> 📌 用户补充要求：${s}`).join('\n');
-    return base ? `${base}\n${lines}` : `${lines}\n> ⚠️ 以上补充要求与原始目标同等约束所有操作。`;
+    return base
+        ? `${base}\n${lines}`
+        : `${lines}\n> ⚠️ 以上补充要求与原始目标同等约束所有操作。`;
 }
 /** 把 llm_error 细节拼进可重试失败的抛错文案（无细节时退化为原样文案）。 */
 export function describeLlmFailure(stepId, detail) {
@@ -95,8 +98,23 @@ function createStepHistory(step, ctx) {
  */
 export async function* runStepQuery(prompt, step, ctx, opts) {
     const activeHistory = createStepHistory(step, ctx);
+    const availableTools = ctx.tools ?? [];
+    const hostToolNames = new Set(availableTools.map((tool) => tool.name));
+    const effectiveStepTools = step.allowed_tools === undefined
+        ? [...hostToolNames]
+        : step.allowed_tools.filter((name) => hostToolNames.has(name));
     // 记录 runQuery 开始前的 history 长度，用于之后提取本步的 assistant 输出
     const historyLenBefore = activeHistory.length;
+    const runtimeContext = createAgentRuntimeContext({
+        ...(ctx.runtimeContext ?? {
+            surface: 'workflow',
+            profile: 'main',
+            interactiveAsk: false,
+        }),
+        cwd: effectiveWorkflowCwd(ctx),
+        owner: ctx.runtimeContext?.owner ?? 'untrusted',
+        memoryAccess: ctx.runtimeContext?.memoryAccess ?? 'denied',
+    });
     let aborted = false;
     let sawLlmError = false;
     let sawMaxTurns = false;
@@ -107,10 +125,12 @@ export async function* runStepQuery(prompt, step, ctx, opts) {
     const toolNames = [];
     for await (const ev of runQuery(prompt, {
         provider: ctx.provider,
+        runtimeContext,
         history: activeHistory,
         signal: ctx.signal,
         maxTurns: opts.maxTurns,
-        allowedTools: step.allowed_tools,
+        allowedTools: effectiveStepTools,
+        requiredTools: step.allowed_tools === undefined ? undefined : effectiveStepTools,
         chat: ctx.chat,
         executeTool: ctx.executeTool,
         sessionState: ctx.sessionState,
@@ -118,6 +138,23 @@ export async function* runStepQuery(prompt, step, ctx, opts) {
         parseInlineImages: opts.parseInlineImages,
         imageDetail: opts.imageDetail,
         imageMaxLongSidePixel: opts.imageMaxLongSidePixel,
+        transientContext: ctx.transientContext,
+        transientBundle: ctx.transientBundle,
+        promptCache: ctx.promptCache,
+        // ⚠️ 宿主授权上下文必须跟着走 —— 这是与 `stepExecutors/tool.ts` 同一处遗漏的
+        // 另一半：tool 步补上了、agent/llm/skill 步没补的话，「让 agent 随机应变操作
+        // 电脑」这类步骤照样恒失败，而且症状与 tool 步完全一样、更难定位。
+        //
+        // 这里**整份下发**而不是像 tool 步那样按 `uses:` 切片，是有意的：agent 步本就是
+        // 「把判断权交给模型」的节点，它要用哪个工具由模型临场决定，事先切片等于让
+        // yaml 作者预测模型的选择。约束改由 `allowed_tools`（上面那行）承担 —— 那是
+        // agent 步既有的、更贴合其语义的收敛手段。
+        ...(ctx.host?.computerRun ? { computerRun: ctx.host.computerRun } : {}),
+        ...(ctx.host?.computerIntervention
+            ? { computerIntervention: ctx.host.computerIntervention }
+            : {}),
+        ...(ctx.host?.browserRun ? { browserRun: ctx.host.browserRun } : {}),
+        ...(ctx.host?.toolGate ? { toolGate: ctx.host.toolGate } : {}),
     })) {
         if (ev.type === 'error') {
             if (ev.code === 'aborted') {
@@ -245,7 +282,9 @@ function isLikelyFalsePositive(reason) {
     if (reason.length > 80)
         return true;
     // 如果 reason 看起来像 markdown 正文（标题/章节），也是误报
-    if (/^#{1,6}\s/m.test(reason) || /^[-*+]\s/m.test(reason) || /^\d+\.\s/m.test(reason)) {
+    if (/^#{1,6}\s/m.test(reason) ||
+        /^[-*+]\s/m.test(reason) ||
+        /^\d+\.\s/m.test(reason)) {
         return true;
     }
     return false;

package/plugins/workflow-runner/src/agentCommon.ts

@@ -0,0 +1,435 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/src/agentCommon.ts —— workflow 内「有界 agent」的共享工具
+ * ------------------------------------------------------------
+ *  工作流里有两处会临时起一个 agent（runQuery 执行后的验证闸门）：
+ *    - onError:'recover'（recovery.ts）—— 节点失败后救火
+ *    - agent: 节点（stepExecutors/agent.ts）—— 作者显式声明的开放任务
+ *  二者本质同构：受工作流目标/上下文指导、用工具随机应变、产出经验证后回灌 capture。
+ *  为避免「同一个脑子写两份提示词、行为漂移」，这里收敛它们的**共享件**：
+ *    1. 统一验证闸门（interpretMiniReActResult）—— runQuery 执行完后，判定「真交付」还是
+ *       「放弃/不可信」，**永不把没验证过的产出当成功**。这是 Phase 2 验证闸门的提取。
+ *
+ *  ⚠️ GIVEUP 标记设计原则（v0.9.3 修复 LLM 误触发问题）：
+ *     旧标记 __AGENT_GIVEUP__ 使用 __XXX__ 格式，MiniMax/GPT 等模型容易在输出中
+ *    幻觉出类似标记（如 "__AGENT_GIVEUP__: since I did the work..."），导致已完成的工作
+ *    被误判为"放弃"而 halt。新标记采用三重防误触发设计：
+ *       ① 非标准格式（非 __XXX__，LLM 训练数据中几乎不存在）
+ *       ② 含明确的 "DO-NOT-GENERATE" 警告文本
+ *       ③ 检测逻辑增加内容长度启发式（reason > 80 字符视为误报）
+ * ============================================================
+ */
+
+import {
+  type ImageDetail,
+  type ImageInputSpec,
+  type LoopEvent,
+  type Message,
+  createAgentRuntimeContext,
+  runQuery,
+  stripThinkBlocks,
+} from '../../../src/plugin-sdk.js';
+import { effectiveWorkflowCwd } from './toolRuntime.js';
+import {
+  type RunContext,
+  type StepDef,
+  type StepResult,
+  normalizeCapture,
+} from './types.js';
+
+/**
+ * agent 显式放弃的唯一标记；recover 与 agent 节点共用。
+ *
+ * 设计约束（纯 ASCII，避免 Unicode 编码匹配问题）：
+ *   - 不使用 __XXX__ 格式（LLM 容易幻觉模仿）
+ *   - 含 "wf-internal" 前缀 + "do-not-generate" 明确警告
+ *   - 使用 [bracket] 格式而非 ⟨angle⟩（避免 Unicode 字符在 Bun indexOf 中行为不一致）
+ */
+export const GIVEUP_MARKER = '[wf-internal-abort-do-not-generate]';
+
+/** 有界 agent 的判定结果：真交付带 value、放弃/不可信带 reason（调用方据此继续或 honest halt）。 */
+export type AgentOutcome =
+  | { ok: true; value: StepResult }
+  | { ok: false; reason: string };
+
+/** 把 step.capture 翻成「下游会把你的结果存成哪些变量」，让 agent 产出对得上形状。
+ *  经 normalizeCapture：裸字符串 capture（capture: design_doc）不再被拆成单字符
+ *  【d、e、s…】，而是正确显示为【design_doc】。 */
+export function describeCaptureContract(step: StepDef): string {
+  const names = Object.values(normalizeCapture(step.capture));
+  if (names.length === 0) return '';
+  return `\n\n下游契约：工作流会把你的结果保存为变量【${names.join('、')}】供后续步骤引用，请确保你的产出能填好这些变量。`;
+}
+
+export function truncate(s: string, n: number): string {
+  return s.length > n ? `${s.slice(0, n)}…` : s;
+}
+
+// stripThinkBlocks 已上移内核 src/utils/stripThink.ts（Agent 子任务工具同样需要，
+// 内核不能 import 插件）——顶部 import 供本模块使用，此处 re-export 保持插件内
+// 既有 import 路径不变。
+export { stripThinkBlocks };
+
+/**
+ * 组合「原始目标锚 + 累积的用户补充要求」为本步实际注入的锚定文本。
+ * agent / llm / skill / recovery 四个执行器统一经此取锚——补充要求
+ * （pause 审批反馈 / goal_supplement 步产出 / 仲裁延续的新指令）与原始目标
+ * 同等贯穿每一步，不再只活在被修订的文件或某个变量里。
+ * 返回空串 = 无锚（执行器跳过注入，行为同旧 ctx.goalAnchor 为空）。
+ */
+export function effectiveGoalAnchor(ctx: RunContext): string {
+  const base = ctx.goalAnchor ?? '';
+  const supps = (ctx.goalSupplements ?? []).filter((s) => s.trim());
+  if (supps.length === 0) return base;
+  const lines = supps.map((s) => `> 📌 用户补充要求：${s}`).join('\n');
+  return base
+    ? `${base}\n${lines}`
+    : `${lines}\n> ⚠️ 以上补充要求与原始目标同等约束所有操作。`;
+}
+
+/** runStepQuery 的归纳结果：本步产出文本 + 终结性错误旗标（语义判断留给各执行器）。 */
+export interface StepQueryOutcome {
+  /** history 反查到的本步最后一条非空 assistant 文本（无则空串） */
+  rawText: string;
+  /** 本轮 runQuery 是否实际调用过工具。用于区分"空答"和"搜/读了但没落盘"。 */
+  sawToolCall: boolean;
+  /** 本轮实际调用过的工具名（按首次出现顺序去重）。 */
+  toolNames: string[];
+  /** 工具成功次数。 */
+  toolOkCount: number;
+  /** 工具失败次数。 */
+  toolFailCount: number;
+  /** 用户中断（code:'aborted'）—— 不可重试，执行器应按现状返回不抛错 */
+  aborted: boolean;
+  /** 终结性 LLM 失败（code:'llm_error'）—— 可重试，空产出时执行器应抛错触发 in-run retry */
+  sawLlmError: boolean;
+  /**
+   * 撞 maxTurns 被截断（code:'max_turns'）—— 模型还在干活时轮数预算耗尽。
+   * 截断时刻的产出是半截工作叙述而非可信交付，执行器应抛错触发 in-run retry——
+   * 重试在共享 history 上重跑 = 模型看到自己之前的进度**接着干**（续作语义），
+   * 每次重试等于再给一份轮数预算。曾被静默当成功：半成品 PPTX 被链路当真交付。
+   */
+  sawMaxTurns: boolean;
+  /**
+   * 最后一次 llm_error 事件的具体错误文案（provider 真实报错：超时/限流/5xx…）。
+   * 执行器抛错时务必附带——它会经 runner 落进 progress.md（↻/✗ 行）与 halt 文案，
+   * 是事后排障的唯一持久证据（TUI 红字刷屏即逝，没有这条就只剩「无产出」四个字）。
+   */
+  llmErrorDetail: string;
+}
+
+/** 把 llm_error 细节拼进可重试失败的抛错文案（无细节时退化为原样文案）。 */
+export function describeLlmFailure(stepId: string, detail: string): string {
+  const base = `step ${stepId}: LLM 调用失败且无产出（触发重试）`;
+  return detail ? `${base}—— ${truncate(detail, 300)}` : base;
+}
+
+function cloneMessage(msg: Message): Message {
+  if (msg.role === 'user' && Array.isArray(msg.content)) {
+    return { ...msg, content: msg.content.map((part) => ({ ...part })) };
+  }
+  return { ...msg };
+}
+
+function createStepHistory(step: StepDef, ctx: RunContext): Message[] {
+  if (step.history_mode !== 'isolated') return ctx.history;
+  return ctx.history.filter((msg) => msg.role === 'system').map(cloneMessage);
+}
+
+/**
+ * agent / llm / skill 三个执行器共享的 runQuery 消费层。
+ *
+ * 为什么不能各自 `yield*` 直透（曾经的三份拷贝、agent.ts 漏同步酿成误报）：
+ *   runQuery 遇 LLM 超时/网络错是 yield error 后 return（不 throw），直透会让
+ *   执行器拿到空 history → 静默返回空文本 → runner 的 in-run retry 不触发
+ *   （只对抛异常的 step 重试）。这里统一显式消费、侦测终结错误，把
+ *   「拿产出 + 记旗标」收敛成一份；**空产出 + sawLlmError 时抛不抛错的语义
+ *   差异保留在各执行器**（agent 还要过验证闸门，llm/skill 不过）。
+ *
+ * 事件透传逐字节等价于重构前：
+ *   - error / interrupted 照常冒泡（红字照常显示，retry 交给 runner）
+ *   - 'compact_failed' 非致命，不计为失败
+ *   - suppressTurnDone（仅 skill 传 true）：turn_done 是 runQuery 单次调用的
+ *     终结标记，不是 workflow 终结，外泄会让 gateway broker / -p json 误判
+ */
+export async function* runStepQuery(
+  prompt: string,
+  step: StepDef,
+  ctx: RunContext,
+  opts: {
+    maxTurns: number;
+    suppressTurnDone?: boolean;
+    imageInputs?: ImageInputSpec[];
+    parseInlineImages?: boolean;
+    imageDetail?: ImageDetail;
+    imageMaxLongSidePixel?: number;
+  },
+): AsyncGenerator<LoopEvent, StepQueryOutcome, void> {
+  const activeHistory = createStepHistory(step, ctx);
+  const availableTools = ctx.tools ?? [];
+  const hostToolNames = new Set(availableTools.map((tool) => tool.name));
+  const effectiveStepTools =
+    step.allowed_tools === undefined
+      ? [...hostToolNames]
+      : step.allowed_tools.filter((name) => hostToolNames.has(name));
+  // 记录 runQuery 开始前的 history 长度，用于之后提取本步的 assistant 输出
+  const historyLenBefore = activeHistory.length;
+  const runtimeContext = createAgentRuntimeContext({
+    ...(ctx.runtimeContext ?? {
+      surface: 'workflow' as const,
+      profile: 'main' as const,
+      interactiveAsk: false,
+    }),
+    cwd: effectiveWorkflowCwd(ctx),
+    owner: ctx.runtimeContext?.owner ?? 'untrusted',
+    memoryAccess: ctx.runtimeContext?.memoryAccess ?? 'denied',
+  });
+
+  let aborted = false;
+  let sawLlmError = false;
+  let sawMaxTurns = false;
+  let llmErrorDetail = '';
+  let sawToolCall = false;
+  let toolOkCount = 0;
+  let toolFailCount = 0;
+  const toolNames: string[] = [];
+  for await (const ev of runQuery(prompt, {
+    provider: ctx.provider,
+    runtimeContext,
+    history: activeHistory,
+    signal: ctx.signal,
+    maxTurns: opts.maxTurns,
+    allowedTools: effectiveStepTools,
+    requiredTools:
+      step.allowed_tools === undefined ? undefined : effectiveStepTools,
+    chat: ctx.chat,
+    executeTool: ctx.executeTool,
+    sessionState: ctx.sessionState,
+    imageInputs: opts.imageInputs,
+    parseInlineImages: opts.parseInlineImages,
+    imageDetail: opts.imageDetail,
+    imageMaxLongSidePixel: opts.imageMaxLongSidePixel,
+    transientContext: ctx.transientContext,
+    transientBundle: ctx.transientBundle,
+    promptCache: ctx.promptCache,
+    // ⚠️ 宿主授权上下文必须跟着走 —— 这是与 `stepExecutors/tool.ts` 同一处遗漏的
+    // 另一半：tool 步补上了、agent/llm/skill 步没补的话，「让 agent 随机应变操作
+    // 电脑」这类步骤照样恒失败，而且症状与 tool 步完全一样、更难定位。
+    //
+    // 这里**整份下发**而不是像 tool 步那样按 `uses:` 切片，是有意的：agent 步本就是
+    // 「把判断权交给模型」的节点，它要用哪个工具由模型临场决定，事先切片等于让
+    // yaml 作者预测模型的选择。约束改由 `allowed_tools`（上面那行）承担 —— 那是
+    // agent 步既有的、更贴合其语义的收敛手段。
+    ...(ctx.host?.computerRun ? { computerRun: ctx.host.computerRun } : {}),
+    ...(ctx.host?.computerIntervention
+      ? { computerIntervention: ctx.host.computerIntervention }
+      : {}),
+    ...(ctx.host?.browserRun ? { browserRun: ctx.host.browserRun } : {}),
+    ...(ctx.host?.toolGate ? { toolGate: ctx.host.toolGate } : {}),
+  })) {
+    if (ev.type === 'error') {
+      if (ev.code === 'aborted') {
+        aborted = true;
+      } else if (ev.code === 'llm_error') {
+        sawLlmError = true;
+        llmErrorDetail = ev.error; // 留住 provider 真实报错，供执行器抛错时附带
+        // 🚫 不原样把这条 raw error 事件漏给顶层消费者（2026-07-04 真机事故：-p 模式
+        // 收到任意 type:'error' 就 handleEvent→exitCode:1→process.exit()，把整个 -p 进程
+        // 杀死在这里——比 runner.ts 的 in-run retry（max_retries/onError:continue）先一步
+        // 判定「终结」，等于跳过了整套设计好的重试/降级机制。这条信号已被上面两行转成
+        // sawLlmError/llmErrorDetail，稍后由本函数调用方（agent.ts 等）转成规范的可重试
+        // Error 抛出，交给 runner.ts 的 catch 块按 max_retries/onError 决定真正要不要终结、
+        // 要终结时也是由 runner.ts 在恰当时机重新 yield 一条 warning/error，不需要这条 raw 事件。
+        continue;
+      } else if (ev.code === 'max_turns') {
+        sawMaxTurns = true;
+        // 同上：max_turns 截断本是「可续跑」信号（isMaxTurnsCutoff），必须留给 runner.ts
+        // 的 in-run retry 先处理，不能原样漏给顶层当成终结。
+        continue;
+      }
+    } else if (
+      ev.type === 'warning' &&
+      ev.message.includes('finish_reason=length')
+    ) {
+      sawMaxTurns = true;
+    } else if (ev.type === 'tool_start') {
+      sawToolCall = true;
+      if (!toolNames.includes(ev.toolName)) toolNames.push(ev.toolName);
+    } else if (ev.type === 'tool_end') {
+      sawToolCall = true;
+      if (!toolNames.includes(ev.toolName)) toolNames.push(ev.toolName);
+      if (ev.ok) toolOkCount++;
+      else toolFailCount++;
+    }
+    if (opts.suppressTurnDone && ev.type === 'turn_done') continue;
+    yield ev;
+  }
+
+  // 从 history 提取本步产生的最后一条非空 assistant 消息。
+  // 经 stripThinkBlocks 净化：最后一条若是纯 <think> 块（模型收尾只剩思考），
+  // 继续向前回退到真正有内容的消息——capture/补充要求拿到的必须是交付文本。
+  let rawText = '';
+  for (let i = activeHistory.length - 1; i >= historyLenBefore; i--) {
+    const msg = activeHistory[i];
+    if (msg.role === 'assistant' && typeof msg.content === 'string') {
+      const cleaned = stripThinkBlocks(msg.content);
+      if (cleaned) {
+        rawText = cleaned;
+        break;
+      }
+    }
+  }
+
+  return {
+    rawText,
+    sawToolCall,
+    toolNames,
+    toolOkCount,
+    toolFailCount,
+    aborted,
+    sawLlmError,
+    sawMaxTurns,
+    llmErrorDetail,
+  };
+}
+
+/** maxTurns 截断失败文案的稳定标记（producer/detector 同源，防 runner 侧 delay 判定漂移）。 */
+export const MAX_TURNS_CUTOFF_MARKER = '达到最大轮数';
+
+/** maxTurns 截断的可重试失败文案（重试 = 在共享 history 上续作，再给一份轮数预算）。 */
+export function describeMaxTurnsCutoff(
+  stepId: string,
+  maxTurns: number,
+): string {
+  return `step ${stepId}: ${MAX_TURNS_CUTOFF_MARKER} ${maxTurns} 被截断（可续跑）`;
+}
+
+/**
+ * 该错误是否是 maxTurns 截断（续作语义）。runner 的 in-run retry 用它区分延时：
+ * maxTurns 截断默认立即续作，不套用普通 retry_delay_ms；长文档/PPT 类工作流
+ * 可显式配置 max_turns_retry_delay_ms 给截断续作增加等待窗口。
+ */
+export function isMaxTurnsCutoff(errMsg: string): boolean {
+  return errMsg.includes(MAX_TURNS_CUTOFF_MARKER) && errMsg.includes('被截断');
+}
+
+/**
+ * 解析非 schema 模式下 agent 最终文本里的放弃标记。
+ *   - 命中 GIVEUP_MARKER → 返回原因字符串（可能为空串）
+ *   - 未命中 → null（视为给出了真实结果）
+ *
+ * 注意：旧标记 __AGENT_GIVEUP__ 也兼容检测（向后兼容已存在的 checkpoint/状态数据），
+ * 但新代码只使用新标记格式。
+ */
+const LEGACY_GIVEUP_MARKER = '__AGENT_GIVEUP__';
+
+export function parseGiveup(text: string): string | null {
+  // 优先检测新标记
+  const newIdx = text.indexOf(GIVEUP_MARKER);
+  const legacyIdx = text.indexOf(LEGACY_GIVEUP_MARKER);
+
+  // 取先出现的那一个
+  let idx = -1;
+  let markerLen = 0;
+  if (newIdx !== -1 && (legacyIdx === -1 || newIdx < legacyIdx)) {
+    idx = newIdx;
+    markerLen = GIVEUP_MARKER.length;
+  } else if (legacyIdx !== -1) {
+    idx = legacyIdx;
+    markerLen = LEGACY_GIVEUP_MARKER.length;
+  }
+  if (idx === -1) return null;
+
+  return text
+    .slice(idx + markerLen)
+    .replace(/^[:：\s\]]+/, '') // 兼容新旧标记后的分隔符（: / : / ]）
+    .trim();
+}
+
+/** 判断一个 giveup reason 是否看起来像"误报"（实际是 LLM 在正常输出中碰巧触发了标记）。
+ *
+ * 启发式规则：
+ *   - reason 长度 > 80 字符 → 几乎可以确定是误报（真正的放弃原因通常简短）
+ *   - reason 包含结构化内容（如 ## 标题、### 章节、列表项等）→ 误报
+ */
+function isLikelyFalsePositive(reason: string): boolean {
+  if (reason.length > 80) return true;
+  // 如果 reason 看起来像 markdown 正文（标题/章节），也是误报
+  if (
+    /^#{1,6}\s/m.test(reason) ||
+    /^[-*+]\s/m.test(reason) ||
+    /^\d+\.\s/m.test(reason)
+  ) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * 验证闸门：把 StepResult 判定为「真交付」或「放弃/不可信」。
+ *   - schema 模式：extractJsonPayload 已严格解析（解析失败会抛、落不到这里），能拿到结果即 ok；
+ *     补 content 别名不覆盖具名字段。
+ *   - 非 schema 模式：空产出 / 命中 GIVEUP 标记 → ok:false；否则 ok:true，raw 补 text/result/content
+ *     三键别名，兼容 capture:{content:x}/{result:x}/{text:x}。
+ *
+ * v0.9.3 增强：GIVEUP 检测增加误报过滤（isLikelyFalsePositive）。
+ * 当标记后的内容看起来像是实质性的工作产出而非简短放弃理由时，
+ * 视为 LLM 误触发标记 → 仍然当作成功交付处理。
+ */
+export function interpretMiniReActResult(
+  result: StepResult,
+  hasSchema: boolean,
+): AgentOutcome {
+  if (hasSchema) {
+    const raw: Record<string, unknown> = { ...result.raw };
+    if (typeof raw.result === 'string' && raw.content === undefined) {
+      raw.content = raw.result;
+    }
+    return { ok: true, value: { raw, preview: result.preview } };
+  }
+
+  const text = typeof result.raw.text === 'string' ? result.raw.text : '';
+  const trimmed = text.trim();
+  if (trimmed.length === 0) {
+    return { ok: false, reason: '没有产出任何结果' };
+  }
+  const giveup = parseGiveup(trimmed);
+  if (giveup !== null) {
+    // v0.9.3: 误报过滤 —— 如果 "放弃原因" 太长或太结构化，
+    // 说明 LLM 是在正常输出中碰巧触发了标记，不应判为放弃
+    if (isLikelyFalsePositive(giveup)) {
+      // 降级为成功交付：去掉误触发的标记部分（replaceAll：标记可能被 LLM
+      // 误触发多次，replace 只删首个会让残留标记流进 capture 污染下游）
+      const cleanText = trimmed
+        .replaceAll(GIVEUP_MARKER, '')
+        .replaceAll(LEGACY_GIVEUP_MARKER, '')
+        .trim();
+      const raw: Record<string, unknown> = {
+        text: cleanText,
+        result: cleanText,
+        content: cleanText,
+      };
+      return {
+        ok: true,
+        value: {
+          raw,
+          preview:
+            cleanText.length > 200 ? `${cleanText.slice(0, 200)}…` : cleanText,
+        },
+      };
+    }
+    return { ok: false, reason: giveup || '显式放弃（未给原因）' };
+  }
+  const raw: Record<string, unknown> = {
+    text: trimmed,
+    result: trimmed,
+    content: trimmed,
+  };
+  return {
+    ok: true,
+    value: {
+      raw,
+      preview: trimmed.length > 200 ? `${trimmed.slice(0, 200)}…` : trimmed,
+    },
+  };
+}

package/plugins/workflow-runner/src/controlFlow/branch.js

@@ -0,0 +1,40 @@
+/**
+ * controlFlow/branch.ts —— 条件分支
+ *
+ * ⚠️ **branch 对 break 透明**：子块返回的 break/continue/halt 都原样上抛给
+ * 最近的循环或顶层。分支只决定「走哪一支」，不吞信号 —— 吞掉的话
+ * `break target:<loopId>` 就穿不过分支，而那正是它存在的意义。
+ */
+import { evalExpr } from '../expressions.js';
+export async function* execBranchStep(step, vars, deps) {
+    const { state } = deps;
+    let cond = false;
+    try {
+        cond = Boolean(evalExpr(step.condition ?? 'false', vars));
+    }
+    catch (e) {
+        const errMsg = `branch 条件错误: ${e.message}`;
+        await state.appendProgress(`✗ ${step.id}: ${errMsg}`);
+        yield { type: 'workflow_step_end', id: step.id, ok: false, error: errMsg };
+        yield { type: 'error', error: `Workflow halted at step "${step.id}": ${errMsg}` };
+        return { kind: 'halted' };
+    }
+    const branch = cond ? step.then : step.else;
+    if (Array.isArray(branch) && branch.length > 0) {
+        // 子块不传 cp：更深嵌套不记 checkpoint（见 CpScope 注释）。
+        const r = yield* deps.runBlock(branch, vars);
+        if (r === 'halted')
+            return { kind: 'halted' };
+        if (r !== 'completed')
+            return { kind: 'flow', signal: r };
+    }
+    await state.appendProgress(`✓ ${step.id} (branch=${cond})`);
+    await state.writeVars(vars.snapshot());
+    yield {
+        type: 'workflow_step_end',
+        id: step.id,
+        ok: true,
+        output: `branch=${cond}`,
+    };
+    return { kind: 'next' };
+}