✨ 为什么需要它？

DeepSeek Harness 改配置、装插件、跑长任务都是家常便饭，风险也随之而来：

• 😱 改崩了 —— cordis.patch.yml 写错、插件冲突，DSH 启动失败白屏
• 😱 会话丢了 —— sessions 目录误删/损坏，几天的对话留档没了
• 😱 反复改反复崩 —— 不知道回退到哪一步才是好的，只能凭记忆重做
• 😱 单机无备份 —— 机器坏了/重装，全部配置与工作留档烟消云散

dsh-git-rescue 的思路：一切历史都是 git 历史。 版本管理交给 git，救援恢复就是回退， 远端备份交给 GitHub（token/SSH）。与现有的 zip 快照方案（dsh-snapshot-guardian）互补：

🧭 设计原理

原理一：版本管理 = .dsh git 仓库 + 自动 commit

触发时机（任一命中即 commit）：

• 🚀 启动时（恢复现场，记录"上次结束时长什么样"）
• 💥 崩溃检测到时（先记坏状态，再谈回退）
• ⏱️ 定时（默认每 30 分钟，可配置）
• 👆 手动（设置页一键备份）

commit 规范：chore(guard): <触发原因> | <自检摘要>，例如 chore(guard): crash-detected | pre-rollback snapshot of broken state —— 每个 commit 都能回溯"当时发生了什么"。

入库边界（安全第一）：

