# YMhut Box manifest v3 插件

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

## 最小包

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

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

## manifest v3

```json
{
  "$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

```js
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](MIGRATION-v3.md)，完整边界见 [SECURITY.md](SECURITY.md)，TypeScript 声明见 [ymhut.d.ts](ymhut.d.ts)。