成本预算治理 PerryLink/dsh-budget

💰 dsh-budget

- 1024 store channel：先执行一次 npm i -g dsh1024，再执行 dsh1024 plugin --profile web add dsh-budget（会计入 deepseek1024.com 的安装排行）。

dshfind

DeepSeek Harness 的成本治理：预算、碳排放、延迟，一个面板全看。

每个会话花多少，先看清再花。

官方仓库。 这里是 dsh-budget 唯一的官方仓库，由 PerryLink 维护。其他账号下的同名仓库与本项目无关。

dsh-doctor
DSH Market

English · 简体中文 · Español · Português · हिन्दी

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

📖 生态知识库 —— 实测数据，不是营销话术：插件开发指南 · 插件选型数据 · 维护标准。

安装与卸载

- git channel（最新 main）：dsh plugin --profile web add github:PerryLink/dsh-budget —— prepare 脚本只用生产依赖构建。
- npm channel（已发布版本）：dsh plugin --profile web add dsh-budget。
- tarball channel：在本仓库执行 pnpm pack，再执行 dsh plugin --profile web add ./dsh-budget-<version>.tgz。
- 卸载：dsh plugin --profile web remove dsh-budget。
如果 pnpm 对这个包报出 ERR_PNPM_IGNORED_BUILDS（esbuild 对平台二进制的无害校验），在 pnpm-workspace.yaml 里加上 allowBuilds: { esbuild: true } —— dsh 命令行会打印出确切的片段。

⭐ 如果它帮到了你

这个插件是 DSH 插件家族的一员（95 个，全部 Apache-2.0）。如果你在用，给个 star —— 它不会解锁任何功能，但会让下一个人在搜索里更容易找到它。

English: part of a 95 plugin family for DeepSeek Harness. If it is useful, a star helps the next person find it — nothing is gated behind it.

dsh-budget 是什么？

DeepSeek Harness 的成本治理：预算、碳排放、延迟，一块面板全看。

每个会话花多少，先知道，再花钱。

dsh-budget 的工作流示意图：请求 → 策略 / 复核 → 判定。

工作流概览：请求 → 策略 / 复核 → 判定。下面的示例用的是真实命令接口。

维护状态：🧊 已冻结

2026-10-05 冻结。不再加新功能。 这个包还能用，也没有退役 —— 但不再做功能开发。只有真正的故障才会修。

维护者认为，这项能力生态里已经收敛到更广泛采用的实现，所以精力挪去了别处。下面的对比测于 2026-10-05，记录下来，省得别人再测一遍。

| | 包 | 每周下载量 |
| 本包 | dsh-budget | 1,079 |
| 更广泛采用的实现 | dsh-cost-meter | 33,526 |
| 另一个替代 | dsh-usage-stats | 未测 |
| 另一个替代 | @dougen/dsh-deepseek-usage | 6,019 |

为什么它是主流选择。 dsh-cost-meter 提供 170+ 模型的价格目录，自动匹配，还能查 11 个服务商的 Coding-Plan 配额。

兼容性。 它声明的 dsh peer 范围包含 0.2.x 线，所以在当前宿主上能加载。

👉 新项目请选 dsh-cost-meter，这是主流选择。 已安装的照常能用，什么都没删。

完整证据，含宿主版本兼容矩阵：dsh-plugin-supersession-review-20261005.md。

对比

dsh-budget 的实测对比图

实测于 2026-10-05 · 数据来自 README 的 FROZEN 维护表（npm 每周下载量）

兼容性

| 层面 | 状态 |
| Harness | DeepSeek Harness dsh-v0.2.1-alpha.1（GitHub tag，2026-09-24 适配；peer 范围 >=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-0 <0.2.0 || >=0.1.7-0 <0.2.0）：alpha.2 目录价已内置到价格表，未知模型会显示为未定价，不再编造估算值；审计闸门继续抑制 budget/alert/budget/block 追加（fail-closed 会话事件词表）。2026-09-24 经双尺类型检查链与完整本地闸门验证；浏览器面板相关条目仍为 人工·未测即未完成（维护者手动清单）。 |

| 审计事件 | 在 0.1.2-rc.1 之前的 harness 上写入；在 0.1.2-rc.1 及之后抑制，并记录降级原因（fail-closed 会话事件词表，无外部注册面） || Node | ^22.19.0 \|\| >=24.0.0 |
| 界面 | 宿主 + Web 客户端（设置预算标签页）；/budget 命令 |

