made-bridge 0.0.0-stage → 0.2.1

package/src/agents/shared.mjs

@@ -0,0 +1,191 @@
+import fs from 'node:fs';
+import { translateKnownMessage } from '../i18n.mjs';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { findCommand, isWindows, windowsCommandLine } from '../plugin-runtime.mjs';
+
+const authenticationCache = new Map();
+
+/**
+ * 每轮任务都要带上的权限边界。CLI 助手拥有桥接器进程的权限，这条约束是设备侧
+ * 唯一的护栏，不能只在某几个适配器里各写一遍，所以统一在 runCli 里拼。
+ */
+const GUARD_INSTRUCTION = '请只修改当前仓库中的文件；不要提交、推送、发布或删除仓库。完成后说明改动与已运行的验证。';
+
+export function probeCli(command, loginArgs) {
+  // 命令查找走共享的跨平台实现：Windows 上要按 PATHEXT 补 .cmd/.exe，
+  // 且 X_OK 在那里没有意义，自己写一遍最容易漏。
+  const found = findCommand(command);
+  let authenticated = !loginArgs;
+  if (found && loginArgs) {
+    const key = `${found}:${loginArgs.join(' ')}`;
+    const cached = authenticationCache.get(key);
+    if (cached && cached.until > Date.now()) authenticated = cached.value;
+    else {
+      const check = spawnCommandSync(found, loginArgs, { encoding: 'utf8', timeout: 3000 });
+      authenticated = check.status === 0 && !/not logged in|not authenticated|login required/i.test(`${check.stdout || ''} ${check.stderr || ''}`);
+      authenticationCache.set(key, { value: authenticated, until: Date.now() + 60000 });
+    }
+  }
+  const available = Boolean(found && authenticated);
+  return { available, mode: 'local_cli', reason: available ? '' : found
+    ? `请先在本机登录 ${command}` : `本机未找到 ${command} 命令` };
+}
+
+/** 同步启动一个已解析到绝对路径的命令：.cmd/.bat 经 cmd.exe，其余直连。 */
+function spawnCommandSync(resolved, args, options) {
+  return isWindows && /\.(?:cmd|bat)$/i.test(resolved)
+    ? spawnSync(windowsCommandLine([resolved, ...args]), { ...options, shell: true })
+    : spawnSync(resolved, args, options);
+}
+
+export function gitState(cwd) {
+  const hasHead = spawnSync('git', ['rev-parse', '--verify', 'HEAD'], {
+    cwd, stdio: 'ignore', timeout: 5000,
+  }).status === 0;
+  const status = spawnSync('git', ['status', '--porcelain', '-z'], {
+    cwd, timeout: 5000, maxBuffer: 32 * 1024 * 1024,
+  });
+  const diff = spawnSync('git', hasHead
+    ? ['diff', '--no-ext-diff', '--binary', 'HEAD']
+    : ['diff', '--no-ext-diff', '--binary'], {
+    cwd, timeout: 5000, maxBuffer: 32 * 1024 * 1024,
+  });
+  const staged = hasHead ? null : spawnSync('git', ['diff', '--no-ext-diff', '--binary', '--cached'], {
+    cwd, timeout: 5000, maxBuffer: 32 * 1024 * 1024,
+  });
+  const untracked = spawnSync('git', ['ls-files', '--others', '--exclude-standard', '-z'], {
+    cwd, timeout: 5000, maxBuffer: 32 * 1024 * 1024,
+  });
+  if (status.status !== 0 || diff.status !== 0 || untracked.status !== 0 ||
+      (staged && staged.status !== 0)) {
+    throw new Error('无法检查项目改动状态');
+  }
+  const hash = createHash('sha256').update(status.stdout).update(diff.stdout);
+  if (staged) hash.update(staged.stdout);
+  for (const relative of untracked.stdout.toString('utf8').split('\0').filter(Boolean)) {
+    const filename = path.join(cwd, relative);
+    const stat = fs.lstatSync(filename);
+    hash.update(relative);
+    if (stat.isFile() && stat.size <= 4 * 1024 * 1024) hash.update(fs.readFileSync(filename));
+    else hash.update(`${stat.size}:${stat.mtimeMs}`);
+  }
+  return {
+    dirty: status.stdout.length > 0,
+    snapshot: hash.digest('hex'),
+    // 改动清单直接从上面这次 `git status --porcelain -z` 里取，收尾时不必再跑一次 git：
+    // 少一个子进程，也少一分超时风险。porcelain 的条目本身就是「 XY 路径」这种可读形状。
+    changed: status.stdout.toString('utf8').split('\0').filter(Boolean).slice(0, 40).join('\n'),
+  };
+}
+
+function repositorySnapshot(cwd) {
+  if (!fs.existsSync(cwd)) {
+    fs.mkdirSync(cwd, { recursive: true });
+    spawnSync('git', ['init'], { cwd, encoding: 'utf8', timeout: 15000 });
+  }
+  if (!fs.statSync(cwd).isDirectory()) {
+    throw new Error(`代码目录不存在：${cwd}`);
+  }
+  const repo = spawnSync('git', ['rev-parse', '--show-toplevel'], {
+    cwd, encoding: 'utf8', timeout: 5000,
+  });
+  if (repo.status !== 0) {
+    throw new Error('目标项目必须是 Git 仓库，以便查看和恢复改动');
+  }
+  const root = repo.stdout.trim();
+  if (path.resolve(root) !== path.resolve(cwd)) {
+    throw new Error('请把项目路径设为 Git 仓库根目录');
+  }
+  return gitState(cwd).snapshot;
+}
+
+/** 收尾附上本轮改了什么：有改动就列出文件，没有就明说，别让用户去猜。 */
+function changeFooter(state, message) {
+  return state.changed ? `${message('改动文件：')}\n${state.changed}` : message('没有检测到代码改动。');
+}
+
+export function runCli({ job, project, signal, onProgress, onSession, config, model }, adapter) {
+  const startingGitSnapshot = repositorySnapshot(project.path);
+  const message = (value) => translateKnownMessage(value, config.locale);
+  // 每轮都拼上权限边界：用户原文一字不改，边界文案按界面语言翻译。
+  const prompt = `${job.instruction}\n\n${message(GUARD_INSTRUCTION)}`;
+  const spec = adapter.command({ cwd: project.path, instruction: prompt, config, model, sessionId: job.sessionId });
+  return new Promise((resolve, reject) => {
+    const events = adapter.createEvents(onProgress, onSession);
+    // 命令先解析成绝对路径：Windows 上 codex/cursor 这类 CLI 实际是 .cmd，
+    // 直接 spawn 会 EINVAL；经 cmd.exe 启动，并自己把参数引号拼好。
+    const resolved = findCommand(spec.command) || spec.command;
+    const viaCmd = isWindows && /\.(?:cmd|bat)$/i.test(resolved);
+    const child = viaCmd
+      ? spawn(process.env.ComSpec || 'cmd.exe', ['/d', '/s', '/c', `"${windowsCommandLine([resolved, ...spec.args])}"`], {
+        cwd: project.path,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        windowsVerbatimArguments: true,
+        env: process.env,
+      })
+      : spawn(resolved, spec.args, {
+        cwd: project.path,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        detached: process.platform !== 'win32',
+        env: process.env,
+      });
+    let stderr = '';
+    let settled = false;
+    let timer;
+    const stop = () => {
+      if (child.pid && process.platform !== 'win32') {
+        try { process.kill(-child.pid, 'SIGTERM'); } catch { /* Already exited. */ }
+        const forceTimer = setTimeout(() => {
+          if (child.exitCode === null) {
+            try { process.kill(-child.pid, 'SIGKILL'); } catch { /* Already exited. */ }
+          }
+        }, 3000);
+        forceTimer.unref();
+      } else {
+        child.kill('SIGTERM');
+      }
+    };
+    const finish = (error, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signal.removeEventListener('abort', stop);
+      if (error) reject(error); else resolve(value);
+    };
+    signal.addEventListener('abort', stop, { once: true });
+    if (signal.aborted) stop();
+    timer = setTimeout(() => {
+      stop();
+      finish(new Error('任务运行超过 20 分钟，已停止'));
+    }, 20 * 60 * 1000);
+    child.on('error', (error) => finish(error));
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => events.write(chunk));
+    child.stderr.on('data', (chunk) => {
+      stderr = `${stderr}${chunk.toString('utf8')}`.slice(-8000);
+    });
+    child.on('close', (code) => {
+      if (settled) return;
+      try {
+      if (signal.aborted) return finish(new Error('任务已取消'));
+      const output = events.finish();
+      if (code !== 0) {
+        const classified = adapter.classifyExit?.({ job, project, stderr, output, startingGitSnapshot });
+        if (classified) return finish(classified);
+        return finish(new Error(`${adapter.label} 退出码 ${code}：${stderr.trim().slice(-300) || message(output.error || '请在电脑端检查 CLI 登录和权限设置')}`));
+      }
+      if (output.error) return finish(new Error(`${adapter.label}：${output.error}`));
+      const summary = output.hasAssistantText === false ? message(output.result) : output.result;
+      const state = gitState(project.path);
+      finish(null, {
+        status: 'completed',
+        result: `${String(summary).slice(-12000)}\n\n${changeFooter(state, message)}`,
+        gitSnapshot: state.snapshot,
+      });
+      } catch (error) { finish(error); }
+    });
+    child.stdin.end(spec.stdin || '');
+  });
+}

