前言¶

在 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 仓库。