你能得到什么

dsh-budget 把会话事件流变成四合一成本治理闭环：

- 聚合计量 —— 按模型、会话、天统计 token（未缓存输入 / 输出 / 缓存读取 / 缓存写入）、估算 USD 成本与碳足迹，价格来自内置的每 1M token USD 价格表，并与你的 config.prices 合并。
- 预算治理 —— 会话 / 每日 / 每月上限；警告比例阈值告警（webhook POST + 桌面通知开关）与三种超限策略：alert（只通知）、block（短路新的模型请求，直到用户解除封锁）、degrade（封锁并给出纠正指引，从你的 degradation 映射里点名更便宜的模型）。
- 碳与延迟 —— token→碳桥接（tokens × kWh/token × PUE × 区域电网强度，移植自 AI-Carbon-Footprint-Calculator）与按模型统计的延迟百分位。
- 界面 —— 设置预算标签页（用量条、每日用量曲线、模型明细、告警、上限编辑器、解除封锁按钮）与 /budget 命令（/budget、/budget models、/budget unblock <scope>）。

快速开始

dsh plugin --profile web add github:PerryLink/dsh-budget

1. install the bundle into your profile
dsh plugin --profile web add github:PerryLink/dsh-budget

or from npm (published releases)
dsh plugin --profile web add dsh-budget

2. restart and verify the row
dsh --profile web --dump-config | grep -A2 'id: budget'

然后对智能体说：/budget —— 看设置标签页填上数据。

示例

这些是插件的真实入口；装一次，然后调用其中一个。

详细示例

命令

~~~sh
/budget

输出

~~~text
session: 5.00 USD / 10.00 USD (50% · 1000 tokens · 0.0010 kg CO2e) daily: 60.00 USD / 50.00 USD (120% · 20000 tokens · 0.0200 kg CO2e) BLOCKED monthly: 60.00 USD / unlimited (0% · 20000 tokens · 0.0200 kg CO2e) deepseek/deepseek-chat: 0.05 USD (100 in / 50 out · p50 20ms · 0.0001 kg CO2e)

取自 tests/command.spec.ts:14-62 (STATUS fixture and overview test); src/command.ts:65-88

失败分支

输入 ~~~text /budget unblock yearly

输出

~~~text
usage: /budget [unblock session|daily|monthly | models]

观察自 plugins/dsh-budget/src/command.ts:35; plugins/dsh-budget/src/command.ts:99-103; plugins/dsh-budget/src/command.ts:128; plugins/dsh-budget/tests/command.spec.ts:49-50

简要示例

- /budget models
- /budget unblock <scope>

配置

所有可调项都是 Schemastery 的 Config 字段（可在 cordis.yml 中修改）。cordis.patch.yml 内联说明了每个键。

| 键 | 默认值 | 含义 |
| prices | {} | 每个模型每 1M token 的美元价格，合并到内置表之上 |
| defaultPrice | 未定价信号（priced: false，数值全为零） | 两张表里都没有的模型走这个兜底：默认值对计费贡献 0，并显示为「未定价」；要显式给未知模型定价，就设好数值并把 priced 设为 true |
| budgets.session / daily / monthly | 10 / 50 / 500 | 各作用域的预算上限，单位美元；省略表示不限 |
| warnRatio | 0.8 | 用量达到上限的这个比例时告警一次（0..1） |
| overLimit | alert | 超出上限后的动作：alert / block / degrade |
| degradation | {} | 模型 id → 同一服务商下更便宜的模型 id |
| webhookUrl | （无） | 可选的 webhook URL，用于阈值告警（POST JSON） |
| webhookTimeoutMs | 5000 | webhook 请求超时 |
| alertsEnabled | true | 阈值告警总开关 |
| alertCooldownMs | 3600000 | 同一作用域两次告警之间的最小毫秒数 |
| desktopNotifications | false | 标签页打开时发送浏览器桌面通知 |
| refreshIntervalMs | 5000 | 设置标签页的轮询间隔 |
| carbon.enabled / region / pue / energyKwhPerToken | true / global / 1.58 / 0.000007 | 碳排放桥接（region 可选：global、us、eu、china、india、uk、france、iceland） |
| latency.enabled / windowSize | true / 200 | 每个模型的延迟分位数及其统计窗口 |
| currency | {code: USD, rate: 1.0, decimals: 2} | 显示货币（费用一律按美元计算） |
| outputLanguage | en | /budget 的输出语言：en / zh |
| historyDays | 30 | 面板快照中保留的每日用量历史天数 |
| persistence.enabled / intervalMs | true / 10000 | 重启后仍保留按天/按月数据（storage 域）；该域不存在时退化为内存存储 |

