minimal-agent 0.8.2 → 0.10.0

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

@@ -1,60 +1,40 @@
 /**
  * ============================================================
- *  plugins/workflow-runner/src/agentCommon.ts —— workflow 内「有界 agent」的共享大脑
+ *  plugins/workflow-runner/src/agentCommon.ts —— workflow 内「有界 agent」的共享工具
  * ------------------------------------------------------------
- *  工作流里有两处会临时起一个 agent（都跑 miniReAct）：
+ *  工作流里有两处会临时起一个 agent（runQuery 执行后的验证闸门）：
  *    - onError:'recover'（recovery.ts）—— 节点失败后救火
  *    - agent: 节点（stepExecutors/agent.ts）—— 作者显式声明的开放任务
  *  二者本质同构：受工作流目标/上下文指导、用工具随机应变、产出经验证后回灌 capture。
  *  为避免「同一个脑子写两份提示词、行为漂移」，这里收敛它们的**共享件**：
- *    1. 统一系统提示词基础内核（来自 promptAssembly.ts）—— 含工具/skill/plugin 完整列表；
- *       两处只在前面各加一句**角色开场白**（recover=救火 / agent=自主完成一步），
- *       后面追加共享纪律块。
- *    2. 统一验证闸门（interpretMiniReActResult）—— miniReAct 跑完后，判定「真交付」还是
+ *    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 { assembleBasePrompt } from '../../../src/prompts/promptAssembly.js';
-/** agent 显式放弃的唯一标记；与 DISCIPLINE 收尾约束严格对应。recover 与 agent 节点共用。 */
-export const GIVEUP_MARKER = '__AGENT_GIVEUP__';
-/** agent 步骤的角色开场白（与 recovery 的 RECOVER_OPENING 对称） */
-export const AGENT_OPENING = '你是一名资深工程师，被一个确定性工作流临时调来「自主完成一步开放任务」。';
-/** 共享纪律块：所有 workflow 内 agent 的通用行为约束（角色开场白由各调用方拼在前面）。 */
-const DISCIPLINE = `按这个纪律干活：
-1. 先想清楚「这一步要产出什么」，必要时用只读工具（Read / Grep / Glob）做最小探查，别凭空猜、别凭空编。
-2. 用工具**实际去做**（读文件、执行命令、写文件…），不要只描述计划。
-3. **收尾前必须自我验证**：用工具确认产出确实存在且满足意图（写了文件就 Read 回来核对、跑了命令就检查退出码与输出）。没验证过不算完成。
-
-安全护栏（你握有包括 Bash 在内的全部工具，务必克制）：
-- 只做达成意图所必需的最小动作，优先可逆操作。
-- 严禁破坏性行为：不 rm -rf、不删除/覆盖与本步无关的用户数据、不碰工作目录以外的东西。
-- **绝不靠伪造、占位、或编造一段「看起来对」的文本来假装成功**——你的产出会被工作流绑给后续步骤，假结果比诚实失败更糟。
-
-收尾（二选一，硬约束）：
-- 真的达成了 → 最终消息**只输出这一步要的结果本身**，不要寒暄、不要复述要求、不要解释推理过程。若要求结构化输出，严格按 JSON Schema、**不要**用 markdown 代码块包裹。
-- 确实做不成 → 最终消息**只输出一行**：\`${GIVEUP_MARKER}: <一句话说明为什么>\`，让工作流诚实地停下。绝不要为了「交差」而编一个假结果。`;
+import { runQuery, stripThinkBlocks, } from '../../../src/plugin-sdk.js';
+import { normalizeCapture, } from './types.js';
 /**
- * 拼一个 workflow agent 的完整 system prompt：
- *
- *   角色开场白 + 基础内核（含 skill/plugin/工具完整列表） + 共享纪律
+ * agent 显式放弃的唯一标记；recover 与 agent 节点共用。
  *
- * 基础内核来自 assembleBasePrompt()，确保 workflow agent 与 TUI 普通对话
- * 看到完全相同的 skill 列表和插件信息。
+ * 设计约束（纯 ASCII，避免 Unicode 编码匹配问题）：
+ *   - 不使用 __XXX__ 格式（LLM 容易幻觉模仿）
+ *   - 含 "wf-internal" 前缀 + "do-not-generate" 明确警告
+ *   - 使用 [bracket] 格式而非 ⟨angle⟩（避免 Unicode 字符在 Bun indexOf 中行为不一致）
  */
