管控插件的开放能力

插件是「有自主行为能力的增强体」：触发器只决定它何时被唤醒，能做什么取决于下面这张清单。npx made-market init --kind control 会把同一份清单生成进包里（capabilities.json + contracts.d.ts），编辑器直接有类型提示。

npx made-market init my-plugin --kind control

能力从哪来：两条供给线

板侧线 · 固件说了算

事件与命令的清单由固件上报，桥接器只做清单校验。要加新命令（比如关机）必须改固件、刷机。

桥接器线 · 重启即生效

任务存储、助手清单、主题、板侧发送等句柄由桥接器进程露出，插件被唤醒后通过 bridge 对象取用。

板侧事件（events 登记）

只有被已激活插件登记过的事件，板子才会上报。cadence 均为 edge（边沿触发）。

事件	含义
`boot.click`	按键短按（语音意图）
`boot.double`	双击（确认）
`boot.triple`	三击（取消）
`boot.long`	长按（回主页）

板侧命令（commands 登记）

在 onEvent 里返回 {commands} 或调 context.send 入队；send 在事件返回后仍有效，可以做「先记下、稍后发」的异步行为。命令名必须同时在板侧清单和插件自己的 commands 里。

命令	作用
`caption.show`	屏幕字幕，fields.text 为正文
`audio.play`	播放音频，可附带 WAV：16-bit PCM、单声道、8k–48kHz、≤256KB
`theme.apply`	应用主题插件
`volume.set`	设置音量
`agent.select`	切换当前助手
`session.create` / `session.select` / `session.delete`	会话管理：新建 / 切换 / 删除
`voice.start`	主动点亮录音
`task.confirm` / `task.cancel`	审批待确认任务：批准 / 取消

任务生命周期与回合管道

onJob 会在任务经过以下状态时收到通知（插件自建的任务不广播 created，防自激）：

created → confirmed → started → progress* → completed
                                      ↘ handed_off / failed / cancelled

回合管道是 override 权限最高的接口：按插件注册顺序成链，返回字符串即改写，最后一个说话的算数。

onTurnInput({ instruction, job, agentId, bridge }) {
  if (agentId !== 'target_agent') return;          // 只加工目标助手
  return instruction + '\\n\\n（附加约束：回答保持两行以内）';
},
onTurnOutput({ result, job, agentId }) {
  if (agentId !== 'target_agent') return;
  return result + '\\n—— 由我的插件加工';
}

边界：钩子超时 1500ms 或抛错时沿用上一环的值，绝不阻断任务本身；onTurnInput 改写的是执行副本，存储里的任务原文保持不变；桥接器会记录每次改写，便于排查「这条回复为什么长这样」。

bridge 句柄（自主行为）

事件、钩子、通知的上下文里都拿得到 context.bridge。全部句柄与签名：

句柄	作用
`agents()` / `agent(id)`	助手清单与可用性（probe 结果）
`jobs()` / `job(id)`	任务清单与详情
`sessions(agentId?)`	会话清单，可按助手过滤
`createTask({instruction, agentId?, projectId?, title?})`	自动建会话并落一个待确认任务，返回 {job, session}；限流 10 次/分钟
`submitTurn({instruction, sessionId})`	向既有会话追加一轮
`confirmJob(id)` / `cancelJob(id)`	批准（立即执行）/ 取消任务
`themes()`	已安装主题清单
`devices()` / `pending(deviceId)`	在线设备 / 待取命令队列
`send(deviceId, command, audio?)`	向指定设备入队板侧命令（须在板侧清单内）

「让某个助手干活」的完整链路：createTask 落待确认 → confirmJob 放行 → onJob 收到 completed 时做后续（播报、上报、再派任务）。

onEvent({ event, bridge }) {
  if (event.name !== 'boot.double') return;
  const { job } = bridge.createTask({ instruction: '总结当前项目最近一次提交' });
  bridge.confirmJob(job.id);
}

脚手架 SDK

init 生成的管控包自带两个能力文件，随包发布、装到用户桥接器后依然在：

文件	作用
`capabilities.json`	机器可读的能力清单：事件、命令、生命周期、句柄、限流——脚本与文档都消费它
`contracts.d.ts`	TypeScript 类型契约：onEvent / onJob / onTurnInput / onTurnOutput / Bridge 的完整签名，编辑器自动提示

清单按 apiVersion 演进：加能力是往清单里添一行；改既有能力的语义才升版本。插件只能选清单里的点，不能自己造点。