minimal-agent 0.10.0 → 0.12.0

package/src/plugin-sdk.ts

@@ -0,0 +1,134 @@
+/**
+ * ============================================================
+ *  src/plugin-sdk.ts —— 插件作者的稳定 import 门面
+ * ------------------------------------------------------------
+ *  Drop-in 插件契约的"窄门"：插件根目录下的 plugin.ts 只允许从
+ *  '../../src/plugin-sdk.js' 取运行时（NodeNext 标准，Bun 自动回退到 .ts
+ *  源文件，Node 跑 install 后编译产物），不直接访问 src/ 内部路径。
+ *
+ *  好处：
+ *   - 框架内部重构（loop.ts / llm/client.ts / tools/* 移动）不破坏插件
+ *   - 插件作者只需记一个 import 源
+ *   - 暴露面收口（这里没的 API 不开放给插件）
+ *
+ *  零运行时开销：纯 re-export，TS 编译后等价于直接 import。
+ * ============================================================
+ */
+
+// --- 运行时入口 ---
+export { runQuery } from './loop.js';
+export type { RunQueryOptions } from './loop.js';
+export type { ToolGate, ToolGateRequest, ToolGateDecision } from './toolGate.js';
+export { runAgentTurn } from './session/runAgentTurn.js';
+export type { RunAgentTurnOptions, RunAgentTurnResult } from './session/runAgentTurn.js';
+
+export { chat } from './llm/client.js';
+export {
+  derivePromptCacheContext,
+} from './llm/promptCache.js';
+
+export { ALL_TOOLS, executeTool, getToolByName } from './tools/index.js';
+export { shutdownAllLsp } from './tools/lsp/service.js';
+
+// --- Computer Use ---
+//
+// 桌面操作的**知识与命令面**住在 `plugins/computer_use/`，可信执行层住在内核
+// （`src/tools/computeruse/`）。这里**只**开放只读诊断门面：
+//
+// ⚠️ 曾经这里导出的是完整的 `computerUseService`，而那个对象的 `request()`
+//    能派发 click / type / file_drop —— 一个「只做诊断与知识管理」的插件不该
+//    拿得到操作鼠标键盘的能力。注释当时宣称「只开放这几件事」，代码没做到。
+//    别再把 service 加回来。
+export { computerUseDiagnostics } from './tools/computeruse/diagnostics.js';
+export { describeCapabilities } from './tools/computeruse/capabilityLabels.js';
+export type { CapabilityLabel, CapabilityState } from './tools/computeruse/capabilityLabels.js';
+export type {
+  ManualDraft,
+  ManualSource,
+} from './tools/computeruse/diagnostics.js';
+export { readRecentComputerUseAudit } from './cli/computerUse.js';
+export { readComputerUseTelemetryReport } from './tools/computeruse/telemetryLog.js';
+export {
+  matchGuide,
+  describeMatch,
+  loadAllAppManuals,
+} from './tools/computeruse/vision/appGuide.js';
+export type {
+  LoadedManuals,
+} from './tools/computeruse/vision/appGuide.js';
+export {
+  EMPTY_MANUAL,
+  validateManual,
+} from './tools/computeruse/manualSchema.js';
+export type {
+  ManualFlow,
+} from './tools/computeruse/manualSchema.js';
+export type {
+  ComputerUseResponse,
+} from './tools/computeruse/protocol.js';
+
+// pre-read 守卫状态登记：tool 步覆盖「声明产物」时用来解除内核「先读后写 / 截断禁写」
+// 守卫（确定性步的 args 写死、模型没机会先 Read）。详见 stepExecutors/tool.ts。
+export { recordRead } from './tools/shared/fileState.js';
+
+export { getWorkingDir } from './bootstrap/workingDir.js';
+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.
+export {
+  buildBaseSystemPrompt,
+  buildTransientContext,
+  buildTransientPromptBundle,
+} from './prompts/system.js';
+export type { PromptEnvelope, PromptSurface } from './prompts/promptAssembly.js';
+export type { ContextBundle } from './context/contextBundle.js';
+export {
+  createAgentRuntimeContext,
+  filterToolsForRuntime,
+} from './runtime/agentRuntimeContext.js';
+export type {
+  AgentRuntimeContext,
+} from './runtime/agentRuntimeContext.js';
+export { getResourceSearchPaths } from './utils/resourcePaths.js';
+export type { ResourceName } from './utils/resourcePaths.js';
+
+// 确定性检查设施：verify 步（shell/file_exists/file_contains/test_count）经此跑校验。
+export { parseCheckString, runVerification } from './infra/verification.js';
+export type { Check } from './infra/verification.js';
+
+export { triggerHook } from './plugins/hookEngine.js';
+export type { HookEventName, HookDecision } from './plugins/hookEngine.js';
+
+export { createSessionState } from './session/sessionState.js';
+export type { SessionState } from './session/sessionState.js';
+
+// 会话文件是否真实存在（含 default session 的 legacy 路径回退）：
+// cron-runner 等需要在发起回合前判断"绑定的 session 是否还在"时用它，
+// 不要绕过 legacy 回退逻辑自己拼路径。
+export { resolveSessionFile } from './context/sessionPath.js';
+
+// --- 类型 ---
+export type {
+  ImageDetail,
+  ImageInputSpec,
+  Message,
+  Provider,
+  LoopEvent,
+  LlmStreamEvent,
+  PromptCacheContext,
+  Tool,
+  // 插件需要它来组装 executeTool 的第四参（宿主授权上下文按需切片转发）。
+  // 不导出的话插件只能绕过门面直接 import 内核，那正是门面要避免的。
+  ToolCallContext,
+  ToolResult,
+} from './types.js';
+
+export type {
+  PluginApi,
+  PluginContext,
+  PluginEvent,
+  PluginRuntimeContext,
+} from './plugins/pluginApi.js';

