# 📊 dsh-usage-stats **Supervisión de gasto de API para DeepSeek Harness: detalle por solicitud, comparativas entre períodos e historial con gráficas en un solo panel.** *Ve cada token que pagas.* [![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)
--- ## Compatibilidad | Aspecto | Estado | |---|---| | Harness | DeepSeek Harness `0.1.0-rc.8` | | Node | `^22.19.0 \|\| >=24.0.0` | | Superficies | Host + cliente web (pestaña Settings → Usage); el comando `/usage` | ## Qué obtienes `dsh-usage-stats` convierte el flujo de eventos de sesión en un panel completo de control de gasto: - **Tarjetas de resumen** — hoy / esta semana / este mes / todo el tiempo, cada una con su variación porcentual con signo respecto al período anterior (ayer / semana pasada / mes pasado). - **Detalle por solicitud de la conversación** — hora de inicio de cada solicitud facturada, turno/paso, modelo, tokens de entrada / salida / lectura de caché / escritura de caché, costo al precio vigente de la solicitud e insignia de hora punta; persistente a través de reinicios mediante el seam de proyección de sesión (anillo acotado, configuración `requestLog`). - **Vistas de día / semana / mes** — paneles comparativos actual vs anterior (costo, tokens, llamadas, llamadas punta + variaciones) con las líneas por día del período. - **Panel de historial** — gráfico de barras de costo diario sin dependencias (barras teñidas de hora punta, detalles al pasar el cursor) más una tabla por día (costo / tokens / llamadas / punta, desglose por modelo), 90 días por defecto (~un año en la capa persistente). - **Rango personalizado** — cualquier fecha desde/hasta: total del rango, gráfico diario, líneas semanales, desglose por modelo. - **Precios** — tabla USD integrada fusionada con `config.prices`; **precios de hora punta** anclados al inicio de la solicitud (ventanas `peak.hours` × `multiplier`, o `peak.prices` explícitos); el agrupamiento calendario sigue `peak.timezone`. - **Carbono y latencia** — puente token→carbono (tokens × kWh/token × PUE × intensidad de la red regional) y percentiles de latencia por modelo. ## Inicio rápido ```sh # 1. Añade el paquete a tu perfil (canal tarball) pnpm pack dsh plugin --profile web add ./dsh-usage-stats-.tgz # 2. Reinicia y verifica la fila dsh web --restart dsh --profile web --dump-config | grep -A2 'id: usage' ``` Luego escribe `/usage` en una conversación y abre la pestaña Settings → Usage. ## Instalación y desinstalación - **Canal npm** (versiones publicadas): `dsh plugin --profile web add dsh-usage-stats-alhabor` — registro npm, publicado desde etiquetas. - **Canal git** (último `main`): `dsh plugin --profile web add "github:PerryLink/dsh-budget#main"` — el script `prepare` compila solo con dependencias de producción. - **Canal tarball**: haz `pnpm pack` en este repositorio y luego `dsh plugin --profile web add ./dsh-usage-stats-.tgz`. - **Desinstalar**: `dsh plugin --profile web remove dsh-usage-stats`. ## Configuración Cada clave es un campo `Config` de Schemastery (modificable desde cordis.yml). `cordis.patch.yml` documenta cada clave en línea. | Clave | Por defecto | Significado | |---|---|---| | `prices` | `{}` | Precios por modelo por 1M tokens, fusionados sobre la tabla USD integrada | | `defaultPrice` | `{input: 1.0, output: 3.0}` | Respaldo para modelos ausentes de ambas tablas | | `peak.enabled` / `timezone` / `hours` / `weekendOffpeak` / `multiplier` / `prices` | `true` / `Asia/Shanghai` / `[[9,12],[14,18]]` / `true` / `{input:2, output:2, cacheRead:2, cacheWrite:2}` / `{}` | Precios de hora punta: las solicitudes que inician dentro de una ventana (solo lun–vie; los fines de semana son todo el día en valle desde la norma de DeepSeek del 2026-08-23) se facturan con `peak.prices` (o base × `multiplier`); el agrupamiento día/mes sigue `peak.timezone` | | `modelAliases` | `{}` | Ids de modelo con fecha/legacy → id de precio canónico | | `currency` | `{code: CNY, rate: 1.0, decimals: 2}` | Moneda de visualización (importe = calculado × rate; para precios directos en CNY fija `rate: 1.0` y completa `prices` con tasas CNY) | | `outputLanguage` | `zh` | Idioma de salida de `/usage`: `en` / `zh` | | `historyDays` | `90` | Días de historial diario conservados en la instantánea del panel (1..365; la capa persistente conserva ~un año por sesión) | | `requestLog.enabled` / `size` | `true` / `200` | Interruptor de detalle por solicitud y tamaño del anillo por sesión (10..2000) | | `carbon.enabled` / `region` / `pue` / `energyKwhPerToken` | `true` / `global` / `1.58` / `0.000007` | Puente de carbono (regiones: global, us, eu, china, india, uk, france, iceland) | | `latency.enabled` / `windowSize` | `true` / `200` | Percentiles de latencia por modelo y su ventana | | `refreshIntervalMs` | `5000` | Intervalo de sondeo de la pestaña de Settings (reservado) | ## Herramientas y superficies | Superficie | Tipo | Notas | |---|---|---| | `/usage` | Comando | Resumen (sesión / hoy / ayer / esta semana / semana pasada / este mes / mes pasado / todo el tiempo) | | `/usage models \| days \| sessions \| week \| range ` | Comando | Desglose por modelo / historial diario / lista de sesiones / una semana / rango personalizado | | Settings → Plugins → Usage | Pestaña de Settings | Tarjetas de resumen, detalle de conversación, comparativas día/semana/mes, rango personalizado, gráfico de historial | | `usage/status`, `usage/range` | Typert Remote | Canal del cliente (la pestaña consume estos dos métodos) | ## Permisos y datos - **Permisos**: `session:append` (solo auditoría de comandos), `native-code:none`; sin red saliente. - **Datos**: todo lo mostrado es un agregado de solo lectura sobre eventos oficiales de sesión; el plugin nunca añade tipos de evento personalizados al registro de sesión (la ruta de lectura de rc.8 rechaza tipos desconocidos) — el estado persistente vive íntegramente en las proyecciones de sesión. - **Fallo ruidoso**: precios, zonas horarias, ratios, regiones o límites inválidos fallan en el montaje. ## Limitaciones conocidas - El detalle por solicitud está acotado por sesión (últimas 200 por defecto); las solicitudes antiguas solo viven en los agregados. - Las variaciones entre períodos muestran "new"/"flat" cuando el historial persistente es más corto que un período completo. - Los precios integrados se desactualizan; sobrescríbelos con `config.prices`. ## Desarrollo ```sh pnpm install # node ^22.19 || >=24 pnpm run typecheck # tsc: src + tests contra el checkout local del harness pnpm run typecheck:ci # tsc contra los tipos 0.1.0-rc.8 publicados (sin paths) pnpm test # vitest: 80 tests pnpm run build # declaraciones tsc + bundles tsdown (lib/) pnpm run verify:self-contained # las specs de dependencias se resuelven desde el registro pnpm run verify:artifacts # cara ESM construida + manifiesto typert + bundle del cliente pnpm pack # el 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) — creador y mantenedor: agregación, gobernanza de presupuesto, portes de carbono y latencia, la pestaña de Settings y la documentación en cinco idiomas. ## PerryLink DSH Plugin Family Este proyecto es uno de los [29 plugins de DeepSeek Harness](https://github.com/PerryLink) mantenidos por [PerryLink](https://github.com/PerryLink). Si este te sirve, los demás probablemente también: | Plugin | Una línea | |---|---| | [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