made-bridge 0.0.0-stage → 0.2.1

package/src/plugin-package.mjs

@@ -0,0 +1,132 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+const PACKAGE_DIR = /^[a-z0-9][a-z0-9_-]{0,39}$/;
+const SETTING_KEY = /^[A-Za-z][A-Za-z0-9_]{0,31}$/;
+const reserved = new Set(['__proto__', 'constructor', 'prototype']);
+const MAX_FIELDS = 16;
+const MAX_LABEL = 64;
+const MAX_HELP = 200;
+const MAX_VALUE = 500;
+const MAX_PATTERN = 200;
+const MAX_FILE = 16 * 1024;
+
+const fail = (message) => {
+  const error = new Error(message);
+  error.preserveMessage = true;
+  return error;
+};
+
+const textOK = (value, max) => typeof value === 'string' && value.trim() && Buffer.byteLength(value) <= max && !/[\p{Cc}\p{Cf}]/u.test(value);
+
+function readJson(file) {
+  const text = fs.readFileSync(file, 'utf8');
+  if (Buffer.byteLength(text) > MAX_FILE) throw fail('插件配置过大');
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw fail('插件配置无效');
+  }
+}
+
+export function parseSettingsSpec(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw fail('插件配置规范无效');
+  const allowed = new Set(['id', 'settings']);
+  if (Object.keys(raw).some((key) => !allowed.has(key))) throw fail('插件配置规范无效');
+  if (raw.id !== undefined && (typeof raw.id !== 'string' || !PACKAGE_DIR.test(raw.id))) throw fail('插件配置规范无效');
+  if (raw.settings === undefined) return { id: raw.id || '', fields: [] };
+  if (!Array.isArray(raw.settings) || raw.settings.length > MAX_FIELDS) throw fail('插件配置规范无效');
+  const keys = new Set();
+  const fields = raw.settings.map((field) => {
+    if (!field || typeof field !== 'object' || Array.isArray(field)) throw fail('插件配置规范无效');
+    const fieldKeys = new Set(['key', 'label', 'type', 'required', 'default', 'help', 'pattern']);
+    if (Object.keys(field).some((key) => !fieldKeys.has(key))) throw fail('插件配置规范无效');
+    if (!SETTING_KEY.test(field.key || '') || reserved.has(field.key) || keys.has(field.key)) throw fail('插件配置规范无效');
+    if (!textOK(field.label, MAX_LABEL) || field.type !== 'text') throw fail('插件配置规范无效');
+    if (field.required !== undefined && typeof field.required !== 'boolean') throw fail('插件配置规范无效');
+    if (field.default !== undefined && (typeof field.default !== 'string' || Buffer.byteLength(field.default) > MAX_VALUE)) throw fail('插件配置规范无效');
+    if (field.help !== undefined && !textOK(field.help, MAX_HELP)) throw fail('插件配置规范无效');
+    let pattern;
+    if (field.pattern !== undefined) {
+      if (typeof field.pattern !== 'string' || field.pattern.length > MAX_PATTERN) throw fail('插件配置规范无效');
+      try {
+        const compiled = new RegExp(field.pattern);
+        if (compiled.global || compiled.sticky) throw fail('插件配置规范无效');
+      } catch (error) {
+        if (error.preserveMessage) throw error;
+        throw fail('插件配置规范无效');
+      }
+      pattern = field.pattern;
+    }
+    keys.add(field.key);
+    return {
+      key: field.key,
+      label: field.label.trim(),
+      type: 'text',
+      required: field.required === true,
+      ...(field.default !== undefined ? { default: field.default } : {}),
+      ...(field.help ? { help: field.help.trim() } : {}),
+      ...(pattern ? { pattern } : {}),
+    };
+  });
+  return { id: raw.id || '', fields };
+}
+
+export function resolveSettings(fields, raw) {
+  if (raw === undefined || raw === null) raw = {};
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw fail('插件配置无效');
+  const known = new Set(fields.map((field) => field.key));
+  for (const key of Object.keys(raw)) {
+    if (!known.has(key) || typeof raw[key] !== 'string' || Buffer.byteLength(raw[key]) > MAX_VALUE) throw fail('插件配置无效');
+  }
+  const values = {};
+  for (const field of fields) {
+    const value = Object.hasOwn(raw, field.key) ? raw[field.key] : (field.default ?? '');
+    if (field.required && !value.trim()) throw fail('插件配置无效');
+    if (field.pattern && !new RegExp(field.pattern).test(value)) throw fail('插件配置无效');
+    values[field.key] = value;
+  }
+  return values;
+}
+
+export function readPackageSettings(dir) {
+  const specFile = path.join(dir, 'plugin.json');
+  if (!fs.existsSync(specFile)) return { id: '', fields: [], values: {}, error: '' };
+  try {
+    const spec = parseSettingsSpec(readJson(specFile));
+    const settingsFile = path.join(dir, 'settings.json');
+    const raw = fs.existsSync(settingsFile) ? readJson(settingsFile) : {};
+    return { id: spec.id, fields: spec.fields, values: resolveSettings(spec.fields, raw), error: '' };
+  } catch (error) {
+    return { id: '', fields: [], values: {}, error: error.preserveMessage ? error.message : '插件配置无效' };
+  }
+}
+
+export function isPackageEntry(filename) {
+  const base = path.basename(filename);
+  return (base === 'plugin.mjs' || base === 'plugin.js') && fs.existsSync(path.join(path.dirname(filename), 'plugin.json'));
+}
+
+export function packageDirectories(pluginsDir) {
+  if (!fs.existsSync(pluginsDir) || !fs.statSync(pluginsDir).isDirectory()) return [];
+  return fs.readdirSync(pluginsDir).sort().flatMap((name) => {
+    if (!PACKAGE_DIR.test(name)) return [];
+    const dir = path.join(pluginsDir, name);
+    if (!fs.statSync(dir).isDirectory()) return [];
+    const entry = ['plugin.mjs', 'plugin.js'].map((file) => path.join(dir, file)).find((file) => fs.existsSync(file) && fs.statSync(file).isFile());
+    return entry ? [{ name, dir, entry }] : [];
+  });
+}
+
+export function writePackageSettings(dir, values) {
+  const current = readPackageSettings(dir);
+  if (current.error) throw fail(current.error);
+  if (!current.fields.length) throw fail('插件没有可保存的配置');
+  const resolved = resolveSettings(current.fields, values);
+  const file = path.join(dir, 'settings.json');
+  const temporary = path.join(dir, `.settings-${process.pid}-${randomUUID()}.json`);
+  fs.writeFileSync(temporary, `${JSON.stringify(resolved, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(temporary, file);
+  return resolved;
+}

package/src/plugin-runtime.mjs

@@ -0,0 +1,169 @@
+/**
+ * 插件运行时助手：跨平台的命令查找与子进程调用。
+ *
+ * 为什么单独放一个文件：插件常要包一层第三方 CLI 或 npm 包，而平台差异全在细节里——
+ *   - Windows 上 npm 实际是 npm.cmd，Node 20 起不允许直接 spawn .cmd/.bat（报 EINVAL），
+ *     必须经 cmd.exe；而 Node 在 shell 模式下只是把命令和参数用空格拼起来，含空格的
+ *     路径（C:\Users\John Doe\…）会被 cmd 拆成两个参数，引号得自己加。
+ *   - PATH 探测在 Windows 上要按 PATHEXT 逐个补扩展名，且 X_OK 在 Windows 上没有意义。
+ *   - 「命令不存在」和「命令存在但执行失败」是两件事，报错必须分开，否则排查会被带偏。
+ * 这些收在一处，插件作者不必各自踩一遍，也不用引入 cross-spawn 之类的依赖。
+ *
+ * 插件通过 `config.runtime` 拿到这些函数，例如：
+ *   const { runNpm } = config.runtime;
+ *   const globalRoot = runNpm(['root', '-g']).trim();
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+export const platform = process.platform;
+export const isWindows = platform === 'win32';
+
+/** 命令是否已自带扩展名，Windows 上带了就不用再补 PATHEXT。 */
+const HAS_EXTENSION = /\.(?:exe|com|bat|cmd|ps1)$/i;
+
+/** Windows 下的可执行扩展名，按 PATHEXT 取，缺省给一套常见值。 */
+function windowsExtensions(env) {
+  const raw = env.PATHEXT || '.COM;.EXE;.BAT;.CMD';
+  return raw.split(';').map((s) => s.trim()).filter(Boolean);
+}
+
+/**
+ * 单个文件能否当命令执行。Windows 上没有可执行位，能读到即可；
+ * 类 Unix 按 X_OK 判，避免把普通数据文件当成命令。
+ */
+function isExecutable(filename) {
+  try {
+    if (!fs.statSync(filename).isFile()) return false;
+    fs.accessSync(filename, isWindows ? fs.constants.F_OK : fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 在 PATH 里查一个命令，返回绝对路径；找不到返回空串。
+ * 传了路径分隔符的命令按字面路径处理，不再搜 PATH。
+ */
+export function findCommand(command, { env = process.env } = {}) {
+  const name = String(command || '').trim();
+  if (!name) return '';
+  if (name.includes('/') || name.includes('\\')) {
+    return isExecutable(name) ? path.resolve(name) : '';
+  }
+  const suffixes = isWindows && !HAS_EXTENSION.test(name) ? ['', ...windowsExtensions(env)] : [''];
+  for (const directory of (env.PATH || '').split(path.delimiter)) {
+    for (const suffix of suffixes) {
+      const candidate = path.join(directory || '.', name + suffix);
+      if (isExecutable(candidate)) return candidate;
+    }
+  }
+  return '';
+}
+
+/** 这条命令在本机是否存在（跨平台，等价于「装了没有」）。 */
+export function hasCommand(command, options) {
+  return Boolean(findCommand(command, options));
+}
+
+/**
+ * 按 cmd.exe 的规则给一个参数加引号。Node 在 shell 模式下不做这层处理，
+ * 含空格或 cmd 元字符的参数必须自己包好，否则会被拆开或被当成控制字符。
+ */
+function quoteWindowsArgument(value) {
+  const text = String(value ?? '');
+  if (text === '') return '""';
+  if (/[\s"^&|<>()]/.test(text)) return `"${text.replace(/"/g, '""')}"`;
+  return text;
+}
+
+/** 把 argv 拼成一条 cmd.exe 命令行。启动 .cmd/.bat 时用它，异步 spawn 也用同一套。 */
+export function windowsCommandLine(argv) {
+  return argv.map(quoteWindowsArgument).join(' ');
+}
+
+/**
+ * 同步执行一条命令。返回 spawnSync 的结果，并补两样东西：
+ *   resolved —— 实际用的可执行文件路径；notFound —— 是不是「本机没这个命令」。
+ * stdio 传 'inherit' 时不做编码转换，交给子进程直连终端。
+ */
+export function runCommand(command, args = [], {
+  env = process.env, cwd, timeout, input, encoding = 'utf8', stdio,
+} = {}) {
+  const resolved = findCommand(command, { env });
+  if (!resolved) {
+    const error = Object.assign(new Error(`本机未找到 ${command} 命令`), { code: 'ENOENT' });
+    return { status: null, stdout: '', stderr: '', error, resolved: '', notFound: true };
+  }
+  const options = { env, cwd, timeout };
+  if (stdio) options.stdio = stdio;
+  else {
+    options.encoding = encoding;
+    if (input !== undefined) options.input = input;
+  }
+  // .cmd/.bat 只能经 cmd.exe 启动；命令与参数在这里拼成一条命令行。
+  const result = isWindows && /\.(?:cmd|bat)$/i.test(resolved)
+    ? spawnSync(windowsCommandLine([resolved, ...args]), { ...options, shell: true })
+    : spawnSync(resolved, args, options);
+  return { ...result, resolved, notFound: false };
+}
+
+/**
+ * 定位 npm。Windows 上 npm 是 npm.cmd，直接 spawn 会 EINVAL；能找到它旁边的
+ * npm-cli.js 就改用 node 跑那个脚本，彻底绕开 cmd 的引号规则（更稳）。
+ */
+function locateNpm(env) {
+  const command = findCommand('npm', { env });
+  if (!command) return null;
+  if (isWindows) {
+    const script = path.join(path.dirname(command), 'node_modules', 'npm', 'bin', 'npm-cli.js');
+    if (fs.existsSync(script)) return { command, script };
+  }
+  return { command, script: '' };
+}
+
+/** npm 执行失败时的错误：带上最后几行输出，「装了但跑不动」和「没装」在 message 里分得清。 */
+function npmFailure(args, detail) {
+  const tail = String(detail || '').trim().slice(-300);
+  return Object.assign(
+    new Error(`npm ${args.join(' ')} 执行失败${tail ? `：${tail}` : ''}`),
+    { code: 'ENPMFAIL' },
+  );
+}
+
+/**
+ * 同步执行 npm，成功返回 stdout（原样，调用方自己 trim）。失败抛错：
+ * 本机没装 npm 是 ENOENT（notFound=true），装了但执行失败是 ENPMFAIL。
+ */
+export function runNpm(args = [], { env = process.env, cwd, timeout, input } = {}) {
+  const npm = locateNpm(env);
+  if (!npm) {
+    throw Object.assign(new Error('本机未找到 npm 命令，请先安装 Node.js（含 npm）'), {
+      code: 'ENOENT', notFound: true,
+    });
+  }
+  const options = { env, cwd, timeout, encoding: 'utf8' };
+  if (input !== undefined) options.input = input;
+  const result = npm.script
+    ? spawnSync(process.execPath, [npm.script, ...args], options)
+    : spawnSync(npm.command, args, options);
+  if (result.error) {
+    if (result.error.code === 'ENOENT') {
+      throw Object.assign(new Error('本机未找到 npm 命令，请先安装 Node.js（含 npm）'), {
+        code: 'ENOENT', notFound: true,
+      });
+    }
+    throw result.error;
+  }
+  if (result.status !== 0) throw npmFailure(args, `${result.stderr || ''}${result.stdout || ''}`);
+  return result.stdout || '';
+}
+
+/** 交给插件的那一份：冻结，避免插件改到别的插件或桥接器的行为。 */
+export const pluginRuntime = Object.freeze({
+  platform, isWindows, findCommand, hasCommand, runCommand, runNpm,
+});
+
+export default pluginRuntime;