-export async function buildWorkflowAgentSystem(cwd, opening, tools) {
-    const baseKernel = await assembleBasePrompt({
-        cwd,
-        tools,
-        includeProjectInstructions: false, // workflow 子步骤不需要项目指令
-        includePlugins: true, // 插件列表对 agent 也有参考价值
-    });
-    return `${opening}\n\n${baseKernel}\n\n${DISCIPLINE}`;
-}
-/** 把 step.capture 翻成「下游会把你的结果存成哪些变量」，让 agent 产出对得上形状。 */
+export const GIVEUP_MARKER = '[wf-internal-abort-do-not-generate]';
+/** 把 step.capture 翻成「下游会把你的结果存成哪些变量」，让 agent 产出对得上形状。
+ *  经 normalizeCapture：裸字符串 capture（capture: design_doc）不再被拆成单字符
+ *  【d、e、s…】，而是正确显示为【design_doc】。 */
 export function describeCaptureContract(step) {
-    if (!step.capture)
-        return '';
-    const names = Object.values(step.capture);
+    const names = Object.values(normalizeCapture(step.capture));
     if (names.length === 0)
         return '';
     return `\n\n下游契约：工作流会把你的结果保存为变量【${names.join('、')}】供后续步骤引用，请确保你的产出能填好这些变量。`;
@@ -62,28 +42,224 @@ export function describeCaptureContract(step) {
 export function truncate(s, n) {
     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) {
+    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> ⚠️ 以上补充要求与原始目标同等约束所有操作。`;
+}
+/** 把 llm_error 细节拼进可重试失败的抛错文案（无细节时退化为原样文案）。 */
+export function describeLlmFailure(stepId, detail) {
+    const base = `step ${stepId}: LLM 调用失败且无产出（触发重试）`;
+    return detail ? `${base}—— ${truncate(detail, 300)}` : base;
+}
+function cloneMessage(msg) {
+    if (msg.role === 'user' && Array.isArray(msg.content)) {
+        return { ...msg, content: msg.content.map((part) => ({ ...part })) };
+    }
+    return { ...msg };
+}
+function createStepHistory(step, ctx) {
+    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, step, ctx, opts) {
+    const activeHistory = createStepHistory(step, ctx);
+    // 记录 runQuery 开始前的 history 长度，用于之后提取本步的 assistant 输出
+    const historyLenBefore = activeHistory.length;
+    let aborted = false;
+    let sawLlmError = false;
+    let sawMaxTurns = false;
+    let llmErrorDetail = '';
+    let sawToolCall = false;
+    let toolOkCount = 0;
+    let toolFailCount = 0;
+    const toolNames = [];
+    for await (const ev of runQuery(prompt, {
+        provider: ctx.provider,
+        history: activeHistory,
+        signal: ctx.signal,
+        maxTurns: opts.maxTurns,
+        allowedTools: step.allowed_tools,
+        chat: ctx.chat,
+        executeTool: ctx.executeTool,
+        sessionState: ctx.sessionState,
+        imageInputs: opts.imageInputs,
+        parseInlineImages: opts.parseInlineImages,
+        imageDetail: opts.imageDetail,
+        imageMaxLongSidePixel: opts.imageMaxLongSidePixel,
+    })) {
+        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, maxTurns) {
+    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) {
+    return errMsg.includes(MAX_TURNS_CUTOFF_MARKER) && errMsg.includes('被截断');
+}
 /**
  * 解析非 schema 模式下 agent 最终文本里的放弃标记。
- *   - 命中 `__AGENT_GIVEUP__: <原因>` → 返回原因字符串（可能为空串）
+ *   - 命中 GIVEUP_MARKER → 返回原因字符串（可能为空串）
  *   - 未命中 → null（视为给出了真实结果）
+ *
+ * 注意：旧标记 __AGENT_GIVEUP__ 也兼容检测（向后兼容已存在的 checkpoint/状态数据），
+ * 但新代码只使用新标记格式。
  */
+const LEGACY_GIVEUP_MARKER = '__AGENT_GIVEUP__';
 export function parseGiveup(text) {
-    const idx = text.indexOf(GIVEUP_MARKER);
+    // 优先检测新标记
+    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 + GIVEUP_MARKER.length)
-        .replace(/^[:：\s]+/, '')
+        .slice(idx + markerLen)
+        .replace(/^[:：\s\]]+/, '') // 兼容新旧标记后的分隔符（: / : / ]）
         .trim();
 }
+/** 判断一个 giveup reason 是否看起来像"误报"（实际是 LLM 在正常输出中碰巧触发了标记）。
+ *
+ * 启发式规则：
+ *   - reason 长度 > 80 字符 → 几乎可以确定是误报（真正的放弃原因通常简短）
+ *   - reason 包含结构化内容（如 ## 标题、### 章节、列表项等）→ 误报
+ */
+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)) {
+        return true;
+    }
+    return false;
+}
 /**
- * 验证闸门：把 miniReAct 的 StepResult 判定为「真交付」或「放弃/不可信」。
- *   - schema 模式：miniReAct 已 strict 解析（解析失败会抛、落不到这里），能拿到结果即 ok；
+ * 验证闸门：把 StepResult 判定为「真交付」或「放弃/不可信」。
+ *   - schema 模式：extractJsonPayload 已严格解析（解析失败会抛、落不到这里），能拿到结果即 ok；
  *     补 content 别名不覆盖具名字段。
  *   - 非 schema 模式：空产出 / 命中 GIVEUP 标记 → ok:false；否则 ok:true，raw 补 text/result/content
  *     三键别名，兼容 capture:{content:x}/{result:x}/{text:x}。
- * 注意：preview 这里给「干净版」（不加任何前缀），需要前缀的调用方（如 recover 的 "recovered: "）
- * 自行包装。
+ *
+ * v0.9.3 增强：GIVEUP 检测增加误报过滤（isLikelyFalsePositive）。
+ * 当标记后的内容看起来像是实质性的工作产出而非简短放弃理由时，
+ * 视为 LLM 误触发标记 → 仍然当作成功交付处理。
  */
 export function interpretMiniReActResult(result, hasSchema) {
     if (hasSchema) {
@@ -100,6 +276,28 @@ export function interpretMiniReActResult(result, hasSchema) {
     }
     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 = {
+                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 = {

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

@@ -0,0 +1,72 @@
+import { ACTION_KINDS, CONTROL_FLOW_TYPES, ON_ERROR_VALUES, VALID_STEP_TYPES } from './loader.js';
+const llmAgentOnly = ['llm', 'agent'];
+const llmAgentSkillOnly = ['llm', 'agent', 'skill'];
+export const WORKFLOW_DSL_MANIFEST = {
+    version: '1.0.0',
+    actionKinds: [...ACTION_KINDS],
+    controlFlowTypes: [...CONTROL_FLOW_TYPES],
+    validStepTypes: [...VALID_STEP_TYPES],
+    onErrorValues: [...ON_ERROR_VALUES],
+    exclusiveActionFields: [...ACTION_KINDS, 'type'],
+    stepKinds: [
+        { kind: 'tool', group: 'action', label: 'Tool', description: 'Call one deterministic tool.', primaryFields: ['tool', 'args'] },
+        { kind: 'llm', group: 'action', label: 'LLM', description: 'Single LLM step.', primaryFields: ['llm', 'output_schema', 'context_files', 'allowed_tools'] },
+        { kind: 'skill', group: 'action', label: 'Skill', description: 'Run one SKILL.md workflow agent.', primaryFields: ['skill', 'input', 'maxTurns'] },
+        { kind: 'agent', group: 'action', label: 'Agent', description: 'Run an inline bounded TAOR agent.', primaryFields: ['agent', 'maxTurns', 'done_when', 'output_schema', 'context_files', 'allowed_tools'] },
+        { kind: 'assert', group: 'quality', label: 'Assert', description: 'Halt when a condition is false.', primaryFields: ['condition', 'onFail'] },
+        { kind: 'verify', group: 'quality', label: 'Verify', description: 'Run deterministic checks before continuing.', primaryFields: ['checks', 'onFail'] },
+        { kind: 'set', group: 'control', label: 'Set', description: 'Set workflow variables deterministically.', primaryFields: ['set'] },
+        { kind: 'branch', group: 'control', label: 'Branch', description: 'Route into then/else child steps.', primaryFields: ['condition'], childCollections: ['then', 'else'] },
+        { kind: 'loop', group: 'control', label: 'Loop', description: 'For-each or bounded while loop.', primaryFields: ['over', 'as', 'max_iterations', 'fresh_context'], childCollections: ['do'] },
+        { kind: 'break', group: 'control', label: 'Break', description: 'Exit the nearest (or target) loop.', primaryFields: ['when', 'target'] },
+        { kind: 'continue', group: 'control', label: 'Continue', description: 'Skip to the next iteration of the nearest (or target) loop.', primaryFields: ['when', 'target'] },
+        { kind: 'echo', group: 'control', label: 'Echo', description: 'Deterministically print an interpolated message (no LLM).', primaryFields: ['message'] },
+        { kind: 'pause', group: 'control', label: 'Pause', description: 'Human approval gate.', primaryFields: ['prompt', 'free_text'] },
+    ],
+    commonStepFields: [
+        { name: 'id', type: 'string', ui: 'text', required: true, label: 'id' },
+        { name: 'title', type: 'string', ui: 'text', label: 'title', description: 'Human-readable progress label (supports ${} interpolation); when set, the status line shows it instead of block-relative step numbers.' },
+        { name: 'when', type: 'string', ui: 'text', label: 'when', description: 'Optional execution condition.' },
+        { name: 'onError', type: 'enum', ui: 'select', enum: [...ON_ERROR_VALUES], label: 'onError' },
+        { name: 'recover_hint', type: 'string', ui: 'text', label: 'recover_hint', description: 'Hint for onError=recover.' },
+    ],
+    stepFields: [
+        { name: 'tool', type: 'string', ui: 'text', appliesTo: ['tool'] },
+        { name: 'args', type: 'object', ui: 'json', appliesTo: ['tool'] },
+        { name: 'llm', type: 'string', ui: 'textarea', appliesTo: ['llm'] },
+        { name: 'skill', type: 'string', ui: 'text', appliesTo: ['skill'] },
+        { name: 'agent', type: 'string', ui: 'textarea', appliesTo: ['agent'] },
+        { name: 'input', type: 'string', ui: 'textarea', appliesTo: ['skill'] },
+        { name: 'capture', type: 'object', ui: 'json' },
+        { name: 'maxTurns', type: 'number', ui: 'number', appliesTo: ['llm', 'skill', 'agent'] },
+        { name: 'max_retries', type: 'number', ui: 'number' },
+        { name: 'artifacts', type: 'string[]', ui: 'string[]' },
+        { name: 'condition', type: 'string', ui: 'text', appliesTo: ['assert', 'branch'] },
+        { name: 'onFail', type: 'string', ui: 'textarea', appliesTo: ['assert', 'verify'] },
+        { name: 'set', type: 'object', ui: 'json', required: true, appliesTo: ['set'] },
+        { name: 'checks', type: 'string[]', ui: 'string[]', required: true, appliesTo: ['verify'] },
+        { name: 'over', type: 'string', ui: 'text', appliesTo: ['loop'] },
+        { name: 'as', type: 'string', ui: 'text', appliesTo: ['loop'] },
+        { name: 'max_iterations', type: 'number', ui: 'number', appliesTo: ['loop'] },
+        { name: 'fresh_context', type: 'boolean', ui: 'boolean', appliesTo: ['loop'] },
+        { name: 'prompt', type: 'string', ui: 'textarea', appliesTo: ['pause'] },
+        { name: 'free_text', type: 'enum', ui: 'select', enum: ['halt', 'approve'], appliesTo: ['pause'] },
+        { name: 'target', type: 'string', ui: 'text', appliesTo: ['break', 'continue'], description: 'Target loop id (label semantics; default = nearest loop).' },
+        { name: 'message', type: 'string', ui: 'textarea', required: true, appliesTo: ['echo'] },
+        { name: 'goal_supplement', type: 'boolean', ui: 'boolean', appliesTo: ['tool', 'skill', 'agent', 'llm', 'pause'], description: 'Append this step output to the goal anchor as a user supplement.' },
+        { name: 'done_when', type: 'string', ui: 'text', appliesTo: ['agent'], description: 'Deterministic completion condition (whitelist expression, e.g. fileExists(...)); engine nudges the agent to keep working until it holds.' },
+        { name: 'output_schema', type: 'object', ui: 'json', appliesTo: llmAgentOnly },
+        { name: 'context_files', type: 'object[]', ui: 'object[]', appliesTo: llmAgentOnly },
+        { name: 'allowed_tools', type: 'string[]', ui: 'string[]', appliesTo: llmAgentOnly },
+        { name: 'history_mode', type: 'enum', ui: 'select', enum: ['shared', 'isolated'], appliesTo: llmAgentSkillOnly, description: 'Use shared workflow history or run this llm/agent/skill step in an isolated history (system prompt + current step only).' },
+        // 多模态（视觉）：仅 llm/agent 生效。images 喂图给模型识图/打分（如 illustrate 配图工作流）。
+        { name: 'images', type: 'array', ui: 'json', appliesTo: llmAgentOnly, description: 'Multimodal image inputs (paths/URLs, supports ${} interpolation). Array of strings or { source, detail, max_long_side_pixel }.' },
+        { name: 'image_detail', type: 'enum', ui: 'select', enum: ['low', 'high', 'auto'], appliesTo: llmAgentOnly, description: 'Default vision detail for this step (per-image override allowed inside images[]).' },
+        { name: 'image_max_long_side_pixel', type: 'number', ui: 'number', appliesTo: llmAgentOnly, description: 'Default max long-side pixels for downscaling images before sending.' },
+        { name: 'parse_inline_images', type: 'boolean', ui: 'boolean', appliesTo: llmAgentOnly, description: 'Parse @./img.png or image URLs found in the prompt text.' },
+    ],
+    workflowFields: [
+        { name: 'artifacts', type: 'string[]', ui: 'string[]', label: 'workflow artifacts' },
+        { name: 'self_heal', type: 'object', ui: 'json', label: 'self_heal' },
+    ],
+};