Connector API 参考
本页是 Connector 契约 0.4 的参考。契约的唯一事实来源是插件仓库的 src/connector/def.ts;SDK 的 index.d.ts 由它自动生成,两者不会漂移。
配套 npm 包:@sync-vault/connector-sdk(只含类型与本地调试工具,不含运行时代码)。
npm install --save-dev @sync-vault/connector-sdk- 当前契约版本:
0.4。 - 判定兼容只看
apiVersion的第一段数字:宿主是0.4,0.4.x、0.2.9都算兼容;1.x不兼容。 - 0.3 新增分集相关字段,0.4 新增
audio-source类型,都是只加可选能力的扩展,旧 Connector 无需修改。
<vault>/.obsidian/plugins/sync-vault-ce/connectors/<connector id>/├── manifest.json 必填├── main.js 必填└── settings.json 可选,由 ctx.getSettings / saveSettings 读写- 插件启动时扫描一次;之后可在命令面板执行 重新加载用户 Connectors。
- 扫描按目录名升序,也就是注册与匹配顺序。
- 单个 Connector 加载失败不影响其他 Connector 与插件启动;失败原因显示在「Connector 管理」卡片并写入日志。
- 重新加载会先
dispose()旧实例,再重新create();插件停用时也会dispose()所有 Connector。 - 停用通过目录内的
.disabled标记实现:文件与设置全部保留,但该 Connector 不求值、不参与匹配。卸载才会删除整个目录。
manifest.json
Section titled “manifest.json”| 字段 | 必填 | 说明 |
|---|---|---|
id | 是 | 唯一标识,必须与目录名一致;只允许 [a-z0-9-_],且以字母或数字开头 |
name | 是 | 展示名 |
version | 是 | Connector 自己的版本号 |
apiVersion | 是 | 目标契约版本,如 0.4 |
type | 是 | video-source、audio-source 或 agent-session |
description | 否 | 一句话说明 |
author | 否 | 作者 |
homepage | 否 | 仓库或主页地址 |
字段缺失、id 非法、id 与目录名不一致、类型不支持、apiVersion 首段不匹配,都会导致加载失败并给出明确原因。
main.js
Section titled “main.js”必须是单文件 CommonJS:
module.exports = { create(ctx) { return { // 按 type 实现对应方法 }; },};- 不能用 ESM 的
import/export;宿主按 CJS 单文件求值。 - 运行时没有
require:node_modules、Node 内置模块都不可用,能力一律从ctx取。 - 顶层代码在加载时执行一次;
create(ctx)可以是async。 - 用 TypeScript 或拆分多文件时,把依赖一起打包进单个
main.js(SDK 的templates/ts有现成配置)。
ctx:宿主注入的能力
Section titled “ctx:宿主注入的能力”| 成员 | 说明 |
|---|---|
id | 本 Connector 的 id |
dir | 本 Connector 在 vault 内的目录路径 |
platform | { isDesktop, isMobile },用于按端降级 |
request(options) | 网络请求,走宿主通道,不受浏览器 CORS 限制 |
log | debug / info / warn / error,写入 Sync Vault 日志 |
getSettings<T>() | 读取 settings.json;文件不存在返回 null |
saveSettings(obj) | 写入 settings.json(缩进 2 的 JSON) |
desktop | 桌面专属的 vault 外文件通道;移动端为 undefined |
request
Section titled “request”const resp = await ctx.request({ url: 'https://api.example.com/x', method: 'GET', // 可选,默认 GET headers: { 'Referer': 'https://example.com' }, // 可选 body: JSON.stringify(payload), // 可选,string | ArrayBuffer});
resp.status; // numberresp.headers; // Record<string, string>,键名小写resp.text; // stringresp.json; // any,访问时才解析resp.arrayBuffer; // ArrayBuffer- 非 2xx 不抛错:返回
status由 Connector 自己判断;断网、DNS 等网络层失败才会抛错。 - 响应体是惰性读取的,不要假设可以重复读取大文件。
settings.json
Section titled “settings.json”适合放 token、Cookie 这类配置。它是 vault 里的普通文件,明文存储,会随同步与分享流转;不要把长期密钥硬编码在 main.js 里。
video-source
Section titled “video-source”interface VideoSourceConnector { match(url: string): boolean; resolve(url: string, onProgress?: (message: string) => void): Promise<MediaStreamInfo>; dispose?(): void | Promise<void>;}match(url):地址是否交给本 Connector。宿主会同步调用,必须廉价,不要在里面发请求。- 多个 Connector 都命中时,目录名升序的第一个生效;命中的 Connector 完全负责该地址。
resolve(url, onProgress):解析为可播放流。onProgress的文案会显示在播放器加载层。- 解析失败必须抛出明确错误。宿主不会回落到内置解析、不会换下一个 Connector,也不会静默当作直链播放。
- 地址过期时宿主会以同一 URL 再次调用
resolve,因此实现必须可重复调用。
MediaStreamInfo
Section titled “MediaStreamInfo”| 字段 | 必填 | 说明 |
|---|---|---|
url | 是 | 要播放的地址 |
urlType | 是 | direct:单个地址;m3u8-list:HLS 播放列表地址 |
mediaType | 是 | raw:直链,播放器直接播放;hls:交给 hls.js / 原生 HLS |
mediaInfo | 是 | 可用清晰度列表,至少一项 |
headers | 否 | 播放时随请求发送的头 |
proxy | 否 | true 表示直链经宿主本地代理转发,需要与 headers 一起返回才生效 |
coverUrl | 否 | 封面图 |
cursor | 否 | 上次播放位置(秒) |
parts | 否 | 分集列表 |
currentPartIndex | 否 | 本次解析对应的分集下标,缺省 0 |
cleanup | 否 | 这份流被替换或播放器销毁时调用的清理函数 |
mediaInfo 每项:
| 字段 | 必填 | 说明 |
|---|---|---|
url | 是 | 该清晰度的地址 |
resolution | 是 | 清晰度展示名,如 1080P、自动 |
width / height | 是 | 像素尺寸,用于播放器初始比例;未知时填 0 |
| 其余 | 否 | duration / codec / frameRate / audioCodec / sampleRate / fileSize |
约定:
streamInfo.url应与mediaInfo中某一项的url相同,该项的resolution会被当作当前清晰度。resolution: '原画'有特殊含义:切换到该清晰度时播放器走直链路径(销毁 hls.js,直接把地址设到<video>上)。HLS 流不要用「原画」,否则切到这个清晰度就无法按 HLS 播放。
分集(parts)
Section titled “分集(parts)”return { url: current.playUrl, urlType: 'm3u8-list', mediaType: 'hls', mediaInfo: [{ url: current.playUrl, width: 0, height: 0, resolution: '自动' }], parts: [ { name: 'P1 开场', url: 'https://www.bilibili.com/video/BV1xx411c7mD?p=1' }, { name: 'P2 正片', url: 'https://www.bilibili.com/video/BV1xx411c7mD?p=2' }, ], currentPartIndex: 1,};parts至少 2 项时才展示选集;单集可以省略。- 宿主切换分集时会用该分集的
url再次调用resolve,所以每个url都必须能被match/resolve正常处理。 currentPartIndex表示本次解析的是第几集;即使请求的?p=非法而回退了实际分集,也应如实返回实际下标。- 分集在宿主内是独立条目:各自记录播放进度与标注锚点,一集播完自动续播下一集。
过期重取与清理
Section titled “过期重取与清理”平台返回的播放地址通常有有效期(带签名的 CDN 链接等)。宿主的兜底逻辑:
- 播放中遇到 401 / 403 / 404 / 410 时,以同一 URL 再次调用
resolve,拿到新地址后跳回原播放位置续播。 - 每个播放器最多自动重取 2 次;重取成功且 1 分钟内不再过期,额度会归还。
- 一份
MediaStreamInfo被替换(过期重取、切换视频)或播放器销毁时,宿主调用它的cleanup()。一次性资源(定时器、本地服务、临时订阅)请挂在cleanup上;跨多份流存活的资源放在实例的dispose里。
音频源目前不做过期重取,见下一节。
audio-source
Section titled “audio-source”interface AudioSourceConnector { match(url: string): boolean; resolve(url: string, onProgress?: (message: string) => void): Promise<MediaStreamInfo>; dispose?(): void | Promise<void>;}方法形状、匹配顺序、错误语义与视频源完全一致,宿主用音频播放器承载结果。差异:
- 音频没有分辨率,
mediaInfo每项填width: 0、height: 0,resolution用原画或展示名。 - 同一个地址同时命中视频源与音频源时按视频处理:宿主先问视频源,视频源都不命中才问音频源。
- 不做过期重取:播放中地址失效时宿主不会再次调用
resolve,请返回时效足够长的地址。 parts会按顺序连播;选集列表在播放器侧栏展示(对音频块右键 打开侧栏),内嵌播放器本身没有选集按钮。cleanup的兑现时机与视频源一致。
agent-session
Section titled “agent-session”把某家 Agent 的本机会话导出到受管仓库,在其他设备恢复到本机继续。宿主负责受管仓库、版本游标与跨设备分发,Connector 只负责该 Agent 的存储布局与恢复方式。
interface AgentSessionConnector { probe(): Promise<AgentSessionProbeResult>; discover(): Promise<AgentSessionRef[]>; export(ref: AgentSessionRef): Promise<AgentSessionBundle>; stage(bundle: AgentSessionBundle, env: DeviceEnv): Promise<ResumePlan>; watch?(ref: AgentSessionRef, onChange: () => void): () => void;}probe/discover/export/stage四个方法缺一即拒绝加载。stage(bundle, env)把数据包写回本机对应位置,返回恢复指引ResumePlan(恢复命令、建议 cwd、注意事项),不自动执行命令。- 数据包内是相对路径;含
..、绝对路径或反斜杠的条目会被宿主拒绝。 watch是可选增强;不实现时,回流检测由宿主按游标(nativeMtime/nativeSize)对比完成。- 仅桌面端:vault 之外的文件读写一律走
ctx.desktop,移动端该通道为undefined。移动端只能查看已加入同步的会话。
完整示例见 SDK 的 examples/qoder。
proxy、headers 与跨域
Section titled “proxy、headers 与跨域”防盗链(需要 Referer 等头)的地址,把 proxy: true 与 headers 一起返回:
- 桌面端:直链经
127.0.0.1的本地代理转发,带上这些头,同时补上跨域响应头。 - 移动端:没有本地代理。
proxy: true退化为直连,直链的headers不生效,依赖防盗链头的地址会 403。请在resolve里主动判断并抛出明确错误。 - HLS:设置
headers时,宿主优先走 hls.js 并用宿主请求通道加载播放列表与分片,headers在桌面端与移动端都会带上;系统不支持 hls.js 时会退回原生 HLS,此时headers不可用。
跨域要求:
- 视频直链由
<video crossorigin="anonymous">直接加载,源站必须返回Access-Control-Allow-Origin,否则会以MEDIA_ELEMENT_ERROR: Format error失败——看起来像编码问题,实际是跨域被拒。桌面端可以用proxy: true让本地代理补上跨域头;移动端没有代理。 - 音频直链用
<audio>加载,不设置crossorigin,不要求源站提供 CORS 头。 - 经宿主请求通道加载的 HLS 播放列表与分片不受浏览器 CORS 限制。
自测时可以先用 curl -H 'Origin: app://obsidian.md' -I <地址> 看响应里有没有 access-control-allow-origin。
- 移动端兼容:Connector 在 iOS / Android 上同样会加载执行。不能用 Node 内置模块(
fs、path、http…),不能用 Electron 专属 API;需要随机数或摘要时用 Web 标准的crypto.subtle。 - 文件访问:vault 内只能通过
getSettings/saveSettings;vault 外的本机文件仅agent-session类型可用,且只能走桌面端的ctx.desktop。 - 没有沙箱:Connector 以插件同等权限运行,能发起网络请求、读写自己的配置。请只安装可信来源。
- 不要阻塞:
match保持同步且廉价,耗时操作放在resolve。
# 视频 / 音频:加载 → match → resolvenpx sync-vault-connector-mock ./my-connector "https://example.com/video/1"
# agent-session:加载 → probe → discovernpx sync-vault-connector-mock ./my-connectormock 的校验与求值规则和宿主一致,能提前暴露 manifest 字段错误、ESM 语法、require 缺失等问题。
装进 vault 后:
- 执行 重新加载用户 Connectors,看弹出的「已加载 N 个,失败 M 个」汇总。
- 播放失败时在日志里搜索
[connector.<id>],resolve抛出的错误会记在那里。