minimal-agent 0.10.0 → 0.12.0

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

@@ -0,0 +1,338 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/src/index.ts —— /workflow 与 /workflows 命令的胶水层
+ * ------------------------------------------------------------
+ *  作为 pluginRunner 与 runner 之间的桥：
+ *    - runWorkflowFromCommand：解析 /workflow <name> --input k=v args 调度
+ *    - runWorkflowsList：处理 /workflows 列表展示（yield "text" 事件让 UI 显示）
+ *
+ *  R1 红线：本文件只在 pluginRunner 命中 workflow 模式时才被 import。
+ *  不污染默认 T-A-O-R 路径。
+ * ============================================================
+ */
+
+import {
+  type LoopEvent,
+  type Message,
+  type PluginContext,
+  type Provider,
+  type Tool,
+  buildBaseSystemPrompt,
+} from '../../../src/plugin-sdk.js';
+import { findWorkflowByName, listWorkflows } from './loader.js';
+import { runWorkflow } from './runner.js';
+import type { InputDef, RunContext, WorkflowEvent } from './types.js';
+
+export interface RunWorkflowFromCommandOptions {
+  provider: Provider;
+  runtimeContext?: import('../../../src/plugin-sdk.js').AgentRuntimeContext;
+  history: Message[];
+  signal?: AbortSignal;
+  /** 会话状态（驱动 microCompact / reactiveCompact） */
+  sessionState?: import('../../../src/plugin-sdk.js').SessionState;
+  /** 当前工作目录（默认 process.cwd()） */
+  cwd?: string;
+  /** 宿主过滤后的可用工具列表；缺省为空，绝不在 runner 内恢复全量工具。 */
+  tools?: Tool[];
+  transientContext?: string;
+  transientBundle?: import('../../../src/plugin-sdk.js').ContextBundle;
+  promptCache?: import('../../../src/plugin-sdk.js').PromptCacheContext;
+  executeTool?: PluginContext['executeTool'];
+  toolContext?: RunContext['toolContext'];
+  /**
+   * 宿主授权上下文（浏览器 / 电脑操控）。
+   *
+   * 引擎**不会**无条件把它转给每一步 —— 只有显式写了 `uses:` 的步骤才拿得到对应那片
+   * （见 `StepDef.uses`）。一份 yaml 无人值守地跑，隐式全权是危险的。
+   */
+  host?: import('../../../src/plugin-sdk.js').PluginContext['host'];
+}
+
+/**
+ * 把 "/workflow <name> [pos1 pos2 ...] [--input k=v ...]" 拆成 name + 显式 inputs + 位置参数。
+ * 简单解析器（不依赖第三方）：
+ *   - 第一个非 flag token = name；末尾 ".yaml" / ".yml" 自动剥（便于直接用文件名）
+ *   - 之后所有非 flag token 收进 positional[]，由调用方按 def.inputs 声明顺序映射
+ *   - --input k=v 显式 KV，优先级高于位置参数（同名 input 不会被位置参数覆盖）
+ *   - 不识别其他 flag（保守跳过其后一个 token）
+ */
+export function parseWorkflowArgs(rawArgs: string): {
+  name: string | null;
+  inputs: Record<string, string>;
+  positional: string[];
+} {
+  const tokens = tokenizeArgs(rawArgs);
+  const inputs: Record<string, string> = {};
+  const positional: string[] = [];
+  let name: string | null = null;
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i];
+    if (t === '--input') {
+      const kv = tokens[i + 1];
+      if (!kv) break;
+      const eq = kv.indexOf('=');
+      if (eq > 0) {
+        inputs[kv.slice(0, eq)] = kv.slice(eq + 1);
+      }
+      i++;
+      continue;
+    }
+    if (t.startsWith('--')) {
+      // 未知 flag：跳过其后一个 token（保守地认为它带值）
+      i++;
+      continue;
+    }
+    if (name === null) {
+      name = t.replace(/\.ya?ml$/i, '');
+    } else {
+      positional.push(t);
+    }
+  }
+  return { name, inputs, positional };
+}
+
+/** 简单 token 化：双引号包裹的整体当一个 token；其它按空白切。 */
+function tokenizeArgs(s: string): string[] {
+  const out: string[] = [];
+  let i = 0;
+  while (i < s.length) {
+    while (i < s.length && /\s/.test(s[i])) i++;
+    if (i >= s.length) break;
+    if (s[i] === '"' || s[i] === "'") {
+      const q = s[i];
+      i++;
+      let acc = '';
+      while (i < s.length && s[i] !== q) {
+        acc += s[i++];
+      }
+      if (i < s.length) i++;
+      out.push(acc);
+    } else {
+      let acc = '';
+      while (i < s.length && !/\s/.test(s[i])) {
+        acc += s[i++];
+      }
+      out.push(acc);
+    }
+  }
+  return out;
+}
+
+/**
+ * 把字符串形态的 input 值按 InputDef.type 转成合适的 JS 类型 + 校验。
+ * 校验失败抛 Error，pluginRunner 会把它转成 error event。
+ */
+function coerceInputs(
+  raw: Record<string, string>,
+  defs: InputDef[] | undefined,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (!defs) return { ...raw };
+
+  for (const def of defs) {
+    const rawVal = raw[def.name];
+    if (rawVal === undefined) {
+      if (def.required) {
+        throw new Error(`缺少必填 input: ${def.name}`);
+      }
+      if (def.default !== undefined) {
+        out[def.name] = def.default;
+      }
+      continue;
+    }
+    if (def.type === 'number') {
+      const n = Number.parseFloat(rawVal);
+      if (Number.isNaN(n))
+        throw new Error(`input ${def.name} 必须是数字，收到 "${rawVal}"`);
+      out[def.name] = n;
+    } else if (def.type === 'enum') {
+      if (!def.values?.includes(rawVal)) {
+        throw new Error(
+          `input ${def.name} 必须是 [${def.values?.join(', ')}] 之一，收到 "${rawVal}"`,
+        );
+      }
+      out[def.name] = rawVal;
+    } else {
+      out[def.name] = rawVal;
+    }
+  }
+  // 未声明的 input 也透传（让 yaml 里可以引用 ad-hoc 变量）
+  for (const k of Object.keys(raw)) {
+    if (!(k in out)) out[k] = raw[k];
+  }
+  return out;
+}
+
+async function refreshWorkflowSystemPrompt(
+  history: Message[],
+  cwd: string,
+  tools: Tool[],
+): Promise<void> {
+  // 只刷稳定层：workflow 一跑就是几十步，system 消息若含日期/记忆等易变内容，
+  // 每步都会重写 history[0]、把 provider 前缀缓存打散（见 prompts/system.ts）。
+  const content = await buildBaseSystemPrompt(cwd, tools);
+  const systemIndex = history.findIndex(
+    (m) => m.role === 'system' && !m._ephemeral,
+  );
+  const fresh: Message = { role: 'system', content };
+
+  if (systemIndex === 0) {
+    history[0] = fresh;
+    return;
+  }
+
+  if (systemIndex > 0) history.splice(systemIndex, 1);
+  history.unshift(fresh);
+}
+
+/** /workflow <name> [pos...] [--input k=v] —— 主入口，由 pluginRunner 调用。 */
+export async function* runWorkflowFromCommand(
+  rawArgs: string,
+  opts: RunWorkflowFromCommandOptions,
+): AsyncGenerator<WorkflowEvent | LoopEvent, void, void> {
+  const { name, inputs: rawInputs, positional } = parseWorkflowArgs(rawArgs);
+  if (!name) {
+    yield {
+      type: 'error',
+      error:
+        '/workflow 用法: /workflow <name> [val ...] [--input key=val ...]\n输入 /workflows 查看可用工作流。',
+    };
+    return;
+  }
+  const def = await findWorkflowByName(name);
+  if (!def) {
+    yield {
+      type: 'error',
+      error: `未找到 workflow "${name}"。输入 /workflows 查看可用列表。`,
+    };
+    return;
+  }
+
+  const cwd = opts.cwd ?? process.cwd();
+  const tools = opts.tools ?? [];
+  await refreshWorkflowSystemPrompt(opts.history, cwd, tools);
+
+  // 位置参数映射，两种模式：
+  //   - 贪婪首参（def.inputs[0].greedy===true）：把【全部】位置参数用空格 join 成整句写进
+  //     首个 input（自然语言 brief 不被空格拆碎、也不会撞上后面的 number/enum 输入），
+  //     其余 input 只走 --input。用户「打一句话」即可（见 webppt.yaml::topic）。
+  //   - 默认：严格按"第 i 个位置参数 ↔ def.inputs[i]"对应。
+  // --input k=v 显式优先：已显式的 input 不被位置参数覆盖（对应位置参数被丢弃，会 warn）。
+  const overriddenByKV: string[] = [];
+  const greedyFirst = def.inputs?.[0]?.greedy === true;
+  if (greedyFirst && def.inputs && positional.length > 0) {
+    const greedyName = def.inputs[0].name;
+    if (greedyName in rawInputs) {
+      // 首参已被 --input 占位 → 整串位置参数被忽略
+      overriddenByKV.push(
+        `${greedyName}=${JSON.stringify(rawInputs[greedyName])} (位置参数 ${JSON.stringify(positional.join(' '))} 被忽略)`,
+      );
+    } else {
+      // 贪婪吸收：整句进首参（空格 join 还原用户原话，不逐位拆映射）
+      rawInputs[greedyName] = positional.join(' ');
+    }
+  } else if (positional.length > 0 && def.inputs) {
+    const max = Math.min(positional.length, def.inputs.length);
+    for (let i = 0; i < max; i++) {
+      const inputDef = def.inputs[i];
+      if (inputDef.name in rawInputs) {
+        // 已被 --input 占位，位置参数被丢弃
+        if (rawInputs[inputDef.name] !== positional[i]) {
+          overriddenByKV.push(
+            `${inputDef.name}=${JSON.stringify(rawInputs[inputDef.name])} (位置参数 ${JSON.stringify(positional[i])} 被忽略)`,
+          );
+        }
+      } else {
+        rawInputs[inputDef.name] = positional[i];
+      }
+    }
+  }
+
+  // warn：超量位置参数（仅非 greedy 模式；greedy 全部吸收进首参，不算多余）
+  if (!greedyFirst && def.inputs && positional.length > def.inputs.length) {
+    const dropped = positional.slice(def.inputs.length);
+    yield {
+      type: 'warning',
+      message: `⚠ 忽略了 ${dropped.length} 个多余位置参数: ${dropped.map((d) => JSON.stringify(d)).join(' ')}（workflow "${name}" 只声明了 ${def.inputs.length} 个 input）`,
+    };
+  }
+  // warn：位置参数被 --input 覆盖
+  if (overriddenByKV.length > 0) {
+    yield {
+      type: 'warning',
+      message: `⚠ --input 优先级高于位置参数，以下位置参数被覆盖：${overriddenByKV.join('; ')}`,
+    };
+  }
+
+  let coerced: Record<string, unknown>;
+  try {
+    coerced = coerceInputs(rawInputs, def.inputs);
+  } catch (e) {
+    yield { type: 'error', error: (e as Error).message };
+    return;
+  }
+
+  const ctx: RunContext = {
+    provider: opts.provider,
+    runtimeContext: opts.runtimeContext,
+    signal: opts.signal,
+    history: opts.history,
+    sessionState: opts.sessionState,
+    cwd,
+    tools,
+    host: opts.host,
+    transientContext: opts.transientContext,
+    transientBundle: opts.transientBundle,
+    promptCache: opts.promptCache,
+    executeTool: opts.executeTool,
+    toolContext: opts.toolContext,
+  };
+
+  // 透传 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(): AsyncGenerator<
+  LoopEvent,
+  void,
+  void
+> {
+  const list = await listWorkflows();
+  if (list.length === 0) {
+    yield {
+      type: 'text',
+      delta:
+        '当前没有可用工作流。在 cwd/workflows/ 下放 *.yaml 即可（参考 workflows/schema.json 或 docs/workflow-design.md）。\n',
+    };
+    yield { type: 'turn_done' };
+    return;
+  }
+  const lines = ['可用工作流：'];
+  for (const w of list) {
+    lines.push(
+      `  /workflow ${w.name}  —  ${w.description.split('\n')[0].trim()}`,
+    );
+  }
+  lines.push('');
+  lines.push('运行示例:');
+  lines.push(
+    '  /workflow <name> <val>            位置参数（按 inputs 声明顺序，第一个 input 直接写值）',
+  );
+  lines.push('  /workflow <name>.yaml <val>       .yaml 后缀可省');
+  lines.push(
+    '  /workflow <name> --input k=v      显式 KV（多 input 或想跳过中间 input 时用）',
+  );
+  yield { type: 'text', delta: `${lines.join('\n')}\n` };
+  yield { type: 'turn_done' };
+}

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

@@ -0,0 +1,84 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/src/jsonPayload.ts —— 从 LLM 文本里提取纯 JSON 负载
+ * ------------------------------------------------------------
+ *  根因（为什么需要这个文件）：
+ *    "思考型"模型（MiniMax-M2/M3、DeepSeek-R1 系等）即使在 strict json_schema 下，
+ *    仍会把 <think>…</think> 思维链**直接写进 content 字段**（不是 reasoning_content）。
+ *    src/llm/client.ts 故意原样保留这段思维链（主循环下一轮工具调用要靠它接上下文，
+ *    见 client.ts:200-205 注释），所以"剥离思维链"不能放进通用 transport——否则会
+ *    破坏主循环。剥离必须发生在「契约要求纯 JSON」的边界，也就是 workflow 的
+ *    output_schema 解析处。本模块就是那个边界的唯一实现，被两个解析点共享：
+ *      - stepExecutors/llm.ts（llm + output_schema 单轮）
+ *      - stepExecutors/llm.ts（output_schema 解析处）
+ *    放一处、两边 import，杜绝"只修一个解析点、另一个继续炸"的漂移。
+ *
+ *  处理顺序（保守、纯函数、可单测）：
+ *    1. 去掉所有 <think>…</think> 块（多行、可多个、大小写不敏感）。
+ *       **必须先做**：思维链里常出现 { } [ ]（模型在"想" JSON 长什么样），
+ *       若不先剥，下面"找首个 JSON 起点"会错锚到思维链里的括号。
+ *    2. 兜底：只有起始 <think>、收尾 </think> 被 length 截断 → 砍掉从 <think> 起的全部。
+ *    3. 从剩余文本定位首个 { 或 [，配平括号截取到对应收尾。
+ *       这一步天然容忍 ```json 代码围栏与 JSON 前后的散文（只取配平的那一段），
+ *       所以不需要单独的"去围栏"正则（也就避免了误伤 JSON 字符串里的反引号）。
+ *    4. 找不到任何 JSON 起点 → 原样返回 trim 后文本，交调用方 JSON.parse 报
+ *       "honest error"（保留原文前若干字符便于排查）。
+ * ============================================================
+ */
+
+/**
+ * 从可能掺杂思维链 / 代码围栏 / 前后散文的文本里提取最可能的 JSON 负载字符串。
+ * 不做 JSON.parse（解析与错误信息留给调用方，便于各自定制报错文案）。
+ */
+export function extractJsonPayload(raw: string): string {
+  // 1. 去成对的思维链块
+  let s = raw.replace(/<think>[\s\S]*?<\/think>/gi, '');
+  // 2. 截断兜底：有起始无收尾（被 max tokens 截断）→ 丢弃从 <think> 起的尾巴
+  if (/<think>/i.test(s) && !/<\/think>/i.test(s)) {
+    s = s.slice(0, s.search(/<think>/i));
+  }
+  s = s.trim();
+
+  // 3. 定位首个 JSON 起点并配平截取
+  const start = firstJsonStart(s);
+  if (start === -1) return s; // 没有 JSON：原样返回，交调用方报错
+  const end = matchBalanced(s, start);
+  return end === -1 ? s.slice(start) : s.slice(start, end + 1);
+}
+
+/** 首个 { 或 [ 的下标（取更靠前者）；都没有返回 -1。 */
+function firstJsonStart(s: string): number {
+  const obj = s.indexOf('{');
+  const arr = s.indexOf('[');
+  if (obj === -1) return arr;
+  if (arr === -1) return obj;
+  return Math.min(obj, arr);
+}
+
+/**
+ * 从 start（{ 或 [）配平到对应的 } 或 ]，返回收尾下标；找不到返回 -1。
+ * 跳过字符串字面量内部的括号与转义，避免被 JSON 值里的 } / ] 误导。
+ */
+function matchBalanced(s: string, start: number): number {
+  const open = s[start];
+  const close = open === '{' ? '}' : ']';
+  let depth = 0;
+  let inStr = false;
+  let esc = false;
+  for (let i = start; i < s.length; i++) {
+    const c = s[i];
+    if (inStr) {
+      if (esc) esc = false;
+      else if (c === '\\') esc = true;
+      else if (c === '"') inStr = false;
+      continue;
+    }
+    if (c === '"') inStr = true;
+    else if (c === open) depth++;
+    else if (c === close) {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  return -1;
+}

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

@@ -193,6 +193,11 @@ export const CONTROL_FLOW_TYPES = new Set([
     'echo',
     'pause',
 ]);
+/**
+ * `uses:` 的合法取值。与 `types.ts::HostCapability` 同源 —— 加新能力要两处一起改，
+ * 单测钉住二者一致（漏改的表现是 yaml 写了却静默不生效）。
+ */
+export const VALID_HOST_CAPABILITIES = new Set(['browser', 'computer']);
 export const VALID_STEP_TYPES = new Set([
     'assert',
     'verify',
@@ -271,6 +276,24 @@ function validateSteps(steps, file, pathPrefix) {
         if (s.recover_hint !== undefined && typeof s.recover_hint !== 'string') {
             throw new WorkflowLoadError(`${p}.recover_hint 必须是 string`, file);
         }
+        // uses：宿主能力声明。写错的代价是「这一步安静地拿不到能力」，而工具的报错
+        // （「当前宿主未启用 Computer Use」）完全指不向拼错的 yaml —— 所以在加载期拦掉。
+        if (s.uses !== undefined) {
+            if (!Array.isArray(s.uses)) {
+                throw new WorkflowLoadError(`${p}.uses 必须是数组，如 uses: [computer]`, file);
+            }
+            for (const capability of s.uses) {
+                if (!VALID_HOST_CAPABILITIES.has(capability)) {
+                    throw new WorkflowLoadError(`${p}.uses 含非法能力 "${String(capability)}"；合法值: ${[...VALID_HOST_CAPABILITIES].join(' / ')}`, file);
+                }
+            }
+            // uses 只对确定性 tool 步有意义：llm/agent/skill 走 runQuery，工具上下文由
+            // 主循环提供；控制流步根本不调工具。声明在这些步上是作者的误解，早点说破。
+            if (s.tool === undefined) {
+                throw new WorkflowLoadError(`${p}.uses 只能用在 tool 步上（当前步不是 tool 步）。`
+                    + `agent/llm/skill 步的工具上下文由主循环提供，无需也不能在此声明。`, file);
+            }
+        }
         if (s.free_text !== undefined) {
             if (s.type !== 'pause') {
                 throw new WorkflowLoadError(`${p}.free_text 只能用在 type=pause 节点上`, file);