nicecx/dsh-reset-handoff

dsh-reset-handoff

DSH 从不自己重启自己。 一个宿主插件，把「重置」请求经带版本号的 JSON 协议交给外部运维 agent——预检快照 → 重启 → 健康检查 → 恢复业务——重启后再把结果投递回发起会话。

为什么需要它

一个长期运行的 DeepSeek Harness（DSH）实例有很多需要重启的理由：重载插件/配置、应用设置、从卡死状态恢复。但 DSH 内部的 agent 不应该自己重启 DSH：

- 重启会杀死发出重启的那个进程，agent 根本没机会看到结果；
- agent 看不到当前有哪些业务在跑（其他活跃会话、relay 通道、待跑任务）；
- 如果重启失败，没有谁留下来诊断和恢复。

安全的做法是 handoff（托管）：DSH 写一个请求，一个独立的外部运维 agent（这里是 Hermes Agent）读取它，带着预检/健康检查/恢复执行重启，再写一个结果，DSH 重启后读回来。

工作原理

[DSH]  agent 调用 reset_handoff(reason)
│  写 request.json（JSON 协议）
│  （可选）触发外部执行方
▼
[外部] 运维 agent 读 request.json
│  1. preflight — 快照活跃会话、relay 状态、待跑任务
│  2. GATE     — 重启前成熟度门禁（见下）
│  3. restart  — 重启 dsh web 服务（macOS launchd）
│  4. health   — 轮询 http://127.0.0.1:3080 直到 200（带超时）
│  5. recover  — 校验 relay/auth-proxy 自愈，列出被打断会话
│  6. result   — 写 result.json（status done/failed + 各阶段明细）
▼
[DSH]  重启后插件读 result.json，把可读摘要投递回发起会话（followup），
让当初请求的 agent 能继续它被打断的工作。

重启前成熟度门禁

参考执行器在条件不成熟时拒绝重启，检查：

1. 无待审批/待回答诉求 —— relay pending.json 的 pending 列表为空（否则重启会丢审批栈）。
2. 磁盘空间充足 —— 至少 MIN_FREE_DISK_MB（默认 500MB）。
3. 冷却期 —— 距上次重启至少 RESTART_COOLDOWN_SEC（默认 60s），防崩溃循环。

任一条件不满足，执行器写 result.json：status: "failed"、restart: { ok: false, gated: true }、以及一个列出每个未通过条件的 gate 数组——并且不重启。请求方（或用户）看到确切原因后，自行决定何时安全再试。

工具

| 工具 | 用途 |
| --- | --- |
| reset_handoff(reason, scope?) | 提交一次重置请求给外部运维 agent，绝不在进程内重启 DSH |
| reset_status() | 查询最近一次请求及其结果（只读） |

两个工具都注册为宿主级，所有会话的 agent 都能在需要重置时调用。

协议（v1）

插件与执行方完全解耦——只共享 ~/.dsh/reset-handoff/ 下的两个 JSON 文件（可用 DSH_RESET_HANDOFF_DIR 覆盖）：

request.json（DSH 写）：

{
"schema": "dsh-reset-handoff/request",
"version": 1,
"id": "",
"requestedAt": "2026-08-30T12:00:00+08:00",
"reason": "重新加载插件配置",
"sessionId": "",
"requester": "dsh-reset-handoff",
"scope": { "restartDshWeb": true, "healthCheck": true, "recoverInterrupted": true }
}

result.json（执行方写）：

{
"schema": "dsh-reset-handoff/result",
"version": 1,
"requestId": "",
"status": "done",
"startedAt": "...",
"finishedAt": "...",
"preflight": { "liveSessions": ["..."], "relay": { }, "hermesJobs": ["..."] },
"restart": { "ok": true },
"health": { "ok": true, "checks": [ { "name": "dsh-web http :3080", "ok": true, "detail": "200" } ] },
"recovery": { "resumed": ["..."], "report": "..." },
"recoveryAction": {
"ok": true,
"attempts": [ { "attempt": 1, "restart": { "ok": true }, "time": "..." } ],
"diag": { "keyErrors": [], "logTail": "..." }
},
"gate": [ { "name": "relay 无待审批/待回答诉求", "ok": true } ]
}

执行方恢复契约（让"recover DSH 本身"真正成立的部分）：重启后健康检查不通过时，执行方必须尝试恢复，而不是只报失败：

1. 诊断 —— 读 dsh web 错误日志尾部，提取关键错误（loader 失败、缺依赖如 undici、EADDRINUSE 多实例、OOM）。
2. 重试 —— 最多 MAX_RESTART_ATTEMPTS（默认 3）轮重启，轮间冷却。
3. 观察 —— 每轮重启后留初始化观察期（默认 120s）再判成败。
4. 报告 —— 结果写进 recoveryAction（attempts + diag），让请求方 agent 和人都能看到为什么失败、重试了几轮。

任何读写这两个文件的执行方都能驱动重置——Hermes、自研脚本、云函数。协议就是契约。

安装

dsh plugin --profile  add github:/dsh-reset-handoff

可选执行方触发：配置 triggerCommand，让 reset_handoff 同时唤起外部 agent（默认无——执行方可改为轮询 request.json）。配置结构见 cordis.patch.yml。

执行方（Hermes 示例）

hermes/reset_agent.py 提供了一个参考执行器（纯 Python，零依赖）。它应放在 Hermes 的 profile（reset-agent）里，由 hermes cron run  触发：

python3 reset_agent.py            # 执行五步流程
python3 reset_agent.py --dry-run  # 只打印流程，不真正重启

要求

- 带 web profile 的 DeepSeek Harness（宿主插件）。
- 外部执行方能重启 dsh web 服务（macOS launchctl kickstart -k com.dsh.web，或对应操作系统/init 的等价命令）。

License

MIT