配置项

键	默认值	说明
`budgetAmount`	`0`	每个会话默认金额预算；`0` 表示不设金额上限
`tokenBudget`	`0`	每个会话默认 Token 预算；`0` 表示不设 Token 上限
`currency`	`CNY`	只支持 `CNY` / `RMB`；两者都是人民币，统一显示 `¥`（不做汇率换算）
`warnRatio`	`0.8`	预警比例，必须 ≤ `interceptRatio`
`interceptRatio`	`0.95`	拦截阈值（0.01–1）
`interceptMode`	`auto`	`auto`：自动取消；`manual`：只提示，等用户点「继续 / 中止」
`enablePreEstimate`	`true`	任务开始前给出粗估
`enableTurnEstimate`	`true`	每轮结束后显示消耗估算：未提供计划时只展示近期历史均值，不做未来外推
`estimateOutput`	`both`	`chat` / `sidebar` / `both`
`turnEstimateMinInterval`	`1500`	两次预估的最小间隔（毫秒），避免连续快轮重复计算
`enforceAtPreStep`	`true`	在 `agent/pre-step` 也做硬拦截，防止超预算后继续买模型调用
`holidays`	`[]`	法定节假日（`YYYY-MM-DD`）。非空时完全覆盖内置表；为空 / 全部非法且 `useBuiltinHolidays=true` 时回退内置表
`useBuiltinHolidays`	`true`	为空时是否允许回退内置 2024–2026 节假日表；`false` 时为空表示“无节假日”；2027 起内置表超范围会 warn
`allowedOrigins`	`[]`	开发用跨源白名单；生产默认只允许同源，见“HTTP 路由”
`enableSnapshot`	`true`	将累计状态写入冷启动快照
`snapshotPath`	`''`	快照基路径；空值时使用 `$DSH_HOME/budget-guard/snapshots.json`，实际写入 `.
.json`
`snapshotMaxSessions`	`200`	每个实例快照最多保留的会话数；活跃会话优先保留
`snapshotKeepTurns`	`8`	快照保留最近多少轮的全部 `stepCharges` 明细；更早的重试会被拒绝并 warn，不会重复累加
`snapshotMaxAgeDays`	`30`	非活跃快照的最长保留天数；`0` 表示不按时间清理
`unknownWarnRatio`	`0.2`	未定价 token 占比达到此值时提示“按最高价估算，实际可能偏低”
`maxGrantedPercent`	`30`	manual「继续」最多累计放行比例；默认终值 130%，严格低于 142.5% 硬停线
`manualHardStopRatio`	`1.5`	manual 模式（含 suppress）超过 `interceptRatio × 该值` 时强制中止
`perSessionMaxSettled`	`2000`	每个会话保留多少条已结算摘要；超过后新步骤只记标记，重试会被拒绝而不是替换
`requireLocalControl`	`true`	`/config/save`（改全局预算）只接受本机（loopback）请求；远程 GUI 改预算需显式关闭
`requireLocalAction`	`true`	`/action`（继续 / 中止 / 设置本次预算）只接受本机请求；可单独关闭以支持远程 manual 操作

单价只影响“金额”核算；Token 预算始终按真实 usage 计算。价格不在 Config 里硬编码，见下一节。

GET /dsh-budget/config 还返回 4 个只读字段（output / holidaysSource / priceSources / server），它们不能通过 /config/save 写回；含义见「HTTP 路由」下的「只读字段」小节。

dsh-budget-guard-plugin

安装

说明文档

配置项