YMhut-box-C-/docs/plugins/README.md

YMhut Box manifest v3 插件

本地 HTML/CSS/JavaScript 是默认插件运行时。DOM、ES Module、Worker、Wasm、Canvas、WebAudio、localStorage 和 IndexedDB 不需要客户端权限，但仅存在于该插件自己的虚拟 HTTPS 原点中。客户端、系统、文件选择器、宿主存储、网络代理和外部服务能力只能通过 window.ymhut Bridge 使用。

最小包

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

插件包不能包含符号链接、目录联接或原生可执行文件。entry、surface 入口和资源必须位于包目录内。

manifest v3

{
  "$schema": "../../../docs/plugins/ymhut.plugin.schema.json",
  "manifestVersion": 3,
  "apiVersion": "2",
  "id": "hello-tools",
  "name": "Hello Tools",
  "version": "1.0.0",
  "author": "you",
  "description": "A local WebView plugin",
  "entry": "index.html",
  "runtime": "WebView",
  "requirements": {
    "minimumClientVersion": "2.0.6.2",
    "minimumWindowsBuild": 17763,
    "architectures": ["X64", "Arm64"]
  },
  "permissions": ["Http", "Output"],
  "permissionReasons": {
    "Http": "Read data from the declared public API.",
    "Output": "Write the user-requested result to the host output panel."
  },
  "security": { "requiredPermissions": ["Http"] },
  "network": {
    "allowedOrigins": ["https://api.example.com"],
    "openExternalOrigins": [],
    "runToolIds": []
  },
  "surfaces": [{
    "kind": "ToolboxTool",
    "id": "hello",
    "name": "Hello",
    "description": "Toolbox entry",
    "entry": "index.html",
    "category": "plugin"
  }],
  "resources": ["index.html", "style.css", "main.js", "README.md"]
}

每项权限必须同时出现在 permissions 和 permissionReasons。security.requiredPermissions 中的权限未授权时插件不能启用；其余权限为可选权限，未授权时 Bridge 返回稳定错误码。权限用途、必需状态、范围、运行时或插件版本改变会使旧授权指纹失效。

Http 必须声明精确 network.allowedOrigins；仅允许公网 https:// 或 wss:// 原点，不允许路径、通配符、HTTP、localhost、局域网或私网。OpenExternal/OpenSystemBrowser 使用 openExternalOrigins，RunTool 使用 runToolIds。

Bridge

const response = await window.ymhut.http.fetch({
  url: "https://api.example.com/data",
  method: "GET"
});
await window.ymhut.output.set(response.content);

协议为 PluginHostProtocol v2。每个 surface 会话绑定插件 ID、surface ID、虚拟原点和一次性令牌。插件脚本无法选择或伪造令牌。单消息上限 256 KiB，每会话最多 64 个并发调用，统一超时 30 秒；宿主 HTTP 响应上限 2 MiB。

常用稳定错误码：permission_not_declared、permission_not_granted、permission_scope_denied、network_denied、session_invalid、payload_too_large、concurrency_limit、timeout。

Web 安全边界

• 每个 surface 使用独立的 https://p-<hash>.plugin.ymhut.invalid 原点和独立 WebView2 数据目录。
• 本地脚本、内联脚本、ES Module、Worker、Blob 和 Wasm 可用。
• 远程脚本、样式、字体、iframe、对象、导航、新窗口、下载、外部拖放和浏览器敏感权限被拒绝。
• 页面直接 fetch/WebSocket 与 ymhut.http.fetch 使用同一来源白名单；宿主 fetch 可兼容无 CORS API。
• 系统浏览器需要 OpenSystemBrowser，且每次调用都由宿主确认。
• Shell、Script、PowerShell、Node、Python 和插件自带原生程序不受支持。

运行时与独立窗口

WebView 是默认和正式运行时。Tauri 独立窗口仅使用应用自带宿主，默认关闭；它要求插件开发者模式、ExternalRuntime 授权和按插件版本保存的二次确认。Tauri 插件内容运行在独立的 https://p-<hash>.localhost 原点和插件私有 WebView2 数据目录中，应用宿主页只通过一次性、当前用户命名管道把 Bridge 请求转发给同一个权限宿主。会话令牌仅存在于原生宿主内，不进入插件 JavaScript。插件包不能携带或构建原生可执行文件，也不能访问 Tauri 全局 API。

旧清单自动降级为 LegacyWebOnly：本地 Web 内容可运行，Bridge、远程连接和外接运行时全部关闭。迁移步骤见 MIGRATION-v3.md，完整边界见 SECURITY.md，TypeScript 声明见 ymhut.d.ts。