DSH 内存守护（dsh-memory-watchdog）

Windows 版 DSH Desktop 的提交内存（commit charge）看门狗。它持续采样系统提交内存，给出谁在吃内存的归因、分页文件只读建议与最近 7 天的崩溃时间线，并在进入预警或危险区间时给出页面内提示；自动重启默认关闭，崩溃后自动续接默认关闭。

• 目标平台：Windows x64
• DSH 版本：>=0.2.0-rc.1 <0.3
• 自动重启：默认关闭（opt-in）
• 崩溃后自动续接：默认关闭（opt-in）
• 采集方式：随插件生命周期运行的轻量 PowerShell 采集进程，只读性能计数
• 不依赖 WMI / CIM，不安装服务、计划任务或原生组件

自动重启默认关闭

插件加载后立即开始监控和预警，但不会自动重启任何进程，直到你在 DSH 的 “设置 → 插件 → DSH Memory Guard”中打开开关。设置页会常驻显示开启后的完整代价说明，不需要展开或确认弹窗。

关闭开关会立即取消尚未开始的待执行重启；内存监控与预警继续运行。

阈值可以调（默认仍是文档值）

设置项	默认	范围	说明
warningPct	80	50–95	进入 warning 的提交内存百分比
criticalPct	90	55–99	进入 critical 的百分比，强制高于 warningPct
criticalAvailMb	2048	256–32768	可用 commit 低于该值时也判 critical
confirmSamples	3	1–10	状态切换所需的连续样本数
cooldownMinutes	30	5–1440	两次重启之间的最小间隔
restartGatePct	20	0–100	重启门限；0 表示关闭该判定

这些字段都是 volatile 设置，改完立即生效，不需要重启 DSH；超出范围的输入会被夹到边界值，criticalPct 永远比 warningPct 高。危险百分比另有绝对兜底：达到 95% 时无论可用量多少都算 critical。

它做什么

• 每 5 秒读取一次 Windows 提交内存已用量、提交上限、物理内存总量与可用量。

• 使用连续样本确认状态（默认 3 个），避免单次尖峰误判；使用迟滞避免在阈值附近反复切换：

  状态	进入条件（默认连续 3 个样本）	退出条件
  normal	从 unknown：有效且 <75%	—
  warning	>=80% 或 可用 commit <=6 GiB	<75% 回 normal
  critical	>=90% 且可用 <=2 GiB，或 >=95%	<85% 回 warning
  unknown	数据缺失、无效或样本超过 15 秒	连续 3 个有效样本且 <75% 回 normal

• 每 30 秒做一次提交内存归因，列出 DSH 进程树占比与占用最高的进程。

• 每 5 分钟读取一次分页文件与提交上限配置，给出只读建议。

• 每 10 分钟汇总一次最近 7 天的崩溃与内存事件时间线（DSH 崩溃日志 + Windows 系统日志）。

• 保留最近 50 条事件历史，可在面板查看并一键导出 JSON；另有“复制诊断信息”按钮。

• 在页面内显示当前状态、动作状态、commit 数值、可用 commit、物理内存、Host RSS、冷却剩余时间、最近错误和最近一次重启记录。

• warning / critical / 恢复 / 采集异常 / 重启结果 / 设置变更通过页面内 toast 提示；右下角常驻一个状态胶囊。

• 插件重启后仍会显示冷却状态；冷却记录保存在本机。

提交内存归因与重启门限

• 归因使用一次 CreateToolhelp32Snapshot 进程枚举 + 每进程 GetProcessMemoryInfo（PrivateUsage）， 分母取系统 commit 已用量；只读，不读取其他进程的内存内容，不使用 WMI/CIM。本机一轮约 1.9 秒（含 PowerShell 启动）。
• 面板给出 DSH 进程树的进程数、合计 commit、占系统提交的比例，以及 Top 5 进程（进程名 + PID + commit）。
• 重启门限：默认只有 DSH 进程树占到提交内存的 20% 以上才允许自动重启。占比不足、归因数据缺失或超过 60 秒过期时一律不重启（fail closed），并在面板与 toast 说明原因；每个 critical episode 只会提示一次，不会刷屏。把 restartGatePct 设为 0 可以关闭该判定。

分页文件建议（只读）

• 读取注册表 Session Manager\Memory Management 的 PagingFiles / ExistingPageFiles、分页文件实际大小，以及 GetPerformanceInfo 的提交上限与物理内存。
• 提示项：没有分页文件、提交上限只比物理内存多不到 2 GiB、分页文件全部落在系统盘（内存 ≥16 GiB 时）、系统自动管理。
• 插件不会修改任何系统设置，也不会代你在 Windows 虚拟内存对话框里点确认；调整分页文件需要你手动操作并重启生效。

