SyncNotes

在 VS Code 中管理 Markdown 笔记，并支持把笔记同步到 Git 远程仓库 或 WebDAV 服务。

笔记存放在你指定的任意目录中，与当前打开的工作区无关——无论在写什么项目，侧边栏里始终是同一份笔记。

功能

• 活动栏中的笔记树视图，支持多级文件夹
• 新建、重命名、删除笔记与文件夹（删除进回收站，可恢复）
• 跨全部笔记的快速检索
• 笔记目录发生变化时自动刷新
• 两种同步后端：Git 远程仓库、WebDAV
• 检测到冲突时保留双方内容，显示冲突与延后处理结果
• 独立的图形化设置页，改动即时生效，无需跳到 VS Code 全局设置页

快速开始

1. 打开活动栏中的 SyncNotes 图标，点击「选择笔记目录」，指定一个用于存放笔记的目录。
2. 点击视图标题栏的 + 新建笔记。
3. 需要同步时，点击视图标题栏的齿轮图标打开设置页，选择同步方式并填好参数。

设置

点击视图标题栏的齿轮图标（或执行「SyncNotes: 打开设置」）会打开一个独立页签，笔记与两种同步后端的全部常用配置都在这一页上，改一项立即生效。重复点击只会把已打开的页签带到前台，不会开出多个页签。

页面包含四节：笔记、同步（后端选择与触发时机）、Git 仓库、WebDAV。后两节跟随「同步方式」下拉框切换显示——选 Git 只显示 Git 一节，选 WebDAV 只显示 WebDAV 一节，选「不同步」则给出提示。切换方式不会清空另一种的配置，随时可以切回来继续用。

各后端一节内可直接完成：

• 录入/清除凭据（密码框，保存到系统密钥库，页面只显示「已保存/尚未保存」，不回显明文）
• 测试连接：Git 用 git ls-remote 验证地址与令牌，WebDAV 发一次 PROPFIND，结果就地显示 本地仓库无需手动初始化：笔记目录还不是 Git 仓库时，首次同步会自动执行 git init、设置 origin 与分支、写入 .gitignore。

页面顶部的「在设置编辑器中打开」链接用于访问下表里未在表单中出现的原始配置项。

同步的范围是笔记目录下的全部文件，而不只是 noteExtensions 里的扩展名——否则笔记引用的图片等附件会在其他设备上缺失。.git、node_modules、.DS_Store 等会自动跳过。

密码与访问令牌不会写入设置文件，而是保存在系统密钥库（VS Code SecretStorage）中，在设置页对应后端一节内录入（也可用命令「SyncNotes: 设置同步凭据」）。Git 凭据按仓库地址保存，WebDAV 凭据按服务地址和账号分别保存。同一服务的不同账号分别录入密码；升级后旧凭据缺少账号归属时，需要重新录入，旧凭据仍保留在密钥库中。

跨 Profile 共享与跨设备同步

全部设置均声明为 VS Code 的 application 作用域：

• 同一台电脑的多个 Profile 间自动共享同一份配置，不用在每个 Profile 里重复设置一遍。
• 若你开启了 VS Code 内置的 Settings Sync（登录 Microsoft / GitHub 账号后在左下角账户菜单启用），这些设置也会随之带到你的其他电脑上。

notesLocation（笔记目录路径）和 sync.deviceName（设备名）是例外：它们同样在本机各 Profile 间共享，但通过 ignoreSync 排除在 Settings Sync 之外。前者是本机文件系统路径，不同电脑的盘符和目录结构通常不同，同步过去大概率是个无效路径；后者本就该因设备而异，才能在冲突文件名和提交信息里区分是哪台设备的改动。设置页里这两个字段旁标注了「不跨设备」。

跨 Profile 共享和跨设备同步由两个独立机制控制：scope 决定前者，ignoreSync 决定后者。

Settings Sync 不会同步凭据——syncnotes.setCredential 保存的令牌 / 密码走的是 SecretStorage，不在 Settings Sync 的同步范围内，换新电脑后仍需重新录入一次（但同一台电脑上的多个 Profile 已经共用同一份，不用重复录入）。

