前言¶
在 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 主页。
