minimal-agent 0.5.6 → 0.6.1

package/package.json

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

@@ -0,0 +1,33 @@
+/**
+ * ============================================================
+ *  src/cli/args.ts —— CLI 参数解析纯函数
+ * ------------------------------------------------------------
+ *  零依赖、零副作用的命令行参数提取工具，供 main.tsx 的 -p 分支使用。
+ *
+ *  为什么单独成文件（而非塞进 main.tsx）：
+ *    main.tsx 顶层有 `main().catch(...)` 自调用，一旦被 import 就会启动整个
+ *    应用。把纯函数抽出来，单测可零副作用地 import 断言。main.tsx re-export
+ *    同名符号，对外仍是「main.tsx 提供 extractFlagValue」的语义。
+ *
+ *  不引 commander：手撸即可，逻辑足够简单且教学清晰。
+ * ============================================================
+ */
+/**
+ * 从 args 里提取「带值标志」的值：找到 names 中任一标志，取其后**紧跟的下一个元素**当 value。
+ *
+ *   - 命中多次：取**第一次**出现的值
+ *   - 标志在末尾（后面没有元素）：返回 undefined（args[i+1] 天然是 undefined）
+ *   - 没命中任何 name：返回 undefined
+ *
+ * 例：extractFlagValue(['-p','--output-format','json','x'], ['--output-format']) === 'json'
+ *
+ * 用于 -p 模式提取 --output-format / --max-turns 的值。
+ */
+export function extractFlagValue(args, names) {
+    for (let i = 0; i < args.length; i++) {
+        if (names.includes(args[i])) {
+            return args[i + 1]; // 末尾标志时 args[i+1] 为 undefined，符合语义
+        }
+    }
+    return undefined;
+}

package/src/cli/print.js

@@ -2,8 +2,12 @@
  * ============================================================
  *  src/cli/print.ts —— CLI 非交互模式（-p / --print）
  * ------------------------------------------------------------
- *  不启动 Ink TUI，直接执行单次问答，流式输出到 stdout。
- *  适合脚本集成、CI/CD、快速单次查询。
+ *  不启动 Ink TUI，直接执行单次问答，最后落盘 history。
+ *  适合脚本集成、CI/CD、宿主程序（hermes/openclaw）spawn 调用。
+ *
+ *  两种输出格式（--output-format，默认 text）：
+ *    text —— 把最终回答原样打到 stdout（向后兼容，逐字节不变）
+ *    json —— stdout 只输出**一行** JSON 结局契约，其它诊断全走 stderr
  *
  *  v2 改进（对齐 kakadeai CLI 工程实践）：
  *    1. SIGINT 先保存 context 再退出（防丢失）
@@ -15,14 +19,24 @@
  *    minimal-agent -p "提示"
  *    echo "提示" | minimal-agent -p
  *    minimal-agent -p --verbose "提示"
+ *    minimal-agent -p --output-format json "提示"        # 结构化结局
  * ============================================================
  */
-import { saveContext } from '../context/persistContext.js';
+import { getContextPath, saveContext } from '../context/persistContext.js';
 import { runWithPlugins } from '../plugins/pluginRunner.js';
 /** stderr 显示工具结果时的截断阈值；超过即末尾加 "..." */
 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')
@@ -47,7 +61,13 @@ export function extractPromptArgs(args) {
         '--version',
     ]);
     // 带值标志：本身 + 后面紧跟的值都要跳过
