PerryLink/dsh-budget

💰 dsh-budget

• 1024 store channel: npm i -g dsh1024 once, then dsh1024 plugin --profile web add dsh-budget (counts toward the deepseek1024.com install ranking).

Cost governance for DeepSeek Harness: budgets, carbon, and latency in one panel.

Know what every session costs — before it costs you.

Official repository. This is the only official repository of dsh-budget, maintained by PerryLink. Same-name repositories under other accounts are not affiliated.

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

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

---

📖 Ecosystem knowledge base — measured data, not marketing: plugin development guide · plugin-selection data · maintenance criteria.

Install & uninstall

• git channel (latest main): dsh plugin --profile web add github:PerryLink/dsh-budget — the prepare script builds with production dependencies only.
• npm channel (published releases): dsh plugin --profile web add dsh-budget.
• tarball channel: pnpm pack in this repo, then dsh plugin --profile web add ./dsh-budget-<version>.tgz.
• uninstall: dsh plugin --profile web remove dsh-budget.

If pnpm reports ERR_PNPM_IGNORED_BUILDS for this package (esbuild's harmless platform-binary validation), add allowBuilds: { esbuild: true } to your pnpm-workspace.yaml — the dsh CLI prints the exact snippet.

⭐ 如果它帮到了你

这个插件是 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.

What is dsh-budget?

Cost governance for DeepSeek Harness: budgets, carbon, and latency in one panel.

Know what every session costs — before it costs you.

The same run, animated.

Maintenance status: 🧊 FROZEN

Frozen on 2026-10-05. No new features. This package still works, and it is not retired — but it no longer receives feature work. Only a genuine breakage will be fixed.

Maintainers treat this capability as one where better-adopted alternatives now exist, so effort has moved elsewhere. The comparison below was measured on 2026-10-05 and is recorded so nobody has to redo it.

	package	weekly downloads
this package	dsh-budget	1,079
better-adopted alternative	dsh-cost-meter	33,526
another alternative	dsh-usage-stats	not measured
another alternative	@dougen/dsh-deepseek-usage	6,019

Why the alternative leads. dsh-cost-meter provides a 170+ model price catalog with automatic matching, and Coding-Plan quota lookup for 11 providers.

Compatibility. Its declared dsh peer range admits the 0.2.x line, so it loads on current hosts.

👉 For new work, prefer dsh-cost-meter. Existing installs keep working unchanged; nothing is being removed.

Full evidence, including the host-version compatibility matrix: dsh-plugin-supersession-review-20261005.md.

Comparison

measured 2026-10-05 · from the README's FROZEN maintenance table (npm weekly downloads)

Compatibility

Surface	Status
Harness	DeepSeek Harness dsh-v0.2.1-alpha.1 (GitHub tag, adapted 2026-09-24; peer range `>=0.1.2-rc.1 <0.2.0

| Audit events | Written on harnesses before 0.1.2-rc.1; suppressed with a logged degradation reason on 0.1.2-rc.1 and later (fail-closed session event vocabulary, no external registration surface) || Node | ^22.19.0 \|\| >=24.0.0 | | Surfaces | Host + Web client (Settings budget tab); /budget command |

What you get

dsh-budget turns the session event stream into a four-in-one cost governance loop:

• Aggregated metering — tokens (uncached input / output / cache read / cache write), estimated USD cost, and carbon footprint per model, session, and day, priced through a built-in USD-per-1M table merged with your config.prices.
• Budget governance — session/daily/monthly caps; a warn-ratio threshold alert (webhook POST + desktop-notification flag) and three over-limit policies: alert (notify only), block (short-circuit new model requests until the user lifts the block), degrade (block with corrective guidance naming the cheaper model from your degradation map).
• Carbon & latency — token→carbon bridge (tokens × kWh/token × PUE × regional grid intensity, ported from AI-Carbon-Footprint-Calculator) and per-model latency percentiles.
• Surfaces — the Settings budget tab (usage bars, per-day usage curve, model breakdown, alerts, cap editors, unblock buttons) and the /budget command (/budget, /budget models, /budget unblock <scope>).

Quick start

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'

Then ask the agent: /budget — and watch the Settings tab fill in.

Configuration

All tunables are Schemastery Config fields (changeable from cordis.yml). cordis.patch.yml documents each key inline.

Key	Default	Meaning
prices	{}	Per-model USD prices per 1M tokens, merged over the built-in table
defaultPrice	unpriced signal (priced: false, zero numbers)	Fallback for models absent from both tables: the default contributes 0 to accounting and surfaces as "unpriced"; set numbers with priced: true to price unknown models explicitly
budgets.session / daily / monthly	10 / 50 / 500	Budget caps in USD per scope; omit for unlimited
warnRatio	0.8	Alert once usage reaches this fraction of a cap (0..1)
overLimit	alert	alert / block / degrade after a cap is crossed
degradation	{}	Model id → cheaper model id of the same provider
webhookUrl	(none)	Optional webhook URL for threshold alerts (POST JSON)
webhookTimeoutMs	5000	Webhook request timeout
alertsEnabled	true	Master switch for threshold alerts
alertCooldownMs	3600000	Minimum ms between two alerts of the same scope
desktopNotifications	false	Browser desktop notifications while the tab is open
refreshIntervalMs	5000	Settings tab polling interval
carbon.enabled / region / pue / energyKwhPerToken	true / global / 1.58 / 0.000007	Carbon bridge (regions: global, us, eu, china, india, uk, france, iceland)
latency.enabled / windowSize	true / 200	Per-model latency percentiles and their window
currency	{code: USD, rate: 1.0, decimals: 2}	Display currency (costs are computed in USD)
outputLanguage	en	/budget output language: en / zh
historyDays	30	Per-day usage history kept in the panel snapshot
persistence.enabled / intervalMs	true / 10000	Durable day/month persistence across restarts (storage domain); degrades to in-memory when the domain is absent

Tools & surfaces

Surface	Kind	Notes
/budget	Command	Per-scope overview (usage, ratio, carbon, blocked state)
/budget models	Command	Per-model breakdown with latency percentiles
/budget unblock <scope>	Command	Lift a blocked scope (session / daily / monthly)
Settings → Plugins → Budget	Settings tab	Usage bars, per-day usage curve, model breakdown, alerts, cap editors, unblock buttons
budget/status, budget/setSettings, budget/unblock	Typert Remote	The client channel (the tab consumes these)

Permissions & data

• Permissions: network:outbound (the optional alert webhook only), session:append (audit events), native-code:none.
• Data: everything displayed comes from the session event stream; the only host-side network call is the configured webhook, whose URL is validated at load and credential-stripped before any log. No prompts or payloads ever leave the host.
• Session log: budget/alert and budget/block are log-only audit events carrying scope names and USD amounts (microtask-deferred past the session-append reentrancy guard). On harnesses 0.1.2-rc.1 and later they are not written — the fail-closed event vocabulary rejects logs with unregistered event types and offers no external registration surface — so the audit trail degrades to the budget logger and webhook only.

Security boundaries

• No fabrication: a budget block yields a corrective error finish on the llm/stream waterfall — the plugin never invents model output.
• No request rewriting: loop-built requests are frozen; degrade therefore names the target model in the corrective message instead of swapping the request.
• Fail loud: invalid prices, URLs, ratios, regions, and bounds fail the mount.
• Honest scope: runtime edits from the panel are session-scoped; a reload restores the cordis.yml values.

Known limitations

• Aggregation is process-local: usage resets when the harness restarts (per-day/per-month buckets rebuild from the current session log view).
• block/degrade rely on the llm/stream waterfall; harness builds without that seam cannot block requests (alerts still work).
• Built-in prices drift; override entries via config.prices.

Development

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

Interoperability with other DSH plugins

Verified against DSH 0.2.0-rc.2 (the runtime this README ships for) and the high-star plugin set surveyed on 2026-10-05.

This plugin does not interfere with other plugins, including the widely installed high-star ones:

• No tool-name collision. Every tool is namespaced; no bare name owned by a shipped tool or another plugin is registered.
• No service-key collision. It provides budget; that key is not a built-in seam and is not provided by any surveyed high-star plugin.
• No slot collision. It registers no client slot key, so it cannot contend for a shadows-shipped-ui seat.
• No HTTP route collision. It registers no webServer prefix.
• No patch-layer collision. The bundle patch only inserts its own row; it never overrides a built-in row's config.
• No global mutation. It does not patch prototypes, rewrite process.env, or replace the global fetch dispatcher.

Shared event listeners are non-interfering by construction. It observes the ordering-sensitive event llm/stream with ctx.on() — Cordis's broadcast registration, where every listener runs and none can starve another. Every listener here delegates through next(), so the chain is never short-circuited, and a mutation is applied to the value next() produced rather than returned in its place:

• llm/stream — also used by dsh-routing-suite (7000★).

Static evidence: dsh-plugin-doctor K10–K13 report pass for every check on this repository.

Topics

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

Contributors

• @PerryLink — creator and maintainer: aggregation, budget governance, carbon and latency ports, the Settings tab, and the five-language docs.

PerryLink DSH Plugin Family

This project is one of the 87 actively maintained DeepSeek Harness plugins from PerryLink. The family roster is 95 plugins in total — 5 frozen, 3 retired — and stays collapsed below so every README keeps a short first screen. Expand it to see every row, with the reason in the Status column.

Plugin	One-liner	Status
dsh-aqua-input-check	水产养殖投入品记录核对（按投入品用量、休药期与起捕间隔核对记录自洽，仅提示差异，不作出定性结论）
dsh-archive-check	档案归档完整性与保管期限核对（依据《档案法》及配套规定，仅提示差异，不作出定性结论）
dsh-auto-review	Second-model auto-review on the approval chain, fail-closed by default
dsh-autotier	Automatic strong/cheap model-tier routing with deterministic risk guards and a /tier command
dsh-background-agents	Durable background child agents with a Web UI sidebar, messaging and interrupt	🚫 RETIRED — see the repo README
dsh-bid-ca-precheck	投标文件符合性预检（按招标文件逐条核对响应情况，仅提示差异，不作出定性结论）
dsh-bid-qual-check	投标人资格条件核对（按资格条件与证明材料核对逐条响应，仅提示差异，不作出定性结论）
dsh-budget	Cost governance for DeepSeek Harness: budgets, carbon, and latency in one panel.	🧊 FROZEN — see the repo README
dsh-cert-mcp	Read-only MCP server exposing the certification registry: grades, snapshots and five-dimension evidence
dsh-checkpoint-rewind	Claude Code /rewind-equivalent: snapshots, session forks, one-shot restore
dsh-claude-move	Migrate Claude Code sessions, memory, skills and CLAUDE.md into DSH	🧊 FROZEN — see the repo README
dsh-click	Cross-platform native desktop control for DeepSeek Harness — Windows first.
dsh-composer-history	Terminal-style input history for the web composer: arrows, Ctrl+R search
dsh-contract-stance	合同条款立场台账核对（按立场、风险等级与退让底线核对台账自洽，仅提示差异，不作出定性结论）
dsh-customs-doc-check	报关单证一致性核对（按公开的报关单填制规范核对单证间字段一致性，仅提示差异，不作出定性结论）
dsh-data-quality	Dataset quality checks and citation cross-checks (the optional numeric bridge consumed here)
dsh-defend	Prompt-injection, jailbreak, and secret-leak defense for DeepSeek Harness.	🧊 FROZEN — see the repo README
dsh-demurrage-ledger	滞箱费台账核对（按免箱期与费率核对超期天数与金额的自洽性，仅提示差异，不作出定性结论）
dsh-doublecheck	Engineering-discipline guard: requirements grill, test gates, adversary review
dsh-draw	Unified static-image generation routing for DeepSeek Harness.	🧊 FROZEN — see the repo README
dsh-drill-script-check	应急演练脚本核对（按阶段、响应分级、指挥与资源要素核对脚本齐备，仅提示差异，不作出定性结论）
dsh-eia-guide-check	环评导则适用性核对（按要素、导则名称与执行标准核对台账自洽，仅提示差异，不作出定性结论）
dsh-emergency-plan	应急预案要素齐备性与条款级页码定位（依据 GB/T 29639-2020 等公开文件，仅提示差异，不作出定性结论）
dsh-essay-rubric-check	作文量表评分核对（按评分项、原文定位与分值算术核对评分自洽，仅提示差异，不作出定性结论）
dsh-evidence-check	证据清单齐备性核对（按待证事实与证据要素核对清单自洽，仅提示差异，不作出定性结论）
dsh-export-ctl-check	出口管制物项核对（按管制清单、最终用途与许可证核对台账齐备，仅提示差异，不作出定性结论）
dsh-fast	Read-only performance diagnostics for DeepSeek Harness.
dsh-fmea-table-check	FMEA 分析表要素齐备性与风险顺序数一致性核对（按公开的 FMEA 方法标准核对表内自洽，仅提示差异，不作出定性结论）
dsh-forecast-penalty	预测准确率考核核对（按准确率、门槛与考核单价核对考核费用的算术自洽，仅提示差异，不作出定性结论）
dsh-fund-research	Deterministic research reports for Chinese public mutual funds
dsh-github	GitHub PR/issues integration for DSH, every write gated by approval
dsh-gongwen-flow-check	公文流转与办理时限核对（按公开的公文处理规范核对环节完整性与时限，仅提示差异，不作出定性结论）
dsh-gongwen-word-check	公文格式要素核对（按公开的党政机关公文格式标准核对版头与主体要素，仅提示差异，不作出定性结论）
dsh-guard-plan-qc	劳动保护与安全防护用品配置表核对（按公开的配备标准核对品名规格与配置数量，仅提示差异，不作出定性结论）
dsh-hazchem-check	危险化学品临界量与重大危险源辨识核对（按储存量与临界量核对台账自洽，仅提示差异，不作出定性结论）
dsh-hazplan-check	HAZOP 分析表要素齐备性与偏差推导一致性核对（依据公开的危险与可操作性分析标准，仅提示差异，不作出定性结论）
dsh-hidden-risk-map	安全隐患台账→《工贸企业重大事故隐患判定标准》（应急管理部令第10号）条款映射提示（仅提示差异，不作出定性结论）
dsh-hs-classify	商品归类层级一致性核对（按章、品目、子目与商品编号的层级关系核对自洽，仅提示差异，不作出定性结论）
dsh-icd-rule-check	ICD 合并编码与星剑号配对提示（依据 GB/T 14396-2016 与公开的 ICD 使用说明，仅提示差异，不作出定性结论）
dsh-industry-research	Industry research orchestration that seals its deliverables through this plugin's ctx.researchReport.assemble
dsh-lawcite-adapter	法条引用与文书要素核对（按名称、条号、原文与效力状态核对引用可核验性，仅提示差异，不作出定性结论）
dsh-laya	Laya typed decisions (noul/choice/score) as a first-class Cordis service and model-visible tools
dsh-lc-doc-check	信用证单据条款核对（按单据种类、份数、期限与不符点核对交单自洽，仅提示差异，不作出定性结论）
dsh-learning-gap-check	能力差距与培养计划核对（按能力等级差、培养措施与完成期限核对台账闭环，仅提示差异，不作出定性结论）
dsh-library	Local document knowledge base for DeepSeek Harness.
dsh-local-ai	Local-model (Ollama) integration for DeepSeek Harness.
dsh-lsp-actions	LSP diagnostics, formatting, completion, code actions and rename over language servers
dsh-mask	PII masking middleware: anonymize at the model boundary, restore at the display layer
dsh-mcp-panel	Read-only MCP runtime panel: /mcp command + Settings tab with status, tools and errors
dsh-medrec-qc	病案首页形式质控与逻辑矛盾提示（依据国卫办医发〔2016〕24号等公开文件，仅提示差异，不作出定性结论）
dsh-memento	Approval-gated cross-session memory: ctx.memory seam + SQLite + memory tool
dsh-nsfc-form-check	国家自然科学基金申请书形式审查与匿名化提示（依据《国家自然科学基金条例》与申请人导入的当年指南，仅提示差异，不作出定性结论）
dsh-nurse-record-check	护理记录时限、签名与评估表完整性校验（依据《病历书写基本规范》等公开文件，仅提示差异，不作出定性结论）
dsh-observe	OpenTelemetry and Langfuse observability exporter for DeepSeek Harness.
dsh-origin-rvc-check	原产地区域价值成分核对（按 RVC 定义式与门槛核对原产地判定自洽，仅提示差异，不作出定性结论）
dsh-ota-review-check	在线点评回复台账核对（按回复时限、问题分类与整改状态核对台账闭环，仅提示差异，不作出定性结论）
dsh-output-styles	Claude Code outputStyles-equivalent runtime style switching
dsh-paper-doc-adapter	试卷解析结构核对（按题型、答案、分值与 yotta 标识核对试卷结构自洽，仅提示差异，不作出定性结论）
dsh-permission-rules	Claude Code-style declarative allow/deny/ask permission rules with audit
dsh-permit-report-check	行政许可办理核对（按申请材料、法定时限与决定记录核对台账闭环，仅提示差异，不作出定性结论）
dsh-pipeline-check	项目全流程文件链条核对（按环节先后与金额口径核对链条自洽，仅提示差异，不作出定性结论）
dsh-pleading-draft	起诉状要素齐备性核对（按诉请、事实、证据、法条四要素核对文书齐备，仅提示差异，不作出定性结论）
dsh-plugin-doctor	Zero-dependency static + sandbox smoke detector for DSH plugins
dsh-plugin-guide	Plugin-development knowledge base as an on-demand agent skill
dsh-plugin-kit	Shared zero-runtime-dependency toolkit for the PerryLink DSH plugins
dsh-plugin-upgrade	One-package, one-corridor-index plugin upgrade skill: routes a repository to the matching closed corridor card
dsh-policy-brief-draft	政策专报要素核对（按观点、依据、出处与建议核对专报齐备，仅提示差异，不作出定性结论）
dsh-power-loss-split	线损电量拆分与考核表核对（依据公开的线损计算口径，仅提示差异，不作出定性结论）
dsh-power-ticket-check	电力工作票要素齐备性与签发许可顺序核对（依据现行电力安全工作规程，仅提示差异，不作出定性结论）
dsh-ppap-check	PPAP 提交要素齐备性核对（按公开的 PPAP 手册与提交等级核对要素齐备与版本填写，仅提示差异，不作出定性结论）
dsh-protest-deadline	质疑与投诉期限核对（按公开的政府采购质疑投诉规定核对期限与台账自洽，仅提示差异，不作出定性结论）
dsh-railway-window	铁路施工天窗台账核对（按时间窗、时长算术与命令号核对台账自洽，仅提示差异，不作出定性结论）
dsh-reach	Multi-channel approval/question bridge: WeChat/Telegram/Feishu, session console	🧊 FROZEN — see the repo README
dsh-repair-order-qc	维修工单结算核对（按项目金额、配件工时合计与结算总额核对算术自洽，仅提示差异，不作出定性结论）
dsh-research-report	Verifiable research-report engine: content-addressed evidence ledger and sealed versions
dsh-review-reply-check	审稿意见逐条回应覆盖核对（按意见与回应一一对应核对覆盖完整性，仅提示差异，不作出定性结论）
dsh-rulefile-check	规则库文件自检核对（按条款引用纪律与效力上限核对规则库自身合规，仅提示差异，不作出定性结论）
dsh-safety-brief-check	安全技术交底记录要素齐备性与签字闭环核对（依据公开的安全生产法规与检查标准，仅提示差异，不作出定性结论）
dsh-score	Multi-dimensional quality scoring for DeepSeek Harness plugins.
dsh-session-pin	Pin sessions in the Web sidebar with durable ordering	🚫 RETIRED — see the repo README
dsh-session-sync	Cross-device session sync for DeepSeek Harness — a dedicated git mirror of your session store.
dsh-site-log-check	监理日志跨日连续性与旁站覆盖提示（依据 GB/T 50319-2013 等公开文件，仅提示差异，不作出定性结论）
dsh-skill-pack-security	Security-audit skill pack: secret scan, dependency and supply-chain review
dsh-soe-decision-check	三重一大决策台账核对（按前置研究、会议审议与决议记录核对程序留痕，仅提示差异，不作出定性结论）
dsh-soilwater-check	土壤与地下水监测台账核对（按点位、监测项目、限值与超标判定核对台账自洽，仅提示差异，不作出定性结论）
dsh-sop-sync-check	作业规程与 FMEA／控制计划一致性核对（按编号与版本核对三份文件是否同步，仅提示差异，不作出定性结论）
dsh-spc-gbt-adapter	控制图常数与过程能力指数核对（按 GB/T 4091 的常规控制图常数表核对控制限与 Cp/Cpk 的自洽性，仅提示差异，不作出定性结论）
dsh-talk	Voice-first session loop for DeepSeek Harness: talk to it, hear it answer.
dsh-team-rooms	Cross-session team rooms: shared message bus, task board and timeline	🚫 RETIRED — see the repo README
dsh-tender-extract	招标文件条款摘录核对（按出处与原文逐字核对摘录完整性，仅提示差异，不作出定性结论）
dsh-tender-matrix	评标因素评分矩阵核对（按分值上限与合计核对矩阵自洽，仅提示差异，不作出定性结论）
dsh-test-drive	Isolated install-and-smoke test drives for DeepSeek Harness plugins.
dsh-ticktick	TickTick/Dida365 task bridge: session-header panel + 11 tools
dsh-translate	Vendor parameter translation and deterministic JSON repair for DeepSeek Harness.
dsh-warranty-calc	质保期与索赔金额核对（按质保期月数与里程、索赔金额算式核对自洽，仅提示差异，不作出定性结论）

Install from the DSH Desktop Market

All PerryLink plugins are browsable in the built-in DSH Desktop Market: Market → Sources → add source → paste https://perrylink-dsh-catalog.perrylink.workers.dev/catalog-source.json → select it. Installation still goes through the Market's npm-identity verification and your confirmation.

License

Apache License 2.0 © 2026 dsh-budget contributors