package/src/plugins/builtinPluginIds.js

@@ -0,0 +1,47 @@
+/**
+ * ============================================================
+ *  src/plugins/builtinPluginIds.ts —— 内置插件清单 / 插件资产目录（单一真值）
+ * ------------------------------------------------------------
+ *  这个文件存在的唯一理由：同一份清单此前被抄在四个地方（builtinRegistry.ts、
+ *  scripts/build-green.ts、minimal-desktop/scripts/build-sidecar.ts、以及各测试），
+ *  而它们**必须**同时更新才正确 —— 漏一处的失败方式全是静默的：
+ *
+ *   · 漏注册 rich 插件（真实发生过：computer_use）→ 绿色版/sidecar 里
+ *     `loadPluginApi` 找不到 runCommand → 静默回退成声明式 markdown →
+ *     `/computeruse` 从「确定性诊断命令」变成「让 LLM 自由发挥的 prompt」。
+ *     没有报错、没有告警，只有行为变了。
+ *   · 漏拷资产目录（真实发生过：`app/`）→ ComputerUse 对每个应用都报
+ *     「未找到说明书」，同样零构建期错误。
+ *
+ *  故意做成**不 import 任何东西的中立叶子模块**：构建脚本（bun 直接跑 .ts）、
+ *  单测和运行时代码都能安全 import 它，不会顺链拖进 plugin-sdk / ink 之类的重依赖。
+ * ============================================================
+ */
+/**
+ * 内置 rich 插件（带 `plugin.ts` 执行器的那些）的 id 清单。
+ *
+ * id 必须**等于插件目录名**（`plugins/<id>/` 的 `<id>`），因为 pluginLoader 用
+ * `basename(pluginRoot)` 查内置注册表。注意 `computer_use` 是下划线不是连字符 ——
+ * 目录名怎么写这里就怎么写，别顺手「统一风格」，改了就查不到了。
+ *
+ * `test/pluginBuiltinRegistry.test.ts` 把它和磁盘上实际存在 `plugin.ts` 的插件目录
+ * 做全等断言：多一个少一个都红。
+ */
+export const BUILTIN_PLUGIN_IDS = [
+    'workflow-runner',
+    'cron-runner',
+    'computer_use',
+];
+/**
+ * 插件里需要随包铺到磁盘的资产子目录（数据，不是代码）。
+ *
+ * 为什么不能靠打包器：这些目录里是 markdown / json 声明，没有任何 import 指向
+ * 它们，`bun --compile` 的依赖图看不见 → 只能由各构建脚本显式拷贝。绿色版
+ * （build-green.ts）与 Desktop sidecar（build-sidecar.ts）各拷一次，两处必须一致。
+ */
+export const PLUGIN_ASSET_DIRS = [
+    '.claude-plugin',
+    'commands',
+    'hooks',
+    'app',
+];

