made-bridge 0.3.1 → 0.3.2

package/package.json

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

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/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

@@ -966,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;
         }