package/src/agents/workbuddy.mjs

@@ -0,0 +1,121 @@
+import { builtinAgentIcons } from '../agent-icons.mjs';
+import { translateKnownMessage } from '../i18n.mjs';
+async function run({ job, config, signal }) {
+  if (!config.workbuddy?.allowUnscopedDispatch || !config.workbuddyToken) {
+    throw new Error('WorkBuddy 开放平台尚未授权或未开启转交模式');
+  }
+  const response = await fetch('https://www.workbuddy.cn/openapi/v2/localassistant/message', {
+    method: 'POST',
+    signal: AbortSignal.any([signal, AbortSignal.timeout(30000)]),
+    headers: {
+      Authorization: `Bearer ${config.workbuddyToken}`,
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+    },
+    body: JSON.stringify({ content: job.instruction, msg_type: 'text' }),
+  });
+  const data = await response.json();
+  if (!response.ok || data.code !== 0) {
+    throw new Error(`WorkBuddy 转交失败：${data.msg || response.status}`);
+  }
+  return {
+    status: 'handed_off',
+    result: config.locale === 'en'
+      ? `Sent to WorkBuddy. Local message ID: ${data.data?.message_id || 'unknown'}. Continue in WorkBuddy for execution and permission requests.`
+      : `已转交给 WorkBuddy，本机消息 ID：${data.data?.message_id || '未知'}。请在 WorkBuddy 中查看后续执行与权限请求。`,
+    handoff: { cursor: data.data?.message_id || '', readState: 'retrying', replyCount: 0 },
+  };
+}
+
+async function readMessages(job, config) {
+  if (!config.workbuddyToken || !job.handoff?.cursor) return { messages: [] };
+  const url = new URL('https://www.workbuddy.cn/openapi/v2/localassistant/message');
+  url.searchParams.set('message_id', job.handoff?.cursor);
+  const response = await fetch(url, {
+    method: 'GET',
+    signal: AbortSignal.timeout(15000),
+    headers: {
+      Authorization: `Bearer ${config.workbuddyToken}`,
+      Accept: 'application/json',
+    },
+  });
+  if (response.status === 401 || response.status === 403) {
+    return { unreadable: true };
+  }
+  const data = await response.json();
+  if (!response.ok || data.code !== 0) {
+    throw new Error(`WorkBuddy 消息读取失败：${data.msg || response.status}`);
+  }
+  if (!Array.isArray(data.data?.messages)) {
+    throw new Error('WorkBuddy 消息历史格式无效');
+  }
+  return {
+    messages: data.data.messages.slice(0, 100).map((message) => ({
+      id: typeof message.message_id === 'string' ? message.message_id : '',
+      role: message.role,
+      type: message.msg_type,
+      text: Array.isArray(message.content)
+        ? message.content.filter((part) => typeof part === 'string').join('\n').slice(0, 2000)
+        : '',
+    })),
+  };
+}
+
+// Migration aliases are confined to this builtin adapter so existing state and
+// older desktop clients remain compatible without shaping the plugin protocol.
+function syncJobState(job) {
+  if (!job.handoff && job.workbuddyCursor) {
+    job.handoff = { cursor: job.workbuddyCursor, readState: job.workbuddyReadState || 'retrying', replyCount: job.workbuddyReplyCount || 0 };
+  }
+  if (!job.handoff) return;
+  job.workbuddyMessageId ||= job.handoff.cursor || '';
+  job.workbuddyCursor = job.handoff.cursor;
+  job.workbuddyReadState = job.handoff.readState;
+  job.workbuddyReplyCount = job.handoff.replyCount || 0;
+  if (job.handoffReadError) job.workbuddyReadError = job.handoffReadError;
+  else delete job.workbuddyReadError;
+}
+
+async function readUpdates({ job, config }) {
+  const localize = (value) => translateKnownMessage(value, config.locale);
+  const update = await readMessages(job, config);
+  const handoff = { ...job.handoff };
+  const additions = [];
+  if (update.unreadable) {
+    handoff.readState = 'unavailable';
+    const notice = localize('当前授权不能读取 WorkBuddy 消息；需 user.localassistant.readable 权限。请在 WorkBuddy 中查看回复。');
+    if (!job.result?.includes(notice)) additions.push(notice);
+  } else {
+    handoff.readState = 'readable';
+    for (const message of update.messages || []) {
+      if (!message.id || message.id === handoff.cursor) continue;
+      // This API is a shared stream: another user prompt makes association
+      // ambiguous, so later replies must not be attached to this handoff.
+      if (message.role === 'user') {
+        handoff.readState = 'ambiguous';
+        additions.push(localize('出现其他 WorkBuddy 用户消息；后续回复无法可靠归属此任务，请在 WorkBuddy 中查看。'));
+        break;
+      }
+      handoff.cursor = message.id;
+      if (message.role !== 'assistant') continue;
+      const reply = message.text || (message.type === 'permission'
+        ? localize('助理请求进一步确认，请在 WorkBuddy 中处理。')
+        : localize('助理有一条新消息，请在 WorkBuddy 中查看详情。'));
+      additions.push(`${localize('WorkBuddy 后续助理消息（任务关联未验证）：')}\n${reply}`);
+      handoff.replyCount = (handoff.replyCount || 0) + 1;
+    }
+  }
+  return { handoff, appendResult: additions.join('\n\n') };
+}
+
+export default {
+  apiVersion: 1, kind: 'coding-agent', id: 'workbuddy', label: 'WorkBuddy', icon: builtinAgentIcons.panda,
+  capabilities: { session: 'external_unscoped', model: false, cancel: false, progress: false },
+  probe(config) {
+    const available = Boolean(config.workbuddyToken && config.workbuddy?.allowUnscopedDispatch);
+    return { available, mode: 'dispatch_only', reason: available
+      ? '可转交任务；如获消息读取授权可回显回复，无法保证指定代码目录或撤回'
+      : '需 WorkBuddy 开放平台授权，并显式允许无项目目录保证的转交模式' };
+  },
+  run, readUpdates, syncJobState,
+};

