QWQLwToo
91 lines
3.5 KiB
Markdown
91 lines
3.5 KiB
Markdown
# 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 创建系统浏览器窗口。
|