made-market 0.2.0 → 0.4.0

package/README.md

@@ -23,8 +23,8 @@ npx made-market publish <包目录>
 
 ## 服务地址
 
-- 默认索引：GitHub 上的 `registry/index.json`（离线时回落到包内自带快照）
-- 自建市场：`--server` 指定市场服务地址，或设 `MADE_MARKET_REGISTRY` / `MADE_MARKET_SERVER` 环境变量
+- 默认走市场服务的分页 API（`--server` 或 `MADE_MARKET_SERVER`，缺省官方市场）；list/search/info 按页拉取，install/info 按包直查，大市场友好
+- 自建静态源：`--registry` 或 `MADE_MARKET_REGISTRY` 指向索引文件（离线时 install 回落到包内自带示例快照）
 
 ## 服务端
 

package/bin/made-market.mjs

@@ -33,8 +33,8 @@ const USAGE = `码得 · 插件市场  (made-market)
 命令
   init <目录> --kind <类型>    生成插件脚手架（可直接 publish 的最小包，SDK 入口）
   validate <包目录>            本地校验一个包（与市场服务端同一套规则）
-  list                        列出索引里的全部包
-  search <关键词>              在包名、简介和标签里搜索
+  list                        列出市场上的包（分页 API，大市场友好）
+  search <关键词>              在包名、简介和标签里搜索（服务端搜索，分页）
   info <包 ID>                 看一个包的详情：文件、校验和、安装位置、创建人
   install <包 ID…>             装到包目录，重启桥接器后生效（匿名，无需登录）
   publish <包目录>             把一个包目录上传到市场服务（需先登录）
@@ -46,8 +46,8 @@ const USAGE = `码得 · 插件市场  (made-market)
 
 选项
   --home <目录>                包目录根，默认 $MADE_HOME 或 ~/made
-  --registry <路径|URL>        索引来源。默认 $MADE_MARKET_REGISTRY > 官方市场（联网拉实时索引，
-                               失败回落本包自带索引，离线可装示例包）
+  --registry <路径|URL>        索引来源（install 默认走市场 API 按包直查；
+                               显式指定后 list/search/info 也改读这个索引文件，自建静态源用）
   --server <URL>              市场服务地址（register/login/publish/install；install 默认官方市场，
                                可用 $MADE_MARKET_SERVER 覆盖，已登录时 publish 也可从凭证读取）
   --token <t>                 发布 token（publish；默认 $MADE_MARKET_TOKEN 或登录凭证）
