Connector 架构
Sync Vault 的内置能力之外,还有一条可插拔的扩展路径:Connector。它是一段你自己写的 JavaScript,把插件还不支持的外部地址接入现有的播放、时间戳与笔记体系。改动不需要重新编译插件,放进仓库后重新加载即可生效。
一个 Connector 是什么
Section titled “一个 Connector 是什么”一个 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)都会被加载执行,所以从第一行代码起就要考虑移动端没有本地代理。
三种扩展类型
Section titled “三种扩展类型”| 类型 | 负责的事 | 典型场景 |
|---|---|---|
video-source | 把网页地址解析成可播放的视频流 | B站、小红书、自建视频站 |
audio-source | 把网页地址解析成可播放的音频流 | RSS 播客、网络电台 |
agent-session | 在本机与受管仓库之间导出、恢复某家 Agent 的会话 | Qoder CLI 会话跨设备续接(仅桌面端) |
视频源与音频源共用同一种返回结构 MediaStreamInfo,直链、HLS、封面、分集这些能力对两者都适用;区别主要在宿主用哪个播放器承载,以及移动端能否使用代理(见 API 参考)。
同一个地址同时命中视频源和音频源时,宿主先问视频源,按视频处理。
一条地址如何变成可播放的流
Section titled “一条地址如何变成可播放的流”flowchart LR A["笔记里的地址"] --> B{"按目录名顺序询问 match(url)"} B -- 命中 --> C["connector.resolve"] C <-->|"ctx.request"| D["平台接口 / 源站"] C --> E["MediaStreamInfo"] E --> F["播放器"] B -- 都不命中 --> G["内置逻辑 / 明确报错"]- 加载:扫描
connectors/,校验manifest.json,求值main.js,调用create(ctx)得到实例并注册。 - 匹配:一个外部地址进入播放链路时,宿主按目录名升序逐个调用
match(url),第一个命中的 Connector 全权负责这个地址。 - 解析:
resolve(url)里通过ctx.request调用平台接口,返回MediaStreamInfo。请求走宿主通道,不受浏览器 CORS 限制。 - 播放:之后就是普通播放链路——清晰度切换、封面、分集、播放进度、时间戳标注都不区分来源。
- 生命周期:重新加载或停用插件时调用
dispose();视频地址过期时宿主会再次调用resolve()(每个播放器最多 2 次)。
失败会明确暴露:一旦某个 Connector 命中,解析失败不会回落到内置逻辑,也不会换下一个 Connector,而是直接把错误交给用户并写入日志。
加载、重载与失败隔离
Section titled “加载、重载与失败隔离”- 目录名既是 Connector 的
id,也决定加载与匹配顺序;manifest.id必须与目录名一致。 - 单个 Connector 加载失败只影响它自己:其他 Connector 和插件本体照常启动;失败原因显示在「Connector 管理」卡片里,也写入日志。
- 重新加载会先调用旧实例的
dispose()再重新create(),不会让新旧两份实例同时存在。 - 停用由目录内的
.disabled标记控制:停用的 Connector 不求值、不参与匹配,但文件与settings.json全部保留;卸载才会删除整个目录。
在仪表盘里安装
Section titled “在仪表盘里安装”- 打开 Sync Vault 仪表盘,在工作台点右下角 ➕,从 Widget 库添加 Connector 管理 卡片。
- 点卡片底部的 安装,粘贴
manifest.json的地址;GitHub 页面链接会自动转换为 raw 地址。 - 也可以点 选择文件,在本地同时选中
manifest.json与main.js。 - 安装完成后可在列表里 启用 / 停用 / 卸载;点 重新加载 可重新扫描手动放入目录的 Connector。
安装只写入 manifest.json 与 main.js。与已有 Connector 同 id 时会覆盖这两个文件,settings.json 保留;原本处于停用状态的不会因为安装自动启用。
手动放入目录
Section titled “手动放入目录”把 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-video | video-source | 公开可访问的直链 / HLS 视频 |
bilibili | video-source | B站地址与分P,需要防盗链头,仅桌面端 |
xiaohongshu | video-source | 小红书视频笔记,桌面端与移动端都可播 |
web-audio | audio-source | 公开可访问的直链 / HLS 音频 |
rss-podcast | audio-source | RSS 播客与 Apple Podcasts 链接,支持选集 |
qoder | agent-session | Qoder CLI 会话导出、恢复,仅桌面端 |
例如在安装框里粘贴:
https://github.com/abcamus/sync-vault-connector-sdk/blob/main/examples/bilibili/manifest.json插件会同时拉取同目录下的 main.js。
- 编写你的第一个 Connector —— 从目录、manifest 到 resolve 的完整步骤。
- Connector API 参考 —— 字段、生命周期,以及桌面端与移动端的差异。