前言¶
在 DSH（DeepSeek Harness）的 Maestro 工具链中，本地文件系统往往承载着记忆和会话数据。当需要在多台机器间同步这些状态时，直接使用 rsync 等工具存在覆盖不可见文件、缺少预览机制或破坏现有结构的风险。dsh-maestro-sync 旨在提供一个安全的、可预览的、带备份的同步方案。
是什么¶
这是一个由 ddtcorex 维护的插件，许可证为 MIT。它的核心作用是跨机器合并记忆和会话，支持发布模式。
安装与启用¶
安装该插件需要执行以下命令：
dsh plugin add @ddtcorex/dsh-maestro-sync
核心功能与用法¶
安全同步：先预览，再应用¶
该插件不提供“直接覆盖”的同步方式。所有同步操作都必须经过预览阶段，确认无误后才能应用。
1. 预览同步
使用 --dry-run 参数进行只读预览。此时不会进行任何写入操作，系统会计算差异并输出一个 SyncPreview 对象，包含预览 ID、版本号和过期时间。
node lib/cli.js --pull --dry-run
2. 应用预览
应用操作必须同时满足三个条件：--apply、--preview-id（上一步输出的 ID）以及 --confirm（操作员确认）。
node lib/cli.js --pull --apply --preview-id <id> --confirm
3. Stale-guard 机制
应用时会重新盘点双方机器状态。如果自生成预览以来有任何文件发生变化，同步会被拒绝，状态为 STALE_PREVIEW，不会执行写入。
R2 离线备份¶
插件支持将符合条件的记忆和会话日志备份到 S3 兼容的对象存储（如 Cloudflare R2）。
配置
在 ~/.dsh/maestro/settings.json 中配置 domains.sync.r2 字段，包含 accountId、bucket、prefix 和 region。
凭证
备份凭证不支持明文存储在设置中，仅支持以下方式：
* 环境变量：R2_ACCESS_KEY_ID / R2_SECRET_ACCESS_KEY
* 私有侧车文件：~/.dsh/dsh-maestro-sync/backup-secrets.json（权限需为 0600）
备份行为
* 预览备份：只读，对比本地哈希与存储中的清单。
* 应用备份：上传缺失的 Blob，生成不可变的清单，并推进 HEAD 指针。
* GC 策略：保留最近 30 个每日清单和 12 个每月清单。
恢复与容错¶
Fail closed 机制
同步过程中如果发生传输或发布失败，不会回退到破坏性的 rsync 覆盖模式。只有当所有文件都成功发布时，返回状态才为 ok:true。
数据恢复
每个被覆盖的文件旁边都会生成一个时间戳备份文件（格式为 .bak.<timestamp>.<random>）。如果需要回滚，可以直接恢复备份文件：
cp <path>.bak.* <path>
适用范围与限制¶
该插件仅对特定文件生效，包括 dsh-maestro-memory/**/*.md、dsh-maestro-memory/SUGGESTIONS.jsonl 以及 sessions 目录下的文件。
以下内容在同步和备份时会被排除，不会被读取、哈希或复制：
* 设置文件、隧道配置、秘密材料
* 配置文件、Supervisor 状态、存储
* 工具、技能、日志、缓存
* 所有 .bak.* 备份文件
开发¶
若需对插件进行本地验证或构建，可以使用以下命令：
pnpm --filter @ddtcorex/dsh-maestro-sync verify
