MYTOOLBOX · DEVELOPER PLATFORM

第三方模块开发者手册

使用 HTML、CSS 和 JavaScript 构建工作模式卡片，并通过宿主管理的 Bridge、按需授权、独立加密和七天审计接入 MyToolbox 能力。

当前协议Schema 12 · 兼容 Schema 1–11

12当前 Schema

3运行表面

100 MB安装包上限

512包内文件上限

QUICK START

从一个离线可见的卡片开始。

最小模块是以 .mytoolbox-workmodule 结尾的文件夹。首屏必须在无网络、无 Cookie、未授权环境中仍能显示可理解的 UI。

建立包结构

创建 manifest.json 与 index.html；settings.json 和 assets 为可选内容。

声明稳定身份

使用永久反向域名 identifier、语义版本、双语名称、SF Symbol 和安全相对入口。

实现离线首屏

页面在四秒内显示文字、按钮、输入框、图片、SVG 或 Canvas，不以空白等待授权。

通过公开 Bridge 调用

使用 window.mytoolbox.request；权限由 operation 决定，manifest 不直接授予能力。

验证生命周期

处理拒绝、离线、停止、重载和 mytoolbox-plugin-stop，并取消计时器与请求。

导入并核对

在插件中心检查自动识别权限、运行表面、审计、加密数据和签名身份。

PACKAGE

最小包结构

运行期 Cache 与 Data 由宿主建立，不应预先放入发行包。绝对路径、符号链接和 .. 路径穿越会被拒绝。

Example.mytoolbox-workmodule/
├── manifest.json
├── index.html
├── settings.json          # 可选，生成原生设置
└── assets/                # 可选，包内静态资源

MANIFEST

Schema 12 清单

清单描述身份、表面、入口、尺寸、介绍、命令和受控宿主能力；第三方 permissions 自述不会直接获得授权。

{
  "schemaVersion": 12,
  "identifier": "dev.example.weather",
  "version": "1.0.0",
  "runtime": "web",
  "names": {"zh-Hans": "城市天气", "en": "City Weather"},
  "summaries": {"zh-Hans": "当前天气", "en": "Current weather"},
  "symbol": "cloud.sun",
  "entryPoint": "index.html",
  "preferredHeight": 220,
  "supportedSurfaces": ["floatingWindow", "menuBar", "horizontalStrip"],
  "cardSizing": {"mode": "content", "minHeight": 120, "maxHeight": 520},
  "minimumAppVersion": "0.4.0"
}

身份与入口

identifier 永久不变且不能与内置或已安装模块重复
version 使用语义版本
runtime 第三方固定为 web
entryPoint 必须是包内安全相对路径
names 与 summaries 建议同时提供 zh-Hans 和 en

表面与响应式布局

supportedSurfaces 支持 floatingWindow、menuBar、horizontalStrip
horizontalLayout 可为横版提供独立入口和宽高边界
adaptiveLayout 允许宿主在响应式重排后做受限微缩
cardSizing.content 由宿主 ResizeObserver 测量语义内容

平台能力

presentation 提供介绍、多图、联系方式和版权
commandCenter 最多声明 24 个结构化指令
services 声明受控 macOS 服务
dataTransfer 管理加密便携数据
updateActions 仅允许声明式 Data/Cache 迁移

UI & LIFECYCLE

插件只负责内容，宿主负责卡片与生命周期。

标题栏、排序、置顶、设置、收起、关闭、键盘焦点和媒体终止由 MyToolbox 统一管理。真实 WKWebView 不参与卡片位置动画。

右侧浮窗

适合纵向信息流和持续可见的轻量工具；内容宽度通常在 330–600pt。

状态栏弹窗

适合短任务和快速查询；非置顶时会随外部点击或 App 失焦收起。

横版窗口

位于 Dock 上方并水平滚动；可提供 260–520pt 宽、160–300pt 高的专用入口。

停止事件

收到 mytoolbox-plugin-stop 后取消网络、计时器、媒体和后台任务，旧结果不得继续回填。

CONTROLLED BRIDGE

一个 Promise 接口，按操作映射权限。

调用已知 operation 时，宿主在运行期核对总策略、单插件授权、数据锁定和审计；动态拼接或压缩源码不能绕过检查。

const result = await window.mytoolbox.request(
  "currency.snapshot",
  {}
);

OperationPermissionPurpose

clipboard.recent / writeTextclipboardRead / clipboardWrite

读取最近剪贴板或写入指定文本

translation.history / executetranslationRead / translationExecute

读取翻译历史或执行当前翻译源

currency.snapshotcurrencyRead

读取 MyToolbox 本地汇率快照

notes.recentnotesRead

读取最近记事，不开放任意改写

favorites.recent / asset.read / importfavoritesRead / favoritesWrite

通过 ID 和 Base64 安全代理收藏内容

vault.index / entriesvaultMetadataRead / vaultSecretRead

元数据与私密字段使用不同授权

network.fetchnetwork

通过无 Cookie、无缓存的宿主临时 HTTPS 会话访问

external.file.readfilePickerRead

只读取用户选择或长期授权的单个文件

plugin.window.* / appearance.*nativeWindow / appearance

请求宿主管理窗口或受限视觉 token

network.relay.* / packet.*networkRelayControl / packetRelayControl

受审计的中转或临时分段流

AUTHORIZATION

界面先出现，能力在调用点决定。

用户可以允许一次、始终允许或永不允许。永不允许后，插件只能引导用户前往授权管理，不能自行重复弹框。

01整个软件加密已开启并处于解锁状态
02全软件离线模式没有阻断当前网络操作
03信任模式允许当前官方、认证或第三方身份运行
04插件中心总开关已开启
05对应全局权限上限没有关闭
06当前插件已取得这一项单独授权
07私密权限的全局验证仍有效
08密钥串使用专属密钥时已经完成第二次验证

ENCRYPTED STORAGE

Cache 可重建，Data 代表重要状态。

每个插件使用从软件主密钥与永久插件 ID 经 HKDF 派生的独立 AES-GCM 密钥；JavaScript 永远拿不到文件密钥或真实路径。

await window.mytoolbox.request("plugin.cache.write", {
  path: "Responses/latest.json",
  base64: encoded
});

await window.mytoolbox.request("plugin.data.write", {
  path: "Preferences/state.bin",
  base64: encoded
});

Cache 单次最多 64 MB，可被电脑优化安全清理
Data 单次最多 32 MB，不参与电脑优化扫描
路径必须是插件目录内的安全相对路径
设置、书签和七天审计同样使用插件独立密钥
锁定软件时删除临时解密目录并停止运行时

TRUST & SECURITY

签名决定身份，不决定无限权限。

官方、认证开发者和普通第三方使用不同信任级别，但总开关、全局权限上限、离线模式和单插件授权仍然有效。

Ed25519 签名覆盖规范 manifest 与全部发行文件
私钥只写入用户选择的外部目录并使用 0600 权限
同标识更新不能更换开发者或降低签名身份
更新失败自动恢复旧版本，成功后保留一代加密快照
认证原生伴随进程必须完整签名、启用 App Sandbox 并通过命令白名单
宿主不会向 Web 或伴随进程暴露 Shell、真实文件路径、书签、密码或密钥