Skip to content

About

Project Graph 多端同步扩展:把整个工程文件夹同步到坚果云等标准 WebDAV,或 S3 兼容存储

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

3 Commits

Folders and files

Repository files navigation

WebDAV / S3 Sync — Project Graph 同步扩展

release topic

作者: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.tsx 312–355 行),打进去的字不会回显,看起来就是"输不进去"。插件无法绕过。

从旧版升级:先卸载旧版再装 v0.5.4。判断是否装对:按 Ctrl+Shift+Alt+I 或看加载提示,应出现 v0.5.4。

如果整个界面都打不进字 / 点不动

这是主程序 Radix 对话框的遮罩异常残留(body 上留了 pointer-events: none,点击无法聚焦任何控件),扩展修不了它,但可以这样恢复:

  1. 先保存工程。
  2. 完全退出 Project Graph 再重新打开(不是「重载应用」,重载不会清 DOM 状态)。
  3. 恢复后按 Ctrl+Shift+Alt+I 确认插件版本(提示条里应有 v0.5.4);配置走 Ctrl+Shift+Alt+C。

安装

  1. 把 out/com.workbuddy.webdav-sync-0.5.4.prg 拖进 Project Graph;或解压成同名文件夹放进设置里显示的「扩展目录」。
  2. 给「重载应用」绑定快捷键(例如 Ctrl+F5)。重载会丢失未保存的文件,先保存工程。
  3. 确认加载成功(任选其一即可):
    • toast 显示「WebDAV / S3 Sync v0.5.4 已加载」
    • 「快捷键」标签里出现 6 个命令(同步/上传/下载/配置/状态/重置)
    • 扩展详情页「快捷键」标签里有 9 个命令

快速开始(坚果云)

  1. 坚果云网页 → 账户信息 → 安全选项 → 添加应用密码(不是登录密码)。开着微信二次验证会返回 403,需先关掉。

  2. 打开任意 .prg 工程(同步范围默认就是这个文件所在的整个文件夹),按 Ctrl+Shift+Alt+C。

  3. 弹出配置表单窗口(字段标签上会标注当前值)。首次至少填两项:

    • 账号:坚果云注册邮箱
    • 密码:应用密码(不是登录密码)

    其余留空 = 保持不变。要固定同步别的目录,填 本地目录(如 E:\005project-graph)。

  4. 点【保存】,看到「配置已保存(webdav)」即成功。

  5. 按 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

已知限制(请务必读)

  1. 同步范围是当前打开的 .prg,不是整个文件夹。两端工程文件名必须一致,否则会被当成两个文件。
  2. 下载后插件会尝试调用 project.init() 刷新画布;若无法刷新,会标记 NEEDS_RESYNC 并提示重新打开工程,下次同步会再次询问,以此避免旧画布被误上传覆盖远端。
  3. 本地变更检测基于 stageHash(覆盖舞台节点/连线),只改标签、引用或附件时可能检测不到,此时请用「强制上传」。
  4. getFileContent() / fs.write() / uri.with() / init() 属于主程序未文档化的内部能力(靠 Comlink 全对象代理访问),软件升级后可能失效。插件对关键路径做了能力探测与降级,但无法保证跨版本兼容。
  5. 配置(含应用密码)以明文存在扩展设置中。务必使用可随时撤销的应用专用密码,不要用主密码;不要在多用户机器上共用配置。
  6. curl 受限模式(网络通道不可用时自动进入)只支持 WebDAV 的显式上传/下载,不做自动冲突判定,也不支持 S3。
  7. 未实现端到端加密、多工程批量同步、目录级同步。

装机验证(建议先做)

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

About

Project Graph 多端同步扩展:把整个工程文件夹同步到坚果云等标准 WebDAV,或 S3 兼容存储

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages