minimal-agent 0.13.0 → 0.14.0

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

@@ -1,109 +1,59 @@
 /**
  * ============================================================
- *  plugins/workflow-runner/src/index.ts —— /workflow 与 /workflows 命令的胶水层
+ *  plugins/workflow-runner/src/index.ts —— /workflow 与 /workflows 的命令胶水
  * ------------------------------------------------------------
- *  作为 pluginRunner 与 runner 之间的桥：
- *    - runWorkflowFromCommand：解析 /workflow <name> --input k=v args 调度
- *    - runWorkflowsList：处理 /workflows 列表展示（yield "text" 事件让 UI 显示）
+ *  工作流只有一种形态：`workflows/<name>/workflow.mjs`。
  *
- *  R1 红线：本文件只在 pluginRunner 命中 workflow 模式时才被 import。
- *  不污染默认 T-A-O-R 路径。
+ *  这里曾有一段「找不到就回落到 legacy yaml 引擎」的迁移期分支，随 yaml 引擎
+ *  一起删除了 —— 现在找不到就是找不到，直接报错并让用户看 /workflows。
  * ============================================================
  */
 
-import {
-  type LoopEvent,
-  type Message,
-  type PluginContext,
-  type Provider,
-  type Tool,
-  buildBaseSystemPrompt,
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { managedCommandController } from '../../../src/managedExecution/registry.js';
+import type {
+  AgentRuntimeContext,
+  ContextBundle,
+  LoopEvent,
+  Message,
+  PluginContext,
+  PromptCacheContext,
+  Provider,
+  SessionState,
+  Tool,
 } from '../../../src/plugin-sdk.js';
-import { findWorkflowByName, listWorkflows } from './loader.js';
-import { runWorkflow } from './runner.js';
-import type { InputDef, RunContext, WorkflowEvent } from './types.js';
+import { refreshStableSystemPrompt } from '../../../src/plugin-sdk.js';
+import { discoverWorkflows } from './discovery.js';
+import { coerceInputs } from './inputCoercion.js';
+import { bindResourceInputs } from './resourceInputs.js';
+import { runWorkflowScript } from './runner.js';
+import type { InputDef, RunContext } from './types.js';
 
 export interface RunWorkflowFromCommandOptions {
   provider: Provider;
-  runtimeContext?: import('../../../src/plugin-sdk.js').AgentRuntimeContext;
+  runtimeContext?: AgentRuntimeContext;
   history: Message[];
   signal?: AbortSignal;
-  /** 会话状态（驱动 microCompact / reactiveCompact） */
-  sessionState?: import('../../../src/plugin-sdk.js').SessionState;
-  /** 当前工作目录（默认 process.cwd()） */
+  sessionState?: SessionState;
   cwd?: string;
-  /** 宿主过滤后的可用工具列表；缺省为空，绝不在 runner 内恢复全量工具。 */
   tools?: Tool[];
   transientContext?: string;
-  transientBundle?: import('../../../src/plugin-sdk.js').ContextBundle;
-  promptCache?: import('../../../src/plugin-sdk.js').PromptCacheContext;
+  transientBundle?: ContextBundle;
+  promptCache?: PromptCacheContext;
   executeTool?: PluginContext['executeTool'];
   toolContext?: RunContext['toolContext'];
-  /**
-   * 宿主授权上下文（浏览器 / 电脑操控）。
-   *
-   * 引擎**不会**无条件把它转给每一步 —— 只有显式写了 `uses:` 的步骤才拿得到对应那片
-   * （见 `StepDef.uses`）。一份 yaml 无人值守地跑，隐式全权是危险的。
-   */
-  host?: import('../../../src/plugin-sdk.js').PluginContext['host'];
+  host?: PluginContext['host'];
+  inputResources?: PluginContext['inputResources'];
+  /** 传给外层控制器的不透明上下文；Workflow Runner 不解释。 */
+  managedContext?: unknown;
 }
 
 /**
- * 把 "/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 };
-}
-
-/**
- * shell 风格 token 化：空白切分 token；引号（' 或 "）在 token **任意位置**（不只开头）
- * 出现即进入引号模式——引号内的空白不切分、引号字符本身被剥离。
- *
- * 修复：`--input topic="带空格的值"`（引号在 `=` 后，token 开头是 `t`）曾被按空白
- * 硬切 → 值截断 + 引号残留（实测 inputs.topic 带 `"` 尾，positional 里散落被拆的字）。
- * 现在 token 内任意位置的引号都正确分组。
+ * shell 风格 token 化：引号在 token **任意位置**出现即进入引号模式。
  *
- * 边界语义（被 parseWorkflowArgs.test.ts 冻结）：
- *   - 未闭合引号：剩余部分并入当前 token（不报错）
- *   - 双引号内的单引号是字面量（不触发嵌套）
- *   - 反斜杠不转义（`a\"b` 中 `"` 仍开启引号模式，行为变化但测试用 toBeDefined 容错）
- *   - 连续空白合并、`""` 产生空 token
+ * 自 legacy 移植。`--input topic="带空格的值"` 里引号在 `=` 之后、token 开头是 `t`，
+ * 只认「开头引号」的写法会把值截断并留下引号残留 —— 这是实测过的。
  */
 function tokenizeArgs(s: string): string[] {
   const out: string[] = [];
@@ -115,11 +65,10 @@ function tokenizeArgs(s: string): string[] {
     while (i < s.length) {
       const c = s[i];
       if (c === '"' || c === "'") {
-        // 引号模式：收集到闭合引号，引号内空白保留
         const q = c;
         i++;
         while (i < s.length && s[i] !== q) acc += s[i++];
-        if (i < s.length) i++; // 跳过闭合引号
+        if (i < s.length) i++;
       } else if (/\s/.test(c)) {
         break;
       } else {
@@ -132,172 +81,225 @@ function tokenizeArgs(s: string): string[] {
   return out;
 }
 
+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('--')) {
+      i++; // 未知 flag：保守跳过其后一个 token（认为它带值）
+      continue;
+    }
+    if (name === null) name = t.replace(/\.ya?ml$/i, '');
+    else positional.push(t);
+  }
+  return { name, inputs, positional };
+}
+
 /**
- * 把字符串形态的 input 值按 InputDef.type 转成合适的 JS 类型 + 校验。
- * 校验失败抛 Error，pluginRunner 会把它转成 error event。
+ * 位置参数 → inputs 映射。
+ * **贪婪首参**（`inputs[0].greedy`）：名后全部位置参数空格 join 进首参，不逐位拆。
+ * 存在理由是真实事故：不贪婪时用户打一句自然语言会被空格拆碎，第二段撞上
+ * number 类型的输入报「必须是数字」。
  */
-function coerceInputs(
-  raw: Record<string, string>,
+function mapPositional(
+  rawInputs: Record<string, string>,
+  positional: string[],
   defs: InputDef[] | undefined,
-): Record<string, unknown> {
-  const out: Record<string, unknown> = {};
-  if (!defs) return { ...raw };
+  cwd = process.cwd(),
+): string[] {
+  const warnings: string[] = [];
+  if (!defs || positional.length === 0) return warnings;
 
-  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;
+  if (defs[0]?.greedy === true) {
+    const name = defs[0].name;
+    if (defs[0].type === 'resource' && !(name in rawInputs)) {
+      // A Desktop invocation commonly has a natural-language tail after the
+      // command and no textual path. Do not mistake that tail for a file.
+      const first = positional[0] ?? '';
+      const looksLikePath =
+        existsSync(resolve(cwd, first)) ||
+        first.startsWith('/') ||
+        first.startsWith('\\') ||
+        /^[A-Za-z]:[\\/]/.test(first) ||
+        first.startsWith('~/') ||
+        first.startsWith('~\\') ||
+        first.startsWith('./') ||
+        first.startsWith('.\\') ||
+        first.startsWith('../') ||
+        first.startsWith('..\\') ||
+        /\.[A-Za-z0-9]{1,16}$/.test(first);
+      if (!looksLikePath) {
+        if (positional.length) rawInputs.requestText = positional.join(' ');
+        return warnings;
       }
-      continue;
+      rawInputs[name] = first;
+      if (positional.length > 1)
+        rawInputs.requestText = positional.slice(1).join(' ');
+      return warnings;
+    }
+    if (defs[0]?.type === 'resource' && name in rawInputs) {
+      if (positional.length) rawInputs.requestText = positional.join(' ');
+      return warnings;
+    }
+    if (name in rawInputs) {
+      // 含空格的值没加引号会被 shell 拆开（只有第一段进 KV，其余散落成位置参数）。
+      // 静默丢弃曾把整段中文主题截成半句，连锁触发仲裁误判。这里拼回去并告警。
+      rawInputs[name] = [rawInputs[name], ...positional].join(' ');
+      warnings.push(
+        `${name}：--input 值未加引号被拆成 ${positional.length} 段，已自动拼回（下次请写 --input "${name}=完整值"）`,
+      );
+    } else {
+      rawInputs[name] = positional.join(' ');
     }
-    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}"`,
+    return warnings;
+  }
+
+  const max = Math.min(positional.length, defs.length);
+  for (let i = 0; i < max; i++) {
+    const def = defs[i];
+    if (def.name in rawInputs) {
+      if (rawInputs[def.name] !== positional[i]) {
+        warnings.push(
+          `--input 优先级高于位置参数：${def.name} 取 ${JSON.stringify(rawInputs[def.name])}，位置参数 ${JSON.stringify(positional[i])} 被忽略`,
         );
       }
-      out[def.name] = rawVal;
     } else {
-      out[def.name] = rawVal;
+      rawInputs[def.name] = positional[i];
     }
   }
-  // 未声明的 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 (positional.length > defs.length) {
+    const dropped = positional.slice(defs.length);
+    warnings.push(
+      `忽略了 ${dropped.length} 个多余位置参数：${dropped.map((d) => JSON.stringify(d)).join(' ')}`,
+    );
   }
-
-  if (systemIndex > 0) history.splice(systemIndex, 1);
-  history.unshift(fresh);
+  return warnings;
 }
 
-/** /workflow <name> [pos...] [--input k=v] —— 主入口，由 pluginRunner 调用。 */
+/** `/workflow <name> …` 主入口。 */
 export async function* runWorkflowFromCommand(
   rawArgs: string,
   opts: RunWorkflowFromCommandOptions,
-): AsyncGenerator<WorkflowEvent | LoopEvent, void, void> {
+): AsyncGenerator<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 查看可用列表。`,
+        '/workflow 用法：/workflow <name> [值 ...] [--input key=值 ...]\n输入 /workflows 查看可用工作流。',
     };
     return;
   }
 
   const cwd = opts.cwd ?? process.cwd();
   const tools = opts.tools ?? [];
-  await refreshWorkflowSystemPrompt(opts.history, cwd, tools);
+  const { workflows, failures } = await discoverWorkflows(cwd);
+  const script = workflows.find((w) => w.name === name);
 
-  // 位置参数映射，两种模式：
-  //   - 贪婪首参（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 greedyNotes: 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 提供时，位置参数仍按贪婪语义【拼回】首参末尾--
-      // 含空格的值未加引号时会被 shell 拆开（--input topic=A B C 只有 A 进 KV，
-      // B C 散落成位置参数），静默丢弃曾把整段中文调研主题截成半句、
-      // 连锁触发任务仲裁误判 new-task 清空全部产物。
-      rawInputs[greedyName] = [rawInputs[greedyName], ...positional].join(' ');
-      greedyNotes.push(
-        `${greedyName}：--input 值未加引号被拆成 ${positional.length} 段位置参数，已自动拼回（下次请写 --input "${greedyName}=完整值"）`,
-      );
-    } else {
-      // 贪婪吸收：整句进首参（空格 join 还原用户原话，不逐位拆映射）
-      rawInputs[greedyName] = positional.join(' ');
+  if (!script) {
+    const broken = failures.find((f) => f.name === name);
+    if (broken) {
+      // 「有但写错了」与「没有」必须区分开 —— 否则用户会去找一个并不存在的拼写问题。
+      yield {
+        type: 'error',
+        error: `工作流「${name}」存在但写错了：\n${broken.errors.map((e) => `  · ${e}`).join('\n')}`,
+      };
+      return;
     }
-  } 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 值被 shell 拆开后自动拼回
-  if (greedyNotes.length > 0) {
     yield {
-      type: 'warning',
-      message: `⚠ ${greedyNotes.join('；')}`,
+      type: 'error',
+      error: `未找到工作流「${name}」。输入 /workflows 查看可用列表。`,
     };
+    return;
   }
-  // warn：位置参数被 --input 覆盖
-  if (overriddenByKV.length > 0) {
-    yield {
-      type: 'warning',
-      message: `⚠ --input 优先级高于位置参数，以下位置参数被覆盖：${overriddenByKV.join('; ')}`,
-    };
+
+  await refreshStableSystemPrompt(opts.history, cwd, tools);
+
+  for (const w of mapPositional(
+    rawInputs,
+    positional,
+    script.meta.inputs,
+    cwd,
+  )) {
+    yield { type: 'warning', message: `⚠ ${w}` };
   }
 
-  let coerced: Record<string, unknown>;
+  const sessionId = opts.runtimeContext?.sessionId ?? 'default';
+  let inputs: Record<string, unknown>;
+  let inputResourceMap: Record<
+    string,
+    import('../../../src/plugin-sdk.js').InvocationResource[]
+  > = {};
+  let resourceFingerprint = '';
   try {
-    coerced = coerceInputs(rawInputs, def.inputs);
+    const bound = await bindResourceInputs({
+      workflowName: script.name,
+      sessionId,
+      cwd,
+      rawInputs,
+      defs: script.meta.inputs,
+      attachments: opts.inputResources,
+    });
+    for (const warning of bound.warnings)
+      yield {
+        type: 'plugin_progress',
+        pluginId: 'workflow-runner',
+        message: warning,
+      };
+    inputResourceMap = bound.resourceMap as typeof inputResourceMap;
+    resourceFingerprint = bound.resourceIdentity.join('|');
+    if (resourceFingerprint)
+      bound.inputs.__resource_fingerprint = resourceFingerprint;
+    inputs = coerceInputs(
+      bound.inputs as Record<string, string>,
+      script.meta.inputs,
+    );
   } catch (e) {
     yield { type: 'error', error: (e as Error).message };
     return;
   }
 
+  let preparedManaged:
+    | import('../../../src/managedExecution/types.js').PreparedManagedCommand
+    | undefined;
+  if (script.meta.managedRuntime) {
+    const controller = managedCommandController(script.meta.managedRuntime);
+    if (!controller) {
+      yield {
+        type: 'error',
+        error: `未知 managedRuntime：${script.meta.managedRuntime}`,
+      };
+      return;
+    }
+    preparedManaged = await controller(inputs, {
+      cwd,
+      runtimeContext: opts.runtimeContext,
+      context: opts.managedContext,
+    });
+    for (const event of preparedManaged.events) yield event;
+    if (preparedManaged.handled) return;
+    inputs = preparedManaged.inputs;
+    // A managed controller may normalize/replace public inputs, but it must not
+    // erase the resource component of task identity.
+    if (resourceFingerprint && !inputs.__resource_fingerprint)
+      inputs.__resource_fingerprint = resourceFingerprint;
+  }
+
   const ctx: RunContext = {
     provider: opts.provider,
     runtimeContext: opts.runtimeContext,
@@ -312,53 +314,50 @@ export async function* runWorkflowFromCommand(
     promptCache: opts.promptCache,
     executeTool: opts.executeTool,
     toolContext: opts.toolContext,
+    managedExecution: preparedManaged?.execution,
+    managedBridge: preparedManaged?.bridge,
+    inputResources: opts.inputResources,
+    inputResourceMap,
   };
 
-  // 透传 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' };
+  yield* runWorkflowScript(script, { ctx, inputs });
 }
 
-/** /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;
+/** `/workflows` —— 列出可用工作流，并如实报出写错的那些。 */
+export async function* runWorkflowsList(
+  cwd?: string,
+): AsyncGenerator<LoopEvent, void, void> {
+  const { workflows, failures } = await discoverWorkflows(cwd);
+  const lines: string[] = [];
+
+  if (workflows.length > 0) {
+    lines.push('可用工作流：');
+    for (const w of workflows) {
+      lines.push(
+        `  /workflow ${w.name}  —  ${w.meta.description.split('\n')[0].trim()}`,
+      );
+    }
   }
-  const lines = ['可用工作流：'];
-  for (const w of list) {
+
+  if (workflows.length === 0) {
     lines.push(
-      `  /workflow ${w.name}  —  ${w.description.split('\n')[0].trim()}`,
+      '当前没有可用工作流。在 workflows/<名字>/workflow.mjs 放一个脚本即可（`/skill workflow-creator` 会带你写）。',
     );
   }
+
+  // 写错的工作流必须报出来 —— 静默消失会让用户以为「我的工作流不见了」。
+  if (failures.length > 0) {
+    lines.push('');
+    lines.push(`⚠ 有 ${failures.length} 个工作流写错了，未能载入：`);
+    for (const f of failures) {
+      lines.push(`  · ${f.name}：${f.errors[0]}`);
+    }
+  }
+
   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 时用）',
-  );
+  lines.push('运行示例：');
+  lines.push('  /workflow <name> <值>          位置参数（按 inputs 声明顺序）');
+  lines.push('  /workflow <name> --input k=v   显式 KV');
   yield { type: 'text', delta: `${lines.join('\n')}\n` };
   yield { type: 'turn_done' };
 }

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

@@ -0,0 +1,40 @@
+export function coerceInputs(raw, defs) {
+    const out = {};
+    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 = typeof rawVal === 'number' || typeof rawVal === 'string'
+                ? Number(rawVal)
+                : Number.NaN;
+            if (!Number.isFinite(n) ||
+                (typeof rawVal === 'string' && !rawVal.trim())) {
+                throw new Error(`input ${def.name} 必须是数字，收到 "${rawVal}"`);
+            }
+            out[def.name] = n;
+        }
+        else if (def.type === 'enum') {
+            if (typeof rawVal !== 'string' || !def.values?.includes(rawVal)) {
+                throw new Error(`input ${def.name} 必须是 [${def.values?.join(', ')}] 之一，收到 "${rawVal}"`);
+            }
+            out[def.name] = rawVal;
+        }
+        else {
+            if (typeof rawVal !== 'string')
+                throw new Error(`input ${def.name} 必须是字符串`);
+            out[def.name] = rawVal;
+        }
+    }
+    for (const k of Object.keys(raw))
+        if (!(k in out))
+            out[k] = raw[k];
+    return out;
+}