minimal-agent 0.5.5 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimal-agent",
-  "version": "0.5.5",
+  "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/context/persistContext.js

@@ -53,15 +53,31 @@ export async function loadContext(file) {
         return null;
     }
 }
+/**
+ * 把 messages 数组过滤掉 _ephemeral=true 的 system 消息。
+ *
+ * v2.x 新增：UI 用 ephemeral system 消息把 slash 命令输出落进 scrollback
+ * （替代 process.stdout.write 旁路 Ink）。这种消息只供 UI 展示，不该污染
+ * 持久化历史；这里在 saveContext 之前做一次过滤。
+ *
+ * 导出供测试断言。
+ */
+export function filterEphemeralMessages(messages) {
+    return messages.filter((m) => !(m.role === 'system' && m._ephemeral === true));
+}
 /**
  * 保存当前 messages 为"上下文文件"，覆盖之前内容。
  * 写失败不抛——丢一次落盘比把进程崩掉划算。
+ *
+ * v2.x 新增：写盘前过滤掉 _ephemeral=true 的 system 消息（UI 临时提示，
+ * 不应进入持久化历史）。
  */
 export async function saveContext(messages, file) {
     const target = file ?? getContextPath();
     try {
         await mkdir(dirname(target), { recursive: true });
-        const data = { updatedAt: Date.now(), messages };
+        const persistable = filterEphemeralMessages(messages);
+        const data = { updatedAt: Date.now(), messages: persistable };
         await writeFile(target, JSON.stringify(data), 'utf8');
     }
     catch {

package/src/llm/client.js

@@ -44,10 +44,24 @@ export async function* chat(args) {
             parameters: t.parameters,
         },
     }));
-    // 2. 构造请求体
+    // 2. 过滤并清洁 messages 数组，剥离 timestamp, id, _ephemeral 等本地渲染元数据
+    const cleanedMessages = messages
+        .filter((m) => {
+        // 过滤掉 _ephemeral=true 的临时 UI 提示消息，防止其污染 LLM 核心上下文
+        if (m.role === 'system' && m._ephemeral === true) {
+            return false;
+        }
+        return true;
+    })
+        .map((m) => {
+        // 结构解构以去除本地专属渲染元数据
+        const { id, timestamp, ...rest } = m;
+        return rest;
+    });
+    // 3. 构造请求体
     const body = {
         model: provider.model,
-        messages,
+        messages: cleanedMessages,
         tools: openaiTools.length > 0 ? openaiTools : undefined,
         stream: true,
         // tool_choice: 'auto' 是默认值，可不写；某些 provider 必须显式