前言¶
在 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
