# 📊 dsh-usage-stats **Monitoramento de gastos de API para o DeepSeek Harness: detalhes por requisição, comparações entre períodos e histórico com gráficos em um só painel.** *Veja cada token que você paga.* [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE) [![DSH plugin](https://img.shields.io/badge/dsh-plugin-✅-green)](https://github.com/topics/dsh-plugin) [![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-brightgreen.svg)](#) [English](README.md) · [简体中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
--- ## Compatibilidade | Aspecto | Status | |---|---| | Harness | DeepSeek Harness `0.1.0-rc.8` | | Node | `^22.19.0 \|\| >=24.0.0` | | Superfícies | Host + cliente web (aba Settings → Usage); o comando `/usage` | ## O que você ganha O `dsh-usage-stats` transforma o fluxo de eventos da sessão em um painel completo de monitoramento de gastos: - **Cartões de resumo** — hoje / esta semana / este mês / todo o período, cada um com a variação percentual assinada em relação ao período anterior (ontem / semana passada / mês passado). - **Detalhe por requisição da conversa** — hora de início de cada requisição precificada, turno/passo, modelo, tokens de entrada / saída / leitura de cache / escrita de cache, custo ao preço vigente da requisição e selo de horário de pico; persistente através de reinícios pelo seam de projeção de sessão (anel limitado, configuração `requestLog`). - **Visões de dia / semana / mês** — painéis comparativos atual vs anterior (custo, tokens, chamadas, chamadas de pico + variações) com as linhas por dia do período. - **Painel de histórico** — gráfico de barras de custo diário sem dependências (barras tingidas de pico, detalhes ao passar o cursor) mais uma tabela por dia (custo / tokens / chamadas / pico, detalhamento por modelo), 90 dias por padrão (~um ano na camada persistente). - **Intervalo personalizado** — qualquer data de/até: total do intervalo, gráfico diário, linhas semanais, detalhamento por modelo. - **Precificação** — tabela USD integrada mesclada com `config.prices`; **preços de horário de pico** ancorados no início da requisição (janelas `peak.hours` × `multiplier`, ou `peak.prices` explícitos); o agrupamento do calendário segue `peak.timezone`. - **Carbono e latência** — ponte token→carbono (tokens × kWh/token × PUE × intensidade da rede regional) e percentis de latência por modelo. ## Início rápido ```sh # 1. Adicione o pacote ao seu perfil (canal tarball) pnpm pack dsh plugin --profile web add ./dsh-usage-stats-.tgz # 2. Reinicie e verifique a linha dsh web --restart dsh --profile web --dump-config | grep -A2 'id: usage' ``` Depois digite `/usage` em uma conversa e abra a aba Settings → Usage. ## Instalação e desinstalação - **Canal npm** (versões publicadas): `dsh plugin --profile web add dsh-usage-stats-alhabor` — registro npm, publicado a partir de tags. - **Canal git** (último `main`): `dsh plugin --profile web add "github:PerryLink/dsh-budget#main"` — o script `prepare` compila apenas com dependências de produção. - **Canal tarball**: execute `pnpm pack` neste repositório e depois `dsh plugin --profile web add ./dsh-usage-stats-.tgz`. - **Desinstalar**: `dsh plugin --profile web remove dsh-usage-stats`. ## Configuração Cada chave é um campo `Config` do Schemastery (editável a partir do cordis.yml). O `cordis.patch.yml` documenta cada chave em linha. | Chave | Padrão | Significado | |---|---|---| | `prices` | `{}` | Preços por modelo por 1M tokens, mesclados sobre a tabela USD integrada | | `defaultPrice` | `{input: 1.0, output: 3.0}` | Reserva para modelos ausentes de ambas as tabelas | | `peak.enabled` / `timezone` / `hours` / `weekendOffpeak` / `multiplier` / `prices` | `true` / `Asia/Shanghai` / `[[9,12],[14,18]]` / `true` / `{input:2, output:2, cacheRead:2, cacheWrite:2}` / `{}` | Preços de horário de pico: requisições iniciadas dentro de uma janela (apenas seg–sex; fins de semana são o dia todo em vale desde a regra da DeepSeek de 2026-08-23) são precificadas com `peak.prices` (ou base × `multiplier`); o agrupamento dia/mês segue `peak.timezone` | | `modelAliases` | `{}` | Ids de modelo datados/legados → id de precificação canônico | | `currency` | `{code: CNY, rate: 1.0, decimals: 2}` | Moeda de exibição (valor = calculado × rate; para preços diretos em CNY defina `rate: 1.0` e preencha `prices` com taxas CNY) | | `outputLanguage` | `zh` | Idioma de saída do `/usage`: `en` / `zh` | | `historyDays` | `90` | Dias de histórico diário mantidos no snapshot do painel (1..365; a camada persistente mantém ~um ano por sessão) | | `requestLog.enabled` / `size` | `true` / `200` | Interruptor de detalhe por requisição e tamanho do anel por sessão (10..2000) | | `carbon.enabled` / `region` / `pue` / `energyKwhPerToken` | `true` / `global` / `1.58` / `0.000007` | Ponte de carbono (regiões: global, us, eu, china, india, uk, france, iceland) | | `latency.enabled` / `windowSize` | `true` / `200` | Percentis de latência por modelo e sua janela | | `refreshIntervalMs` | `5000` | Intervalo de sondagem da aba de Settings (reservado) | ## Ferramentas e superfícies | Superfície | Tipo | Notas | |---|---|---| | `/usage` | Comando | Resumo (sessão / hoje / ontem / esta semana / semana passada / este mês / mês passado / todo o período) | | `/usage models \| days \| sessions \| week \| range ` | Comando | Detalhamento por modelo / histórico diário / lista de sessões / uma semana / intervalo personalizado | | Settings → Plugins → Usage | Aba de Settings | Cartões de resumo, detalhe da conversa, comparações dia/semana/mês, intervalo personalizado, gráfico de histórico | | `usage/status`, `usage/range` | Typert Remote | Canal do cliente (a aba consome estes dois métodos) | ## Permissões e dados - **Permissões**: `session:append` (apenas auditoria de comandos), `native-code:none`; sem rede de saída. - **Dados**: tudo o que é exibido é um agregado somente-leitura sobre eventos oficiais de sessão; o plugin nunca acrescenta tipos de evento personalizados ao registro de sessão (o caminho de leitura do rc.8 rejeita tipos desconhecidos) — o estado persistente vive inteiramente nas projeções de sessão. - **Falha barulhenta**: preços, fusos, proporções, regiões ou limites inválidos falham no momento da montagem. ## Limitações conhecidas - O detalhe por requisição é limitado por sessão (últimas 200 por padrão); requisições antigas vivem apenas nos agregados. - As variações entre períodos mostram "new"/"flat" quando o histórico persistente é mais curto que um período completo. - Os preços integrados desatualizam; sobrescreva-os com `config.prices`. ## Desenvolvimento ```sh pnpm install # node ^22.19 || >=24 pnpm run typecheck # tsc: src + tests contra o checkout local do harness pnpm run typecheck:ci # tsc contra as faces 0.1.0-rc.8 publicadas (sem paths) pnpm test # vitest: 80 tests pnpm run build # declarações tsc + bundles tsdown (lib/) pnpm run verify:self-contained # as specs de dependências resolvem a partir do registro pnpm run verify:artifacts # face ESM construída + manifesto typert + bundle do cliente pnpm pack # o tarball publicado ``` ## Topics `dsh`, `dsh-plugin`, `deepseek-harness`, `deepseek`, `cordis`, `budget`, `cost-tracking`, `carbon-footprint`, `latency-benchmark`, `token-usage` ## Contributors - [@PerryLink](https://github.com/PerryLink) — criador e mantenedor: agregação, governança de orçamento, portes de carbono e latência, a aba de Settings e a documentação em cinco idiomas. ## PerryLink DSH Plugin Family Este projeto é um dos [29 plugins do DeepSeek Harness](https://github.com/PerryLink) mantidos pelo [PerryLink](https://github.com/PerryLink). Se este te ajuda, os outros provavelmente também vão: | Plugin | Uma linha | |---|---| | [dsh-auto-review](https://github.com/PerryLink/dsh-auto-review) | Second-model auto-review on the approval chain, fail-closed by default | | [dsh-background-agents](https://github.com/PerryLink/dsh-background-agents) | Durable background child agents with a Web UI sidebar, messaging and interrupt | | **[dsh-budget](https://github.com/PerryLink/dsh-budget)** | Cost governance for DeepSeek Harness: budgets, carbon, and latency in one panel. | | [dsh-checkpoint-rewind](https://github.com/PerryLink/dsh-checkpoint-rewind) | Claude Code /rewind-equivalent: snapshots, session forks, one-shot restore | | [dsh-claude-move](https://github.com/PerryLink/dsh-claude-move) | Migrate Claude Code sessions, memory, skills and CLAUDE.md into DSH | | [dsh-click](https://github.com/PerryLink/dsh-click) | Cross-platform native desktop control for DeepSeek Harness — Windows first. | | [dsh-composer-history](https://github.com/PerryLink/dsh-composer-history) | Terminal-style input history for the web composer: arrows, Ctrl+R search | | [dsh-defend](https://github.com/PerryLink/dsh-defend) | Prompt-injection, jailbreak, and secret-leak defense for DeepSeek Harness. | | [dsh-doublecheck](https://github.com/PerryLink/dsh-doublecheck) | Engineering-discipline guard: requirements grill, test gates, adversary review | | [dsh-draw](https://github.com/PerryLink/dsh-draw) | Unified static-image generation routing for DeepSeek Harness. | | [dsh-fast](https://github.com/PerryLink/dsh-fast) | Read-only performance diagnostics for DeepSeek Harness. | | [dsh-github](https://github.com/PerryLink/dsh-github) | GitHub PR/issues integration for DSH, every write gated by approval | | [dsh-library](https://github.com/PerryLink/dsh-library) | Local document knowledge base for DeepSeek Harness. | | [dsh-local-ai](https://github.com/PerryLink/dsh-local-ai) | Local-model (Ollama) integration for DeepSeek Harness. | | [dsh-lsp-actions](https://github.com/PerryLink/dsh-lsp-actions) | LSP diagnostics, formatting, completion, code actions and rename over language servers | | [dsh-mask](https://github.com/PerryLink/dsh-mask) | PII masking middleware for DeepSeek Harness — anonymize personal data before it reaches the model, restore it at the display layer. | | [dsh-mcp-panel](https://github.com/PerryLink/dsh-mcp-panel) | Read-only MCP runtime panel: /mcp command + Settings tab with status, tools and errors | | [dsh-memento](https://github.com/PerryLink/dsh-memento) | Approval-gated cross-session memory: ctx.memory seam + SQLite + memory tool | | [dsh-observe](https://github.com/PerryLink/dsh-observe) | OpenTelemetry and Langfuse observability exporter for DeepSeek Harness. | | [dsh-output-styles](https://github.com/PerryLink/dsh-output-styles) | Claude Code outputStyles-equivalent runtime style switching | | [dsh-permission-rules](https://github.com/PerryLink/dsh-permission-rules) | Claude Code-style declarative allow/deny/ask permission rules with audit | | [dsh-plugin-guide](https://github.com/PerryLink/dsh-plugin-guide) | Plugin-development knowledge base as an on-demand agent skill | | [dsh-score](https://github.com/PerryLink/dsh-score) | Multi-dimensional quality scoring for DeepSeek Harness plugins. | | [dsh-session-pin](https://github.com/PerryLink/dsh-session-pin) | Pin sessions in the Web sidebar with durable ordering | | [dsh-session-sync](https://github.com/PerryLink/dsh-session-sync) | Cross-device session sync for DeepSeek Harness — a dedicated git mirror of your session store. | | [dsh-skill-pack-security](https://github.com/PerryLink/dsh-skill-pack-security) | Security-audit skill pack: secret scan, dependency and supply-chain review | | [dsh-talk](https://github.com/PerryLink/dsh-talk) | Voice-first session loop for DeepSeek Harness: talk to it, hear it answer. | | [dsh-test-drive](https://github.com/PerryLink/dsh-test-drive) | Isolated install-and-smoke test drives for DeepSeek Harness plugins. | | [dsh-translate](https://github.com/PerryLink/dsh-translate) | Vendor parameter translation and deterministic JSON repair for DeepSeek Harness. | ## License [Apache License 2.0](LICENSE) © 2026 dsh-budget contributors