minimal-agent 0.12.0 → 0.14.0

package/src/plugin-sdk.ts

@@ -76,13 +76,17 @@ export { dlog } from './utils/debugLog.js';
 // <think> 思维链剥离：内核与 workflow-runner 共享（原住 agentCommon.ts，
 // Agent 子任务工具也需要 → 上移内核，插件经此 re-export）。
 export { stripThinkBlocks } from './utils/stripThink.js';
-// buildFullSystemPrompt is retained for compatibility. New long-running hosts should keep
-// buildBaseSystemPrompt stable and pass buildTransientContext separately for each turn.
+// 长驻宿主保持 buildBaseSystemPrompt 稳定，每回合单独传 transient bundle。
+// （`buildTransientContext` 曾也在这里 re-export，唯一消费者是已删除的 yaml 引擎；
+// 门面每多一个导出就多一条不能自由重构的边，没消费者就先不导出。）
 export {
   buildBaseSystemPrompt,
-  buildTransientContext,
   buildTransientPromptBundle,
 } from './prompts/system.js';
+export {
+  refreshStableSystemPrompt,
+  upsertStableSystemMessage,
+} from './prompts/stableSystemPrompt.js';
 export type { PromptEnvelope, PromptSurface } from './prompts/promptAssembly.js';
 export type { ContextBundle } from './context/contextBundle.js';
 export {
@@ -94,6 +98,10 @@ export type {
 } from './runtime/agentRuntimeContext.js';
 export { getResourceSearchPaths } from './utils/resourcePaths.js';
 export type { ResourceName } from './utils/resourcePaths.js';
+// 「这个路径在不在那个目录里」的唯一实现——已经被手写错过好几次（含
+// workflow-runner 自己的两份，Windows 跨盘符时会误判成"在目录内"）。插件凡是要
+// 做路径包含判定，一律经这里，不要再手写一遍。
+export { pathContains } from './utils/pathContains.js';
 
 // 确定性检查设施：verify 步（shell/file_exists/file_contains/test_count）经此跑校验。
 export { parseCheckString, runVerification } from './infra/verification.js';
@@ -110,10 +118,35 @@ export type { SessionState } from './session/sessionState.js';
 // 不要绕过 legacy 回退逻辑自己拼路径。
 export { resolveSessionFile } from './context/sessionPath.js';
 
+/**
+ * 按模型 id 解析出一个 Provider（工作流的 `agent(..., { model })` 用）。
+ *
+ * ⚠️ 门面只暴露这一个**语义明确的解析函数**，不暴露整个 ConfigService ——
+ * 后者带着读写配置、草稿、顾问设置一大堆能力，插件不该拿到，而门面每多一个
+ * 导出就多一条不能自由重构的边（`test/pluginSdkSurface.test.ts` 守这条）。
+ *
+ * 解析不到（id 不存在 / 该条目没填 apiKey）返回 null —— 调用方**必须**回落到
+ * 基座 provider 并如实告警，不能静默换模型。
+ */
+export async function resolveProviderForModel(
+  modelId: string,
+): Promise<import('./types.js').Provider | null> {
+  const { configService } = await import('./config/configService.js');
+  return configService.providerForModel(modelId);
+}
+
+/** Resolve a portable workflow capability role through this machine's config. */
+export async function resolveProviderForWorkflowRole(
+  role: string,
+): Promise<import('./types.js').Provider | null> {
+  const { configService } = await import('./config/configService.js');
+  return configService.providerForWorkflowRole(role);
+}
+
 // --- 类型 ---
 export type {
-  ImageDetail,
   ImageInputSpec,
+  InvocationResource,
   Message,
   Provider,
   LoopEvent,
@@ -123,12 +156,12 @@ export type {
   // 插件需要它来组装 executeTool 的第四参（宿主授权上下文按需切片转发）。
   // 不导出的话插件只能绕过门面直接 import 内核，那正是门面要避免的。
   ToolCallContext,
-  ToolResult,
+  // 工作流引擎要把每次 agent()/llm() 的用量记进账本，`budget()` 才有刻度。
+  TurnResourceUsage,
 } from './types.js';
 
 export type {
   PluginApi,
   PluginContext,
-  PluginEvent,
   PluginRuntimeContext,
 } from './plugins/pluginApi.js';

package/src/plugins/pluginApi.ts

@@ -50,6 +50,8 @@ export interface PluginContext {
   maxTurns?: number;
   /** 当前回合的瞬时外部上下文；插件不得把它持久化到 history。 */
   transientContext?: string;
+  /** 本轮宿主明确授权给命令插件的文件资源；绝对路径仅限本机运行时。 */
+  inputResources?: readonly import('../types.js').InvocationResource[];
   transientBundle?: ContextBundle;
   promptCache?: PromptCacheContext;
   /** Canonical host-issued trust context; plugins may narrow it but never elevate it. */
@@ -82,7 +84,7 @@ export interface PluginContext {
    * 而同一个工具在主循环里好好的。
    *
    * 插件**不应**无条件把它转给每一步：能力要由各步显式声明后按需转发
-   * （见 workflow-runner 的 `StepDef.uses`），否则一份无人值守的脚本就隐式拿到了
+   * （见 workflow-runner 的逐次 `uses` 选项），否则一份无人值守的脚本就隐式拿到了
    * 完整的机器控制权。
    */
   host?: Pick<
@@ -113,6 +115,14 @@ export interface PluginEvent {
   [key: string]: unknown;
 }
 
+export interface PluginSlashFallback {
+  /** Existing command owned by this plugin, without the leading slash. */
+  commandName: string;
+  /** Rewritten arguments for that command. */
+  args: string;
+  message?: string;
+}
+
 /**
  * 插件 plugin.ts 的 default export 形状。
  *
@@ -130,4 +140,9 @@ export interface PluginApi {
     args: string,
     ctx: PluginContext,
   ): AsyncGenerator<LoopEvent | PluginEvent, void, void>;
+  resolveSlashFallback?(
+    commandName: string,
+    args: string,
+    context: { cwd: string },
+  ): Promise<PluginSlashFallback | null> | PluginSlashFallback | null;
 }

package/src/plugins/pluginLoader.js

@@ -52,6 +52,10 @@ function isPluginApi(value) {
     const { runCommand } = value;
     if (runCommand !== undefined && typeof runCommand !== 'function')
         return false;
+    const { resolveSlashFallback } = value;
+    if (resolveSlashFallback !== undefined &&
+        typeof resolveSlashFallback !== 'function')
+        return false;
     return true;
 }
 /**

package/src/plugins/pluginLoader.ts

@@ -57,6 +57,12 @@ function isPluginApi(value: unknown): value is PluginApi {
   if (!value || typeof value !== 'object') return false;
   const { runCommand } = value as { runCommand?: unknown };
   if (runCommand !== undefined && typeof runCommand !== 'function') return false;
+  const { resolveSlashFallback } = value as { resolveSlashFallback?: unknown };
+  if (
+    resolveSlashFallback !== undefined &&
+    typeof resolveSlashFallback !== 'function'
+  )
+    return false;
   return true;
 }
 

package/src/plugins/pluginRunner.js

@@ -9,13 +9,14 @@
  *    2) / 输入 → discoverPlugins → resolveCommand
  *       a) 命中插件且其 plugin.ts 暴露 runCommand → 让 plugin.ts 接管
  *       b) 命中插件但只有声明式 commands/*.md → 把 prompt 拼好喂给 runQuery
- *       c) 未命中 → 静默透传 runQuery（/ 只是激活前缀，不是严格命令系统；
- *          未知的 /xxx 当普通用户输入处理，不报错）
+ *       c) 未命中 -> warning 提示未知命令后透传 runQuery（/ 只是激活前缀，
+ *          不是严格命令系统；未知的 /xxx 当普通用户输入处理，不报错）
  * ============================================================
  */
 import { runQuery } from '../loop.js';
-import { buildCommandInput, discoverPlugins, resolveCommand, } from './commandRouter.js';
+import { buildCommandInput, discoverPlugins, listAvailableCommands, resolveCommand, } from './commandRouter.js';
 import { loadPluginApi } from './pluginLoader.js';
+import { buildFallbackInput, parseExplicitPrefix, resolveSlashFallback, } from './slashFallback.js';
 export async function* runWithPlugins(userInput, options) {
     const { provider, history, signal } = options;
     const isSlashCommand = userInput.trimStart().startsWith('/');
@@ -25,6 +26,7 @@ export async function* runWithPlugins(userInput, options) {
             history,
             runtimeContext: options.runtimeContext,
             allowedTools: options.allowedTools,
+            availableTools: options.availableTools,
             signal,
             maxTurns: options.maxTurns,
             sessionState: options.sessionState,
@@ -36,7 +38,9 @@ export async function* runWithPlugins(userInput, options) {
             transientBundle: options.transientBundle,
             promptCache: options.promptCache,
             userAttachments: options.userAttachments,
+            inputResources: options.inputResources,
             userMessageId: options.userMessageId,
+            messageProvenance: options.messageProvenance,
             userBrowserReferences: options.userBrowserReferences,
             imageInputs: options.imageInputs,
             parseInlineImages: options.parseInlineImages,
@@ -53,18 +57,152 @@ export async function* runWithPlugins(userInput, options) {
         return;
     }
     // 确保插件已发现（resolveCommand 依赖 pluginCache）
-    await discoverPlugins();
-    const matched = resolveCommand(userInput);
+    const discoveredPlugins = await discoverPlugins();
+    let matched = resolveCommand(userInput);
+    const trimmedUnknown = userInput.trimStart();
+    const spaceUnknown = trimmedUnknown.indexOf(' ', 1);
+    const unknownCmd = (spaceUnknown >= 0
+        ? trimmedUnknown.slice(1, spaceUnknown)
+        : trimmedUnknown.slice(1)).trim();
+    const unknownArgs = spaceUnknown >= 0 ? trimmedUnknown.slice(spaceUnknown + 1).trim() : '';
+    // ── `/` 的解析规则（见 slashFallback.ts）────────────────────────────
+    //   显式前缀 → **只**在那一类里找，找不到就明确报错：
+    //     /tool <名字> …      只查工具
+    //     /skill <名字> …     只查 skill
+    //     /workflow <名字> …  只查工作流（它是插件命令，走下面的 resolveCommand）
+    //   省略前缀 → 工具 → skill → 插件 fallback；插件冲突必须报错。
+    //
+    // 为什么要有链式：用户心里的 `/` 是「唤起一个能力」，而能力有三种载体、
+    // 名字对用户是平级的。只认插件命令的话，`/pptx`、`/research` 这些**明明存在**
+    // 的能力全都会掉进「未知命令，按普通对话处理」—— 用户以为在跑工作流，
+    // 实际只烧了一轮 LLM。
+    let fallback = null;
+    const explicit = matched
+        ? null
+        : parseExplicitPrefix(unknownCmd, unknownArgs);
+    if (explicit) {
+        if (!explicit.name) {
+            yield {
+                type: 'error',
+                error: `/${unknownCmd} 用法：/${unknownCmd} <名字> [参数]。省略前缀直接写 /<名字> 也可以（会按 工具 → skill → 工作流 的顺序找）。`,
+            };
+            return;
+        }
+        fallback = await resolveSlashFallback(explicit.name, explicit.args, undefined, explicit.kind);
+        if (!fallback) {
+            // ⚠️ 显式前缀找不到就**明确报错**，不回落成普通对话 ——
+            // 用户点名要一个工具/skill，静默当聊天处理只会让他以为跑了但没效果。
+            const label = explicit.kind === 'tool' ? '工具' : 'skill';
+            yield {
+                type: 'error',
+                error: `没有名为「${explicit.name}」的${label}。` +
+                    `跑 \`node skills/workflow-creator/scripts/list-resources.mjs --${explicit.kind}s\` 看全部可用的${label}。`,
+            };
+            return;
+        }
+    }
+    else if (!matched && unknownCmd) {
+        fallback = await resolveSlashFallback(unknownCmd, unknownArgs);
+        if (!fallback) {
+            const claims = [];
+            for (const plugin of discoveredPlugins) {
+                const api = await loadPluginApi(plugin.root);
+                const claim = await api?.resolveSlashFallback?.(unknownCmd, unknownArgs, { cwd: options.runtimeContext?.cwd ?? process.cwd() });
+                if (claim)
+                    claims.push({ plugin, claim });
+            }
+            if (claims.length > 1) {
+                yield {
+                    type: 'error',
+                    error: `/${unknownCmd} 被多个插件同时认领：${claims.map((v) => v.plugin.name).join('、')}。请使用显式插件命令。`,
+                };
+                return;
+            }
+            if (claims.length === 1) {
+                const [{ claim, plugin }] = claims;
+                const rewritten = `/${claim.commandName}${claim.args ? ` ${claim.args}` : ''}`;
+                matched = resolveCommand(rewritten);
+                if (!matched) {
+                    yield {
+                        type: 'error',
+                        error: `插件「${plugin.name}」认领了 /${unknownCmd}，但改写目标 /${claim.commandName} 未注册。`,
+                    };
+                    return;
+                }
+                if (claim.message) {
+                    yield {
+                        type: 'plugin_progress',
+                        pluginId: plugin.name,
+                        message: claim.message,
+                    };
+                }
+            }
+        }
+    }
+    if (!matched && fallback) {
+        // 工具 / skill 层：拼一段明确的指令交给模型（工具入参是结构化 schema，
+        // 而命令行只有自由文本 —— 让模型做这层映射正是它擅长的）。
+        const label = fallback.kind === 'tool' ? '工具' : 'skill';
+        yield {
+            type: 'plugin_progress',
+            pluginId: 'slash-router',
+            message: `▸ /${unknownCmd} → ${label}「${fallback.name}」`,
+        };
+        yield* runQuery(buildFallbackInput(fallback), {
+            provider,
+            history,
+            runtimeContext: options.runtimeContext,
+            // 工具层收敛到那一个工具：用户点名要它，不该让模型另选
+            allowedTools: fallback.kind === 'tool' ? [fallback.name] : options.allowedTools,
+            availableTools: options.availableTools,
+            signal,
+            maxTurns: options.maxTurns,
+            sessionState: options.sessionState,
+            chat: options.chat,
+            executeTool: options.executeTool,
+            commitFormalDelivery: options.commitFormalDelivery,
+            toolGate: options.toolGate,
+            transientContext: options.transientContext,
+            transientBundle: options.transientBundle,
+            promptCache: options.promptCache,
+            userAttachments: options.userAttachments,
+            inputResources: options.inputResources,
+            userMessageId: options.userMessageId,
+            messageProvenance: options.messageProvenance,
+            userBrowserReferences: options.userBrowserReferences,
+            imageInputs: options.imageInputs,
+            parseInlineImages: options.parseInlineImages,
+            imageDetail: options.imageDetail,
+            imageMaxLongSidePixel: options.imageMaxLongSidePixel,
+            hasQueuedInput: options.hasQueuedInput,
+            onToolStart: options.onToolStart,
+            onToolEnd: options.onToolEnd,
+            browserRun: options.browserRun,
+            computerRun: options.computerRun,
+            computerIntervention: options.computerIntervention,
+            memoryContext: options.memoryContext,
+        });
+        return;
+    }
     if (!matched) {
-        // 未命中任何插件命令 → 静默透传 runQuery。
-        // / 只是激活前缀（类似 Claude Code 的 / 模式），不是严格命令系统。
-        // 用户可能输入 /init、/help、/任何东西 —— 不匹配就当普通对话处理，
-        // 让 LLM 自行理解意图。不报错、不提示、不打断用户体验。
+        // 四层都没命中 -> 提示后透传 runQuery。
+        // / 只是激活前缀（类似 Claude Code 的 / 模式），不是严格命令系统：
+        // 不匹配仍当普通对话处理，让 LLM 自行理解意图。但 -p 等无人值守场景里
+        // 拼错的 /reseach 会被静默当文本烧一轮 LLM（实战：用户以为在跑工作流，
+        // 实际什么都没发生）--先 warning 列出已注册命令，零成本纠正拼写。
+        if (unknownCmd) {
+            const available = listAvailableCommands().map((c) => c.command);
+            yield {
+                type: 'warning',
+                message: `未知命令 /${unknownCmd}（找遍了插件命令、工具、skill、工作流都没有；已注册插件命令：${available.length ? available.join('、') : '无'}），已按普通对话处理。`,
+            };
+        }
         yield* runQuery(userInput, {
             provider,
             history,
             runtimeContext: options.runtimeContext,
             allowedTools: options.allowedTools,
+            availableTools: options.availableTools,
             signal,
             maxTurns: options.maxTurns,
             sessionState: options.sessionState,
@@ -76,7 +214,9 @@ export async function* runWithPlugins(userInput, options) {
             transientBundle: options.transientBundle,
             promptCache: options.promptCache,
             userAttachments: options.userAttachments,
+            inputResources: options.inputResources,
             userMessageId: options.userMessageId,
+            messageProvenance: options.messageProvenance,
             userBrowserReferences: options.userBrowserReferences,
             imageInputs: options.imageInputs,
             parseInlineImages: options.parseInlineImages,
@@ -117,6 +257,7 @@ export async function* runWithPlugins(userInput, options) {
                 computerIntervention: options.computerIntervention,
                 toolGate: options.toolGate,
             },
+            inputResources: options.inputResources,
         });
         return;
     }
@@ -138,7 +279,9 @@ export async function* runWithPlugins(userInput, options) {
         transientBundle: options.transientBundle,
         promptCache: options.promptCache,
         userAttachments: options.userAttachments,
+        inputResources: options.inputResources,
         userMessageId: options.userMessageId,
+        messageProvenance: options.messageProvenance,
         userBrowserReferences: options.userBrowserReferences,
         imageInputs: options.imageInputs,
         parseInlineImages: options.parseInlineImages,

package/src/plugins/pluginRunner.ts

@@ -9,8 +9,8 @@
  *    2) / 输入 → discoverPlugins → resolveCommand
  *       a) 命中插件且其 plugin.ts 暴露 runCommand → 让 plugin.ts 接管
  *       b) 命中插件但只有声明式 commands/*.md → 把 prompt 拼好喂给 runQuery
- *       c) 未命中 → 静默透传 runQuery（/ 只是激活前缀，不是严格命令系统；
- *          未知的 /xxx 当普通用户输入处理，不报错）
+ *       c) 未命中 -> warning 提示未知命令后透传 runQuery（/ 只是激活前缀，
+ *          不是严格命令系统；未知的 /xxx 当普通用户输入处理，不报错）
  * ============================================================
  */
 
@@ -19,16 +19,34 @@ import type { LoopEvent, Message, Provider } from '../types.js';
 import {
   buildCommandInput,
   discoverPlugins,
+  listAvailableCommands,
   resolveCommand,
 } from './commandRouter.js';
 import type { PluginEvent } from './pluginApi.js';
 import { loadPluginApi } from './pluginLoader.js';
+import {
+  type SlashTarget,
+  buildFallbackInput,
+  parseExplicitPrefix,
+  resolveSlashFallback,
+} from './slashFallback.js';
 
 export interface PluginRunnerOptions {
   provider: Provider;
   history: Message[];
   runtimeContext?: RunQueryOptions['runtimeContext'];
   allowedTools?: RunQueryOptions['allowedTools'];
+  /**
+   * 本回合实际可调用的工具对象池（不只是名字）。缺省时 `loop.ts` 退回 `ALL_TOOLS`——
+   * 那是静态全局注册表，装不下按回合动态构造的工具（比如群协作工具，每次都要闭包捕获
+   * 当次投递的 owner/群 id/回复回调）。此前这里只转发 `allowedTools`（纯名字数组），
+   * 于是系统提示词会写"你有 GetGroupContext 工具"、允许名单里也有这个名字，但 API
+   * 实际下发给模型的 tools schema 里从来没有它——模型如实报告"没有这个能力"，
+   * 比静默瞎猜更诚实，但这条工具从一开始就没进模型能调用的范围（2026-08-21 真实
+   * LLM 群回合 E2E 首次跑通时抓到的问题，此前所有测试都 stub 掉了 runAgentTurn，
+   * 没有一条测试真的走到过这一层）。
+   */
+  availableTools?: RunQueryOptions['availableTools'];
   signal?: AbortSignal;
   maxTurns?: number;
   sessionState?: import('../session/sessionState.js').SessionState;
@@ -45,7 +63,9 @@ export interface PluginRunnerOptions {
   transientBundle?: RunQueryOptions['transientBundle'];
   promptCache?: RunQueryOptions['promptCache'];
   userAttachments?: RunQueryOptions['userAttachments'];
+  inputResources?: RunQueryOptions['inputResources'];
   userMessageId?: RunQueryOptions['userMessageId'];
+  messageProvenance?: RunQueryOptions['messageProvenance'];
   userBrowserReferences?: RunQueryOptions['userBrowserReferences'];
   imageInputs?: RunQueryOptions['imageInputs'];
   parseInlineImages?: RunQueryOptions['parseInlineImages'];
@@ -73,6 +93,7 @@ export async function* runWithPlugins(
       history,
       runtimeContext: options.runtimeContext,
       allowedTools: options.allowedTools,
+      availableTools: options.availableTools,
       signal,
       maxTurns: options.maxTurns,
       sessionState: options.sessionState,
@@ -84,7 +105,9 @@ export async function* runWithPlugins(
       transientBundle: options.transientBundle,
       promptCache: options.promptCache,
       userAttachments: options.userAttachments,
+      inputResources: options.inputResources,
       userMessageId: options.userMessageId,
+      messageProvenance: options.messageProvenance,
       userBrowserReferences: options.userBrowserReferences,
       imageInputs: options.imageInputs,
       parseInlineImages: options.parseInlineImages,
@@ -102,19 +125,169 @@ export async function* runWithPlugins(
   }
 
   // 确保插件已发现（resolveCommand 依赖 pluginCache）
-  await discoverPlugins();
-  const matched = resolveCommand(userInput);
+  const discoveredPlugins = await discoverPlugins();
+  let matched = resolveCommand(userInput);
+
+  const trimmedUnknown = userInput.trimStart();
+  const spaceUnknown = trimmedUnknown.indexOf(' ', 1);
+  const unknownCmd = (
+    spaceUnknown >= 0
+      ? trimmedUnknown.slice(1, spaceUnknown)
+      : trimmedUnknown.slice(1)
+  ).trim();
+  const unknownArgs =
+    spaceUnknown >= 0 ? trimmedUnknown.slice(spaceUnknown + 1).trim() : '';
+
+  // ── `/` 的解析规则（见 slashFallback.ts）────────────────────────────
+  //   显式前缀 → **只**在那一类里找，找不到就明确报错：
+  //     /tool <名字> …      只查工具
+  //     /skill <名字> …     只查 skill
+  //     /workflow <名字> …  只查工作流（它是插件命令，走下面的 resolveCommand）
+  //   省略前缀 → 工具 → skill → 插件 fallback；插件冲突必须报错。
+  //
+  // 为什么要有链式：用户心里的 `/` 是「唤起一个能力」，而能力有三种载体、
+  // 名字对用户是平级的。只认插件命令的话，`/pptx`、`/research` 这些**明明存在**
+  // 的能力全都会掉进「未知命令，按普通对话处理」—— 用户以为在跑工作流，
+  // 实际只烧了一轮 LLM。
+  let fallback: SlashTarget | null = null;
+  const explicit = matched
+    ? null
+    : parseExplicitPrefix(unknownCmd, unknownArgs);
+
+  if (explicit) {
+    if (!explicit.name) {
+      yield {
+        type: 'error',
+        error: `/${unknownCmd} 用法：/${unknownCmd} <名字> [参数]。省略前缀直接写 /<名字> 也可以（会按 工具 → skill → 工作流 的顺序找）。`,
+      };
+      return;
+    }
+    fallback = await resolveSlashFallback(
+      explicit.name,
+      explicit.args,
+      undefined,
+      explicit.kind,
+    );
+    if (!fallback) {
+      // ⚠️ 显式前缀找不到就**明确报错**，不回落成普通对话 ——
+      // 用户点名要一个工具/skill，静默当聊天处理只会让他以为跑了但没效果。
+      const label = explicit.kind === 'tool' ? '工具' : 'skill';
+      yield {
+        type: 'error',
+        error:
+          `没有名为「${explicit.name}」的${label}。` +
+          `跑 \`node skills/workflow-creator/scripts/list-resources.mjs --${explicit.kind}s\` 看全部可用的${label}。`,
+      };
+      return;
+    }
+  } else if (!matched && unknownCmd) {
+    fallback = await resolveSlashFallback(unknownCmd, unknownArgs);
+    if (!fallback) {
+      const claims = [];
+      for (const plugin of discoveredPlugins) {
+        const api = await loadPluginApi(plugin.root);
+        const claim = await api?.resolveSlashFallback?.(
+          unknownCmd,
+          unknownArgs,
+          { cwd: options.runtimeContext?.cwd ?? process.cwd() },
+        );
+        if (claim) claims.push({ plugin, claim });
+      }
+      if (claims.length > 1) {
+        yield {
+          type: 'error',
+          error: `/${unknownCmd} 被多个插件同时认领：${claims.map((v) => v.plugin.name).join('、')}。请使用显式插件命令。`,
+        };
+        return;
+      }
+      if (claims.length === 1) {
+        const [{ claim, plugin }] = claims;
+        const rewritten = `/${claim.commandName}${claim.args ? ` ${claim.args}` : ''}`;
+        matched = resolveCommand(rewritten);
+        if (!matched) {
+          yield {
+            type: 'error',
+            error: `插件「${plugin.name}」认领了 /${unknownCmd}，但改写目标 /${claim.commandName} 未注册。`,
+          };
+          return;
+        }
+        if (claim.message) {
+          yield {
+            type: 'plugin_progress',
+            pluginId: plugin.name,
+            message: claim.message,
+          };
+        }
+      }
+    }
+  }
+
+  if (!matched && fallback) {
+    // 工具 / skill 层：拼一段明确的指令交给模型（工具入参是结构化 schema，
+    // 而命令行只有自由文本 —— 让模型做这层映射正是它擅长的）。
+    const label = fallback.kind === 'tool' ? '工具' : 'skill';
+    yield {
+      type: 'plugin_progress',
+      pluginId: 'slash-router',
+      message: `▸ /${unknownCmd} → ${label}「${fallback.name}」`,
+    };
+    yield* runQuery(buildFallbackInput(fallback), {
+      provider,
+      history,
+      runtimeContext: options.runtimeContext,
+      // 工具层收敛到那一个工具：用户点名要它，不该让模型另选
+      allowedTools:
+        fallback.kind === 'tool' ? [fallback.name] : options.allowedTools,
+      availableTools: options.availableTools,
+      signal,
+      maxTurns: options.maxTurns,
+      sessionState: options.sessionState,
+      chat: options.chat,
+      executeTool: options.executeTool,
+      commitFormalDelivery: options.commitFormalDelivery,
+      toolGate: options.toolGate,
+      transientContext: options.transientContext,
+      transientBundle: options.transientBundle,
+      promptCache: options.promptCache,
+      userAttachments: options.userAttachments,
+      inputResources: options.inputResources,
+      userMessageId: options.userMessageId,
+      messageProvenance: options.messageProvenance,
+      userBrowserReferences: options.userBrowserReferences,
+      imageInputs: options.imageInputs,
+      parseInlineImages: options.parseInlineImages,
+      imageDetail: options.imageDetail,
+      imageMaxLongSidePixel: options.imageMaxLongSidePixel,
+      hasQueuedInput: options.hasQueuedInput,
+      onToolStart: options.onToolStart,
+      onToolEnd: options.onToolEnd,
+      browserRun: options.browserRun,
+      computerRun: options.computerRun,
+      computerIntervention: options.computerIntervention,
+      memoryContext: options.memoryContext,
+    });
+    return;
+  }
 
   if (!matched) {
-    // 未命中任何插件命令 → 静默透传 runQuery。
-    // / 只是激活前缀（类似 Claude Code 的 / 模式），不是严格命令系统。
-    // 用户可能输入 /init、/help、/任何东西 —— 不匹配就当普通对话处理，
-    // 让 LLM 自行理解意图。不报错、不提示、不打断用户体验。
+    // 四层都没命中 -> 提示后透传 runQuery。
+    // / 只是激活前缀（类似 Claude Code 的 / 模式），不是严格命令系统：
+    // 不匹配仍当普通对话处理，让 LLM 自行理解意图。但 -p 等无人值守场景里
+    // 拼错的 /reseach 会被静默当文本烧一轮 LLM（实战：用户以为在跑工作流，
+    // 实际什么都没发生）--先 warning 列出已注册命令，零成本纠正拼写。
+    if (unknownCmd) {
+      const available = listAvailableCommands().map((c) => c.command);
+      yield {
+        type: 'warning',
+        message: `未知命令 /${unknownCmd}（找遍了插件命令、工具、skill、工作流都没有；已注册插件命令：${available.length ? available.join('、') : '无'}），已按普通对话处理。`,
+      };
+    }
     yield* runQuery(userInput, {
       provider,
       history,
       runtimeContext: options.runtimeContext,
       allowedTools: options.allowedTools,
+      availableTools: options.availableTools,
       signal,
       maxTurns: options.maxTurns,
       sessionState: options.sessionState,
@@ -126,7 +299,9 @@ export async function* runWithPlugins(
       transientBundle: options.transientBundle,
       promptCache: options.promptCache,
       userAttachments: options.userAttachments,
+      inputResources: options.inputResources,
       userMessageId: options.userMessageId,
+      messageProvenance: options.messageProvenance,
       userBrowserReferences: options.userBrowserReferences,
       imageInputs: options.imageInputs,
       parseInlineImages: options.parseInlineImages,
@@ -168,6 +343,7 @@ export async function* runWithPlugins(
         computerIntervention: options.computerIntervention,
         toolGate: options.toolGate,
       },
+      inputResources: options.inputResources,
     });
     return;
   }
@@ -190,7 +366,9 @@ export async function* runWithPlugins(
     transientBundle: options.transientBundle,
     promptCache: options.promptCache,
     userAttachments: options.userAttachments,
+    inputResources: options.inputResources,
     userMessageId: options.userMessageId,
+    messageProvenance: options.messageProvenance,
     userBrowserReferences: options.userBrowserReferences,
     imageInputs: options.imageInputs,
     parseInlineImages: options.parseInlineImages,