3. 双向 JSON-RPC 2.0 通信协议
所有请求与响应均为单行 UTF-8 JSON(末尾 \n)。
3.1 宿主调用插件(Host -> Plugin)
plugin.initialize- 请求
params:json{ "plugin_id": "example-sync", "data_dir": "/abs/path/to/apps-data/example-sync", "downloads_dir": "/Users/name/Downloads", "notebook_root": "/abs/path/to/notebook", "notebooks": ["/abs/path/to/notebook", "/abs/path/to/other-notebook"], "locale": "zh", "theme": "system", "tarot": false, "host_version": "1.0.854", "ui_capabilities": [ "kv_tooltip", "treemap", "host_perf", "checklist", "form_layout", "multi_notebook", "card_collapse", "metric_tone", "log_columns", "file_picker", "action_feedback", "action_progress", "note_revision", "sidebar_sections", "file_badges", "sidebar_menu", "backdrops", "status_icon", "toast_icon", "notes_open", "log_actions", "panel_toggle", "editor_insert_mode", "dialog_token", "checklist_add_folder", "item_icons" ] }- 运行时上下文:
notebook_root仅在声明notes:read、notes:write或events:note_saved任一权限且目标笔记本非空时传入,否则为"";notebooks仅在声明notes:read时填充,否则为[]。切换桌面笔记本不会立刻重启全部插件,仅在下次调用该插件且目标根目录与当前运行时上下文不同(含后台note.saved事件)时,宿主才关闭旧进程并按新notebook_root重新初始化。 downloads_dir(默认~/Downloads,环境变量BLOCKMD_DOWNLOADS_DIR):凡涉及导出文件、备份归档或清理转移的目录,一律默认输出到downloads_dir(单文件直接输出到downloads_dir/<文件名>,多文件收拢到一个干净文件夹内,严禁默认塞进apps-data隐藏目录或在笔记本内新建.trash-*等隐藏目录)。ui_capabilities可能在旧宿主中省略,用于渐进启用特性:kv_tooltip(kv行提示)、treemap(空间分布图控件)、host_perf(host.perf.snapshot;注意本地 CLI 校验器尚未注入性能回调,调用会返回-32005,插件应做降级处理)、checklist(多选勾选列表)、checklist_add_folder(checklist.add_folder加号添加文件夹)、form_layout(layout与group)、multi_notebook(多笔记本列表与读写)、card_collapse(卡片折叠)、metric_tone(metrics[].tone柔和色板)、log_columns(log_list对齐列、sub_text/ratio/tone/tooltip与→映射模式)、file_picker(folder.accept_extensions)、action_feedback(plugin.action的ok/tone与内联/按钮反馈)、action_progress(host.action.progress)、note_revision(revision/expected_revision乐观并发)、sidebar_sections(左侧栏插件分区)、file_badges(文件树行尾角标)、sidebar_menu(左侧栏文件树右键菜单)、backdrops(编辑区自定义矢量背景)、status_icon(底部状态栏图标)、toast_icon(Toast 图标)、notes_open(host.notes.open跳转打开笔记)、log_actions(log_list条目点击触发action_id)、panel_toggle(host.ui.toggle_panel原子切换侧栏面板)、editor_insert_mode(host.editor.insert支持"mode": "insert"|"replace"非破坏插入)、dialog_token(host.ui.open_dialog返回宿主确认句柄dialog_token)、item_icons(switch/kv行前置图标icon与icon_strip图标条)。
- 运行时上下文:
- 返回
result:{"ready": true}。
- 请求
plugin.render- 请求
params:例如{"surface": "settings_page", "values": {"protocol": "webdav"}}。- 首次打开、切换笔记本/当前笔记/笔记本列表、动作前表单补刷、定时轮询及
note.saved成功后刷新时省略values。 - 用户在界面编辑控件时(离散控件约 25ms 防抖,文本输入约 220ms 防抖),
values仅包含用户尚未同步的改动字段。将这些字段合并到持久配置后生成预览;需要显式提交的表单由plugin.action保存。
- 首次打开、切换笔记本/当前笔记/笔记本列表、动作前表单补刷、定时轮询及
- 返回
result:包含必填page(严格解码)与可选values。- 值合并规则:
- 首次加载、笔记本/活动笔记/笔记本列表变化触发的重载、编辑预览刷新与动作前表单补刷都会消费
result.values(更新表单并清除对应字段的未同步标记)。 - 定时轮询(
refresh_interval_ms)与note.saved成功后的刷新忽略result.values,但仍会用新page的控件默认值更新未被用户编辑的键(!editedControls)。 - 编辑预览刷新中,新
page的控件默认值只补全缓存里尚不存在的新键(已存在的键以用户编辑态或result.values为准)。
- 首次加载、笔记本/活动笔记/笔记本列表变化触发的重载、编辑预览刷新与动作前表单补刷都会消费
- 值合并规则:
- 请求
plugin.action- 用户点击页面按钮时触发。注意:本地校验器会调用初始
UIPage中的全部header_actions与卡片顶层actions按钮(不判断visible_when与卡片折叠状态),需避免默认配置下触发非预期外部副作用。 - 请求
params:json{ "surface": "settings_page", "action_id": "save_config", "values": { "protocol": "local_mirror", "mirror_dir": "/Users/name/Sync", "selected_notebooks": ["/Users/name/Notes/Work"] } }values为宿主缓存的整份表单值(覆盖segmented、select、input、folder、secret、switch、checklist,含group内子控件,也可能残留当前隐藏、已移除或插件此前回传的键);插件应按当前有效分支读取并合并持久化到host.storage.set。 - 返回
result(字段均可选;page若返回须为完整合法UIPage对象,见第 4 节):json{ "ok": true, "tone": "success", "values": { "protocol": "local_mirror" }, "status": "已同步 2 篇笔记", "open_path": "/Users/name/Downloads/欢迎使用 Block.html", "reveal_path": "/Users/name/Downloads/欢迎使用 Block.html" }- 表单更新顺序:若同时返回
page与values,宿主先用新page的控件默认值覆盖对应键,再应用result.values并清除对应字段的未同步标记;若page.status为空且result.status非空,宿主自动将result.status填入page.status。 - 动作反馈(
ok/tone/status):合法tone("success"|"warning"/"warn"|"danger"/"error"|"info")优先级最高;未知或空tone回退按ok判定(true为success,false为danger);两者均省略时按status关键词推断,未命中默认"success"。卡片内按钮返回danger/warning且status非空时,在按钮上方显示提示条,success/info在按钮旁显示单行状态;header_actions在顶栏展示状态。success态按钮会短暂切换为绿色勾选态(2.4s);action_id为test_conn、以test_开头或以_test结尾的连接测试按钮会保持成功态,直到用户修改表单或触发下一次动作。 - 打开与定位输出文件(
open_path/reveal_path):切勿在插件内自行调用open/xdg-open子进程。宿主会先对路径做Clean归一化,再验证目标已存在且位于downloads_dir内,且downloads_dir之下的相对路径组件及目标均不得为符号链接(downloads_dir本身及其祖先不在逐段检查范围内),不满足则静默忽略。open_path禁止打开.app目录,且普通文件仅允许.html、.htm、.pdf、.txt、.md、.markdown、.csv、.tsv、.png、.jpg、.jpeg、.webp、.gif、.docx、.xlsx、.pptx;其余格式(如.zip)请使用reveal_path(Linux 下对文件打开其父目录)。即便ok: false,宿主仍会处理非空路径,因此失败动作应省略这两个字段。
- 表单更新顺序:若同时返回
- 用户点击页面按钮时触发。注意:本地校验器会调用初始
plugin.event(保存事件需声明"events:note_saved",系统事件见 3.3 节)- 请求
params:{"event": "note.saved", "notebook_root": "/abs/path/to/notebook", "path": "welcome.md", "timestamp": "2026-11-18T10:00:00Z"} - 仅投递给已启用的订阅插件,由已接入该钩子的落盘入口(块编辑保存与其他插件通过
host.notes.write产生的实际变更,不含写入者自身,不包含源码编辑保存分支)触发;timestamp为每次派发/重试时的 UTC 时间。插件应以事件参数自带的notebook_root与path为准。 - 宿主按
(plugin_id, notebook_root, 绝对路径)合并排队(处理期间同文件再次保存会再排一次,跨文件无全局顺序保证)。 - 响应要求:宿主会将
result解码为{"handled": <bool>}(返回{"handled": true}、{"handled": false}或{}均视为成功;返回非对象如true或错误类型如{"handled": "false"}会因解码失败报错)。业务失败须返回 JSON-RPCerror,宿主才会在侧栏标错并在空闲、同路径未重新排队且无更高优先错误时展示重试入口(可能来自另一笔记本)。成功后若该笔记本已有缓存页且无忙碌动作,宿主会自动触发plugin.render刷新(即使当前未停留在插件页)。
- 请求
plugin.shutdown- 请求
params:{} - 宿主发出
plugin.shutdown前已将运行时标为关闭并停止受理反向host.*调用,因此关闭阶段切勿调用host.storage.set等宿主 RPC。推荐直接返回{"ok": true}(宿主不校验响应内容),随后在 2 秒内正常退出。
- 请求
3.2 插件调用宿主能力(Plugin -> Host)
插件在处理 plugin.initialize、plugin.render、plugin.action 或 plugin.event 请求期间,可向 stdout 发送 JSON-RPC 请求调用 host.*,并从 stdin 读取匹配 id 的响应后再返回外层结果(同时在途不超过 8 个;plugin.shutdown 期间宿主不再响应 host.*)。
常见错误码:-32001 缺少权限、-32002 存储失败或超 8 MiB、-32003 列举笔记失败(含未注册笔记本)、-32004 笔记文件系统错误(含文件打开/读写失败、路径下存在符号链接或超 16 MiB)、-32005 性能快照回调不可用或返回错误、-32006 编辑器脏状态/虚拟预览或版本冲突、-32601 未知方法、-32602 参数无效(含 read/write 未注册笔记本或参数路径不合规)。
笔记路径边界:支持扩展名 .md、.markdown、.mdown、.mkd、.mkdn、.mdwn、.mdtxt、.mdtext、.mdx(不区分大小写)。显式 notebook_root 会去空白并转绝对路径后与已注册笔记本精确匹配;省略时使用当前运行时上下文根。host.notes.list 跳过 . 开头项与非普通文件;host.notes.read/write 先对相对路径做 Clean 归一化,参数层校验须位于笔记本内、无 :、无 . 开头路径段且为支持后缀(不合规则报 -32602),文件系统层打开时拒绝符号链接且限制旧文件/读取 <= 16 MiB(失败报 -32004)。
host.storage.get(需"storage")- 参数解码失败按空对象处理。单键:
{"key": "config"}-> 命中{"value": {"auto_sync": true}, "found": true},未命中{"value": null, "found": false};全量:{}->{"data": {"config": {"auto_sync": true}}}。
- 参数解码失败按空对象处理。单键:
host.storage.set(需"storage"){"key": "config", "value": {"auto_sync": true}}->{"ok": true}。key须为非空白字符串(否则-32602);省略value会存成null。host.storage.set_many使用同一权限和 8 MiB 限制。{"values": {"config": {...}, "migration": null}}一次写入 1–64 个非空白键,成功返回{"ok": true}。
host.notes.active(需"notes:read",忽略参数){}->{"path": "welcome.md"}(返回宿主缓存的活动标签相对路径,可能为空、非 Markdown 或尚未更新)。
host.notebooks.list(需"notes:read",忽略参数){}->{"notebooks": [{"path": "/abs/path/to/notebook", "name": "notebook", "active": true}]}(active反映当前运行时上下文根,建议配合checklist控件勾选范围)。
host.notes.list(需"notes:read"){"notebook_root": "/abs/path/to/notebook"}(可选;解码失败按省略处理;省略且运行时根为空时返回[];传未注册笔记本报-32003)->{"notes": [{"path": "welcome.md", "size": 42, "mod_time": "2026-11-18T10:00:00Z"}]}
host.notes.read(需"notes:read"){"notebook_root": "/abs/path/to/notebook", "path": "welcome.md"}(notebook_root可选,省略且运行时根为空报-32602;path必填)->{"path": "welcome.md", "content": "# 欢迎...", "revision": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"}
host.notes.write(需"notes:write"){"notebook_root": "/abs/path/to/notebook", "path": "notes/synced.md", "content": "# 内容", "expected_revision": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"}->{"ok": true, "changed": true}(示例哈希须替换为host.notes.read实际返回的revision,原样传固定值会在实际写入时触发-32006)。- 必须始终显式传入字符串
content(省略或null会按空字符串写入);content需满足单行 4 MiB 传输预算。 - 冲突与幂等判定顺序:
- 桌面端先检查编辑器会话:若目标笔记存在未保存修改或处于虚拟预览,直接返回
-32006(即使目标字节相同;此类冲突需用户先保存或退出预览)。 - 读取磁盘旧文件并逐字节比较:若文件已存在且内容完全相同,直接返回
{"ok": true, "changed": false}(即使expected_revision为""或旧哈希,也不报错、不写盘、不记历史、不触发事件)。 - 核对
expected_revision:省略或传null跳过校验;传""要求文件尚不存在;传读取时的 64 位小写 SHA-256 哈希则要求磁盘当前内容匹配,否则返回-32006(不提供对外部写入进程的原子 CAS)。
- 桌面端先检查编辑器会话:若目标笔记存在未保存修改或处于虚拟预览,直接返回
- 实际写入时原子落盘、尽力记录「插件保存」版本历史、刷新干净的编辑器标签页并向其他订阅插件派发
note.saved。响应不含新revision,连续修改前请重新host.notes.read。
host.notes.open(需"notes:read"){"notebook_root": "/abs/path/to/notebook", "path": "welcome.md"}(notebook_root可选;严格校验目标为已注册笔记本内的合法普通 Markdown 文件且非符号链接)-> 在桌面编辑器中切换打开目标笔记(若设置页开着会自动收起)并返回{"ok": true, "path": "welcome.md"};无 UI 宿主环境(如 CLI 校验)返回-32005。
host.action.progress(无需额外权限;须先在plugin.initialize的ui_capabilities中检查"action_progress",旧宿主不支持时不得发送)- 在
plugin.action执行期间实时上报进度,推荐以 JSON-RPC 2.0 通知(省略id,无需等待响应,宿主走内联快速通道以保证顺序且不占并发槽)发送,也支持普通调用(返回{"ok": true}):- 计数模式:
{"done": 12, "total": 48}(total > 0,宿主在标题栏运行胶囊中展示12/48) - 百分比模式:
{"progress": 0.32}(0.0–1.0,仅在未传total时生效,宿主在标题栏运行胶囊中展示32%) - 可选
label覆盖运行动词(最多 32 字符;默认由宿主按action_id推断,如同步中/迁入中/上传中)
- 计数模式:
- 空载荷或无效参数不会覆盖当前进度;动作结束或取消时宿主自动清空进度,并在内部节流重绘(保留首帧与末帧)。
- 在
host.perf.snapshot(需"notes:read"){"refresh_disk": false}(可选,解码失败按false;仅在宿主尚无磁盘扫描缓存时,传false才会触发首次扫描,内置性能窗口可能已生成缓存)-> 返回宿主资源与 7 类磁盘占用摘要(分类 ID:notes、assets、history、recovery、ai_sessions、logs、config;每类entries最多前 6 条摘要;scan_error、file_count、entries与明细path/count可省略;磁盘扫描异常写在成功响应的scan_error中,仅回调不可用或失败时返回-32005):json{ "cpu_percent": 1.2, "rss_bytes": 125829120, "total_bytes": 52428800, "last_scan": "01:00:00", "categories": [ { "id": "notes", "label": "笔记", "detail": "Markdown 正文", "bytes": 10485760, "file_count": 128, "entries": [ { "name": "Work", "path": "/abs/path/Work", "bytes": 5242880, "count": 64 } ] } ] }
3.3 系统集成
桌面宿主在 plugin.initialize.ui_capabilities 中提供 "system_integration"。host.system.capabilities {} 无需额外权限,返回布尔值对象,字段为 notify、notify_click、secrets、open_url、reveal、open_dialog、save_dialog、clipboard_read、clipboard_write、trash、badge、wake、network、focus。结果反映当前桌面可用性,实际调用还受清单权限、系统授权和服务状态影响。
| 接口 | 权限 | 参数与返回 |
|---|---|---|
host.system.notify | system:notify | {"title":"同步失败","body":"打开同步设置查看详情。","tone":"error"}。title 和 body 必填,分别截断至 80 和 240 字符。可传 notebook_root 指定已注册笔记本内的插件设置,或同时传 rel_path 指定 Markdown 笔记,需 notes:read。可用 timeout_ms 缩短等待时间,默认 15000 毫秒。可传最长 128 字节的 dedup_key 区分文案及目标相同的独立事件,同一事件重试时沿用原值。Block 有焦点时显示应用内提示,否则请求系统通知。桌面支持通知点击时,打开目标笔记或插件设置。排队返回 {"ok":false,"queued":true,"delivered":false}。宿主显示提示、提交至系统通知服务,或识别到同一事件已经送达时返回 delivered:true。需要跨重启补送的插件应保留待发记录,直至收到 delivered:true。重复或过频的提示返回 suppressed:true。 |
host.system.open_url | system:open | {"url":"https://example.com"},仅接受无账号和密码的 HTTP(S) 链接。 |
host.system.reveal | system:open、notes:read | {"rel_path":"assets/example.png","notebook_root":"/abs/notebook"},在系统文件管理器里显示文件。 |
host.system.open_dialog、host.system.save_dialog | system:dialogs | 可传 title、default_path、extensions。打开框另支持 directory、multiple。选目录时省略 extensions。返回 {"ok":true,"paths":["/abs/file"],"canceled":false},用户取消时 paths 为空。发起动作取消或超时会关闭选择框并返回 -32007。 |
host.clipboard.read、host.clipboard.write | system:clipboard_read、system:clipboard_write | 读取传 {},返回 {"ok":true,"text":"..."}。写入传 {"text":"..."}。支持最多 64 KiB UTF-8 文本。 |
host.system.trash | system:trash、notes:write | 与 reveal 参数相同,仅支持普通文件。用户在原生确认框确认后,宿主移到系统回收站并更新相关标签页。 |
host.system.badge | system:badge | {"count":3},范围 0–999,0 清除本插件角标。宿主合计已启用插件的数值,上限 999。 |
host.secrets.get、host.secrets.set、host.secrets.delete | system:secrets | {"key":"auth.token"},写入另传 value(1–1536 字节,无 NUL)。键以 ASCII 字母或数字开头,后续允许字母、数字、.、_、-,总长最多 128 字符。读取返回 {"ok":true,"found":true,"value":"..."} 或 {"ok":true,"found":false}。删除支持重复调用。宿主按应用数据目录、插件 ID 和安装来源隔离凭据。缺少宿主安装来源记录时,凭据接口返回不可用。 |
其余写操作成功返回 {"ok":true}。打开网页、定位文件、文件选择、剪贴板和回收站操作需要由用户触发的 plugin.action,且 Block 窗口有焦点。授权随动作结束或切换笔记本而失效。笔记本路径使用 / 分隔,相对路径须指向可见项目,路径组件须为真实文件或目录。省略 notebook_root 时使用运行时笔记本。系统能力不可用时返回 -32005,繁忙时返回 -32006,操作取消或失效时返回 -32007。前台提示队列满时,通知调用返回 -32006,插件可保留原事件并重试。窗口切到后台时,排队的系统提醒可转为原生通知。转发失败的提醒暂存至窗口恢复焦点,后续提醒仍可投递。宿主生成的 Sync 失败提醒投递失败后,可在提示队列腾出空间或应用恢复焦点时补送。补送前复查插件身份和 Sync 通知开关。
events:system 通过 plugin.event 接收 system.wake、network.changed、app.focus。事件包含 event 和 UTC timestamp,唤醒和网络变化包含系统报告的 online 布尔值。需要笔记权限或保存事件权限才能收到 notebook_root。宿主可启动已启用的订阅插件,并按插件串行处理,排队中的同类事件只保留最新一条。network.changed 涵盖系统报告的状态变化和检测到的网卡地址变化。服务器可达性由插件自行判断。
macOS 使用通知中心、钥匙串和 Dock。macOS 通知的点击目标可跨 Block 重启保留七天,点击时重新检查安装状态和权限。Windows 使用系统通知、凭据管理器和任务栏叠加角标,通知点击依赖系统横幅仍然有效。Linux 使用桌面通知服务、Secret Service 和兼容 Unity Launcher 协议的 Dock,唤醒事件依赖 logind。Linux 需要通知服务支持 actions 才能点击通知,notify_click:false 时仍可能显示通知。Linux 系统凭据需在系统凭据管理器中先解锁。单次运行最多保留最近 128 条插件原生通知。系统选择框已打开时,原生后端可能需要用户关闭窗口,宿主会丢弃已过期动作的选择结果。缺少相应服务时,插件应根据能力查询或调用错误调整界面和行为。
回收确认前,宿主先保存正在编辑的内容。确认后,宿主记录恢复位置,将文件移到同卷的暂存目录并复核文件身份。Block 数据目录与原文件分处不同卷时,暂存目录建在原文件旁。Windows 还需要文件所在卷支持硬链接。条件不满足时保留原文件。回收失败时优先恢复原路径,原路径已被占用时保留暂存文件。系统「还原」会将文件放回暂存目录。Block 会保留原路径记录,启动时提示可恢复文件及其原路径。凭据权限约束宿主 RPC,独立插件进程仍以当前系统用户运行,其直接访问由操作系统控制。
4. 声明式 UI Schema(UIPage)精确定义
同一 UIPage 内:所有 card.id 唯一、所有表单控件 item.id 唯一、所有按钮 button.id(含 header_actions 与 actions 项)唯一。宿主已在设置窗口标题栏与插件页头部统一提供面包屑、单行合并状态位、主操作位、拨弦启用开关(Pluck Switch)与「⋯」更多菜单(含次要操作、查看说明/应用商店、重新加载与红色卸载),插件无需自己声明开关、取消任务按钮或卸载按钮。
UIPage 顶层最小可复制示例
{
"title": "示例同步",
"status": "上次同步 14:20",
"header_actions": [
{ "id": "sync_now", "label": "立即同步", "variant": "primary" }
],
"cards": [
{
"id": "target-card",
"title": "存储目标",
"items": [
{
"kind": "segmented",
"id": "protocol",
"label": "存储目标",
"value": "local_mirror",
"options": [
{ "value": "local_mirror", "label": "目录镜像" },
{ "value": "webdav", "label": "WebDAV" }
]
}
]
}
]
}title:必填非空字符串(桌面设置标题栏展示manifest.name,但UIPage.title仍须提供)。status:可选只读次级状态短文本(仅展示真实执行结果、配置摘要或最近运行时间,闲置或未配置时传"";严禁写"已就绪"/"已启用"/"已停用"/"迁入中…"等占位或运行中文案)。progress:可选0–1浮点数,用于声明式独立后台任务在空闲轮询刷新时展示百分比进度;plugin.action执行期间请使用host.action.progress。cards:必填,最多 64 张卡片;所有卡片的items合计最多 400 项。refresh_interval_ms:可选定时刷新间隔(500–60000毫秒,0或省略表示不自动轮询;仅在最近绘制时间窗口内且空闲时触发)。header_actions:可选标题栏动作按钮数组;每项含id(必填唯一)、label(必填)、variant(仅限"primary"|"secondary"|"danger")。宿主将首个variant: "primary"放在标题栏主操作位(运行中自动变为带进度与■取消按钮的胶囊),其余secondary/danger/ 多余按钮自动收进标题栏⋯菜单顶部。cards:必填非空数组;每项含id(必填唯一)、title(可选)、meta(可选右侧副信息)、badge(可选右侧胶囊徽章)、collapsible/default_collapsed(可选折叠配置卡片,展开状态保存在当前控制器内存中)、items(必填非空数组;若卡片内所有顶层项均被visible_when隐藏,整个卡片自动隐藏)。
14 种 UIItem 控件(按 kind 区分)
交互与布局准则
- 选择本地文件夹使用
folder,需要同时允许选文件时附加accept_extensions(如[".zip"]);远端路径和分支等文本使用input并给合理默认值;单项下拉用select,多选列表(如勾选多个笔记本)用checklist。 - 离散控件(
switch、segmented、select、checklist、folder)切换后建议立即在plugin.render中持久化并通过result.values回传,不要强制用户再点「保存」;仅在包含远端地址、密钥等多项文本输入时提供「测试连接 / 保存」按钮。 - 涉及多笔记本同步或批量处理的插件,不要扫描并列出全部笔记本:声明
ui_capabilities含"checklist_add_folder"时,用add_folder: true的checklist只展示用户通过右上角加号主动添加的文件夹,只对列表内的文件夹执行操作;旧宿主缺少该能力时回退为host.notebooks.list加普通checklist勾选。 layout合法值为""|"stacked"|"full":"stacked"由segmented/folder/input/secret消费,"full"仅segmented消费(且此时可省略label)。- 柔和色板键(用于
metrics[].tone、log_list占比条与treemap.tiles[].color):"assets"(绿)、"config"(蓝)、"notes"(靛紫)、"history"(紫)、"recovery"(青)、"logs"(红)、"ai_sessions"(琥珀),省略或未知值回退中性底色。
任意 UIItem(含 group.fields 子项)均支持可选字段 visible_when,按其他控件当前值零延迟动态显隐(control_id 必填,至少提供 equals 或非空 in;in 为字符串数组且非空时优先于 equals;equals: true 与 equals: "true" 按 JSON 类型严格区分;未知 control_id 视为隐藏;若需按条件隐藏整组避免卡片只剩空标题,请将 visible_when 写在 group 上):
{
"visible_when": { "control_id": "protocol", "equals": "webdav" }
}或匹配多个字符串值:
{
"visible_when": { "control_id": "provider", "in": ["r2", "s3"] }
}segmented(分段切换,适合 2–3 个短选项):id必填,label在layout != "full"时必填,options至少 2 项(每项value与label必填非空),value(string)必须命中某个options[].value,可选layout(""|"stacked"|"full"):json{ "kind": "segmented", "id": "protocol", "label": "存储目标", "value": "local_mirror", "options": [ { "value": "local_mirror", "label": "目录镜像" }, { "value": "webdav", "label": "WebDAV" }, { "value": "git", "label": "Git 仓库" } ] }select(下拉选单):id、label必填,options至少 1 项(每项value与label必填非空),value(string)必须命中某个options[].value,placeholder可选。input(单行文本输入框):id、label必填,value必须为string,placeholder、layout(""|"stacked")可选:json{ "kind": "input", "id": "endpoint_url", "label": "服务器地址", "value": "", "placeholder": "https://dav.example.com/dav" }folder(本地文件夹 / 可选文件选择器):id、label、value必填,value传完整路径或"";可选layout(""|"stacked")与accept_extensions(非空字符串数组如[".zip"]且宿主提供文件选择器时,额外显示文件选择按钮)。目录选择器允许新建目录,完整路径通过悬停提示展示;对话框默认打开当前绝对路径或笔记本根,切换笔记本会丢弃旧选择。注意:accept_extensions仅为系统对话框过滤提示,宿主不复核选中路径后缀,插件处理前须自行校验文件类型与内容:json{ "kind": "folder", "id": "source_path", "label": "导入目录或压缩包", "layout": "stacked", "value": "", "accept_extensions": [".zip"] }secret(密码/凭证输入框):字段同input,value必须为string(宿主自动掩码并支持显示/隐藏切换)。switch(布尔开关):id、label必填,value必须为bool(宿主统一使用 Ocean Paper Pluck Switch 渲染):json{ "kind": "switch", "id": "auto_sync", "label": "保存笔记后自动同步", "value": true }icon(可选,需"item_icons"能力;kv的每行rows[].icon同理):行首图标。二选一:{"name": "<宿主内置图标名>"}(小写字母、数字与-,未知名称渲染为空白),或与DuoIconSpec同形的内联矢量{"view_box": "0 0 24 24", "stroke_paths": [...], "fill_paths": [...], "accent_paths": [...]};可加tooltip。第三种为文字胶囊{"chip": "统一发送", "dot": true}(chip最多 16 字,dot加强调圆点,不可与图标字段混用):行首只绘制圆点,icon_strip中绘制为顶栏同款胶囊。host.titlebar.get_items返回的items[].icon可直接透传。
actions(卡片内操作按钮行):不含id/label,仅含非空buttons数组:json{ "kind": "actions", "buttons": [ { "id": "save_config", "label": "保存配置", "variant": "primary" }, { "id": "test_conn", "label": "测试连接", "variant": "secondary" } ] }metrics(多列数据指标宫格):不含id/label,仅含非空metrics数组(每项label、value必填非空,tone可选,取值见柔和色板键;宿主按数量与视口宽度自动渲染为 1–4 列等宽卡片):json{ "kind": "metrics", "metrics": [ { "label": "笔记篇数", "value": "128", "tone": "notes" }, { "label": "附件体积", "value": "14.2 MB", "tone": "assets" } ] }kv(只读状态键值行):rows为非空数组,每行label与value均必填非空。若ui_capabilities包含kv_tooltip,可加tooltip在悬停时展示补充信息(勿放密码或令牌):json{ "kind": "kv", "rows": [ { "label": "当前笔记本", "value": "团队笔记", "tooltip": "/Users/name/Documents/团队笔记" } ] }preview(实时视觉预览卡片):不含id/label,必填preview对象:variant:"article"(最多显示 14 条非空行)|"cards"(每卡最多 5 条非空行;cards为空时回退article)|"diff"(before/after/body各最多 6 条非空行)|"plan"(默认,最多 10 条非空行)palette:可选"ocean"(默认)|"paper"(浅色纸感)|"ink"(暗色墨夜)|"warm"(暖纸衬线)。article/cards/diff按所选纸面绘制;plan在深色主题下若选paper或warm,列表改跟应用底色,避免浅色字落在白底上。title:必填;badge、subtitle可选body:多行正文("article"支持#、##、>、[1]脚注行)before/after:用于"diff"对照文本cards:用于"cards"的卡片数组[{"badge": "封面", "title": "...", "body": "..."}]
json{ "kind": "preview", "preview": { "variant": "article", "palette": "paper", "title": "实时排版预览 · 欢迎使用 Block", "badge": "海盐纸感 · 单文件 HTML", "subtitle": "欢迎使用 Block.html", "body": "# 欢迎使用 Block\n## 核心特性\n> 模块化无侵入插件体系" } }log_list(运行记录 / 队列 / 占比列表):empty_text必填非空,label可选,entries可为空数组。每项title必填,其余可选:sub_text:标题旁的次级说明status/time:右侧自动对齐的等宽列;若全部条目均传"status": "→",宿主切换为title → time双栏映射样式(隐藏sub_text与前导状态点,保留占比条与tooltip)tone:前导状态点支持语义色("success"|"warning"/"warn"|"danger"/"error"|"info"/"accent")与柔和色板键;ratio占比条仅使用柔和色板键(传"success"等语义色会回退中性底色)ratio:约定传0–1浮点数(<= 0不画条,> 0渲染时夹到4%–100%并隐藏前导状态点)tooltip:整行悬停提示action_id:可选点击动作 ID(ui_capabilities含log_actions时生效,<= 128 字符、禁止 Emoji;点击该行时触发当前表面的plugin.action,常配合host.notes.open实现侧栏/面板一键跳转笔记)
json{ "kind": "log_list", "empty_text": "暂无同步记录", "entries": [ { "title": "welcome.md", "sub_text": "Work", "time": "12:30", "status": "成功", "tone": "success" } ] }checklist(多选勾选列表):id必填,label、empty_text可选,value为已选string[](省略或null归一化为[],不会在解码时过滤旧选项值),options每项含value(必填唯一)、label(必填)及可选detail/badge/tooltip;多于 1 项时宿主自动提供「全选 / 取消全选」。注意checklist只能放在卡片顶层,不能放入group。add_folder(可选bool,仅限checklist,需"checklist_add_folder"能力):改为「用户添加的文件夹列表」。宿主在卡片标题栏右上角(或控件自身标题行右侧)显示加号按钮,点击弹出系统目录选择器;选中的目录会登记为宿主笔记本(不切换当前笔记本,host.notes.*因此可访问),以绝对路径追加到value并立即触发plugin.render。列表只渲染value中存在对应options的项,每行没有勾选框,行尾提供移除按钮(仅从value移除,不会删除笔记本或文件)。插件应让options只包含value内的路径;value为空时显示empty_text:json{ "kind": "checklist", "id": "selected_notebooks", "add_folder": true, "value": ["/Users/name/Notes/Work"], "empty_text": "点击右上角 + 添加要同步的文件夹", "options": [ { "value": "/Users/name/Notes/Work", "label": "Work", "detail": "~/Notes/Work", "tooltip": "/Users/name/Notes/Work" } ] }- 普通勾选列表示例:
json{ "kind": "checklist", "id": "selected_notebooks", "value": ["/Users/name/Notes/Work"], "empty_text": "暂无已打开的笔记本", "options": [ { "value": "/Users/name/Notes/Work", "label": "Work", "badge": "当前", "detail": "~/Notes/Work", "tooltip": "/Users/name/Notes/Work" } ] }group(并排表单分组):fields至少包含 2 个表单项(仅允许input、secret、segmented、select、folder、switch),宿主自动并排展示;未显式设layout(或layout: "")的子项默认按"stacked"排布(switch仍横排),各子项可独立声明visible_when。treemap(磁盘/空间分布图,固定 Bento 布局按字节排序,非严格面积比例):tiles为必填非空数组,id(同页有多个图时须显式传不同id以免共享选中状态)、total_bytes(非负整数uint64,0或省略时取各瓦片bytes之和)、summary可选:json{ "kind": "treemap", "id": "storage-map", "total_bytes": 15728640, "summary": { "total_label": "总占用", "total_value": "15.0 MB", "sub_text": "共 2 类数据", "metrics": [{ "label": "文件数", "value": "140" }] }, "tiles": [ { "id": "notes", "label": "笔记", "detail": "Markdown 正文", "bytes": 10485760, "file_count": 120, "color": "notes", "entries": [ { "name": "Work", "path": "/abs/path/Work", "bytes": 6291456, "count": 72 } ] }, { "id": "assets", "label": "附件", "detail": "图片与文档", "bytes": 5242880, "file_count": 20, "color": "assets" } ] }其中
total_bytes与两级bytes均为无符号整数(负数或小数会解码失败);summary若存在,total_value必填(summary.metrics[].tone可解码但渲染不消费);每个tile的id(唯一)与label必填,color默认取tile.id(柔和色板键);每条entries的name必填,path/count可选(count <= 0汇总时按1计数)。icon_strip(图标条预览,需"item_icons"能力):不含id,icons为图标数组(格式同switch.icon,最多 32 个,可各带tooltip),宿主按顺序右对齐绘制成顶栏样式的一行;label可选(显示在左侧),icons为空时显示可选的empty_text。不能放入group:json{ "kind": "icon_strip", "icons": [{ "name": "message-square", "tooltip": "反馈" }, { "name": "more", "tooltip": "页面操作" }], "empty_text": "未显示任何图标" }
5. Python 标准库双向通信骨架
#!/usr/bin/env python3
import json
import sys
if hasattr(sys.stdin, "reconfigure"):
sys.stdin.reconfigure(encoding="utf-8")
if hasattr(sys.stdout, "reconfigure"):
sys.stdout.reconfigure(encoding="utf-8")
class HostRPCError(RuntimeError):
def __init__(self, code, message):
super().__init__(message)
self.code = code
self.message = message
class HostBridge:
def __init__(self):
self._seq = 1000
def send(self, obj):
sys.stdout.write(json.dumps(obj, ensure_ascii=False) + "\n")
sys.stdout.flush()
def notify_host(self, method, params=None):
self.send({"jsonrpc": "2.0", "method": method, "params": params or {}})
def call_host(self, method, params=None):
self._seq += 1
req_id = f"p-{self._seq}"
self.send({"jsonrpc": "2.0", "id": req_id, "method": method, "params": params or {}})
while True:
line = sys.stdin.readline()
if not line:
raise RuntimeError("stdin closed while awaiting host response")
msg = json.loads(line)
if str(msg.get("id")) == req_id:
if "error" in msg and msg["error"]:
err = msg["error"]
raise HostRPCError(err.get("code", -32000), err.get("message", "host error"))
return msg.get("result", {})
def serve(self, handler):
while True:
line = sys.stdin.readline()
if not line:
break
line = line.strip()
if not line:
continue
req = json.loads(line)
method = req.get("method")
req_id = req.get("id")
try:
result = handler(self, method, req.get("params") or {})
self.send({"jsonrpc": "2.0", "id": req_id, "result": result})
if method == "plugin.shutdown":
break
except Exception as exc:
self.send({"jsonrpc": "2.0", "id": req_id, "error": {"code": -32000, "message": str(exc)}})