工具与界面

| 界面 | 类型 | 说明 |
| /budget | 命令 | 各作用域总览（用量、比例、碳排放、封禁状态） |
| /budget models | 命令 | 按模型细分，附延迟分位数 |
| /budget unblock <scope> | 命令 | 解除某个被封禁的作用域（session / daily / monthly） |
| Settings → Plugins → Budget | 设置标签页 | 用量条、每日用量曲线、模型细分、告警、上限编辑、解封按钮 |
| budget/status、budget/setSettings、budget/unblock | Typert Remote | 客户端通道（标签页消费这些接口） |

权限与数据

- 权限：network:outbound（仅用于可选的告警 webhook）、session:append（审计事件）、native-code:none。
- 数据：界面显示的内容全部来自会话事件流；宿主机侧唯一的网络调用是配置的 webhook，其 URL 在加载时校验，写日志前会剥离凭据。提示词和载荷永远不会离开宿主机。
- 会话日志：budget/alert 和 budget/block 是只写日志的审计事件，携带作用域名称和美元金额（经微任务延迟，避开 session-append 的重入保护）。在 0.1.2-rc.1 及更高版本的 harness 上，这两个事件不会写入——fail-closed 的事件词表会拒绝包含未注册事件类型的日志，也不提供外部注册入口——因此审计线索退化为预算日志器和 webhook。

安全边界

- 不伪造：预算拦截会在 llm/stream 瀑布上产生一个纠正性错误结束——插件从不编造模型输出。
- 不改写请求：循环构建的请求是冻结的；因此 degrade 在纠正消息里点名目标模型，而不是替换请求。
- 大声失败：无效的价格、URL、比例、区域和边界都会导致挂载失败。
- 如实说明范围：面板里的运行时修改只作用于当前会话；重新加载会恢复 cordis.yml 中的值。

已知限制

- 聚合是进程内的：harness 重启后用量会重置（按日/按月桶从当前会话日志视图重建）。
- block/degrade 依赖 llm/stream 瀑布；没有这个接缝的 harness 构建无法拦截请求（告警仍然可用）。
- 内置价格会漂移；通过 config.prices 覆盖条目。

开发

pnpm install # node ^22.19 || >=24
pnpm run typecheck # tsc: src + tests against the local harness checkout
pnpm run typecheck:ci # tsc against the published types (no paths)
pnpm test # vitest
pnpm run build # tsc declarations + tsdown bundles (lib/)
pnpm run verify:self-contained # dependency specs resolve from the registry
pnpm run verify:artifacts # built ESM face + typert manifest + client bundle
pnpm pack # the published tarball

与其他 DSH 插件的互操作性

已针对 DSH 0.2.0-rc.2（本 README 面向的运行时）以及 2026-10-05 调研的高星插件集验证。

本插件不会干扰其他插件，包括广泛安装的高星插件：

- 无工具名冲突。 每个工具都带命名空间；不注册任何已发布工具或其他插件拥有的裸名称。
- 无服务键冲突。 它提供 budget；该键不是内置接缝，调研过的高星插件也都不提供。
- 无槽位冲突。 它不注册任何客户端槽位键，因此不会争抢 shadows-shipped-ui 的席位。
- 无 HTTP 路由冲突。 它不注册任何 webServer 前缀。
- 不会与补丁层冲突。 插件包里的补丁只 insert 自己那一行，从不覆盖内置行的 config。
- 不做全局改动。 它不改原型、不重写 process.env、也不替换全局 fetch dispatcher。

共享事件监听器从设计上就互不干扰。 它用 ctx.on() 监听对顺序敏感的事件 llm/stream —— 这是 Cordis 的广播注册方式，每个监听器都会执行，谁也无法挤掉别人。这里的每个监听器都通过 next() 委托，所以调用链永远不会被短路；改动施加在 next() 产出的值上，而不是拿自己的返回值顶替它：
- llm/stream —— dsh-routing-suite（7000★）也在用。

