メインコンテンツへスキップ
P

dsh-budget

perrylink/dsh-budget

llm/stream ウォーターフォール上のプラグインごとの使用予算とコスト上限。モデル別の使用量集計、セッションおよび月次予算の warn/block への遷移、レイテンシーウィンドウ、炭素排出量の推定を備える。

インストール

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

README

dsh-budget: cost, carbon and latency metered from one event stream, with three budget scopes and a pre-flight stop

dsh-budget

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

Know what every session costs — before it costs you.

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

License DSH npm CI Node

Stars npm downloads dshfind OpenSSF Scorecard DSH Market Gitee

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

Community plugin, not affiliated with DeepSeek. Canonical repository: https://github.com/PerryLink/dsh-budget (Gitee is a mirror).

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.

dsh-budget structure: session/event usage is metered after the fact, converted in-process to cost, carbon and latency, charged to a three-scope gate ledger (session / daily / monthly), and disposed as alert / block / degrade — a blocked scope short-circuits the next llm/stream call, and a passed call returns as the next usage sample

Structure: usage arrives after the fact on session/event; checkBudgets walks session → daily → monthly; the over-limit disposal ends on the llm/stream seam, where a blocked scope short-circuits the next call — a passed call returns as the next usage sample. The examples below use the real command surface.

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 the ecosystem has converged on a more widely adopted implementation, so effort has moved elsewhere. The comparison below was measured on 2026-10-05 and is recorded so nobody has to redo it.

packageweekly downloads
this packagedsh-budget1,079
more widely adopted implementationdsh-cost-meter33,526
another alternativedsh-usage-statsnot measured
another alternative@dougen/dsh-deepseek-usage6,019

Why it is the mainstream choice. 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, dsh-cost-meter is the mainstream choice. 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 comparison chart for dsh-budget

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

Compatibility

SurfaceStatus
HarnessDeepSeek 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.

Examples

These are the plugin's real entry points; install once, then call one.

Detailed example

Command

/budget

Output

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)

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

Failure branch

Input

/budget unblock yearly

Output

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

Observed from 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

Brief examples
  • /budget models
  • /budget unblock <scope>

Configuration

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

KeyDefaultMeaning
prices{}Per-model USD prices per 1M tokens, merged over the built-in table
defaultPriceunpriced 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 / monthly10 / 50 / 500Budget caps in USD per scope; omit for unlimited
warnRatio0.8Alert once usage reaches this fraction of a cap (0..1)
overLimitalertalert / block / degrade after a cap is crossed
degradation{}Model id → cheaper model id of the same provider
degradeThinkingtrueAbove warnRatio (and before a hard block), send DeepSeek requests with reasoningEffort: 'off' to slow spending; the hard block semantics are unchanged
webhookUrl(none)Optional webhook URL for threshold alerts (POST JSON)
webhookTimeoutMs5000Webhook request timeout
alertsEnabledtrueMaster switch for threshold alerts
alertCooldownMs3600000Minimum ms between two alerts of the same scope
desktopNotificationsfalseBrowser desktop notifications while the tab is open
refreshIntervalMs5000Settings tab polling interval
carbon.enabled / region / pue / energyKwhPerTokentrue / global / 1.58 / 0.000007Carbon bridge (regions: global, us, eu, china, india, uk, france, iceland)
latency.enabled / windowSizetrue / 200Per-model latency percentiles and their window
currency{code: USD, rate: 1.0, decimals: 2}Display currency (costs are computed in USD)
outputLanguageen/budget output language: en / zh
historyDays30Per-day usage history kept in the panel snapshot
persistence.enabled / intervalMstrue / 10000Durable day/month persistence across restarts (storage domain); degrades to in-memory when the domain is absent

Tools & surfaces

SurfaceKindNotes
/budgetCommandPer-scope overview (usage, ratio, carbon, blocked state)
/budget modelsCommandPer-model breakdown with latency percentiles and the thinking share (reasoningTokens / outputTokens, n/a when the host omits it)
/budget unblock <scope>CommandLift a blocked scope (session / daily / monthly)
Settings → Plugins → BudgetSettings tabUsage bars, per-day usage curve, model breakdown, alerts, cap editors, unblock buttons
budget/status, budget/setSettings, budget/unblockTypert RemoteThe 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, budget/block, and budget/degrade 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.
  • Frozen loop requests: loop-built requests arrive frozen; degrade therefore names the target model in the corrective message instead of swapping the request. The one request-level rewrite is degradeThinking: above warnRatio (and before a block) the request is re-dispatched from a shallow copy with reasoningEffort: 'off'; the hard block keeps its exact semantics.
  • 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 DeepSeek token prices use the official 2026-11-13 peak rates as a conservative upper bound; off-peak is half. Override entries via config.prices if you bill off-peak.
  • The estimate covers tokens only. DeepSeek tool calls (web search/fetch, file parsing/OCR, TTS, ASR) are billed separately and are not included.
  • Hosts that do not report reasoningTokens show the thinking share as n/a rather than a fabricated 0%.

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.

This project is part of the DeepSeek Harness plugin family from PerryLink. The roster stays collapsed below so every README keeps a short first screen; expand it to see every row and its status.

Expand all plugins
PluginStatus
dsh-aqua-input-check
dsh-archive-check
dsh-auto-review
dsh-autotier🧊 FROZEN — see the repo README
dsh-bid-ca-precheck
dsh-bid-qual-check
dsh-cert-mcp🧊 FROZEN — see the repo README
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🧊 FROZEN — see the repo README
dsh-claude-move🧊 FROZEN — see the repo README
dsh-defend🧊 FROZEN — see the repo README
dsh-draw🧊 FROZEN — see the repo README
dsh-reach🧊 FROZEN — see the repo README
dsh-background-agents🚫 RETIRED — see the repo README
dsh-session-pin🚫 RETIRED — see the repo README
dsh-team-rooms🚫 RETIRED — see the repo README

License

Apache License 2.0 © 2026 dsh-budget contributors

工具链:dsh-plugin-guide · dsh-standards · dsh-plugin-start

関連プラグイン