minimal-agent 0.5.6 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimal-agent",
-  "version": "0.5.6",
+  "version": "0.6.0",
   "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/src/expressions.js

@@ -13,23 +13,34 @@
  *    or      := and ( '||' and )*
  *    and     := not ( '&&' not )*
  *    not     := '!' not | comparison
- *    comparison := primary ( ('==' | '!=' | '>=' | '<=' | '>' | '<') primary )?
- *    primary := number | string | array | call | path | '(' expr ')'
+ *    comparison := additive ( ('==' | '!=' | '>=' | '<=' | '>' | '<') additive )?
+ *    additive := primary ( '+' primary )*        // number 相加 / 否则 stringify 后拼接
+ *    primary := number | string | array | call | path | interp | '(' expr ')'
  *    array   := '[' expr (',' expr)* ']'
  *    call    := IDENT '(' expr (',' expr)* ')'   // 白名单
  *    path    := IDENT ('.' IDENT)*               // 变量 + 点路径
+ *    interp  := '${' EXPR '}'                     // 取 EXPR 的"值"（任意类型，不字符串化）
+ *    string  := "…" | '…'                         // 内嵌 ${EXPR} 走 template-literal 插值
  *
  *  白名单函数：fileExists / length / lower / upper
  *
- *  插值：${EXPR} —— 把 EXPR 求值后 toString 替换；对象/数组用 JSON.stringify。
- *  interpolateDeep 递归处理对象/数组/字符串。
+ *  ★ P2 根治：表达式上下文（when/condition/over/assert/vote.input）直接 evalExpr，
+ *    不再"先 interpolate 再 eval"（旧双求值的 footgun 源头）。四种写法都 OK：
+ *      裸 ${x} == 'y'   → ${x} 取值后比较（修掉旧 footgun：旧实现把 ${x} 替成裸字面量被当变量名）
+ *      "a/${x}/b"       → 字符串字面量内插值拼路径（向后兼容旧 fileExists("…${x}…") 写法）
+ *      "a/" + x + "/b"  → + 拼接（新增）
+ *      x == 'y'         → 裸变量名（向后兼容）
+ *    安全性也更好：变量的字符串内容不再被当作表达式二次执行（旧实现若插值结果落在引号外会被 eval）。
+ *
+ *  插值函数 interpolate(${EXPR}) 仍用于**模板上下文**（prompt / args / file_path）——
+ *  把 EXPR 求值后 toString 替换；对象/数组用 JSON.stringify。interpolateDeep 递归处理对象/数组/字符串。
  * ============================================================
  */
 import { existsSync } from 'node:fs';
 import { join, isAbsolute } from 'node:path';
 import { getWorkingDir } from '../../../src/plugin-sdk.js';
 const PUNCT2 = new Set(['==', '!=', '>=', '<=', '&&', '||']);
