made-market 0.1.2 → 0.3.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

@@ -0,0 +1,208 @@
+/**
+ * 管控插件的开放能力清单（apiVersion 1 的能力面真源）。
+ *
+ * 单一真源，三处消费：init 脚手架把它生成进包里（capabilities.json +
+ * contracts.d.ts，作者写插件时编辑器直接有提示）、市场网站说明页按它排版、
+ * 桥接器侧的实现（made 仓库 enhance.mjs）是它的运行时对应物。改能力面时
+ * 先改这里，再同步 made 仓库 AGENTS.md 的清单表与 site/capabilities.html。
+ *
+ * 两条供给线：
+ * - board：事件与命令，清单由固件上报（announceBoardCatalog），扩清单要刷固件；
+ * - bridge：桥接器进程内露出的句柄（enhance.mjs），重启桥接器即生效。
+ */
+
+export const CAPABILITIES = {
+  apiVersion: 1,
+  /** 能力清单版本：加能力不升它；改既有能力的语义/形状才升，并同步桥接器。 */
+  schemaVersion: 1,
+  board: {
+    events: [
+      { name: 'boot.click', cadence: 'edge', desc: '按键短按（语音意图）' },
+      { name: 'boot.double', cadence: 'edge', desc: '双击（确认）' },
+      { name: 'boot.triple', cadence: 'edge', desc: '三击（取消）' },
+      { name: 'boot.long', cadence: 'edge', desc: '长按（回主页）' },
+    ],
+    commands: [
+      { name: 'caption.show', desc: '屏幕字幕，fields.text 为正文' },
+      { name: 'audio.play', desc: '播放音频，可附带 WAV：16-bit PCM、单声道、8k–48kHz、≤256KB' },
+      { name: 'theme.apply', desc: '应用主题插件' },
+      { name: 'volume.set', desc: '设置音量' },
+      { name: 'agent.select', desc: '切换当前助手' },
+      { name: 'session.create', desc: '新建会话' },
+      { name: 'session.select', desc: '切换会话' },
+      { name: 'session.delete', desc: '删除会话' },
+      { name: 'voice.start', desc: '主动点亮录音' },
+      { name: 'task.confirm', desc: '批准待确认任务' },
+      { name: 'task.cancel', desc: '取消任务' },
+    ],
+  },
+  /** onJob 收到的任务生命周期，type 字段的全部取值（按典型顺序排列）。 */
+  jobLifecycle: ['created', 'confirmed', 'started', 'progress', 'completed', 'handed_off', 'failed', 'cancelled'],
+  /** 回合管道：按插件注册顺序成链，返回字符串即 override，最后一个说话的算数。 */
+  turnPipes: [
+    { name: 'onTurnInput', context: ['instruction', 'job', 'agentId', 'config', 'bridge'], desc: '改写本轮实际执行的指令；存储里的任务原文不动' },
+    { name: 'onTurnOutput', context: ['result', 'job', 'agentId', 'status', 'config', 'bridge'], desc: '仅在任务完成时调用，改写回给用户的结果' },
+  ],
+  /** bridge 门面：事件、钩子、通知的上下文里都拿得到。 */
+  bridge: [
+    { name: 'agents', signature: 'agents()', desc: '全部助手（含可用性与探测原因）' },
+    { name: 'agent', signature: 'agent(id)', desc: '按 id 查单个助手' },
+    { name: 'jobs', signature: 'jobs()', desc: '全部任务' },
+    { name: 'job', signature: 'job(id)', desc: '按 id 查单个任务' },
+    { name: 'sessions', signature: 'sessions(agentId?)', desc: '会话清单，可按助手过滤' },
+    { name: 'createTask', signature: 'createTask({instruction, agentId?, projectId?, title?})', desc: '建会话并落一个待确认任务，返回 {job, session}；限流 10 次/分钟' },
+    { name: 'submitTurn', signature: 'submitTurn({instruction, sessionId})', desc: '向既有会话追加一轮（同样落待确认）' },
+    { name: 'confirmJob', signature: 'confirmJob(id)', desc: '批准待确认任务，批准后立即执行' },
+    { name: 'cancelJob', signature: 'cancelJob(id)', desc: '取消任务' },
+    { name: 'themes', signature: 'themes()', desc: '已安装主题清单' },
+    { name: 'devices', signature: 'devices()', desc: '当前在线设备 id 列表' },
+    { name: 'send', signature: 'send(deviceId, command, audio?)', desc: '向指定设备入队一条板侧命令（须在板侧清单内）' },
+    { name: 'pending', signature: 'pending(deviceId)', desc: '该设备尚未取走的命令队列' },
+  ],
+  limits: {
+    hookTimeoutMs: 1500,
+    createTaskPerMinute: 10,
+    audioFormat: '16-bit PCM WAV，单声道，8k–48kHz，≤256KB',
+  },
+};
+
+/** 生成进包里的 capabilities.json（作者可读，也方便脚本化消费）。 */
+export const capabilitiesJson = () => `${JSON.stringify(CAPABILITIES, null, 2)}\n`;
+
+/**
+ * 生成进包里的 contracts.d.ts：只描述插件作者看得见、用得上的接口面。
+ * 类型仅给编辑器提示，运行时不加载（plugin.mjs 是纯 JS）。
+ */
+export const contractsDts = () => `/**
+ * 码得管控插件 · 接口契约（apiVersion ${CAPABILITIES.apiVersion}）。
+ * 由 npx made-market init 生成，运行时对应桥接器的 bridge/src/plugins/enhance.mjs。
+ * 能力清单（事件/命令/句柄/限制）见同目录 capabilities.json。
+ */
+
+export interface BoardEvent {
+  name: string;
+  fields: Record<string, string>;
+}
+
+export interface BoardCommand {
+  name: string;
+  fields?: Record<string, string>;
+}
+
+export interface PluginConfig {
+  /** 各插件的设置：pluginSettings[<你的插件 id>] */
+  pluginSettings: Record<string, Record<string, string>>;
+  /** 用户当前默认助手 id */
+  defaultProvider: string;
+  [key: string]: unknown;
+}
+
+export interface JobView {
+  id: string;
+  sessionId: string;
+  instruction: string;
+  status: string;
+  /** 执行该任务的助手 id */
+  provider: string;
+  projectId?: string;
+  /** 任务来源：'voice' | 'plugin' | ... */
+  source?: string;
+  result?: string;
+  progress?: string;
+  createdAt: string;
+  updatedAt: string;
+  [key: string]: unknown;
+}
+
+export interface SessionView {
+  id: string;
+  provider: string;
+  title?: string;
+  [key: string]: unknown;
+}
+
+export interface AgentView {
+  id: string;
+  label: string;
+  available: boolean;
+  reason: string;
+  mode: string;
+  capabilities?: unknown;
+}
+
+/** 桥接器句柄：事件、钩子、通知的上下文里都拿得到（context.bridge）。 */
+export interface Bridge {
+  agents(): AgentView[];
+  agent(id: string): AgentView | undefined;
+  jobs(): JobView[];
+  job(id: string): JobView | undefined;
+  sessions(agentId?: string): SessionView[];
+  createTask(options: { instruction: string; agentId?: string; projectId?: string; title?: string }):
+    { job: JobView; session: SessionView };
+  submitTurn(options: { instruction: string; sessionId: string }): JobView;
+  confirmJob(id: string): JobView;
+  cancelJob(id: string): JobView;
+  themes(): Array<Record<string, unknown>>;
+  devices(): string[];
+  send(deviceId: string, command: BoardCommand, audio?: Uint8Array): unknown;
+  pending(deviceId: string): unknown[];
+}
+
+export type JobEventType =
+  | 'created' | 'confirmed' | 'started' | 'progress'
+  | 'completed' | 'handed_off' | 'failed' | 'cancelled';
+
+export interface PluginBase {
+  apiVersion: 1;
+  kind: 'board-plugin';
+  id: string;
+  label: string;
+  /** 健康探测：工作台据此显示 available / reason。 */
+  probe: (config: PluginConfig) => { available: boolean; reason?: string };
+
+  /** 板侧事件：events 里登记过的才会被上报。返回 {commands} 或调 context.send 入队。 */
+  onEvent(context: {
+    event: BoardEvent;
+    deviceId: string;
+    config: PluginConfig;
+    send: (command: BoardCommand, audio?: Uint8Array) => unknown;
+    bridge: Bridge;
+  }): Promise<{ commands?: BoardCommand[] } | void> | { commands?: BoardCommand[] } | void;
+
+  onConnect?(context: {
+    deviceId: string;
+    config: PluginConfig;
+    send: (command: BoardCommand, audio?: Uint8Array) => unknown;
+    bridge: Bridge;
+  }): Promise<void> | void;
+
+  onDisconnect?(context: { deviceId: string }): Promise<void> | void;
+
+  /** 任务生命周期通知（${CAPABILITIES.jobLifecycle.join(' / ')}）。 */
+  onJob?(context: {
+    type: JobEventType;
+    job: JobView;
+    config: PluginConfig;
+    bridge: Bridge;
+  }): Promise<void> | void;
+
+  /** 回合管道：返回字符串即 override。超时 ${CAPABILITIES.limits.hookTimeoutMs}ms 或抛错则沿用上一环。 */
+  onTurnInput?(context: {
+    instruction: string;
+    job: JobView;
+    agentId: string;
+    config: PluginConfig;
+    bridge: Bridge;
+  }): Promise<string | void> | string | void;
+
+  /** 仅在任务完成时调用；返回字符串即改写回给用户的结果。 */
+  onTurnOutput?(context: {
+    result: string;
+    job: JobView;
+    agentId: string;
+    status: 'completed';
+    config: PluginConfig;
+    bridge: Bridge;
+  }): Promise<string | void> | string | void;
+}
+`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "made-market",
-  "version": "0.1.2",
+  "version": "0.3.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

