前言¶
在 DSH 裏跑 Agent 時，上下文窗口會隨多輪對話、工具往返和緩存策略不斷變化。開發者能看日誌，但模型側通常拿不到「當前已用多少 token、還剩多少、緩存命中率如何」這類讀數，長任務裏很難在合適時機收窄上下文或觸發壓縮。社區插件 dsh-context-usage-for-agent（維護者 dixieWithHeart）在宿主會話投影之上，把佔用指標暴露給 Agent，並在每輪對話開頭可選注入一行摘要；同時在設置裏提供開關與模板預覽。本文按安裝、能力、數據來源與配置說明用法，事實以 GitHub README 爲準。
這是什麼¶
dsh-context-usage-for-agent（README 亦稱「上下文自知」）歸類爲模型推理相關 DSH 插件，當前 package 版本爲 0.6.0，許可證 MIT，要求 Node >= 20。它解決的是：Agent 與界面側能一致地看到同一會話的上下文佔用，而不是憑猜測控制 prompt 長度。
DSH 生態奉行「一切皆插件」；目錄站點 SkillHub 插件頁 與 GitHub 倉庫由社區維護，與 DeepSeek / 幻方無官方從屬關係。
核心功能¶
插件在三處呈現上下文佔用，三者相互獨立又可組合使用。
context_usage 工具¶
Agent 可調用 context_usage 工具，查詢：
- 佔用百分比
- 已用 token、上下文窗口大小、剩餘 token
- 緩存命中率
若在配置中設置了已知自動壓縮閾值（compactAtRatio），工具還可回報距壓縮還剩幾個百分點。
每輪一行讀數¶
在本回合首次工具調用之前，宿主可向對話注入一行格式化讀數。默認形態類似：
[ctx 17.7%] 177k/1.00M · 緩存 99.4% · 餘 823k
可通過總開關或模板控制是否注入、文案長什麼樣（見下文配置）。
設置頁¶
路徑：設置 → 上下文自知。提供注入開關、自定義模板與實時預覽。設置頁文案隨 DSH 界面語言（設置 → 常規 → 語言）在中英文間切換，無需重啓；插件清單名稱與描述由 locale/zh.json、locale/en.json 提供。
佔位符列表中的細字說明目前由宿主提供，且僅有中文；若宿主缺少 locale 服務（精簡組合），界面會退回中文並在控制台輸出一條 warn。
數據來源與狀態¶
佔用數字並非插件自行估算，而是對齊宿主事件與投影：
| 項 | 來源 |
|---|---|
pressureTokens |
assistant/message 的 usage：未緩存輸入 + 緩存讀 + 緩存寫（不含輸出） |
contextWindow |
request/context 的真實值；未到達前用配置兜底 |
| 回合號 | turn/start |
狀態走會話投影（ctx.sessionProjections，key 爲 contextUsage），不訂閱 session/event。冷讀或進程重啓後，摺疊日誌即可得到當前值。
安裝與啓用¶
在已安裝 DSH CLI 的環境中執行官方文檔給出的命令：
dsh plugin add dsh-context-usage-for-agent
安裝完成後刷新頁面。context_usage 工具立即可用；每輪讀數默認開啓（injectPerTurn 默認爲 true）。
插件以後臺進程權限隨當前 DSH 運行。安裝前建議閱讀 源碼倉庫 與 LICENSE，確認符合你的環境與合規要求。
配置¶
兩層配置並存：
cordis.patch.yml中的config爲啓動默認值- 設置頁寫入
~/.dsh/dsh-context-usage.json，優先級更高
| 項 | 默認 | 說明 |
|---|---|---|
enabled |
true |
總開關。關閉後只停止每輪讀數，工具仍可用 |
injectPerTurn |
true |
是否在每輪注入一行 |
template |
[ctx {percent}%] {used}/{window} · 緩存 {cache}% · 餘 {remaining} |
注入文案；留空即不注入 |
contextWindow |
1000000 |
僅兜底；provider 上報後以真實值爲準 |
compactAtRatio |
null |
已知自動壓縮閾值（0–1）時，工具可回報距壓縮的百分點 |
模板佔位符¶
| 佔位符 | 含義 |
|---|---|
{percent} |
佔用百分比，如 17.7 |
{used} / {usedRaw} |
已用 token（帶單位 / 原始數字） |
{window} / {windowRaw} |
窗口大小（帶單位 / 原始數字） |
{remaining} / {remainingRaw} |
剩餘 token（帶單位 / 原始數字） |
{cache} |
緩存命中率 |
{turn} |
回合號 |
{compact} |
距壓縮百分點（需配置 compactAtRatio） |
未知佔位符會原樣保留，便於發現拼寫錯誤；已知佔位符但取不到值時顯示 ?。
設置頁通過下列 HTTP 路由讀寫狀態（供 UI 使用，無鑑權）：
| 方法 | 路徑 | 用途 |
|---|---|---|
| GET/HEAD | /api/dsh-context-usage/state |
設置與實時佔用 |
| POST | /api/dsh-context-usage/set |
部分更新設置 |
典型用法¶
- 安裝插件並刷新 DSH Web 界面。
- 在 Agent 流程中需要判斷「是否接近窗口上限」時，調用
context_usage獲取當前百分比與剩餘 token。 - 若希望模型在每輪開場即看到佔用，保持
enabled與injectPerTurn爲true，或到 設置 → 上下文自知 調整模板並查看實時預覽。 - 若你已知宿主會在某一佔用比例觸發自動壓縮，將
compactAtRatio設爲對應小數，工具與模板中的{compact}纔有意義。
倉庫內可用下列命令做契約與語法檢查（維護者文檔）：
node tools/test-context-usage.mjs # 61 條契約斷言
node --check index.js client.js
瀏覽器端設置頁渲染需刷新頁面目視確認，腳本無法自動斷言。
適用場景與注意¶
適合誰： 在 DSH 上開發或調試長鏈路 Agent、需要根據 token 與緩存命中率做 prompt 收窄、壓縮或自我說明的場景；也適合希望在 UI 與模型側看到一致讀數的團隊。
注意：
- 關閉
enabled不會禁用context_usage工具，只會停止每輪注入。 contextWindow配置項僅在 provider 尚未上報真實窗口前起兜底作用。- HTTP 狀態接口無鑑權，部署在共享或公網環境時需結合整體 DSH 訪問控制評估風險。
結尾¶
dsh-context-usage-for-agent 把會話投影裏的上下文佔用同時交給工具和可選的每輪讀數，並在設置頁提供模板化展示，減少 Agent 對窗口狀態的盲區。進一步瞭解與安裝：