-    const FLAG_WITH_VALUE = new Set(['-d', '--cwd']);
+    // （--output-format / --max-turns 必须在此，否则它们的值会被当成 prompt 文本污染）
+    const FLAG_WITH_VALUE = new Set([
+        '-d',
+        '--cwd',
+        '--output-format',
+        '--max-turns',
+    ]);
     const result = [];
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
@@ -62,12 +82,62 @@ export function extractPromptArgs(args) {
     return result;
 }
 /**
- * CLI 非交互模式：读取 prompt，执行 runQuery，流式输出到 stdout，最后落盘 history。
+ * 输出 `-p --output-format json` 的结局契约（**一行** JSON 到 stdout）。
+ *
+ * ⚠️ 诚实声明：`ok=true` 只代表「Agent 正常跑完（stop_reason==='end_turn'）——
+ * 未报错、未被中断、未撞最大轮数」，**不代表任务目标真的达成**。工具失败会被
+ * 吞回 LLM 让它自行重试，LLM 完全可能在没产出有效结果的情况下正常收尾、给出
+ * end_turn。调用方（宿主程序）若要判断「任务是否真做成」，必须额外校验 `result`
+ * 文本内容 / 产物文件，不能只看 ok。
+ *
+ * 字段语义：
+ *   ok          = (stop_reason === 'end_turn')
+ *   result      = 累积的 assistant 文本
+ *   is_error    = !ok
+ *   stop_reason = end_turn | max_turns | error | interrupted | config_error
+ *   num_turns   = assistant_message 事件计数
+ *   error       = 失败文案（成功时 null）
+ *   session_file（可选）= 当前对话落盘路径；拿得到才填，拿不到省略该键
+ *
+ * 导出供单测断言。
+ */
+export function emitJsonResult(result, sessionFile) {
+    const stopReason = result.stopReason ?? 'error';
+    const ok = stopReason === 'end_turn';
+    console.log(JSON.stringify({
+        ok,
+        result: result.buffer,
+        is_error: !ok,
+        stop_reason: stopReason,
+        num_turns: result.numTurns,
+        error: result.error,
+        ...(sessionFile ? { session_file: sessionFile } : {}),
+    }));
+}
+/**
+ * 尝试拿当前会话落盘路径（给 json 契约的 session_file 字段）。
+ * 取不到（异常等）返回 undefined，emitJsonResult 据此省略该键（契约允许）。
+ */
+function trySessionFile() {
+    try {
+        return getContextPath();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * CLI 非交互模式：读取 prompt，执行 runQuery，最后落盘 history。
+ *
+ *  - text 模式：流式 / 收尾把答案打到 stdout（逐字节兼容旧行为）
+ *  - json 模式：stdout 只在退出时输出一行 JSON 结局契约（emitJsonResult）
  */
 export async function runPrintMode(provider, args, initialHistory, options) {
     // EPIPE 保护：管道断开时不崩溃（如 `bun -p "..." | head -1`）
     process.stdout.on('error', handleEPIPE(process.stdout));
     process.stderr.on('error', handleEPIPE(process.stderr));
+    const outputFormat = options.outputFormat ?? 'text';
+    const isJson = outputFormat === 'json';
     const promptArgs = extractPromptArgs(args);
     let prompt;
     if (promptArgs.length > 0) {
@@ -86,53 +156,97 @@ export async function runPrintMode(provider, args, initialHistory, options) {
     }
     const abortController = new AbortController();
     let interrupted = false;
+    const history = initialHistory;
+    // text 模式只关心 buffer；json 模式还要 numTurns / stopReason / error。
+    // 用同一个对象承载，handleEvent 按 outputFormat 决定写哪些字段。
+    const result = {
+        buffer: '',
+        numTurns: 0,
+        stopReason: undefined,
+        error: null,
+    };
     process.on('SIGINT', () => {
         if (interrupted)
             process.exit(130);
         interrupted = true;
         abortController.abort();
         console.error('\n已中断');
-        void saveContext(initialHistory).finally(() => process.exit(130));
+        // json 模式：SIGINT 也要给出结构化结局（stop_reason='interrupted'）
+        if (isJson) {
+            result.stopReason = 'interrupted';
+            void saveContext(history).finally(() => {
+                emitJsonResult(result, trySessionFile());
+                process.exit(130);
+            });
+        }
+        else {
+            void saveContext(history).finally(() => process.exit(130));
+        }
     });
-    const history = initialHistory;
-    const output = { buffer: '' };
     try {
         for await (const event of runWithPlugins(prompt, {
             provider,
             history,
             signal: abortController.signal,
+            maxTurns: options.maxTurns,
         })) {
-            // event 是 LoopEvent | PluginEvent；handleEvent 识别 LoopEvent + workflow_warning，其它走 default 静默忽略
-            const result = handleEvent(event, output, options.verbose);
-            if (result.exitCode !== undefined) {
+            // event 是 LoopEvent | PluginEvent；handleEvent 只认 LoopEvent，未识别的插件私有事件走 default 静默忽略
+            const handled = handleEvent(event, result, options.verbose, outputFormat);
+            if (handled.exitCode !== undefined) {
                 await saveContext(history);
-                process.exit(result.exitCode);
+                if (isJson)
+                    emitJsonResult(result, trySessionFile());
+                process.exit(handled.exitCode);
             }
         }
     }
     catch (e) {
         if (e.name === 'AbortError') {
             await saveContext(history);
+            if (isJson) {
+                result.stopReason = 'interrupted';
+                emitJsonResult(result, trySessionFile());
+            }
             process.exit(130);
         }
         console.error(`\n未捕获异常: ${e.message}`);
         await saveContext(history);
+        if (isJson) {
+            // 未分类异常按 error 收尾（stopReason 仍为空 → emitJsonResult 兜底 'error'）
+            result.error = result.error ?? e.message;
+            emitJsonResult(result, trySessionFile());
+        }
         process.exit(1);
     }
     await saveContext(history);
+    // json 模式：for-await 正常跑完（没有触发任何 exitCode 退出点）也要 emit 一行结局。
+    if (isJson)
+        emitJsonResult(result, trySessionFile());
 }
 /**
  * 处理 runQuery yield 出来的 LoopEvent。
  * 纯事件分发函数，返回 { exitCode? } 由调用方决定是否退出。
+ *
+ * @param result      累积态（buffer 始终累积；json 模式还会写 numTurns/stopReason/error）
+ * @param verbose     是否把工具/压缩诊断打到 stderr
+ * @param outputFormat 'text'（默认）逐字节兼容旧行为；'json' 时 stdout 静默（只在退出时由 emitJsonResult 输出）
+ *
+ * ⚠️ 向后兼容：旧调用方 `handleEvent(ev, output, verbose)` 三参不传 outputFormat，
+ *    默认 'text'，行为与改前逐字节一致。
  */
-export function handleEvent(event, output, verbose) {
+export function handleEvent(event, result, verbose, outputFormat = 'text') {
+    const isJson = outputFormat === 'json';
     switch (event.type) {
         case 'text':
-            if (verbose)
+            // text 模式：verbose 才流式写 stdout（与旧行为逐字节一致）。
+            // json 模式：绝不往 stdout 写任何东西（stdout 只允许最后那一行 JSON），仅累积 buffer。
+            if (verbose && !isJson)
                 process.stdout.write(event.delta);
-            output.buffer += event.delta;
+            result.buffer += event.delta;
             return {};
         case 'assistant_message':
+            // 一轮 assistant 消息完整组装 → 回合计数 +1（json 契约的 num_turns）
+            result.numTurns++;
             return {};
         case 'tool_start':
             if (verbose) {
@@ -153,19 +267,54 @@ 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 {};
         case 'turn_done':
-            if (!verbose)
-                console.log(output.buffer);
+            // text 模式：非 verbose 时这里一次性把累积答案打到 stdout（旧行为，逐字节不变）。
+            // json 模式：只记 stopReason='end_turn'，stdout 保持静默。
+            result.stopReason = 'end_turn';
+            if (!isJson && !verbose)
+                console.log(result.buffer);
             return {};
         case 'error':
+            // compact_failed 是「非致命」信号：loop 压缩失败后会继续硬上（不 return），
+            // 这里**不退出**，只 stderr 警告 —— 对齐 loop 语义。
+            // （这同时修了一个旧瑕疵：之前 -p 收到该 error 会被误当致命退出。）
+            if (event.code === 'compact_failed') {
+                process.stderr.write(`${event.error}\n`);
+                return {};
+            }
+            // 其余 error 都是终结性的。
+            if (isJson) {
+                result.stopReason = event.code === 'max_turns' ? 'max_turns' : 'error';
+                result.error = event.error;
+                // json 模式不在这里打 stdout/stderr；由外层 emitJsonResult 统一输出
+                return { exitCode: 1 };
+            }
+            // text 模式：保持旧行为（红字 stderr + exitCode 1）
             console.error(`\n错误: ${event.error}`);
             return { exitCode: 1 };
+        case 'interrupted':
+            // 用户中断：json 模式记 stop_reason；外层退出点（catch / for-await 收尾 / SIGINT）emit。
+            // text 模式无需特殊处理（与旧行为一致：静默忽略，靠 SIGINT handler 退出）。
+            if (isJson)
+                result.stopReason = 'interrupted';
+            return {};
+        // 已知但 -p 模式无需呈现的框架事件：显式忽略，好让 default 只剩"真正未知"的插件私有事件。
+        case 'user_message_committed':
+        case 'tool_messages_committed':
+        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/loop.js

@@ -70,7 +70,8 @@ export async function* runQuery(userInput, options) {
                 timestamp: Date.now(),
                 id: crypto.randomUUID(),
             });
-            yield { type: 'error', error: '已被用户中断' };
+            // code='aborted'：让 `-p --output-format json` 把终结原因映射成 stop_reason='interrupted'
+            yield { type: 'error', error: '已被用户中断', code: 'aborted' };
             return;
         }
         // 2. 自动压缩
@@ -88,10 +89,13 @@ export async function* runQuery(userInput, options) {
             }
         }
         catch (e) {
-            // 压缩失败不要让整个对话挂掉
+            // 压缩失败不要让整个对话挂掉。
+            // code='compact_failed'：标记为「非致命」——注意此处 yield error 后**不 return**，
+            // loop 继续往下跑（不压缩硬上）。`-p --output-format json` 据此只 stderr 警告、不退出。
             yield {
                 type: 'error',
                 error: `自动压缩失败（继续不压缩）：${e.message}`,
+                code: 'compact_failed',
             };
         }
         // 3. 调 LLM 并组装 assistant 消息
@@ -179,7 +183,12 @@ export async function* runQuery(userInput, options) {
                 }
                 // reactive 也失败 → 退回正常错误路径
             }
-            yield { type: 'error', error: `LLM 调用失败：${e.message}` };
+            // code='llm_error'：终结性错误，stop_reason='error'
+            yield {
+                type: 'error',
+                error: `LLM 调用失败：${e.message}`,
+                code: 'llm_error',
+            };
             return;
         }
         const assistantMsg = {
@@ -312,9 +321,11 @@ export async function* runQuery(userInput, options) {
         }
         // 6. 继续 while 让模型看到 tool_result 后继续推理
     }
+    // code='max_turns'：撞最大轮数上限而终结，stop_reason='max_turns'
     yield {
         type: 'error',
         error: `达到最大轮数 ${maxTurns}，提前结束（防止失控）。如果合理可以提高 maxTurns。`,
+        code: 'max_turns',
     };
 }
 // ---------------- 辅助函数 ----------------

package/src/main.js

@@ -15,6 +15,10 @@ import { buildFullSystemPrompt } from './prompts/system.js';
 import { ALL_TOOLS } from './tools/index.js';
 import { Root } from './ui/Root.js';
 import { runPrintMode } from './cli/print.js';
+import { extractFlagValue } from './cli/args.js';
+// re-export：对外保持「main.tsx 提供 extractFlagValue」的语义；实现住在 cli/args.ts，
+// 这样单测可零副作用 import（main.tsx 顶层 main() 自调用会启动整个 app，不可被测试 import）。
+export { extractFlagValue };
 async function main() {
     // ★ -d/--cwd：在锁定工作目录之前先建目录 + chdir，让后续逻辑全在 -d 下运行
     //   不存在则自动 mkdir -p；后续 initWorkingDir() 自然拿到新 cwd
@@ -46,10 +50,30 @@ async function main() {
     }
     const isPrintMode = args.includes('-p') || args.includes('--print');
     if (isPrintMode) {
+        // 先把输出格式解析出来——provider 缺失分支也要按 json 契约给信号。
+        // 只接受 'text' | 'json'，其它值（含拼错）一律回落 'text'（向后兼容）。
+        const rawFormat = extractFlagValue(args, ['--output-format']);
+        const outputFormat = rawFormat === 'json' ? 'json' : 'text';
+        // --max-turns：parseInt，非法（NaN）→ undefined（走 loop 默认 50）
+        const rawMaxTurns = extractFlagValue(args, ['--max-turns']);
+        const parsedMaxTurns = rawMaxTurns !== undefined ? Number.parseInt(rawMaxTurns, 10) : Number.NaN;
+        const maxTurns = Number.isNaN(parsedMaxTurns) ? undefined : parsedMaxTurns;
         // CLI 非交互模式：先 env，再 ~/.minimal-agent/config.json fallback；都没就退出
         // （宿主 spawn 子进程时通常没 export env，靠 TUI 向导写出的 config.json 持久化）
         const provider = await loadProviderLayered();
         if (!provider) {
+            // json 模式：先给宿主一行结构化信号（stop_reason='config_error'），再退出。
+            // 人类可读的中文提示仍走 stderr（json 契约只占 stdout 那一行）。
+            if (outputFormat === 'json') {
+                console.log(JSON.stringify({
+                    ok: false,
+                    result: '',
+                    is_error: true,
+                    stop_reason: 'config_error',
+                    num_turns: 0,
+                    error: 'provider config not found',
+                }));
+            }
             process.stderr.write(`\n未找到 provider 配置。\n\n` +
                 `请二选一：\n` +
                 `  1. 设置环境变量 MINIMAL_AGENT_BASE_URL / MINIMAL_AGENT_API_KEY / MINIMAL_AGENT_MODEL\n` +
@@ -58,7 +82,7 @@ async function main() {
         }
         const initialHistory = await buildInitialHistory();
         const verbose = args.includes('--verbose') || args.includes('-v');
-        await runPrintMode(provider, args, initialHistory, { verbose });
+        await runPrintMode(provider, args, initialHistory, { verbose, outputFormat, maxTurns });
         return;
     }
     // TUI 交互模式：env 不全则 fallback 到 ~/.minimal-agent/config.json；
@@ -96,6 +120,9 @@ minimal-agent - 轻量级 AI 编程助手
   -v, --verbose      显示详细输出（工具调用、压缩信息）
   -d, --cwd <dir>    指定工作目录（不存在自动创建）；启动时 chdir 到这里，
                      上下文文件、工具相对路径、.env 加载都以此为基准
+  --output-format <fmt>  text（默认）= 纯文本答案；json = stdout 输出一行结构化
+                         结局契约（ok / result / stop_reason / num_turns / error）
+  --max-turns <n>    最大工具循环轮数（防失控；缺省 50）
   -h, --help         显示帮助信息
 
 会话记忆:
@@ -108,6 +135,7 @@ minimal-agent - 轻量级 AI 编程助手
   echo "解释代码" | minimal-agent -p
   minimal-agent -p --verbose "运行测试并报告结果"
   minimal-agent -p "处理资料" -d /tmp/job-123        # 工作目录隔离
+  minimal-agent -p --output-format json "做点事"     # 宿主程序 spawn：一行 JSON 结局
   `);
 }
 main().catch((e) => {

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",