@@ -9,6 +9,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { PACKAGE_DIR } from '../lib/plugin.mjs';
 import { renderIcon } from '../lib/icon.mjs';
+import { capabilitiesJson, contractsDts } from '../lib/capabilities.mjs';
 
 const THEME_NAME = /^[A-Za-z0-9_-]{1,64}$/;
 
@@ -101,12 +102,15 @@ function controlMarketJson(id, pluginId) {
 
 function controlPluginMjs(pluginId) {
   return `/**
- * 管控插件模板：改掉 id/label，实现 onConnect / onEvent，就能发布。
+ * 管控插件模板：改掉 id/label，挑需要的钩子实现，就能发布。
  *
- * events 只能填板侧公开清单里的名字（boot.click / boot.double / boot.triple /
- * boot.long）；commands 只能填 caption.show / audio.play / theme.apply /
- * volume.set / agent.select / session.* / voice.start / task.*。
- * 语音通过 send({ name: 'audio.play' }, wav) 入队，send 在 onEvent 返回后仍有效。
+ * 能力清单（板侧事件/命令、任务生命周期、bridge 句柄、限流）见同目录
+ * capabilities.json；接口类型见 contracts.d.ts（编辑器自动提示）。
+ *
+ * events/commands 只能填板侧清单里的名字：
+ * - 事件：boot.click / boot.double / boot.triple / boot.long
+ * - 命令：caption.show / audio.play / theme.apply / volume.set / agent.select /
+ *   session.create / session.select / session.delete / voice.start / task.confirm / task.cancel
  */
 export default {
   apiVersion: 1,
@@ -119,15 +123,41 @@ export default {
     // 健康探测：桥接器会显示 available / reason。
     return { available: true, reason: '模板插件，尚未实现逻辑' };
   },
-  onConnect({ deviceId, config, send }) {
-    // 设备连上来时触发（可选实现）。
-  },
-  onEvent({ event, deviceId, config, send }) {
+
+  // ── 触发面一：板侧事件 ────────────────────────────────────────────
+  onEvent({ event, deviceId, config, send, bridge }) {
     if (event.name === 'boot.click') {
+      // 两条出命令的路：返回 {commands}，或稍后调 send(command, audio?)。
       return { commands: [{ name: 'caption.show', fields: { text: '你好，码得！' } }] };
     }
     return null;
   },
+
+  // ── 触发面二：任务生命周期（可选）────────────────────────────────
+  // type: created / confirmed / started / progress / completed / handed_off /
+  //       failed / cancelled。注意：插件自建的任务不广播 created（防自激）。
+  // onJob({ type, job, bridge }) {
+  //   if (type === 'completed' && job.provider === '某助手id') {
+  //     // 例：把操作日志上报远端、或在板上播报完成。
+  //   }
+  // },
+
+  // ── 触发面三：回合管道（可选，override 权限最高）─────────────────
+  // 按插件注册顺序成链，返回字符串即改写，最后一个说话的算数；
+  // 超时 1500ms 或抛错则沿用上一环，绝不阻断任务本身。
+  // onTurnOutput({ result, job, agentId }) {
+  //   if (agentId !== '某助手id') return;          // 只加工目标助手
+  //   return \`\${result}\\n—— 由我的插件加工\`;
+  // },
+
+  // ── 自主行为：bridge 句柄（可选）────────────────────────────────
+  // bridge.agents() / bridge.createTask({...})（落待确认任务，限流 10 次/分钟）/
+  // bridge.confirmJob(id) / bridge.send(deviceId, {name:'audio.play'}, wav) ……
+  // 全部句柄与签名见 capabilities.json 的 bridge 一节。
+
+  onConnect({ deviceId, config, send, bridge }) {
+    // 设备连上来时触发（可选实现）。
+  },
   onDisconnect({ deviceId }) {
     // 设备断开时触发（可选实现）。
   },
@@ -216,6 +246,10 @@ const SCHEMAS = {
         { name: 'plugin.mjs', data: controlPluginMjs(pluginId) },
         { name: 'plugin.json', data: `${JSON.stringify(controlPluginJson(pluginId), null, 2)}\n` },
         { name: 'settings.json', data: '{}\n' },
+        // 能力 SDK：清单（机器可读）+ 类型契约（编辑器提示）。随包发布，
+        // 装到 ~/made/plugins/<id>/ 后依然在，作者与使用者都能查。
+        { name: 'capabilities.json', data: capabilitiesJson() },
+        { name: 'contracts.d.ts', data: contractsDts() },
       ];
     },
   },