minimal-agent 0.6.4 → 0.6.6

package/plugins/workflow-runner/commands/workflow.md

@@ -6,7 +6,7 @@ argument-hint: <name> [val ...] [--input key=value ...]
 # /workflow
 
 本命令由 workflow-runner 插件接管（plugin.ts.runCommand），不会把 prompt 喂给 LLM。
-直接调用插件内置的 YAML DAG 执行器，按 steps 顺序运行 tool / llm / assert / branch / loop 等节点。
+直接调用插件内置的 YAML DAG 执行器，按 steps 顺序运行 tool / llm / skill / agent / assert / branch / loop 等节点。
 
 用法示例：
 
@@ -22,4 +22,84 @@ argument-hint: <name> [val ...] [--input key=value ...]
 - 多余的位置参数（超过 inputs 声明数量）被丢弃并 stderr 打 warning，不影响 workflow 执行
 - 值含空格时用引号：`/workflow xxx "AI 教程 进阶"`
 
+## agent 节点：把一步交给会随机应变的子 agent
+
+大多数 step 是确定性的（`tool` 调一个原子工具、`llm` 单轮生成）。但有些步骤本质是开放式的——
+「把 ./data 下最新的 csv 整理成 summary.md」这种，怎么做得看现场。这时用 `agent:` 节点：inline 写一句
+任务描述，工作流就地起一个**有界 TAOR 子 agent**（思考 → 用工具 → 观察 → 反思 → 再来），让它随机应变
+把这一步要的结果做出来，产出经验证后 `capture` 给下游。这就是「受工作流指导的 TAOR」——happy path 仍是
+确定性骨架，只在你显式声明的节点上注入完整 agency。
+
+```yaml
+steps:
+  - id: summarize
+    agent: "把 ./data 下最新的 csv 读出来，整理成一份 markdown 摘要写到 summary.md"
+    capture: { content: summary }     # agent 的最终产出存进变量 summary
+  - id: gate
+    type: assert
+    condition: "fileExists('summary.md')"
+```
+
+`agent:` 的配套字段（全部复用现有字段，都可选）：
+
+- `allowed_tools: [Read, Write]` —— 收窄它能用的工具；**缺省给全量工具**（要真 agency）。
+- `output_schema: {...}` —— 要求结构化产出（provider-native JSON Schema），按字段 `capture`。
+- `context_files: [{ path, hint }]` —— 列出可读文件让它按需 Read（不 inline 内容）。
+- `maxTurns: <n>` —— 子循环最大轮数，默认 12。
+- `capture` / `when` / `onError` —— 与其它动作 step 一致（agent 节点也能 `onError: recover` 被再救一次）。
+
+`agent` vs `skill`：`agent` 是 **inline、一次性**的有界子循环（miniReAct，轻、收敛快、产出受验证闸门把关）；
+`skill` 是跑一个**外部 SKILL.md 定义、可复用**的完整 agent（runQuery）。需要复用同一套能力用 `skill`，
+临时让某步「自己想办法」用 `agent`。
+
+**信任边界 / 不伪造**：agent 节点与 `onError: recover` 共用同一套系统提示词纪律——内置安全护栏（最小动作、
+优先可逆、不碰工作目录外、不删无关数据）、收尾前自我验证、**严禁伪造产出**；做不成就诚实放弃（抛错走 `onError`）。
+默认握全量工具，信任边界同 `skill:`——「运行一条 workflow 即信任它」。
+
+## 节点失败怎么办：onError（指导 ↔ 自主 旋钮）
+
+传统工作流的痛点：某个节点一失败、或撞上预料之外的情况，整条流程就崩、停摆。
+每个**动作 step**（tool / llm / skill / agent / assert）可声明 `onError`，决定失败时的行为，
+让一条工作流在「刚性确定」和「随机应变」之间按节点滑动：
+
+- `halt`（**默认**）：节点失败 → 整条工作流停、报错。最刚性、最可审计。
+- `continue`：跳过该节点、继续往下。⚠️ 下游若用 `capture` 依赖它会拿到空值，慎用。
+- `recover`（**自适应恢复**）：失败时**不立刻停**，而是临时起一个**有界 agent**，带着
+  「工作流目标 + 这个节点本来要做什么 + 错在哪 + 当前已知变量 + 下游 capture 契约」去**随机应变**——
+  它会先诊断根因，再换路径 / 换命令 / 先读后写 / 补齐前置条件，**并在收尾前自我验证**产出确实满足意图，
+  想办法把这一步要的**结果**做出来。
+  **救回** → 用同一个 `capture` 绑定结果、继续走正常流程；**救不回** → 它会**诚实放弃**（绝不伪造假结果），
+  工作流带原因报错停止（错误信息形如「自适应恢复未成功：<原因>」）。这是「确定性工作流 × 会随机应变的 agent」的结合点。
+
+`recover` 的配套字段（都可选）：
+
+- `recover_hint: "<提示>"` —— 给恢复 agent 的提示（支持 `${var}` 插值），如 `"端口被占就换 3001 重试"`。
+- `allowed_tools: [Read, Bash]` —— 收窄恢复 agent 能用的工具；**缺省给全量工具**。
+- `maxTurns: <n>` —— 恢复子循环最大轮数，默认 12（够「诊断 + 探查 + 动手 + 验证」一圈）。
+
+示例：
+
+```yaml
+steps:
+  - id: start_server
+    tool: Bash
+    args: { command: "node server.js" }
+    onError: recover
+    recover_hint: "端口被占就换一个端口重试"
+    capture: { content: server_log }
+```
+
+注意事项：
+
+- `onError` **只作用于动作 step**。控制流节点（branch / loop / vote / parallel 的条件或结构错误、
+  以及 `when` 表达式错误）**始终 halt** —— 那类是「作者写错了」，不是「运行期意外」，不走恢复。
+- `continue` vs `recover`：前者「放弃这步、盲目往下」，后者「想办法把这步做成、保住下游」。
+  要扛住「预料之外」的情况，用 `recover`。
+- **信任边界**：恢复 agent 默认握有全量工具，与 `skill:` 节点一致——「运行一条 workflow 即信任它」。
+  不信任来源的 yaml 本就不该跑。
+- **不伪造 / 诚实失败**：恢复 agent 的系统提示词内置安全护栏（只做最小必要动作、优先可逆、不碰工作目录外、
+  不删无关数据）并**严禁编造假结果**——它要么交付经自我验证的真产出，要么显式放弃让工作流诚实 halt。
+  框架侧另有验证闸门：空产出 / 显式放弃一律**不绑 `capture`、不放行下游**，杜绝把脏值喂给后续步骤。
+- `recover` 是 opt-in 的：确定性 / 可审计正是工作流的价值，不默认抹掉；由作者按节点决定授予多少「自主权」。
+
 输入 /workflows 查看可用工作流列表。