package/src/plugins/builtinPluginIds.ts

@@ -0,0 +1,51 @@
+/**
+ * ============================================================
+ *  src/plugins/builtinPluginIds.ts —— 内置插件清单 / 插件资产目录（单一真值）
+ * ------------------------------------------------------------
+ *  这个文件存在的唯一理由：同一份清单此前被抄在四个地方（builtinRegistry.ts、
+ *  scripts/build-green.ts、minimal-desktop/scripts/build-sidecar.ts、以及各测试），
+ *  而它们**必须**同时更新才正确 —— 漏一处的失败方式全是静默的：
+ *
+ *   · 漏注册 rich 插件（真实发生过：computer_use）→ 绿色版/sidecar 里
+ *     `loadPluginApi` 找不到 runCommand → 静默回退成声明式 markdown →
+ *     `/computeruse` 从「确定性诊断命令」变成「让 LLM 自由发挥的 prompt」。
+ *     没有报错、没有告警，只有行为变了。
+ *   · 漏拷资产目录（真实发生过：`app/`）→ ComputerUse 对每个应用都报
+ *     「未找到说明书」，同样零构建期错误。
+ *
+ *  故意做成**不 import 任何东西的中立叶子模块**：构建脚本（bun 直接跑 .ts）、
+ *  单测和运行时代码都能安全 import 它，不会顺链拖进 plugin-sdk / ink 之类的重依赖。
+ * ============================================================
+ */
+
+/**
+ * 内置 rich 插件（带 `plugin.ts` 执行器的那些）的 id 清单。
+ *
+ * id 必须**等于插件目录名**（`plugins/<id>/` 的 `<id>`），因为 pluginLoader 用
+ * `basename(pluginRoot)` 查内置注册表。注意 `computer_use` 是下划线不是连字符 ——
+ * 目录名怎么写这里就怎么写，别顺手「统一风格」，改了就查不到了。
+ *
+ * `test/pluginBuiltinRegistry.test.ts` 把它和磁盘上实际存在 `plugin.ts` 的插件目录
+ * 做全等断言：多一个少一个都红。
+ */
+export const BUILTIN_PLUGIN_IDS = [
+  'workflow-runner',
+  'cron-runner',
+  'computer_use',
+] as const;
+
+export type BuiltinPluginId = (typeof BUILTIN_PLUGIN_IDS)[number];
+
+/**
+ * 插件里需要随包铺到磁盘的资产子目录（数据，不是代码）。
+ *
+ * 为什么不能靠打包器：这些目录里是 markdown / json 声明，没有任何 import 指向
+ * 它们，`bun --compile` 的依赖图看不见 → 只能由各构建脚本显式拷贝。绿色版
+ * （build-green.ts）与 Desktop sidecar（build-sidecar.ts）各拷一次，两处必须一致。
+ */
+export const PLUGIN_ASSET_DIRS = [
+  '.claude-plugin',
+  'commands',
+  'hooks',
+  'app',
+] as const;

package/src/plugins/builtinRegistry.ts

