UI Plugin

UI Plugin 是极简模式（web-minimal）的界面插件。宿主是纯静态页面，插件以 iframe 挂载、按 slot.area 入驻不同区域，通过 postMessage 的 callAction 动作总线与宿主通信。 A UI plugin is an interface plugin for minimal mode. The host is a static page, plugins mount as an iframe, land in an area declared by slot.area, and talk to the host over the callAction postMessage bus.

目录结构Layout

ui-plugins/<id>/          # 市场仓库中的单元
├── plugin.json          # 清单（必需）
├── index.html           # entry 入口页面（必需）
└── ...                  # 样式/脚本/图片等相对引用资源（可选）

文件夹名 = plugin.json 的 id = 插件标识，三者必须一致。 Folder name, plugin.json's id, and the plugin identity must all be the same string.

plugin.json 字段 plugin.json fields

{
  "id": "doodle-chat",
  "name": "涂鸦聊天",
  "description": "English one-liner.",
  "description-en": "English one-liner.",
  "icon": "🖍️",
  "slot": { "area": "panel" },
  "entry": "index.html",
  "image": "cover.png",
  "root": "user",
  "builtin": false,
  "dependency": [],
  "configSchema": [
    { "key": "color", "type": "select", "label": "主题色",
      "options": [{ "value": "warm", "label": "暖" }, { "value": "cool", "label": "冷" }],
      "default": "warm" }
  ],
  "backend": { "kind": "npm" }
}

slot.area 区域清单 slot.area values

area 是插件声明的唯一入驻维度；行为（单例 / 容器抽屉 / 浮窗）由宿主按区域内置，插件不要自行声明窗口类型。 area is the only thing a plugin declares. The host decides the behaviour — singleton, container drawer, or floating window — so plugins should never declare a window type themselves.

callAction 动作总线 The callAction bus

插件调用宿主时发这条消息，id 用于匹配响应： A plugin calls the host with this message; id matches the reply:

window.parent.postMessage({ type: 'callAction', id: 'req-1',
  actionId: 'config.get', payload: { plugin_id: 'doodle-chat' } }, '*');

actionId 契约（payload → data） actionId contracts (payload → data)

应答信封 { type: 'callActionResult', id, ok, data | error }；ok 为 false 时读 error，未知 actionId 返回 null。实现见 ui/web-minimal/assets/host.js 的 dispatch()。
文件与上传：宿主 / 前端 / 后端同机，dialog.files 返回绝对路径，后端可直接 fs 读取（不必 base64 走 plugin.rpc）；要交给 Agent（大模型）读用 POST /agent/upload（落盘 agent_vm/.buffer/upload）。 Reply envelope: { type: 'callActionResult', id, ok, data | error }; read error when ok is false; an unknown actionId returns null. Implementation: dispatch() in ui/web-minimal/assets/host.js.
Files & upload: host / frontend / backend share one machine, so dialog.files returns absolute paths the backend can read with fs (no base64 over plugin.rpc); to hand a file to the Agent (LLM), use POST /agent/upload (lands in agent_vm/.buffer/upload).

事件（节选）Events (excerpt)

事件按 slot 路由，只发给声明了对应槽的插件。所以 panel 槽的插件收不到 conversation.*，而且它只带 session_id（无消息内容、无"完成"标记）——要判定 Agent 任务完成得自行轮询（产物 mtime / state.get）+ 超时兜底。 Events are routed by slot and only reach plugins in that slot. So a plugin in the panel slot never receives conversation.*, which only carries session_id anyway (no message content, no "done" flag) — to detect that an Agent task finished, poll instead (artifact mtime / state.get) with a timeout fallback.

开发注意Gotchas

