ddtcorex/dsh-maestro-sync

dsh-maestro-sync

Maestro 测试框架同步——跨机器合并内存和会话（可发布）

DSH Maestro 插件——属于 dsh-maestro- 生态系统（@ddtcorex/dsh-maestro-sync）。

安装

dsh plugin add @ddtcorex/dsh-maestro-sync

安全同步——先预览再应用

同步是精确的、先只读预览、再确认应用：

1. 预览（只读，不写入，60 秒 TTL）——查看计划的唯一方式
node lib/cli.js --pull --dry-run      # 或 --push --dry-run
stdout：一个最终 JSON SyncPreview { ok, previewId, revision, expiresAt, summary, actions }
人类可读的进度输出到 stderr

2. 应用你刚刚审阅过的那个精确预览（三项全部必需）
node lib/cli.js --pull --apply --preview-id  --confirm

- 任何被省略的布尔标志都无法应用同步。 缺少 --preview-id 和
--confirm 的 --apply 会以非零状态退出；旧版的 pull/push 路由和工具
是仅预览的兼容别名，永不写入。
- 陈旧防护： 应用时会重新盘点两台机器，重新计算计划，如果自预览以来
有任何变化，则将其拒绝为 STALE_PREVIEW——绝不会针对陈旧计划执行写入。
每个预览 id 只能应用一次。
- 仅限符合条件的项： dsh-maestro-memory//.md（不含 .bak.）、dsh-maestro-memory/SUGGESTIONS.jsonl、sessions///session.jsonl.zstd
- 传输： 仅通过 argv 的 spawn/rsync --files-from，无 shell 插值；
远程根目录是经过校验的绝对路径。~/.dsh 默认值由 SSH 预检
（printf %s '$HOME'）解析为绝对远程主目录，绝不通过 shell 的 ~ 展开。
- 会话： 仅通过经过校验的 Zstd 产物 API 使用 Buffer/path；独立的
带校验和的头部帧会被保留，并按行并集合并。
- 原子发布： 拉取 = 对每个本地文件执行 backup + fsync(tmp) + rename + fsync(dir)；
推送 = 物化到私有操作目录，上传到
/.maestro-sync/stage//，然后由一个固定的 POSIX CAS 辅助程序校验
每个目标的 SHA-256（expectedTargetSha256），备份并原子重命名。
并发的远程变更会报告为 CONCURRENT_MODIFICATION，绝不覆盖目标。
- 故障关闭： 传输/暂存/发布失败会返回结构化的非零结果，并附带
committed/uncommitted 日志——仅当每个报告的文件都实际发布后才会
ok:true。没有回退到破坏性 rsync 的合并模式；--strategy=override
仅在单独提供 --ack-override 时存在。
- 恢复： 每个被覆盖的文件都会在其旁边保留一个带时间戳的备份
（.bak..；远程备份遵循相同规则）。使用
cp .bak.*  恢复。
- 同意： 实时应用是操作员操作——CLI 要求
--preview-id + --confirm；设置 UI 仅在绑定到实时预览的
确认对话框中提供“应用”。
- 主机预检： 在预览/应用之前，ssh -o ConnectTimeout=5 必须成功。
- UI： 设置 -> Maestro Sync -> 预览拉取/推送 -> 审阅
copy/merge/skip/conflict -> 确认对话框（方向、主机、
计划年龄、操作计数）-> 应用。

排除项（从不读取、哈希或复制）：设置、隧道配置文件、机密
材料、配置文件、监督器状态、存储、工具、技能、日志、缓存以及
.bak.。

R2 同步 — 异地备份（Cloudflare R2；通过同一客户端支持 AWS S3，UI 隐藏）

通过无依赖的 SigV4 客户端，将符合条件的数据（记忆 + 会话日志）备份和恢复到
兼容 S3 的存储桶。

- 配置（~/.dsh/maestro/settings.json → domains.sync.r2）：accountId、
bucket（默认 maestro-backup）、prefix、region；可选的
provider: "aws" 配合真实区域可通过同一客户端工作（阶段 1 中 UI
隐藏）。
- 机密材料：环境变量（R2_ACCESS_KEY_ID/R2_SECRET_ACCESS_KEY，
AWS AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY）或插件自身运行时目录中的
私有 0600 sidecar 文件 — 绝不在设置中，绝不记录日志，
绝不由 RPC/工具返回（状态仅显示 Env | Private file | Not
configured 以及存储桶/前缀）。
- 预览备份为只读：它将当前符合条件的哈希与
存储桶中的最后一个清单进行比较（不传输对象）。应用是唯一的上传
途径：它 PUT 缺失的 blob（内容寻址、幂等），写入
不可变清单并通过 CAS 推进 HEAD 指针；仅在 HEAD 推进后
才报告 ok（竞争时返回 CONCURRENT_MODIFICATION）。
- 恢复：恢复到新目录（绝不触碰实时主目录）或就地恢复
（每个被覆盖的目标保留一个 .bak..，fsync+rename），两者
均需先确认。GC：保留最新的 30 个每日 + 12 个每月
清单，仅删除不可达的 blob，需先确认。
- 实时 R2 条件写入行为由操作员同意的探针在阶段 3 封闭式假 S3 门禁之后
固定 — 构建或测试此功能无需 R2 账户。

开发

pnpm --filter @ddtcorex/dsh-maestro-sync verify
pnpm --filter @ddtcorex/dsh-maestro-sync build
pnpm --filter @ddtcorex/dsh-maestro-sync test