前言¶
DeepSeek Harness (DSH) 的核心設計理念是“一切皆插件”。在長時間運行智能體任務時，預算失控或任務突然中斷且無記錄是常見痛點。ziostudio/dsh-budget-handoff 是一個 Session budget brake 插件，它根據官方價目表實時計算消費，在預算耗盡時停止運行，並留下一份可恢復的交接快照。
安裝與啓用¶
安裝該插件需要指定 profile。安裝完成後需重啓 DSH。
dsh plugin --profile <你的profile> add dsh-budget-handoff
安裝過程中若看到 missing peer 告警，屬於結構性噪音，不影響使用。若需要固定版本，可在命令末尾添加版本號。
核心功能¶
該插件提供以下能力：
- 按官方價目表計費：監控每一次調用，對照官方價格表計算成本。
- 預算耗盡攔截：當會話預算用完時，立即停止任務執行。
- 交接快照：攔截時生成一份包含上下文、文件改動和進度的快照文件，便於後續恢復。
- 預算管理：支持設置、查詢和臨時提高預算。
- 80% 預警：當消費達到預算的 80% 時發出提醒，但不會停止任務。
使用方法¶
基礎命令¶
在 DSH 會話中發送以下命令（大小寫與空格不敏感）：
/budget 5：將本會話預算設爲 5 元。/budget：查詢當前剩餘預算與已用金額。/budget 20：提高預算上限（需大於已花掉的金額）。
如果不設置，每個會話默認預算爲 10 元。
預算管理細節¶
- 格式校驗：
/budget abc會明確提示格式錯誤並給出用法。 - 下限限制：
/budget 0或/budget -1會被拒絕，下限爲0.0001元。 - 跨會話隔離：不同會話的預算互不影響。
預警與攔截機制¶
- 80% 預警：當已用金額達到預算的 80% 時，插件會發送一條提醒，說明剩餘金額和預計攔截點。任務會繼續運行，此提醒僅在會話中觸發一次。
- 100% 攔截：當預算真正耗盡時，任務執行會被停止。此時 CLI 的退出碼爲 1。
預算耗盡後的處理¶
1. 生成交接快照¶
當預算耗盡時，插件會在本地生成兩個文件：
<你的工作目錄>\BUDGET-STOPPED-handoff-snapshot.md<$DSH_HOME>\storages\dsh-budget-handoff\last-stop.md
快照包含以下信息：
- 生成時間與會話 ID。
- 觸發位置（turn/step）。
- 累計消費與預算對比。
- 任務目標描述。
- 幹到哪了（工作目錄、回覆次數、最近動作）。
- 動過哪些文件。
- 怎麼接着幹（恢復步驟）。
2. 恢復任務¶
要繼續之前的工作，需滿足以下條件：
- 提高預算：使用
/budget <新金額>提高上限，新金額必須大於已花掉的金額。 - 輸入指令：發送指令
繼續。
由於交接快照已注入模型上下文，模型可以基於此斷點繼續執行，無需從頭開始。
配置¶
若需修改全局默認預算，可在 profile 的 cordis.patch.yml 中添加配置：
- insert:
- id: dsh-budget-handoff
name: dsh-budget-handoff
config:
budgetCNY: 20.0
配置項說明：
* budgetCNY：每會話預算，單位人民幣元，默認 10.0，下限 0.0001。
* verbose：是否將逐筆用量輸出到 stdout，默認 false。
計費規則與限制¶
計費覆蓋範圍¶
插件僅覆蓋 deepseek-official provider 下的特定模型：
* deepseek-flash
* deepseek-v4-pro
* deepseek-v4-flash
* deepseek-v4-flash-vision-exp
如果使用其他 provider 或模型，插件無法計費，提示預算保護失效。
價格表與時段¶
價格基於 src/pricing.json，單位爲人民幣元 / 百萬 token。包含緩存命中/未命中、高峯/空閒兩檔價格。
- 高峯時段：北京時間（UTC+8）週一至週五
09:00–12:00、14:00–18:00。 - 空閒時段：除高峯時段外的時間（含週末）。
- 節假日處理：插件未建模法定節假日。節假日白天會被按高峯價（2 倍）計費，可能導致預算提前用完。
已知限制¶
- 單步會話不會觸發攔截：閘門在“下一步開始前”生效。如果會話只有一步，執行完即結束，不會觸發攔截。
- 跨進程不累計：累計消費與預算均爲內存值，進程重啓後歸零。
- 價格不自動更新：官方調價需手動修改配置文件並重新構建。
目錄與源碼¶
- 技能Hub 目錄：ziostudio/dsh-budget-handoff
- GitHub 倉庫：ZiOstudio/dsh-budget-handoff
