前言¶
在 DeepSeek Harness（DSH）里跑长会话时，Host 既要解析会话日志，又要执行工具调用。单次工具参数过大，或日志里反复写入同一段 PTC 载荷，会让日志体积和堆占用一起抬升，严重时 Host 在打开会话时就 OOM。社区插件 dsh-memory-guard（维护者 zeroed-07，分类 admin-security）面向这类问题：在本地监控堆与会话目录，拦截过大的工具参数，并对已「冷」下来的会话做离线瘦身。下文介绍其定位、能力与安装用法；事实以 GitHub README 为准。
这是什么¶
dsh-memory-guard 是 DSH 的 Host + Client 插件（npm 包名 dsh-memory-guard，当前版本 0.1.2，MIT）。它只做本地防护：采样 Host 堆、统计 $DSH_HOME/sessions 下的日志体积，在运行时拒绝估算超过阈值的工具参数，并对已持久化的大事件发出分级告警；必要时对冷会话日志做 vacuum，保留原文件备份。README 记载的真实案例：一个 7,913 行会话解压后约 954 MB、磁盘约 177 MB，其中 98.5% 为重复的 PTC dispatch 载荷，打开时会话耗尽 Host 堆——插件即针对此类膨胀设计。
核心功能¶
监控与界面¶
- 堆监控：每 3 秒采样
process.memoryUsage()与v8.getHeapStatistics()（used / limit / ratio / RSS）。 - 会话日志统计：每 15 秒扫描
$DSH_HOME/sessions，汇报总字节数、文件数及最大的若干会话。 - Header chip：在会话头注册
MEM 42% · 24.6 MB一类指示；Host 报告 warn / critical 时变黄 / 红。Client 每 5 秒请求同源/memory-guard/stats；悬停可看堆、RSS、会话合计、最大会话、近期告警与大载荷。DSH 升级后若 chip 未出现，Host 侧仍可通过/memguard与memguard工具使用。
运行时防护¶
- 同步拒绝：工具调用参数估算超过
maxToolArgBytes（默认 2 MiB）时直接拒绝，并提示模型分块写入或用脚本生成文件。 - 已写入载荷告警：对已追加的
tool/call、tool/ptc-dispatch*等行，8 MiB 警告、32 MiB 升级；单会话日志 50 MiB 警告、200 MiB 严重。 - 配置项
guardEnabled：设为false可关闭拒绝，保留监控。
离线 vacuum¶
- 命令
/memguard vacuum为 dry-run，列出可瘦身冷会话及可节省字节；/memguard vacuum <session-id> confirm重写该冷日志：超大参数字符串在 PTC start/final 对中用相同占位符替换，校验通过后原文件保留为.orig-<timestamp>。 memguard工具提供status、vacuum-scan、vacuum-apply（后者需confirm: true，且拒绝 live 会话）。- 独立 CLI（不装 DSH 也可对磁盘上的备份跑）：
npx dsh-memory-guard-vacuum ./session.v4.jsonl.zstd scan
npx dsh-memory-guard-vacuum ./session.v4.jsonl.zstd write --out=./session.slim.jsonl.zstd
vacuum 保守处理 DSH 的「首帧仅含 header 行」与 PTC 成对 arguments 必须 deep-equal 的格式约束；详见 README「Why the vacuum is conservative」。
本地 HTTP¶
同源前缀 /memory-guard：GET /stats、POST /limit（临时改 maxToolArgBytes，重启失效）、POST /vacuum（冷会话 dry-run）。除 Origin 检查外无额外鉴权；README 明确要求勿将 DSH web 端口暴露给不可信网络。
环境与安装¶
| 项 | 要求 |
|---|---|
| DSH | 在 0.2.1-rc.2 上测试（desktop 与 web profile） |
| Node.js | >= 22.15（使用内置 zstd API；DSH 自带合适运行时） |
| 平台 | 在 Windows 开发与验证；代码路径无关，Linux/macOS 未测试 |
安装 Host 半部分后需重启应用；Client chip 需刷新页面。
# desktop profile（DeepSeek Harness 桌面应用）
dsh plugin --profile desktop add dsh-memory-guard
# web / headless profile
dsh plugin --profile web add dsh-memory-guard
也可在 DSH UI：Settings → Plugins → Install，输入 dsh-memory-guard。
升级示例：
dsh plugin --profile desktop remove dsh-memory-guard
dsh plugin --profile desktop add dsh-memory-guard
卸载：
dsh plugin --profile desktop remove dsh-memory-guard
典型用法¶
1、安装并重启后，观察会话头 chip 或执行 /memguard，查看堆、会话 Top 5、告警、阈值。
2、日志已膨胀且会话已冷，先做 dry-run：
/memguard vacuum
确认后再：
/memguard vacuum <session-id> confirm
3、调参时编辑已安装插件的 cordis.patch.yml 中 config 块（或 profile composition 里对应 bundle 行），重启 DSH。常用键示例：
| Key | 默认 | 含义 |
|---|---|---|
maxToolArgBytes |
2097152 (2 MiB) |
超过则拒绝工具调用 |
guardExemptTools |
[] |
豁免工具名，如 ["write"] |
heapWarnRatio / heapCriticalRatio |
0.75 / 0.90 |
堆黄 / 红 |
sessionLogWarnBytes / sessionLogCriticalBytes |
50 MiB / 200 MiB | 单会话日志黄 / 红 |
vacuumMinBytes |
10485760 (10 MiB) |
小于此体积不参与 vacuum 候选 |
运行时临时改上限（重启恢复默认）：
# POST /memory-guard/limit，body: {"maxToolArgBytes": <int>}
适用场景与注意¶
适合：长期在 DSH 里跑 Agent、频繁 run_code / 大工具参数、会话列表里出现百 MB 级日志，或 Host 堆占用持续偏高的开发者。
权限与信任：插件以当前 DSH Host 进程权限运行，会读本地会话路径与体积，vacuum 会改写所选冷日志（原文件备份为 .orig-*）。安装前应阅读 源码与 LICENSE；社区目录 skillhub.cn 为独立站点，与 DeepSeek / 幻方无官方从属关系。
已知限制（README 原文要点）：
run_code的tool/ptc-dispatch-start在 guard 之前写入，首次超大参数仍可能进日志；guard 阻止执行与第二条结果行，告警与 vacuum 覆盖其余。- 仅冷会话可 vacuum；live 日志不重写。
- 仅可见 Host 堆，不能替 launcher 提高 Node/Electron 堆上限。
- 无网络请求、无遥测；Privacy 节说明仅本地读盘与同源 UI 调用。
结尾¶
dsh-memory-guard 把「堆 + 会话日志 + 超大工具参数」收在一套本地 guard 里：先监控与拦截，再对冷日志 dry-run vacuum，避免 Host 被单会话拖垮。目录页：https://www.skillhub.cn/plugins/zeroed-07/dsh-memory-guard；仓库：https://github.com/zeroed-07/dsh-memory-guard。