同时开着多个 VS Code 窗口

每个窗口都是独立的进程，都会各自跑同步。为避免两个窗口同时改写同一份基线（Git 后端还会直接撞上 index.lock），同步前会先在 ~/.syncnotes/ 取一把按笔记目录区分的进程锁：

• 同一时刻只有一个窗口在同步，其余窗口跳过本轮；手动触发时会提示「另一个窗口正在同步」。
• 持锁期间定期续期，进程仍存活时保留互斥。异常退出留下的锁过期后可重新取得，锁失效会停止任务的后续步骤。
• 尝试时间、成功时间与任务结果按同步关系共享，聚焦触发的冷却在窗口间统一生效。失败重试有独立退避，部分完成会显示延后、失败或待核实文件数。
• 各窗口登记未保存文档。WebDAV 对检测到的编辑中文件延后覆盖和删除，下载内容可另存为冲突副本；Git 在合并前检测到编辑中文件时延后本轮合并。
• 登记协议覆盖当前版本参与协调的窗口。其他程序在最终检查后的并发写入仍有时序窗口，编辑器保存冲突与同步恢复记录共同参与保护。

Git 同步

需要本机已安装 git 并可在 PATH 中找到。

配置步骤

1. 先在 GitHub / GitLab / Gitea 等处创建一个仓库（建议设为私有）。
2. 打开设置页，「同步方式」选「Git 仓库」，在 Git 一节填入仓库地址与分支名。
3. HTTPS 地址在同一节录入访问令牌；点击「测试连接」确认能通即可，本地仓库会在首次同步时自动建好。

笔记目录不能放在其他 Git 仓库内部，否则拒绝同步。哪怕笔记目录自己已经是一个仓库（嵌套仓库）也不行。

笔记仓库与你其他项目的仓库必须是彼此独立的两个仓库。判断依据是笔记目录在文件系统上的仓库归属，与远端地址用 SSH 还是 HTTPS 无关——两者都可以用任意协议，各自的凭据也分开保存。.gitignore 挡不住这件事：Git 判断归属看的是工作树，不是忽略规则。

认证方式

• HTTPS + 访问令牌：在托管平台生成一个个人访问令牌（PAT），按提示录入。
  • GitHub：Settings → Developer settings → Personal access tokens，勾选 repo 权限
  • 若服务端要求特定用户名，把地址写成 https://用户名@host/仓库.git，插件会从中取用
• SSH：地址填 git@host:用户/仓库.git，直接使用本机已配置的 SSH key，无需在插件中录入任何凭据。

令牌通过 GIT_ASKPASS 以环境变量传给 git 子进程，不会出现在命令行参数中（后者可被同机其他进程看到）。

同步流程

git add -A → 有改动则提交 → git fetch → git merge → 处理冲突 → git push

推送被拒（远端有新提交）时会自动重新拉取并重试一次。

WebDAV 同步

适用于坚果云、Nextcloud、ownCloud、群晖等服务。

1. 打开设置页，「同步方式」选「WebDAV」。
2. 在 WebDAV 一节填入服务地址、用户名、远端路径，录入密码。
3. 点击「测试连接」确认能通。

坚果云：地址为 https://dav.jianguoyun.com/dav/，密码必须使用「应用密码」（账户信息 → 安全选项 → 添加应用），不能用登录密码。

同步策略

WebDAV 本身没有版本概念，插件通过一份本地状态清单记录上次同步完成时各文件的指纹，再用「上次同步态 / 本地当前态 / 远端当前态」三方对比来判断每个文件发生了什么。

这样才能区分「本地新增」和「远端已删除」——只比较修改时间是做不到的，会把已删除的笔记反复复活。

清单保存在用户主目录下的 ~/.syncnotes/ 中，按实际本地目录、服务地址、账号与远端目录区分。每台设备维护自己的清单，同一实际目录通过目录联接打开时仍使用同一份状态。

