YMhut Box 插件开发说明

YMhut Box 插件是本地 WebView 插件包，用来扩展工具箱工具或插件页。插件运行在宿主隔离的 WebView 中，通过 window.ymhut Bridge 请求能力；插件不能直接访问应用核心资源、任意文件路径或系统浏览器。

最小插件包

my-plugin/
  ymhut.plugin.json
  README.md
  index.html
  style.css
  main.js

README.md、README.txt 或 说明.md 必须存在。entry、resources 和 surface 入口都必须留在插件目录内，不能使用 ../ 逃逸。

manifest 核心字段

{
  "id": "hello-tools",
  "name": "Hello Tools",
  "version": "1.0.0",
  "author": "you",
  "description": "A local YMhut Box plugin",
  "entry": "index.html",
  "permissions": ["Output", "Log", "Storage", "OpenExternal"],
  "surfaces": [
    {
      "kind": "ToolboxTool",
      "id": "hello",
      "name": "Hello",
      "description": "Toolbox entry",
      "entry": "index.html",
      "category": "plugin"
    }
  ],
  "resources": ["index.html", "style.css", "main.js", "README.md"]
}

id 只允许字母、数字、点、短横线和下划线，不能以 plugin: 开头。工具箱挂载后的工具 ID 由宿主生成，格式是 plugin:<pluginId>:<surfaceId>。

权限

权限默认关闭。manifest 只声明插件需要什么，用户仍要在插件页启用插件并授予权限。

Input：读取或写入插件输入。
Output：写入宿主输出区。
Log：写入 plugin:<pluginId> 日志。
Storage：访问插件私有 key-value 状态。
Http：通过宿主请求 http/https。
Clipboard：读写剪贴板文本。
FilePicker：通过系统选择器打开或保存文件。
RunTool：调用允许的内置工具。
OpenExternal：打开 http/https 外链，默认进入安全浏览器。
NetworkDiagnostics：请求本机网络诊断能力。

Bridge

await window.ymhut.output.set("report");
await window.ymhut.storage.set("lastRun", JSON.stringify(data));
await window.ymhut.http.fetch({ url: "https://example.com/api" });
await window.ymhut.openExternal("https://example.com");
await window.ymhut.openExternal("https://example.com", { target: "system" });

普通外链默认进入 YMhut Box 安全浏览器。系统浏览器只作为显式动作使用，并继续受 OpenExternal 权限控制。

窗口与输出

插件内容区承载主 UI；宿主输出区用于报告、日志摘要、复制结果和调试信息。不要用输出区做主交互，也不要在插件页面使用全屏 fixed 遮罩、透明点击层或超高 z-index 覆盖宿主控件。

插件需要适配主窗口内嵌和独立窗口内容区。建议使用响应式网格、可滚动表格和清晰空态；不要假设窗口固定尺寸。

安全边界

插件 WebView 只允许加载插件目录内本地资源。非本地导航会被拦截并交给安全浏览器。插件不能覆盖内置工具 ID、应用图标、开发者信息、关于页核心身份或内置 Assets 路径。

网络结果、排行榜和第三方数据都应标明不确定性，并在失败时显示降级状态。

常见问题

加载失败：检查 manifest、README、entry 和 resources 是否存在且路径合法。
权限拒绝：检查 manifest 是否声明权限，以及插件页是否已授权。
外链打不开：只支持绝对 http/https URL，默认安全浏览器。
输出区遮挡：将输出区用于报告，不要用它承载主 UI。
独立窗口异常：不要调用浏览器弹窗 API 创建系统浏览器窗口。

3.5 KiB Raw Blame History