made-bridge 0.2.1 → 0.2.2

package/config.example.json

@@ -4,6 +4,8 @@
   "defaultProject": "demo",
   "defaultProvider": "codex",
   "codexModel": "gpt-6-astra",
+  "stuckIdleMinutes": 5,
+  "maxAutoRetries": 1,
   "projects": [
     {
       "id": "demo",

package/package.json

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

package/src/agent-sprites.mjs

@@ -0,0 +1,206 @@
+/**
+ * Agent 形象素材（sprite/）读取与校验。
+ *
+ * 规范真源是主仓库 docs/SPRITES.md：agent 插件包可选携带 sprite/ 目录
+ * （manifest.json + 分层 PNG），桥接器把素材清单暴露给码得，素材本体走
+ * /device/sprite 分片拉取端点（单次 ≤192KB，兼容 USB 帧转发 256KB 上限）。
+ *
+ * 这里只做「读、验、切片」：不改素材、不缓存像素。清单结果按目录 mtime
+ * 缓存，避免每次 /device/config 都重算哈希。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+
+export const SPRITE_MAX_TOTAL_BYTES = 512 * 1024;
+export const SPRITE_MAX_CHUNK = 192 * 1024;
+export const SPRITE_MAX_FILE_BYTES = 256 * 1024;
+const MANIFEST_MAX_BYTES = 16 * 1024;
+const MAX_LAYERS = 8;
+const MAX_FRAMES = 4;
+// ≤20 字符：固件 SPIFFS 缓存对象名 = '/' + "s<hash6>_" + 文件名 + "~"，
+// 而 SPIFFS 只给 31 字节，20 是留了 1 字节余量的上限。
+const FILE_NAME = /^[A-Za-z0-9_-]{1,16}\.png$/i;
+const LAYER_ID = /^[A-Za-z][A-Za-z0-9_]{0,15}$/;
+const RESERVED_IDS = new Set(['__proto__', 'constructor', 'prototype']);
+
+class SpriteError extends Error {
+  constructor(message) {
+    super(message);
+    this.preserveMessage = true;
+  }
+}
+
+const isInt = (value, min, max) => Number.isInteger(value) && value >= min && value <= max;
+
+function readManifestFile(dir) {
+  const file = path.join(dir, 'manifest.json');
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch {
+    return null; // 包没带 sprite/ —— 合法，用固件兜底形象。
+  }
+  if (Buffer.byteLength(text) > MANIFEST_MAX_BYTES) throw new SpriteError('sprite/manifest.json 超过 16 KB');
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new SpriteError('sprite/manifest.json 不是合法 JSON');
+  }
+}
+
+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'].includes(key))) {
+    throw new SpriteError('manifest 包含不支持的字段');
+  }
+  if (!isInt(raw.version, 1, 2147483647)) throw new SpriteError('manifest.version 必须是正整数');
+  const canvas = raw.canvas;
+  if (!canvas || typeof canvas !== 'object' || Array.isArray(canvas) ||
+      !isInt(canvas.w, 1, 512) || !isInt(canvas.h, 1, 512) ||
+      Object.keys(canvas).some((key) => !['w', 'h'].includes(key))) {
+    throw new SpriteError('manifest.canvas 必须是 {w, h}（各 1–512）');
+  }
+  if (!Array.isArray(raw.layers) || raw.layers.length < 1 || raw.layers.length > MAX_LAYERS) {
+    throw new SpriteError(`manifest.layers 需要 1–${MAX_LAYERS} 层`);
+  }
+  const seen = new Set();
+  const referenced = new Set();
+  for (const layer of raw.layers) {
+    if (!layer || typeof layer !== 'object' || Array.isArray(layer)) throw new SpriteError('layers 条目必须是对象');
+    const keys = Object.keys(layer);
+    if (keys.some((key) => !['id', 'file', 'frames', 'x', 'y', 'z', 'blink', 'talk', 'alert'].includes(key))) {
+      throw new SpriteError(`层 ${layer.id || '?'} 包含不支持的字段`);
+    }
+    if (typeof layer.id !== 'string' || !LAYER_ID.test(layer.id) || RESERVED_IDS.has(layer.id) || seen.has(layer.id)) {
+      throw new SpriteError('层 id 必须是 1–16 位字母开头的唯一标识');
+    }
+    seen.add(layer.id);
+    const files = layer.frames !== undefined ? layer.frames : [layer.file];
+    if (!Array.isArray(files) || files.length < 1 || files.length > MAX_FRAMES ||
+        files.some((file) => typeof file !== 'string' || !FILE_NAME.test(file))) {
+      throw new SpriteError(`层 ${layer.id} 需要单帧 file 或 1–${MAX_FRAMES} 帧 frames（PNG 文件名）`);
+    }
+    for (const file of files) {
+      if (referenced.has(file)) throw new SpriteError(`素材文件被多层引用：${file}`);
+      referenced.add(file);
+    }
+    if (!isInt(layer.x, 0, canvas.w) || !isInt(layer.y, 0, canvas.h) || !isInt(layer.z, 0, 100)) {
+      throw new SpriteError(`层 ${layer.id} 的 x/y/z 超出画布或范围`);
+    }
+    if (layer.blink !== undefined) {
+      const blink = layer.blink;
+      if (!blink || typeof blink !== 'object' || Array.isArray(blink) ||
+          !isInt(blink.period_ms, 200, 60000) || !isInt(blink.closed_ms, 20, 2000) ||
+          Object.keys(blink).some((key) => !['period_ms', 'closed_ms'].includes(key))) {
+        throw new SpriteError(`层 ${layer.id} 的 blink 必须是 {period_ms, closed_ms}`);
+      }
+    }
+    if (layer.talk !== undefined && typeof layer.talk !== 'boolean') {
+      throw new SpriteError(`层 ${layer.id} 的 talk 必须是布尔值`);
+    }
+    if (layer.alert !== undefined && layer.alert !== 'pulse') {
+      throw new SpriteError(`层 ${layer.id} 的 alert 只支持 "pulse"`);
+    }
+  }
+  if (raw.motion !== undefined) {
+    const motion = raw.motion;
+    if (!motion || typeof motion !== 'object' || Array.isArray(motion)) throw new SpriteError('motion 必须是对象');
+    const keys = Object.keys(motion);
+    if (keys.some((key) => !['breath', 'sway_deg', 'sway_period_ms'].includes(key))) {
+      throw new SpriteError('motion 包含不支持的字段');
+    }
+    if (motion.breath !== undefined) {
+      const breath = motion.breath;
+      if (!breath || typeof breath !== 'object' || Array.isArray(breath) ||
+          !isInt(breath.scale_pct, 100, 120) || !isInt(breath.period_ms, 500, 10000) ||
+          Object.keys(breath).some((key) => !['scale_pct', 'period_ms'].includes(key))) {
+        throw new SpriteError('motion.breath 必须是 {scale_pct, period_ms}');
+      }
+    }
+    if (motion.sway_deg !== undefined && !isInt(motion.sway_deg, 0, 15)) throw new SpriteError('motion.sway_deg 范围 0–15');
+    if (motion.sway_period_ms !== undefined && !isInt(motion.sway_period_ms, 200, 10000)) {
+      throw new SpriteError('motion.sway_period_ms 范围 200–10000');
+    }
+  }
+  return { version: raw.version, canvas: canvas, layers: raw.layers, motion: raw.motion ?? null };
+}
+
+/** 按目录内容 mtime 缓存读取结果；素材被替换时自动失效。
+ * 键要覆盖目录内每个文件：原地覆盖文件不会更新目录自身的 mtime。 */
+const cache = new Map();
+
+function spriteStamp(spriteDir) {
+  let stamp;
+  try {
+    stamp = `${fs.statSync(spriteDir).mtimeMs}`;
+    for (const name of fs.readdirSync(spriteDir).sort()) {
+      stamp += `|${name}:${fs.statSync(path.join(spriteDir, name)).mtimeMs}`;
+    }
+  } catch {
+    return null;
+  }
+  return stamp;
+}
+
+/**
+ * 读取并校验一个插件包的 sprite/ 目录。
+ * @returns 清单对象（含每个文件的 bytes/sha256）；包没带 sprite/ 时返回 null；
+ *          manifest 或素材不合法时抛错（调用方决定是拒绝加载还是降级兜底）。
+ */
+export function readSprite(packageDir) {
+  const spriteDir = path.join(packageDir, 'sprite');
+  const stamp = spriteStamp(spriteDir);
+  if (!stamp) return null; // 目录不存在：没有素材，合法。
+  const hit = cache.get(spriteDir);
+  if (hit && hit.stamp === stamp) return hit.value;
+  const raw = readManifestFile(spriteDir);
+  if (!raw) return null;
+  const manifest = validateManifest(raw);
+  // 引用完整性：目录里的 PNG 必须全部被 manifest 引用，帮开发者抓住文件名拼写错误。
+  for (const name of fs.readdirSync(spriteDir)) {
+    if (!name.toLowerCase().endsWith('.png')) continue;
+    const referenced = manifest.layers.some((layer) =>
+      (layer.frames !== undefined ? layer.frames : [layer.file]).includes(name));
+    if (!referenced) throw new SpriteError(`sprite/${name} 未被 manifest 引用`);
+  }
+  let total = 0;
+  const files = [];
+  for (const layer of manifest.layers) {
+    for (const file of layer.frames !== undefined ? layer.frames : [layer.file]) {
+      const target = path.join(spriteDir, file);
+      let bytes;
+      try {
+        bytes = fs.statSync(target).size;
+      } catch {
+        throw new SpriteError(`manifest 引用的素材不存在：sprite/${file}`);
+      }
+      if (bytes > SPRITE_MAX_FILE_BYTES) throw new SpriteError(`素材单文件超过 256 KB：${file}`);
+      total += bytes;
+      if (total > SPRITE_MAX_TOTAL_BYTES) throw new SpriteError(`sprite/ 整包超过 512 KB`);
+      const data = fs.readFileSync(target);
+      files.push({ file, bytes, sha256: createHash('sha256').update(data).digest('hex') });
+    }
+  }
+  const value = Object.freeze({
+    dir: spriteDir, version: manifest.version, canvas: manifest.canvas,
+    layers: manifest.layers, motion: manifest.motion,
+    files: Object.freeze(files.map((file) => Object.freeze(file))),
+  });
+  cache.set(spriteDir, { stamp, value });
+  return value;
+}
+
+/**
+ * 从已校验的 sprite 目录切一片文件数据。越界与超长都会收敛到合法范围，
+ * 返回空 Buffer 表示 offset 已到文件尾（调用方据此判断下载完成）。
+ */
+export function spriteChunk(sprite, file, offset, length) {
+  const entry = sprite?.files?.find((item) => item.file === file);
+  if (!entry) return null;
+  const start = Math.max(0, Math.min(Math.trunc(offset) || 0, entry.bytes));
+  const wanted = length === undefined || length === null ? SPRITE_MAX_CHUNK : Math.trunc(length) || 0;
+  const end = Math.min(entry.bytes, start + Math.max(1, Math.min(wanted, SPRITE_MAX_CHUNK)));
+  const data = fs.readFileSync(path.join(sprite.dir, file));
+  return data.subarray(start, end);
+}

package/src/agents/shared.mjs

@@ -134,6 +134,22 @@ export function runCli({ job, project, signal, onProgress, onSession, config, mo
     let stderr = '';
     let settled = false;
     let timer;
+    // 卡死看门狗：编程工具进程连续 idleMs 没有任何输出（进度、流式、stderr 都算）
+    // 视为卡死，杀掉进程树并把错误标记为可自动重跑，由任务车道决定是否重试。
+    const idleMs = Number(config?.stuckIdleMs)
+      || Math.max(1, Number(config?.stuckIdleMinutes) || 5) * 60 * 1000;
+    let idleTimer;
+    const bumpIdle = () => {
+      clearTimeout(idleTimer);
+      idleTimer = setTimeout(() => {
+        stop();
+        const error = new Error(`任务 ${Math.round(idleMs / 60000)} 分钟没有任何输出，疑似卡死：已终止编程工具进程`);
+        error.retryable = true;
+        error.autoRetry = true;
+        finish(error);
+      }, idleMs);
+      if (idleTimer.unref) idleTimer.unref();
+    };
     const stop = () => {
       if (child.pid && process.platform !== 'win32') {
         try { process.kill(-child.pid, 'SIGTERM'); } catch { /* Already exited. */ }
@@ -151,19 +167,28 @@ export function runCli({ job, project, signal, onProgress, onSession, config, mo
       if (settled) return;
       settled = true;
       clearTimeout(timer);
+      clearTimeout(idleTimer);
       signal.removeEventListener('abort', stop);
       if (error) reject(error); else resolve(value);
     };
     signal.addEventListener('abort', stop, { once: true });
     if (signal.aborted) stop();
+    bumpIdle();
     timer = setTimeout(() => {
       stop();
-      finish(new Error('任务运行超过 20 分钟，已停止'));
+      const error = new Error('任务运行超过 20 分钟，已停止');
+      error.retryable = true;
+      error.autoRetry = true;
+      finish(error);
     }, 20 * 60 * 1000);
     child.on('error', (error) => finish(error));
     child.stdout.setEncoding('utf8');
-    child.stdout.on('data', (chunk) => events.write(chunk));
+    child.stdout.on('data', (chunk) => {
+      bumpIdle();
+      events.write(chunk);
+    });
     child.stderr.on('data', (chunk) => {
+      bumpIdle();
       stderr = `${stderr}${chunk.toString('utf8')}`.slice(-8000);
     });
     child.on('close', (code) => {

package/src/board-link.mjs

@@ -182,6 +182,9 @@ export function createBoardLink() {
     deviceIds() {
       return [...catalogs.keys()];
     },
+    hasCatalog(deviceId) {
+      return catalogs.has(deviceId);
+    },
     connect(deviceId, runtime, config, bridge) {
       if (!runtime?.boardPlugins) return;
       for (const plugin of runtime.boardPlugins()) {

package/src/board-screenshot.mjs

@@ -0,0 +1,132 @@
+// 板端截屏：固件把当前 LVGL 画面以 RGB565 裸帧 POST 上来，这里转 PNG 落盘。
+// 触发端走桌面本地 API（POST /api/screenshot），向设备队列塞 debug.screenshot 命令。
+// 仅调试用途：命令在固件能力清单里声明（esp_brookesia_app_vibe.cpp announceBoardCatalog）。
+import fs from 'node:fs';
+import path from 'node:path';
+import zlib from 'node:zlib';
+
+const MAX_WIDTH = 1024;
+const MAX_HEIGHT = 1024;
+const MAX_UPLOAD = 2 * 1024 * 1024;
+const KEEP_FILES = 20;
+
+const crcTable = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n += 1) {
+    let c = n;
+    for (let k = 0; k < 8; k += 1) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+function crc32(buffer) {
+  let crc = 0xffffffff;
+  for (const byte of buffer) crc = crcTable[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+function chunk(type, data) {
+  const length = Buffer.alloc(4);
+  length.writeUInt32BE(data.length, 0);
+  const typeBuffer = Buffer.from(type, 'ascii');
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(Buffer.concat([typeBuffer, data])), 0);
+  return Buffer.concat([length, typeBuffer, data, crc]);
+}
+
+// LVGL RGB565 小端：低字节 GGGBBBBB，高字节 RRRRRGGG；stride 为每行字节数（可能含行尾填充）。
+export function rgb565ToPng(width, height, rgb565, stride = width * 2) {
+  if (!Number.isInteger(width) || width < 16 || width > MAX_WIDTH) throw new Error('宽度无效');
+  if (!Number.isInteger(height) || height < 16 || height > MAX_HEIGHT) throw new Error('高度无效');
+  if (!Buffer.isBuffer(rgb565)) throw new Error('像素数据无效');
+  if (!Number.isInteger(stride) || stride < width * 2 || stride > MAX_WIDTH * 4) throw new Error('行距无效');
+  const expected = stride * height;
+  if (rgb565.length !== expected) throw new Error(`数据长度不符：期望 ${expected} 字节，实得 ${rgb565.length}`);
+  const raw = Buffer.alloc(height * (1 + width * 3));
+  let out = 0;
+  for (let y = 0; y < height; y += 1) {
+    raw[out] = 0; // filter: none
+    out += 1;
+    const row = y * stride;
+    for (let x = 0; x < width; x += 1) {
+      const value = rgb565.readUInt16LE(row + x * 2);
+      const r5 = (value >> 11) & 0x1f;
+      const g6 = (value >> 5) & 0x3f;
+      const b5 = value & 0x1f;
+      raw[out] = (r5 << 3) | (r5 >> 2);
+      raw[out + 1] = (g6 << 2) | (g6 >> 4);
+      raw[out + 2] = (b5 << 3) | (b5 >> 2);
+      out += 3;
+    }
+  }
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8; // bit depth
+  ihdr[9] = 2; // color type: truecolor RGB
+  const signature = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+  return Buffer.concat([
+    signature,
+    chunk('IHDR', ihdr),
+    chunk('IDAT', zlib.deflateSync(raw, { level: 6 })),
+    chunk('IEND', Buffer.alloc(0)),
+  ]);
+}
+
+export function validateScreenshotParams(query) {
+  const width = Number(query.get('w'));
+  const height = Number(query.get('h'));
+  const stride = query.has('stride') ? Number(query.get('stride')) : width * 2;
+  if (!Number.isInteger(width) || width < 16 || width > MAX_WIDTH) throw new Error('宽度无效');
+  if (!Number.isInteger(height) || height < 16 || height > MAX_HEIGHT) throw new Error('高度无效');
+  if (!Number.isInteger(stride) || stride < width * 2 || stride > MAX_WIDTH * 4) throw new Error('行距无效');
+  if ((query.get('fmt') || 'rgb565') !== 'rgb565') throw new Error('仅支持 rgb565 像素格式');
+  return { width, height, stride };
+}
+
+export function createScreenshotStore(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  const sanitize = (deviceId) => String(deviceId).replace(/[^0-9a-f-]/gi, '').slice(0, 40) || 'unknown';
+  const prune = () => {
+    const files = fs.readdirSync(dir).filter((f) => f.endsWith('.png')).sort();
+    for (const stale of files.slice(0, Math.max(0, files.length - KEEP_FILES))) {
+      try { fs.unlinkSync(path.join(dir, stale)); } catch { /* 并发清理可忽略 */ }
+    }
+  };
+  return {
+    save(deviceId, png) {
+      const stamp = Date.now();
+      const dev = sanitize(deviceId);
+      // 同毫秒多次保存不得互相覆盖（连拍/快速重试会撞毫秒，曾有测试因
+      // 27 次保存挤在几个毫秒里而假失败，实机连拍也会丢图）。
+      let name = `${stamp}-${dev}.png`;
+      for (let n = 1; fs.existsSync(path.join(dir, name)); n += 1) {
+        name = `${stamp}-${dev}-${n}.png`;
+      }
+      const file = path.join(dir, name);
+      fs.writeFileSync(file, png);
+      prune();
+      return file;
+    },
+    latest(afterMs) {
+      let best = null;
+      let bestTime = 0;
+      for (const name of fs.readdirSync(dir)) {
+        if (!name.endsWith('.png')) continue;
+        const stamp = Number(name.split('-')[0]);
+        if (!Number.isFinite(stamp) || stamp < afterMs) continue;
+        const file = path.join(dir, name);
+        let mtime = 0;
+        try { mtime = fs.statSync(file).mtimeMs; } catch { continue; }
+        if (mtime > bestTime) {
+          best = file;
+          bestTime = mtime;
+        }
+      }
+      return best;
+    },
+  };
+}
+
+export { MAX_UPLOAD };

package/src/config.mjs

@@ -133,7 +133,9 @@ export function loadConfig(env = process.env) {
   }
   const port = Number(raw.port || 8787);
   const devicePort = Number(raw.devicePort || 8788);
-  if (![port, devicePort].every((p) => Number.isInteger(p) && p > 0 && p < 65536)) {
+  // UDP 发现端口：默认与官方端口一致；跑第二个实例（开发/测试）时必须错开。
+  const discoveryPort = Number(env.VIBE_DISCOVERY_PORT || raw.discoveryPort || 8789);
+  if (![port, devicePort, discoveryPort].every((p) => Number.isInteger(p) && p > 0 && p < 65536)) {
     throw new Error('端口号必须在 1 到 65535 之间');
   }
   // 同时执行的会话数。同一会话恒为串行（编程工具按会话线程加写锁，并行必然冲突），
@@ -142,6 +144,16 @@ export function loadConfig(env = process.env) {
   if (!Number.isInteger(maxParallelJobs) || maxParallelJobs < 1 || maxParallelJobs > 4) {
     throw new Error('并行任务数必须是 1 到 4 之间的整数');
   }
+  // 卡死自愈：任务连续 N 分钟没有任何输出（进度/流式/stderr 都算）视为卡死，
+  // 桥接器杀掉编程工具进程并自动重跑，最多 maxAutoRetries 次。
+  const stuckIdleMinutes = Number(env.VIBE_STUCK_IDLE_MINUTES ?? raw.stuckIdleMinutes ?? 5);
+  if (!Number.isInteger(stuckIdleMinutes) || stuckIdleMinutes < 1 || stuckIdleMinutes > 60) {
+    throw new Error('卡死判定时长必须是 1 到 60 之间的整数（分钟）');
+  }
+  const maxAutoRetries = Number(env.VIBE_MAX_AUTO_RETRIES ?? raw.maxAutoRetries ?? 1);
+  if (!Number.isInteger(maxAutoRetries) || maxAutoRetries < 0 || maxAutoRetries > 3) {
+    throw new Error('卡死自动重跑次数必须是 0 到 3 之间的整数');
+  }
   const stateDir = path.resolve(env.VIBE_STATE_DIR
     || (hasUserConfig ? path.join(path.dirname(configPath), 'state') : dataHome(env)));
   const usbPort = validateUsbPort(env.VIBE_USB_PORT || '');
@@ -172,7 +184,10 @@ export function loadConfig(env = process.env) {
     defaultProvider,
     port,
     devicePort,
+    discoveryPort,
     maxParallelJobs,
+    stuckIdleMinutes,
+    maxAutoRetries,
     codexModel: models.codex,
     models,
     asrMode,

package/src/jobs.mjs

@@ -11,7 +11,7 @@ function now() {
 }
 
 export class JobStore {
-  constructor({ file, projects, defaultProject, defaultProvider, workspaceRoot, maxParallel, run, providerAvailable, pluginsRuntime, hooks }) {
+  constructor({ file, projects, defaultProject, defaultProvider, workspaceRoot, maxParallel, maxAutoRetries, run, providerAvailable, pluginsRuntime, hooks }) {
     this.agent = pluginsRuntime ? (id) => pluginsRuntime.agent(id) : run.agent || builtinAgent;
     this.hooks = hooks || null;
     this.file = file;
@@ -24,6 +24,9 @@ export class JobStore {
     // 同时执行的会话数。缺省 1 = 完全串行（保持既有语义，便于测试与降级）。
     const lanes = Number(maxParallel);
     this.maxParallel = Number.isFinite(lanes) ? Math.min(Math.max(Math.trunc(lanes), 1), 4) : 1;
+    // 卡死自愈：看门狗杀掉无输出的编程工具进程后，同车道自动重跑的次数上限。
+    const retries = Number(maxAutoRetries);
+    this.maxAutoRetries = Number.isFinite(retries) ? Math.min(Math.max(Math.trunc(retries), 0), 3) : 1;
     // 正在占用车道的会话 ID。一个会话同时只会有一条指令在跑，所以按会话占位即可。
     this.lanes = new Set();
     this.sessions = new SessionStore({
@@ -344,6 +347,20 @@ export class JobStore {
           }
         } catch (error) {
           if (job.status === 'running') {
+            // 卡死自愈：看门狗杀掉无输出的编程工具进程后，同车道自动重跑，
+            // 最多 maxAutoRetries 次；重跑的是同一条指令（native 会话会 resume 同一 CLI 线程）。
+            const attempts = job.attempts || 0;
+            if (error?.autoRetry && attempts < this.maxAutoRetries) {
+              job.attempts = attempts + 1;
+              job.status = 'queued';
+              job.progress = '任务疑似卡死，已终止编程工具进程并自动重跑';
+              job.progressAt = now();
+              job.error = '';
+              job.updatedAt = now();
+              this.save();
+              this.hooks?.notify('retrying', job);
+              continue;
+            }
             const retryableConflict = error?.retryable === true;
             job.status = retryableConflict ? 'waiting_confirmation' : 'failed';
             job.retryPending = retryableConflict;

package/src/plugins/registry.mjs

@@ -6,6 +6,7 @@ import { isPackageEntry, packageDirectories, readPackageSettings } from '../plug
 import { MODEL_ID } from '../model-settings.mjs';
 import { builtinAgents } from '../agents/index.mjs';
 import { normalizeAgentIcon } from '../agent-icons.mjs';
+import { readSprite } from '../agent-sprites.mjs';
 import { builtinSpeechRecognizers } from '../speech/index.mjs';
 
 export const PLUGIN_API_VERSION = 1;
@@ -95,8 +96,16 @@ export async function loadConfiguredPlugins(config) {
     const exported = (await import(pathToFileURL(filename).href)).default;
     const bundle = Array.isArray(exported) ? exported : [exported];
     const pack = isPackageEntry(filename) ? readPackageSettings(path.dirname(filename)) : null;
+    const packageDir = isPackageEntry(filename) ? path.dirname(filename) : null;
     for (const p of bundle) {
       validatePlugin(p);
+      // 素材挂包目录：sprite/ 校验失败只降级（该助手用固件兜底形象），不阻断插件加载。
+      if (packageDir && p.kind === 'coding-agent') {
+        try { p.sprite = readSprite(packageDir) || undefined; } catch (error) {
+          console.warn(`插件 ${p.id}：${error.message}，改用内置兜底形象`);
+          p.sprite = undefined;
+        }
+      }
       if (p.kind !== 'coding-agent' && p.kind !== 'board-plugin') throw new Error(`插件 ${p.id}：外部插件仅支持 coding-agent；语音识别请配置兼容接口的 URL、API Key 和模型名`);
       if (pack) {
         const mismatch = pack.id && pack.id !== p.id;

package/src/providers.mjs

@@ -39,6 +39,8 @@ export function providerStates(config, locale = config.locale) {
       },
       model: plugin.capabilities.model && plugin.model
         ? { default: plugin.model.default, required: plugin.model.required } : null,
+      // 形象素材清单：码得按 version 决定是否分片重拉（docs/SPRITES.md）。
+      sprite: plugin.sprite ? { version: plugin.sprite.version, files: plugin.sprite.files } : null,
       canCancelRunning: plugin.capabilities.cancel,
     };
   });

package/src/server.mjs

@@ -25,6 +25,8 @@ import { createPluginRegistry, loadConfiguredPlugins } from './plugins/registry.
 import { createEnhancement } from './plugins/enhance.mjs';
 import { listInstalled, listThemes, removePlugin, removeTheme, savePluginSettings, setPluginEnabled, themeExists } from './installed.mjs';
 import { createBoardLink } from './board-link.mjs';
+import { spriteChunk } from './agent-sprites.mjs';
+import { createScreenshotStore, rgb565ToPng, validateScreenshotParams, MAX_UPLOAD } from './board-screenshot.mjs';
 import { initializeSpeechSettings, saveSpeechSettings } from './speech-settings.mjs';
 import { builtinSpeechRecognizers } from './speech/index.mjs';
 const PAIRED_DISCOVERY_REQUEST = /^VIBE_DISCOVER_PAIRED_V2 ([0-9a-f]{12}) ([0-9a-f]{32})$/;
@@ -253,6 +255,7 @@ export function createApp(config, { run, transcribe, tunnel: providedTunnel, ena
   const usbForwardSecret = randomUUID();
   const pairing = new PairingStore(config.stateDir);
   const boardLink = createBoardLink();
+  const screenshots = createScreenshotStore(path.join(config.stateDir, 'screenshots'));
   // 增强运行时：回合管道与生命周期通知给 JobStore 用，bridge 句柄给插件上下文用。
   const enhance = createEnhancement(config);
   const tunnel = providedTunnel || new TunnelManager({
@@ -306,6 +309,7 @@ export function createApp(config, { run, transcribe, tunnel: providedTunnel, ena
     defaultProject: config.defaultProject,
     defaultProvider: config.defaultProvider,
     maxParallel: config.maxParallelJobs,
+    maxAutoRetries: config.maxAutoRetries,
     pluginsRuntime: config.pluginsRuntime,
     run: run || createRunner(config),
     hooks: enhance,
@@ -545,6 +549,41 @@ export function createApp(config, { run, transcribe, tunnel: providedTunnel, ena
           send(res, 200, { command: boardLink.send(named, { name: payload.name, fields: payload.fields }) });
           return;
         }
+        // 板端截屏触发：向在线的码得下发 debug.screenshot 命令，等待固件回传并返回 PNG。
+        if (url.pathname === '/api/screenshot') {
+          const online = boardLink.deviceIds();
+          if (!online.length) throw new Error('码得未连接（板侧能力清单未上报）');
+          const before = Date.now() - 1500;
+          let queued = 0;
+          let lastError = '';
+          for (const deviceId of online) {
+            try {
+              boardLink.send(deviceId, { name: 'debug.screenshot' });
+              queued += 1;
+            } catch (error) {
+              lastError = error.message;
+            }
+          }
+          if (!queued) throw new Error(lastError || '命令未能下发');
+          const deadline = Date.now() + 15000;
+          while (Date.now() < deadline) {
+            const file = screenshots.latest(before);
+            if (file) {
+              const png = fs.readFileSync(file);
+              res.writeHead(200, {
+                'Content-Type': 'image/png',
+                'Content-Length': png.length,
+                'X-Screenshot-File': path.basename(file),
+                'Cache-Control': 'no-store',
+                'X-Content-Type-Options': 'nosniff',
+              });
+              res.end(png);
+              return;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 250));
+          }
+          throw new Error('码得未在 15 秒内回传截图（固件需要更新到支持 debug.screenshot 的版本）');
+        }
         const pairAction = url.pathname.match(/^\/api\/pair\/([0-9a-f]{12})\/(confirm|reject)$/);
         if (pairAction) {
           const { nonce } = await body(req);
@@ -696,6 +735,7 @@ export function createApp(config, { run, transcribe, tunnel: providedTunnel, ena
         return;
       }
       const deviceId = pairing.deviceIdForToken(token);
+      if (process.env.VIBE_UI_DIAGNOSTICS === '1') console.info('[device-req]', req.method, url.pathname);
       if (req.method === 'POST' && url.pathname === '/device/capabilities') {
         boardLink.setCatalog(deviceId, await body(req));
         boardLink.connect(deviceId, config.pluginsRuntime, config, enhance.bridge());
@@ -795,16 +835,62 @@ export function createApp(config, { run, transcribe, tunnel: providedTunnel, ena
         // picker lives on the desktop. Keep room for twelve bounded bitmaps.
         const payload = {
           locale: config.locale,
-          providers: providerStates(config, deviceLocale).map(({ id, label, available, reason, icon, capabilities }) => ({ id, label, available, reason: devicePreview(reason, 120), icon, capabilities })),
+          providers: providerStates(config, deviceLocale).map(({ id, label, available, reason, icon, capabilities, sprite }) => ({ id, label, available, reason: devicePreview(reason, 120), icon, capabilities, sprite })),
           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 },
           board: { events: boardLink.subscription(pairing.deviceIdForToken(token), config.pluginsRuntime, config) },
+          // 桥接器重启会丢掉板侧命令清单：让板子看到 announce 后重新上报。
+          announce: !boardLink.hasCatalog(pairing.deviceIdForToken(token)),
         };
         if (Buffer.byteLength(JSON.stringify(payload)) > 32 * 1024) throw new Error('码得配置超过 32 KB，请检查助手元数据');
+        if (process.env.VIBE_UI_DIAGNOSTICS === '1') console.info('[device-config]', deviceId, 'announce=', payload.announce,
+          'providers=', payload.providers.map((p, i) => `${i}:${p.id}${p.sprite ? '@' + p.sprite.version : ''}`).join(' ') || 'none');
         deviceSend(res, 200, payload);
         return;
       }
+      // 形象素材分片拉取：单次 ≤192KB，兼容 USB 帧转发 256KB 上限（docs/SPRITES.md）。
+      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)$/);
+      if (spriteMatch) {
+        const plugin = config.pluginsRuntime.agent(spriteMatch[1]);
+        if (spriteMatch[2] === 'manifest.json') {
+          if (!plugin?.sprite) {
+            deviceSend(res, 404, { error: '素材不存在' });
+            return;
+          }
+          deviceSend(res, 200, {
+            version: plugin.sprite.version, canvas: plugin.sprite.canvas,
+            layers: plugin.sprite.layers, ...(plugin.sprite.motion ? { motion: plugin.sprite.motion } : {}),
+          });
+          return;
+        }
+        // 单次应答上限：固件按 offset 循环续拉整文件，这里故意切小。USB 链路
+        // （尤其叠着固件控制台输出时）对十几 KB 以上的帧偶发丢失；4KB 应答在
+        // 实测中始终送达，代价只是多几个来回。固件侧对下载失败已有 15s×5 次
+        // 重试（59f4043），此处小分片是为了把单次失败概率压到最低。
+        const SPRITE_DEVICE_CHUNK = 4 * 1024;
+        const requested = url.searchParams.has('len') ? Number(url.searchParams.get('len')) : undefined;
+        const chunk = plugin?.sprite ? spriteChunk(plugin.sprite, spriteMatch[2],
+          Number(url.searchParams.get('offset')) || 0,
+          requested === undefined ? SPRITE_DEVICE_CHUNK : Math.min(requested, SPRITE_DEVICE_CHUNK)) : null;
+        if (process.env.VIBE_UI_DIAGNOSTICS) {
+          console.log(`[device-sprite] ${spriteMatch[2]} offset=${url.searchParams.get('offset') ?? 0} len=${url.searchParams.get('len') ?? '-'} -> ${chunk ? chunk.length : -1}B`);
+        }
+        if (!chunk) {
+          deviceSend(res, 404, { error: '素材不存在' });
+          return;
+        }
+        res.writeHead(200, {
+          'Content-Type': 'application/octet-stream',
+          'Content-Length': chunk.length,
+          'X-Sprite-Total': plugin.sprite.files.find((file) => file.file === spriteMatch[2])?.bytes ?? 0,
+          'Cache-Control': 'no-store',
+          'X-Content-Type-Options': 'nosniff',
+        });
+        res.end(chunk);
+        return;
+      }
       if (req.method === 'POST' && url.pathname === '/device/voice') {
         if (voiceBusy) {
           deviceSend(res, 429, { error: '另一段录音正在识别，请稍后再试' });
@@ -854,6 +940,15 @@ export function createApp(config, { run, transcribe, tunnel: providedTunnel, ena
         deviceSend(res, 200, publicJob(match[2] === 'confirm' ? store.confirm(match[1]) : store.cancel(match[1]), deviceLocale));
         return;
       }
+      // 板端截屏回传：固件把当前画面以 RGB565 裸帧 POST 上来（tools/shot.mjs 触发）。
+      if (req.method === 'POST' && url.pathname === '/device/screenshot') {
+        const { width, height, stride } = validateScreenshotParams(url.searchParams);
+        const raw = await binaryBody(req, MAX_UPLOAD);
+        const png = rgb565ToPng(width, height, raw, stride);
+        const saved = screenshots.save(deviceId, png);
+        deviceSend(res, 201, { saved: path.basename(saved) }, false);
+        return;
+      }
       deviceSend(res, 404, { error: '未找到接口' });
     } catch (error) {
       deviceSend(res, error.message === '电脑配对窗口未开启' ? 403 :

package/src/usb-receiver.mjs

@@ -15,6 +15,9 @@ const MAX_CHUNK = 1024;
 // 8×1KB 的 base64 行大约 11KB，小于接收器 16KB 接收环。窗口内不等确认，
 // 避免 224KB 提示音被逐块往返拖过接收器 30 秒转发上限。
 const ACK_WINDOW = 8;
+// USB 直连（码得）走 ESP 的 USB Serial/JTAG，固件 RX 环只有 4KB；连发 8 块
+// 会灌爆环、丢字节，表现为大响应偶发超时。直连模式收紧到 2 块（约 2.8KB）。
+const ACK_WINDOW_DIRECT = 2;
 const MAX_REQUEST = 1_100_000;
 const MAX_RESPONSE = 262_144;
 const REQUEST_TIMEOUT_MS = 30_000;
@@ -169,6 +172,8 @@ export class UsbReceiverProtocol {
     this.locale = locale;
     this.line = Buffer.alloc(0);
     this.discardLine = false;
+    this.discardIsFrame = false;
+    this.ackWindow = ACK_WINDOW;
     this.helloReceived = false;
     this.peer = null;
     this.connectionId = randomBytes(16).toString('hex');
@@ -191,9 +196,14 @@ export class UsbReceiverProtocol {
       const segment = chunk.subarray(start, index);
       start = index + 1;
       if (this.discardLine || this.line.length + segment.length + 1 > MAX_LINE) {
+        // 超长行同样要区分日志与坏帧：固件的长日志行不该掐掉在途请求。
+        const looksLikeFrame = this.discardLine
+          ? this.discardIsFrame
+          : (this.line.length ? this.line[0] : segment[0]) === 0x7b;
+        if (looksLikeFrame) this.rejectCurrent(400, 'USB 帧过长');
         this.line = Buffer.alloc(0);
         this.discardLine = false;
-        this.rejectCurrent(400, 'USB 帧过长');
+        this.discardIsFrame = false;
         continue;
       }
       const line = Buffer.concat([this.line, segment]).toString('utf8').replace(/\r$/, '');
@@ -203,6 +213,7 @@ export class UsbReceiverProtocol {
     const remainder = chunk.subarray(start);
     if (this.discardLine) return;
     if (this.line.length + remainder.length + 1 > MAX_LINE) {
+      this.discardIsFrame = (this.line.length ? this.line[0] : remainder[0]) === 0x7b;
       this.line = Buffer.alloc(0);
       this.discardLine = true;
       return;
@@ -213,6 +224,13 @@ export class UsbReceiverProtocol {
   handleLine(line) {
     let frame;
     try { frame = JSON.parse(line); } catch {
+      // 固件控制台日志和协议帧共用这条 USB 流（USB Serial/JTAG），日志行随时
+      // 会插进来。只有「看着像帧」的坏行才算协议错误；日志必须原样放行，
+      // 否则板子一打日志就会掐掉正在传输的响应（素材分片下载失败即此因）。
+      if (!line.startsWith('{')) {
+        console.error(`[usb-link] log: ${line.slice(0, 240)}`);
+        return;
+      }
       console.error(`[usb-link] unparseable: ${line.slice(0, 240)}`);
       this.rejectCurrent(400, 'USB 帧格式无效');
       return;
@@ -236,6 +254,7 @@ export class UsbReceiverProtocol {
       if (this.onHello(peer) === false) return;
       console.error(`[usb-link] hello: mode=${peer.mode} ${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.
@@ -399,11 +418,21 @@ export class UsbReceiverProtocol {
         length: bytes.length }));
       let sentChunks = 0;
       for (let offset = 0; offset < bytes.length; offset += MAX_CHUNK) {
-        while (sentChunks - (this.ackCredits.get(id) || 0) >= ACK_WINDOW) {
-          await this.waitForCredits(id, sentChunks - ACK_WINDOW + 1);
+        while (sentChunks - (this.ackCredits.get(id) || 0) >= this.ackWindow) {
+          await this.waitForCredits(id, sentChunks - this.ackWindow + 1);
+        }
+        const piece = bytes.subarray(offset, offset + MAX_CHUNK);
+        // 逐帧指纹：这是【所有】USB 响应分片（sessions/commands 轮询也会打），
+        // 不是素材专属日志。与固件 [sprite-rx] 对齐比对仅在素材下载窗口内有效，
+        // 能定位到具体哪一帧被改——别的请求别拿这里的指纹对账（2026-10-14 排障
+        // 曾因把 15B/42B 轮询响应当素材分片绕了远路）。
+        if (process.env.VIBE_UI_DIAGNOSTICS === '1') {
+          let fnv = 2166136261 >>> 0;
+          for (const byte of piece) fnv = Math.imul(fnv ^ byte, 16777619) >>> 0;
+          console.log(`[usb-tx] id=${id} off=${offset} len=${piece.length} fnv1a=${fnv.toString(16).padStart(8, '0')}`);
         }
         await this.sendLine(JSON.stringify({ type: 'data', id,
-          chunk: bytes.subarray(offset, offset + MAX_CHUNK).toString('base64') }));
+          chunk: piece.toString('base64') }));
         sentChunks += 1;
       }
       if (sentChunks > (this.ackCredits.get(id) || 0)) await this.waitForCredits(id, sentChunks);