前言¶

在 DeepSeek Harness (DSH) 中構建智能體樹時，根智能體及其下屬的一次性、可續接子智能體往往並行消耗 Token，容易超出單次對話或全局的預算限制。dsh-plugin-agent-budget 插件爲這些智能體樹提供了共享的 Token 預算管理能力。它將整個智能體樹視爲一個預算賬戶，或者爲每個會話獨立覈算，防止 Token 消耗失控。

核心功能¶

該插件由 winter-street 維護，是一個 MIT 許可的開源項目。其核心功能集中在智能體樹的 Token 覈算與控制上：

1. 作用域管理：支持將整個智能體樹作爲一個預算賬戶（scope: tree），或者讓每個會話獨立使用預算（scope: session）。
2. 獨立存儲：賬本存儲在插件擁有的側車目錄 ~/.dsh/agent-budget/ 中，不寫入會話日誌。這意味着卸載插件不會破壞會話數據。
3. 賬本特性：保持追加式、可重放、可恢復的日誌結構，確保數據持久化與可審計性。
4. 模型感知：爲模型本身提供只讀的 budget_status 工具，使其能主動感知剩餘額度。
5. 無外部依賴：作爲純本地 Bundle 運行，不依賴外部服務。

安裝與配置¶

由於包目前未發佈到 npm，需要通過本地包或 Git 依賴安裝。

1. 安裝插件：

    dsh plugin --profile <name> add dsh-plugin-agent-budget

或者使用 pnpm：

    pnpm add dsh-plugin-agent-budget

2. 基礎配置：
   插件依賴 dsh.profile.bundles 層，通常通過 cordis.patch.yml 配置。必須設置 maxTokens（正整數）。

    - insert:
        - id: agent-budget
          name: dsh-plugin-agent-budget
          config:
            maxTokens: 200000
            missingUsage: exhaust
            scope: tree

*   `maxTokens`：限制作用域內的最大 Token 數。
*   `missingUsage`：默認爲 `exhaust`（耗盡），若提供商不返回使用量且有意忽略，可設爲 `ignore`。
*   `scope`：默認爲 `tree`。若設爲 `session`，則每個會話獨立覈算。

作用域與語義¶

插件根據配置決定 Token 覈算的粒度與規則：

• 樹作用域 (scope: tree)：
  • 優先通過 DSH 的運行時智能體所有權解析根節點。
  • 若運行時不可用，則回退到持久化的 parentSession 鏈。
  • 若以上均不可用，則創建一個帶有警告的獨立預算賬戶。
  • 插件不會將不相關的會話合併到同一賬戶。
• 會話作用域 (scope: session)：
  • 每個會話擁有獨立的預算，包括子智能體。
• 覈算規則：
  • 包含所有帶 sessionId 的 llm/stream 調用（對話、子智能體、工作流、壓縮、標題生成）。
  • 未緩存輸入、緩存讀取、緩存寫入、輸出被劃分爲四個獨立的桶。
  • 理由 Token 已包含在輸出中，不再重複計算。

控制與降級¶

插件提供可選的控制層，在接近預算限制時主動干預，防止超支：

• degradeRatio (0–1)：
  當作用域剩餘比例低於此閾值時，後續調用會被降級。maxTokens 會被鉗制爲剩餘預算（最小值爲 1），且可配合 maxOutputTokens 設置硬性輸出上限。
• pressurePrompt (默認 true)：
  當使用量超過 50% 且達到 80% 時，會在系統提示中注入預算壓力提示。這利用模型自身的節流能力，在達到硬性限制前自我約束。
• maxConcurrentCalls：
  限制每個作用域下同時進行的最大提供者調用數。超過限制的調用會在調度前因 TOKEN_BUDGET_CONCURRENT_LIMIT 錯誤而失敗。

API 與設置¶

插件內置了一個本地 HTTP API 和設置面板。

• 設置面板：
  在 DSH 的設置頁面中會註冊一個“Token 預算”區域。它可以列出所有開放的作用域，顯示進度條，並允許調整限制或重置使用量，無需直接操作日誌文件。
• HTTP API (本地)：
  服務器運行在 /agent-budget/api，僅限本地訪問。請求需攜帶 X-Agent-Budget-Request: 1 頭。
  • GET /scopes：列出作用域及當前用量。
  • POST /adjust-limit：修改作用域限制。
  • POST /reset：清除指定作用域的用量。

注意事項¶

1. 實驗性狀態：該插件目前處於實驗階段，已針對 DSH 0.1.0-rc.6 進行驗證。
2. 依賴與構建：
   • 需要 @deepseek-ai/cordis、@deepseek-ai/dsh-agent 等特定對等依賴。
   • 使用 pnpm >= 10 安裝 Git 依賴時，默認會阻止構建腳本。需在 pnpm-workspace.yaml 中添加 allowBuilds: dsh-plugin-agent-budget: true。
3. 併發競態：
   • 允許併發 admits 的調用結果可能最終導致用量超過限制。
   • 一旦 settled 用量達到限制，後續調用會在調度前因 TOKEN_BUDGET_EXHAUSTED 失敗。
4. 數據存儲與卸載：
   • 數據位於 ~/.dsh/agent-budget/。
   • 卸載插件不會破壞會話日誌，但若要完全刪除預算數據，需手動刪除該目錄。
   • 併發寫入會被鎖拒絕，損壞的日誌或索引會導致啓動失敗。

總結¶

dsh-plugin-agent-budget 爲 DeepSeek Harness 提供了針對智能體樹的細粒度、持久化 Token 預算管理。通過配置作用域、開啓降級策略或利用模型自身的提示干預，可以構建成本可控的智能體工作流。更多細節可參考插件目錄或 GitHub 倉庫。