made-bridge 0.3.1 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "made-bridge",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "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;
@@ -245,6 +248,9 @@ export function createBoardLink() {
       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);
+      // 设备事件一律落日志（含未订阅被拒的）：调试/烧机观察通道依赖它，
+      // 例如 burn-in 压测的水位事件 burnin.mem 就没有任何插件订阅。
+      console.log('[board-event]', deviceId.slice(-6), payload.name, JSON.stringify(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);

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

@@ -582,7 +582,9 @@ export function createApp(config, { run, transcribe, tunnel: providedTunnel, ena
             }
           }
           if (!queued) throw new Error(lastError || '命令未能下发');
-          const deadline = Date.now() + 15000;
+          // USB 分片上传 240×320 帧实测 >15s（base64 走请求通道），15s 会
+          // 误报失败——其实 PNG 随后正常落盘。放宽到 45s。
+          const deadline = Date.now() + 45000;
           while (Date.now() < deadline) {
             const file = screenshots.latest(before);
             if (file) {
@@ -599,7 +601,7 @@ export function createApp(config, { run, transcribe, tunnel: providedTunnel, ena
             }
             await new Promise((resolve) => setTimeout(resolve, 250));
           }
-          throw new Error('码得未在 15 秒内回传截图（固件需要更新到支持 debug.screenshot 的版本）');
+          throw new Error('码得未在 45 秒内回传截图（固件需要更新到支持 debug.screenshot 的版本）');
         }
         if (url.pathname === '/api/firmware') {
           const type = String(req.headers['content-type'] || '');
@@ -966,6 +968,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;
         }

package/src/usb-receiver.mjs

@@ -220,6 +220,9 @@ export class UsbReceiverProtocol {
 
   feed(chunk) {
     if (this.closed) return;
+    if (chunk.includes(0x22) && chunk.includes(0x3a) && chunk.length > 60 && !chunk.slice(0, 30).includes('hello')) {
+      console.log('[usb-raw]', chunk.length, JSON.stringify(chunk.subarray(0, 120).toString('utf8')));
+    }
     let start = 0;
     for (let index = 0; index < chunk.length; index += 1) {
       if (chunk[index] !== 10) continue;
@@ -264,7 +267,7 @@ export class UsbReceiverProtocol {
         console.error(`[usb-link] log: ${line.slice(0, 240)}`);
         return;
       }
-      console.error(`[usb-link] unparseable: ${line.slice(0, 240)}`);
+      console.error(`[usb-link] unparseable len=${line.length} tail=${JSON.stringify(line.slice(-40))}`);
       this.rejectCurrent(400, 'USB 帧格式无效');
       return;
     }
@@ -272,6 +275,9 @@ export class UsbReceiverProtocol {
       this.rejectCurrent(400, 'USB 帧格式无效');
       return;
     }
+    if (frame && typeof frame.type === 'string' && frame.type !== 'hello') {
+      console.log('[usb-frame]', frame.type, frame.id ?? '', String(frame.path || '').slice(0, 60));
+    }
     if (frame.type === 'hello') {
       if (frame.version !== 1 || ![undefined, 'receiver', 'direct'].includes(frame.mode)) return;
       const direct = frame.mode === 'direct';
@@ -285,13 +291,25 @@ export class UsbReceiverProtocol {
         ssid: direct ? '' : frame.ssid, password: direct ? '' : frame.password };
       if (this.peer && (this.peer.mode !== peer.mode || this.peer.deviceId !== peer.deviceId)) return;
       if (this.onHello(peer) === false) return;
-      console.error(`[usb-link] hello: mode=${peer.mode} ${new Date().toISOString()}`);
+      console.error(`[usb-link] hello: mode=${peer.mode} diag=${frame.diag || '-'} ${new Date().toISOString()}`);
       this.peer = peer;
       this.ackWindow = peer.mode === 'direct' ? ACK_WINDOW_DIRECT : ACK_WINDOW;
       this.helloReceived = true;
       this.onActivity();
       // The receiver waits for this acknowledgement before forwarding HTTP.
       // A USB cable being present does not mean the desktop process is ready.
+      // ready 直发不进 pendingWork：pendingWork 同时承载 writeResponse 的
+      // ack 流控等待——设备偶发丢 ack 时该链最长堵 15s，期间所有重握手
+      // 都等不到 ready，设备侧表现为连环 E263 + UI 闪「连接电脑」（实锤
+      // 于 2026-10-20 冒烟：ack TIMEOUT id=52 前后 15s 全是 1.5s 间隔握手
+      // 超时）。sendLine 走 link.writeQueue，帧原子性与 pendingWork 相同；
+      // direct 固件 read_request_frame 本就支持在响应流中处理 ready。
+      // receiver 模式保持原排队路径（ready 语义 = 桥接进程就绪）。
+      if (peer.mode === 'direct' && !this.closed) {
+        this.sendLine(JSON.stringify({ type: 'ready', version: 1, connectionId: this.connectionId }))
+          .catch(() => this.dispose());
+        return;
+      }
       const generation = this.generation;
       this.pendingWork = this.pendingWork.then(async () => {
         if (!this.closed && this.helloReceived && this.generation === generation) {
@@ -318,6 +336,7 @@ export class UsbReceiverProtocol {
       return;
     }
     if (frame.type === 'request') {
+      console.log('[usb-req]', frame.method, frame.path, 'id=' + frame.id);
       if (this.current || this.responding || !validId(frame.id)) {
         if (this.current) this.rejectCurrent(409, 'USB 请求重叠');
         return;
@@ -382,6 +401,7 @@ export class UsbReceiverProtocol {
       return;
     }
     if (frame.type === 'end') {
+      console.log('[usb-end] id=' + current.id + ' received=' + current.received + ' path=' + current.path.slice(0, 40));
       if (current.received !== current.length) {
         this.rejectCurrent(400, 'USB 请求长度不符');
         return;
@@ -392,6 +412,8 @@ export class UsbReceiverProtocol {
         try {
           if (this.closed || this.current !== current || current.controller.signal.aborted) return;
           const response = await this.forward(request, current.controller.signal);
+          console.log('[usb-resp]', response.status, request.method, request.path.slice(0, 40),
+            'body=' + (response.body ? response.body.length : -1));
           if (this.closed || this.current !== current) return;
           clearTimeout(current.timer);
           await this.writeResponse(current.id, response.status, response.contentType, response.body);
@@ -485,7 +507,7 @@ export class UsbReceiverProtocol {
         console.error(`[usb-link] ack TIMEOUT id=${id} ${new Date().toISOString()}`);
         this.ackWaiters.delete(id);
         reject(new Error('USB ACK 超时'));
-      }, 15_000);
+      }, 3_000);
       timer.unref?.();
       const check = () => {
         if ((this.ackCredits.get(id) || 0) < target) return;