静态证据：dsh-plugin-doctor 的 K10–K13 对本仓库的每一项检查都报告 pass。

Topics

dsh, dsh-plugin, deepseek-harness, deepseek, cordis, budget, cost-tracking, carbon-footprint, latency-benchmark, token-usage

贡献者

- @PerryLink —— 创建者兼维护者：聚合、预算治理、碳排与延迟移植、Settings 标签页，以及五语文档。

PerryLink DSH 插件家族

本项目属于 PerryLink 的 DeepSeek Harness 插件家族。下面这份名单默认折叠，好让每个 README 的首屏都保持简短；展开即可看到每一行及其状态。

展开全部插件

| 插件 | 状态 |
| dsh-aqua-input-check | |
| dsh-archive-check | |
| dsh-auto-review | |
| dsh-autotier | |
| dsh-bid-ca-precheck | |
| dsh-bid-qual-check | |
| dsh-cert-mcp | |
| dsh-checkpoint-rewind | |
| dsh-click | |
| dsh-composer-history | |
| dsh-contract-stance | |
| dsh-customs-doc-check | |
| dsh-data-quality | |
| dsh-demurrage-ledger | |
| dsh-doublecheck | |
| dsh-drill-script-check | |
| dsh-eia-guide-check | |
| dsh-emergency-plan | |
| dsh-essay-rubric-check | |
| dsh-evidence-check | |
| dsh-export-ctl-check | |
| dsh-fast | |
| dsh-fmea-table-check | |
| dsh-forecast-penalty | |
| dsh-fund-research | |
| dsh-github | |
| dsh-gongwen-flow-check | |
| dsh-gongwen-word-check | |
| dsh-guard-plan-qc | |
| dsh-hazchem-check | |
| dsh-hazplan-check | |
| dsh-hidden-risk-map | |
| dsh-hs-classify | |
| dsh-icd-rule-check | |
| dsh-industry-research | |
| dsh-lawcite-adapter | |
| dsh-laya | |
| dsh-lc-doc-check | |
| dsh-learning-gap-check | |
| dsh-library | |
| dsh-local-ai | |
| dsh-lsp-actions | |
| dsh-mask | |
| dsh-mcp-panel | |
| dsh-medrec-qc | |
| dsh-memento | |
| dsh-nsfc-form-check | |
| dsh-nurse-record-check | |
| dsh-observe | |
| dsh-origin-rvc-check | |
| dsh-ota-review-check | |
| dsh-output-styles | |
| dsh-paper-doc-adapter | |
| dsh-permission-rules | |
| dsh-permit-report-check | |
| dsh-pipeline-check | |
| dsh-pleading-draft | |
| dsh-plugin-doctor | |
| dsh-plugin-guide | |
| dsh-plugin-kit | |
| dsh-plugin-upgrade | |
| dsh-policy-brief-draft | |
| dsh-power-loss-split | |
| dsh-power-ticket-check | |
| dsh-ppap-check | |
| dsh-protest-deadline | |
| dsh-railway-window | |
| dsh-repair-order-qc | |
| dsh-research-report | |
| dsh-review-reply-check | |
| dsh-rulefile-check | |
| dsh-safety-brief-check | |
| dsh-score | |
| dsh-session-sync | |
| dsh-site-log-check | |
| dsh-skill-pack-security | |
| dsh-soe-decision-check | |
| dsh-soilwater-check | |
| dsh-sop-sync-check | |
| dsh-spc-gbt-adapter | |
| dsh-talk | |
| dsh-tender-extract | |
| dsh-tender-matrix | |
| dsh-test-drive | |
| dsh-ticktick | |
| dsh-translate | |
| dsh-warranty-calc | |
| dsh-budget | 🧊 已冻结 —— 见仓库 README |
| dsh-claude-move | 🧊 已冻结 —— 见仓库 README |
| dsh-defend | 🧊 已冻结 —— 见仓库 README |
| dsh-draw | 🧊 已冻结 —— 见仓库 README |
| dsh-reach | 🧊 已冻结 —— 见仓库 README |
| dsh-background-agents | 🚫 已停用 — 见仓库 README |
| dsh-session-pin | 🚫 已停用 — 见仓库 README |
| dsh-team-rooms | 🚫 已停用 — 见仓库 README |

许可证

Apache License 2.0 © 2026 dsh-budget contributors