made-bridge 0.3.0 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "made-bridge",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "码得（made）独立语音编程设备的电脑侧桥接器：工作台 API、设备接口、任务调度与插件运行时。一条命令启动，配合 ESP32 固件使用，源码在 github.com/jobop/made。",
   "type": "module",
   "license": "MIT",

package/src/agent-sprites.mjs

@@ -54,7 +54,7 @@ function readManifestFile(dir) {
 
 function validateManifest(raw) {
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new SpriteError('manifest 必须是对象');
-  if (Object.keys(raw).some((key) => !['version', 'canvas', 'layers', 'motion', 'emotions', 'actions'].includes(key))) {
+  if (Object.keys(raw).some((key) => !['version', 'canvas', 'layers', 'motion', 'emotions', 'actions', 'commands'].includes(key))) {
     throw new SpriteError('manifest 包含不支持的字段');
   }
   if (!isInt(raw.version, 1, 2147483647)) throw new SpriteError('manifest.version 必须是正整数');
@@ -204,9 +204,27 @@ function validateManifest(raw) {
       }
     }
   }
+  // 两级绑定模型（docs/SPRITES.md）：commands 表（可选）定义「命令绑素材」
+  // ——抽象命令号 A1–A9 → actions 表动作名，纯编号不定语义。事件绑定（增强
+  // 插件）只发命令号；声明了本表的素材只认命令号，语义名直发废弃。
+  if (raw.commands !== undefined) {
+    const commands = raw.commands;
+    if (!commands || typeof commands !== 'object' || Array.isArray(commands)) {
+      throw new SpriteError('commands 必须是对象（A1–A9 → 动作名）');
+    }
+    const keys = Object.keys(commands);
+    if (keys.length > 9) throw new SpriteError('commands 最多 9 个命令号（A1–A9）');
+    const actionNames = new Set(Object.keys(raw.actions ?? {}));
+    for (const [slot, target] of Object.entries(commands)) {
+      if (!/^A[1-9]$/.test(slot)) throw new SpriteError(`commands.${slot} 命令号必须是 A1–A9`);
+      if (typeof target !== 'string' || !actionNames.has(target)) {
+        throw new SpriteError(`commands.${slot} 映射目标必须是 actions 表已声明的动作名`);
+      }
+    }
+  }
   return {
     version: raw.version, canvas: canvas, layers: raw.layers, motion: raw.motion ?? null,
-    emotions: raw.emotions ?? null, actions: raw.actions ?? null,
+    emotions: raw.emotions ?? null, actions: raw.actions ?? null, commands: raw.commands ?? null,
   };
 }
 