@@ -99,7 +99,7 @@ const semverGreater = (a, b) => {
 
 /**
  * API 模式安装：按包直查市场服务的 /api/packages/<id>，不下载全量索引。
- * 大市场（索引几十 MB）时用这个，归档地址改写成服务上的绝对地址。
+ * 大市场（十几万包，全量索引根本不存在）时用这个，归档地址改写成服务上的绝对地址。
  */
 async function resolveViaApi(ids, server) {
   const base = String(server).replace(/\/+$/, '');
@@ -115,6 +115,36 @@ async function resolveViaApi(ids, server) {
   return { packages, base };
 }
 
+/**
+ * 分页拉目录：/api/packages 每页最多 100，循环翻页直到拉完。
+ * 十几万包的市场没有全量索引，list/search 只能这么吃。maxPages 是
+ * 防呆上限（默认 500 页 = 5 万条，超出提示加关键词/过滤）。
+ */
+async function fetchAllPages(server, { kind = '', q = '', maxPages = 500 } = {}) {
+  const base = String(server).replace(/\/+$/, '');
+  const items = [];
+  let offset = 0;
+  let total = Infinity;
+  while (offset < total) {
+    const params = new URLSearchParams({ limit: '100', offset: String(offset) });
+    if (kind) params.set('kind', kind);
+    if (q) params.set('q', q);
+    const response = await fetch(`${base}/api/packages?${params}`, { signal: AbortSignal.timeout(20000) });
+    if (!response.ok) throw new Error(`目录拉取失败：HTTP ${response.status}`);
+    const data = await response.json();
+    total = Number(data.total) || 0;
+    const batch = Array.isArray(data.items) ? data.items : [];
+    items.push(...batch);
+    if (!batch.length) break;
+    offset += batch.length;
+    if (offset >= 100 * maxPages) {
+      console.error(`包太多（共 ${total} 个），只列出前 ${offset} 个；用 search 或 --kind 缩小范围。`);
+      break;
+    }
+  }
+  return { items, total, base };
+}
+
 const human = (bytes) => (bytes < 1024 ? `${bytes} B` : bytes < 1024 * 1024 ? `${(bytes / 1024).toFixed(1)} KB` : `${(bytes / 1048576).toFixed(2)} MB`);
 const homeOf = (options) => resolveHome(options.home);
 
@@ -198,12 +228,21 @@ async function main() {
     return;
   }
 
-  // 索引来源按需加载：--registry > $MADE_MARKET_REGISTRY > 官方市场实时索引
-  // （远端失败自动回落包内自带索引，离线可装示例包）。
-  // rebuild-from-store 不依赖全量索引。
-  const loadIndex = () => loadRegistry(resolveRegistry(options.registry));
+  // list/search/info 的读路径：显式 --registry 或 $MADE_MARKET_REGISTRY 指向
+  // 索引文件（自建静态源/离线复现）时读文件；否则走市场分页 API（大市场没有全量索引）。
+  const staticRegistry = options.registry || process.env.MADE_MARKET_REGISTRY || '';
+  const loadIndex = () => loadRegistry(resolveRegistry(staticRegistry));
+
+  // list/search 的服务端地址：--server > $MADE_MARKET_SERVER > 官方市场
+  const listServer = () => (options.server || process.env.MADE_MARKET_SERVER || DEFAULT_SERVER).replace(/\/+$/, '');
 
   if (options.command === 'list') {
+    if (!staticRegistry) {
+      const { items } = await fetchAllPages(listServer(), { kind: options.kind });
+      if (options.json) console.log(JSON.stringify(items.map(describe), null, 2));
+      else printTable(items);
+      return;
+    }
     const rows = listRows((await loadIndex()).index, options);
     if (options.json) console.log(JSON.stringify(rows.map(describe), null, 2));
     else printTable(rows);
@@ -213,6 +252,13 @@ async function main() {
   if (options.command === 'search') {
     const query = options.args.join(' ').trim().toLowerCase();
     if (!query) throw new Error('search 需要一个关键词');
+    // 搜索在服务端做（id/名称/简介/标签全字段），客户端只翻页聚合。
+    if (!staticRegistry) {
+      const { items } = await fetchAllPages(listServer(), { q: query, kind: options.kind });
+      if (options.json) console.log(JSON.stringify(items.map(describe), null, 2));
+      else printTable(items);
+      return;
+    }
     const rows = listRows((await loadIndex()).index, options).filter((entry) => [
       entry.id, entry.name, entry.nameEn, entry.summary, entry.summaryEn, ...(entry.tags || []), ...(entry.highlights || []),
     ].filter(Boolean).some((field) => String(field).toLowerCase().includes(query)));
@@ -224,8 +270,19 @@ async function main() {
   if (options.command === 'info') {
     const id = options.args[0];
     if (!id) throw new Error('info 需要一个包 ID');
-    const entry = (await loadIndex()).index.packages.find((item) => item.id === id);
-    if (!entry) throw new Error(`索引里没有包 ${id}`);
+    let entry;
+    if (!staticRegistry) {
+      const base = listServer();
+      const response = await fetch(`${base}/api/packages/${encodeURIComponent(id)}`, { signal: AbortSignal.timeout(15000) });
+      if (!response.ok) throw new Error(`服务上没有包 ${id}（HTTP ${response.status}）`);
+      const versions = await response.json();
+      entry = versions.reduce((best, item) => (!best || semverGreater(item.version, best.version) ? item : best), null);
+      if (!entry) throw new Error(`服务上没有包 ${id}`);
+      if (!/^https?:\/\//.test(entry.download)) entry.download = `${base}/${entry.download}`;
+    } else {
+      entry = (await loadIndex()).index.packages.find((item) => item.id === id);
+      if (!entry) throw new Error(`索引里没有包 ${id}`);
+    }
     if (options.json) {
       console.log(JSON.stringify(describe(entry), null, 2));
       return;
@@ -254,8 +311,9 @@ async function main() {
   if (options.command === 'install') {
     if (!options.args.length) throw new Error('install 需要至少一个包 ID');
     // 默认走市场 API：按包直查最新版本，不拉全量索引（大市场友好），
-    // 新发布的包立即可装。显式 --registry 才按索引文件走（自建源/精确复现用）。
-    if (!options.registry) {
+    // 新发布的包立即可装。显式 --registry 或 $MADE_MARKET_REGISTRY 才按索引文件走
+    // （自建源/精确复现用）。
+    if (!options.registry && !process.env.MADE_MARKET_REGISTRY) {
       const server = options.server || process.env.MADE_MARKET_SERVER || DEFAULT_SERVER;
       try {
         const { packages, base } = await resolveViaApi(options.args, server);

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

package/registry/index.json

@@ -80,7 +80,7 @@
       ],
       "payloadBytes": 209717,
       "archiveBytes": 39822,
-      "sha256": "b656724a6be3466c0ad52010bfa9f2a3b043595b6b7b6bed90a01bdfcca3ba95",
+      "sha256": "f99ab016bda97781fba979cf5d31ffec18edf1ea91a2339c1d7e4cf63f36a0a7",
       "download": "packages/sunset-1.0.0.tar.gz",
       "swatch": [
         "#e0834a",
@@ -153,7 +153,7 @@
       ],
       "payloadBytes": 212917,
       "archiveBytes": 44910,
-      "sha256": "3894aadcfdba77eb351abc4381d3b76141ed0d6a15d8b75a982a64092e1300fa",
+      "sha256": "a48c12c45c83185041a25ea0f408f8ce15a1632d4473440a0a1fbc7b5f674cd1",
       "download": "packages/ocean-1.0.0.tar.gz",
       "swatch": [
         "#2fa3b8",
@@ -226,7 +226,7 @@
       ],
       "payloadBytes": 198517,
       "archiveBytes": 31125,
-      "sha256": "ff66fd400882e4ce3017b32782825aca59e60e5a407c793b175d2c4500c1cb97",
+      "sha256": "9dd6037414f9303ecc507c4348380baeaf8dd2a97c98c58748410c18b37c014e",
       "download": "packages/graphite-1.0.0.tar.gz",
       "swatch": [
         "#8e9aa6",
@@ -299,7 +299,7 @@
       ],
       "payloadBytes": 206517,
       "archiveBytes": 34163,
-      "sha256": "24dbf64bb96520a16efbfbb553ccff91190ae4fde5b18444f3c6a7ee97b0993f",
+      "sha256": "76095ce19587f8e0bc7ba5aeb7ca62f1e622bc8ef14847fdb3479dbf0ea87b29",
       "download": "packages/bamboo-1.0.0.tar.gz",
       "swatch": [
         "#5aa85e",
@@ -367,7 +367,7 @@
       ],
       "payloadBytes": 1576,
       "archiveBytes": 1067,
-      "sha256": "c3f6afae9ef5f47b622c74c2faf7174ba2ba38a9db2d19651a992874fd6f5f9a",
+      "sha256": "35c4768f607bb936b2e263e972895920c66cce74a8829d944cd86c6d2e5b0030",
       "download": "packages/theme-cycler-1.0.0.tar.gz",
       "sourcePath": "packages/control/theme-cycler"
     },
@@ -430,7 +430,7 @@
       ],
       "payloadBytes": 3023,
       "archiveBytes": 1808,
-      "sha256": "ab7acdc88895a391596182fa9425e1e81d0b7ec5de73c035b9fe0ee2a7a3a123",
+      "sha256": "0c7c6453b78a76c327282dfd62f6d023e90dc12a2c7458a67b1b43e5e20e15ba",
       "download": "packages/webhook-notify-1.0.0.tar.gz",
       "sourcePath": "packages/control/webhook-notify"
     },
@@ -492,7 +492,7 @@
       ],
       "payloadBytes": 2370,
       "archiveBytes": 1450,
-      "sha256": "43512f16e9559f5984ab9cf827b9b8e0e7c5671bc1cd1cf211adc0b0344e9f37",
+      "sha256": "cea53eedab0232272ed6f5ebd5c6b8a7250ff08240fb2d754b16b1e7c9088d7a",
       "download": "packages/key-chime-1.0.0.tar.gz",
       "sourcePath": "packages/control/key-chime"
     },
@@ -554,7 +554,7 @@
       ],
       "payloadBytes": 3940,
       "archiveBytes": 1959,
-      "sha256": "c131b7a0e67a9e0a1e4ab23b9dcf5ec05f7bb73c8b43621fe849c6762009c4e0",
+      "sha256": "bd4c7ae744be6a99dacaf663a0624e61e568f8da5e83566eb104127d39ddf11d",
       "download": "packages/alarm-clock-1.0.0.tar.gz",
       "sourcePath": "packages/control/alarm-clock"
     },
@@ -621,7 +621,7 @@
       ],
       "payloadBytes": 3793,
       "archiveBytes": 1612,
-      "sha256": "7f3d1045be427b2d4cbe0b070cb63ca0fc1fe127c63201f9423f23970d37f736",
+      "sha256": "aaf99b7ab9af49712f9ff5da37695c4d41cf89e09ae6ec5168057dede7075546",
       "download": "packages/demo-echo-1.0.0.tar.gz",
       "icon": {
         "format": "indexed4",
@@ -702,7 +702,7 @@
       ],
       "payloadBytes": 6098,
       "archiveBytes": 2672,
-      "sha256": "0a33b62f6f186a80d370012ddd146f9c504daf182503cc23cb4c13bd9c7e35d3",
+      "sha256": "8da05c474aa4b0d3d8913e16109b0ed887a4bab2d1d136527bb85bd798860cff",
       "download": "packages/ollama-agent-1.0.0.tar.gz",
       "icon": {
         "format": "indexed4",
@@ -786,7 +786,7 @@
       ],
       "payloadBytes": 5814,
       "archiveBytes": 2456,
-      "sha256": "541eef0c992b636cfe5d0b8f1f03dffa15a58b414f061ed392971bd3723a6c0f",
+      "sha256": "12de415fa0bb0bfaa3eb119c5e0930b3d3239836d184eab781dc1b36be93d06a",
       "download": "packages/shell-agent-1.0.0.tar.gz",
       "icon": {
         "format": "indexed4",

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}`);