前言¶

DSH 生態裏已經有不少插件能告訴你一個目標花了多少錢、多少 token，但這類插件大多到此爲止：只讀，只展示。長任務真正缺的是下一步——當預算用盡時把目標停下來，而不是讓它繼續自動續跑。boom-10 維護的 dsh-goal-budget 補的就是這一步：把會話消耗歸因到目標，超限後調用官方策略入口阻斷目標。下面介紹它實際做了什麼，以及怎麼裝、怎麼用。

這是什麼¶

一句話定位：給 DSH 的長任務目標設一個 token / 費用（以及計算時間）上限，超了就停，不是隻報一個數字。

基本信息來自 README 與 package.json：

• 插件名：dsh-goal-budget
• 維護者：boom-10
• 分類：工作流
• Star：0
• 版本：0.10.2，license MIT
• 運行要求：Node ≥ 22，DSH >=0.2.1-rc.5 <0.3.0

這個缺口在 DSH 自帶代碼裏被明確承認過。goal-round-driver 的 README 寫着：它的輪次上限不是資源預算，token、貨幣、時間等策略各自獨立，會話事件「不會歸因到目標消息」「不會被映射成目標的阻斷碼」。本插件補上三塊：按 goalId + round 做歸因，給出樹內第三個阻斷碼 budget-exceeded，並在 0.8.0 加入計算時間預算。

核心功能¶

目標維度的歸因¶

插件不自己存一份賬。它從會話事件日誌重建歸屬關係：agent/inbox/claimed 是唯一把消息和它開啓的 turn 配對的事件，assistant/message 攜帶 turn 和 usage；據此把每個 turn 的消耗累加到對應的 {goalId, round} 上。重啓不會重複計費，也不會清零。

阻斷而非告警¶

預算超限時，插件調用 ctx.goals.block()，在一次調用裏標記目標 blocked 並解除自動續跑。阻斷原因是一個穩定的 code 加一段可讀說明，例如 budget-exceeded。可選配置 onExceed: block | warn，warn 模式只記日誌不阻斷。

展示與判定同源¶

輸入框狀態條裏多出一個 pill，點開是花費明細。pill 不自己算錢，讀的是與阻斷判定同一個投影，因此界面上的數和閘門用的數不會分歧。顯示分兩種狀態：未設上限時面板提示怎麼設；設了之後標題欄右側出現使用百分比，pill 上長出進度條，80% 轉琥珀，100% 轉紅。

計算時間預算¶

除了 token 和費用，還可以設計算時間上限。時長 = 各輪跨度之和（每輪從 turn/start 到最後一個 turn/end），而不是 now - 創建時間，所以目標暫停隔夜不會誤爆預算；代價是輪間的空閒不計入。時間只用 SessionEvent.time，不用 Date.now()，重放同一份日誌得到同一個數。它是 0.8.0 加入的，pill 上暫時不顯示時間。

安裝與啓用¶

安裝命令來自 README 原文，兩條等價，按你的 registry 選：

dsh plugin --profile desktop add dsh-goal-budget                 # npm 源
dsh plugin --profile desktop add github:boom-10/dsh-goal-budget  # GitHub 源

裝完重啓 DSH（客戶端和宿主半邊都在啓動時加載）。兩點注意：

• 如果本機默認 registry 是公司內網代理且還沒同步到這個包，add dsh-goal-budget 會報 ERR_PNPM_NO_VERSIONS，改用 GitHub 源即可。
• 帶版本號的形式在兩種源上都不可用，不要寫 ...@0.10.0。

在開放插件市場裏搜 Goal Budget 也可以裝（已收錄）。不配任何預算也能裝——插件加載後空轉，等你用 /budget 設值。

配置與用法¶

會話內設上限¶

直接在輸入框打命令，不改 YAML、不重啓：

/budget            查看當前生效的上限和已用量
/budget $5         本會話費用上限 5 美元
/budget 500k       本會話 token 上限 50 萬
/budget $5 500k    兩個都設，誰先到算誰
/budget $5 30min   費用和計算時間都設，支持 s / min / h
/budget off        清掉會話覆蓋，回到 profile 默認

時間單位用 min 而不是 m，因爲 m 已被用來表示百萬 token。預算按「會話覆蓋 ?? profile 默認」解析：固定額度寫在配置裏，臨時收緊在輸入框打一行。

profile 默認¶

給所有會話一個固定額度的 YAML 配置如下，字段帶註釋：

- id: dsh-goal-budget
  config:
    budget:
      tokens: 2000000
      costUsd: 5.00
    onExceed: block        # 或 'warn'，只記日誌不阻斷
    warnAtRatio: 0.8
    currency: auto                       # auto：用 DeepSeek 餘額接口識別（官方線路）；網關線路寫 USD 或 CNY
    deepseekCredentialRef: DEEPSEEK_API_KEY   # 憑據服務裏的 Key 引用名
    modelAliases: {}                     # 網關給模型改名時映射，例如 cm-ais/deepseek-v5-flash: deepseek-flash
    peakPricing: false                   # 官方線路 true；網關按固定單價計費時 false（否則高峯時段高估一倍）

兩層界面的設計理由是：預算是運行時決策，插件配置是啓動時讀的部署決策；把預算只放在配置裏，改一個臨時值就得改 YAML 加重啓。會話級預算配會話級界面，就是 /budget 存在的原因。

與其他用量插件的區別¶

生態裏報花費的插件已經飽和，且全是隻讀的，例如 @kenz1117/dsh-ui-usage-billing（賬單看板，95 星）、dsh-credits（跟蹤餘額與套餐）、dsh-composer-balance（顯示餘額）。它們回答「我花了多少」。本插件回答「該不該繼續」，並把這個答案執行下去。

適用場景與注意¶

適合需要給長任務目標加硬預算、不希望燒穿額度自行停止的用戶，尤其是配置了目標自動續跑的場景。README 也列出了已知失敗模式，需要按預期理解：一輪裏若混入人類消息和目標消息，人類的消費可能被記到目標上導致過早阻斷，緩解辦法是嚴格過濾 source.kind === 'goal'。

插件以當前 DSH 進程的權限運行，會在你啓動的會話裏讀取事件、註冊命令並調用阻斷入口。安裝前建議先讀源碼（許可證爲 MIT）確認行爲符合預期，尤其是計劃把它作爲部署默認策略時。

結尾¶

dsh-goal-budget 的價值在於把「預算超限」從一個數字變成一個動作：讓目標停下，而不是繼續燒。它複用 DSH 既有的事件與命令機制，不另起賬本，界面與判定共用同一份投影。如果需要更細的歸因規則或新增預算維度，建議從源碼入手。

• 目錄頁：https://www.skillhub.cn/plugins/boom-10/dsh-goal-budget
• 源代碼：https://github.com/boom-10/dsh-goal-budget