编写你的第一个 Connector
这一页从一个空目录开始,写一个能把外部视频地址解析为可播放流的 Connector,并在本地调试后装进 Obsidian。全程只需要 JavaScript 和一个可访问的接口地址,不需要修改插件源码。
TIP可以让 AI 帮你写 Connector 的接口很小。把这一页和 API 参考 一起交给 AI,说明你要接入的站点与取流方式,让它生成
main.js,再用本地调试器验证即可。
1. 建目录
Section titled “1. 建目录”一个 Connector 就是一个目录、两个文件:
my-connector/├── manifest.json└── main.js目录名就是 Connector 的 id,必须与 manifest.json 里的 id 一致。
2. 写 manifest.json
Section titled “2. 写 manifest.json”{ "id": "my-connector", "name": "My Connector", "version": "1.0.0", "apiVersion": "0.4", "type": "video-source", "description": "解析 watch.example.com 的视频地址", "author": "your-name", "homepage": "https://github.com/you/my-connector"}| 字段 | 必填 | 说明 |
|---|---|---|
id | 是 | 唯一标识,必须与目录名一致;只允许小写字母、数字、-、_ |
name | 是 | 展示名 |
version | 是 | Connector 自己的版本号 |
apiVersion | 是 | 目标契约版本。宿主当前为 0.4,只看第一段数字是否一致 |
type | 是 | video-source、audio-source 或 agent-session |
description / author / homepage | 否 | 展示与溯源信息 |
3. 写 main.js
Section titled “3. 写 main.js”main.js 是单文件 CommonJS,导出一个 create(ctx) 工厂函数:
module.exports = { create(ctx) { return { // 宿主会对每个外部地址同步调用它,必须廉价 match(url) { return /^https?:\/\/watch\.example\.com\/video\//i.test(url); },
async resolve(url, onProgress) { onProgress?.('正在解析播放地址…');
// 走宿主通道请求,不受浏览器 CORS 限制 const resp = await ctx.request({ url: `https://api.example.com/resolve?url=${encodeURIComponent(url)}`, }); if (resp.status !== 200) { throw new Error(`解析接口返回 HTTP ${resp.status}`); }
const data = resp.json; if (!data.playUrl) { throw new Error(data.message || '解析结果里没有 playUrl'); }
return { url: data.playUrl, urlType: 'm3u8-list', mediaType: 'hls', coverUrl: data.cover, mediaInfo: [{ url: data.playUrl, width: data.width ?? 0, height: data.height ?? 0, resolution: data.quality ?? '自动', }], }; },
// 可选:重新加载或停用插件时清理定时器、连接等 dispose() {}, }; },};几个关键点:
match要保守:它决定这个地址是否完全交给你的 Connector。不要匹配所有http(s)地址,否则会把普通网页条目也劫持成视频。匹配后同步返回,不要在里面发请求。resolve失败就抛错:宿主不会回落到内置解析,也不会再问其他 Connector;错误信息会直接展示给用户并写入日志。不要用「返回空流」掩盖失败。- 返回的
url要能被再次解析:切换分集或地址过期时,宿主会拿原始地址再次调用resolve,所以实现要可重复调用,不要在实例上累积一次性状态。 - HLS 不要用
resolution: '原画':「原画」在播放器里有特殊含义,会按直链处理;HLS 用自动或清晰度名称即可。
完整字段说明见 Connector API 参考。
4. 在本地调试
Section titled “4. 在本地调试”不用打开 Obsidian,直接用 SDK 的 mock 跑一遍「加载 → match → resolve」:
npx sync-vault-connector-mock ./my-connector "https://watch.example.com/video/123"mock 的 manifest 校验、main.js 求值方式与宿主一致,能提前发现字段缺失、ESM 语法、require 之类的问题。差异只有两处:ctx.request 走 Node 的 fetch(没有 CORS 限制),ctx.dir 是本地绝对路径。
如果报错,先修到命令能打印出解析结果,再装进 Obsidian。
5. 装进 Obsidian 并用起来
Section titled “5. 装进 Obsidian 并用起来”在仪表盘工作台添加 Connector 管理 卡片,点 安装:
- 粘贴
manifest.json的地址(GitHub 页面链接会自动转成 raw),或 - 点 选择文件,同时选中
manifest.json与main.js。
也可以把整个目录拷到 <vault>/.obsidian/plugins/sync-vault-ce/connectors/my-connector/,再执行命令 重新加载用户 Connectors。
然后在笔记里用 cloudvideo 代码块写入地址:
```cloudvideohttps://watch.example.com/video/123 | 我的视频```切换回阅读模式即可播放。清晰度切换、播放进度、时间戳标注等能力与内置视频源一致,不需要额外适配。
6. 加一点配置
Section titled “6. 加一点配置”需要 token、Cookie 之类的配置时,用 ctx.getSettings() 读取本 Connector 目录下的 settings.json:
const settings = await ctx.getSettings();const token = settings?.token;if (!token) { throw new Error('请先在 settings.json 中配置 token');}用户也可以直接编辑这个文件。它是 vault 里的普通 JSON,明文存储,会随 vault 一起同步;不要把长期密钥硬编码进 main.js。
7. 支持分集
Section titled “7. 支持分集”多分P、多集的视频可以返回 parts,宿主会在播放器侧栏展示选集,并在播完一集后自动续播下一集:
return { url: current.playUrl, urlType: 'm3u8-list', mediaType: 'hls', mediaInfo: [{ url: current.playUrl, width: 0, height: 0, resolution: '自动' }], parts: [ { name: 'P1 开场', url: 'https://watch.example.com/video/123?part=1' }, { name: 'P2 正片', url: 'https://watch.example.com/video/123?part=2' }, ], currentPartIndex: 0,};- 至少 2 项时才会展示选集。
- 每个
parts[].url都必须能被你的match/resolve正常处理——宿主切换分集时会拿它再次调用resolve。 - 分集在宿主内是独立条目,各自记录播放进度与标注。
8. 音频 Connector
Section titled “8. 音频 Connector”把 manifest.type 改成 audio-source,方法形状完全不变。注意:
- 音频没有分辨率,
mediaInfo每项填width: 0、height: 0,resolution用原画或展示名。 - 音频地址过期后宿主不会自动重取,请返回时效足够长的地址。
- 返回
parts时宿主按顺序连播;选集列表在播放器侧栏展示,内嵌播放器本身没有选集按钮。
可以直接参考 SDK 里的 web-audio(直链 / HLS)和 rss-podcast(RSS 播客)示例。
9. 移动端检查清单
Section titled “9. 移动端检查清单”- 不用 Node / Electron API:
fs、path、http都不可用;需要随机数或摘要时用 Web 标准的crypto.subtle。 - 文件读写只走
ctx:vault 内用getSettings/saveSettings;vault 外的本机路径只有agent-session可以用,且只能走桌面端的ctx.desktop。 - 依赖防盗链头的地址:
proxy: true的本地代理只在桌面端有效,移动端会退化成直连、headers不生效。请主动判断并报错,而不是让用户看到莫名其妙的播放失败:
if (ctx.platform.isMobile) { throw new Error('该地址需要防盗链头,暂仅支持桌面端播放');}- 直链视频需要跨域:播放器以
<video crossorigin="anonymous">直接加载直链,源站必须返回Access-Control-Allow-Origin,否则会以MEDIA_ELEMENT_ERROR: Format error失败。桌面端可以用proxy: true让本地代理补上跨域头;移动端没有代理。
10. 分享给别人
Section titled “10. 分享给别人”把目录推到 GitHub(只带 manifest.json 与 main.js,不要带 settings.json 和 .disabled),别人在安装框里粘贴 manifest.json 的 GitHub 页面链接即可。后续更新时保持 id 不变、递增 version,同 id 覆盖安装会保留用户的 settings.json。
| 现象 | 常见原因 |
|---|---|
加载失败:manifest.id(...) 必须与目录名(...)一致 | 目录名和 id 不一致 |
加载失败:提示不能用 ESM 的 import / export | 用了 ESM 语法,改成 module.exports |
加载失败:main.js 必须导出 create(ctx) | 忘了导出工厂函数 |
播放器提示 Unsupported file type | 没有 Connector 命中,检查 match 是否过窄 |
播放 403 / Format error | 防盗链头或跨域问题,检查 proxy / headers 与移动端差异 |
| 解析失败但不知道哪一步 | 在日志里搜索 [connector.my-connector] |
更多字段与生命周期细节见 Connector API 参考。