生产环境的共享目录独立于 Profile，开发与测试宿主使用隔离存储。v2 基线包含同步关系身份和待核实动作。旧版基线缺少本地目录与账号归属，升级时保留旧文件，并按双方当前内容重建，首轮保留双方独有文件、为不同内容创建冲突副本。此前删除的文件可能重新出现，插件会给出提示。

清单不存在（真正的首次同步）会保留双方全部内容，不会误删；清单损坏则会明确弹窗提示，因为此时同样会退化为首次同步，已删除的笔记可能重新出现。

强 ETag 且支持条件请求的服务使用条件上传和条件删除，基线中的内容指纹与同次响应版本对应。弱 ETag 使用归一化版本比较，无 ETag 时退化为大小与修改时间比较，元数据未变的文件不会每轮下载。兼容模式在写入或删除前复查内容，但无 ETag 且大小、修改时间均未变化的远端修改可能无法自动发现，服务端也无法提供原子的并发保护。失败和结果不明的操作保留旧基线及待核实记录，下轮先确认实际状态再继续。

本地覆盖前的恢复副本和原路径信息存放在共享状态目录的 recovery/ 中，基线确认提交后清理本轮副本，异常退出留下的副本可用于恢复。Git 同步阶段另记录在 git-run-*.json，用于定位提交、合并或推送中断。

冲突处理

两个后端对检测到的冲突保留双方内容，并按实际处理结果提示。扫描后的本地修改会在覆盖或删除前再次检查。

冲突发生时会弹窗提示，可直接打开冲突副本对照。副本本身也是一篇普通笔记，会同步到其他设备，因此两边都能看到这次冲突。合并完成后自行删除副本即可。

命令

全部命令可在命令面板中以 SyncNotes 前缀找到：

插件不预置快捷键，以免占用你已有的按键。需要的话可在「键盘快捷方式」中自行绑定。

开发

npm install
npm run watch                # esbuild 监听构建
npm test                     # 单元测试
npm run check-types
npm run lint
npm run verify:git           # 用真实 git 仓库验证同步与冲突处理
npm run verify:activation    # 用 vscode 桩件验证激活流程与命令注册
npm run verify:regressions   # 已复现数据一致性问题的回归
npm run verify:sync-state    # 真实多进程互斥、编辑登记与基线校验
npm run verify:webdav        # 本地服务上的条件请求、并发与故障恢复
npm run verify:coordinator   # 任务配置、取消、部分完成与关闭
npm run verify:host          # 两个隔离 VS Code 宿主的跨窗口验收
npm run package              # 产出 .vsix
npm run verify:package       # 检查最新隔离打包产物的资源清单
npm run verify:installed     # 将隔离打包产物安装到临时目录并验收

在 VS Code 中按 F5 启动扩展开发宿主进行调试。首次按下会自动：

1. 运行 scripts/setup-debug-workspace.mjs，在用户主目录的 .syncnotes-debug/notes 下生成示例笔记，并把该目录写入隔离的 .dev/user-data/User/settings.json，使 application 配置生效
2. 运行 esbuild 构建
3. 用独立的 --user-data-dir（.dev/user-data）打开这个示例工作区，调试宿主的设置、状态与你日常使用的 VS Code 完全隔离

调试宿主启动后即可直接在笔记树里看到示例内容，无需手动执行「选择笔记目录」。示例笔记的编辑会保留到下次调试；如需清空重来，运行 npm run debug:reset。

verify:git 在每轮专属临时目录建立裸仓库与两个笔记仓库，直接调用生产后端验证双方修改、删除冲突、新增冲突、二进制内容、取消和推送竞争。verify:webdav 启动可控制的本地服务验证版本条件和故障恢复。验证脚本仅清理本轮创建的临时数据。

verify:host 需要本机可用的 VS Code，通过独立用户数据和扩展目录运行两个测试窗口，验证真实编辑缓冲区的未保存状态与保存后清除。可使用 SYNCNOTES_VSCODE_EXECUTABLE 指定 VS Code 可执行文件路径。

watch 任务的问题匹配器直接写在 .vscode/tasks.json 里（识别 esbuild.mjs 打印的 [watch] build started / [watch] build finished），不依赖任何第三方扩展，装好依赖后开箱即用。

许可

MIT