前言¶

在 DeepSeek Harness（DSH）的 composer 底部，上下文用量環（context-usage ring）與會話統計膠囊同處一行，用來反映當前會話的 contextPressure 投影。當模型調用因限流、超時或傳輸錯誤失敗，並由 @deepseek-ai/dsh-llm-retry 自動重試時，宿主仍可能收到一個「全零」的 usage chunk；投影把它當作最新樣本，環會短暫顯示 0%，儘管上下文並未清空。與此同時，隨包樣式表裏 meter trigger 與 StatsPills 的字號差 1px，環上的百分比比同行數字略大，視覺上像另一套字體。下面介紹社區插件 dsh-context-usage-guard（維護者 icrefin），如何在宿主與瀏覽器兩側各做一處最小修補，且不新增頁面或持久化配置以外的負擔。

這是什麼¶

dsh-context-usage-guard 是面向 DSH 0.2.0-rc.2 的客戶端類 Cordis 插件（npm 包名 dsh-context-usage-guard，當前發佈版本 v0.2.0，MIT 許可證）。它修復 composer 上下文用量環的兩處問題：重試風暴期間環不再被空 usage 樣本壓成 0%；環上百分比與 footer 裏其他數字同字號。插件不替換 meter 組件、不改投影註冊表，也不編造用量數字。

兩個症狀與修復思路¶

重試期間環塌到 0%¶

環渲染會話投影 contextPressure，其中：

pressureTokens  = usage.inputTokens + cacheReadTokens + cacheWriteTokens
projectedTokens = max(0, pressureTokens + surfaceTokens - sampledSurfaceTokens)

失敗嘗試在 provider 未報告有效計量時，仍可能以如下流結束（示例爲 RATE_LIMIT）：

[ { "type": "chunk", "chunk": { "type": "usage",  "usage": { "inputTokens": 0, "outputTokens": 0, "totalTokens": 0 } } },
  { "type": "chunk", "chunk": { "type": "finish", "reason": { "kind": "error",
      "failure": { "code": "RATE_LIMIT", "message": "429: token_capacity_exceeded" } } } } ]

該樣本計數全爲零，卻被當作「最新樣本」，未加防護時 pressureTokens 與 projectedTokens 都會變成 0，環顯示 0%。README 中針對真實會話回放（test/fold.spec.ts）的對照：最後一次成功調用後環爲 6%；失敗嘗試未攔截時爲 0%，攔截後仍爲 6%。

百分比比同行數字大 1px¶

@deepseek-ai/dsh-client-ui-chat 的 StatsPills 與 @deepseek-ai/dsh-client-ui-conversation 的 ContextMeter trigger 對 secondary 字號的處理差 1px（前者 calc(... - 1px)，後者直接用變量）。環上的 30% 因此比 182 steps、Cache hit 94% 等略大約 8%（約 13px 對 12px cap height）。

核心功能¶

插件分兩半，均不增加路由、設置頁或落盤文件（配置僅通過 Cordis patch 中的 config 字段）：

宿主側聲明 inject: ['llm']，在 ctx.effect 中註冊 listener，卸載或關閉配置行時由 cordis 清理。規則要點：

• 成功完成（stop、tool-calls、max-tokens 等）報告的 usage 原樣通過，即使爲零；
• 失敗但已有非零計數的 partial 調用不丟棄；
• 流順序與終止 finish chunk 保持不變，僅可能 withheld 那一個 usage chunk。

瀏覽器側使用結構選擇器（不依賴 content-hashed 類名）：

button[aria-haspopup="dialog"]:has(> svg > circle) {
  font-size: calc(var(--dsh-content-font-size-secondary,13px) - 1px);
}

上游若統一字號，倉庫中的 test/meter-typography.spec.ts 會失敗，屆時應移除該 workaround。

環境要求¶

構建產物已提交在 lib/，安裝插件本身不需要在目標機器上執行 pnpm build。

安裝與啓用¶

官方 README 給出的安裝步驟如下。先克隆倉庫並執行安裝腳本，腳本會生成 tarball 並打印路徑：

git clone https://github.com/icrefin/dsh-context-usage-guard.git
cd dsh-context-usage-guard
sh scripts/install.sh

scripts/install.sh 會打出 dist/dsh-context-usage-guard-0.2.0.tgz。桌面 profile 歸 Electron 應用所有，不能對該 profile 使用 dsh plugin add；應在 Settings → Plugins 中安裝該 tarball（或使用插件管理器工具），然後重啓 harness。裝進正在運行的 profile 的 bundle 時，當前進程無法 import；瀏覽器側還需刷新頁面。

運維上需注意：同一版本號重裝時 pnpm 可能複用已解壓包，若需強制更新 tarball，應先移除 bundle 再安裝或 bump 版本。宿主側 listener 在進程啓動時加載，後續僅改客戶端 bundle 可熱更新瀏覽器半側，但宿主半側改動需重啓後生效。

卸載：從 Settings → Plugins 移除 bundle 並重啓；插件不寫額外持久狀態。

配置¶

在 profile 的 cordis.patch.yml 對應插件行的 config 中寫入：

- id: dsh-context-usage-guard
  config:
    enabled: true
    logHeldSamples: false

兩項均爲 volatile，下一請求即生效，無需重載 profile。

典型用法與驗證¶

日常使用中無需額外操作：enabled: true 時，限流重試等場景下環應維持失敗前的百分比，而非長時間顯示 0%。若需確認宿主側是否攔截，可將 logHeldSamples 設爲 true，日誌示例形態爲：

[dsh-context-usage-guard] held an empty usage sample from a failed request
  (example-provider/example-model-v1, RATE_LIMIT); the context reading stays at its last value

開發者在倉庫內自檢可執行（需 pnpm，僅用於開發本插件）：

pnpm install
pnpm check

pnpm check 會對宿主與客戶端兩半做 TypeScript 檢查，並運行 5 個套件共 40 個測試。

適用場景與注意¶

適合在 DSH composer 中依賴上下文用量環判斷「是否接近窗口上限」的開發者：尤其在頻繁觸發 retry（429、超時等）的長會話裏，避免誤讀 0% 而做出不必要的壓縮或新開對話。

務必知曉：

• 插件以當前 DSH 進程權限運行，安裝前請閱讀 GitHub 源碼 與 MIT 許可證，自行評估信任邊界。
• 宿主側只覆蓋經 LLM 服務 llm/stream 的調用；繞過該服務直連 provider 的路徑不受此插件影響。
• 瀏覽器側字號修復是隨上游聲明差異而存在的 workaround；上游合併後應刪除注入規則。
• 若環仍爲 0%，先查 enabled；成功完成且 provider 報告全零的 usage 不會被攔截——那是隨包語義，而非 guard 失效。

插件不會凍結讀數：下一次成功調用上報真實 usage 後，環會正常推進；不會在沒有可測量數據時顯示虛構百分比（無數據時環保持隱藏，與隨包行爲一致）。

結尾¶

dsh-context-usage-guard 用一條流過濾規則與一條 CSS 聲明，分別穩住重試期間的 context 讀數，並對齊 footer 排版。DSH 生態強調「一切皆插件」；社區目錄 SkillHub 插件頁 與 GitHub 倉庫由社區維護，與 DeepSeek / 幻方無官方從屬關係。源碼、Issue 與發佈說明見：https://github.com/icrefin/dsh-context-usage-guard。