admin_gitea
c92f358774
完成天气胶囊在高 DPI 和窄窗口下的逐级降级布局，减少窗口拖动期间的主题与材质重建。新增三个停用的 manifest v3 插件示例、Tauri 伴随程序和构建哈希校验；旧版插件自动回收到可恢复目录。安装器升级成功后递归清理旧静态资源空目录，并补充相关文档和测试。
92 lines
4.6 KiB
Markdown
92 lines
4.6 KiB
Markdown
# 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。
|
||
|
||
`manifestVersion < 3` 的旧清单不再运行。扫描时插件会立即停用、清除授权和 WebView 缓存，并移动到 `data/PluginRecycle/legacy-<id>-<时间>-<随机值>` 以便恢复；迁移失败时保持隐藏并在下次扫描重试。缺失或损坏的清单不会被自动删除。升级步骤见 [MIGRATION-v3.md](MIGRATION-v3.md)，完整边界见 [SECURITY.md](SECURITY.md)，TypeScript 声明见 [ymhut.d.ts](ymhut.d.ts)。
|