@@ -0,0 +1,43 @@
+/**
+ * ============================================================
+ *  src/plugins/builtinRegistry.ts —— 内置插件静态注册（仅绿色版 compile 用）
+ * ------------------------------------------------------------
+ *  仅被 `src/entry.compiled.tsx`（bun --compile 入口）import。
+ *
+ *  作用：静态 import 内置 rich 插件的 plugin.ts，让 bun 在 `--compile` 时把
+ *  它们的执行器整树（含各自 `./src/*` 与框架 `../../src/plugin-sdk.ts`）一并
+ *  打进单个可执行文件；再注册进 pluginLoader 的内置表，供绿色目录里"只铺了
+ *  声明式部分（plugin.json + commands/）"的插件在运行时回退命中执行器。
+ *
+ *  ⚠️ dev / npm 模式**绝不 import 本文件**（入口是 src/main.tsx）→ 注册表为空
+ *  → pluginLoader 走原磁盘动态加载，行为逐字节不变。tsconfig.json 已 exclude
+ *  本文件与 entry.compiled.tsx，故 `tsc --build` 不产出二者 .js，npm tarball 不变。
+ *
+ *  key 必须等于插件目录名（`plugins/<id>/` 的 `<id>`），与 pluginLoader 里
+ *  `basename(pluginRoot)` 对齐。清单本身住在 `builtinPluginIds.ts`。
+ *
+ *  ⚠️ 为什么是 `Record<BuiltinPluginId, PluginApi>` 而不是几行 setBuiltinPluginApi：
+ *  漏一个插件的后果是**静默降级**（找不到执行器 → 回退声明式 markdown →
+ *  确定性命令悄悄变成 LLM prompt），没有任何报错。真实发生过：computer_use 有
+ *  plugin.ts 却没登记在这里。用 Record 之后，清单里加了 id 而这里少一个 import
+ *  就直接类型不过 —— 编译期挡住，比事后扫源码字符串硬得多。
+ *
+ *  注意 tsconfig.json 虽然 exclude 了本文件（不进 npm tarball），但
+ *  tsconfig.typecheck.json 不继承 include/exclude，`bun run typecheck` 照查不误。
+ * ============================================================
+ */
+
+import computerUseApi from '../../plugins/computer_use/plugin.js';
+import cronApi from '../../plugins/cron-runner/plugin.js';
+import workflowApi from '../../plugins/workflow-runner/plugin.js';
+import { BUILTIN_PLUGIN_IDS, type BuiltinPluginId } from './builtinPluginIds.js';
+import type { PluginApi } from './pluginApi.js';
+import { setBuiltinPluginApi } from './pluginLoader.js';
+
+const APIS: Record<BuiltinPluginId, PluginApi> = {
+  'workflow-runner': workflowApi,
+  'cron-runner': cronApi,
+  computer_use: computerUseApi,
+};
+
+for (const id of BUILTIN_PLUGIN_IDS) setBuiltinPluginApi(id, APIS[id]);

package/src/plugins/commandRouter.js

@@ -1,8 +1,12 @@
 import { readFile, readdir } from 'node:fs/promises';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
+import { getWorkingDir } from '../bootstrap/workingDir.js';
 import { getResourceSearchPaths } from '../utils/resourcePaths.js';