• ❌ 凭据永不入库：.credentials.yaml、.env、.anonymous-user-id、git-rescue/（token/heartbeat/events）
• ❌ 大文件不入库：node_modules/、profiles/*/node_modules/
• ⚠️ sessions/storages 为 zstd 压缩二进制 → 定期全量基线 + 常规增量排除（默认每天一次基线）
• ✅ .gitignore 规则由插件首次初始化时自动生成并提交

原理二：救援恢复 = 专项工具 → git 回退 → 纯净协助（三层兜底）

崩溃检测 → ① 故障分类（系统/引导/插件/数据）
        → ② 专项恢复工具（⑤，简单修复优先，修复后探活）
        → ③ 不能修复 → git 回退（⑥）
        → ④ 保留坏现场 commit → 坏点标记 → reset 到最后一个好提交
        → ⑤ 重启 DSH → 健康自检
        → ⑥ 仍失败 → 唤起纯净环境（⑦，纯净 dsh 加载 skills 协助）

• 坏点标记：回退过的 commit 打 bad 标记，防止"回退后又回到同一个坏点"的死循环
• 回退动作可逆：回退前有全量副本，误回退也能再恢复

原理三：远端备份 = GitHub + token / SSH key 双方案

• 🔑 认证双方案（任一可用）：
  1. SSH key 优先（~/.ssh/id_*）：本地 git remote + push，走 git 原生 SSH 传输
  2. GitHub token 兜底：REST API 快照推送（git-remote-https 缺失环境仍可用）
• 🔒 token 只存本地，权限 600，绝不写入任何 commit；仅用于 push 认证
• ⚠️ 环境自检：初始化时检测系统 git 是否可用。已知坑：本机 git 缺少 git-remote-https 助手，HTTPS git 操作直接失败 —— 插件检测到该情况时自动降级为 GitHub REST API 直连
• ☁️ 远端仓库名：.dsh@<dsh版本>.<设备ID>（如 .dsh@0.1.0-rc.6.87566bf2a1c8），每台设备一个备份仓；GitHub 不允许 . 开头时自动降级 dsh-at-...
• 🪪 设备身份 = 设备稳定指纹，不是主机名：默认基于 /etc/machine-id（Linux 系统级唯一 ID，兜底为持久化 UUID）；dsh 版本由守护进程读取主实例 @deepseek-ai/dsh 包版本

原理四：崩溃检测与自动回退

检测到崩溃 → 走原理二的三层兜底流程 → 回退后自动拉起 DSH → 自检通过则通知恢复完成。

🔄 工作流程总览

┌─────────────┐   ┌──────────────────────────┐   ┌─────────────────┐
│  DSH 启动    │──▶│ ① 检测运行机器有无 git     │──▶│ ② 检查插件配置   │
└─────────────┘   │    (git --version)        │   │    (token/SSH)  │
                  └──────────────────────────┘   └────────┬────────┘
                                                          ▼
                  ┌─────────────────────────────────────────────┐
                  │ ③ 初始化 .dsh git 仓库 + .gitignore + 首 commit │
                  └─────────────────────────────────────────────┘
                                                          │
                  ┌───────────────┐   每 30min / 事件触发    ▼
                  │ ④ 自动 commit  ◀───────────────────── 版本快照
                  └───────┬───────┘
                          │
                  ┌───────▼───────┐   push (token/SSH)   ┌──────────────────┐
                  │ ⑤ 远端备份     │────────────────────▶│ GitHub 私有库      │
                  └───────┬───────┘   .dsh@<版本>.<设备ID>│ .dsh@...          │
                          │                              └──────────────────┘
                  ┌───────▼───────┐
                  │ ⑥ 崩溃监控     │──崩溃?──▶ ⑦ 故障分类 → ⑧ 专项工具
                  └───────────────┘        → ⑨ git 回退 → ⑩ 拉起自检
                                           → ⑪ 失败? → ⑫ 唤起纯净环境协助

📦 组件规划

组件一：dsh-git-rescue 插件（DSH 进程内，2.0.0 单组件根级结构）

dsh-git-rescue/
├── package.json              # 2.0.0
├── cordis.patch.yml          # 插件注册（bundle patch 自注册）
├── lib/
│   ├── index.js              # 插件入口（API + Agent 工具）
│   ├── git.js / github.js / device.js    # git 管理 + 远端备份 + 设备识别
│   ├── probe.js / flapping.js / process-capture.js / fault-classify.js
│   ├── rescue-env.js         # 救援环境（<版本>@Save-clean / @Save-test）
│   ├── save-lock.js          # 纯净环境防装插件锁定
│   ├── repair-tools.js       # 专项恢复工具（⑤，6 个工具）
│   ├── plugin-health.js      # 插件树健康体检（合并自旧版）
│   ├── session-link.js       # 会话恢复联动（合并自旧版）
│   ├── boot-startup.js       # 开机自启（③）
│   └── self-update.js        # 自动更新 + 大版本换代升级
├── guardian/
│   ├── server.js             # 独立守护进程（②-⑦ 全部）
│   ├── guardian-boot.sh      # 开机自启脚本
│   └── public/               # 控制台网页（含 token/SSH 配置面板）
├── skills/                   # 插件 skill 档案（含联动契约）
├── tools/
│   └── dir-tree.mjs          # 独立目录结构查看工具（零依赖、全平台兼容 Node.js）
├── docs/
│   ├── harness-startup-failure-log.md   # ⭐ 启动失败原因/解决方案（按类型）
│   └── screenshots/architecture.svg     # 体系架构图
└── test-git-rescue.mjs       # 单测

Agent 工具：git_rescue_status / git_rescue_init / git_rescue_backup / git_rescue_log / git_rescue_rollback / git_rescue_push / git_rescue_restart / git_rescue_repair / git_rescue_rescue_env / git_rescue_boot_autostart / git_rescue_link_recovery / git_rescue_restorepoints / git_rescue_restorepoint_build / git_rescue_restorepoint_restore

组件二：guardian 独立进程

• 为什么独立？ 网页崩了恢复按钮就没了 —— 监控与回退必须活在 DSH 之外
• 周期探活 + 崩溃自动救援（专项工具 → git 回退 → 拉起）+ 纯净环境唤起
• OOM 防护：拉起 DSH 时带 NODE_OPTIONS=--max-old-space-size=4096（2026-08-20 教训）
• peak-resume：救援成功后自动恢复高峰暂停的自动续跑（受自动续跑全局闸门约束：闸门 closed 时不恢复，等用户手动对话后放行）
• 自动续跑闸门：DSH 恢复健康时置 autoContinueGate=closed（防批量建空壳），用户手动开启或第一次手动对话后放行（联动 dsh-session-manager，见「联动与源码地址」）
• 插件树体检：git 回退后、拉起前自动修复带病插件（合并自旧版）
• 网页（默认 3082）：状态 / 手动控制 / 🔑 远端认证配置（token/SSH） / git 历史 / 日志

组件三：手动兜底（零依赖）

• 什么都不装也能用：cd ~/.dsh && git log --oneline、git reset --hard <commit>
• 崩溃到连 guardian 都起不来时，命令行 git 就是最后一张网

🔒 安全边界

📚 设计理念

1. 历史即资产：凡是 DSH 可编辑的状态都进 git，丢了的都能找回来
2. 回退是最终手段，也是自动手段：手动可回、守护可回、崩溃自动回
3. token/SSH 双方案、环境自检：环境不对劲时自动降级，不把鸡蛋放一个篮子里
4. 三层网互不依赖：专项工具（简单修复）→ git 还原（⑥）→ 纯净 dsh（⑦），每层独立可救
5. 功能完备性：一项功能不只能靠 skill 或只靠代码——缺哪补哪（skill-code-parity）

🧪 测试结果（2026-08-20，测试实例 3083 实测）

• 插件加载：version=2.0.0、backupRepo=.dsh@0.1.0-rc.6.87566bf2a1c8、心跳正常
• .dsh 仓库 init：git init + .gitignore + 基线 commit
• 破坏测试 5/5：篡改配置 / 删文件 / 连环破坏 / kill -9 / 灭门级（cordis.patch.yml 致崩）
• guardian 自动救援 e2e：破坏致无法启动 → 专项工具/git 回退 → 拉起 → 自检通过
• 坏点标记：回退后再次崩溃不会回到同一 commit（bad-* tag 实测）
• 专项工具：plugin_config/boot_symlink/ro_volume/plugin_load/permission/session_repair 诊断命中
• 救援环境：Save-clean 防装插件锁定（拒绝他插件、救援插件放行）
• 代码级修复：OOM 防护 / chown 权限 / import 冒烟（T10）/ corrupt session（session_repair）/ peak-resume
• 自更新：majorUpgrade 大版本换代判定（结构不同=大版本+1，旧结构不自动更新）

🧪 测试体系：不测"正常"，专测"搞破坏"

救援工具的信任来自反面测试。我们不信"应该没问题"，而是故意把它弄坏，再让它自己爬起来—— 这是本项目的核心测试哲学，也是它敢自称"救援"的底气。

破坏矩阵（5 类真实破坏，全部实测通过 ✅）

灭门级测试的完整时间线（真实日志节选）

10:21:44  健康检查失败（连续 1/3）
10:21:54  健康检查失败（连续 2/3）
10:22:04  健康检查失败（连续 3/3）→ 触发自动救援
10:22:04  坏点标记: bad-c6a588b            ← 坏提交被标记，防再次踩坑
10:22:04  已回退到 bd6824c（from c6a588b） ← git reset --hard 秒级完成
10:22:04  启动 DSH: <自动拉起命令>
10:22:09  ✅ 救援成功：回退后 DSH 恢复正常  ← 5 秒内满血复活

为什么值得"吹"：

• 留证：每次破坏都会留下一个可事后分析的坏提交（pre-rollback snapshot）——不只救回来，还保留完整现场供复盘
• 防死循环：坏点标记（bad-* tag）保证"回退后再次崩溃不会回到同一个坏点"
• 可复现：整套破坏流程跑在一次性测试实例上，任何人想验证都能安全重放，不碰生产数据

独立测试环境：测试随便崩，生产不动摇

┌─ 主实例（生产/会话）────────────────────────┐
│  dsh web  127.0.0.1:3081   DSH_HOME=~/.dsh  │
└──────────────────────────────────────────────┘
┌─ 测试实例（插件热开发，随便崩）───────────────┐
│  DSH_HOME=workspace/dsh-test-home（完全隔离）│
│  └ 反代 0.0.0.0:3084（局域网访问）           │
└──────────────────────────────────────────────┘

🌐 平台能力（2.0.0，代码实证判断）

完整判断见 dsh-git-rescue-平台能力判断-20260820.md。核心救援（git 回退/专项工具/探活）三平台可用； 系统级救援（守护/自启/救援环境/权限修复）Linux 完整、Windows 缺失、macOS 部分——非 Linux 均 try-catch 降级不崩溃。

📖 设计溯源：从 zip 快照方案学到的原理

原独立仓库 dsh-snapshot-archive / dsh-guardian / dsh-snapshot-guardian 已合并入本仓库并从 GitHub 删除。 以下是从中提取、迁移到 git 方案的原理要点——原仓库已不在，这份记录就是永久提醒，后续开发照此执行。

核心思想（三仓库共通）

1. 恢复 = 最朴素的操作：zip 版恢复 = 解压覆盖；git 版 = git reset --hard；网页全崩，命令行也能救
2. 监控不能依赖被监控对象：guardian 独立进程 + 独立端口，DSH 崩了它照样活着
3. 三层安全网互不依赖：插件(网页活) → guardian(进程活) → 手动(文件/命令在)，故障域最小化
4. 敏感隔离：凭据脱敏 / 独立文件 600 权限，绝不进备份
5. 双入口：设置页按钮 + Agent 工具
6. 回退前保留现场：先快照/commit 坏状态，再谈回退
7. 连续失败阈值：连续 N 次失败才触发回退，防单次误判
8. 回退后自证健康：重启 + 健康检查通过才算恢复成功
9. 撤销即恢复：不搞撤销栈，从历史选一个点恢复
10. 零依赖可移植：git 命令 spawn 封装

迁移对照（zip 方案 → git 方案）

增强（git 方案新增，原方案没有）

• bad 标记：回退过的提交打 bad-* tag，防"回退后又回到同一坏点"死循环
• 心跳文件 + 启动自检：区分"进程挂了"与"启动即崩"，崩溃检出更细
• GitHub token/SSH 远端备份 + REST API 降级：绕开 git-remote-https 缺失的环境坑
• sessions 入库策略：zstd 二进制直接入库，靠 .gitignore 排除大文件/凭据控体积

✅ 三合一合并（历史，已完成）

结果：三个原独立仓库（dsh-snapshot-archive / dsh-guardian / dsh-snapshot-guardian）已并入本仓库并从 GitHub 删除。

✅ 2.0.0 重构合并（2026-08-20，当前）

以 2.0.0 重构版为基底，合并旧版救援功能（守护进程为重点）：

📜 版本记录（旧版谱系 1.x，保留自 v1.13.0 README）

X.Y.Z 语义（2026-08-21 更清晰定义）：X=大版本（主功能版本，1 开头，目录结构不兼容=X+1）；Y=提交序号（从 0 开始提交 README，之后每提交一次 +1）；Z=新增子功能数量（全新子功能+子功能修复/更新都计入）。子功能版本线：0 开头=目录结构不兼容，功能缺失导致救援失败 +1；1 开头=结构兼容，新增几种功能 +几。旧版为 components/git-rescue 单组件结构；2.0.0 起为根级单组件结构。

开发期修复的 bug（webServer 注册签名、tools output schema、bad 标记顺序、空仓 seed、ref 更新、软链推送）计入功能实现本身，Z 从发布后修复开始计数。

✅ 2.1.0 合并（2026-08-21，v1.13.0 ⇄ v2.0.0 功能合并）

策略（用户确立）：以 v2.0.0 重构版为代码基底，按重构同款要求把旧版 v1.13.0 独有功能合并回来；README 以旧版为底保留图文/架构图/分版本功能表，再追加重构版内容。

版本号：合并后大版本数据结构未变（仍根级结构）→ 保持 2.x 线，本次合并为 2.1.0。

✅ 2.2.0 还原策略改进（2026-08-21 用户确立：还原只还原 profile）

问题：guardian/手动回退原用 git reset --hard 全量回退整个 .dsh，而 sessions/（131 文件，历史 force-add）与 .credentials.yaml 曾被跟踪 → 崩溃救援会把会话数据一并覆盖还原（「测试环境触发救援全还原」的深层原因之一）。

改进：

语义：完整备份（commit 快照）不变；崩溃回退只把配置/插件恢复到好提交，会话与注册表数据保持现状——救援不再"顺手覆盖"数据。

✅ 2.3.0 官方权限设计对齐（2026-08-21）

背景：系统研究 DeepSeek Harness 官方设计（196 个官方包源码 + 架构/sandbox/credentials/CLI 文档）后，把官方权限约定落实到本插件。

官方关键设计（已核实源码）：

• .credentials.yaml / settings.yaml 写时强制目录 0700（mode 448）+ 文件 0600（mode 384）（dsh-credentials-local / dsh-settings-file）
• 读取凭据前校验权限过宽（GROUP_OTHER_BITS=0o077），过宽抛错拒绝（"run chmod 600"）——官方强制 owner-only
• 原子写（dsh-atomic-write）：随机后缀临时文件 wx 独占创建 + 同目录 rename 原子替换，权限随新 inode 收窄（替换宽权限文件无 chmod 竞态）；写锁 <file>.lock wx 创建 + 指数退避 + 2s 超时
• 官方 .dsh 根目录本身不强制 chmod，约束施加于凭据/设置/原子写等局部（用户确认：.dsh 权限 600/700 是正常设计）

本插件落地：

版本：2.2.0 → 2.3.0。

✅ 2.4.0 OOM 故障识别与自适应防护（2026-08-21，用户实测"内存崩了好几次"）

背景：本机 8.7GB 内存，DSH 主实例 RSS 常驻 ~3GB（33%），可用内存紧张。此前 OOM 崩溃被 classifyFault 误判为 unknown → 走 git 回退（对内存问题毫无作用）→ 拉起 → 又崩 → 死循环（flapping 冷却只能暂缓，不解决根因）。本次把 OOM 从"误当配置故障回退"改为"识别 + 直接拉起 + 内存诊断"。

为什么"不限制内存"不可行：Node 没有无限堆选项（--max-old-space-size 必须给具体 MB，设 0 回落默认）；且本机总内存仅 8.7GB、可用常驻紧张——堆上限设太大反而让 DSH 抢占更多内存，更快触发系统 OOM killer。正确姿势：按物理内存自适应（50%），必要时 DSH_MAX_OLD_SPACE=8192 显式加大，同时留意系统整体内存水位（git_rescue_status 已显示）。

版本：2.3.0 → 2.4.0。

✅ 2.5.0 profile 还原点 zip（2026-08-21，用户要求"unzip 作为 git 救援小功能"）

背景：旧快照恢复插件"备份变化的文件但作者水平不够，恢复没有全自动恢复还改了文件名都不方便手动覆盖恢复"。本版把 unzip 收编为 git 救援小功能，与 git 主通道互补（git 回退 + zip 手动兜底双保险）。

版本：2.4.0 → 2.5.0。

🔗 联动与源码地址

联动：自动续跑全局闸门（dsh-git-rescue ⇄ dsh-session-manager）

崩溃恢复后自动续跑所有会话会批量建空壳会话（真实教训）。2.0.0 起通过全局闸门联动解决：

• 闸门语义：autoContinueGate = open | closed（存于 session-manager 持久化域）
  • closed：一切自动续跑跳过（周期扫描 / 错峰强制续跑 / 面板 scan 的自动续跑部分均不续）
  • open：恢复原有判定（单会话开关 → 全局默认 → 错峰强制）
• guardian 动作：检测到 DSH 恢复健康时，置 autoContinueGate=closed（启动默认关，不自动开启）
• 放行条件（任一满足即自动置 open）：
  1. 用户手动开启（面板 / POST /api/session-manager/auto-continue-gate {gate:"open"}）
  2. 检测到用户第一次手动对话（turn/start 由 user 发起）——有真实对话才放行，杜绝空壳
• API：GET /api/session-manager/auto-continue-gate（查状态）、POST 同路径（置 open/closed）
• 未装 session-manager 时闸门逻辑静默跳过（fail-soft，不影响救援）

源码地址（GitHub，均已实测可达）

仓库地址权威源见 dsh-repo-index；本表地址写入前已按 url-verify-before-write 规则实测验证。

Windows 平台（守护进程可启动，2026-08-20 适配）

核心代码跨平台（Node/HTTP/fetch/fs），Linux 专属调用已加 win32 分支：

启动命令（CMD，勿用 Linux 写法）：

cd <插件目录>\guardian
cmd /c start "" /b node server.js > %USERPROFILE%\.dsh\git-rescue\guardian-boot.log 2>&1

或 PowerShell：Start-Process -FilePath node -ArgumentList "server.js" -WorkingDirectory <guardian目录> -WindowStyle Hidden

开启 SSH（2026-08-20 新增，免手动跑脚本）：

curl -s -X POST http://127.0.0.1:3082/api/ssh/enable

• Windows：自动装 OpenSSH Server → 启 sshd（自动）→ 防火墙放行 22 → 自检端口
• 非 Windows（Linux/macOS）：返回 {noop:true}（系统自带 SSH 服务端，无需开启）
• 之后可从其他机器 ssh <用户>@<Windows-IP> 远程调试

详见 skill windows-process-cmd-start。

License

MIT