跳转到内容

Connector 架构

Sync Vault 的内置能力之外,还有一条可插拔的扩展路径:Connector。它是一段你自己写的 JavaScript,把插件还不支持的外部地址接入现有的播放、时间戳与笔记体系。改动不需要重新编译插件,放进仓库后重新加载即可生效。

一个 Connector 就是一个目录,包含两个文件:

<vault>/.obsidian/plugins/sync-vault-ce/connectors/my-connector/
├── manifest.json 元信息:id、类型、契约版本
└── main.js 入口:导出一个 create(ctx) 函数
  • 运行时加载:插件启动时扫描 connectors/ 目录;也可以随时在命令面板执行 重新加载用户 Connectors,改完 main.js 不必重启 Obsidian。
  • 与本体的边界:main.js 是自包含的 CommonJS 单文件,运行时没有 require,也不能使用 Node / Electron API。发请求、读写自己的设置、写日志这些能力都由宿主通过 ctx 注入。
  • 两端同一份代码:Connector 在桌面端和移动端(iOS / Android)都会被加载执行,所以从第一行代码起就要考虑移动端没有本地代理。
类型负责的事典型场景
video-source把网页地址解析成可播放的视频流B站、小红书、自建视频站
audio-source把网页地址解析成可播放的音频流RSS 播客、网络电台
agent-session在本机与受管仓库之间导出、恢复某家 Agent 的会话Qoder CLI 会话跨设备续接(仅桌面端)

视频源与音频源共用同一种返回结构 MediaStreamInfo,直链、HLS、封面、分集这些能力对两者都适用;区别主要在宿主用哪个播放器承载,以及移动端能否使用代理(见 API 参考)。

同一个地址同时命中视频源和音频源时,宿主先问视频源,按视频处理。

flowchart LR
A["笔记里的地址"] --> B{"按目录名顺序询问 match(url)"}
B -- 命中 --> C["connector.resolve"]
C <-->|"ctx.request"| D["平台接口 / 源站"]
C --> E["MediaStreamInfo"]
E --> F["播放器"]
B -- 都不命中 --> G["内置逻辑 / 明确报错"]
  1. 加载:扫描 connectors/,校验 manifest.json,求值 main.js,调用 create(ctx) 得到实例并注册。
  2. 匹配:一个外部地址进入播放链路时,宿主按目录名升序逐个调用 match(url),第一个命中的 Connector 全权负责这个地址。
  3. 解析:resolve(url) 里通过 ctx.request 调用平台接口,返回 MediaStreamInfo。请求走宿主通道,不受浏览器 CORS 限制。
  4. 播放:之后就是普通播放链路——清晰度切换、封面、分集、播放进度、时间戳标注都不区分来源。
  5. 生命周期:重新加载或停用插件时调用 dispose();视频地址过期时宿主会再次调用 resolve()(每个播放器最多 2 次)。

失败会明确暴露:一旦某个 Connector 命中,解析失败不会回落到内置逻辑,也不会换下一个 Connector,而是直接把错误交给用户并写入日志。

  • 目录名既是 Connector 的 id,也决定加载与匹配顺序;manifest.id 必须与目录名一致。
  • 单个 Connector 加载失败只影响它自己:其他 Connector 和插件本体照常启动;失败原因显示在「Connector 管理」卡片里,也写入日志。
  • 重新加载会先调用旧实例的 dispose() 再重新 create(),不会让新旧两份实例同时存在。
  • 停用由目录内的 .disabled 标记控制:停用的 Connector 不求值、不参与匹配,但文件与 settings.json 全部保留;卸载才会删除整个目录。
  1. 打开 Sync Vault 仪表盘,在工作台点右下角 ➕,从 Widget 库添加 Connector 管理 卡片。
  2. 点卡片底部的 安装,粘贴 manifest.json 的地址;GitHub 页面链接会自动转换为 raw 地址。
  3. 也可以点 选择文件,在本地同时选中 manifest.json 与 main.js。
  4. 安装完成后可在列表里 启用 / 停用 / 卸载;点 重新加载 可重新扫描手动放入目录的 Connector。

安装只写入 manifest.json 与 main.js。与已有 Connector 同 id 时会覆盖这两个文件,settings.json 保留;原本处于停用状态的不会因为安装自动启用。

把 Connector 目录整体拷贝到:

<vault>/.obsidian/plugins/sync-vault-ce/connectors/<connector id>/

然后在命令面板执行 重新加载用户 Connectors。移动端不方便直接访问插件目录,推荐使用上面的安装入口(从 URL 或本地文件均可)。

WARNING

只安装你信任的 Connector Connector 代码在插件内直接执行,拥有与插件相同的权限,并且可以通过宿主通道发起网络请求。不要安装来源不明的 Connector。

官方 SDK 仓库附带一组可直接安装的示例:https://github.com/abcamus/sync-vault-connector-sdk

示例类型说明
web-videovideo-source公开可访问的直链 / HLS 视频
bilibilivideo-sourceB站地址与分P,需要防盗链头,仅桌面端
xiaohongshuvideo-source小红书视频笔记,桌面端与移动端都可播
web-audioaudio-source公开可访问的直链 / HLS 音频
rss-podcastaudio-sourceRSS 播客与 Apple Podcasts 链接,支持选集
qoderagent-sessionQoder CLI 会话导出、恢复,仅桌面端

例如在安装框里粘贴:

https://github.com/abcamus/sync-vault-connector-sdk/blob/main/examples/bilibili/manifest.json

插件会同时拉取同目录下的 main.js。