package/src/board-link.mjs

@@ -0,0 +1,266 @@
+export const CAPABILITY_NAME = /^[a-z][a-z0-9_]{0,15}(?:\.[a-z][a-z0-9_]{0,15}){0,2}$/;
+const FIELD_KEY = /^[a-z][a-z0-9_]{0,15}$/;
+const COMMAND_ID = /^[1-9][0-9]{0,15}$/;
+const MAX_ITEMS = 32;
+const MAX_QUEUE = 8;
+const MAX_FIELDS = 6;
+const MAX_TEXT = 120;
+const MAX_PER_SECOND = 8;
+const MAX_AUDIO = 256 * 1024;
+const PLUGIN_TIMEOUT_MS = 1500;
+
+function fail(message) {
+  const error = new Error(message);
+  error.preserveMessage = true;
+  return error;
+}
+
+function readNames(list, { cadence }) {
+  if (!Array.isArray(list) || list.length > MAX_ITEMS) throw fail('能力清单无效');
+  const items = [];
+  const seen = new Set();
+  for (const item of list) {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) throw fail('能力清单无效');
+    if (typeof item.name !== 'string' || !CAPABILITY_NAME.test(item.name) || seen.has(item.name)) throw fail('能力清单无效');
+    const rate = item.cadence || 'edge';
+    if (cadence && rate !== 'edge' && rate !== 'continuous') throw fail('能力清单无效');
+    if (!cadence && item.cadence !== undefined && item.cadence !== 'edge') throw fail('能力清单无效');
+    seen.add(item.name);
+    items.push(cadence ? { name: item.name, cadence: rate } : { name: item.name });
+  }
+  return items;
+}
+
+export function parseCatalog(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) throw fail('能力清单无效');
+  return {
+    events: readNames(payload.events, { cadence: true }),
+    commands: readNames(payload.commands, { cadence: false }),
+  };
+}
+
+export function parseFields(fields) {
+  if (fields === undefined || fields === null) return {};
+  if (typeof fields !== 'object' || Array.isArray(fields)) throw fail('事件字段无效');
+  const keys = Object.keys(fields);
+  if (keys.length > MAX_FIELDS) throw fail('事件字段无效');
+  const out = {};
+  for (const key of keys) {
+    const value = fields[key];
+    if (!FIELD_KEY.test(key) || typeof value !== 'string' || Buffer.byteLength(value) > MAX_TEXT) throw fail('事件字段无效');
+    out[key] = value;
+  }
+  return out;
+}
+
+function pluginAvailable(plugin, config) {
+  try {
+    const result = plugin.probe(config);
+    return Boolean(result && typeof result === 'object' && !(result instanceof Promise) && result.available === true);
+  } catch {
+    return false;
+  }
+}
+
+function commandsFrom(plugin, result, catalog) {
+  if (!result || typeof result !== 'object' || !Array.isArray(result.commands)) return [];
+  const allowed = new Set(plugin.commands);
+  const known = new Set(catalog.commands.map((item) => item.name));
+  const commands = [];
+  for (const command of result.commands) {
+    if (!command || typeof command !== 'object' || !allowed.has(command.name) || !known.has(command.name)) continue;
+    let fields;
+    try { fields = parseFields(command.fields); } catch { continue; }
+    commands.push({ name: command.name, fields });
+  }
+  return commands;
+}
+
+function pcmWav(audio) {
+  if (!Buffer.isBuffer(audio) || audio.length < 44 || audio.length > MAX_AUDIO) return false;
+  if (audio.toString('ascii', 0, 4) !== 'RIFF' || audio.toString('ascii', 8, 12) !== 'WAVE') return false;
+  let offset = 12;
+  let format = 0;
+  let channels = 0;
+  let rate = 0;
+  let bits = 0;
+  let data = 0;
+  while (offset + 8 <= audio.length) {
+    const id = audio.toString('ascii', offset, offset + 4);
+    const size = audio.readUInt32LE(offset + 4);
+    if (id === 'fmt ' && offset + 24 <= audio.length) {
+      format = audio.readUInt16LE(offset + 8);
+      channels = audio.readUInt16LE(offset + 10);
+      rate = audio.readUInt32LE(offset + 12);
+      bits = audio.readUInt16LE(offset + 22);
+    } else if (id === 'data') data = size;
+    const step = 8 + size + (size & 1);
+    if (step > audio.length) return false;
+    offset += step;
+  }
+  return format === 1 && bits === 16 && channels >= 1 && channels <= 2 && rate >= 8000 && rate <= 48000 && data > 0;
+}
+
+function enqueueCommand(queues, audios, catalogs, seq, deviceId, command, allowed, audio) {
+  const catalog = catalogs.get(deviceId);
+  if (!catalog) throw fail('板侧尚未上报命令清单');
+  if (!command || typeof command !== 'object' || typeof command.name !== 'string' || !CAPABILITY_NAME.test(command.name)) throw fail('命令无效');
+  if (!catalog.commands.some((item) => item.name === command.name)) throw fail('命令不在板侧清单');
+  if (allowed && !allowed.has(command.name)) throw fail('插件未声明该命令');
+  const fields = parseFields(command.fields);
+  if (audio != null && command.name !== 'audio.play') throw fail('只有 audio.play 可以附带语音');
+  if (command.name === 'audio.play' && audio == null) throw fail('audio.play 需要同时附带语音');
+  if (audio != null && !pcmWav(audio)) throw fail('语音须为不超过 256KB 的 16-bit PCM WAV');
+  const queue = queues.get(deviceId) || [];
+  if (queue.length >= MAX_QUEUE) throw fail('命令队列已满');
+  if (audio != null && queue.some((item) => item.audio)) throw fail('已有一条待播放语音');
+  seq.n += 1;
+  const item = { id: String(seq.n), name: command.name, fields, audio: audio != null };
+  queue.push(item);
+  queues.set(deviceId, queue);
+  if (audio != null) audios.set(`${deviceId}\n${item.id}`, audio);
+  return { id: item.id, name: item.name, fields: { ...item.fields }, audio: item.audio };
+}
+
+async function runPlugin(plugin, context) {
+  let timer;
+  try {
+    return await Promise.race([
+      Promise.resolve(plugin.onEvent(context)),
+      new Promise((_, reject) => {
+        timer = setTimeout(() => reject(fail('插件处理超时')), PLUGIN_TIMEOUT_MS);
+      }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export function createBoardLink() {
+  const catalogs = new Map();
+  const queues = new Map();
+  const audios = new Map();
+  const hits = new Map();
+  const seq = { n: 0 };
+  const dropAudio = (deviceId, id) => audios.delete(`${deviceId}\n${id}`);
+  const enqueue = (deviceId, command, allowed, audio) => enqueueCommand(queues, audios, catalogs, seq, deviceId, command, allowed, audio);
+  return {
+    setCatalog(deviceId, payload) {
+      const catalog = parseCatalog(payload);
+      catalogs.set(deviceId, catalog);
+      const known = new Set(catalog.commands.map((item) => item.name));
+      const queue = queues.get(deviceId) || [];
+      const next = queue.filter((item) => known.has(item.name));
+      for (const item of queue) {
+        if (!next.includes(item)) dropAudio(deviceId, item.id);
+      }
+      queues.set(deviceId, next);
+      return catalog;
+    },
+    forget(deviceId) {
+      catalogs.delete(deviceId);
+      queues.delete(deviceId);
+      for (const key of [...hits.keys(), ...audios.keys()]) {
+        if (key.startsWith(`${deviceId}\n`)) {
+          hits.delete(key);
+          audios.delete(key);
+        }
+      }
+    },
+    pending(deviceId) {
+      return (queues.get(deviceId) || []).map((item) => ({
+        id: item.id, name: item.name, fields: { ...item.fields }, audio: item.audio === true,
+      }));
+    },
+    audio(deviceId, id) {
+      const wav = audios.get(`${deviceId}\n${id}`);
+      return wav ? Buffer.from(wav) : null;
+    },
+    send(deviceId, command, audio) {
+      return enqueue(deviceId, command, undefined, audio);
+    },
+    deviceIds() {
+      return [...catalogs.keys()];
+    },
+    connect(deviceId, runtime, config, bridge) {
+      if (!runtime?.boardPlugins) return;
+      for (const plugin of runtime.boardPlugins()) {
+        if (typeof plugin.onConnect !== 'function' || !pluginAvailable(plugin, config)) continue;
+        const allowed = new Set(plugin.commands);
+        const send = (command, audio) => enqueue(deviceId, command, allowed, audio);
+        try {
+          const result = plugin.onConnect({ deviceId, config, send, bridge });
+          if (result && typeof result.then === 'function') result.catch(() => {});
+        } catch {
+          /* A plugin that fails to arm must not block the catalog response. */
+        }
+      }
+    },
+    ack(deviceId, payload) {
+      if (!payload || typeof payload !== 'object' || Array.isArray(payload) || !Array.isArray(payload.ids) || payload.ids.length > MAX_QUEUE) throw fail('确认无效');
+      const drop = new Set();
+      for (const id of payload.ids) {
+        if (typeof id !== 'string' || !COMMAND_ID.test(id) || drop.has(id)) throw fail('确认无效');
+        drop.add(id);
+      }
+      const queue = queues.get(deviceId) || [];
+      const next = queue.filter((item) => !drop.has(item.id));
+      for (const id of drop) dropAudio(deviceId, id);
+      queues.set(deviceId, next);
+      return { acked: queue.length - next.length };
+    },
+    subscription(deviceId, runtime, config) {
+      const catalog = catalogs.get(deviceId);
+      if (!catalog || !runtime?.boardPlugins) return [];
+      const known = new Set(catalog.events.map((item) => item.name));
+      const wanted = [];
+      for (const plugin of runtime.boardPlugins()) {
+        if (!pluginAvailable(plugin, config)) continue;
+        for (const name of plugin.events) {
+          if (known.has(name) && !wanted.includes(name)) wanted.push(name);
+        }
+      }
+      return wanted;
+    },
+    async handleEvent(deviceId, payload, runtime, config, bridge) {
+      if (!payload || typeof payload !== 'object' || Array.isArray(payload)) throw fail('事件无效');
+      if (typeof payload.name !== 'string' || !CAPABILITY_NAME.test(payload.name)) throw fail('事件无效');
+      const fields = parseFields(payload.fields);
+      const catalog = catalogs.get(deviceId);
+      if (!catalog || !catalog.events.some((item) => item.name === payload.name)) throw fail('事件不在板侧清单');
+      const subscribed = this.subscription(deviceId, runtime, config);
+      if (!subscribed.includes(payload.name)) throw fail('事件未注册');
+      const key = `${deviceId}\n${payload.name}`;
+      const now = Date.now();
+      const recent = (hits.get(key) || []).filter((at) => now - at < 1000);
+      if (recent.length >= MAX_PER_SECOND) throw fail('事件上报过于频繁');
+      recent.push(now);
+      hits.set(key, recent);
+      const allowedFor = (plugin) => new Set(plugin.commands);
+      for (const plugin of runtime.boardPlugins()) {
+        if (!plugin.events.includes(payload.name) || !pluginAvailable(plugin, config)) continue;
+        const allowed = allowedFor(plugin);
+        let result;
+        try {
+          result = await runPlugin(plugin, {
+            event: { name: payload.name, fields },
+            config,
+            deviceId,
+            send: (command, audio) => enqueue(deviceId, command, allowed, audio),
+            bridge,
+          });
+        } catch {
+          continue;
+        }
+        for (const command of commandsFrom(plugin, result, catalog)) {
+          try {
+            enqueue(deviceId, command, allowed);
+          } catch (error) {
+            if (error.message === '命令队列已满') break;
+          }
+        }
+      }
+      return { accepted: true };
+    },
+  };
+}