package/plugins/workflow-runner/commands/workflows.md

@@ -6,3 +6,5 @@ description: 列出当前 cwd 与插件包内可用的 YAML 工作流
 
 由 workflow-runner 插件接管（plugin.ts.runCommand），扫描 cwd/workflows/ 与
 plugin 自带 examples/ 下的 *.yaml，把名称 + 一行描述列出来。
+
+提示：用 `agent:` 节点可把开放式的一步交给有界 TAOR 子 agent 随机应变完成；用 `onError: recover` 可让失败节点交给恢复 agent 自适应救回（而非整条崩停）。二者共用同一套「自我验证 / 不伪造」纪律——详见 `/workflow` 命令说明。

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

@@ -0,0 +1,100 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/src/agentCommon.ts —— workflow 内「有界 agent」的共享大脑
+ * ------------------------------------------------------------
+ *  工作流里有两处会临时起一个 agent（都跑 miniReAct）：
+ *    - onError:'recover'（recovery.ts）—— 节点失败后救火
+ *    - agent: 节点（stepExecutors/agent.ts）—— 作者显式声明的开放任务
+ *  二者本质同构：受工作流目标/上下文指导、用工具随机应变、产出经验证后回灌 capture。
+ *  为避免「同一个脑子写两份提示词、行为漂移」，这里收敛它们的**共享件**：
+ *    1. 统一系统提示词纪律（DISCIPLINE）—— 诊断→动手→自我验证→诚实失败(不伪造)→输出纪律；
+ *       两处只在前面各加一句**角色开场白**（recover=救火 / agent=自主完成一步）。
+ *    2. 统一验证闸门（interpretMiniReActResult）—— miniReAct 跑完后，判定「真交付」还是
+ *       「放弃/不可信」，**永不把没验证过的产出当成功**。这是 Phase 2 验证闸门的提取。
+ * ============================================================
+ */
+/** agent 显式放弃的唯一标记；与 DISCIPLINE 收尾约束严格对应。recover 与 agent 节点共用。 */
+export const GIVEUP_MARKER = '__AGENT_GIVEUP__';
+/** 共享纪律块：所有 workflow 内 agent 的通用行为约束（角色开场白由各调用方拼在前面）。 */
+const DISCIPLINE = `按这个纪律干活：
+1. 先想清楚「这一步要产出什么」，必要时用只读工具（Read / Grep / Glob）做最小探查，别凭空猜、别凭空编。
+2. 用工具**实际去做**（读文件、执行命令、写文件…），不要只描述计划。
+3. **收尾前必须自我验证**：用工具确认产出确实存在且满足意图（写了文件就 Read 回来核对、跑了命令就检查退出码与输出）。没验证过不算完成。
+
+安全护栏（你握有包括 Bash 在内的全部工具，务必克制）：
+- 只做达成意图所必需的最小动作，优先可逆操作。
+- 严禁破坏性行为：不 rm -rf、不删除/覆盖与本步无关的用户数据、不碰工作目录以外的东西。
+- **绝不靠伪造、占位、或编造一段「看起来对」的文本来假装成功**——你的产出会被工作流绑给后续步骤，假结果比诚实失败更糟。
+
+收尾（二选一，硬约束）：
+- 真的达成了 → 最终消息**只输出这一步要的结果本身**，不要寒暄、不要复述要求、不要解释推理过程。若要求结构化输出，严格按 JSON Schema、**不要**用 markdown 代码块包裹。
+- 确实做不成 → 最终消息**只输出一行**：\`${GIVEUP_MARKER}: <一句话说明为什么>\`，让工作流诚实地停下。绝不要为了「交差」而编一个假结果。`;
+/** 拼一个 workflow agent 的 system prompt：角色开场白 + 共享纪律。 */
+export function buildWorkflowAgentSystem(opening) {
+    return `${opening}\n\n${DISCIPLINE}`;
+}
+/** 把 step.capture 翻成「下游会把你的结果存成哪些变量」，让 agent 产出对得上形状。 */
+export function describeCaptureContract(step) {
+    if (!step.capture)
+        return '';
+    const names = Object.values(step.capture);
+    if (names.length === 0)
+        return '';
+    return `\n\n下游契约：工作流会把你的结果保存为变量【${names.join('、')}】供后续步骤引用，请确保你的产出能填好这些变量。`;
+}
+export function truncate(s, n) {
+    return s.length > n ? `${s.slice(0, n)}…` : s;
+}
+/**
+ * 解析非 schema 模式下 agent 最终文本里的放弃标记。
+ *   - 命中 `__AGENT_GIVEUP__: <原因>` → 返回原因字符串（可能为空串）
+ *   - 未命中 → null（视为给出了真实结果）
+ */
+export function parseGiveup(text) {
+    const idx = text.indexOf(GIVEUP_MARKER);
+    if (idx === -1)
+        return null;
+    return text
+        .slice(idx + GIVEUP_MARKER.length)
+        .replace(/^[:：\s]+/, '')
+        .trim();
+}
+/**
+ * 验证闸门：把 miniReAct 的 StepResult 判定为「真交付」或「放弃/不可信」。
+ *   - schema 模式：miniReAct 已 strict 解析（解析失败会抛、落不到这里），能拿到结果即 ok；
+ *     补 content 别名不覆盖具名字段。
+ *   - 非 schema 模式：空产出 / 命中 GIVEUP 标记 → ok:false；否则 ok:true，raw 补 text/result/content
+ *     三键别名，兼容 capture:{content:x}/{result:x}/{text:x}。
+ * 注意：preview 这里给「干净版」（不加任何前缀），需要前缀的调用方（如 recover 的 "recovered: "）
+ * 自行包装。
+ */
+export function interpretMiniReActResult(result, hasSchema) {
+    if (hasSchema) {
+        const raw = { ...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) {
+        return { ok: false, reason: giveup || '显式放弃（未给原因）' };
+    }
+    const raw = {
+        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/index.js

@@ -1,6 +1,6 @@
 /**
  * ============================================================
- *  src/workflows/index.ts —— /workflow 与 /workflows 命令的胶水层
+ *  plugins/workflow-runner/src/index.ts —— /workflow 与 /workflows 命令的胶水层
  * ------------------------------------------------------------
  *  作为 pluginRunner 与 runner 之间的桥：
  *    - runWorkflowFromCommand：解析 /workflow <name> --input k=v args 调度
@@ -189,7 +189,20 @@ export async function* runWorkflowFromCommand(rawArgs, opts) {
         signal: opts.signal,
         history: opts.history,
     };
-    yield* runWorkflow(def, coerced, ctx);
+    // 透传 runWorkflow 的事件，并观察是否出现终结事件（error / interrupted = 失败或中断，
+    // 与 gateway broker 的 TERMINAL 判定同一套逻辑）。成功（没见到终结事件）则在末尾补一条
+    // 通用 `turn_done`，让对外流式协议以通用终结事件收口——否则成功 workflow 只发私有
+    // workflow_done：gateway TERMINAL 不认它 → 子进程关闭时误补 interrupted；
+    // `-p --output-format json` 因无 turn_done → stop_reason 兜底 error → ok:false（成功却报失败）。
+    // 与 runWorkflowsList 末尾的 turn_done 是同一约定；失败/中断不补（error/interrupted 已是终结）。
+    let sawTerminal = false;
+    for await (const ev of runWorkflow(def, coerced, ctx)) {
+        if (ev.type === 'error' || ev.type === 'interrupted')
+            sawTerminal = true;
+        yield ev;
+    }
+    if (!sawTerminal)
+        yield { type: 'turn_done' };
 }
 /** /workflows —— 列出可用 workflow。yield 一条 text 事件让 UI 显示。 */
 export async function* runWorkflowsList() {

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

@@ -144,6 +144,12 @@ export const VALID_STEP_TYPES = new Set([
     'parallel',
     'vote',
 ]);
+// 动作字段里「自带 kind 含义」的那几个（不含 type —— type 的 kind 由其值决定）。
+// 单一来源：validateSteps 的 actionFields + test/editorSchemaSync.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 validateSteps(steps, file, pathPrefix) {
     const seenIds = new Set();
     for (const [i, item] of steps.entries()) {
@@ -164,15 +170,25 @@ function validateSteps(steps, file, pathPrefix) {
         if (s.type !== undefined && (typeof s.type !== 'string' || !VALID_STEP_TYPES.has(s.type))) {
             throw new WorkflowLoadError(`${p}.type "${String(s.type)}" 非法；合法值: ${[...VALID_STEP_TYPES].join(' / ')}`, file);
         }
-        // 动作字段恰好一个
-        const actionFields = ['tool', 'skill', 'llm', 'type'];
+        // 动作字段恰好一个（ACTION_KINDS 单一来源 + 控制流 type）
+        const actionFields = [...ACTION_KINDS, 'type'];
         const present = actionFields.filter((k) => s[k] !== undefined);
         if (present.length === 0) {
-            throw new WorkflowLoadError(`${p} 必须有以下字段之一: tool / skill / llm / type`, file);
+            throw new WorkflowLoadError(`${p} 必须有以下字段之一: ${actionFields.join(' / ')}`, file);
         }
         if (present.length > 1) {
             throw new WorkflowLoadError(`${p} 同时设置了 ${present.join(', ')}；只允许其中一个`, file);
         }
+        // onError 枚举校验：runner 只认 halt/continue/recover，typo 会被静默当 halt，
+        // 故在加载期拦掉，给作者明确错误。
+        if (s.onError !== undefined &&
+            !ON_ERROR_VALUES.includes(s.onError)) {
+            throw new WorkflowLoadError(`${p}.onError "${String(s.onError)}" 非法；合法值: ${ON_ERROR_VALUES.join(' / ')}`, file);
+        }
+        // recover_hint 必须是字符串（仅 onError:'recover' 时有意义，但不强制配对）
+        if (s.recover_hint !== undefined && typeof s.recover_hint !== 'string') {
+            throw new WorkflowLoadError(`${p}.recover_hint 必须是 string`, file);
+        }
         // 控制流字段一致性
         if (s.type === 'branch' && s.condition === undefined) {
             throw new WorkflowLoadError(`${p} type=branch 必须带 'condition'`, file);

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

@@ -2,9 +2,18 @@
  * ============================================================
  *  plugins/workflow-runner/src/miniReAct.ts —— 简化版 ReAct 子循环
  * ------------------------------------------------------------
- *  ADR-05 阶段 4：当 llm step 声明 context_files 时，execLlmStep 会调本子循环
- *  代替单轮 chat()。本循环只做最纯净的 ReAct：调 LLM → 执行 tool_call → 喂回
- *  → 再调 → 直到模型不再调工具或达到 maxTurns。
+ *  本循环只做最纯净的 ReAct：调 LLM → 执行 tool_call → 喂回 → 再调 → 直到模型
+ *  不再调工具或达到 maxTurns。**有三个调用方**（都要「有界、白名单、不污染主
+ *  history、直接拿 StepResult」）：
+ *    - execLlmStep 的 context_files 分支（llm.ts，maxTurns 默认 10）
+ *    - agent: 节点（stepExecutors/agent.ts，默认 12）
+ *    - onError:'recover' 恢复 agent（recovery.ts，默认 12）
+ *
+ *  **流式**：本循环边跑边 yield UI 事件——text（答案）/ reasoning（思维链）/
+ *  tool_start/tool_end（工具）/ **stage_change（thinking→streaming→tool_executing，
+ *  对齐 src/loop.ts::runQuery）**。stage_change 是 TUI LiveArea 显示的开关（idle 时
+ *  LiveArea 整块隐藏），没有它则上述内层事件在 TUI 上发了也看不见。output_schema
+ *  模式下**仍切 stage、但不回显 text**（避免把 JSON 原文当答案刷屏，对齐 llm.ts）。
  *
  *  为什么不复用 src/loop.ts::runQuery？
  *    - runQuery 依赖太重：history 持久化、自动压缩、反应式压缩自救、
@@ -23,7 +32,11 @@
  */
 import { chat, executeTool, } from '../../../src/plugin-sdk.js';
 /**
- * 执行一次 ReAct 子循环。返回最终 StepResult（与 execLlmStep 老路径形状一致）。
+ * 执行一次 ReAct 子循环。**边跑边 yield UI 事件（stage_change / text / reasoning /
+ * tool_start / tool_end），同时 return 最终 StepResult**——让 recover / agent 节点 /
+ * llm+context_files 三处子 agent 的内层思考在 TUI / webchat 实时可见（之前是纯 async
+ * 不 yield，"哑"的；且漏发 stage_change 时 TUI LiveArea 整块隐藏，等于没显示）。
+ * 调用方用 `const result = yield* runMiniReAct(...)` 既透传事件、又拿到 StepResult。
  *
  * 抛错场景：
  *   - 用户中断（signal.aborted）
@@ -31,7 +44,7 @@ import { chat, executeTool, } from '../../../src/plugin-sdk.js';
  *   - 用尽 maxTurns 仍未收敛
  *   - output_schema 解析失败 / 非对象
  */
-export async function runMiniReAct(args) {
+export async function* runMiniReAct(args) {
     const { messages, tools, output_schema, provider, signal } = args;
     const maxTurns = args.maxTurns ?? 10;
     // 工作消息列表：拷贝一份，避免污染调用方
@@ -57,6 +70,11 @@ export async function runMiniReAct(args) {
         // ---- 1. 调 LLM 并累积流式响应 ----
         let textAccum = '';
         const toolCallsAccum = [];
+        // 进 LLM 流前本质是「等首 token」= thinking；首个 text_delta 时切 streaming（一次性）。
+        // 对齐 src/loop.ts::runQuery —— 没有这两个 stage_change，TUI LiveArea 会一直 idle 隐藏，
+        // 下面 yield 的 text/reasoning/tool 事件在 TUI 上等于白发。
+        let stageStreamingYielded = false;
+        yield { type: 'stage_change', stage: 'thinking' };
         for await (const ev of chat({
             provider,
             messages: conv,
@@ -66,14 +84,26 @@ export async function runMiniReAct(args) {
         })) {
             if (ev.type === 'text_delta') {
                 textAccum += ev.delta;
+                if (!stageStreamingYielded) {
+                    stageStreamingYielded = true;
+                    yield { type: 'stage_change', stage: 'streaming' };
+                }
+                // output_schema 模式：切了 streaming 阶段但**不回显 JSON 原文**（不把结构化产出
+                // 当答案刷屏，对齐 llm.ts:121 的克制）；非 schema 模式才把答案流式 yield 给 UI。
+                if (!output_schema)
+                    yield { type: 'text', delta: ev.delta };
             }
             else if (ev.type === 'tool_call_delta') {
                 mergeToolCallDelta(toolCallsAccum, ev);
             }
+            else if (ev.type === 'reasoning_delta') {
+                // 思维链字符串增量透传给 UI（reasoning_details 是结构化数组、无 delta，跳过）
+                if (ev.delta)
+                    yield { type: 'reasoning', delta: ev.delta };
+            }
             else if (ev.type === 'done' && ev.stopReason === 'aborted') {
                 throw new Error('用户中断');
             }
-            // reasoning_delta / 其它事件忽略
         }
         // ---- 2. 把 assistant 消息推入 conv ----
         conv.push({
@@ -89,6 +119,8 @@ export async function runMiniReAct(args) {
         }
         lastTurnHadToolCalls = true;
         // ---- 4. 执行所有 tool_calls，结果回填为 tool 消息 ----
+        // 进工具执行 = tool_executing 阶段（驱动 TUI LiveArea 显示运行中工具，对齐 loop.ts:340）。
+        yield { type: 'stage_change', stage: 'tool_executing' };
         for (const tc of toolCallsAccum) {
             // 重复检测
             const sig = `${tc.function.name}:${tc.function.arguments}`;
@@ -99,11 +131,27 @@ export async function runMiniReAct(args) {
             }
             if (signal?.aborted)
                 throw new Error('用户中断');
+            // 执行前后 yield tool_start/tool_end，让 UI 看到子 agent 在用工具（事件形状对齐
+            // src/loop.ts；miniReAct 串行执行，顺序 yield 即可，不需要 loop 的并行事件队列）。
+            yield {
+                type: 'tool_start',
+                toolName: tc.function.name,
+                toolCallId: tc.id,
+                argsPreview: previewArgs(tc.function.arguments),
+            };
             const result = await executeTool(tc.function.name, tc.function.arguments, signal);
+            const toolContent = result.ok ? result.content : `工具错误: ${result.error}`;
+            yield {
+                type: 'tool_end',
+                toolName: tc.function.name,
+                toolCallId: tc.id,
+                ok: result.ok,
+                content: toolContent,
+            };
             conv.push({
                 role: 'tool',
                 tool_call_id: tc.id,
-                content: result.ok ? result.content : `工具错误: ${result.error}`,
+                content: toolContent,
             });
         }
         // 继续下一轮
@@ -153,3 +201,8 @@ function mergeToolCallDelta(acc, ev) {
     if (ev.argumentsDelta)
         slot.function.arguments += ev.argumentsDelta;
 }
+/** 给 tool_start 事件用的参数预览（压成一行、截断到 60 字符），与 loop.ts previewArgs 同义。 */
+function previewArgs(rawJson) {
+    const oneLine = rawJson.replace(/\s+/g, ' ').trim();
+    return oneLine.length <= 60 ? oneLine : `${oneLine.slice(0, 60)}...`;
+}

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

@@ -0,0 +1,107 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/src/recovery.ts —— 节点失败的自适应恢复
+ * ------------------------------------------------------------
+ *  「确定性工作流 × 随机应变 agent」的结合点（onError:'recover'）。
+ *
+ *  传统 DAG 的脆点：某节点抛错 → 整条 halt（或 onError:'continue' 盲跳，下游
+ *  capture 拿 undefined 静默级联错）。当节点声明 onError:'recover' 时，runner
+ *  不立刻 halt，而是调本模块起一个**有界恢复 agent**（复用 miniReAct），喂给它
+ *  「工作流总目标 + 失败节点的意图 + 错误信息 + 当前已知变量 + 下游 capture 契约」，
+ *  让它**随机应变去达成该节点本来要的结果**（换路径 / 换命令 / 先读后写…）。
+ *
+ *  —— 共享大脑 ——
+ *  恢复 agent 与 agent: 节点（stepExecutors/agent.ts）本质同构，故系统提示词纪律与
+ *  验证闸门都收敛在 agentCommon.ts：本模块只贴一句「救火」角色开场白（RECOVER_OPENING），
+ *  跑完后交给 interpretMiniReActResult 判定「真救回 / 放弃」——绝不把没验证过的产出当成功
+ *  绑给下游。返回 AgentOutcome：
+ *    - { ok:true, value }  —— runner 用同一个 step.capture 绑定后继续 happy path
+ *    - { ok:false, reason } —— runner 带原因 honest halt
+ *
+ *  设计取舍：复用 miniReAct 而非 runQuery —— 恢复要的正是「有界、白名单、不污染主
+ *  history、直接返回 StepResult」；默认全量 ALL_TOOLS（与 skill/agent 节点同等授权、
+ *  同一信任边界），step.allowed_tools 可收窄。本函数是 AsyncGenerator，yield*
+ *  runMiniReAct 把恢复 agent 的内层思考透传给 UI；warning/plugin_progress/halt 仍由
+ *  runner 在调用前后发（事件卫生集中在 runner）。
+ * ============================================================
+ */
+import { ALL_TOOLS } from '../../../src/plugin-sdk.js';
+import { buildWorkflowAgentSystem, describeCaptureContract, interpretMiniReActResult, truncate, } from './agentCommon.js';
+import { interpolate, interpolateDeep } from './expressions.js';
+import { runMiniReAct } from './miniReAct.js';
+const RECOVER_OPENING = `你是一名资深的自动化工程师 / SRE，被一个确定性工作流临时调来「救火」。
+工作流里一个原本写死的步骤刚刚执行失败了，现在交给你随机应变——先看错误信息诊断根因，再想办法真正达成这个步骤**本来要的结果**（关注它要的结果，别拘泥它原先怎么写）。`;
+const RECOVERY_SYSTEM = buildWorkflowAgentSystem(RECOVER_OPENING);
+/** 描述失败节点「本来要干什么」，喂给恢复 agent 作为意图说明。 */
+function describeStepIntent(step, vars) {
+    if (step.tool) {
+        const args = interpolateDeep(step.args ?? {}, vars);
+        return `调用工具 ${step.tool}，参数：${JSON.stringify(args)}`;
+    }
+    if (step.agent) {
+        return `自主完成这个开放任务：${interpolate(step.agent, vars)}`;
+    }
+    if (step.llm) {
+        return `用 LLM 生成内容，提示词：${interpolate(step.llm, vars)}`;
+    }
+    if (step.skill) {
+        const input = step.input ? interpolate(step.input, vars) : '(无显式输入)';
+        return `执行 skill「${interpolate(step.skill, vars)}」，输入：${input}`;
+    }
+    if (step.type === 'assert') {
+        return `让这个断言成立：${step.condition}`;
+    }
+    return `完成步骤 ${step.id}`;
+}
+/**
+ * 尝试自适应恢复一个失败的动作 step。
+ *   - 救回 → { ok:true, value }（value.raw 已 normalize，可被原 step.capture 绑定）
+ *   - 放弃 / 不可信 / 子循环抛错（含用户中断）→ { ok:false, reason }
+ *     （中断的最终语义由调用方在拿到结果后另行检测 ctx.signal 决定）
+ */
+export async function* runRecovery(step, vars, ctx, errorMsg) {
+    const intent = describeStepIntent(step, vars);
+    const knownVars = truncate(JSON.stringify(vars.snapshot()), 1500);
+    const goalLine = ctx.goal ? `工作流总目标：${ctx.goal}\n\n` : '';
+    const captureLine = describeCaptureContract(step);
+    const hintLine = step.recover_hint
+        ? `\n\n作者给恢复的提示：${interpolate(step.recover_hint, vars)}`
+        : '';
+    const userMsg = `${goalLine}` +
+        `失败的步骤（id=${step.id}）本来要做的事：\n${intent}\n\n` +
+        `它失败时的错误：\n${truncate(errorMsg, 800)}\n\n` +
+        `当前已知的变量（JSON）：\n${knownVars}` +
+        `${captureLine}${hintLine}\n\n` +
+        `请随机应变，把这一步要的结果做出来；做不成就按约定输出放弃标记。`;
+    // 工具集：默认全量（与 skill/agent 节点同等 agency）；step.allowed_tools 收窄。
+    const allowed = step.allowed_tools;
+    const tools = allowed && allowed.length > 0
+        ? ALL_TOOLS.filter((t) => allowed.includes(t.name))
+        : ALL_TOOLS;
+    const messages = [
+        { role: 'system', content: RECOVERY_SYSTEM },
+        { role: 'user', content: userMsg },
+    ];
+    try {
+        const result = yield* runMiniReAct({
+            messages,
+            tools,
+            output_schema: step.output_schema,
+            provider: ctx.provider,
+            signal: ctx.signal,
+            maxTurns: step.maxTurns ?? 12,
+        });
+        const outcome = interpretMiniReActResult(result, step.output_schema !== undefined);
+        if (!outcome.ok)
+            return outcome;
+        // 救回：preview 加 recovered: 前缀（runner 的 step_end output 用），raw 原样。
+        return {
+            ok: true,
+            value: { raw: outcome.value.raw, preview: `recovered: ${outcome.value.preview}` },
+        };
+    }
+    catch (e) {
+        // miniReAct 抛错（用尽轮数 / 重复工具调用 / schema 解析失败 / 中断）→ 恢复失败。
+        return { ok: false, reason: e.message ?? String(e) };
+    }
+}

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

@@ -10,9 +10,11 @@
  *    - 信号 abort → yield interrupted 后 return
  *
  *  支持的 step kind（loader 已校验）：
- *    - tool / llm / assert    —— 原子动作（execXxxStep 返回 StepResult）
- *    - skill                  —— 迷你 ReAct 子循环（透传子事件 + 累计 text）
- *    - branch / loop / pause  —— 控制流，直接在 runSteps 内处理（不走 executor）
+ *    - tool / llm / assert            —— 原子动作（execXxxStep 返回 StepResult）
+ *    - agent / skill                  —— 有界 TAOR：miniReAct(agent) / 外部 SKILL.md(skill)；
+ *                                        透传子事件（stage_change/text/reasoning/tool_*）
+ *    - branch / loop / pause          —— 控制流，直接在 runSteps 内处理（不走 executor）
+ *    - parallel / vote                —— 并发 / 投票门，也在 runSteps 内处理
  *
  *  控制流嵌套通过 runSteps 递归实现：branch.then/else / loop.do 子数组
  *  是 StepDef[]，调用方语义与顶层 def.steps 一致；变量栈用 VarStack.push/pop
@@ -21,6 +23,8 @@
  */
 import { getWorkingDir } from '../../../src/plugin-sdk.js';
 import { evalExpr, interpolate } from './expressions.js';
+import { runRecovery } from './recovery.js';
+import { execAgentStep } from './stepExecutors/agent.js';
 import { execAssertStep } from './stepExecutors/assert.js';
 import { execLlmStep } from './stepExecutors/llm.js';
 import { execSkillStep } from './stepExecutors/skill.js';
@@ -42,6 +46,8 @@ function stepKind(step) {
         return 'tool';
     if (step.skill)
         return 'skill';
+    if (step.agent)
+        return 'agent';
     if (step.llm)
         return 'llm';
     return 'assert'; // 不会到这里（loader 已校验），兜底
@@ -65,19 +71,21 @@ function bindCapture(captureMap, result, vars) {
     }
 }
 /**
- * 分发"动作"型 step（tool / llm / skill / assert）到对应 executor。
- * 控制流 step（branch / loop / pause）由 runSteps 直接处理，不走这里。
+ * 分发"动作"型 step（tool / agent / llm / skill / assert）到对应 executor。
+ * 控制流 step（branch / loop / pause / parallel / vote）由 runSteps 直接处理，不走这里。
  */
 async function* dispatchActionStep(step, vars, ctx) {
     if (step.type === 'assert')
         return execAssertStep(step, vars);
     if (step.tool)
         return yield* execToolStep(step, vars, ctx);
+    if (step.agent)
+        return yield* execAgentStep(step, vars, ctx);
     if (step.llm)
         return yield* execLlmStep(step, vars, ctx);
     if (step.skill)
         return yield* execSkillStep(step, vars, ctx);
-    throw new Error(`step ${step.id}: 无可执行字段（tool/llm/skill/assert）`);
+    throw new Error(`step ${step.id}: 无可执行字段（tool/agent/llm/skill/assert）`);
 }
 /**
  * 递归执行 steps[]。返回 true 表示该 block 已 halt（上游应中止）。
@@ -396,6 +404,54 @@ async function* runSteps(steps, vars, ctx, state) {
         catch (e) {
             const errMsg = e.message ?? String(e);
             await state.appendProgress(`✗ ${step.id}: ${errMsg}`);
+            // onError:'recover' —— 不立刻 halt，交给有界恢复 agent 随机应变把这一步救回来。
+            // 「确定性工作流 × TAOR」的结合点：happy path 走刚性 DAG，撞上预料之外的就地
+            // 降级为 agent 自适应；救回则继续 happy path，救不回才 honest halt。
+            if (step.onError === 'recover') {
+                yield {
+                    type: 'warning',
+                    message: `step "${step.id}" 失败：${errMsg}；尝试自适应恢复…`,
+                };
+                yield {
+                    type: 'plugin_progress',
+                    pluginId: WF_PLUGIN_ID,
+                    current: i + 1,
+                    max: steps.length,
+                    message: `↻ 恢复 ${step.id}…`,
+                };
+                const rec = yield* runRecovery(step, vars, ctx, errMsg);
+                if (ctx.signal?.aborted) {
+                    yield { type: 'interrupted' };
+                    return true;
+                }
+                // 验证闸门：只有恢复 agent 真正交付（rec.ok）才绑 capture 走下去；
+                // 显式放弃 / 产出不可信（rec.ok=false）则带原因 honest halt，绝不盲绑脏值。
+                if (rec.ok) {
+                    if (step.capture)
+                        bindCapture(step.capture, rec.value, vars);
+                    await state.appendProgress(`⚠→✓ ${step.id} recovered`);
+                    await state.writeVars(vars.snapshot());
+                    yield {
+                        type: 'workflow_step_end',
+                        id: step.id,
+                        ok: true,
+                        output: rec.value.preview,
+                    };
+                    continue;
+                }
+                const combined = `${errMsg}（自适应恢复未成功：${rec.reason}）`;
+                yield {
+                    type: 'workflow_step_end',
+                    id: step.id,
+                    ok: false,
+                    error: combined,
+                };
+                yield {
+                    type: 'error',
+                    error: `Workflow halted at step "${step.id}": ${combined}`,
+                };
+                return true;
+            }
             if (step.onError === 'continue') {
                 yield {
                     type: 'workflow_step_end',
@@ -424,12 +480,20 @@ async function* runSteps(steps, vars, ctx, state) {
  * 运行一个 workflow。
  *
  * yields 混合事件：本地 WorkflowEvent（workflow_* 系列，UI 静默忽略不渲染）
- * + 通用 LoopEvent（error / interrupted 等，UI 识别并渲染）。
- * 经 plugin.ts -> pluginRunner 透传给 UI；workflow_* 由 PluginEvent 开放契约承载。
+ * + 通用 LoopEvent（error / interrupted / 子 step 透传的 text/tool/stage_change 等，
+ * UI 识别并渲染）。经 plugin.ts -> pluginRunner 透传给 UI；workflow_* 由 PluginEvent
+ * 开放契约承载。
+ *
+ * 成功跑完以 `workflow_done` 收尾（携带 vars 快照）；中途失败/中断只 yield error/interrupted。
+ * **对外流式协议的通用终结事件 `turn_done` 由命令层 index.ts 在成功后补发**（见那里）——
+ * 本函数自身事件序列保持不变，直测它的 runner.test.ts / 单元测试仍以 workflow_done 为最后一条。
  */
 export async function* runWorkflow(def, inputs, ctx) {
     const vars = new VarStack();
     vars.setGlobal('inputs', inputs);
+    // onError:'recover' 用：把工作流总目标（description）透传给恢复 agent，
+    // 让它知道「这条工作流到底想干什么」。已有 goal 则不覆盖。
+    const runCtx = { ...ctx, goal: ctx.goal ?? def.description };
     const state = new WorkflowState(getWorkingDir());
     await state.init(def.name, inputs);
     yield {
@@ -446,7 +510,7 @@ export async function* runWorkflow(def, inputs, ctx) {
         message: `▶ workflow ${def.name}`,
     };
     try {
-        const halted = yield* runSteps(def.steps, vars, ctx, state);
+        const halted = yield* runSteps(def.steps, vars, runCtx, state);
         if (halted)
             return;
         // 完成态也给一条 plugin_progress（放在 workflow_done 之前，保证