package/src/plugins/contracts.d.ts

@@ -0,0 +1,184 @@
+/** Vibe Bridge plugin API v1. Local plugins execute in the desktop process. */
+/** Pixel image supplied by the bridge, not a firmware animal-template name. */
+export interface AgentIcon {
+  format: 'indexed4';
+  width: number; // integer 1..48
+  height: number; // integer 1..48
+  palette: string[]; // 1..16 colors, RRGGBBAA without #
+  data: string; // canonical base64: 4-bit linear indices, high nibble first
+  background: string; // #RRGGBB
+  accent: string; // #RRGGBB
+}
+/** Legacy preset strings are expanded on the bridge before transmission. */
+export type Icon = AgentIcon | 'fox' | 'rabbit' | 'owl' | 'panda';
+export type Settings = Record<string, string>;
+export interface Capabilities {
+  session: 'native' | 'external_unscoped';
+  model: boolean;
+  cancel: boolean;
+  progress: boolean;
+}
+export interface Job {
+  id: string;
+  provider: string;
+  instruction: string;
+  vibeSessionId: string;
+  sessionId?: string;
+  [key: string]: unknown;
+}
+export interface Project { id: string; label: string; path: string }
+/**
+ * Cross-platform helpers the bridge hands to every plugin. Use these instead of
+ * hand-rolling PATH lookups or spawning npm: on Windows npm is npm.cmd, which
+ * Node 20+ refuses to spawn without a shell, and PATH lookups must walk PATHEXT.
+ */
+export interface PluginRuntime {
+  /** process.platform of the bridge, e.g. 'darwin' | 'linux' | 'win32'. */
+  platform: string;
+  isWindows: boolean;
+  /** Absolute path of a command on PATH, or '' when it is not installed. */
+  findCommand: (command: string, options?: { env?: NodeJS.ProcessEnv }) => string;
+  /** Whether a command is installed. */
+  hasCommand: (command: string, options?: { env?: NodeJS.ProcessEnv }) => boolean;
+  /** Sync spawn that returns {status, stdout, stderr, resolved, notFound}. */
+  runCommand: (command: string, args?: string[], options?: Record<string, unknown>) => {
+    status: number | null; stdout: string; stderr: string; resolved: string; notFound: boolean;
+  };
+  /** Sync npm run; returns stdout. Throws ENOENT when npm is missing. */
+  runNpm: (args?: string[], options?: Record<string, unknown>) => string;
+}
+export interface PluginConfig {
+  locale?: 'zh-CN' | 'en';
+  stateDir: string;
+  models?: Record<string, string>;
+  /** Values for one plugin. A packaged plugin declares the keys in plugin.json; the bridge fills this from that package's settings.json. */
+  pluginSettings?: Record<string, Record<string, string>>;
+  /** Cross-platform helpers; prefer these over hand-rolled spawn/npm calls. */
+  runtime?: PluginRuntime;
+  [key: string]: unknown;
+}
+export interface RunContext {
+  job: Job;
+  project: Project;
+  signal: AbortSignal;
+  config: PluginConfig;
+  model?: string;
+  onProgress: (text: string) => void;
+  onSession: (sessionId: string) => void;
+}
+export interface RunResult {
+  status: 'completed' | 'handed_off';
+  result: string;
+  gitSnapshot?: string;
+  handoff?: { cursor: string; readState: string; replyCount?: number; [key: string]: unknown };
+}
+export interface CodingAgentPlugin {
+  apiVersion: 1;
+  kind: 'coding-agent';
+  id: string;
+  label: string;
+  icon?: Icon;
+  capabilities: Capabilities;
+  model?: { default: string; required: boolean };
+  sessionIdPattern?: RegExp;
+  probe: (config: PluginConfig) => { available: boolean; reason?: string; mode?: string };
+  run: (context: RunContext) => Promise<RunResult>;
+  readUpdates?: (context: { job: Job; config: PluginConfig }) => Promise<{
+    handoff: { cursor: string; readState: string; replyCount?: number };
+    appendResult: string;
+  }>;
+}
+export interface BoardEvent {
+  name: string;
+  fields: Record<string, string>;
+}
+export interface BoardCommand {
+  name: string;
+  fields?: Record<string, string>;
+}
+export interface QueuedBoardCommand extends BoardCommand {
+  id: string;
+  fields: Record<string, string>;
+}
+/** Bridge handles for board plugins: what an enhancement can reach without a hook. */
+export interface BridgeFacade {
+  /** Enabled coding agents with a probed availability snapshot. */
+  agents(): { id: string; label: string; available: boolean; reason: string; mode: string; capabilities: Capabilities }[];
+  agent(id: string): ReturnType<BridgeFacade['agents']>[number] | undefined;
+  /** Persisted jobs, newest first. */
+  jobs(): Record<string, unknown>[];
+  job(id: string): Record<string, unknown> | undefined;
+  sessions(agentId?: string): Record<string, unknown>[];
+  /** Create a task (waiting_confirmation) for an agent; rate-limited per bridge. */
+  createTask(options: { instruction: string; agentId?: string; projectId?: string; title?: string }): { job: Record<string, unknown>; session: Record<string, unknown> };
+  /** Append a turn to an existing session. */
+  submitTurn(options: { instruction: string; sessionId: string }): Record<string, unknown>;
+  confirmJob(id: string): Record<string, unknown>;
+  cancelJob(id: string): Record<string, unknown>;
+  themes(): { name: string; title: string; sound: boolean; icon: boolean; background: boolean }[];
+  devices(): string[];
+  /** Enqueue a board command directly; only the board-side catalog constrains the name. */
+  send(deviceId: string, command: BoardCommand, audio?: Uint8Array): QueuedBoardCommand;
+  pending(deviceId: string): QueuedBoardCommand[];
+}
+/** Turn input pipeline: return a new string to override what the agent executes. */
+export interface TurnInputContext {
+  instruction: string;
+  job: Job;
+  agentId: string;
+  config: PluginConfig;
+  bridge: BridgeFacade;
+}
+/** Turn output pipeline: called only when a job completes; a returned string overrides the result. */
+export interface TurnOutputContext {
+  result: string;
+  job: Job;
+  agentId: string;
+  status: 'completed';
+  config: PluginConfig;
+  bridge: BridgeFacade;
+}
+export type JobEventType = 'created' | 'confirmed' | 'started' | 'progress' | 'completed' | 'handed_off' | 'failed' | 'cancelled';
+/** Job lifecycle notification; fire-and-forget, failures never affect the job. */
+export interface JobEventContext {
+  type: JobEventType;
+  job: Job;
+  config: PluginConfig;
+  bridge: BridgeFacade;
+}
+/**
+ * Bridge plugin: subscribes to board events. Event delivery and command
+ * delivery are separate. Return commands or call send(); both enqueue for a
+ * later pull. send() stays valid after onEvent returns. Pass a PCM WAV
+ * buffer as the second argument only for audio.play; the board fetches those
+ * bytes with the command.
+ */
+export interface BoardPlugin {
+  apiVersion: 1;
+  kind: 'board-plugin';
+  id: string;
+  label: string;
+  events: string[];
+  commands: string[];
+  probe: (config: PluginConfig) => { available: boolean; reason?: string };
+  onConnect?: (context: {
+    deviceId: string;
+    config: PluginConfig;
+    send: (command: BoardCommand, audio?: Uint8Array) => QueuedBoardCommand;
+    bridge: BridgeFacade;
+  }) => Promise<void> | void;
+  onEvent: (context: {
+    event: BoardEvent;
+    config: PluginConfig;
+    deviceId: string;
+    send: (command: BoardCommand, audio?: Uint8Array) => QueuedBoardCommand;
+    bridge: BridgeFacade;
+  }) => Promise<{ commands?: BoardCommand[] } | void> | { commands?: BoardCommand[] } | void;
+  /** Turn input pipeline: a returned string overrides the instruction actually executed (the stored original stays intact). */
+  onTurnInput?: (context: TurnInputContext) => string | void | Promise<string | void>;
+  /** Turn output pipeline: called only for completed jobs; a returned string overrides the result. */
+  onTurnOutput?: (context: TurnOutputContext) => string | void | Promise<string | void>;
+  /** Job lifecycle notification. Tasks created by plugins do not broadcast 'created'. */
+  onJob?: (context: JobEventContext) => void;
+}
+export type VibePlugin = CodingAgentPlugin | BoardPlugin;

