Developer Documentation · v3

写一份边界清楚的扩展

这份文档把 MyPaste 插件协议 v3 讲成一条可走通的路:声明 manifest,选择命令或表面形态,接入封闭服务,理解注册表裁决,再打包发布。字段与枚举以本文为准。

01 / MODEL

模型与词表

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 与对应能力。宿主
不要把 v2 词带进 v3

appliesTo / global / workbench / editor / renderer / data-action 都不是 v3 的展示位;它们只在兼容映射时出现,宿主不保留第二套词。

02 / QUICKSTART

五分钟:最小命令包

目录名就是扩展 ID。一个命令包至少包含 manifest 与可执行入口;命令按本次调用的实体运行,输出由宿主校验后处理。

v2/plugins/com.example.upper/
com.example.upper/
├── mypaste.plugin.json
└── run.sh # 可执行,独立子进程入口
mypaste.plugin.json
{
  "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 命令,才会进入命令面板。
03 / CMD API

命令扩展:无 UI 的能力

命令是「把实体交给逻辑,收回结果」。它可以出现在宿主的动作行、命令面板或后台触发,也可以不占界面、由别的表面通过注册表集成。

字段契约注意
forms输入实体类型,叶子或父类型。语言不是裁决键,SQL 与 PHP 都是 text。
output产出实体类型;缺省与 forms 相同。只有显式声明才算文本产出者。
placementpalette、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 发现它并接入自己的工具栏。

04 / GUI API

表面扩展:一整页由你实现

表面扩展声明 surface 或 menus,页面入口随包携带。宿主负责挂载、把当前条目与解析后的主题送进 iframe,并校验所有回传消息。

surface declaration · jsonc
{
  "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适配的实体类型。注册表按类型裁决,不按语言或安装顺序。
roleopen 是「打开某实体」的目标;preview 渲染到卡片预览。预览先画宿主正文,扩展只在一次显式选择后进入。
chrome缺省 host;page 让页面画整块卡片。仅 open 可用;宿主不裁剪 iframe,页面自画唯一关闭控件。
页面不是信任边界

页面不能直接访问数据库、文件系统或系统剪贴板。它只按封闭角色调用动作,或原样回传宿主组合好的 plugin: 全局 ID;宿主每次都按当前 manifest 与授权重新解析。

05 / BRIDGE

容器线格式

表面页面与宿主容器只通过 postMessage 通信,每条消息都带 v: 1。这是页面能使用的全部控制通道,不含任意文件读取或进程执行。

页面 → 宿主字段宿主回答
ready无先回 item,随后回 theme
saverequestId、文本或图片 data URLok、id?
copyrequestId、文本或图片 data URLok
registryrequestId、1–8 个 formscommands[]
invokerequestId、pluginId、commandId、textoutput?、diagnostics?
companion / closerequestId / 无item? / 无
host → page · ready 之后
{"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 并附宿主自己的错误消息。

06 / SERVICES

封闭服务清单

服务清单没有高亮、格式化或语法检查,那些属于扩展自己。除功能服务按所有权保留外,能力对任何已安装且已启用的扩展开放;收窄一项能力必须说明命中的边界理由。

entity.read

读当前实体的类型与受控内容。

entity.save

保存为新条目,1 MiB / UTF-8 / 无 NUL。

copy

经 WriteAndBaseline 写入剪贴板。

clipboard.write

剪贴板写入能力。

entry.payload

读条目的受控载荷。

secret.read

读扩展自有的密钥。

network.outbound

HTTPS、声明主机、宿主代理。

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 是批量只读入口,对任何已安装且已启用的包开放;宿主施加机械预算,扩展永远拿不到路径或句柄。

07 / REGISTRY & TRUST

注册表、确定性与信任

注册表只按实体类型裁决,没有特异性、安装顺序或固定链。它是「谁适配这个实体」的唯一所有者。

命中数行为用户状态
0宿主基线行为,例如 plain 文本用默认预览。无选择
1直接作为打开目标。无选择
≥ 2由用户选择;选择记为「用户拥有的默认值」。记住默认值

resolve(entityType) 返回唯一处理者,list(entityType) 返回全部适配者供表面集成或宿主画选择器。预览接入点不自动采用扩展:选择不记忆,关闭预览或切换条目即回到宿主内容。

安装即信任

  • 第三方代码永远在独立子进程里运行,command 按调用启动,resident 常驻且有退避重启与失败上限。
  • 安装对话框一次列清包来源、进程形态、危险能力与网络目的地;确认后只有一个启用 / 停用开关。
  • 来源是安装事实:目录里 publisher 标签(mypaste / 仓库主机)只用于显示「由 MyPaste 组织发布」,不参与能力判断;宿主不钉住内容摘要、不内嵌包。
  • 安装记录 builtin / marketplace / manual 只回答来源与批量选择,publisher 只回答发布方标签。
宿主不认识扩展的行为

行为边界来自 manifest 的能力、展示位与封闭 role,结果按 Go 类型分派。宿主不按包 ID 或命令 ID 写特判,页面也不自己组合命令名。

08 / PUBLISH

打包与发布

发布的是可校验的包,不是一段能绕过宿主的安装脚本。索引地址由用户在宿主里配置,宿主在每次请求前重新校验地址,并且只从索引旁解析包 URL。

发布前检查

  • manifest 只用 manifestVersion: 3;ID、版本、能力、入口与所有封闭枚举词都通过解析。
  • run.sh 可执行;只有 menus 的 ui 包不声明多余 runtime。
  • 页面自测 ready → item / theme、保存、复制、关闭与 result 失败分支。
  • 输出校验大小与 UTF-8;错误上下文不包含剪贴板正文、令牌或私密文件内容。
  • 索引记录包 ID、名称、版本、kind、描述、文件名、SHA-256 与仓库地址;安装按目录里的 SHA-256 复核字节。
index.json · shape
{
  "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。

字段或行为与本文有出入时,以宿主实现和发布目录里的实际索引为准。

查看发布目录