dsh-memory-webdav-sync

给 DeepSeek Harness（DSH） 用的记忆同步插件：把工作目录里的记忆文件（Markdown / 文本） 双向同步到任意标准 WebDAV 服务器，让多台机器共享同一份记忆。

---

功能一览

功能	说明
双向同步	本地改动推送到 WebDAV；服务器上的改动拉回本地
后台运行，不打扰对话	会话开始时拉取一次；写完文件后延迟几秒推送；中途的检查在后台进行
冲突保护	两边都改过同一个文件时，先把本地那份另存为 文件名.conflict-时间戳，不会静默丢改动
只同步文本	默认 .md / .txt / .json / .yaml / .yml；图片可选开启
删除安全	本地删除不会删除服务器上的文件（避免一次误删清空远端）
传得完整	上传先写临时文件、校验大小后才改名成正式文件；下载不完整就丢弃。半截文件永远不会冒充你的记忆
凭据不外传	插件自身的配置与状态文件永远不会被同步出去
图形化配置	在 DSH 设置里填写，不需要手改 JSON
无额外依赖	只用系统自带的 curl，无需安装客户端套件

它解决什么问题

DSH 不会自动把上一次会话读给模型。"记忆"靠两样东西：

1. 工作目录里的一份文本档案（例如 index.md 作为入口，下面再分目录）
2. 你的一句触发语（例如「读一下记忆」），让助手去读它

只有一台电脑时这没问题。多台电脑就会分叉：一台改了记忆，另一台不知道。

本插件在后台做双向同步，因此换机器不需要额外操作 —— 开工时它会先把服务器上的最新记忆拉下来。

环境要求

项	要求
DSH	已安装 DSH 桌面版（已在 macOS 上实测；Windows / Linux 未经实测）
WebDAV 服务器	支持 PROPFIND / GET / PUT / MKCOL，认证方式为 Basic Auth
服务器返回的 href	必须是路径形式（例如 /dsh/a.md）；返回完整 URL 的服务端暂不支持
网络	能访问你的 WebDAV 地址（局域网地址或公网域名均可）
系统	需要系统自带 curl（macOS / Linux 默认自带；Windows 10 及以上也自带）

安装

桌面版不能用命令行安装。 DSH 官方规定 desktop profile 由桌面应用自身管理， dsh plugin 命令会拒绝它；「添加本地插件」按钮在 DSH 里也不存在。 下面四种方式任选一种。

方式一：macOS 一键脚本（推荐）

⚠️ 仅适用于 macOS。 Windows / Linux 请用方式二或方式四。

1. 在本仓库页面点 Code → Download ZIP，解压（不需要 Git，也不需要账号）
2. 进入解压出来的文件夹，双击 install.command （首次双击若被系统拦下：右键 →「打开」）
3. 脚本会：把插件登记到 DSH 的 profile → 复制插件文件 → 缺少运行依赖时用 DSH 自带的包管理器补上
4. 完全退出 DSH（⌘Q），再重新打开

脚本只做安装，不会改动插件以外的任何东西；它在动手前会自动备份 profile 的配置文件。

方式二：插件市场（所有平台）

1. 打开 DSH → 设置 → 插件市场
2. 搜索 memory-webdav-sync（或「记忆同步」）→ 点安装
3. 按提示刷新或重启 DSH

如果没有搜到，说明本插件尚未进入市场收录表，请用方式一或方式四。

方式三：命令行（仅适用于 web 等非桌面 profile）

dsh plugin --profile web add github:YerenChina/dsh-memory-webdav-sync

方式四：手工安装（任何平台）

1. 把本目录复制到 <DSH 配置目录>/profiles/<profile 名>/node_modules/dsh-memory-webdav-sync/
2. 在该 profile 的 package.json 中登记两处：

{
  "dependencies": { "dsh-memory-webdav-sync": "file:/本插件的绝对路径" },
  "dsh": { "profile": { "bundles": ["……原有项……", "dsh-memory-webdav-sync"] } }
}

3. 重启 DSH

若该目录下没有 node_modules（例如从 ZIP 解压得到），插件运行所需的 @deepseek-ai/schemastery 需要另行安装：在该目录里执行 pnpm install --prod。

服务器侧准备

1. 启用 WebDAV 服务（群晖等 NAS 的 WebDAV Server 套件、Nextcloud，或自建 Apache / Nginx）
2. 建一个用于存放记忆的目录（例如 /dsh），稍后填进配置的 remotePath
3. 确保所用账号对该目录有读写权限

配置

安装完成后重启 DSH，打开 插件配置 → 记忆同步，填写 WebDAV 地址、账号、密码、远程路径并保存。

也可以改用配置文件：把 memory-sync.example.json 复制成工作目录下的 .memory-sync.json 并填好。 优先级：设置界面 > 配置文件 > 默认值。

配置不会随代码仓库同步，因此每台机器都要填一次（填同一份内容即可共享记忆）。

字段	默认	说明
url	—	WebDAV 服务器地址，例如 https://example.com:5006
localRoot	空	要同步的本地目录；留空 = 自动识别当前 DSH 工作区
user	—	WebDAV 账号
password	—	WebDAV 密码；留空保存 = 不修改已保存的密码
remotePath	/dsh	服务器上存放记忆的目录
includeExt	.md .txt .json .yaml .yml	参与同步的文件类型
syncAssets	false	是否同步图片（体积可能较大）
debounceMs	3000	写完文件后延迟多久推送（毫秒）；越大越省请求
pullIntervalMs	60000	两次自动拉取之间的最小间隔（毫秒）；会话开始那次不受此限制
listTimeoutSec	8	列目录的超时（秒）；它发生在对话开始前，不宜过长
conflictBackup	true	两边都改过时，覆盖前把本地那份另存为 xxx.conflict-时间戳
mirrorDeletions	false	⚠️ 以本地为准：推送时删掉"我们同步过、但本地已经没了"的远端文件与空目录（改名/移动/删除场景）。只删本插件同步过的文件，别人放在服务器上的文件绝不碰
verbose	false	输出调试日志

