前言¶
DeepSeek Harness（DSH）采用“一切皆插件”的理念。在长时间运行的智能体会话中，上下文窗口占用、压缩次数和缓存命中率会随着对话轮次增加而变化，容易导致 Token 浪费或性能下降。dsh-session-health 插件通过右下角的悬浮按钮，实时监控会话健康度，帮助开发者判断是否需要重开会话或生成 handoff 文件。
安装与启用¶
本插件是一个 DSH bundle（包含 dsh.bundle.patch 和 dsh.client）。安装后需重启 web profile 进程才能生效。
- 执行以下命令安装插件：
dsh plugin --profile web add github:CJL-1995/dsh-session-health
- 重启
dsh web进程，右下角会出现“会话健康度提醒”按钮。
功能概览¶
安装完成后，右下角会出现一个可拖动的悬浮按钮。长按（约 260ms）可拖动定位，快速点击则在按钮上方弹出健康度报告面板。
报告面板包含以下核心数据：
- 健康度评分：0–100% 的评分，分为绿、黄绿、橙、红四档。
- 上下文窗口使用情况：红/绿进度条显示占用率，附带百分比和窗口大小。
- 压缩分析：显示压缩次数，并附带“距上次压缩折线图”（横轴为压缩序号，纵轴为轮次）。
- 调用趋势：每轮工具调用总次数 / 累计平均工具调用；每轮步骤总次数 / 累计平均步骤。
- Token 消耗统计：未缓存输入、缓存读、输出、推理及总计（整会话累计）。
- 耗时分析：LLM 生成时间、工具执行时间、活跃总耗时。
- 步骤明细：倒序排列的步骤列表，显示每步耗时及调用的工具。
- 大户排名：按 tool 排名，列出 Token 消耗和耗时大户。
- 亚健康一键生成 handoff：当健康度低于 60% 时，面板会额外出现“生成 handoff 并重开会话”按钮。
健康度评分逻辑¶
健康度评分基于三因子加权计算，公式如下：
健康度 = 100 − 上下文占用扣分(40%) − 压缩次数扣分(30%) − 缓存命中率扣分(30%)
- 上下文占用：占用率 > 30% 后线性扣分，100% 时扣满 40 分。
- 压缩次数：0–5 次线性扣分，≥5 次时扣满 30 分。
- 缓存命中率：< 50% 时直接扣满 30 分，50%–100% 线性扣分，100% 不扣。
评分分级标准：
* ≥ 80：健康
* 60 – 79：尚可
* 40 – 59：亚健康
* < 40：不健康
典型用法¶
- 查看报告：点击右下角按钮，查看当前会话的各项指标。
- 处理亚健康会话：若健康度 < 60%，点击面板上的“生成 handoff 并重开会话”按钮。
- 自动处理：插件会将总结 prompt 发入当前会话，由 Agent 生成
HANDOFF.md文件并返回落盘路径，随后重开会话。
技术细节¶
- 架构：Host 端（
index.js）通过sessionProjections注册sessionHealthprojection，将会话事件增量折叠成纯 JSON 状态；Client 端（client.js）通过window.__ModuleLoader__加载并注册到shell.overlay，响应式读取报告。 - Bundle 类型：
dsh.bundle.patch+dsh.client。
适用场景与注意¶
本插件适合需要精细控制会话成本和状态的开发者。使用时请注意，插件以当前 dsh web 进程的权限运行，安装前建议检查源码与许可证（MIT）。