崩溃时间线

• 汇总 %APPDATA%\@deepseek-ai\dsh-desktop\logs\crash-*.log（取 --- error --- 段首行）与系统日志中的 2004（虚拟内存耗尽）、26（低虚拟内存提示）、41（意外关机）事件，默认窗口 7 天、最多 20 条。
• 同一次事故产生的多份日志（main + renderer + web-boot）合并成一条，优先级 OOM > host > main > renderer > web-boot。
• 只读本机文件，不上传任何数据。日志正文可能包含本机路径，面板只显示错误首行，导出的诊断文本不含日志正文与会话完整 id。

崩溃后自动续接（默认关闭）

开启 resumeAfterCrash 后，插件会在 DSH 重启后扫描会话，对被中断的对话注入一条“先核对当前状态，再从中断处继续”的提示：

• 只认 turn/end 的 reason.kind === 'interrupted'；你手动停止的 aborted 永不续接。
• 只处理 12 小时内有过人类提示词、当前未在运行、非空白的会话；距中断需静置 20 秒，避开刚打开会话时的写入竞争。
• 每个会话每小时最多 2 次尝试；超过 1 小时没有再续就把计数归零。
• 子代理被打断时，父会话即使自己已经 completed 也会被唤醒一次，并把该子代理标记为已处理，避免僵尸子代理反复唤醒父会话。
• 注入用的 requestId 形如 memory-watchdog-resume-<sessionId>-<turn>[-child]，同一轮同一来源重复扫描不会二次注入。
• 启动后按 20 秒 / 60 秒 / 180 秒 / 600 秒各扫一轮，被静置期推迟的会话按到期时间自动重排；面板也可以手动“立即扫描”。
• 账本保存在 $DSH_HOME/memory-watchdog/resume.json，面板展示会话短 id、轮次、来源与尝试次数。
• 续接的 turn 使用该会话原有的工具与权限运行——这是开启该开关前最需要权衡的一点。

自动重启如何决定

自动重启只有在以下条件同时满足时才会开始：

1. 开关已由用户开启；
2. 压力状态为连续确认的 critical，且交接前样本仍然新鲜；
3. 不在冷却期内（默认 30 分钟），且当前 critical episode 尚未尝试过重启；
4. 重启门限通过（DSH 进程树占比达标，或门限已设为 0）；
5. 活动检测明确确认空闲；
6. 当前平台与 DSH 版本受支持；
7. helper 能力自检已通过；
8. 用户没有取消本次待执行动作。

活动检测会检查运行中的 agent、待处理队列（nextTurn / nextStep）、以及全局和各 agent 作用域下状态为 running / stopping 的 job。活动 API 缺失、报错或返回结构不可解释时，一律按“未确认空闲”处理。

确认空闲需要连续 3 次检查（间隔 1 秒），之后还有 1.5 秒宽限期；宽限期内出现新任务会退回等待。任务忙碌时不会强制重启，等待提醒最多每 5 分钟一次。

整个重启由两阶段交接完成：helper 先校验 Host / Electron 主进程的 executable、创建时间与父子关系，写 verified 后等待 Host 的 go；Host 在真正交接前再次检查全部条件（包括重启门限的复评）。未收到 go（20 秒超时）、Host 提前退出或用户取消时，helper 自行退出，不结束任何进程。

开启前请确认（重要代价）

• 该开关会重启整个 DSH Desktop（Electron 主进程及其全部子进程），不是只刷新界面或重载插件。
• 重启可能丢失未发送的草稿。
• 交接会绕过 Electron 壳的原生退出确认框；profile 与会话数据仍由 Host 的优雅 shutdown 落盘，但界面不会再次询问。
• 若提交内存压力来自其他软件，重启可能无效（重启门限就是为此而设）。
• 冷却期内（默认 30 分钟）最多重启一次；每个持续 critical episode 最多尝试一次。失败同样进入冷却，不会自动重试风暴。
• 重启前会等待旧进程退出（最长 10 秒）与端口释放（最长 10 秒）；旧实例未退出或端口未释放时，本次重启记为失败并不再拉起新实例，避免双实例或静默失败。
• 旧实例退出后最多等待 30 秒让 commit 回落；超时仍会拉起新实例，此时可能很快再次触发。新实例必须在 3 秒启动观察期后、15 秒内重新监听原端口，否则本次重启记为失败（新进程不会被自动结束）。
• 重启过程可能持续数十秒，期间 DSH Desktop 不可用。
• 开启崩溃续接后，插件会以你的名义向会话注入消息并让 agent 继续执行；续接的 turn 拥有该会话原有的工具与权限。