package/src/plugins/enhance.mjs

@@ -0,0 +1,156 @@
+/**
+ * 增强运行时：桥接器向管控插件开放的接口面。
+ *
+ * 管控插件是"有自主行为能力的增强体"：触发（事件、回合钩子、任务通知）只决定它
+ * 何时被唤醒；被唤醒后能做什么，取决于这里露出了多少句柄。接口有两条供给线：
+ * - 板侧线：事件与命令，清单由固件上报，桥接器只做清单校验；要新命令（如关机）得改固件。
+ * - 桥接器线：本模块露出的句柄（助手、任务、主题、板侧发送），重启桥接器即生效。
+ *
+ * 回合管道是顺序链：每个插件拿到上一环的产物，返回新字符串即 override，最后一个
+ * 说话的算数。单个插件超时或出错时沿用上一环的值，绝不阻断任务本身。
+ */
+
+const HOOK_TIMEOUT_MS = 1500;
+const CREATE_TASK_LIMIT = 10;
+const CREATE_TASK_WINDOW_MS = 60_000;
+
+export function createEnhancement(config) {
+  const wired = { jobs: null, board: null, themes: null };
+  const created = [];
+
+  const boardPlugins = () => {
+    try { return config.pluginsRuntime?.boardPlugins?.() ?? []; } catch { return []; }
+  };
+
+  const usable = (plugin) => {
+    try {
+      const state = plugin.probe(config);
+      return Boolean(state && typeof state === 'object' && !(state instanceof Promise) && state.available === true);
+    } catch { return false; }
+  };
+
+  async function settle(value, plugin) {
+    let timer;
+    try {
+      return await Promise.race([
+        Promise.resolve(value),
+        new Promise((_, reject) => {
+          timer = setTimeout(() => reject(new Error(`插件 ${plugin.id} 处理超时`)), HOOK_TIMEOUT_MS);
+        }),
+      ]);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async function pipeline(hookName, initial, contextFor) {
+    let value = initial;
+    for (const plugin of boardPlugins()) {
+      const hook = plugin[hookName];
+      if (typeof hook !== 'function' || !usable(plugin)) continue;
+      try {
+        const next = await settle(hook(contextFor(value)), plugin);
+        if (typeof next === 'string') value = next;
+      } catch { /* 单个插件失败不阻断链，也不影响任务本身。 */ }
+    }
+    return value;
+  }
+
+  function agentView(plugin) {
+    let state = {};
+    try {
+      const probed = plugin.probe(config);
+      if (probed && typeof probed === 'object' && typeof probed.then !== 'function') state = probed;
+    } catch { state = {}; }
+    return {
+      id: plugin.id,
+      label: plugin.label,
+      capabilities: plugin.capabilities,
+      available: state.available === true,
+      reason: typeof state.reason === 'string' ? state.reason : '',
+      mode: typeof state.mode === 'string' ? state.mode : 'plugin',
+    };
+  }
+
+  /** 桥接器句柄：插件在事件、钩子与通知的上下文里拿到的就是这个对象。 */
+  function bridge() {
+    const agents = () => {
+      try { return (config.pluginsRuntime?.agents?.() ?? []).map(agentView); } catch { return []; }
+    };
+    return {
+      agents,
+      agent: (id) => agents().find((agent) => agent.id === id),
+      jobs: () => (wired.jobs ? wired.jobs.list().map((job) => ({ ...job })) : []),
+      job: (id) => {
+        if (!wired.jobs) return undefined;
+        const job = wired.jobs.get(id);
+        return job ? { ...job } : undefined;
+      },
+      sessions: (agentId) => (wired.jobs ? wired.jobs.listSessions(agentId).map((session) => ({ ...session })) : []),
+      createTask: ({ instruction, agentId, projectId, title } = {}) => {
+        if (!wired.jobs) throw new Error('桥接器尚未就绪');
+        createTaskGuard();
+        const provider = agentId || config.defaultProvider;
+        const project = projectId || wired.jobs.defaultProject;
+        const session = wired.jobs.createSession({ provider, projectId: project, title });
+        const job = wired.jobs.submit({ instruction, sessionId: session.id, provider, projectId: project, source: 'plugin' });
+        return { job: { ...job }, session: { ...session } };
+      },
+      submitTurn: ({ instruction, sessionId } = {}) => {
+        if (!wired.jobs || !sessionId) throw new Error('请指定要继续的任务');
+        return { ...wired.jobs.submit({ instruction, sessionId, source: 'plugin' }) };
+      },
+      confirmJob: (id) => ({ ...wired.jobs.confirm(id) }),
+      cancelJob: (id) => ({ ...wired.jobs.cancel(id) }),
+      themes: () => (wired.themes ? wired.themes() : []),
+      devices: () => (wired.board ? wired.board.deviceIds() : []),
+      send: (deviceId, command, audio) => {
+        if (!wired.board) throw new Error('桥接器尚未就绪');
+        return wired.board.send(deviceId, command, audio);
+      },
+      pending: (deviceId) => (wired.board ? wired.board.pending(deviceId) : []),
+    };
+  }
+
+  /** 回合输入管道：改写本轮实际执行的指令；存储里的任务原文保持不变。 */
+  async function turnIn(job) {
+    return pipeline('onTurnInput', job.instruction, (instruction) => ({
+      instruction, job, agentId: job.provider, config, bridge: bridge(),
+    }));
+  }
+
+  /** 回合输出管道：仅在任务完成时调用，返回新字符串即改写结果。 */
+  async function turnOut(job, result) {
+    return pipeline('onTurnOutput', result, (value) => ({
+      result: value, job, agentId: job.provider, status: 'completed', config, bridge: bridge(),
+    }));
+  }
+
+  /** 任务生命周期通知：created/confirmed/started/progress/completed/handed_off/failed/cancelled。 */
+  function notify(type, job) {
+    // 插件自己建的任务不再广播 created：否则"建任务→收到 created→再建任务"会自激。
+    if (type === 'created' && job.source === 'plugin') return;
+    for (const plugin of boardPlugins()) {
+      if (typeof plugin.onJob !== 'function' || !usable(plugin)) continue;
+      try {
+        const result = plugin.onJob({ type, job, config, bridge: bridge() });
+        if (result && typeof result.then === 'function') result.catch(() => {});
+      } catch { /* 通知失败只影响这个插件自己。 */ }
+    }
+  }
+
+  function createTaskGuard() {
+    const at = Date.now();
+    while (created.length && at - created[0] >= CREATE_TASK_WINDOW_MS) created.shift();
+    if (created.length >= CREATE_TASK_LIMIT) throw new Error('插件创建任务过于频繁，请稍后再试');
+    created.push(at);
+  }
+
+  function attach({ jobs, board, themes } = {}) {
+    if (jobs) wired.jobs = jobs;
+    if (board) wired.board = board;
+    if (themes) wired.themes = themes;
+  }
+
+  return { attach, turnIn, turnOut, notify, bridge };
+}