模型与词表
MyPaste 只保留两个宿主表面:剪切坞的卡片网格与预览、设置面板。编辑器、图片处理、数据视图等一切具体界面,都由扩展自己实现。
接入层由三个概念组成:实体是一条有类型的剪贴板内容;接口是宿主暴露的 cmd API(命令级)与 gui API(页面级);注册表是按实体类型裁决「谁适配这个实体」的唯一位置。扩展可以是有 UI 的表面,也可以是纯命令的能力,关键区别只在有没有页面。
| 词 | 取值 / 作用 | 所有权 |
|---|---|---|
| kind | 封闭枚举 ui / command;省略时按 surface 或 menus 推导。 | manifest |
| forms | 实体类型,叶子或父类型;来自 internal/domain/forms.json 的唯一词表。 | 宿主 |
| surface.role | 封闭值 open / preview,只回答「页面接在哪个接入点」。 | 宿主 |
| placement | 封闭值 palette / card-action / trigger。 | 宿主 |
| role | 命令的宿主驱动共享动作,例如 backup-run;必须声明 trigger 与对应能力。 | 宿主 |
appliesTo / global / workbench / editor / renderer / data-action 都不是 v3 的展示位;它们只在兼容映射时出现,宿主不保留第二套词。
五分钟:最小命令包
目录名就是扩展 ID。一个命令包至少包含 manifest 与可执行入口;命令按本次调用的实体运行,输出由宿主校验后处理。
com.example.upper/
├── mypaste.plugin.json
└── run.sh # 可执行,独立子进程入口{
"manifestVersion": 3,
"kind": "command",
"id": "com.example.upper",
"name": "大写转换",
"version": "1.0.0",
"capabilities": ["entity.read", "entity.save"],
"runtime": {
"mode": "command",
"entrypoint": "run.sh"
},
"commands": [{
"id": "upper",
"title": "转成大写",
"forms": ["text"],
"output": ["text"],
"placement": ["card-action"],
"parameters": []
}]
}命令执行契约
- 宿主把当前实体交给子进程,收回受控输出;插件输出不是 HTML。
- 文本输出限制 1 MiB、校验 UTF-8、拒绝 NUL;剪贴板写入只经宿主
WriteAndBaseline。 - 参数最多 4 个,每个最多 12 个选项;
default必须是已声明选项。 - 显式写出
output且含text的无placement命令,才会进入命令面板。
命令扩展:无 UI 的能力
命令是「把实体交给逻辑,收回结果」。它可以出现在宿主的动作行、命令面板或后台触发,也可以不占界面、由别的表面通过注册表集成。
| 字段 | 契约 | 注意 |
|---|---|---|
| forms | 输入实体类型,叶子或父类型。 | 语言不是裁决键,SQL 与 PHP 都是 text。 |
| output | 产出实体类型;缺省与 forms 相同。 | 只有显式声明才算文本产出者。 |
| placement | palette、card-action、trigger。 | 没有 editor / workbench 等旧词。 |
| role | 宿主驱动的封闭共享命令角色。 | 带 role 必须声明 trigger 与对应能力;同 manifest 内一个角色只能出现一次。 |
| longRunning | 可选布尔,缺省 false。 | 声明即生效,调用预算从 10 秒放宽到 30 分钟。 |
三种 runtime 形态
command 按命令启动子进程;resident 常驻并带退避重启与失败上限;只有 menus、没有 surface 的 ui 包不需要 run.sh 与 runtime。无论哪种形态,第三方代码都不会加载进宿主进程。
一个格式化器不必做界面。声明作用于 text 的无 placement 命令,代码编辑器通过 registry 发现它并接入自己的工具栏。
表面扩展:一整页由你实现
表面扩展声明 surface 或 menus,页面入口随包携带。宿主负责挂载、把当前条目与解析后的主题送进 iframe,并校验所有回传消息。
{
"kind": "ui",
"capabilities": [
"entity.read", "entity.save",
"clipboard.write", "companion.read"
],
"surface": {
"entry": "preview.html",
"forms": ["text"],
"role": "open",
"chrome": "page"
}
}| surface 字段 | 契约 | 边界 |
|---|---|---|
| entry | 包内表面页面入口。 | 资产按条目 ID 经受控协议读取,不暴露路径。 |
| forms | 适配的实体类型。 | 注册表按类型裁决,不按语言或安装顺序。 |
| role | open 是「打开某实体」的目标;preview 渲染到卡片预览。 | 预览先画宿主正文,扩展只在一次显式选择后进入。 |
| chrome | 缺省 host;page 让页面画整块卡片。 | 仅 open 可用;宿主不裁剪 iframe,页面自画唯一关闭控件。 |
页面不能直接访问数据库、文件系统或系统剪贴板。它只按封闭角色调用动作,或原样回传宿主组合好的 plugin: 全局 ID;宿主每次都按当前 manifest 与授权重新解析。
容器线格式
表面页面与宿主容器只通过 postMessage 通信,每条消息都带 v: 1。这是页面能使用的全部控制通道,不含任意文件读取或进程执行。
| 页面 → 宿主 | 字段 | 宿主回答 |
|---|---|---|
| ready | 无 | 先回 item,随后回 theme |
| save | requestId、文本或图片 data URL | ok、id? |
| copy | requestId、文本或图片 data URL | ok |
| registry | requestId、1–8 个 forms | commands[] |
| invoke | requestId、pluginId、commandId、text | output?、diagnostics? |
| companion / close | requestId / 无 | item? / 无 |
{"v":1,"type":"item","item":{"kind":"text","text":"…"}}
{"v":1,"type":"theme","scheme":"dark","tokens":{…}}
{"v":1,"type":"result","requestId":"…","ok":true,"commands":[…]}theme 是宿主主动推送的一次性消息,不是可请求的服务。令牌名由 SURFACE_TOKEN_NAMES 声明一次,页面把值写成自己的 --mp-* 变量;未知键不读也不写。回答统一为 result,失败时 ok: false 并附宿主自己的错误消息。
封闭服务清单
服务清单没有高亮、格式化或语法检查,那些属于扩展自己。除功能服务按所有权保留外,能力对任何已安装且已启用的扩展开放;收窄一项能力必须说明命中的边界理由。
entity.read读当前实体的类型与受控内容。
entity.save保存为新条目,1 MiB / UTF-8 / 无 NUL。
copy经 WriteAndBaseline 写入剪贴板。
clipboard.write剪贴板写入能力。
entry.payload读条目的受控载荷。
secret.read读扩展自有的密钥。
network.outboundHTTPS、声明主机、宿主代理。
storage.plugin私有目录、配额、卸载即删除。
companion.read读本次调用的一条对照条目。
surface.network本包表面文档的远程媒体与 fetch CSP 策略。
backup.schedule立即备份或读排程摘要。
boards.control看板与成员关系的封闭动作组与导出。
saved-searches.control保存搜索的封闭动作组。
settings.data一级菜单数据页的封闭 call 方法组。
backup.sync不透明句柄、分块读写与 HTTPS 传输恢复。
data.read宿主打开只读连接,返回受限 SELECT 结果。
asset.read按条目 ID 返回 base64 资产分块。
数据库、资产、偏好、密钥的直接读写入口都不存在。data.read / asset.read 是批量只读入口,对任何已安装且已启用的包开放;宿主施加机械预算,扩展永远拿不到路径或句柄。
注册表、确定性与信任
注册表只按实体类型裁决,没有特异性、安装顺序或固定链。它是「谁适配这个实体」的唯一所有者。
| 命中数 | 行为 | 用户状态 |
|---|---|---|
| 0 | 宿主基线行为,例如 plain 文本用默认预览。 | 无选择 |
| 1 | 直接作为打开目标。 | 无选择 |
| ≥ 2 | 由用户选择;选择记为「用户拥有的默认值」。 | 记住默认值 |
resolve(entityType) 返回唯一处理者,list(entityType) 返回全部适配者供表面集成或宿主画选择器。预览接入点不自动采用扩展:选择不记忆,关闭预览或切换条目即回到宿主内容。
安装即信任
- 第三方代码永远在独立子进程里运行,
command按调用启动,resident常驻且有退避重启与失败上限。 - 安装对话框一次列清包来源、进程形态、危险能力与网络目的地;确认后只有一个启用 / 停用开关。
- 来源是安装事实:目录里
publisher标签(mypaste/ 仓库主机)只用于显示「由 MyPaste 组织发布」,不参与能力判断;宿主不钉住内容摘要、不内嵌包。 - 安装记录
builtin/marketplace/manual只回答来源与批量选择,publisher只回答发布方标签。
行为边界来自 manifest 的能力、展示位与封闭 role,结果按 Go 类型分派。宿主不按包 ID 或命令 ID 写特判,页面也不自己组合命令名。
打包与发布
发布的是可校验的包,不是一段能绕过宿主的安装脚本。索引地址由用户在宿主里配置,宿主在每次请求前重新校验地址,并且只从索引旁解析包 URL。
发布前检查
- manifest 只用
manifestVersion: 3;ID、版本、能力、入口与所有封闭枚举词都通过解析。 run.sh可执行;只有menus的ui包不声明多余 runtime。- 页面自测
ready → item / theme、保存、复制、关闭与result失败分支。 - 输出校验大小与 UTF-8;错误上下文不包含剪贴板正文、令牌或私密文件内容。
- 索引记录包 ID、名称、版本、kind、描述、文件名、SHA-256 与仓库地址;安装按目录里的 SHA-256 复核字节。
{
"version": 1,
"generated": "2026-11-20",
"packages": [{
"id": "com.example.upper",
"name": "大写转换",
"version": "1.0.0",
"kind": "command",
"fileName": "com.example.upper-1.0.0.mypaste-plugin",
"sha256": "…",
"repository": "https://github.com/…"
}]
}市场索引必须是绝对 HTTPS 地址,不带凭据、查询或片段;纯 HTTP 只对本机回环地址开放。页面永远不能让宿主去请求任意包 URL。
字段或行为与本文有出入时,以宿主实现和发布目录里的实际索引为准。
查看发布目录