• 宿主 CSS 变量不跨 iframe 继承，插件样式必须自带 fallback，如 color: var(--wm-label, #16191d)；token 全量见 ui/web-minimal/assets/theme.css。 Host CSS variables do not cross the iframe — always ship a fallback, e.g. color: var(--wm-label, #16191d); the full token list is in ui/web-minimal/assets/theme.css.
• 宿主跑在 Electron 里，window.prompt / alert / confirm 不可用（prompt 直接返回 null）；输入与二次确认请用插件自绘浮层。 The host runs in Electron, where window.prompt / alert / confirm are unavailable (prompt just returns null); build your own overlay for input and confirmation.

最小可运行示例Minimal runnable example

plugin.json plugin.json

{
  "id": "hello-panel",
  "name": "Hello 面板",
  "description": "A minimal panel plugin.",
  "description-en": "A minimal panel plugin.",
  "icon": "🐾",
  "slot": { "area": "panel" },
  "entry": "index.html",
  "configSchema": [
    { "key": "greeting", "type": "text", "label": "问候语", "default": "喵~" }
  ]
}

index.html index.html

<!doctype html>
<html lang="zh-CN">
<head><meta charset="utf-8"><title>Hello</title>
<style>body{font-family:system-ui;margin:16px;background:transparent}</style></head>
<body>
  <h3 id="hi">喵~</h3>
  <button id="send">发到会话</button>
<script>
  let reqSeq = 0;
  const pending = new Map();
  function call(actionId, payload) {
    const id = 'r' + (++reqSeq);
    return new Promise(res => { pending.set(id, res);
      window.parent.postMessage({ type: 'callAction', id, actionId, payload }, '*'); });
  }
  window.addEventListener('message', e => {
    const m = e.data || {};
    if (m.type === 'callActionResult' && pending.has(m.id)) { pending.get(m.id)(m.ok ? m.data : m.error); pending.delete(m.id); }
    if (m.type === 'configApply') { document.getElementById('hi').textContent = m.config.greeting || '喵~'; }
  });
  document.getElementById('send').onclick = () => call('chat.send', { message: '你好，来自面板插件' });
</script>
</body>
</html>

开发与调试Build & debug

• 本地预览：插件目录放到 ~/.purrcat/webmin-plugins/<id>/，重启极简宿主（/minimal 页面 Ctrl+R）即可加载。 Local preview: drop the folder into ~/.purrcat/webmin-plugins/<id>/ and reload the host page at /minimal with Ctrl+R.
• 调试：插件跑在 iframe 里，用开发者工具选中对应 iframe 上下文看 Console；callAction 出错会落在宿主控制台。 Debugging: the plugin runs inside an iframe — pick that iframe's context in DevTools to read its console. callAction errors surface in the host console.
• 自带后端：声明 backend: { "kind": "npm" } 并提供 server/server.js（Node；依赖放插件自己的 package.json / node_modules），插件侧用 plugin.rpc 调用；宿主把它当独立子进程拉起，进程退出后下次 RPC 会自动重新拉起。
  协议走 stdio 单行 JSON：宿主发 {"id","handler","payload"}，插件回 {"id","ok":true,"result":...} 或 {"id","ok":false,"error":"..."}； 启动后必须向 stdout 打一行 {"event":"ready"}，否则宿主 15 秒后判定"后端未就绪"； stdout 只许输出协议行。
  调试：后端 stderr 会被宿主捕获并在报错里回显；iframe 的 console 在宿主 Electron 窗口的开发者工具（Ctrl+Shift+I）里看。 Own backend: declare backend: { "kind": "npm" }, ship server/server.js (Node; dependencies go in the plugin's own package.json / node_modules), and call it from the plugin with plugin.rpc; the host runs it as a separate child process and auto-restarts it on the next RPC after it exits.
  The protocol is stdio, one JSON line at a time: the host sends {"id","handler","payload"} and the plugin replies {"id","ok":true,"result":...} or {"id","ok":false,"error":"..."}; on startup it must write one line {"event":"ready"} to stdout, or the host reports "backend not ready" after 15 s; only protocol lines may go to stdout.
  Debugging: backend stderr is captured by the host and surfaced in error messages; the iframe's console is in the host Electron window's DevTools (Ctrl+Shift+I).
• 完整字段见仓库 docs/plugins/ui-plugin.md，宿主接入见 docs/api/webmin.md。 Full details: docs/plugins/ui-plugin.md and docs/api/webmin.md.

最小骨架（照此改即可，别漏掉最后那行 ready）： Minimal skeleton (adapt this, don't drop the final ready line):

'use strict';
const readline = require('readline');
const handlers = {
  ping: (payload) => ({ pong: (payload && payload.msg) || null }),
};
function send(obj) { process.stdout.write(JSON.stringify(obj) + '\n'); }
readline.createInterface({ input: process.stdin, crlfDelay: Infinity }).on('line', (line) => {
  const text = String(line || '').trim();
  if (!text) return;
  let req;
  try { req = JSON.parse(text); }
  catch (_) { send({ id: null, ok: false, error: '请求不是合法 JSON' }); return; }
  const fn = handlers[req.handler];
  if (!fn) { send({ id: req.id, ok: false, error: '未知 handler: ' + req.handler }); return; }
  try { send({ id: req.id, ok: true, result: fn(req.payload || {}) }); }
  catch (e) { send({ id: req.id, ok: false, error: String((e && e.message) || e) }); }
});
// ★ 必须：就绪握手，缺了它宿主会等 15 秒后判定"后端未就绪"
send({ event: 'ready' });