ygc-dsh-sync-backup
Verifiedygc-dsh-sync-backup · v0.9.1 · MIT · Web UI
DSH 会话跨机同步备份:按工作区落地、按机器隔离、一轮对话结束即备份、一键拉取别机会话。
Install
dsh plugin add ygc-dsh-sync-backup Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Published to npm without a public repository. Inspect the package contents before installing.
Tags
Readme
会话同步备份(dsh-sync-backup)
把指定文件夹内工作区的对话,按机器隔离备份到工作区里;支持一键拉取其他机器的会话。
它做什么
工作区位于「特定文件夹」内时,自动建立:
<工作区>/
└─ .dsh-sync/sessions/
├─ <本机标识>/ ← 只有这一格可写
│ └─ <sessionId>/session.v4.jsonl.zstd
└─ <其他机器标识>/ ← 只读,拉取时读
三条规则:
- 一轮对话结束即备份。 你发出自然语言 → 到最终回复生成完毕算一轮,中间插话也算这一轮。落盘时机是
turn/end后再等 4 秒,把这一轮写完的东西一次写掉。 - 只写自己的目录。 所有写入走同一个守卫(
assertWritable),目标不在<工作区>/.dsh-sync/sessions/<本机标识>/下就抛错。别的机器的目录只读。 - 备份是原字节复制。 会话文件是多帧 zstd,整段重压会让 dsh 判
corrupt session log,所以从不重新压缩。
本机标识
格式 <名称>-<特征值>,例如 DSH-b78936a7c1d2。
特征值在插件第一次安装时生成一次,之后永久固定,永不重算。
- 来源是随机字节,不是主机名 / MachineGuid 复算
- 所以换主机名、注册表读不到、甚至重装系统都不会让标识漂移
- 生成时间记在
machineHashGeneratedAt,可追溯 - 唯一的迁移来源是老版本 state 里已有的哈希——那是既有目录名,必须原样继承,否则已备份的会话找不回来
名称部分可改:面板上填「李超台式」,标识变成 李超台式-b78936a7c1d2,特征值不变。改名后新备份写进新目录,旧目录不删。
状态文件:~/.dsh/storages/sync-backup.json
巡检
扫描每个「特定文件夹」的直接子目录:
| 情况 | 处理 |
|---|---|
有 .dsh-sync/ 但本机未注册 |
列进「待注册」,等你勾选确认后才注册 |
已注册但缺 .dsh-sync/sessions/<本机标识>/ |
自动补齐(只建空目录) |
没有 .dsh-sync/ |
忽略 |
| 已完整 | 忽略 |
不会扫进二级子目录,避免把 工作区A/子目录 误注册成独立工作区。
定时巡检:固定间隔
面板上勾选「定时巡检」并填间隔分钟数(默认 30,范围 1–1440)。
排程规则:
- DSH 启动后先巡检一次(开机自动巡检,启动后约 8 秒)
- 以这次巡检为起点计时,之后每 N 分钟一次
- 关闭再启用会重新首跑一次
- 改间隔立即生效:从上次运行时间按新间隔重算,不用等完旧周期
- 跨多个周期只补跑一次,不积压
实现上每 30 秒检查一次是否该跑;计时起点是进程内的 nextDueAt,不是持久化的时间戳,所以每次启动都会立即巡检,而不是"上次刚跑过就再等一会儿"。
DSH 关闭期间不跑,这是插件内定时器的固有限制。要关机也跑请用 dsh-automation。
注册时会顺手补齐本机特征文件夹。workspaceRegistry.create() 本身幂等,重复注册不会产生重复实体。
一键拉取
把别机备份的会话导回本机 ~/.dsh/sessions/。冲突按内容判定,不看时间戳(NAS 同步会改 mtime):
| 情况 | 判定 | 动作 |
|---|---|---|
| 两边字节一致 | 相同 | 跳过 |
| 本机是别机的前缀 | 别机更新 | 覆盖本机(旧副本存进 .conflicts/) |
| 别机是本机的前缀 | 本机更新 | 跳过 |
| 两边都不是对方前缀 | 真分支 | 本机保留,别机那份导入为新 sessionId 并加标题后缀 |
会话日志是 append-only 的,所以「谁是前缀」用字节比较就能判,不需要解压。
拉取时会把 header 的 cwd 改写成本机这个工作区的路径——同一个工作区在宿主机是 W:\、在用户机是 D:\,不重写会归错工作区。只重写首帧,尾部帧逐字节保留。
不需要重启 DSH。 旧的说明写「新导入的会话需要完全退出 DSH 重开后才出现在侧栏」,那句话掩盖了真问题:当时缺的是归属登记,不是索引刷新。sessionQuery.listSessions() 每次调用都重新读盘 + 读归属表,没有缓存层,所以登记归属即时生效。
三者缺一不可
拉取要真正落到「对应的工作区」而不是「未分组」,四件事都得做全:
| 环节 | 旧版状态 | 后果 |
|---|---|---|
| 工作区目录里有别机备份 | 有 | — |
| 目录已注册成工作区 | 可能没有 | /pull 的匹配范围里都没有它,永远拉不到 |
会话日志写进 ~/.dsh/sessions/<projectKey>/ |
有 | — |
sessionId 登记进 workspace.json 的归属账 |
没有 | 侧栏只认归属账,没登记就是「未分组」 |
- 未注册的目录自动注册:
/pull先扫一遍,凡是「目录里有.dsh-sync/、且确实存在别的机器的会话备份」的,自动workspaceRegistry.create()后再拉。空壳目录不碰。传autoRegister: false可关闭。 - 拉完必须登记归属:DSH 只在「新建 / 分叉会话」时自己调
attachSession();启动期的一次性 bootstrap 也只在initialized=false时跑一次。所以插件拉进来的会话必须自己补这一步,否则永远是「未分组」。 - header.id 必须跟着分叉改:目录名 =
encodeSegment(header.id)。只改目录不改 header,会让同一个header.id出现在两个 projectKey 下,sessionPersistence直接抛duplicate JSONL session id,整块工作区停摆。
补登记历史残留
旧版只写文件没登记,那些会话至今散在「未分组」里。面板上点「补登记归属」即可修回,或:
curl -X POST http://127.0.0.1:<PORT>/api/local/dsh-sync-backup/attach/repair \
-H 'content-type: application/json' -d '{}'
默认只补拉取产物(别的机器备份目录里确实有它)。自动化插件和子代理留下的会话也命中 cwd,但它们不是拉来的,无差别补会让侧栏一次多出上百条——要全量补必须显式传 {"all": true}。
路径不可达的工作区(NAS 没挂载)登记会失败,会话仍留在磁盘,路径恢复后下次巡检自动补上。
界面
侧栏底部一个图标,点开是主面板:
- 本机标识(可改)
- 特定文件夹列表(可增删,命中其下的工作区才备份)
- 统计:本机已备份会话数、占用空间、其他机器可拉取数、最近备份时间
- 一键拉取 / 立即备份全部 / 补登记归属(可多选工作区)
- 最近记录
样式只用 --dsw-alias-* 主题令牌,跟随明暗模式。
技能同步
把母版文件夹里的技能拉到本地 ~/.agents/skills/ 部署。
四条规则
| 情况 | 处理 |
|---|---|
| 母版有、本地无 | 拉取到本地 |
| 两侧都有,母版版本更高 | 拉取覆盖本地(旧版备份到 .pre-pull-<时间戳>/) |
| 两侧都有,本地版本更高或内容不同 | 只报告,你在面板上勾选并点「推送到母版」才执行 |
| 本地有、母版没有 | 跳过,不放进母版,本地也原样保留 |
母版里删掉的技能,本地什么都不做——不删、不搬,就是留着不用。
记忆插件的技能优化:同步时自动处理
记忆插件(dsh-mnemon)会自己审查会话、写技能草稿,但草稿写完停在
ledger.json 的 drafts[] 里等人在面板上点「采纳」。放着不管就越积越多
(本机曾积 12 份),而技能同步只看磁盘上的 SKILL.md——草稿还没落地,
一条都同步不出去。
所以每轮技能同步开头先做一次预处理,把两端接起来:
- 读
~/.mnemon/skills/ledger.json,取status="ready"的草稿(同技能多份取最新) - 校验:技能名能当目录名、frontmatter 的
name对得上、update草稿的baseHash仍等于当前SKILL.md的 sha256 - 落地到本机
~/.agents/skills/<技能名>/SKILL.md,旧版备份到.pre-mnemon-<时间戳>/ - 立刻推回母版,旧版备份到
_backup/<技能名>.<时间戳>/,并在母版_技能修改记录.md写一条,触发方式记为「记忆插件优化」 - 然后照常比对/拉取/推送——这一轮看到的已经是落地后的内容
为什么单独推一次:草稿是本插件刚落的,谱系里还没记过这份内容,按判据会 落进「待你决定」。这一步是明知新,不猜。
四条边界:
| 情况 | 行为 |
|---|---|
本机 SKILL.md 已经是这份草稿的内容 |
跳过(already-applied),重复跑幂等 |
update 草稿的 baseHash 与当前文件不符 |
跳过(stale-base),期间有人改过,交给待裁决 |
create 草稿撞上已有同名技能 / 技能属性为「母版有·本机不拉取」 |
跳过 |
targetRoot 是 project-* |
跳过(project-scope),项目技能不进母版 |
落地之后要结案,否则面板永远显示「待审」
只把文件写进去、账本不动,面板上那条建议就永远停在 review、草稿永远停在
ready——看起来一直有活没干。所以落地成功后会顺手把账本里对应的
draft 与 suggestion 标成 adopted。
写账本是安全的,因为记忆插件每次操作都从磁盘重读 ledger.json
(SkillsStore.ledger() 里就是 readJson),没有内存缓存。只要格式对得上:
| 项 | 规则 |
|---|---|
generation |
每次写入 +1(插件用它算 revision,不 +1 会被当成没变) |
reviews |
截到最新的 200 条 |
drafts |
非 ready 的只留 60 份(ready 全留,等处理) |
| 落盘 | 先写 <file>.<pid>-<uuid>.tmp 再 rename,mode 600 |
| 并发 | 写之前比对 size + mtime,期间被改过就整体放弃,下一轮再来 |
结案判据仍然只用内容哈希:磁盘上的 SKILL.md 必须还等于草稿内容才结案。
刚落完就被人改回去、或者本机根与草稿目标根对不上,一律不结案,留在 ready
等下一轮。
面板上「记忆插件优化自动处理」可关(skills.mnemonAuto,默认开);
关键设置:POST /skills/config 传 {"mnemonAuto": false}。
已经积压的历史账本
外部流程(本插件早期版本、手工采纳)落地过的草稿,账本里仍停在 review。
用 C:\DSH-Work\mnemon-reconcile\reconcile.mjs 一次性对账:
node reconcile.mjs # 预演,只报告
node reconcile.mjs --apply # 真写(先自动备份 ledger.json)
它按同样两条判据分流:内容对得上 → 结案并补一条 reason=evolution 的版本记录
(正文落到 versions/<sha256(skillKey) 前16位>/<id>.md,与插件 recordVersion 同格式);
对不上 → 草稿标 discarded、建议退回 pending 重新起稿。早已过期的建议顺手删掉。
新旧怎么判
不看版本号。 记忆插件优化技能时不升 version,按 version 比只会把已经优化的 版本判成「版本相同但内容不同」,永远卡在待确认。
也不看文件 mtime。 NAS 同步、拉取、拷贝都会刷 mtime,它跟内容新旧无关。
判据按硬度依次尝试,命中即停:
| 顺序 | 判据 | 依据 | basis |
|---|---|---|---|
| 1 | 内容修改时间 | 谱系文件记录的「两侧各自的内容何时变成现在这样」 | content-time |
| 2 | 只一侧变过 | 上次比对时记的内容,现在只有一侧还对得上 → 另一侧是改的 | content-time |
| 3 | 记忆插件演化记录 | ~/.mnemon/skills/ledger.json 里 reason=evolution 的哈希 + 时间 |
mnemon |
| 4 | 历史快照时间 | 母版 _backup/、本机 .pre-pull-*、记忆插件 versions/、母版修改记录 |
content-time |
| 5 | 谱系基线 | 上次两侧一致时的内容树;只有一侧偏离 | lineage |
| 6 | 包含关系 | 一侧完全包含另一侧(纯新增,没改写原意) | superset |
六段都拿不到证据 → 归「待你决定」,不自动覆盖任何一方。
「内容修改时间」到底是什么
不是 stat 出来的 mtime,是同步插件亲眼看到内容变成现在这样的那一刻:
- 每次比对都会把两侧当前的内容哈希记进
<母版>/.skill-lineage.json - 同一个哈希再次观测,时间保持不动——内容没变就不算改动,哪怕文件被 NAS 搬过、mtime 全变了
- 内容真变了才刷新时间
所以「谁的内容时间更晚,谁就是新版」这句话,在同步场景下才成立; 换成 mtime 就完全不成立。
记忆插件的修改留下了什么
三样东西,全部只读,记忆插件一行代码都不用改:
| 痕迹 | 位置 | 能证明什么 |
|---|---|---|
| 演化版本记录 | ~/.mnemon/skills/ledger.json → versions[] |
采纳草稿时写一条 reason="evolution",hash 正是新 SKILL.md 的 sha256 —— 「这次是记忆插件改的」最硬的证据 |
| 历史全文快照 | ~/.mnemon/skills/versions/<sha256(skillKey) 前16位>/<versionId>.md |
当时那份全文,可做三方对比 |
| 演化建议/草稿 | ledger.json → suggestions[] / drafts[] |
还没采纳的改动在 drafts[].content,已采纳的进 versions[] |
它的目录名就是 sha256(skillKey).hex.slice(0,16),skillKey 形如
user-dsh:kb-zhishiku —— 不用猜,照算就能对上号。
注意:记忆插件平常的技能注册表不在账本里(那是宿主扫磁盘得出的),账本只记 「安装」和「演化」。所以账本里查不到某个技能,不能推断是谁改的—— 这种情况下判据继续往后走,不硬判。
$ node tools/skill-lineage.mjs --status
母版:D:\Ai工作空间\技能库
本机:C:\Users\DSH\.agents\skills
谱系:43 条观测
账本:2 个技能有记忆插件记录
一致 43 · 待你决定 4
本机新 demo [content-time] 上次比对后本机内容变了(11-01 21:51 之后)
母版新 demo2 [content-time] 母版这份内容更晚(11-01 22:03 vs 10-30 10:18)
本机新 demo3 [superset] 本机内容完全包含母版内容(只增不减)
待你决定 x [-] 两侧内容都改写过、没有快照或演化记录可比,需要你决定(保留哪边)
比对就是同步
规矩:同步属性的技能,比对时就把能定下来的做掉。
| 判定 | 动作 |
|---|---|
| 母版更新 | 自动拉取覆盖本机(旧版备份到 .pre-pull-<时间戳>/) |
| 本机更新(同步属性) | 自动推送覆盖母版(旧版备份到 _backup/<技能>.<时间戳>/,并写修改记录) |
| 判不出来 | 什么都不动,列在面板上等你裁决,附差异摘要 |
POST /skills/scan 带 {auto: false} 时退化为纯比对(只报告,不动文件);
面板上的「比对」按钮走自动模式,定时器也是。
判不出来的那些会带一份差异摘要,一眼看出两边差在哪:
母版独有 3 行、本机独有 12 行(14770 vs 14735 字节)
- 旧的那一行
+ 新的那一行
为什么不能靠 version 硬撑
版本号只能表达「谁手工标得更正式」,表达不了「谁的内容是后来的」。 存量 48 个技能里:
kb-zhishiku本机 2.0.0 / 母版 1.0.0 —— 版本号确实能分skill-creator两侧都没有 version —— 版本号完全失效expert-copywriting两侧都是 1.0.0 但内容不同 —— 版本号给出错误结论
现在这三种都由内容时间处理;真分不出来的才落到「待你决定」。
给技能补 version
tools/add-version.mjs 批量补 version: 1.0.0:
node tools/add-version.mjs --dry # 只看会改哪些
node tools/add-version.mjs # 实际写入
node tools/add-version.mjs --dir <路径> # 指定技能根
行为:
- 已有
version的跳过,不覆盖 - 无 front matter 的跳过,不强加
- 保留原编码(UTF-8 无 BOM / 有 BOM)
- 保留换行风格(CRLF / LF)
- 改写前备份为
SKILL.md.bak-<时间戳> - 幂等:重复运行不产生第二份备份
2026-10-29 已对 42 个技能执行,全部补为 1.0.0,42 份备份在各自目录下。wx-send-image 是空目录(无 SKILL.md),未处理。
2026-11-01 起 version 不再参与新旧判定——它只是个给人看的标记。
判定改按内容修改时间,见上文「新旧怎么判」。补 version 这一步留着,
只是因为部分技能商店/清单用得上。
单机属性(技能列表)
每个技能有一个只存本机的属性,三种值:
| 属性 | 含义 | 改为该属性时做的事 |
|---|---|---|
| 同步 | 正常双向 | 本机有 → 推送到母版;母版有本机无 → 拉到本机 |
| 本机独属 | 本机有、母版不该有 | 删除母版,保留本机(母版备份到 _backup/) |
| 母版有·本机不拉取 | 母版有、本机不要 | 删除本机,保留母版(本机备份到 .pre-mode-<时间戳>/) |
未显式设置的按自动判定:本机有、母版没有 → 本机独属;其余 → 同步。
属性只写本机 state(~/.dsh/storages/sync-backup.json 的 skills.modes),不随母版走,所以每台机器可以各设各的。
对母版的删除和新增都会写进母版修改记录,记录里能看出谁、什么时候、加了还是删了。
修改本机或改属性失败时不会落属性——只有实质动作成功才记。
每次插件对母版写入,都在母版根目录追加一条记录。
文件:<母版>/_技能修改记录.md
- 不存在时自动创建(带表头)
- 已存在则只追加,保留全部历史
- 设置母版路径时就会建好,不用等第一次推送
字段:
| 列 | 内容 |
|---|---|
| 时间 | 本机时间,精确到秒 |
| 操作者 | <本机名称> (<本机标识>) |
| 操作 | 覆盖 / 新增 |
| 技能 | 技能名 |
| 触发方式 | 用户授权 / 自动 |
| 说明 | 覆盖时记旧版备份路径,新增时记「母版此前无此技能」 |
例:
| 2026-10-29 16:20:31 | 李超台式 (DSH-7e6b1bb7e052) | 覆盖 | expert-code-review | 用户授权 | 旧版备份于 _backup/expert-code-review.20261029-162031 |
只有实际写入母版才记录。拉取(母版 → 本地)不碰母版,不产生记录。
竖线和换行会转义,不会破坏表格。母版只读时记录失败不阻断推送,只在响应里报错。
面板上「查看母版修改记录」可直接读最近 30 条。
推送本地独有技能
本地有、母版没有的技能默认跳过。要让它进入母版,在面板上勾选后点「推送到母版」——此时属于用户明确要求,操作类型记为 新增。
定时(技能同步)
- 开机拉取一次(启动后约 12 秒)
- 之后每
intervalMinutes分钟一次,默认 120 - 改间隔立即生效
- 与巡检共用同一套排程语义
- 每轮开头先跑记忆插件预处理(见上文),可在面板关掉
与旧脚本的关系
本插件接管技能同步。 如果 Sync-Skills.ps1 还在跑,它和本插件会同时对 ~/.agents/skills 动手,可能互相覆盖。请停掉:
# 停掉计划任务
Unregister-ScheduledTask -TaskName 'DSH-SyncSkills' -Confirm:$false
# 停掉登录自启的守护(如有)
Get-Process | Where-Object { $_.CommandLine -like '*Sync-Skills*' }
推送时母版旧版会备份到 <母版>/_backup/<技能名>.<时间戳>/。
接口
/api/local/dsh-sync-backup/
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /state |
配置、匹配工作区、统计、巡检与技能状态 |
| POST | /config |
保存 folders / machineName |
| POST | /backup |
备份(workspaceIds 可选) |
| POST | /preview |
预判拉取会做什么,不写文件 |
| POST | /pull |
拉取(workspaceIds、machines 可选) |
| POST | /patrol/scan |
巡检扫描,只读 |
| POST | /patrol/register |
注册选中的目录 + 补齐特征文件夹 |
| POST | /patrol/repair |
补全缺特征文件夹的工作区 |
| POST | /patrol/config |
定时巡检开关与间隔分钟数 |
| POST | /skills/scan |
技能比对,只读 |
| POST | /skills/pull |
拉取母版技能到本地 |
| POST | /skills/push |
把本地技能推回母版(覆盖或新增),并写修改记录 |
| POST | /skills/config |
母版路径、开关、间隔 |
| POST | /skills/changelog |
读母版修改记录 |
| POST | /skills/list |
技能列表 + 单机属性 |
| POST | /skills/mode |
切换属性并执行实质动作 |
测试
node test/projectkey.test.mjs # projectKey 编码与真实目录名比对
node test/zstd.test.mjs # 多帧 zstd 边界、尾部保留、前缀判定
node test/guard.test.mjs # 写权限边界(含同名前缀陷阱)
node test/api.test.mjs # 基础端点、前缀匹配、去重
node test/e2e.test.mjs # 备份 → 拉取 → 分叉 全流程
node test/patrol.test.mjs # 巡检发现、补全、标识拆分拼接
node test/patrol-api.test.mjs # 巡检四个端点 + 改名
node test/hash.test.mjs # 特征值生成规则
node test/persist.test.mjs # 跨进程持久性:生成后永不改变
node test/schedule.test.mjs # 排程:开机首跑 + 间隔计时 + 改配置立即生效
node test/host-load.test.mjs # Host 半加载与清理
node test/skills.test.mjs # 技能:版本比较、树哈希、比对规则、拉取推送
node test/skills-api.test.mjs # 技能四个端点
node test/changelog.test.mjs # 修改记录:自动建、追加、转义、只读容错
node test/changelog-api.test.mjs # 推送时写入记录、新增/覆盖区分
node test/addversion.test.mjs # 补 version:编码/换行保留、幂等、跳过规则
node test/client.test.mjs # 客户端契约:注入、注册配对、locale、组件可调用
node test/mode.test.mjs # 单机属性:三种切换的实质动作与审计
node test/mode-api.test.mjs # 列表与属性切换端点
共 325 项。
已知限制
- 拉取进来的会话要重启 DSH 才可见(无热重扫接口)。
- 不接管任何既有同步脚本,只管
.dsh-sync/sessions/<标识>/这一块。 - 冲突留档放在本机标识目录内的
.conflicts/,不写工作区其他位置。