minimal-agent 0.3.0 → 0.3.1

package/README.md

@@ -258,9 +258,13 @@ YAML DAG workflow 执行器，支持 7 种 step：
 
 ```bash
 /workflow youtube-shorts --input topic="猫咪赛博朋克城市探险"
+/workflow youtube-shorts "猫咪赛博朋克城市探险"   # 位置参数：按 inputs 声明顺序映射，.yaml 后缀可省
 /workflows                          # 列出所有 workflow
 ```
 
+> ⚠ **位置参数依赖 yaml 文件 `inputs:` 数组的声明顺序**。重排 inputs 顺序会破坏所有现有 CLI 位置参数调用（位置参数会映射到错误的 input）。
+> 多 input workflow 推荐使用 `--input key=value` 显式 KV 形式，更稳。
+
 ### 写自己的插件
 
 参考 `plugins/HOW-TO-WRITE-A-PLUGIN.md`。两种契约任选其一即可生效：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimal-agent",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "最小化 Agent 系统 —— 10 工具 + 插件系统 + workflow DSL + 自动压缩 + OpenAI 兼容 + Ink TUI；NodeNext + tsc 原地编译，dev 用 Bun .ts、install 用 Node .js（学习/教学用）",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Bill Wang <leiwang0359@gmail.com>",

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

@@ -1,6 +1,6 @@
 ---
-description: 运行 YAML 工作流（DAG 执行器），用 --input k=v 传参
-argument-hint: <name> [--input key=value ...]
+description: 运行 YAML 工作流（DAG 执行器）。位置参数按 inputs 声明顺序映射，或用 --input k=v 显式传参
+argument-hint: <name> [val ...] [--input key=value ...]
 ---
 
 # /workflow
@@ -10,6 +10,16 @@ argument-hint: <name> [--input key=value ...]
 
 用法示例：
 
-  /workflow hello-workflow --input name=alice --input lang=zh
+  /workflow hello-workflow alice                            位置参数：直接传 inputs 声明里第一个 input
+  /workflow hello-workflow alice zh                         多个位置参数：按 inputs 顺序填
+  /workflow hello-workflow.yaml alice                       .yaml 后缀可省（带也认）
+  /workflow hello-workflow --input name=alice --input lang=zh   显式 KV
+  /workflow hello-workflow alice --input lang=zh            混用：位置填 name，--input 填 lang
+
+规则：
+- 位置参数按 yaml 文件 `inputs:` 数组的**声明顺序**映射（不是字段名顺序）。多 input workflow 推荐 `--input key=value` 显式 KV，不易出错
+- `--input k=v` 显式 KV 优先级高于位置参数；位置参数对应的 input 已被 KV 占位时，位置参数被丢弃并 stderr 打 warning
+- 多余的位置参数（超过 inputs 声明数量）被丢弃并 stderr 打 warning，不影响 workflow 执行
+- 值含空格时用引号：`/workflow xxx "AI 教程 进阶"`
 
 输入 /workflows 查看可用工作流列表。

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

@@ -13,15 +13,17 @@
 import { findWorkflowByName, listWorkflows } from './loader.js';
 import { runWorkflow } from './runner.js';
 /**
- * 把 "/workflow <name> --input k=v --input k2=v2" 拆成 name + inputs。
+ * 把 "/workflow <name> [pos1 pos2 ...] [--input k=v ...]" 拆成 name + 显式 inputs + 位置参数。
  * 简单解析器（不依赖第三方）：
- *   - 第一个非 flag token = name
- *   - --input k=v 重复
- *   - 不识别其他 flag（P0 不报错，仅 console.warn）
+ *   - 第一个非 flag token = name；末尾 ".yaml" / ".yml" 自动剥（便于直接用文件名）
+ *   - 之后所有非 flag token 收进 positional[]，由调用方按 def.inputs 声明顺序映射
+ *   - --input k=v 显式 KV，优先级高于位置参数（同名 input 不会被位置参数覆盖）
+ *   - 不识别其他 flag（保守跳过其后一个 token）
  */
 export function parseWorkflowArgs(rawArgs) {
     const tokens = tokenizeArgs(rawArgs);
     const inputs = {};
+    const positional = [];
     let name = null;
     for (let i = 0; i < tokens.length; i++) {
         const t = tokens[i];
@@ -42,10 +44,13 @@ export function parseWorkflowArgs(rawArgs) {
             continue;
         }
         if (name === null) {
-            name = t;
+            name = t.replace(/\.ya?ml$/i, '');
+        }
+        else {
+            positional.push(t);
         }
     }
-    return { name, inputs };
+    return { name, inputs, positional };
 }
 /** 简单 token 化：双引号包裹的整体当一个 token；其它按空白切。 */
 function tokenizeArgs(s) {
@@ -119,13 +124,13 @@ function coerceInputs(raw, defs) {
     }
     return out;
 }
