made-market 0.1.2 → 0.2.0

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

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() },
       ];
     },
   },