另有三个只在配置文件里可用的项：excludeDirs（额外要排除的目录）、timeoutSec（传输超时，默认 20 秒）。

关于「删除远端多余文件」（mirrorDeletions）

默认关闭。原因是这个插件默认是"补齐式"同步：服务器上有、本地没有的文件会被下载下来 —— 这带来了一个副作用：你在本地把文件改名/移动/删除后，服务器上那份还在，下一轮拉取又把它下载回来。

打开 mirrorDeletions 后，推送时会以本地为准：把"以前同步过、现在本地已经没有了"的远端文件删掉， 并把这些文件留下的空目录一并清掉（文件删了却留一堆空文件夹，服务器会越来越乱）。 两条安全护栏：

1. 只删同步状态里记录过的文件（即这个插件自己传上去的）—— 你手动放在服务器上的文件永远不会被删；
2. 删除失败（比如 404）也算成功；真的失败会在日志里报出来。

如果你会经常改文件名、挪目录（比如整理笔记结构），建议打开它；如果只是往里写文件，保持默认即可。

哪些文件不会同步

• 以 . 或 _ 开头的目录一律不同步（.git、.build、.obsidian、_draft 等版本控制、 缓存与草稿目录不必逐个列）。此规则只作用于目录：以 _ 开头的文件（如 _template-规格表.md）照常同步。
• 构建产物目录 dist / build 不同步。
• 同名目录 node_modules、inbox、.mnt 不同步。
• 插件自身的配置与状态文件（.memory-sync.json、.memory-sync-state.json）永不参与同步。

同步时机

时机	动作
会话开始	拉取（等待完成后才开始，确保用到最新记忆）
每轮对话前	后台拉取（不阻塞对话；pullIntervalMs 内只拉一次）
工具调用结束后	等待 debounceMs → 推送（期间的多次改动合并为一次）

多台机器与冲突

同步按时间戳判断，不做自动合并：

情况	处理
服务器上有新版本、本地没动	拉取并覆盖本地
本地有改动、服务器没动	保留本地，稍后推送
两边都改了同一个文件	以服务器版本为准，同时把本地版本另存为 xxx.conflict-时间戳

使用建议：同一时间只在一台机器上编辑记忆，其余机器开工时会自动拉到最新版本。

兼容的 WebDAV 服务

本插件使用标准 WebDAV，不绑定任何厂商：

服务端	是否可用
群晖 / 威联通等 NAS 的 WebDAV Server	✅
Nextcloud / ownCloud	✅
坚果云（WebDAV）	✅
Apache mod_dav / Nginx + WebDAV 模块（自建）	✅
Windows IIS WebDAV	⚠️ 通常不可用（href 返回完整 URL）

排查

先把 verbose 打开，同步细节会写入日志。

现象	可能原因
插件已加载但不传输	未读到配置：确认设置已保存，或 .memory-sync.json 在正确目录
401	账号或密码错误；账号对该目录无权限
404	remotePath 不存在 —— 请先在服务器上建好目录
一直超时	地址不通：先用浏览器打开该 WebDAV 地址确认
密码正确但仍报 401	部分 NAS（如群晖）有自动封锁：多次认证失败会封禁来源 IP，需在控制台将其移出封锁列表

安全

• .memory-sync.json 内含明文密码，已在 .gitignore 中排除 —— 请勿提交或外发
• 建议在服务器上单独建一个账号，只授予记忆目录的读写权限
• 建议使用 HTTPS 的 WebDAV 地址，避免明文传输
• 本插件不会把配置与状态文件同步到服务器

开发与自检

客户端设置卡片源码位于 src/client/index.js，需打包为 DSH 的 lazy-CJS 格式（产物 lib/client.js 已提交， 使用者无需构建）：

pnpm install
pnpm run build                  # 生成 lib/client.js
bash scripts/sync-to-profile.sh # 同步到已安装的 profile 副本

自检（修改同步逻辑前建议先跑）：

node test/smoke.mjs            # 86 项离线自检：进程内假 WebDAV + 真实 apply()，无需网络与密码
node test/real-pull-check.mjs  # 对真实服务器做只读拉取校验（读取 DSH 设置里的配置）

test/smoke.mjs 中的假 WebDAV 刻意照抄主流 NAS 的真实响应格式（<D:response> 带 xmlns 属性、 属性元素使用 lp1: 前缀、href 采用 URI 编码），并支持 MOVE / Depth: 0 / 「故意只存前 N 字节」， 用来钉住「原子上传」与「完整性校验」。

推送前的隐私闸门（仓库里不许出现开发文档 / 配置 / 私人信息）：

bash scripts/install-hooks.sh    # 装 pre-push 钩子（装一次即可，之后每次推送自动跑）
bash scripts/privacy-check.sh    # 手动跑一遍：查跟踪的文件 + 全部历史
bash scripts/privacy-check.sh selftest   # 确认闸门本身没失灵

诊断用环境变量：

变量	作用
DSH_MEMORY_SYNC_DEBUG=1	输出详细诊断日志
DSH_MEMORY_SYNC_CARD=0	禁用设置卡片（卡片异常时用于保证 DSH 仍能启动）

插件机制与维护细节见上级目录的 DEVELOPMENT.md（维护手册：坑与决策）与 TECH.md（插件机制、构建与发布）。

许可

MIT