made-market 0.3.0 → 0.4.0

package/lib/capabilities.mjs

@@ -34,6 +34,9 @@ export const CAPABILITIES = {
       { name: 'voice.start', desc: '主动点亮录音' },
       { name: 'task.confirm', desc: '批准待确认任务' },
       { name: 'task.cancel', desc: '取消任务' },
+      { name: 'ui.swipe', desc: '语义化手势，fields.direction：left/right（切助手）、up（开抽屉）、down（收抽屉）' },
+      { name: 'ui.tap', desc: '点击屏幕，fields.x/fields.y 为板面像素坐标（240x320），命中最深的可点击对象' },
+      { name: 'debug.screenshot', desc: '截取当前画面回传桥接器转 PNG（存 stateDir/screenshots/）' },
     ],
   },
   /** onJob 收到的任务生命周期，type 字段的全部取值（按典型顺序排列）。 */

package/lib/market.mjs

@@ -38,12 +38,17 @@ const PAYLOAD_IGNORED = new Set(['market.json']);
 export const sha256 = (buffer) => crypto.createHash('sha256').update(buffer).digest('hex');
 export const hashFile = (file) => sha256(fs.readFileSync(file));
 
-/** Deterministic, sorted payload listing — `market.json` never ships. */
+/** Deterministic, sorted payload listing — `market.json` never ships.
+ *  递归收子目录（如 agent 包的 sprite/），路径带 / 前缀；点文件与 market.json 永远跳过。 */
 export function payloadFiles(dir) {
-  return fs.readdirSync(dir)
-    .filter((name) => !PAYLOAD_IGNORED.has(name) && !name.startsWith('.'))
-    .filter((name) => fs.statSync(path.join(dir, name)).isFile())
-    .sort();
+  const walk = (base, prefix = '') => fs.readdirSync(base, { withFileTypes: true })
+    .filter((entry) => !PAYLOAD_IGNORED.has(entry.name) && !entry.name.startsWith('.'))
+    .flatMap((entry) => {
+      if (entry.isDirectory()) return walk(path.join(base, entry.name), `${prefix}${entry.name}/`);
+      if (entry.isFile()) return [`${prefix}${entry.name}`];
+      return [];
+    });
+  return walk(dir).sort();
 }
 
 export function readPackages(root = ROOT) {
@@ -134,8 +139,57 @@ function checkMarketFields(pkg, fail, warn) {
 /**
  * @returns {{errors: string[], warnings: string[], installDir: string, entry: string, pluginId: string}}
  */
-export function validatePackage(pkg) {
-  const errors = [];
+/** agent 包可选的 sprite/ 形象素材目录（规范见 made 仓库 docs/SPRITES.md）。
+ *  有目录就必须有合法 manifest；引用的 PNG 必须存在；整包 ≤512KB（分片下发协议约束）。 */
+function validateSpriteDir(dir, fail, warn) {
+  const spriteDir = path.join(dir, 'sprite');
+  if (!fs.existsSync(spriteDir)) {
+    warn('agent 包没有 sprite/ 目录，设备将显示内置兜底形象（规范见 made 仓库 docs/SPRITES.md）');
+    return;
+  }
+  const manifestPath = path.join(spriteDir, 'manifest.json');
+  if (!fs.existsSync(manifestPath)) {
+    fail('sprite/ 缺少 manifest.json');
+    return;
+  }
+  let sprite;
+  try {
+    sprite = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch (error) {
+    fail(`sprite/manifest.json 不是合法 JSON：${error.message}`);
+    return;
+  }
+  if (!Number.isInteger(sprite.version) || sprite.version < 1) {
+    fail('sprite/manifest.json 的 version 必须是 ≥1 的整数（改素材必须递增，否则设备不更新）');
+  }
+  if (!Array.isArray(sprite.layers) || !sprite.layers.length) {
+    fail('sprite/manifest.json 的 layers 必须是非空数组');
+  }
+  const pngs = fs.readdirSync(spriteDir).filter((name) => name.endsWith('.png'));
+  const referenced = new Set();
+  for (const layer of sprite.layers || []) {
+    for (const file of layer.frames || (layer.file ? [layer.file] : [])) {
+      if (typeof file !== 'string') {
+        fail('sprite/manifest.json 的层素材字段必须是字符串');
+        continue;
+      }
+      referenced.add(file);
+      if (!/^[A-Za-z0-9_-]{1,16}\.png$/i.test(file)) {
+        // 固件把素材平铺缓存在 SPIFFS（对象名上限 32 字符），文件名必须短。
+        fail(`sprite/${file} 文件名不合规：1–16 个字母/数字/下划线/连字符 + .png（总长 ≤20）`);
+      }
+      if (!pngs.includes(file)) fail(`sprite/manifest.json 引用了不存在的 ${file}`);
+    }
+  }
+  let total = 0;
+  for (const file of pngs) {
+    total += fs.statSync(path.join(spriteDir, file)).size;
+    if (!referenced.has(file)) warn(`sprite/${file} 没有被 manifest.json 引用，不会下发到设备`);
+  }
+  if (total > 512 * 1024) fail(`sprite/ 素材共 ${total} 字节，超过 512KB 上限`);
+}
+
+export function validatePackage(pkg) {  const errors = [];
   const warnings = [];
   const fail = (message) => errors.push(message);
   const warn = (message) => warnings.push(message);
@@ -235,6 +289,7 @@ export function validatePackage(pkg) {
       for (const key of ['session', 'model', 'cancel', 'progress']) {
         if (!scan.capabilityKeys.includes(key)) warn(`${source} 的 capabilities 缺少 ${key}`);
       }
+      validateSpriteDir(pkg.dir, fail, warn);
     }
     if (spec?.fields?.length && !pkg.market.highlights?.length) warn('这个包有可配置项，建议在 market.json 里写 highlights');
   }

package/lib/plugin.mjs

@@ -19,11 +19,12 @@ const MAX_VALUE = 500;
 const MAX_PATTERN = 200;
 const MAX_FILE = 16 * 1024;
 
-/** Commands the device currently executes (made README, 板侧事件与命令). */
+/** Commands the device currently executes (made 仓库 AGENTS.md，板侧事件与命令). */
 export const BOARD_COMMANDS = Object.freeze([
   'caption.show', 'audio.play', 'theme.apply', 'volume.set', 'agent.select',
   'session.create', 'session.select', 'session.delete', 'voice.start',
   'task.confirm', 'task.cancel',
+  'ui.swipe', 'ui.tap', 'debug.screenshot',
 ]);
 
 /** Events the device currently publishes. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "made-market",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "码得（made）公开插件市场的命令行工具：列出、搜索、安装主题/管控/agent 包，以及登录后发布新包。市场服务端在 github.com/jobop/made-market 仓库内，不随本包分发。",
   "type": "module",
   "license": "MIT",

package/src/init.mjs

@@ -7,6 +7,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import zlib from 'node:zlib';
 import { PACKAGE_DIR } from '../lib/plugin.mjs';
 import { renderIcon } from '../lib/icon.mjs';
 import { capabilitiesJson, contractsDts } from '../lib/capabilities.mjs';
@@ -182,7 +183,7 @@ function agentMarketJson(id, pluginId) {
     nameEn: 'My Agent Runtime',
     summary: '一句话简介：接的是哪个模型服务、怎么驱动码得。',
     summaryEn: 'One-line summary shown in the market listing.',
-    description: '详细描述会话建立方式、模型接入与取消行为。',
+    description: '详细描述会话建立方式、模型接入与取消行为。\n\n可选 sprite/ 目录：分层 PNG + manifest.json 定义助手在码得屏幕上的形象与动效，规范见 made 仓库 docs/SPRITES.md。眨眼/说话是 eyes/mouth 层切帧，位置全由 manifest 声明，固件零写死坐标；内置绿豆形象就是这套格式的参考实例。改素材必须递增 manifest 的 version。',
     descriptionEn: 'Long description in English.',
     author: '你的名字',
     license: 'MIT',
@@ -196,25 +197,34 @@ function agentMarketJson(id, pluginId) {
 
 /** agent 模板的 capabilities：四个键写成一行字面量，静态扫描（scanPluginSource）才认得。 */
 function agentPluginMjs(pluginId) {
+  // 模板必须能直接通过桥接器 validatePlugin：capabilities 是元数据（session 取
+  // 'native' | 'external_unscoped'，其余是布尔），probe 与 run 是顶层函数。
   return `/**
- * agent 运行时模板：把云端模型会话接到码得。capabilities 静态扫描会检查
- * session / model / cancel / progress 四个键是否齐全（缺了只是告警，但建议补全）。
- * agent 包不接收板侧事件。
+ * agent 运行时模板：把你的模型/CLI 接到码得。probe 决定「是否可用」的展示，
+ * run 执行一轮任务。capabilities 是能力声明（不是函数）：
+ * session: 'native'（可跨轮续会话）| 'external_unscoped'（任务隔离受限）。
  */
-const createSession = async ({ deviceId, config }) => {
-  // 建立（或复用）一个模型会话，返回会话句柄。
-  return { id: \`demo-\${deviceId}\`, model: 'demo-model' };
-};
-const currentModel = async ({ config }) => 'demo-model';
-const cancelTask = async () => { /* 取消当前任务 */ };
-const reportProgress = ({ state }) => { /* 上报进度 */ };
-
 export default {
   apiVersion: 1,
   kind: 'coding-agent',
   id: '${pluginId}',
   label: '我的 Agent',
-  capabilities: { session: createSession, model: currentModel, cancel: cancelTask, progress: reportProgress },
+  capabilities: { session: 'native', model: true, cancel: true, progress: true },
+  model: { default: '', required: false },
+
+  probe: (config) => {
+    // 返回 { available, reason }；reason 会显示在电脑端助手里。
+    return { available: true, reason: '模板助手：把 run 换成你的模型接入即可' };
+  },
+
+  run: async ({ job, project, config, signal, onProgress, onSession, model }) => {
+    // job.instruction 是用户指令；job.sessionId 非空表示续接既有会话。
+    // 首轮必须上报会话 id（onSession），后续轮经 job.sessionId 传回。
+    if (!job.sessionId) onSession(\`demo-\${Date.now()}\`);
+    onProgress('模板正在假装干活……');
+    // 真正的接入在这里：调你的模型 API / CLI 子进程，尊重 signal 取消。
+    return { status: 'completed', result: \`（模板）收到指令：\${job.instruction}\` };
+  },
 };
 `;
 }
@@ -224,6 +234,73 @@ function agentIconJson() {
   return renderIcon({ background: '#141C29', accent: '#5B8DEF', shapes: [[12, 12, 18, 18, '5B8DEF', 5]] });
 }
 
+// ── sprite/ 形象素材（规范真源：made 仓库 docs/SPRITES.md）────────────────
+// 占位 PNG 是合法 RGBA 图，尺寸/透明度合法，替换成真图即可。整体 ≤512KB。
+
+const CRC_TABLE = (() => {
+  const table = new Int32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    table[n] = c;
+  }
+  return table;
+})();
+
+function crc32(buffer) {
+  let c = 0xffffffff;
+  for (const byte of buffer) c = CRC_TABLE[(c ^ byte) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+function pngChunk(type, data) {
+  const length = Buffer.alloc(4);
+  length.writeUInt32BE(data.length);
+  const body = Buffer.concat([Buffer.from(type, 'ascii'), data]);
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(body));
+  return Buffer.concat([length, body, crc]);
+}
+
+/** 纯色 RGBA PNG（逐行相同，deflate 后只有几十字节）。 */
+function placeholderPng(width, height, [r, g, b, a]) {
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8;  // bit depth
+  ihdr[9] = 6;  // color type: RGBA
+  const row = Buffer.alloc(1 + width * 4);
+  for (let x = 0; x < width; x++) {
+    row[1 + x * 4] = r;
+    row[2 + x * 4] = g;
+    row[3 + x * 4] = b;
+    row[4 + x * 4] = a;
+  }
+  const raw = Buffer.concat(Array.from({ length: height }, () => row));
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    pngChunk('IHDR', ihdr),
+    pngChunk('IDAT', zlib.deflateSync(raw)),
+    pngChunk('IEND', Buffer.alloc(0)),
+  ]);
+}
+
+function spriteManifest() {
+  return {
+    version: 1,
+    canvas: { w: 360, h: 360 },
+    layers: [
+      // body 铺满画布；eyes/mouth 的 x/y 是层左上角在画布上的位置，z 小的在下。
+      { id: 'body', file: 'body.png', x: 100, y: 62, z: 0 },
+      { id: 'eyes', frames: ['eyes-open.png', 'eyes-closed.png'], x: 150, y: 150, z: 1,
+        blink: { period_ms: 4000, closed_ms: 120 } },
+      { id: 'mouth', frames: ['mouth-closed.png', 'mouth-open.png'], x: 155, y: 215, z: 2, talk: true },
+    ],
+    // 整体动效：呼吸缩放 / 左右轻摆；缺省用固件默认值。
+    motion: { breath: { scale_pct: 103, period_ms: 3000 }, sway_deg: 3, sway_period_ms: 1800 },
+  };
+}
+
 const SCHEMAS = {
   theme: {
     label: '主题',
@@ -262,6 +339,14 @@ const SCHEMAS = {
         { name: 'plugin.mjs', data: agentPluginMjs(pluginId) },
         { name: 'plugin.json', data: `${JSON.stringify({ id: pluginId, settings: [] }, null, 2)}\n` },
         { name: 'icon.json', data: `${JSON.stringify(agentIconJson(), null, 2)}\n` },
+        // 形象素材：分层 PNG + manifest。规范与字段说明见 made 仓库 docs/SPRITES.md。
+        // 改素材后必须递增 manifest.json 的 version，已安装的设备才会重新拉取。
+        { name: 'sprite/manifest.json', data: `${JSON.stringify(spriteManifest(), null, 2)}\n` },
+        { name: 'sprite/body.png', data: placeholderPng(160, 160, [0x10, 0x26, 0x29, 0xff]) },
+        { name: 'sprite/eyes-open.png', data: placeholderPng(40, 16, [0x26, 0x21, 0x5c, 0xff]) },
+        { name: 'sprite/eyes-closed.png', data: placeholderPng(40, 16, [0x10, 0x26, 0x29, 0xff]) },
+        { name: 'sprite/mouth-closed.png', data: placeholderPng(32, 12, [0x26, 0x21, 0x5c, 0xff]) },
+        { name: 'sprite/mouth-open.png', data: placeholderPng(32, 12, [0x71, 0x2b, 0x13, 0xff]) },
       ];
     },
   },
@@ -283,6 +368,7 @@ export function scaffold({ dir, kind, force = false }) {
   fs.mkdirSync(dir, { recursive: true });
   return schema.files(id).map((file) => {
     const target = path.join(dir, file.name);
+    fs.mkdirSync(path.dirname(target), { recursive: true }); // sprite/ 等子目录
     fs.writeFileSync(target, file.data);
     return target;
   });

package/src/install.mjs

@@ -141,7 +141,11 @@ export async function install(ids, { home = '', registry = BUNDLED_REGISTRY, ind
     if (!dryRun) {
       fs.rmSync(target, { recursive: true, force: true });
       fs.mkdirSync(target, { recursive: true });
-      for (const file of entries) fs.writeFileSync(path.join(target, file.name), file.data);
+      for (const file of entries) {
+        const dest = path.join(target, file.name);
+        fs.mkdirSync(path.dirname(dest), { recursive: true }); // sprite/ 等子目录
+        fs.writeFileSync(dest, file.data);
+      }
     }
     done.push({ entry, target, files: entries.map((file) => file.name) });
     console.log(`${dryRun ? '将安装' : '已安装'} ${entry.name} · ${id} v${entry.version}`);