minimal-agent 0.9.0 → 0.10.0

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

@@ -1,22 +1,23 @@
 /**
  * ============================================================
- *  src/workflows/loader.ts —— workflow yaml 双源加载 + 最小校验
+ *  plugins/workflow-runner/src/loader.ts —— workflow yaml 双源加载 + 校验
  * ------------------------------------------------------------
  *  - 扫描 cwd/workflows/ 与 packageRoot/workflows/（cwd 优先，复用
  *    getResourceSearchPaths 契约）
  *  - 一个坏 yaml 不应拖累其它工作流（catch 单文件错误，继续扫描）
  *  - 目录不存在 / 为空 → 静默返回 []（默认 T-A-O-R 不受影响）
  *
- *  P0 不引 AJV；下面手写 ≤80 行的最小校验器，只挡死硬性错误：
- *    - name / description / steps 必填且类型正确
- *    - steps 非空
- *    - 每个 step 必须有且只有一个动作字段（tool / skill / llm / type）
- *
- *  P1 切 AJV 做完整 schema。
+ *  不引 AJV：下面手写校验器（validate/validateSteps），覆盖结构性硬错误并对
+ *  每条 step 字段做类型/一致性校验——
+ *    - name / description / steps 必填且类型正确；steps 非空
+ *    - 每个 step 必须有且只有一个动作字段（tool / skill / llm / agent / type）
+ *    - 控制流字段一致性 + ADR-05 的 llm-only 字段（output_schema/context_files/
+ *      allowed_tools）准入 + 断点续跑字段（artifacts/max_retries）类型
+ *  手写而非 schema 库：依赖少、错误信息可中文化、按减法不为「完整 schema」引依赖。
  * ============================================================
  */
 import { readFile, readdir } from 'node:fs/promises';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 import { parse as parseYamlLib } from 'yaml';
 import { getResourceSearchPaths } from '../../../src/plugin-sdk.js';
 export class WorkflowLoadError extends Error {
@@ -31,10 +32,10 @@ export class WorkflowLoadError extends Error {
  * 扫描双源目录，返回所有 *.yaml / *.yml 解析后的 workflow。
  * 永远不抛；坏文件 console.warn 并跳过。
  */
-export async function listWorkflows() {
+export async function listWorkflows(workingDir) {
     const out = [];
     const seen = new Set();
-    const roots = getResourceSearchPaths('workflows', import.meta.url);
+    const roots = getResourceSearchPaths('workflows', import.meta.url, workingDir);
     for (const root of roots) {
         let entries;
         try {
@@ -63,9 +64,21 @@ export async function listWorkflows() {
     return out;
 }
 /** 按 name 查找。找不到返回 null —— 调用方决定如何提示用户。 */
-export async function findWorkflowByName(name) {
-    const all = await listWorkflows();
-    return all.find((w) => w.name === name) ?? null;
+export async function findWorkflowByName(name, workingDir) {
+    const all = await listWorkflows(workingDir);
+    const normalized = normalizeWorkflowLookupName(name);
+    return all.find((w) => w.name === normalized || workflowFileBaseName(w) === normalized) ?? null;
+}
+function stripYamlExt(name) {
+    return name.replace(/\.ya?ml$/i, '');
+}
+function normalizeWorkflowLookupName(name) {
+    return stripYamlExt(basename(name));
+}
+function workflowFileBaseName(workflow) {
+    if (!workflow.__source)
+        return null;
+    return stripYamlExt(basename(workflow.__source));
 }
 /** 读单个 yaml 文件 → 解析 → 校验。失败抛 WorkflowLoadError。 */
 export async function parseWorkflowFile(file) {
@@ -119,6 +132,16 @@ function validate(obj, file) {
                 throw new WorkflowLoadError("self_heal.max_retries 必须是 >= 1 的整数", file);
             }
         }
+        if (sh.retry_delay_ms !== undefined) {
+            if (typeof sh.retry_delay_ms !== 'number' || !Number.isFinite(sh.retry_delay_ms) || sh.retry_delay_ms < 0) {
+                throw new WorkflowLoadError("self_heal.retry_delay_ms 必须是 >= 0 的数字（毫秒）", file);
+            }
+        }
+        if (sh.max_turns_retry_delay_ms !== undefined) {
+            if (typeof sh.max_turns_retry_delay_ms !== 'number' || !Number.isFinite(sh.max_turns_retry_delay_ms) || sh.max_turns_retry_delay_ms < 0) {
+                throw new WorkflowLoadError("self_heal.max_turns_retry_delay_ms 必须是 >= 0 的数字（毫秒）", file);
+            }
+        }
     }
     // artifacts 校验（WorkflowDef 级别，可选）
     if (obj.artifacts !== undefined) {
@@ -144,39 +167,71 @@ function validate(obj, file) {
             if (r.type === 'enum' && (!Array.isArray(r.values) || r.values.length === 0)) {
                 throw new WorkflowLoadError(`inputs[${i}].values 必填（type=enum 时）`, file);
             }
+            // greedy 首参：只许 boolean，且只能标在第一个 input（语义=吸收全部位置参数，
+            // 标在非首位无意义且会误导，响亮拒绝）。
+            if (r.greedy !== undefined && typeof r.greedy !== 'boolean') {
+                throw new WorkflowLoadError(`inputs[${i}].greedy 必须是 boolean`, file);
+            }
+            if (r.greedy === true && i !== 0) {
+                throw new WorkflowLoadError(`inputs[${i}].greedy 只能标在第一个 input 上`, file);
+            }
         }
     }
 }
 // ADR-05: 控制流 type 集合——这些节点的"动作"由 type 自身定义，
 // 因此不能附带 tool/skill/llm 也不能配 output_schema / context_files / allowed_tools。
-// 导出供「editor ↔ 后端」schema 一致性测试比对（test/editorSchemaSync.test.ts）。
+// 导出供「editor ↔ 后端」schema 一致性测试比对（test/workflowEditorSchemaSync.test.ts）。
 // editor 因 D2 红线禁止 import 后端、手抄了同一份；后端在此演进时该测试会红，提示同步 editor。
 export const CONTROL_FLOW_TYPES = new Set([
     'assert',
     'verify',
+    'set',
     'branch',
     'loop',
     'break',
+    'continue',
+    'echo',
     'pause',
-    'parallel',
-    'vote',
 ]);
 export const VALID_STEP_TYPES = new Set([
     'assert',
     'verify',
+    'set',
     'branch',
     'loop',
     'break',
+    'continue',
+    'echo',
     'pause',
-    'parallel',
-    'vote',
 ]);
 // 动作字段里「自带 kind 含义」的那几个（不含 type —— type 的 kind 由其值决定）。
-// 单一来源：validateSteps 的 actionFields + test/editorSchemaSync.test.ts 都从这里取，
+// 单一来源：validateSteps 的 actionFields + test/workflowEditorSchemaSync.test.ts 都从这里取，
 // 新增动作 kind 只改这一处（并同步 editor 手抄镜像 + 该测试快照）。
 export const ACTION_KINDS = ['tool', 'skill', 'agent', 'llm'];
 // onError 合法值（单一来源：onError 校验 + editor schema 同步测试）。
 export const ON_ERROR_VALUES = ['halt', 'continue', 'recover'];
+function isValidMaxIterations(value) {
+    return ((typeof value === 'number' && Number.isInteger(value) && value > 0) ||
+        (typeof value === 'string' && (value.includes('${') || /^\d+$/.test(value.trim()))));
+}
+function isValidImageDetail(value) {
+    return value === 'low' || value === 'default' || value === 'high';
+}
+function assertLlmOrAgentMultimodalField(s, key, p, file) {
+    if (s.llm === undefined && s.agent === undefined) {
+        throw new WorkflowLoadError(`${p}.${key} 仅支持 llm / agent 节点`, file);
+    }
+}
+function assertHistoryModeField(s, p, file) {
+    if (s.llm === undefined && s.agent === undefined && s.skill === undefined) {
+        throw new WorkflowLoadError(`${p}.history_mode 只能用在 llm / agent / skill 节点上`, file);
+    }
+}
+function requireNonEmptyString(s, key, p, file, typeName) {
+    if (typeof s[key] !== 'string' || String(s[key]).length === 0) {
+        throw new WorkflowLoadError(`${p} type=${typeName} requires non-empty '${key}'`, file);
+    }
+}
 function validateSteps(steps, file, pathPrefix) {
     const seenIds = new Set();
     for (const [i, item] of steps.entries()) {
@@ -216,6 +271,83 @@ function validateSteps(steps, file, pathPrefix) {
         if (s.recover_hint !== undefined && typeof s.recover_hint !== 'string') {
             throw new WorkflowLoadError(`${p}.recover_hint 必须是 string`, file);
         }
+        if (s.free_text !== undefined) {
+            if (s.type !== 'pause') {
+                throw new WorkflowLoadError(`${p}.free_text 只能用在 type=pause 节点上`, file);
+            }
+            if (s.free_text !== 'halt' && s.free_text !== 'approve') {
+                throw new WorkflowLoadError(`${p}.free_text "${String(s.free_text)}" 非法；合法值: halt / approve`, file);
+            }
+        }
+        // 数字字段类型校验：yaml 给字符串会静默进入运行时算术（NaN footgun），加载期拦掉
+        if (s.maxTurns !== undefined &&
+            (typeof s.maxTurns !== 'number' || !Number.isInteger(s.maxTurns) || s.maxTurns < 1)) {
+            throw new WorkflowLoadError(`${p}.maxTurns 必须是 >= 1 的整数`, file);
+        }
+        if (s.max_retries !== undefined &&
+            (typeof s.max_retries !== 'number' || !Number.isInteger(s.max_retries) || s.max_retries < 0)) {
+            throw new WorkflowLoadError(`${p}.max_retries 必须是 >= 0 的整数`, file);
+        }
+        // 多模态图片输入：仅 llm / agent 节点支持；skill/控制流/确定性 tool 节点
+        // 不接收图片字段，避免 yaml 作者以为图片已传给模型但实际被静默忽略。
+        const multimodalFields = [
+            'images',
+            'parse_inline_images',
+            'image_detail',
+            'image_max_long_side_pixel',
+        ];
+        for (const key of multimodalFields) {
+            if (s[key] !== undefined)
+                assertLlmOrAgentMultimodalField(s, key, p, file);
+        }
+        if (s.images !== undefined) {
+            if (!Array.isArray(s.images)) {
+                throw new WorkflowLoadError(`${p}.images 必须是数组`, file);
+            }
+            for (const [j, item] of s.images.entries()) {
+                if (typeof item === 'string') {
+                    if (item.length === 0) {
+                        throw new WorkflowLoadError(`${p}.images[${j}] 必须是非空 string`, file);
+                    }
+                    continue;
+                }
+                if (!item || typeof item !== 'object' || Array.isArray(item)) {
+                    throw new WorkflowLoadError(`${p}.images[${j}] 必须是 string 或 { source, detail?, max_long_side_pixel? }`, file);
+                }
+                const r = item;
+                if (typeof r.source !== 'string' || r.source.length === 0) {
+                    throw new WorkflowLoadError(`${p}.images[${j}].source 必须是非空 string`, file);
+                }
+                if (r.detail !== undefined && !isValidImageDetail(r.detail)) {
+                    throw new WorkflowLoadError(`${p}.images[${j}].detail 必须是 low/default/high`, file);
+                }
+                if (r.max_long_side_pixel !== undefined &&
+                    (typeof r.max_long_side_pixel !== 'number' ||
+                        !Number.isInteger(r.max_long_side_pixel) ||
+                        r.max_long_side_pixel < 1)) {
+                    throw new WorkflowLoadError(`${p}.images[${j}].max_long_side_pixel 必须是正整数`, file);
+                }
+            }
+        }
+        if (s.parse_inline_images !== undefined &&
+            typeof s.parse_inline_images !== 'boolean') {
+            throw new WorkflowLoadError(`${p}.parse_inline_images 必须是 boolean`, file);
+        }
+        if (s.image_detail !== undefined && !isValidImageDetail(s.image_detail)) {
+            throw new WorkflowLoadError(`${p}.image_detail 必须是 low/default/high`, file);
+        }
+        if (s.image_max_long_side_pixel !== undefined &&
+            (typeof s.image_max_long_side_pixel !== 'number' ||
+                !Number.isInteger(s.image_max_long_side_pixel) ||
+                s.image_max_long_side_pixel < 1)) {
+            throw new WorkflowLoadError(`${p}.image_max_long_side_pixel 必须是正整数`, file);
+        }
+        if (s.history_mode !== undefined) {
+            assertHistoryModeField(s, p, file);
+            if (s.history_mode !== 'shared' && s.history_mode !== 'isolated') {
+                throw new WorkflowLoadError(`${p}.history_mode "${String(s.history_mode)}" 非法；合法值: shared / isolated`, file);
+            }
+        }
         // 控制流字段一致性
         if (s.type === 'branch' && s.condition === undefined) {
             throw new WorkflowLoadError(`${p} type=branch 必须带 'condition'`, file);
@@ -238,6 +370,13 @@ function validateSteps(steps, file, pathPrefix) {
                 if (s.as !== undefined && (typeof s.as !== 'string' || s.as.length === 0)) {
                     throw new WorkflowLoadError(`${p} type=loop while 模式的 'as' 必须是非空字符串`, file);
                 }
+                // max_iterations：正整数 或 含 ${} 的模板字符串（运行时插值 + coerce，
+                // 失败响亮报错）。裸字符串数字（"50"）也容忍。其它一律加载期拦掉——
+                // 曾有 "${max_iterations}" 不被插值直接参与 < 比较 → NaN → 静默 0 次迭代。
+                const mi = s.max_iterations;
+                if (!isValidMaxIterations(mi)) {
+                    throw new WorkflowLoadError(`${p}.max_iterations 必须是正整数或含 \${} 的模板字符串，得到: ${JSON.stringify(mi)}`, file);
+                }
             }
             if (!Array.isArray(s.do)) {
                 throw new WorkflowLoadError(`${p} type=loop 必须带 'do' 数组`, file);
@@ -248,9 +387,58 @@ function validateSteps(steps, file, pathPrefix) {
             // break 是循环退出信号，通常配合 when 条件使用
             // 无额外必填字段；when 缺失时等价于无条件跳出（极少用）
         }
+        // continue：跳到（目标）循环的下一轮迭代；与 break 同族（when 可选）
+        // echo：确定性输出 message（支持 ${} 插值），不烧 LLM
+        if (s.type === 'echo') {
+            requireNonEmptyString(s, 'message', p, file, 'echo');
+        }
+        else if (s.message !== undefined) {
+            throw new WorkflowLoadError(`${p}.message 只能用在 type=echo 节点上`, file);
+        }
+        // target：仅 break/continue 的标签语义（指定要穿透到哪一层循环）
+        if (s.target !== undefined) {
+            if (s.type !== 'break' && s.type !== 'continue') {
+                throw new WorkflowLoadError(`${p}.target 只能用在 type=break / type=continue 节点上`, file);
+            }
+            if (typeof s.target !== 'string' || s.target.length === 0) {
+                throw new WorkflowLoadError(`${p}.target 必须是非空 string（目标循环的 id）`, file);
+            }
+        }
+        // title：任意步可选的人话进度显示名（声明后状态行显示它、不显示块内相对序号）
+        if (s.title !== undefined && (typeof s.title !== 'string' || s.title.length === 0)) {
+            throw new WorkflowLoadError(`${p}.title 必须是非空 string（进度显示名）`, file);
+        }
+        // goal_supplement：动作步与 pause 可声明（产出作为用户补充要求贯穿后续步骤）
+        if (s.goal_supplement !== undefined) {
+            if (typeof s.goal_supplement !== 'boolean') {
+                throw new WorkflowLoadError(`${p}.goal_supplement 必须是 boolean`, file);
+            }
+            const isActionStep = ACTION_KINDS.some((k) => s[k] !== undefined);
+            if (!isActionStep && s.type !== 'pause') {
+                throw new WorkflowLoadError(`${p}.goal_supplement 只能用在动作步（${ACTION_KINDS.join('/')}）或 type=pause 节点上`, file);
+            }
+        }
+        // done_when：仅 agent 步可选（确定性完成条件，引擎 nudge 兜底 announce-not-do 烂尾）
+        if (s.done_when !== undefined) {
+            if (typeof s.done_when !== 'string' || s.done_when.trim().length === 0) {
+                throw new WorkflowLoadError(`${p}.done_when 必须是非空 string（白名单表达式）`, file);
+            }
+            if (s.agent === undefined) {
+                throw new WorkflowLoadError(`${p}.done_when 仅支持 agent 节点`, file);
+            }
+        }
         if (s.type === 'assert' && s.condition === undefined) {
             throw new WorkflowLoadError(`${p} type=assert 必须带 'condition'`, file);
         }
+        // set：确定性变量赋值（曾有 yaml 用 llm:"PLAN" 当赋值——模型自由回复非确定，set 是根治）
+        if (s.type === 'set') {
+            if (!s.set ||
+                typeof s.set !== 'object' ||
+                Array.isArray(s.set) ||
+                Object.keys(s.set).length === 0) {
+                throw new WorkflowLoadError(`${p} type=set 必须带非空对象 'set'（{ 变量名: 值 }，值支持 \${} 插值）`, file);
+            }
+        }
         if (s.type === 'verify') {
             // 兼容两种格式：YAML 数组 或逗号分隔字符串
             const rawChecks = Array.isArray(s.checks)
@@ -262,7 +450,15 @@ function validateSteps(steps, file, pathPrefix) {
                 throw new WorkflowLoadError(`${p} type=verify 必须带 checks（数组或逗号分隔字符串）`, file);
             }
             for (const [ci, c] of rawChecks.entries()) {
-                if (typeof c !== 'string' || !c.includes(':')) {
+                if (typeof c !== 'string') {
+                    throw new WorkflowLoadError(`${p}.checks[${ci}] 必须是字符串`, file);
+                }
+                // 含 ${...} 模板的 check（如 checks: "${verify_checks}"）在运行时插值后才知道真实值，
+                // 加载期跳过格式校验，交给 verify.ts 在插值后解析。否则这类合法的动态配置会被
+                // 误判为"损坏 yaml"而整个工作流加载失败（ralph-loop 的 run_verify 即如此）。
+                if (c.includes('${'))
+                    continue;
+                if (!c.includes(':')) {
                     throw new WorkflowLoadError(`${p}.checks[${ci}] 格式错误，应为 "type:value"（如 "file_exists:./x"）`, file);
                 }
             }
@@ -280,50 +476,6 @@ function validateSteps(steps, file, pathPrefix) {
                 validateSteps(s.else, file, `${p}.else`);
         }
         // ---------------- ADR-05 新增校验 ----------------
-        // parallel：必须有非空 fork[]，递归校验子步骤
-        if (s.type === 'parallel') {
-            if (!Array.isArray(s.fork) || s.fork.length === 0) {
-                throw new WorkflowLoadError(`${p} type=parallel 必须有 fork: [...]（至少 1 个子步骤）`, file);
-            }
-            validateSteps(s.fork, file, `${p}.fork`);
-        }
-        else if (s.fork !== undefined) {
-            throw new WorkflowLoadError(`${p}.fork 只能用在 type=parallel 节点上`, file);
-        }
-        // vote：voters_count (2~10) / rules / input 必填；threshold 可选但越界要拦
-        if (s.type === 'vote') {
-            const vc = s.voters_count;
-            const rules = s.rules;
-            const input = s.input;
-            const missing = typeof vc !== 'number' ||
-                !Number.isInteger(vc) ||
-                vc < 2 ||
-                vc > 10 ||
-                typeof rules !== 'string' ||
-                rules.length === 0 ||
-                typeof input !== 'string' ||
-                input.length === 0;
-            if (missing) {
-                throw new WorkflowLoadError(`${p} type=vote 要求 voters_count (2~10), rules, input 三个字段`, file);
-            }
-            if (s.threshold !== undefined) {
-                const t = s.threshold;
-                if (typeof t !== 'number' ||
-                    !Number.isInteger(t) ||
-                    t < 1 ||
-                    t > vc) {
-                    throw new WorkflowLoadError(`${p} threshold=${String(t)} 超出范围；必须是 1 <= threshold <= voters_count(${vc})`, file);
-                }
-            }
-        }
-        else {
-            // 非 vote 节点不应携带 vote-only 字段
-            for (const k of ['voters_count', 'rules', 'threshold']) {
-                if (s[k] !== undefined) {
-                    throw new WorkflowLoadError(`${p}.${k} 只能用在 type=vote 节点上`, file);
-                }
-            }
-        }
         // output_schema：必须是 object；不能用在控制流节点上
         if (s.output_schema !== undefined) {
             if (typeof s.output_schema !== 'object' ||

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

@@ -0,0 +1,37 @@
+import { isAbsolute, resolve } from 'node:path';
+import { interpolate } from './expressions.js';
+export function resolveWorkflowMultimodalOptions(step, vars, ctx, onMissing) {
+    const imageDetail = step.image_detail;
+    const imageMaxLongSidePixel = step.image_max_long_side_pixel;
+    const imageInputs = (step.images ?? []).map((item) => {
+        if (typeof item === 'string') {
+            return {
+                source: resolveWorkflowImageSource(interpolate(item, vars, { onMissing }), ctx),
+                detail: imageDetail,
+                maxLongSidePixel: imageMaxLongSidePixel,
+            };
+        }
+        return {
+            source: resolveWorkflowImageSource(interpolate(item.source, vars, { onMissing }), ctx),
+            detail: item.detail ?? imageDetail,
+            maxLongSidePixel: item.max_long_side_pixel ?? imageMaxLongSidePixel,
+        };
+    });
+    return {
+        imageInputs: imageInputs.length > 0 ? imageInputs : undefined,
+        parseInlineImages: step.parse_inline_images,
+        imageDetail,
+        imageMaxLongSidePixel,
+    };
+}
+function resolveWorkflowImageSource(source, ctx) {
+    const clean = source.trim();
+    if (/^https?:\/\//i.test(clean) ||
+        /^data:image\//i.test(clean) ||
+        clean.startsWith('file://') ||
+        clean.startsWith('~/') ||
+        isAbsolute(clean)) {
+        return clean;
+    }
+    return resolve(ctx.cwd, clean);
+}

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

@@ -22,8 +22,7 @@
  *    - { ok:false, reason } —— runner 带原因 honest halt
  * ============================================================
  */
-import { runQuery } from '../../../src/loop.js';
-import { describeCaptureContract, interpretMiniReActResult, truncate, } from './agentCommon.js';
+import { describeCaptureContract, effectiveGoalAnchor, interpretMiniReActResult, runStepQuery, truncate, } from './agentCommon.js';
 import { interpolate, interpolateDeep } from './expressions.js';
 // RECOVER_OPENING 作为用户消息的一部分（系统提示词已在 history[0] 中）
 const RECOVER_OPENING = `你是一名资深的自动化工程师 / SRE，被一个确定性工作流临时调来「救火」。
@@ -74,28 +73,31 @@ export async function* runRecovery(step, vars, ctx, errorMsg) {
     const schemaHint = step.output_schema
         ? `\n\n【结构化输出约束】请严格按照以下 JSON Schema 输出结果：\n${JSON.stringify(step.output_schema, null, 2)}`
         : '';
-    const fullPrompt = recoverPrompt + schemaHint;
-    // 记录 history 长度用于提取本步输出
-    const historyLenBefore = ctx.history.length;
+    // 通用目标锚定（同 agent/llm/skill 步）：恢复 agent 也要看到用户原始目标
+    // 与补充要求，不能只有 def.description 的"工作流总目标"（E10）。
+    const anchor = effectiveGoalAnchor(ctx);
+    const fullPrompt = anchor
+        ? `${anchor}\n\n${recoverPrompt}${schemaHint}`
+        : recoverPrompt + schemaHint;
     try {
-        // 委托 TAOR 引擎执行——事件透传给 UI（显示恢复进度）
-        yield* runQuery(fullPrompt, {
-            provider: ctx.provider,
-            history: ctx.history,
-            signal: ctx.signal,
-            maxTurns: step.maxTurns ?? 12,
-            chat: ctx.chat,
-            executeTool: ctx.executeTool,
-            sessionState: ctx.sessionState,
-        });
-        // 从 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;
-            }
+        // 委托 TAOR 引擎执行（共享消费层 runStepQuery）——事件透传给 UI（显示恢复进度）。
+        // 注意剥掉 step 的 allowed_tools 白名单：原步收敛工具是为弱模型聚焦，
+        // 恢复 agent 的职责正是「随机应变换路径」，要全工具箱（保持 v0.9 行为）。
+        const { rawText, sawLlmError, sawMaxTurns, llmErrorDetail } = yield* runStepQuery(fullPrompt, { ...step, allowed_tools: undefined }, ctx, { maxTurns: step.maxTurns ?? 25 });
+        // 恢复是兜底路径：无论 provider 失败还是模型空答，都按「没救回」返回
+        // ok:false（不抛重试——retry 在进入 recover 前已用尽）；只是归因更诚实。
+        if (!rawText.trim() && sawLlmError) {
+            return {
+                ok: false,
+                reason: `LLM 调用失败且无产出${llmErrorDetail ? `—— ${truncate(llmErrorDetail, 300)}` : ''}`,
+            };
+        }
+        // 恢复 agent 也撞 maxTurns 截断 → 截断产出不可信，诚实「未救回」
+        if (sawMaxTurns) {
+            return {
+                ok: false,
+                reason: `恢复 agent 达到最大轮数 ${step.maxTurns ?? 25} 被截断，产出不可信（未救回）`,
+            };
         }
         const stepResult = {
             raw: { text: rawText, result: rawText },
@@ -111,7 +113,7 @@ export async function* runRecovery(step, vars, ctx, errorMsg) {
         };
     }
     catch (e) {
-        // runQuery 抛错（用尽轮数 / 中断）→ 恢复失败。
+        // runStepQuery 抛错（编程性异常 / 中断竞态）→ 恢复失败。
         return { ok: false, reason: e.message ?? String(e) };
     }
 }