# YMhut Box 插件开发说明

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

## 最小插件包

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

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

## manifest 核心字段

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

```js
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 创建系统浏览器窗口。