前言¶
在 DeepSeek Harness（DSH）裏跑 Agent 任務時，模型調用會隨輪次累積：Token 與人民幣費用往往要到賬單出來纔看得清。若任務步數多、子代理嵌套或反覆重試，單次會話的成本可能超出預期。社區裏常見做法是事後對賬或憑經驗掐斷，缺少與會話同生命週期的實時覈算與硬閾值。
下面介紹維護者 Existence001100 發佈的 dsh-budget-guard-plugin（GitHub：Existence001100/dsh-budget-guard-plugin，SkillHub 分類 admin-security）。它在 DSH 官方擴展點（如 agent/pre-step、agent/turn-stopping）上掛接計費與攔截邏輯，不改動模型核心；支持按 CNY 金額 或 Token 數量 設上限，接近閾值預警，達到比例後自動中止或手動放行，並在每輪結束後基於歷史燃燒率做降級預估（不額外調用 LLM）。
這是什麼¶
dsh-budget-guard-plugin 是面向 Web Profile 的 DSH 插件（npm 包名 dsh-budget-guard-plugin，當前資料中版本 0.4.5，許可證 MIT）。定位是：給每一次任務加一條可審計的預算線——從會話日誌裏的 assistant/message.usage 累計 input/output/cache Token，按消息實際發生時刻的北京高峯/空閒價計費，金額與 Token 兩條線獨立，任一先到即觸發；值爲 0 的維度表示「不設這條線」，不參與攔截。
插件以當前 DSH 進程權限運行；安裝前建議自行查看 GitHub 倉庫 源碼與許可證。社區目錄頁：SkillHub 插件頁（獨立站點，與 DeepSeek / 幻方無官方從屬關係）。
核心功能¶
預算聲明與實時覈算¶
- 全局默認：在 profile 的
cordis.patch.yml或 設置 → 預算護欄 中配置budgetAmount、tokenBudget等。 - 當前會話：對話內
/budget命令，或輸入框下方預算條展開後「設置本次預算…」；寫入command/run日誌，重啓後可重放。
計費引擎匹配內置價格表，支持高峯/空閒計價；未知模型可按配置告警。父任務與子代理消耗可聚合（詳見 README「父任務 / 子代理聚合」）。
攔截與預警¶
| 行爲 | 說明 |
|---|---|
| 預警 | 達到 warnRatio（默認 0.8）時在預算條與每輪卡片提示 |
自動攔截（interceptMode: auto） |
達到 interceptRatio（默認 0.95）時 agent.cancel({ kind: 'hook' })；enforceAtPreStep 爲真時超預算拒絕下一步 |
手動攔截（manual） |
不自動取消；composer 下方預算條提供「繼續 / 中止」；可用 /budget continue、/budget abort |
預算爲 0 時不攔截——未設金額且未設 Token 時不會 cancel 或 pre-step 拒絕；只有任一維度大於 0 才啓用閾值判定。
預估與展示¶
- 任務前粗估（
enablePreEstimate）：首輪前給出步數與金額/Token 範圍及佔預算比例，可關閉。 - 每輪降級預估（
enableTurnEstimate）：展示近期歷史燃燒率（最近 3 輪/步平均）；僅在模型明確寫出計劃時顯示剩餘步數與剩餘金額，不預測未來總花費。 - 輸出位置（
estimateOutput）：chat/sidebar/both（默認）；右側欄依賴dsh-better-sidebar，無 bundle 時退回對話卡片。
安全與可恢復性¶
/config/save與/action默認僅接受本機 loopback（requireLocalControl、requireLocalAction）。- 冷啓動快照 + 從會話日誌重放，避免重複計費；排障可用
/budget reset-snapshot按日誌重算本會話緩存（保留用戶預算聲明與手動放行決定）。
攔截流程概覽：用戶請求 → agent/pre-step → 計費引擎 → 高峯/空閒計價 → 累計判定 → 放行或攔截/詢問。
安裝與啓用¶
環境要求¶
- DeepSeek Harness 0.2.0 及以上；
- Node.js >=22.13；
PATH中有 pnpm（供dsh plugin使用）。
從 npm 安裝（推薦）¶
dsh plugin --profile web add dsh-budget-guard-plugin
安裝後請 重啓正在運行的 Web Profile。DSH 會識別包內 dsh.bundle manifest，並在 composition 中插入 budget-guard 行，默認含 interceptMode: auto、enableTurnEstimate: true、estimateOutput: both 等。
從 GitHub 安裝¶
需要尚未發佈到 npm 的變更時：
dsh plugin --profile web add github:Existence001100/dsh-budget-guard-plugin
如需可復現安裝，請固定到具體 commit。
更新與卸載¶
dsh plugin --profile web update dsh-budget-guard-plugin
dsh plugin --profile web remove dsh-budget-guard-plugin
任一操作後同樣應重啓 Profile。
典型用法¶
對話命令（僅當前會話）¶
命令不調用模型，只寫會話日誌，便於審計與重放：
/budget 2.5 # 本次任務 ¥2.50
/budget 20000 tokens # 本次任務 20k tokens
/budget 20k # 同上
/budget both 2 20000 # 金額 + Token 雙上限（任一先到即觸發）
/budget # 查看當前預算、已用、進度與上一輪預估
/budget continue # manual 模式：繼續，再增加約 10% 預算後再次提示
/budget abort # manual 模式：中止當前輪次
/budget unlock # 解除本會話攔截（仍統計費用）
/budget lock # 恢復攔截
/budget off # 清除會話覆蓋，回到 Config 默認
/budget reset-snapshot # 按日誌重算計費緩存（排障）
Config 示例¶
在 cordis.patch.yml 中覆蓋 budget-guard 的 config，例如：
- id: budget-guard
config:
budgetAmount: 2
tokenBudget: 0
currency: CNY
warnRatio: 0.8
interceptRatio: 0.95
interceptMode: auto
enablePreEstimate: true
enableTurnEstimate: true
estimateOutput: both
turnEstimateMinInterval: 1500
enforceAtPreStep: true
holidays: []
常用鍵含義（完整表見 README「配置項」）：budgetAmount / tokenBudget 默認 0 表示不設該維上限；warnRatio 須 ≤ interceptRatio；比例在設置頁以百分數展示（如 85 表示 0.85）。snapshotPath、allowedOrigins、holidays、useBuiltinHolidays 僅能通過 patch 手改，不在設置表單中。
適用場景與注意¶
適合：在 DSH Web Profile 中長期跑 Agent、需要會話級費用上限、希望接近超支時自動停或人工確認再繼續的團隊或個人；與官網賬單對賬、高峯/空閒價、子代理聚合等有專門 README 章節可查閱。
注意：
- 插件估算基於內置價格表與會話日誌 usage，與官網賬單可能存在差異——README 提供「怎麼覈對金額」說明。
- 默認
budgetAmount與tokenBudget均爲 0，不會因未設預算而誤攔；啓用攔截前須顯式設預算或 Config 默認值。 - 安裝、更新、卸載後重啓 Profile，保證 composition 與已安裝 bundle 一致。
- 問題反饋可走 GitHub Issues（倉庫 bugs 字段指向該地址）。
結尾¶
經過上面的步驟，你可以在 DSH 裏爲每次任務加上可配置的金額或 Token 預算線，並在超支前預警或攔截，同時保留日誌重放與快照恢復能力。進一步瞭解能力與邊界，請閱讀倉庫 README；安裝入口見 SkillHub dsh-budget-guard-plugin 與 GitHub 主頁。
