前言¶
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）。