-/** /workflow <name> [--input k=v] —— 主入口，由 pluginRunner 调用。 */
+/** /workflow <name> [pos...] [--input k=v] —— 主入口，由 pluginRunner 调用。 */
 export async function* runWorkflowFromCommand(rawArgs, opts) {
-    const { name, inputs: rawInputs } = parseWorkflowArgs(rawArgs);
+    const { name, inputs: rawInputs, positional } = parseWorkflowArgs(rawArgs);
     if (!name) {
         yield {
             type: 'error',
-            error: '/workflow 用法: /workflow <name> [--input key=val ...]\n输入 /workflows 查看可用工作流。',
+            error: '/workflow 用法: /workflow <name> [val ...] [--input key=val ...]\n输入 /workflows 查看可用工作流。',
         };
         return;
     }
@@ -137,6 +142,40 @@ export async function* runWorkflowFromCommand(rawArgs, opts) {
         };
         return;
     }
+    // 位置参数严格按"第 i 个位置参数 ↔ def.inputs[i]"对应。
+    // --input k=v 显式优先：已显式的 input 不被位置参数覆盖（对应的位置参数被丢弃，会 warn）。
+    // 多余的位置参数（超过 def.inputs 数量）也被丢弃（会 warn）。
+    const overriddenByKV = [];
+    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：超量位置参数（用户写多了，提示一下）
+    if (def.inputs && positional.length > def.inputs.length) {
+        const dropped = positional.slice(def.inputs.length);
+        yield {
+            type: 'workflow_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: 'workflow_warning',
+            message: `⚠ --input 优先级高于位置参数，以下位置参数被覆盖：${overriddenByKV.join('; ')}`,
+        };
+    }
     let coerced;
     try {
         coerced = coerceInputs(rawInputs, def.inputs);
@@ -168,7 +207,10 @@ export async function* runWorkflowsList() {
         lines.push(`  /workflow ${w.name}  —  ${w.description.split('\n')[0].trim()}`);
     }
     lines.push('');
-    lines.push('运行示例: /workflow <name> --input key=val');
+    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/src/cli/print.js

@@ -102,7 +102,7 @@ export async function runPrintMode(provider, args, initialHistory, options) {
             history,
             signal: abortController.signal,
         })) {
-            // event 是 LoopEvent | PluginEvent；插件私有事件 handleEvent 走 default 静默忽略
+            // event 是 LoopEvent | PluginEvent；handleEvent 识别 LoopEvent + workflow_warning，其它走 default 静默忽略
             const result = handleEvent(event, output, options.verbose);
             if (result.exitCode !== undefined) {
                 await saveContext(history);
@@ -153,6 +153,11 @@ export function handleEvent(event, output, verbose) {
                 process.stderr.write(`📝 压缩完成: ${event.before} → ${event.after} tokens\n`);
             }
             return {};
+        case 'workflow_warning':
+            // workflow 引擎警告（如多余位置参数、--input 覆盖位置参数等）始终走 stderr，
+            // 不受 verbose 控制 —— 这是用户必须看到的信号，避免静默丢弃语义被忽略。
+            process.stderr.write(`${event.message}\n`);
+            return {};
         case 'turn_done':
             if (!verbose)
                 console.log(output.buffer);