跳转到内容

Connector API 参考

本页是 Connector 契约 0.4 的参考。契约的唯一事实来源是插件仓库的 src/connector/def.ts;SDK 的 index.d.ts 由它自动生成,两者不会漂移。

配套 npm 包:@sync-vault/connector-sdk(只含类型与本地调试工具,不含运行时代码)。

Terminal window
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 不求值、不参与匹配。卸载才会删除整个目录。
字段必填说明
id是唯一标识,必须与目录名一致;只允许 [a-z0-9-_],且以字母或数字开头
name是展示名
version是Connector 自己的版本号
apiVersion是目标契约版本,如 0.4
type是video-source、audio-source 或 agent-session
description否一句话说明
author否作者
homepage否仓库或主页地址

字段缺失、id 非法、id 与目录名不一致、类型不支持、apiVersion 首段不匹配,都会导致加载失败并给出明确原因。

必须是单文件 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 有现成配置)。
成员说明
id本 Connector 的 id
dir本 Connector 在 vault 内的目录路径
platform{ isDesktop, isMobile },用于按端降级
request(options)网络请求,走宿主通道,不受浏览器 CORS 限制
logdebug / info / warn / error,写入 Sync Vault 日志
getSettings<T>()读取 settings.json;文件不存在返回 null
saveSettings(obj)写入 settings.json(缩进 2 的 JSON)
desktop桌面专属的 vault 外文件通道;移动端为 undefined
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; // number
resp.headers; // Record<string, string>,键名小写
resp.text; // string
resp.json; // any,访问时才解析
resp.arrayBuffer; // ArrayBuffer
  • 非 2xx 不抛错:返回 status 由 Connector 自己判断;断网、DNS 等网络层失败才会抛错。
  • 响应体是惰性读取的,不要假设可以重复读取大文件。

适合放 token、Cookie 这类配置。它是 vault 里的普通文件,明文存储,会随同步与分享流转;不要把长期密钥硬编码在 main.js 里。

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,因此实现必须可重复调用。
字段必填说明
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 播放。
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= 非法而回退了实际分集,也应如实返回实际下标。
  • 分集在宿主内是独立条目:各自记录播放进度与标注锚点,一集播完自动续播下一集。

平台返回的播放地址通常有有效期(带签名的 CDN 链接等)。宿主的兜底逻辑:

  • 播放中遇到 401 / 403 / 404 / 410 时,以同一 URL 再次调用 resolve,拿到新地址后跳回原播放位置续播。
  • 每个播放器最多自动重取 2 次;重取成功且 1 分钟内不再过期,额度会归还。
  • 一份 MediaStreamInfo 被替换(过期重取、切换视频)或播放器销毁时,宿主调用它的 cleanup()。一次性资源(定时器、本地服务、临时订阅)请挂在 cleanup 上;跨多份流存活的资源放在实例的 dispose 里。

音频源目前不做过期重取,见下一节。

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 的本机会话导出到受管仓库,在其他设备恢复到本机继续。宿主负责受管仓库、版本游标与跨设备分发,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。

防盗链(需要 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。
Terminal window
# 视频 / 音频:加载 → match → resolve
npx sync-vault-connector-mock ./my-connector "https://example.com/video/1"
# agent-session:加载 → probe → discover
npx sync-vault-connector-mock ./my-connector

mock 的校验与求值规则和宿主一致,能提前暴露 manifest 字段错误、ESM 语法、require 缺失等问题。

装进 vault 后:

  1. 执行 重新加载用户 Connectors,看弹出的「已加载 N 个,失败 M 个」汇总。
  2. 播放失败时在日志里搜索 [connector.<id>],resolve 抛出的错误会记在那里。