English | 简体中文

dsh-cold-backup

dsh-cold-backup 是一个纯第三方 DeepSeek Harness 插件：在 Harness 的 Web UI 里加一页「备份」， 回答一个问题——我的定时备份到底跑了没有、最近一次成功是什么时候。

它读的是「冷备约定」留下的三样东西，任何满足下面任一条的备份方案都能接入：

来源	含义	怎么读
成功时间戳文件	最近一次成功的时间	文件内容为 epoch 秒；不是纯数字就退回用文件 mtime
失败日志	最近一次出问题的记录	取最后一行（约定会追加，所以最后一行最新）
launchd 任务	定时任务是否加载、上次退出码	launchctl print gui/<uid>/<label>
状态命令（可选）	任意自检命令	退出码 0 视为正常，输出会显示在面板里
JSON 状态命令（可选）	结构化状态文档	跑一条命令（如 cold-backup --status --json），读它的 cold-backup.status/1 JSON；解析成功时以它为准，并显示逐目标明细

判定规则只有一条值得记住：只要失败记录没有被后来的成功「盖过」，就报有问题。 用的是 >= 而不是 >——因为一次运行可能在同一秒里既写下成功时间戳、又留下失败记录， 用 > 会把这种情况静默藏掉（见 docs/decisions.md）。

功能

• 一眼看全的新鲜度 —— 面板顶部是状态点＋结论：正常 / 需要留意 / 有问题 / 尚未配置。
• 说清「为什么红」 —— 不是只给一个颜色，而是列出具体原因（过期 N 小时、状态文件不存在、 launchd 未加载、退出码非 0、失败未被盖过……），中英双语。
• 自动刷新 —— 面板打开期间按 refreshSeconds 轮询 Host 半侧的路由，另有「立即刷新」。
• 三处联动的一致性 —— 包名、cordis.patch.yml 的 id、Host 的 ENTRY_ID、Client 的模块 id 由测试强制对齐；这四者不一致时 Client 半侧会静默不加载，是同类插件的常见事故。
• 零运行时依赖 —— Host 半侧只用 node 内置模块，唯一的 dependency 是 @deepseek-ai/schemastery （只用来声明 Config）。

要求

• Node.js ^22.19 或 >=24
• DeepSeek Harness 0.2.0-rc.2（本版本已实测；见 docs/evidence/）
• launchd 那一项仅 macOS 可用，其他来源跨平台

安装

装进一个自带 Web 界面的 profile。包本身不含任何指向 Harness 检出目录的路径依赖， dsh.bundle 里的 patch 会自动把 Host 与 Client 两行插件接进去：

dsh --profile web-backup --from-default-profile web --dump-config
dsh plugin --profile web-backup add dsh-cold-backup
dsh --profile web-backup

装本地构建的 tarball 也行：

npm pack
dsh plugin --profile web-backup add ./dsh-cold-backup-<版本>.tgz

配置

在 设置 → 插件 → dsh-cold-backup 里改，全部字段都标了 volatile()，改完立即生效、不用重启：

字段	默认值	说明
freshnessFile	~/Library/Logs/cold-backup/last-ok	最近成功时间戳文件
failureFile	~/Library/Logs/cold-backup/last-failure	失败记录（留空关闭）
launchdLabel	空	要检查的 LaunchAgent label（留空关闭）
statusCommand	空	可选自检命令，退出码 0 视为正常
statusJsonCommand	空	可选：打印 cold-backup.status/1 JSON 的命令（例如 cold-backup --status --json）。解析成功时以它的判定为准，并显示逐目标明细
staleAfterHours	36	超过这么多小时没成功就报「需要留意」
refreshSeconds	30	面板轮询间隔

默认值直接对应冷备约定（last-ok 存 epoch 秒、last-failure 追加记录）—— 也正是配套备份引擎 cold-backup 在 macOS 上的默认位置， 所以「用 cold-backup + 装本插件」这条路一个字段都不用改。 换成别的备份方案时，只要把路径指过去即可，不需要这个约定本身。

举例：如果你的备份是 launchd 任务 com.example.nightly-backup、成功时间写在 ~/.backup/last-ok， 就把 launchdLabel 填 com.example.nightly-backup、freshnessFile 填 ~/.backup/last-ok。

它是怎么工作的

Host 半侧 (index.js)                      Client 半侧 (client.js)
  ├─ 读状态文件 / launchctl / 状态命令       ├─ 往 settings.section 注册一页「备份」
  ├─ evaluateStatus() 归一成 ok/warn/       ├─ 按 refreshSeconds 轮询 Host 的路由
  │  bad/unknown + 机器可读的 reasons        └─ 中英双语，列出每条 reason
  └─ 在 /dsh-cold-backup/status 上出 JSON

健康判定与解析全是纯函数，node --test 覆盖 28 项，不需要真实 Harness 即可跑：

npm test

JSON 契约（cold-backup.status/1）

statusJsonCommand 读的是一份跨工具共用的判定：配套的 macOS 面板（Backup.app）读的是同一份， 所以两处显示不可能各说各话。

字段	含义
schema	cold-backup.status/ 前缀；不匹配的文档一律不当成自己的
verdict	ok | bad（与那条命令的退出码一致）
reasons[]	{code, target, message}；code 是机器可读的英文标识，message 由脚本给出（保持中文 —— 脚本是与 launchd、文档、自测共用的事实源）
targets[]	每个仓库/快照/配置一条：state（ok/behind/missing/skipped）、upload、at、bytes、sha256、dirty、message
counts / orphans / lastOk / lastFailure	汇总计数、云盘残留、成功与失败信号

配置了它之后，判定权在脚本：本插件不再自己重算规则（历史上两边各写一份，面板用 >、插件用 >=， 已经漂移过一次）。没配、或输出不是合法文档时，回落到上面三种通用来源；「配了但用不了」会明确报成问题， 不会静默回落。

与冷备方案（cold-backup）的关系

本插件是备份方案的 UI 前端，不替代备份本身。冷备方案指的是：一个定时任务把 「最近成功时间」写进一个文件、把失败追加进一个日志，需要时再配一个 launchd 任务兜底。 插件只读这些产物，不写、不触发、不删除任何东西——所以它可以安全地常开。

配套的备份引擎是 cold-backup （npm i -g cold-backup，无依赖的 bash CLI，macOS / Linux）：

npm i -g cold-backup      # 备份引擎：bundle + 快照 + 配置白名单 → 你的同步目录
cold-backup --init        # 生成配置，填 ROOT 与 DEST
cold-backup schedule install

它不是必需的：任何写出 last-ok / last-failure、或能输出 cold-backup.status/1 文档的 备份方案都能接这个面板。反过来，cold-backup 也不依赖本插件——它自带 --status， 本插件只是把同一份判定搬进了 Harness 的 UI。

许可证

MIT，见 LICENSE。