-const pluginCache = new Map();
-let discoveryDone = false;
+import { readPluginManifest } from './pluginManifest.js';
+const pluginCaches = new Map();
+function cacheFor(workingDir = getWorkingDir()) {
+    return pluginCaches.get(resolve(workingDir)) ?? new Map();
+}
 function stripQuotes(s) {
     const trimmed = s.trim();
     if ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
@@ -38,23 +42,22 @@ function parseMarkdownFrontmatter(content) {
 }
 async function loadPlugin(pluginDirPath) {
     const dirName = baseName(pluginDirPath);
-    const manifestPath = join(pluginDirPath, '.claude-plugin', 'plugin.json');
-    let manifestName = dirName;
-    let manifestVersion;
-    let manifestDesc;
-    try {
-        const raw = await readFile(manifestPath, 'utf8');
-        const parsed = JSON.parse(raw);
-        manifestName = parsed.name ?? dirName;
-        manifestVersion = parsed.version;
-        manifestDesc = parsed.description;
-    }
-    catch {
+    // manifest 只在 `pluginManifest.ts` 解析一处：字段一旦有两份读法就会漂移，
+    // 而说明书发现（vision/appGuide.ts）读的正是同一个文件。
+    const manifest = readPluginManifest(pluginDirPath);
+    const manifestName = manifest?.name ?? dirName;
+    const manifestVersion = manifest?.version;
+    const manifestDesc = manifest?.description;
+    for (const issue of manifest?.issues ?? []) {
+        console.warn(`[minimal-agent] 插件 "${manifestName}" 的 plugin.json：${issue}`);
     }
     const commandsDir = join(pluginDirPath, 'commands');
     const commands = [];
     try {
         const entries = await readdir(commandsDir, { withFileTypes: true });
+        // 排序理由同 skillList.ts：命令顺序会进系统提示词（formatPluginHint），
+        // readdir 的 fs 顺序不稳定会让提示词前缀漂移、打散 provider 的自动前缀缓存。
+        entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
         for (const entry of entries) {
             if (!entry.name.endsWith('.md'))
                 continue;
@@ -91,7 +94,10 @@ async function loadPlugin(pluginDirPath) {
     }
     catch {
     }
-    if (commands.length === 0 && !hasStopHook)
+    // 「只提供应用说明书、没有命令也没有 hook」也是合法插件 —— 知识本身就是
+    // 一种贡献。此前这里会把它判成「不是插件」直接丢掉。
+    const appManualDirs = manifest?.appManualDirs ?? [];
+    if (commands.length === 0 && !hasStopHook && appManualDirs.length === 0)
         return null;
     return {
         name: manifestName,
@@ -100,22 +106,30 @@ async function loadPlugin(pluginDirPath) {
         root: pluginDirPath,
         commands,
         hasStopHook,
+        appManualDirs,
     };
 }
-export async function discoverPlugins() {
-    if (discoveryDone && pluginCache.size > 0) {
-        return Array.from(pluginCache.values());
+export async function discoverPlugins(workingDir = getWorkingDir()) {
+    const cacheKey = resolve(workingDir);
+    const cached = pluginCaches.get(cacheKey);
+    if (cached) {
+        return Array.from(cached.values());
     }
-    pluginCache.clear();
-    discoveryDone = true;
+    const pluginCache = new Map();
     // 双源扫描：cwd 优先 + packageRoot fallback；按数组顺序处理，已有 manifestName 跳过
-    const searchPaths = getResourceSearchPaths('plugins', import.meta.url);
+    const searchPaths = getResourceSearchPaths('plugins', import.meta.url, cacheKey);
     // 命令名 → 首个声明它的插件名。resolveCommand 按插入顺序返回第一个命中，
     // 所以两个不同插件声明同名命令时，先注册者生效、后者被影 —— 不再静默，warn 一次。
     const commandOwners = new Map();
     for (const root of searchPaths) {
         try {
             const entries = await readdir(root, { withFileTypes: true });
+            // 排序有两个作用：
+            //   1. 提示词缓存：插件清单进系统提示词，顺序必须逐字节可复现（同 skillList.ts）。
+            //   2. 顺带修掉一个既有的不确定性 —— 下面「先注册者赢」的命令名冲突裁决此前
+            //      取决于 readdir 的 fs 返回顺序，同一份插件目录在不同机器/不同增删历史下
+            //      可能裁出不同赢家。排序后裁决稳定为字典序，行为可预测、可写进测试。
+            entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
             for (const entry of entries) {
                 if (!entry.isDirectory())
                     continue;
@@ -142,12 +156,12 @@ export async function discoverPlugins() {
         catch {
         }
     }
+    pluginCaches.set(cacheKey, pluginCache);
     return Array.from(pluginCache.values());
 }
 /** 仅供测试：重置 discovery cache。 */
 export function _resetPluginCache() {
-    pluginCache.clear();
-    discoveryDone = false;
+    pluginCaches.clear();
 }
 export function resolveCommand(input) {
     const trimmed = input.trimStart();
@@ -156,7 +170,7 @@ export function resolveCommand(input) {
     const spaceIdx = trimmed.indexOf(' ', 1);
     const cmdName = spaceIdx >= 0 ? trimmed.slice(1, spaceIdx) : trimmed.slice(1);
     const args = spaceIdx >= 0 ? trimmed.slice(spaceIdx + 1) : '';
-    for (const plugin of pluginCache.values()) {
+    for (const plugin of cacheFor().values()) {
         for (const cmd of plugin.commands) {
             if (cmd.name === cmdName) {
                 return { cmd, arguments: args };
@@ -183,7 +197,7 @@ export function buildCommandInput(resolved) {
 // src 内无调用不代表死代码，勿删。
 export function listAvailableCommands() {
     const result = [];
-    for (const plugin of pluginCache.values()) {
+    for (const plugin of cacheFor().values()) {
         for (const cmd of plugin.commands) {
             result.push({
                 command: `/${cmd.name}`,

package/src/plugins/commandRouter.ts

@@ -0,0 +1,261 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
+import { getWorkingDir } from '../bootstrap/workingDir.js';
+import { getResourceSearchPaths } from '../utils/resourcePaths.js';
+import { readPluginManifest } from './pluginManifest.js';
+
+export interface PluginCommand {
+  name: string;
+  description: string;
+  argumentHint?: string;
+  pluginName: string;
+  pluginRoot: string;
+  promptBody: string;
+}
+
+export interface PluginManifest {
+  name: string;
+  version?: string;
+  description?: string;
+  root: string;
+  commands: PluginCommand[];
+  hasStopHook: boolean;
+  /** manifest 里 `appManuals` 声明的应用说明书目录（绝对路径，已安全收敛）。 */
+  appManualDirs: string[];
+}
+
+const pluginCaches = new Map<string, Map<string, PluginManifest>>();
+
+function cacheFor(workingDir = getWorkingDir()): Map<string, PluginManifest> {
+  return pluginCaches.get(resolve(workingDir)) ?? new Map<string, PluginManifest>();
+}
+
+function stripQuotes(s: string): string {
+  const trimmed = s.trim();
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+/**
+ * 跨平台取路径最后一段。Windows 上 join() 产出反斜杠路径，单纯 split('/')
+ * 不切分会让整条绝对路径变成"目录名"。同时吃 \\ 与 /，与
+ * hookEngine.pluginNameFromRoot 的归一逻辑保持一致。
+ */
+export function baseName(p: string): string {
+  const parts = p.replace(/[\\/]+$/, '').split(/[\\/]/);
+  return parts[parts.length - 1] || p;
+}
+
+function parseMarkdownFrontmatter(content: string): Record<string, string> {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return {};
+
+  const frontmatter: Record<string, string> = {};
+  for (const line of match[1].split('\n')) {
+    const colon = line.indexOf(':');
+    if (colon < 0) continue;
+    const key = line.slice(0, colon).trim();
+    const value = line.slice(colon + 1).trim();
+    if (key) frontmatter[key] = stripQuotes(value);
+  }
+  return frontmatter;
+}
+
+async function loadPlugin(pluginDirPath: string): Promise<PluginManifest | null> {
+  const dirName = baseName(pluginDirPath);
+
+  // manifest 只在 `pluginManifest.ts` 解析一处：字段一旦有两份读法就会漂移，
+  // 而说明书发现（vision/appGuide.ts）读的正是同一个文件。
+  const manifest = readPluginManifest(pluginDirPath);
+  const manifestName = manifest?.name ?? dirName;
+  const manifestVersion = manifest?.version;
+  const manifestDesc = manifest?.description;
+  for (const issue of manifest?.issues ?? []) {
+    console.warn(`[minimal-agent] 插件 "${manifestName}" 的 plugin.json：${issue}`);
+  }
+
+  const commandsDir = join(pluginDirPath, 'commands');
+  const commands: PluginCommand[] = [];
+
+  try {
+    const entries = await readdir(commandsDir, { withFileTypes: true });
+    // 排序理由同 skillList.ts：命令顺序会进系统提示词（formatPluginHint），
+    // readdir 的 fs 顺序不稳定会让提示词前缀漂移、打散 provider 的自动前缀缓存。
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const entry of entries) {
+      if (!entry.name.endsWith('.md')) continue;
+
+      const cmdPath = join(commandsDir, entry.name);
+      try {
+        const content = await readFile(cmdPath, 'utf8');
+        const fm = parseMarkdownFrontmatter(content);
+
+        const sep = content.indexOf('\n---', 4);
+        const body = sep >= 0 ? content.slice(sep + 4).trim() : content.trim();
+
+        commands.push({
+          name: entry.name.replace(/\.md$/, ''),
+          description: fm.description ?? '(no description)',
+          argumentHint: fm['argument-hint'],
+          pluginName: manifestName,
+          pluginRoot: pluginDirPath,
+          promptBody: body,
+        });
+      } catch {
+      }
+    }
+  } catch {
+  }
+
+  const hooksJsonPath = join(pluginDirPath, 'hooks', 'hooks.json');
+  let hasStopHook = false;
+  try {
+    const hooksRaw = await readFile(hooksJsonPath, 'utf8');
+    const hooksParsed = JSON.parse(hooksRaw);
+    const stopHooks = hooksParsed?.hooks?.Stop;
+    if (Array.isArray(stopHooks) && stopHooks.length > 0) {
+      hasStopHook = true;
+    }
+  } catch {
+  }
+
+  // 「只提供应用说明书、没有命令也没有 hook」也是合法插件 —— 知识本身就是
+  // 一种贡献。此前这里会把它判成「不是插件」直接丢掉。
+  const appManualDirs = manifest?.appManualDirs ?? [];
+  if (commands.length === 0 && !hasStopHook && appManualDirs.length === 0) return null;
+
+  return {
+    name: manifestName,
+    version: manifestVersion,
+    description: manifestDesc,
+    root: pluginDirPath,
+    commands,
+    hasStopHook,
+    appManualDirs,
+  };
+}
+
+export async function discoverPlugins(workingDir = getWorkingDir()): Promise<PluginManifest[]> {
+  const cacheKey = resolve(workingDir);
+  const cached = pluginCaches.get(cacheKey);
+  if (cached) {
+    return Array.from(cached.values());
+  }
+
+  const pluginCache = new Map<string, PluginManifest>();
+
+  // 双源扫描：cwd 优先 + packageRoot fallback；按数组顺序处理，已有 manifestName 跳过
+  const searchPaths = getResourceSearchPaths('plugins', import.meta.url, cacheKey);
+
+  // 命令名 → 首个声明它的插件名。resolveCommand 按插入顺序返回第一个命中，
+  // 所以两个不同插件声明同名命令时，先注册者生效、后者被影 —— 不再静默，warn 一次。
+  const commandOwners = new Map<string, string>();
+
+  for (const root of searchPaths) {
+    try {
+      const entries = await readdir(root, { withFileTypes: true });
+      // 排序有两个作用：
+      //   1. 提示词缓存：插件清单进系统提示词，顺序必须逐字节可复现（同 skillList.ts）。
+      //   2. 顺带修掉一个既有的不确定性 —— 下面「先注册者赢」的命令名冲突裁决此前
+      //      取决于 readdir 的 fs 返回顺序，同一份插件目录在不同机器/不同增删历史下
+      //      可能裁出不同赢家。排序后裁决稳定为字典序，行为可预测、可写进测试。
+      entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        if (entry.name.startsWith('.')) continue;
+
+        const plugin = await loadPlugin(join(root, entry.name));
+        if (!plugin) continue;
+        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 {
+    }
+  }
+
+  pluginCaches.set(cacheKey, pluginCache);
+  return Array.from(pluginCache.values());
+}
+
+/** 仅供测试：重置 discovery cache。 */
+export function _resetPluginCache(): void {
+  pluginCaches.clear();
+}
+
+export function resolveCommand(input: string): { cmd: PluginCommand; arguments: string } | null {
+  const trimmed = input.trimStart();
+  if (!trimmed.startsWith('/')) return null;
+
+  const spaceIdx = trimmed.indexOf(' ', 1);
+  const cmdName = spaceIdx >= 0 ? trimmed.slice(1, spaceIdx) : trimmed.slice(1);
+  const args = spaceIdx >= 0 ? trimmed.slice(spaceIdx + 1) : '';
+
+  for (const plugin of cacheFor().values()) {
+    for (const cmd of plugin.commands) {
+      if (cmd.name === cmdName) {
+        return { cmd, arguments: args };
+      }
+    }
+  }
+
+  return null;
+}
+
+export function buildCommandInput(
+  resolved: { cmd: PluginCommand; arguments: string },
+): string {
+  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 (!hadArgsPlaceholder && args.trim()) {
+    input += `\n\n用户参数: ${args.trim()}`;
+  }
+
+  return input;
+}
+
+// 消费方是测试与宿主侧枚举（V1 红线守护测试 pluginRunner.isolation.test.ts 用它
+// 断言「非 / 输入零 discovery 副作用」；commandRouter.test.ts 断言命令清单）——
+// src 内无调用不代表死代码，勿删。
+export function listAvailableCommands(): { command: string; plugin: string; description: string }[] {
+  const result: { command: string; plugin: string; description: string }[] = [];
+  for (const plugin of cacheFor().values()) {
+    for (const cmd of plugin.commands) {
+      result.push({
+        command: `/${cmd.name}`,
+        plugin: plugin.name,
+        description: cmd.description,
+      });
+    }
+  }
+  return result;
+}