插件不承诺防止 OOM、闪退或数据丢失，也不诊断具体内存泄漏；它不是独立于 DSH 的系统级看门狗。

权限与进程行为

• 采集使用固定系统路径的 Windows PowerShell，隐藏窗口运行；每次调用只使用进程级 -ExecutionPolicy Bypass，不修改机器或用户的持久执行策略。
• 四个 PowerShell 资源都是只读的：collector.ps1（性能计数）、top.ps1（进程 commit 归因）、system-info.ps1（分页文件与提交上限）、crash-history.ps1（崩溃日志 + Get-WinEvent），全部不使用 WMI/CIM/WMIC。
• 能力自检与交接前检查会读取目标进程的可执行文件路径、创建时间和命令行，并验证 Host 与 Electron 主进程的父子关系。
• 重启时只处理已校验身份的 Electron 主进程、Host，以及事先记录的、executable 相同的子进程；必要时先挂起，再在超时后结束。不使用 taskkill /IM ... /T /F，不按内存占用选择或结束无关进程。
• 崩溃续接只调用 DSH 的 sessionController list / inspect / prompt（mode: 'queue'）；不调用任何进程创建 API，也不写会话日志以外的东西。
• 插件只在 $DSH_HOME/memory-watchdog/（默认 ~/.dsh/memory-watchdog/）下读写状态、事件、能力自检、续接账本和交接文件。
• 状态、事件、取消与续接接口通过 DSH 带认证的 ctx.connection.fetch 注册，响应禁止缓存；客户端不能传入 PID、executable、命令行、脚本路径或 helper 参数，也不能改配置。
• 不发起任何网络请求，不上传遥测或诊断数据。

资源开销

• 常驻采集 PowerShell 进程实测工作集约 62–70 MB、commit 约 49 MB；每 5 秒采样一次，单次采集约 7 ms。
• 归因一轮约 1.9 s（每 30 秒一次），分页信息约 1.8 s（每 5 分钟一次），崩溃时间线约 1.6 s（每 10 分钟一次）；三者都是短命进程，用完即退，不常驻。
• helper 只在真正交接时启动，不常驻。

通知边界

DSH 当前没有向插件暴露系统级通知或托盘 API，因此通知只存在于页面内（toast 与常驻胶囊），不承诺系统级通知。如果 renderer 已经崩溃或页面未打开，页面提示不可用；此时依赖 $DSH_HOME/memory-watchdog/ 下的事件、崩溃时间线和最近重启记录，下次加载时展示。

已知边界

• Host 完全卡死或 OOM 时，插件自身无法继续执行，这是不可消除的边界。
• renderer 先于 Host 退出时，页面通知不可用。
• 归因只能读到有权限打开的进程（本机约 320 个进程里 197 个可读），DSH 占比按系统 commit 已用量计算，因此是下界估计。
• 崩溃续接无法区分“中断前那个 turn 已经做完一半”，因此注入文本要求先核对状态；这降低了风险但不是零风险。
• 活动检测能降低误重启概率，但不消除所有并发时序竞争。
• 不同 Windows / DSH 启动方式可能改变 Job 标志；helper 启动后会用 IsProcessInJob 自检，发现自己位于 Job 内时立即失败退出，不结束任何进程。
• 真实环境中的重启、不同启动方式与长期稳定性仍需按发布检查清单单独验证。

安装与卸载

从 DSH Market 安装本插件，或使用 DSH 的插件安装能力安装构建好的 npm tarball。安装后无需另行安装服务或运行构建脚本。

卸载时插件会清理自己的定时器、取消待执行动作并停止采集子进程。$DSH_HOME/memory-watchdog/ 下的历史记录不会自动删除，可在确认不再需要后手动删除。不要在重启交接已经开始时卸载插件：helper 已独立运行，可能仍会完成本次重启。

开发

npm test          # node:test 单元与集成测试
npm run preflight # 包内容与安全规则检查
npm pack          # 生成不要求消费者构建的 tarball

源码为 ESM JavaScript、PowerShell 和浏览器端 client bundle；不包含 TypeScript 编译步骤、原生 addon 或安装脚本。

数据文件

文件	用途
state.json	持久冷却与最近尝试信息
last-event.json	最近一次压力 / 动作事件
events.json	最近 50 条事件历史（面板与导出用）
last-restart.json	最近一次重启结果（启动时展示）
capability.json	最近一次 helper 能力自检
resume.json	崩溃续接账本（尝试次数、已处理子代理、不可读会话）
handoff/<id>/	两阶段交接标记与结果

许可证

MIT，见 LICENSE。