前言¶

在 DeepSeek Harness (DSH) 的開發或智能體編排場景中，模型往往無法直觀感知當前會話的 token 消耗、上下文窗口剩餘量或預算進度。這容易導致在上下文撐滿或預算耗盡後才被動止損。dsh-plugin-quota 解決了這個問題，它通過實時儀表和預測算法，讓模型在每一回合都能“看見”自身的資源消耗，並支持自我剎車。

插件簡介¶

這是一個客戶端插件，旨在爲每個回合提供實時的 token/花費儀表，並給出下一步預估與預算/上下文窗口的消耗預測。模型自身可見這些信息，從而自主控制輸出節奏。該插件由 121212165 維護，採用 MIT 許可證。

核心功能¶

• 實時追蹤：監聽 session/event（assistant/message usage），每次模型回覆後實時累計本會話的輸入/輸出/緩存命中 token。如果配置了價格表，同時估算花費（微單位累計）。
• 注入系統提示：每回合給模型一行實時儀表（例如 實時用量：13.8k tok / 50k ▰▰▰▱… · 5 步 · ≈0.0153 USD），預算超限時模型能直接看見。
• /qm 面板：輸入 /qm 查看本會話 + 今日全部會話合計，含預算進度條（需配置 budgetTokens）和超預算警告。
• 下步預估：基於歷史數據給出下一回合的 token 和花費區間，以及撐滿上下文或燒完預算所需的步數。
• quota_meter 工具：模型可調用此工具自查，結果渲染爲 generic 卡片。
• 跨插件契約：通過 ~/.dsh/quota/summary.json 向家族其他插件（如 task-forge）發佈預算和上下文狀態，無需關心會話 ID 結構。

安裝與啓用¶

通過命令行安裝插件。安裝後需重啓 dsh，默認配置即可工作（儀表注入 + /qm 面板）。

dsh plugin --profile <你的profile> add github:121212165/dsh-plugin-quota

重啓 dsh 後，在對話中輸入 /qm 即可查看面板。如果需要預算進度條或估算花費，需配置 budgetTokens 和 prices。

配置說明¶

• 零配置即用：不配置價格和預算時，僅顯示 token 數量和步數。
• 價格配置：需配置 prices 才能估算花費。
• 預算配置：需配置 budgetTokens 才能顯示進度條。
• 上下文窗口：contextWindow 必須是正有限數，否則啓動即報錯。

示例配置（放入 profile 的 cordis.patch.yml）：

budgetTokens: 0      # 單會話 token 預算，0 = 不顯示進度條
inject: true         # 實時儀表注入系統提示
prices:              # 按模型 id 子串匹配，命中才估花費
  - match: space-bunny
    currency: USD
    perMillion: { input: 1, output: 2, cacheRead: 0.1 }
    contextWindow: 128000   # 撐滿預測的根據；缺省則該模型只報下步預估，不算撐滿點

數據落盤與契約¶

插件在 ~/.dsh/quota/（或 dataPath 所在目錄）下維護三個文件，全原子寫：
- totals.json：本插件的內部賬，格式爲 { <sessionId>: UsageTotals }。
- history.json：每會話最近 64 步的 StepUsage[]，用於預測。
- summary.json：家族契約文件，包含 budgetTokens、contextWindow、stepsUntilFull、stepsUntilBudget 等字段。其他插件讀取此文件即可獲知會話狀態。

測試與維護¶

該插件包含 34 個測試，覆蓋純函數（折算、定價、格式化、預測模型、契約字段）和裝配層測試（真實 apply() 掛 mock ctx，真實 usage 事件驅動）。代碼庫遵循 MIT 許可證。

適用場景¶

適合需要精細化控制成本和上下文窗口的 DSH 用戶或開發者。插件以當前 dsh 進程權限運行，安裝前建議檢查源碼與許可證。

結尾¶

通過引入 dsh-plugin-quota，開發者可以在智能體開發中實現“模型自我監控”，避免資源浪費。更多詳情與源碼，請參考 GitHub 倉庫。