@@ -299,7 +317,7 @@ export function readSprite(packageDir) {
   const value = Object.freeze({
     dir: spriteDir, version: manifest.version, canvas: manifest.canvas,
     layers: manifest.layers, motion: manifest.motion, emotions: manifest.emotions,
-    actions: manifest.actions,
+    actions: manifest.actions, commands: manifest.commands,
     files: Object.freeze(files.map((file) => Object.freeze(file))),
   });
   cache.set(spriteDir, { stamp, value });

package/src/board-link.mjs

@@ -1,4 +1,7 @@
-export const CAPABILITY_NAME = /^[a-z][a-z0-9_]{0,15}(?:\.[a-z][a-z0-9_]{0,15}){0,2}$/;
+// 能力名：段 = 字母开头的 [A-Za-z0-9_]{0,15}，1–3 段点分。大写段用于行动
+// 系统的抽象命令号（action.A1–A9，两级绑定模型 docs/SPRITES.md）；老语义
+// 动作名与事件名全小写不受影响。
+export const CAPABILITY_NAME = /^[a-zA-Z][a-zA-Z0-9_]{0,15}(?:\.[a-zA-Z][a-zA-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;

package/src/i18n.mjs

@@ -59,6 +59,8 @@ const messages = new Map([
   ['插件状态检查必须同步返回', 'The plugin status check must return synchronously'],
   ['任务已取消', 'Task cancelled'],
   ['默认编程助手未安装或已禁用', 'The default assistant is not installed or is disabled'],
+  ['这是默认编程助手，不能停用；请先在设置里把默认编程助手切换为其他助手', 'This is the default assistant and cannot be disabled; switch the default assistant to another one in settings first'],
+  ['这是默认编程助手，不能删除；请先在设置里把默认编程助手切换为其他助手', 'This is the default assistant and cannot be removed; switch the default assistant to another one in settings first'],
   ['配对请求格式无效', 'Invalid pairing request'],
   ['设备名称无效', 'Invalid device name'],
   ['电脑配对窗口未开启', 'Pairing is not open on the computer'],

package/src/installed.mjs

@@ -189,6 +189,12 @@ export async function setPluginEnabled(config, id, enabled) {
   if (!PLUGIN_ID.test(id || '')) throw fail('插件不存在');
   const installed = (await listInstalled(config)).plugins;
   if (!installed.some((plugin) => plugin.id === id)) throw fail('插件不存在');
+  // 默认编程助手不能停用：loadConfiguredPlugins 会守卫 defaultProvider，
+  // 但那里的报错不含操作指引，用户只会看到一句没头没尾的「未安装或已禁用」。
+  // 在动作入口给出可操作的前置报错。
+  if (!enabled && id === config.defaultProvider) {
+    throw fail('这是默认编程助手，不能停用；请先在设置里把默认编程助手切换为其他助手');
+  }
   const previous = [...(config.disabledPlugins || [])];
   const next = new Set(previous);
   if (enabled) next.delete(id);
@@ -246,6 +252,11 @@ export async function removePlugin(config, { id = '', file = '' } = {}) {
   target = removalTarget(config, target);
   const described = await describeModule(target, config);
   const ids = described.map((plugin) => plugin.id).filter((item) => PLUGIN_ID.test(item));
+  // 同 setPluginEnabled：删默认助手会被 defaultProvider 守卫拦下但报错没有指引，
+  // 在动作入口就说清楚（2026-10-18 实锤：删除 codex 后桥接器重启都起不来）。
+  if (ids.includes(config.defaultProvider)) {
+    throw fail('这是默认编程助手，不能删除；请先在设置里把默认编程助手切换为其他助手');
+  }
   const previousDisabled = [...(config.disabledPlugins || [])];
   const previousPlugins = [...(config.plugins || [])];
   config.disabledPlugins = [...new Set([...previousDisabled, ...ids])];

package/src/plugins/contracts.d.ts

@@ -159,7 +159,7 @@ export interface BridgeFacade {
   cancelJob(id: string): Record<string, unknown>;
   themes(): { name: string; title: string; sound: boolean; icon: boolean; background: boolean }[];
   devices(): string[];
-  /** Action system: action names derived from the device command catalog (`action.<name>` entries, decided by the current assistant sprite). Advisory only — the board silently ignores unknown action commands. */
+  /** Action system: command names derived from the device command catalog (`action.<name>` entries). Two-level binding model (docs/SPRITES.md): sprites declaring a `commands` map expose abstract slots `action.A1`–`action.A9` ("command binds artwork", decided by the sprite author); legacy sprites expose semantic action names (deprecated). Advisory only — the board silently ignores unknown action commands. */
   deviceActions(deviceId: string): string[];
   /** Enqueue a board command directly; only the board-side catalog constrains the name. */
   send(deviceId: string, command: BoardCommand, audio?: Uint8Array): QueuedBoardCommand;

package/src/plugins/registry.mjs

@@ -33,7 +33,9 @@ export function validatePlugin(plugin) {
   } else if (plugin.kind === 'board-plugin') {
     const names = (key, min) => {
       const list = plugin[key];
-      if (!Array.isArray(list) || list.length > 16 || list.length < min || list.some((name) => typeof name !== 'string' || !/^[a-z][a-z0-9_]{0,15}(?:\.[a-z][a-z0-9_]{0,15}){0,2}$/.test(name))) fail(`${key} 无效`);
+      // 能力名与桥接器 CAPABILITY_NAME 同形（字母开头的段，1–3 段点分）；
+      // 大写段用于行动系统的抽象命令号（action.A1–A9，docs/SPRITES.md）。
+      if (!Array.isArray(list) || list.length > 16 || list.length < min || list.some((name) => typeof name !== 'string' || !/^[a-zA-Z][a-zA-Z0-9_]{0,15}(?:\.[a-zA-Z][a-zA-Z0-9_]{0,15}){0,2}$/.test(name))) fail(`${key} 无效`);
       if (new Set(list).size !== list.length) fail(`${key} 有重复项`);
     };
     names('events', 1);

package/src/server.mjs

@@ -807,7 +807,7 @@ export function createApp(config, { run, transcribe, tunnel: providedTunnel, ena
         return;
       }
       if (req.method === 'GET' && url.pathname === '/device/heartbeat') {
-        console.error(`[trace] hb upMs=${url.searchParams.get('upMs') ?? '-'} wifiReason=${url.searchParams.get('wifiReason') ?? '-'} wifiDrops=${url.searchParams.get('wifiDrops') ?? '-'} fwStage=${url.searchParams.get('fwStage') ?? '-'} fwWhy=${url.searchParams.get('fwWhy') ?? '-'} fwResult=${url.searchParams.get('fwResult') ?? '-'} fwWritten=${url.searchParams.get('fwWritten') ?? '-'} fwSize=${url.searchParams.get('fwSize') ?? '-'} fwHttp=${url.searchParams.get('fwHttp') ?? '-'} fwTasks=${url.searchParams.get('fwTasks') ?? '-'} fwTask=${url.searchParams.get('fwTask') ?? '-'} ${new Date().toISOString()}`);
+        console.error(`[trace] hb upMs=${url.searchParams.get('upMs') ?? '-'} wifiReason=${url.searchParams.get('wifiReason') ?? '-'} wifiDrops=${url.searchParams.get('wifiDrops') ?? '-'} wifiSelf=${url.searchParams.get('wifiSelf') ?? '-'} wifiHist=${url.searchParams.get('wifiHist') ?? '-'} heap=${url.searchParams.get('heap') ?? '-'} minHeap=${url.searchParams.get('minHeap') ?? '-'} psram=${url.searchParams.get('psram') ?? '-'} psramMin=${url.searchParams.get('psramMin') ?? '-'} fwStage=${url.searchParams.get('fwStage') ?? '-'} fwWhy=${url.searchParams.get('fwWhy') ?? '-'} fwResult=${url.searchParams.get('fwResult') ?? '-'} fwWritten=${url.searchParams.get('fwWritten') ?? '-'} fwSize=${url.searchParams.get('fwSize') ?? '-'} fwHttp=${url.searchParams.get('fwHttp') ?? '-'} fwTasks=${url.searchParams.get('fwTasks') ?? '-'} fwTask=${url.searchParams.get('fwTask') ?? '-'} ${new Date().toISOString()}`);
         if (process.env.VIBE_UI_DIAGNOSTICS === '1') {
           const fields = Object.fromEntries(['uiStage', 'uiAge', 'bootAge', 'exit', 'provider', 'displayStage', 'displayCount']
             .map((key) => [key, url.searchParams.get(key)])
@@ -930,7 +930,11 @@ export function createApp(config, { run, transcribe, tunnel: providedTunnel, ena
           projects: config.projects.filter(({ id }) => id === config.defaultProject).map(({ id, label }) => ({ id, label: devicePreview(label, 64) })),
           defaultProject: config.defaultProject,
           voice: { mode: voice.mode, available: voice.available },
-          firmwareUrl: firmwareSummary.otaUrl,
+          // 只有固件仓库里存在已导入的当前包（有 sha/版本）才 advertise OTA：
+          // 只配了 otaUrl 却没传固件时，设备会拿到无 sha 的 url → 永远 nomark
+          // → 弹更新确认 → waiting_confirmation 任务常驻 → 素材 preload 被门禁
+          // 拦死（GIF 动作等新文件永远下载不到）。
+          firmwareUrl: firmwareSummary.current ? firmwareSummary.otaUrl : '',
           firmwareVersion: firmwareSummary.current?.version || '',
           firmwareSha256: firmwareSummary.current?.sha256 || '',
           firmwareSize: firmwareSummary.current?.size || 0,
@@ -946,8 +950,10 @@ export function createApp(config, { run, transcribe, tunnel: providedTunnel, ena
         return;
       }
       // 形象素材分片拉取：单次 ≤192KB，兼容 USB 帧转发 256KB 上限（docs/SPRITES.md）。
+      // 扩展名含 .gif：GIF 动作素材（actions[].gif）也在 files 清单里，路由
+      // 只放行 .png 的话设备永远拉不到，playAction 报 gif_unavailable。
       const spriteMatch = req.method === 'GET' &&
-        url.pathname.match(/^\/device\/sprite\/([a-z0-9][a-z0-9_-]{0,39})\/([A-Za-z0-9_-]+\.png|manifest\.json)$/);
+        url.pathname.match(/^\/device\/sprite\/([a-z0-9][a-z0-9_-]{0,39})\/([A-Za-z0-9_-]+\.(?:png|gif)|manifest\.json)$/);
       if (spriteMatch) {
         const plugin = config.pluginsRuntime.agent(spriteMatch[1]);
         if (spriteMatch[2] === 'manifest.json') {
@@ -960,6 +966,7 @@ export function createApp(config, { run, transcribe, tunnel: providedTunnel, ena
             layers: plugin.sprite.layers, ...(plugin.sprite.motion ? { motion: plugin.sprite.motion } : {}),
             ...(plugin.sprite.emotions ? { emotions: plugin.sprite.emotions } : {}),
             ...(plugin.sprite.actions ? { actions: plugin.sprite.actions } : {}),
+            ...(plugin.sprite.commands ? { commands: plugin.sprite.commands } : {}),
           });
           return;
         }