作者:namean | 仓库:https://github.com/naMeaning/project-graph-webdav-sync
安装:到 Releases 下载最新的 .prg,拖进 Project Graph,然后重载应用。
把整个文件夹(默认是当前 .prg 所在的目录)同步到坚果云等标准 WebDAV。也可以只同步单个 .prg,或改用 S3 兼容存储(R2 / B2 / MinIO / 腾讯云 COS)。同步算法与交互参考 Obsidian 的 Remotely Save。
当前状态:v0.5.4。 已通过 29 个本地模拟场景测试(含 S3 签名交叉校验、目录递归同步、忽略规则、三向冲突、删除策略、IIFE 语法校验、表单窗口通道、快捷键注册回调)。
v0.5.4 作者改为 namean;配置通道的尝试结果会写入设置项
_lastConfig(排障用);按配置键立刻有 toast 反馈。v0.5.3 修正表单 schema(补
$schema,否则z.fromJSONSchema解析失败)、区分「用户取消」与「接口不可用」;通道顺序改为 表单窗口 → 单框对话框 → 记事本。v0.5.2 修的是表单窗口体验。 之前表单给了 10 个字段,而主程序 FormWindow 的子窗口高度只有屏高 62% 且没有滚动条,字段一多【保存】按钮就被挤出可视区,表现就是「按钮点不到」;同时所有字段都设了必填,只想改账号密码也会被校验卡住。现在表单精简为 5 个字段、全部非必填(留空=保持不变)。
v0.5.1 修的是快捷键注册。 v0.2.0 起我把注册回调从
Comlink.proxy(...)改成了普通函数,主程序收不到可跨线程调用的回调,注册直接失败——表现是扩展详情页「快捷键」里一个命令都不显示,按任何快捷键都没反应。v0.5.1 恢复Comlink.proxy包装,并且只使用磁盘上已存在的 6 个命令 ID(新增 ID 需要写 keybinds2.json,那条路会失败),功能全部挂在这 6 个 ID 上。v0.5.0 的重点:同步单位从「一个 .prg」改成「一整个文件夹」。 默认同步当前
.prg所在目录的全部文件与子目录;要固定同步某个目录(比如E:\005project-graph),在配置的「本地目录」里填绝对路径。配置仍用主程序的表单窗口(FormWindow),打字正常回显。若软件版本过老没有表单窗口,会退到工程同目录的
<工程名>.sync.json文件通道。目录同步只在 WebDAV 后端可用(坚果云等)。S3 后端目前只支持单文件模式。
v0.2.0 修的是什么:主程序对话框的关闭顺序是「先返回结果 → 播退场动画 → 500ms 后才真正移除遮罩」。旧版配置向导连续弹 4 个输入框,前一个的遮罩与焦点锁还盖在页面上,后一个就出现了——表现就是字打不进去、按钮点了没反应。现在所有对话框统一走串行队列(每次间隔 700ms),不会重叠。
不要用扩展设置页的输入框。主程序用的是受控输入框,但没有订阅扩展设置的变化(
Extension.tsx312–355 行),打进去的字不会回显,看起来就是"输不进去"。插件无法绕过。
从旧版升级:先卸载旧版再装 v0.5.4。判断是否装对:按
Ctrl+Shift+Alt+I或看加载提示,应出现v0.5.4。
这是主程序 Radix 对话框的遮罩异常残留(body 上留了 pointer-events: none,点击无法聚焦任何控件),扩展修不了它,但可以这样恢复:
- 先保存工程。
- 完全退出 Project Graph 再重新打开(不是「重载应用」,重载不会清 DOM 状态)。
- 恢复后按
Ctrl+Shift+Alt+I确认插件版本(提示条里应有v0.5.4);配置走Ctrl+Shift+Alt+C。
- 把
out/com.workbuddy.webdav-sync-0.5.4.prg拖进 Project Graph;或解压成同名文件夹放进设置里显示的「扩展目录」。 - 给「重载应用」绑定快捷键(例如
Ctrl+F5)。重载会丢失未保存的文件,先保存工程。 - 确认加载成功(任选其一即可):
- toast 显示「WebDAV / S3 Sync v0.5.4 已加载」
- 「快捷键」标签里出现 6 个命令(同步/上传/下载/配置/状态/重置)
- 扩展详情页「快捷键」标签里有 9 个命令
-
坚果云网页 → 账户信息 → 安全选项 → 添加应用密码(不是登录密码)。开着微信二次验证会返回 403,需先关掉。
-
打开任意
.prg工程(同步范围默认就是这个文件所在的整个文件夹),按Ctrl+Shift+Alt+C。 -
弹出配置表单窗口(字段标签上会标注当前值)。首次至少填两项:
- 账号:坚果云注册邮箱
- 密码:应用密码(不是登录密码)
其余留空 = 保持不变。要固定同步别的目录,填 本地目录(如
E:\005project-graph)。 -
点【保存】,看到「配置已保存(webdav)」即成功。
-
按
Ctrl+Shift+Alt+S执行首次目录同步,完成后会弹出汇总:目录同步完成:上传 12,下载 0,冲突保留副本 0,删除 0,未变 0,超限跳过 0
另一台设备:装同一插件、填同样账号密码、打开同名同路径的工程,按 S 即可拉取。远端路径规则是 <云端目录>/<本地文件夹名>/<相对路径>,所以两台机器本地文件夹名需要一致(或用「远端子目录」手动对齐)。
改用 S3:在表单的「类型」里填 s3,保存;再按一次 C,表单会换成 S3 字段。注意 S3 目前只支持单文件模式(把「模式」填 file)。
只同步单个 .prg:在表单的「模式」里填 file。
想恢复出厂设置:在 .sync.json 里去掉 #重置=yes 前面的 #,保存后按 C 载入。
关于 Esc:主程序的弹窗/表单窗口都不支持 Esc 关闭(Dialog 未接 onOpenChange、FormWindow 写死 closeOnEscape: false),请点【取消】或【保存】。这是软件侧的行为,已整理成 issue 草稿见 issue-draft.md。
备用输入通道:表单窗口打不开时,按 C 会自动用记事本打开 <工程名>.sync.json;改完保存再按一次 C 即可载入。若工程目录不可写,会退回弹窗(Shift+Enter 提交)。
配置字段:类型 账号 密码 地址 云端目录 模式 本地目录 远端子目录 忽略 同步删除 自动同步 间隔分钟 AK SK 桶 前缀 pathstyle 重置。不认识的键会被忽略,写错不会导致整份配置失效。
范围:本地根目录递归遍历(含子目录),映射到远端 <云端目录>/<本地文件夹名>/<相对路径>。
判定:三向比较(本地内容 hash / 远端 ETag / 上次同步基线),逐文件决定:
| 情况 | 动作 |
|---|---|
| 本地新增 | 上传 |
| 远端新增 | 下载 |
| 只有本地改了 | 上传 |
| 只有远端改了 | 下载 |
| 两端都改了 | 保留本地,远端版本另存为 xxx.conflict-时间戳.ext |
| 本地删除、远端没动 | 开启「同步删除」才删远端,否则保留 |
| 远端删除、本地没动 | 开启「同步删除」才删本地,否则保留 |
安全默认:同步删除 默认关闭 —— 只增不删,误删风险最低。开启后才会把删除同步到另一端。
忽略规则(忽略,逗号分隔,支持 *):默认 node_modules, .git, .svn, .idea, __pycache__, *_backup, .DS_Store, Thumbs.db, desktop.ini, *.sync.json, *.conflict-*。冲突副本和时间戳备份不会被再次上传。
上限保护:最大文件数(默认 800)、最大总量(默认 300MB)、单文件大小沿用 maxSizeMB(默认 480MB,受坚果云 500MB 限制)。超限文件会被跳过并在汇总里报数。
性能说明:readDir 拿不到文件修改时间,所以每次同步都要读一遍本地文件算 hash 才能判断是否有变化。目录很大时会比较慢——建议把 *_backup、图片原始素材之类放进忽略规则。
坚果云限流:目录同步按目录逐层发 PROPFIND,请求量与目录数成正比。远端目录数超过 300 会主动中止;自动同步默认关闭,开启后间隔下限 5 分钟,冲突时只提示不处理。
| 快捷键 | 命令 | 作用 |
|---|---|---|
Ctrl+Shift+Alt+S |
立即同步 | 按配置的模式同步(默认整个目录),三向判定后上传/下载/保留冲突副本 |
Ctrl+Shift+Alt+U |
强制上传 | 全部用本地覆盖远端(目录模式:本地所有文件都上传) |
Ctrl+Shift+Alt+J |
强制下载 | 全部用远端覆盖本地(目录模式:远端所有文件都下载) |
Ctrl+Shift+Alt+C |
同步配置 | 打开表单窗口,打字正常回显;表单不可用时自动用记事本打开 .sync.json |
Ctrl+Shift+Alt+I |
同步状态 | 先发两条提示条(版本/后端/范围/通道/错误),再弹可复制的详细状态 |
Ctrl+Shift+Alt+R |
重置基线 | 清除当前目录的同步记录,下次重新比对(不会删文件) |
只有这 6 个命令,不再新增。原因见上面的 v0.5.1 说明:新命令 ID 无法写入
keybinds2.json。
扩展详情页「设置」标签里会出现下面这些项,只用于查看当前值。这里有个容易误解的点:主程序的设置页输入框是「受控但不订阅」的实现,打字其实会写进去、但界面不回显,看起来像打不进去。所以别在这里填,请用 Ctrl+Shift+Alt+C。_keybinds 会显示每个命令的注册结果,_capabilities 会显示本机支持哪些 API——排查问题先看这两项。注意本期新增的 _configFile 会显示当前工程的配置文件完整路径,这是找到那个文件最快的办法。
之所以用扁平键:主程序面板只渲染扩展自己写过的键,且只支持「布尔开关」和「单行文本」两种控件;嵌套对象会显示成 [object Object] 且一编辑就坏。扩展启动时会把没写过的键补上默认值,并写入 _version 方便确认版本。
| 设置键 | 默认值 | 说明 |
|---|---|---|
backend |
webdav |
填 webdav 或 s3 |
webdav.root |
https://dav.jianguoyun.com/dav/ |
WebDAV 根地址 |
webdav.username |
空 | 坚果云注册邮箱 |
webdav.appPassword |
空 | 应用密码(不是登录密码) |
webdav.remoteDir |
ProjectGraph |
远端目录,建议全英文 |
s3.endpoint |
空 | 留空走 AWS;填了走自定义端点 |
s3.region |
us-east-1 |
S3 region |
s3.accessKeyId |
空 | Access Key ID |
s3.secretAccessKey |
空 | Secret Access Key |
s3.bucket |
空 | 桶名 |
s3.prefix |
project-graph |
桶内前缀 |
s3.forcePathStyle |
开(开关) | R2 / MinIO / COS 建议开启 |
mode |
dir |
dir = 同步整个文件夹;file = 只同步当前 .prg |
localDir |
空 | 要同步的文件夹;空 = 当前 .prg 所在目录。支持绝对路径或相对路径 |
remoteSubdir |
空 | 远端子目录名;空 = 用本地文件夹名 |
ignore |
见上 | 忽略规则,逗号分隔,支持 * |
syncDelete |
关(开关) | 是否把删除同步到另一端 |
maxFiles |
800 |
文本;单次同步的文件数上限 |
maxTotalMB |
300 |
文本;单次同步的数据总量上限 |
autoSync |
关(开关) | 定时同步 |
intervalMinutes |
10 |
文本;强制下限 5 分钟 |
maxSizeMB |
480 |
文本;单文件大小上限 |
requestBudget |
600 |
文本;30 分钟窗口请求上限 |
_syncState |
内部数据 | 请勿修改:存同步基线与设备 ID |
_configFile |
自动填入 | 当前工程的 .sync.json 完整路径,用来找到配置文件 |
_version / _help |
自动填入 | 已安装版本 / 配置入口提示 |
- S3 留空
s3.endpoint时用bucket.s3.region.amazonaws.com;填了端点且s3.forcePathStyle开启时用endpoint/bucket/key。 autoSync开启后,自动模式遇到冲突只提示、不弹窗、不自动覆盖。requestBudget达到 80% 时自动同步暂停,避免触发坚果云限流。.sync.json与扩展设置里的密码都是明文,且.sync.json就在工程旁边。请用可随时撤销的坚果云「应用密码」,不要把工程目录随手分享。- 应用密码以明文存在软件设置里(主程序机制如此),务必用可随时撤销的应用专用密码。
三源元数据:本地 stageHash、远端指纹、上次成功同步的基线(存在扩展私有设置里)。
本地未变 + 远端未变 → 无需同步
仅本地变 → 上传
仅远端变 → 下载(写盘前先备份本地)
两端都变 → 弹窗让用户选
远端被删 → 询问是否重新上传
首次连接且两端都有 → 弹窗让用户选
冲突选项:用本地覆盖远端 / 用远端覆盖本地 / 两份都保留(远端另存为 xxx.conflict-时间戳.prg)/ 取消。.prg 是 ZIP 二进制,不做内容合并。
不依赖云端修改时间判冲突——坚果云不支持 PROPPATCH,getlastmodified 等于上传时间,每次 PUT 都会变。远端指纹优先取 S3 自定义元数据 hash,其次 WebDAV ETag,ETag 缺失才退回 Last-Modified / 大小。这与 Remotely Save v3「no remote meta data」一致。
| 限制 | 本插件的应对 |
|---|---|
| 应用密码、微信二次验证 403 | 配置向导明确提示,403 时给出针对性错误信息 |
PROPFIND 只支持 Depth: 1 |
仅用 Depth: 0 查单文件;默认走 HEAD |
不支持 PROPPATCH |
见上,不靠 mtime 判冲突 |
支持 ETag |
用 HEAD 取 ETag 作为远端指纹 |
| 免费 600 次 / 30 分钟(付费 1500) | 禁止高频轮询、请求预算保护、503 明确提示 |
| 单次列表 750 条 | 不扫描目录,只操作单个工程文件 |
| 单文件 500 MB | 上传前按 maxSizeMB 拦截 |
| 中文路径需编码 | 远端路径逐段 encodeURIComponent |
- 同步范围是当前打开的
.prg,不是整个文件夹。两端工程文件名必须一致,否则会被当成两个文件。 - 下载后插件会尝试调用
project.init()刷新画布;若无法刷新,会标记NEEDS_RESYNC并提示重新打开工程,下次同步会再次询问,以此避免旧画布被误上传覆盖远端。 - 本地变更检测基于
stageHash(覆盖舞台节点/连线),只改标签、引用或附件时可能检测不到,此时请用「强制上传」。 getFileContent()/fs.write()/uri.with()/init()属于主程序未文档化的内部能力(靠 Comlink 全对象代理访问),软件升级后可能失效。插件对关键路径做了能力探测与降级,但无法保证跨版本兼容。- 配置(含应用密码)以明文存在扩展设置中。务必使用可随时撤销的应用专用密码,不要用主密码;不要在多用户机器上共用配置。
- curl 受限模式(网络通道不可用时自动进入)只支持 WebDAV 的显式上传/下载,不做自动冲突判定,也不支持 S3。
- 未实现端到端加密、多工程批量同步、目录级同步。
out/com.workbuddy.webdav-sync-probe-0.0.1.prg 是阶段 0 自检插件,按 Ctrl+Shift+Alt+D 运行,会检查 Comlink 二进制通道、getFileContent()、fs.read() 以及 WebDAV 的 PROPFIND/MKCOL/PUT/GET/HEAD/DELETE,输出 JSON 报告。它只上传一个 16 字节临时文件并立即删除,不改工程、报告不含凭据。详见 stage0/README.md。
正式插件已内置运行时探测:若 prg.fetch 无法跨线程传二进制,会自动降级到 curl 受限模式并明确提示,因此自检不是强制步骤,但跑一次能更快定位问题。
零依赖打包(推荐,不需要 npm 网络,因为扩展是 Web Worker + Blob URL,不能 import 其他模块,源码刻意保持单文件纯 JS 语法):
python tools/build.py # 生成 out/com.workbuddy.webdav-sync-0.5.4.prg
python tools/build_probe.py # 重新生成阶段 0 自检包
node tests/smoke.mjs # 29 个模拟场景回归测试src/extension.ts 既是正式源码,也可被 extprg / tsdown 编译(文件里没有 TS 专有语法)。package.json 按 create-extprg 规范书写,未来可直接接官方工具链:
pnpm install && pnpm dev # 监听 src 并自动安装到本机
pnpm package # 产出 {name}-{version}.zip官方市场在 hub.graphif.dev/ext/marketplace,采用自动扫描:GitHub Public 仓库 + extprg topic + 默认分支根目录含符合规范的 package.json(本仓库已具备)+ 至少一个带 .prg 附件的 Release,约 5 分钟后自动收录。目前市场里还没有同步类扩展。
src/extension.ts 正式插件(单文件:传输层 / WebDAV / S3 SigV4 / 同步引擎 / UI)
stage0/ 阶段 0 能力自检插件源码
tools/build.py 正式插件零依赖打包
tools/build_probe.py 自检插件打包
tests/smoke.mjs Node 模拟宿主环境的回归测试
metadata.json 扩展元数据(打包时转成 metadata.msgpack)
out/ 可直接安装的 .prg