-const PUNCT1 = new Set(['(', ')', '[', ']', ',', '.', '!', '>', '<']);
+const PUNCT1 = new Set(['(', ')', '[', ']', ',', '.', '!', '>', '<', '+']);
 function tokenize(src) {
     const out = [];
     let i = 0;
@@ -39,6 +50,25 @@ function tokenize(src) {
             i++;
             continue;
         }
+        // 独立 ${...} 取值 token。注意：字符串字面量内部的 ${} 不会到这里——
+        // 会被下面的字符串分支整体读进 str token，由 parsePrimary 在 eval 时插值。
+        if (c === '$' && src[i + 1] === '{') {
+            let depth = 1;
+            let j = i + 2;
+            while (j < src.length && depth > 0) {
+                if (src[j] === '{')
+                    depth++;
+                else if (src[j] === '}')
+                    depth--;
+                if (depth > 0)
+                    j++;
+            }
+            if (depth !== 0)
+                throw new Error(`未闭合的 \${ 在表达式 "${src}"`);
+            out.push({ kind: 'interp', value: src.slice(i + 2, j) });
+            i = j + 1;
+            continue;
+        }
         // 字符串
         if (c === '"' || c === "'") {
             const quote = c;
@@ -161,11 +191,11 @@ function parseNot(c, vars) {
     return parseComparison(c, vars);
 }
 function parseComparison(c, vars) {
-    const left = parsePrimary(c, vars);
+    const left = parseAdditive(c, vars);
     const t = peek(c);
     if (t && t.kind === 'punct' && ['==', '!=', '>=', '<=', '>', '<'].includes(t.value)) {
         eat(c);
-        const right = parsePrimary(c, vars);
+        const right = parseAdditive(c, vars);
         switch (t.value) {
             case '==':
                 // eslint-disable-next-line eqeqeq
@@ -185,6 +215,23 @@ function parseComparison(c, vars) {
     }
     return left;
 }
+// 加法/拼接层：number + number → 相加；否则两边 stringify 后字符串拼接。
+// 表达式语言原本无拼接符，导致拼路径只能"先插值再 eval"（footgun 源头）；
+// 有了 + 之后可写 fileExists("videos/" + inputs.book + "/x") 这种纯表达式。
+function parseAdditive(c, vars) {
+    let left = parsePrimary(c, vars);
+    while (isPunct(c, '+')) {
+        eat(c);
+        const right = parsePrimary(c, vars);
+        left = addValues(left, right);
+    }
+    return left;
+}
+function addValues(l, r) {
+    if (typeof l === 'number' && typeof r === 'number')
+        return l + r;
+    return stringify(l) + stringify(r);
+}
 function parsePrimary(c, vars) {
     const t = peek(c);
     if (!t)
@@ -218,7 +265,15 @@ function parsePrimary(c, vars) {
     }
     if (t.kind === 'str') {
         eat(c);
-        return t.value;
+        // 字符串字面量支持内嵌 ${...} 插值（template-literal 语义）：
+        // fileExists("videos/${inputs.book}/x") 不必预插值也能工作。无 ${} 时原样返回。
+        return interpolate(t.value, vars);
+    }
+    if (t.kind === 'interp') {
+        eat(c);
+        // 独立 ${EXPR}：求值为 EXPR 的"值"（任意类型，不字符串化）。
+        // 修掉"裸 ${x} == 'y' 被当成变量名 x"的 footgun。
+        return evalExpr(t.value, vars);
     }
     if (t.kind === 'ident') {
         eat(c);

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

@@ -165,14 +165,14 @@ export async function* runWorkflowFromCommand(rawArgs, opts) {
     if (def.inputs && positional.length > def.inputs.length) {
         const dropped = positional.slice(def.inputs.length);
         yield {
-            type: 'workflow_warning',
+            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: 'workflow_warning',
+            type: 'warning',
             message: `⚠ --input 优先级高于位置参数，以下位置参数被覆盖：${overriddenByKV.join('; ')}`,
         };
     }

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

@@ -256,6 +256,11 @@ function validateSteps(steps, file, pathPrefix) {
             if (typeof s.type === 'string' && CONTROL_FLOW_TYPES.has(s.type)) {
                 throw new WorkflowLoadError(`${p}.output_schema 不能用在 type=${s.type} 控制流节点上`, file);
             }
+            // P3：output_schema 在 skill 节点上是静默 no-op（execSkillStep 无视它）。
+            // 与其悄悄丢弃，不如 loader 直接拒绝——仅 llm 节点支持 structured output。
+            if (s.skill !== undefined) {
+                throw new WorkflowLoadError(`${p}.output_schema 暂不支持 skill 节点（仅 llm 节点生效）`, file);
+            }
         }
         // context_files：[{ path, hint? }]；不能用在控制流节点上
         if (s.context_files !== undefined) {
@@ -277,6 +282,11 @@ function validateSteps(steps, file, pathPrefix) {
             if (typeof s.type === 'string' && CONTROL_FLOW_TYPES.has(s.type)) {
                 throw new WorkflowLoadError(`${p}.context_files 不能用在 type=${s.type} 控制流节点上`, file);
             }
+            // P3：context_files 同样是 skill 节点的静默 no-op（execSkillStep 无视它），
+            // 仅 llm 节点经 miniReAct 生效——loader 直接拒绝，避免悄悄丢弃。
+            if (s.skill !== undefined) {
+                throw new WorkflowLoadError(`${p}.context_files 暂不支持 skill 节点（仅 llm 节点生效）`, file);
+            }
         }
         // allowed_tools：string[]；不能用在控制流节点上
         if (s.allowed_tools !== undefined) {
@@ -287,6 +297,10 @@ function validateSteps(steps, file, pathPrefix) {
             if (typeof s.type === 'string' && CONTROL_FLOW_TYPES.has(s.type)) {
                 throw new WorkflowLoadError(`${p}.allowed_tools 不能用在 type=${s.type} 控制流节点上`, file);
             }
+            // P3：allowed_tools 与 context_files 配对，skill 节点上同样无效——一并拒绝。
+            if (s.skill !== undefined) {
+                throw new WorkflowLoadError(`${p}.allowed_tools 暂不支持 skill 节点（仅 llm 节点生效）`, file);
+            }
         }
     }
 }

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

@@ -28,6 +28,13 @@ import { execToolStep } from './stepExecutors/tool.js';
 import { VarStack } from './types.js';
 import { runVoter } from './voteHelpers.js';
 import { WorkflowState } from './workflowState.js';
+/**
+ * 插件 ID：把私有 workflow_* 事件镜像成框架通用 plugin_progress 时挂这个 id。
+ * LiveArea 状态行会渲染成 "[plugin:workflow-runner] i/total <message>"
+ * （src/ui/LiveArea.tsx:123），让 TUI 里跑 workflow 不再"无声"。
+ * （-p 非交互模式另由 src/cli/print.ts 把通用 warning 事件落 stderr。）
+ */
+const WF_PLUGIN_ID = 'workflow-runner';
 function stepKind(step) {
     if (step.type)
         return step.type;
@@ -65,9 +72,9 @@ async function* dispatchActionStep(step, vars, ctx) {
     if (step.type === 'assert')
         return execAssertStep(step, vars);
     if (step.tool)
-        return await execToolStep(step, vars, ctx);
+        return yield* execToolStep(step, vars, ctx);
     if (step.llm)
-        return await execLlmStep(step, vars, ctx);
+        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）`);
@@ -89,7 +96,7 @@ async function* runSteps(steps, vars, ctx, state) {
         if (step.when) {
             let pass = false;
             try {
-                pass = Boolean(evalExpr(interpolate(step.when, vars), vars));
+                pass = Boolean(evalExpr(step.when, vars));
             }
             catch (e) {
                 const errMsg = `when 表达式错误: ${e.message}`;
@@ -123,11 +130,21 @@ async function* runSteps(steps, vars, ctx, state) {
             index: i,
             total: steps.length,
         };
+        // P1 TUI 可见：把私有 workflow_step_start 镜像成框架通用 plugin_progress，
+        // LiveArea 状态行渲染成 "[plugin:workflow-runner] i/total step <id> (<kind>)"。
+        // （嵌套 block 的 i/total 相对当前 block，足够给"跑到哪一步"的实时反馈。）
+        yield {
+            type: 'plugin_progress',
+            pluginId: WF_PLUGIN_ID,
+            current: i + 1,
+            max: steps.length,
+            message: `step ${step.id} (${kind})`,
+        };
         // ---------- 控制流：branch ----------
         if (step.type === 'branch') {
             let cond = false;
             try {
-                cond = Boolean(evalExpr(interpolate(step.condition ?? 'false', vars), vars));
+                cond = Boolean(evalExpr(step.condition ?? 'false', vars));
             }
             catch (e) {
                 const errMsg = `branch 条件错误: ${e.message}`;
@@ -156,7 +173,7 @@ async function* runSteps(steps, vars, ctx, state) {
         if (step.type === 'loop') {
             let arr;
             try {
-                arr = evalExpr(interpolate(step.over ?? '[]', vars), vars);
+                arr = evalExpr(step.over ?? '[]', vars);
             }
             catch (e) {
                 const errMsg = `loop over 表达式错误: ${e.message}`;
@@ -208,6 +225,18 @@ async function* runSteps(steps, vars, ctx, state) {
                 ? interpolate(step.prompt, vars)
                 : 'pause（非交互模式直接跳过）';
             await state.appendProgress(`- ${step.id} pause: ${msg}`);
+            // P3：pause 在当前实现下**从不**真正等待人工（runner 是纯 AsyncGenerator，
+            // 没有把用户输入回灌进来的通道）。把"静默放行"变"响亮放行"——发通用 warning
+            // （-p 模式由 print.ts 落 stderr，权威通道）并镜像 plugin_progress（TUI 状态行可见），
+            // 避免审批闸门被悄悄跳过。真·HITL pause 属 P4，本轮不做。
+            const warnMsg = `⚠ pause "${step.id}" 在非交互模式被自动跳过，未真正等待人工确认——若这是审批闸门请勿依赖它。提示：${msg}`;
+            yield { type: 'warning', message: warnMsg };
+            yield {
+                type: 'plugin_progress',
+                pluginId: WF_PLUGIN_ID,
+                current: 0,
+                message: warnMsg,
+            };
             yield {
                 type: 'workflow_step_skipped',
                 id: step.id,
@@ -296,7 +325,7 @@ async function* runSteps(steps, vars, ctx, state) {
             const threshold = step.threshold ?? Math.ceil(voters_count / 2);
             let inputArr;
             try {
-                inputArr = evalExpr(interpolate(step.input ?? '[]', vars), vars);
+                inputArr = evalExpr(step.input ?? '[]', vars);
             }
             catch (e) {
                 const errMsg = `vote.input 求值失败: ${e.message}`;
@@ -408,10 +437,27 @@ export async function* runWorkflow(def, inputs, ctx) {
         name: def.name,
         totalSteps: def.steps.length,
     };
+    // P1 TUI 可见：开工时给 LiveArea 状态行一条 plugin_progress（0/total）。
+    yield {
+        type: 'plugin_progress',
+        pluginId: WF_PLUGIN_ID,
+        current: 0,
+        max: def.steps.length,
+        message: `▶ workflow ${def.name}`,
+    };
     try {
         const halted = yield* runSteps(def.steps, vars, ctx, state);
         if (halted)
             return;
+        // 完成态也给一条 plugin_progress（放在 workflow_done 之前，保证
+        // workflow_done 仍是事件流最后一条——e2e 测试依赖 events[last]===workflow_done）。
+        yield {
+            type: 'plugin_progress',
+            pluginId: WF_PLUGIN_ID,
+            current: def.steps.length,
+            max: def.steps.length,
+            message: `✓ workflow ${def.name} 完成`,
+        };
         yield { type: 'workflow_done', name: def.name, vars: vars.snapshot() };
     }
     finally {

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

@@ -12,8 +12,8 @@ export function execAssertStep(step, vars) {
     }
     let ok;
     try {
-        const expanded = interpolate(step.condition, vars);
-        ok = Boolean(evalExpr(expanded, vars));
+        // P2：表达式上下文直接 evalExpr（${} 由引擎原生处理），不再"先插值再 eval"。
+        ok = Boolean(evalExpr(step.condition, vars));
     }
     catch (e) {
         throw new Error(`assert 表达式求值失败: ${e.message}`);

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

@@ -5,7 +5,9 @@
  *  单轮 LLM 生成。关键设计：
  *    - tools: [] —— 不开任何工具（工具调用应该写成 tool: step）
  *    - 自带独立 system + user 两条消息，不污染主 history
- *    - 流式累积文本（reasoning 字段在这里忽略；只关心最终文本）
+ *    - AsyncGenerator：非 schema 模式把 text_delta 流式 yield 给 UI（答案是主角，
+ *      消除 TUI"无声"），最终仍 return StepResult；schema 模式静默累积 JSON 不回显。
+ *      reasoning 字段在这里忽略；只关心最终文本
  *
  *  capture：
  *    - `{ text: var_name }` 绑生成文本（无 output_schema 时）
@@ -18,7 +20,7 @@
  *    - system prompt 切换为严格 JSON 模式，禁止 markdown 代码块包裹
  * ============================================================
  */
-import { ALL_TOOLS, chat } from '../../../../src/plugin-sdk.js';
+import { ALL_TOOLS, chat, } from '../../../../src/plugin-sdk.js';
 import { interpolate } from '../expressions.js';
 import { runMiniReAct } from '../miniReAct.js';
 const LLM_STEP_SYSTEM_PLAIN = '你正在被一个 workflow 调用。只输出本步骤要求的内容本身，不要寒暄、不要列要求复述、不要工具调用语法。';
@@ -37,7 +39,7 @@ const LLM_STEP_SYSTEM_WITH_TOOLS = `你正在被一个 workflow 调用。你被
 4. 完成后**不要**再调用工具，直接输出最终回答
 
 如果 workflow 要求结构化输出，请在最终回答里严格遵循 JSON Schema（无 markdown 代码块包裹）。`;
-export async function execLlmStep(step, vars, ctx) {
+export async function* execLlmStep(step, vars, ctx) {
     if (typeof step.llm !== 'string')
         throw new Error(`step ${step.id}: 缺少 llm 字段`);
     const prompt = interpolate(step.llm, vars);
@@ -88,8 +90,13 @@ export async function execLlmStep(step, vars, ctx) {
         responseFormat,
         signal: ctx.signal,
     })) {
-        if (ev.type === 'text_delta')
+        if (ev.type === 'text_delta') {
             text += ev.delta;
+            // 非 schema 模式：把答案流式 yield 给 UI（答案是主角，消除"无声"）。
+            // schema 模式输出是原始 JSON，不当"答案文本"回显，避免屏幕闪 JSON。
+            if (!useSchema)
+                yield { type: 'text', delta: ev.delta };
+        }
         if (ev.type === 'done' && ev.stopReason === 'aborted') {
             throw new Error('用户中断');
         }

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

@@ -1,4 +1,6 @@
-// TODO ADR-05: output_schema 暂未在 skill 节点生效，仅 llm 节点支持；workflow 用 vote 时通过 runVoter 直接调 execLlmStep
+// NOTE: output_schema 不支持 skill 节点——loader 现已直接拒绝 skill+output_schema 组合
+// （见 loader.ts validateSteps，P3 修复：静默 no-op 改为加载期报错）。
+// 仅 llm 节点支持 provider-native structured output；vote 通过 runVoter 调 execLlmStep（llm 虚拟步骤）。
 /**
  * ============================================================
  *  plugins/workflow-runner/src/stepExecutors/skill.ts —— skill step 执行

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

@@ -5,17 +5,23 @@
  *  把 step.args 递归 ${var} 插值后 JSON.stringify，转发到 executeTool。
  *  失败（ok=false）抛 Error，让 runner 走 onError 处理。
  *
+ *  v2（P1 TUI 可见）：本执行器改为 AsyncGenerator，在调 executeTool 前后
+ *  yield 通用 tool_start / tool_end LoopEvent —— 这样 workflow 的 tool 步骤
+ *  在 TUI 里像普通 ReAct 工具调用一样显示（runningTools spinner + 人话描述），
+ *  不再"无声"。**不** yield tool_messages_committed：workflow 步骤不进主 history，
+ *  其 live 态由 useChat 的 submit finally(resetTurnState) 在事件流末尾统一清理；
+ *  tool_end 自身已把该 callId 从 runningTools 里摘除，无需额外 commit 语义。
+ *
  *  capture 字段（支持点路径）：
  *    - `{ content: var_name }`      绑 ToolResult.content（工具回执文本）
  *    - `{ result: var_name }`       同义，给"无结构化字段"工具用
  *    - `{ args.content: var_name }` 绑插值后传给工具的入参（如真正写入的内容）
  *    - `{ args.<任意字段>: var_name }` 绑入参的具名字段
- *    P1 可扩展按工具特定字段（如 Read 的 fileSize）。
  * ============================================================
  */
-import { executeTool, getToolByName } from '../../../../src/plugin-sdk.js';
+import { executeTool, getToolByName, } from '../../../../src/plugin-sdk.js';
 import { interpolateDeep } from '../expressions.js';
-export async function execToolStep(step, vars, ctx) {
+export async function* execToolStep(step, vars, ctx) {
     if (!step.tool)
         throw new Error(`step ${step.id}: 缺少 tool 字段`);
     const tool = getToolByName(step.tool);
@@ -23,7 +29,23 @@ export async function execToolStep(step, vars, ctx) {
         throw new Error(`step ${step.id}: 未知 tool "${step.tool}"`);
     const args = interpolateDeep(step.args ?? {}, vars);
     const argsJson = JSON.stringify(args);
+    const toolCallId = `wf_${step.id}`;
+    const argsPreview = argsJson.length > 80 ? `${argsJson.slice(0, 80)}…` : argsJson;
+    yield {
+        type: 'tool_start',
+        toolName: tool.name,
+        toolCallId,
+        argsPreview,
+        argsFriendly: friendlyToolDesc(tool.name, args),
+    };
     const result = await executeTool(tool.name, argsJson, ctx.signal);
+    yield {
+        type: 'tool_end',
+        toolName: tool.name,
+        toolCallId,
+        ok: result.ok,
+        content: result.ok ? result.content : result.error,
+    };
     if (!result.ok) {
         throw new Error(result.error);
     }
@@ -33,3 +55,16 @@ export async function execToolStep(step, vars, ctx) {
         preview: content.length > 200 ? `${content.slice(0, 200)}...` : content,
     };
 }
+/**
+ * 给 tool_start 生成人话描述（LiveArea spinner 行用）。
+ * 取常见入参键（file_path/command/query/...）拼成 "Write greetings/a/hello.txt"
+ * 这样的短句；都没命中就回退到工具名本身。
+ */
+function friendlyToolDesc(toolName, args) {
+    const key = ['file_path', 'command', 'query', 'pattern', 'path', 'url'].find((k) => typeof args[k] === 'string');
+    if (!key)
+        return toolName;
+    const val = String(args[key]);
+    const short = val.length > 60 ? `${val.slice(0, 60)}…` : val;
+    return `${toolName} ${short}`;
+}

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

@@ -41,7 +41,13 @@ export async function runVoter(rules, item, vars, ctx) {
         output_schema: VERDICT_SCHEMA,
     };
     try {
-        const result = await execLlmStep(virtualStep, vars, ctx);
+        // execLlmStep 现为 AsyncGenerator：手动 drain 取 return 值。voter 必须静默——
+        // N 个 voter 在 Promise.all 里并行，若把它们的 text 事件向上转发会在 UI 互相打架。
+        const gen = execLlmStep(virtualStep, vars, ctx);
+        let res = await gen.next();
+        while (!res.done)
+            res = await gen.next();
+        const result = res.value;
         const verdict = extractVerdict(result.raw);
         if (verdict)
             return verdict;

package/src/cli/print.js

@@ -23,6 +23,15 @@ import { runWithPlugins } from '../plugins/pluginRunner.js';
 const TOOL_OUTPUT_PREVIEW_MAX = 200;
 /** stdin 读取超时（ms），防止非 TTY + 无管道时永久挂起 */
 const STDIN_TIMEOUT_MS = 3000;
+/** 已告警过的未知事件类型（去重，避免高频插件私有事件刷屏 stderr）。 */
+const warnedUnknownEventTypes = new Set();
+function warnUnknownEventType(type) {
+    const t = typeof type === 'string' ? type : String(type);
+    if (warnedUnknownEventTypes.has(t))
+        return;
+    warnedUnknownEventTypes.add(t);
+    process.stderr.write(`[minimal-agent] 忽略未识别事件类型 "${t}"（插件私有事件；若是 yield 时拼错的 LoopEvent type，请检查插件）\n`);
+}
 function handleEPIPE(stream) {
     return (err) => {
         if (err.code === 'EPIPE')
@@ -102,7 +111,7 @@ export async function runPrintMode(provider, args, initialHistory, options) {
             history,
             signal: abortController.signal,
         })) {
-            // event 是 LoopEvent | PluginEvent；handleEvent 识别 LoopEvent + workflow_warning，其它走 default 静默忽略
+            // event 是 LoopEvent | PluginEvent；handleEvent 只认 LoopEvent，未识别的插件私有事件走 default 静默忽略
             const result = handleEvent(event, output, options.verbose);
             if (result.exitCode !== undefined) {
                 await saveContext(history);
@@ -153,8 +162,8 @@ export function handleEvent(event, output, verbose) {
                 process.stderr.write(`📝 压缩完成: ${event.before} → ${event.after} tokens\n`);
             }
             return {};
-        case 'workflow_warning':
-            // workflow 引擎警告（如多余位置参数、--input 覆盖位置参数等）始终走 stderr，
+        case 'warning':
+            // 通用非致命警告（如 workflow 多余参数、pause 被自动跳过等）始终走 stderr，
             // 不受 verbose 控制 —— 这是用户必须看到的信号，避免静默丢弃语义被忽略。
             process.stderr.write(`${event.message}\n`);
             return {};
@@ -165,7 +174,19 @@ export function handleEvent(event, output, verbose) {
         case 'error':
             console.error(`\n错误: ${event.error}`);
             return { exitCode: 1 };
+        // 已知但 -p 模式无需呈现的框架事件：显式忽略，好让 default 只剩"真正未知"的插件私有事件。
+        case 'user_message_committed':
+        case 'tool_messages_committed':
+        case 'interrupted':
+        case 'plugin_progress':
+        case 'reasoning':
+        case 'stage_change':
+            return {};
         default:
+            // 落到这里 = 插件私有事件（PluginEvent，type 任意字符串）。正常静默忽略；
+            // verbose 下打一行 stderr 帮插件作者发现 yield 了拼错的 type（如 tool_strat）。
+            if (verbose)
+                warnUnknownEventType(event.type);
             return {};
     }
 }

package/src/plugins/commandRouter.js

@@ -11,6 +11,15 @@ function stripQuotes(s) {
     }
     return trimmed;
 }
+/**
+ * 跨平台取路径最后一段。Windows 上 join() 产出反斜杠路径，单纯 split('/')
+ * 不切分会让整条绝对路径变成"目录名"。同时吃 \\ 与 /，与
+ * hookEngine.pluginNameFromRoot 的归一逻辑保持一致。
+ */
+export function baseName(p) {
+    const parts = p.replace(/[\\/]+$/, '').split(/[\\/]/);
+    return parts[parts.length - 1] || p;
+}
 function parseMarkdownFrontmatter(content) {
     const match = content.match(/^---\n([\s\S]*?)\n---/);
     if (!match)
@@ -28,7 +37,7 @@ function parseMarkdownFrontmatter(content) {
     return frontmatter;
 }
 async function loadPlugin(pluginDirPath) {
-    const dirName = pluginDirPath.split('/').pop() ?? pluginDirPath;
+    const dirName = baseName(pluginDirPath);
     const manifestPath = join(pluginDirPath, '.claude-plugin', 'plugin.json');
     let manifestName = dirName;
     let manifestVersion;
@@ -101,6 +110,9 @@ export async function discoverPlugins() {
     discoveryDone = true;
     // 双源扫描：cwd 优先 + packageRoot fallback；按数组顺序处理，已有 manifestName 跳过
     const searchPaths = getResourceSearchPaths('plugins', import.meta.url);
+    // 命令名 → 首个声明它的插件名。resolveCommand 按插入顺序返回第一个命中，
+    // 所以两个不同插件声明同名命令时，先注册者生效、后者被影 —— 不再静默，warn 一次。
+    const commandOwners = new Map();
     for (const root of searchPaths) {
         try {
             const entries = await readdir(root, { withFileTypes: true });
@@ -115,6 +127,16 @@ export async function discoverPlugins() {
                 if (pluginCache.has(plugin.name))
                     continue; // cwd 已注册的 manifestName，packageRoot 同名跳过
                 pluginCache.set(plugin.name, plugin);
+                for (const cmd of plugin.commands) {
+                    const owner = commandOwners.get(cmd.name);
+                    if (owner && owner !== plugin.name) {
+                        console.warn(`[minimal-agent] 命令名冲突：/${cmd.name} 同时由插件 "${owner}" 与 "${plugin.name}" 声明；` +
+                            `先注册的 "${owner}" 生效，"${plugin.name}" 的同名命令被忽略。`);
+                    }
+                    else if (!owner) {
+                        commandOwners.set(cmd.name, plugin.name);
+                    }
+                }
             }
         }
         catch {
@@ -147,9 +169,11 @@ export function buildCommandInput(resolved) {
     const { cmd, arguments: args } = resolved;
     let input = cmd.promptBody;
     input = input.replaceAll('${CLAUDE_PLUGIN_ROOT}', cmd.pluginRoot);
+    // 模板是否自己引用了参数占位符。引用了就别再补尾注，否则参数出现两遍。
+    const hadArgsPlaceholder = input.includes('$ARGUMENTS') || input.includes('${ARGUMENTS}');
     input = input.replaceAll('$ARGUMENTS', args);
     input = input.replaceAll('${ARGUMENTS}', args);
-    if (args.trim()) {
+    if (!hadArgsPlaceholder && args.trim()) {
         input += `\n\n用户参数: ${args.trim()}`;
     }
     return input;

package/src/ui/hooks/useChat.js

@@ -567,6 +567,11 @@ export function handleEvent(ev, setters) {
             setters.setError(e.error);
             setters.bump();
             break;
+        case 'warning':
+            // 通用非致命警告。TUI 不把它当红色 error 渲染；workflow 这类插件已另发
+            // plugin_progress 把同一文案镜像到状态行（LiveArea）。这里显式 no-op 让它
+            // 成为"已识别事件"，不触发 default 分支对未知事件的 dev 告警（见 default）。
+            break;
         case 'plugin_progress':
             setters.setPluginProgress({
                 pluginId: e.pluginId,
@@ -588,5 +593,10 @@ export function handleEvent(ev, setters) {
             // 工具集合的清空时机是各自 tool_end
             setters.setProgressStage(e.stage);
             break;
+        default:
+            // 落到这里 = 插件私有事件（PluginEvent，type 任意字符串），TUI 不识别即忽略。
+            // 这里**故意不**写 console.warn —— Ink 渲染期间写 stdout/stderr 会撕裂终端画面。
+            // 要排查插件 yield 了拼错的事件 type，请用 `minimal-agent -p --verbose`（print.ts 落 stderr）。
+            break;
     }
 }

package/workflows/schema.json

@@ -73,7 +73,7 @@
         "prompt": { "type": "string" },
         "output_schema": {
           "type": "object",
-          "description": "⚠ ADR-05 新增：LLM 输出 JSON Schema 强约束，走 provider-native structured output。仅 llm/skill 节点生效；详见 docs/05-advanced-workflow-integration.md。"
+          "description": "⚠ ADR-05 新增：LLM 输出 JSON Schema 强约束，走 provider-native structured output。仅 llm 节点生效（skill 节点 loader 拒绝）；详见 docs/workflow-design.md。"
         },
         "fork": {
           "type": "array",
@@ -105,7 +105,7 @@
               "hint": { "type": "string" }
             }
           },
-          "description": "⚠ ADR-05 新增：llm/skill 节点声明可用的上下文文件清单（path + hint），runner 拼进 prompt 并开放 Read 子循环，不 inline 内容。详见 docs/05-advanced-workflow-integration.md。"
+          "description": "⚠ ADR-05 新增：仅 llm 节点声明可用的上下文文件清单（path + hint），runner 拼进 prompt 并开放 Read 子循环，不 inline 内容（skill 节点 loader 拒绝）。详见 docs/workflow-design.md。"
         },
         "allowed_tools": {
           "type": "array",