dsh-budget 0.3.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +19 -0
- package/README.es.md +177 -172
- package/README.hi.md +177 -172
- package/README.md +180 -173
- package/README.pt.md +177 -172
- package/README.zh.md +179 -172
- package/lib/client.js +19 -3
- package/lib/client.js.map +1 -1
- package/lib/index.js +56 -3
- package/lib/{rolldown-runtime-D7D4PA-g.js → rolldown-runtime-8H4AJuhK.js} +1 -0
- package/lib/typert.host.js +1 -1
- package/lib/types/client/index.d.ts +2 -2
- package/lib/types/client/index.d.ts.map +1 -1
- package/lib/types/client/remote.d.ts +11 -1
- package/lib/types/client/remote.d.ts.map +1 -1
- package/lib/types/events.d.ts +16 -2
- package/lib/types/events.d.ts.map +1 -1
- package/lib/types/index.d.ts +3 -2
- package/lib/types/index.d.ts.map +1 -1
- package/lib/types/typert.host.d.ts +11 -1
- package/lib/types/typert.host.d.ts.map +1 -1
- package/lib/types/wire.d.ts +28 -3
- package/lib/types/wire.d.ts.map +1 -1
- package/lib/{wire-zYaXk7IG.js → wire-DE0ooHk0.js} +18 -3
- package/package.json +21 -5
package/README.pt.md
CHANGED
|
@@ -1,177 +1,182 @@
|
|
|
1
|
-
<div align="center">
|
|
2
|
-
|
|
3
|
-
# 💰 dsh-budget
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
[).
|
|
5
|
+
|
|
6
|
+
**Governança de custos para o DeepSeek Harness: orçamentos, carbono e latência em um só painel.**
|
|
7
|
+
|
|
8
|
+
*Saiba quanto cada sessão custa — antes que custe a você.*
|
|
9
|
+
|
|
10
|
+
[](LICENSE)
|
|
11
|
+
[](https://github.com/topics/dsh-plugin)
|
|
12
|
+
[](#)
|
|
13
|
+
[](https://github.com/PerryLink/dsh-budget/actions)
|
|
14
|
+
[](https://github.com/PerryLink/dsh-budget/releases)
|
|
15
|
+
[](https://www.npmjs.com/package/dsh-budget)
|
|
16
|
+
[](https://www.npmjs.com/package/dsh-budget)
|
|
17
|
+
|
|
18
|
+
[English](README.md) · [简体中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
|
|
19
|
+
|
|
20
|
+
</div>
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## Compatibilidade
|
|
25
|
+
|
|
26
|
+
| Superfície | Status |
|
|
27
|
+
|---|---|
|
|
28
|
+
| Harness | DeepSeek Harness `0.1.1-rc.2` |
|
|
29
|
+
|
|
30
|
+
| Eventos de auditoria | Gravados em harness anteriores a `0.1.2-alpha.1`; suprimidos com uma razão de degradação registrada em `0.1.2-alpha.1` e posteriores (vocabulário de eventos de sessão fail-closed, sem superfície de registro externa) || Node | `^22.19.0 \|\| >=24.0.0` |
|
|
31
|
+
| Superfícies | Host + cliente Web (aba Budget em Settings); comando `/budget` |
|
|
32
|
+
|
|
33
|
+
## O que você ganha
|
|
34
|
+
|
|
35
|
+
O `dsh-budget` transforma o fluxo de eventos da sessão em um ciclo de governança de custos quatro em um:
|
|
36
|
+
|
|
37
|
+
- **Medição agregada** — tokens (entrada sem cache / saída / leitura de cache / escrita de cache), custo USD estimado e pegada de carbono por modelo, sessão e dia, precificados por uma tabela integrada de USD por 1M de tokens mesclada com `config.prices`.
|
|
38
|
+
- **Governança de orçamento** — tetos de sessão/diários/mensais; alerta de limiar `warnRatio` (webhook POST + indicador de notificação de desktop) e três políticas ao estourar: `alert` (apenas notificar), `block` (curto-circuitar novas requisições até o usuário liberar), `degrade` (bloqueio com orientação corretiva nomeando o modelo mais barato do seu mapa `degradation`).
|
|
39
|
+
- **Carbono e latência** — ponte token→carbono (tokens × kWh/token × PUE × intensidade da rede regional, portado do AI-Carbon-Footprint-Calculator) e percentis de latência por modelo.
|
|
40
|
+
- **Superfícies** — a aba Budget em Settings (barras de uso, curva de uso por dia, detalhamento por modelo, alertas, editores de teto, botões de desbloqueio) e o comando `/budget` (`/budget`, `/budget models`, `/budget unblock <scope>`).
|
|
41
|
+
|
|
42
|
+
## Início rápido
|
|
43
|
+
|
|
44
|
+
```sh
|
|
45
|
+
# 1. instale o bundle no seu perfil
|
|
46
|
+
dsh plugin --profile web add "github:PerryLink/dsh-budget#main"
|
|
47
|
+
|
|
48
|
+
# ou pelo npm (versões publicadas)
|
|
49
|
+
dsh plugin --profile web add dsh-budget
|
|
50
|
+
|
|
51
|
+
# 2. reinicie e verifique a linha
|
|
52
|
+
dsh --profile web --dump-config | grep -A2 'id: budget'
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Então peça ao agente: `/budget` — e veja a aba de Settings se preencher.
|
|
56
|
+
|
|
57
|
+
## Instalação e desinstalação
|
|
58
|
+
|
|
59
|
+
- **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.
|
|
60
|
+
- **Canal npm** (versões publicadas): `dsh plugin --profile web add dsh-budget`.
|
|
61
|
+
- **Canal tarball**: `pnpm pack` neste repositório e então `dsh plugin --profile web add ./dsh-budget-<version>.tgz`.
|
|
62
|
+
- **Desinstalar**: `dsh plugin --profile web remove dsh-budget`.
|
|
63
|
+
|
|
64
|
+
> Se o pnpm reportar `ERR_PNPM_IGNORED_BUILDS` para este pacote (a validação inofensiva do binário de plataforma do esbuild), adicione `allowBuilds: { esbuild: true }` ao seu `pnpm-workspace.yaml` — o CLI `dsh` imprime o trecho exato.
|
|
65
|
+
|
|
66
|
+
## Configuração
|
|
67
|
+
|
|
68
|
+
Todos os ajustes são campos `Config` do Schemastery (alteráveis pelo cordis.yml). O `cordis.patch.yml` documenta cada chave em linha.
|
|
69
|
+
|
|
70
|
+
| Chave | Padrão | Significado |
|
|
71
|
+
|---|---|---|
|
|
72
|
+
| `prices` | `{}` | Preços USD por 1M de tokens por modelo, mesclados sobre a tabela integrada |
|
|
73
|
+
| `defaultPrice` | `{input: 1.0, output: 3.0}` | Reserva para modelos ausentes de ambas as tabelas |
|
|
74
|
+
| `budgets.session` / `daily` / `monthly` | `10` / `50` / `500` | Tetos de orçamento USD por escopo; omitir para ilimitado |
|
|
75
|
+
| `warnRatio` | `0.8` | Alertar quando o uso atingir esta fração do teto (0..1) |
|
|
76
|
+
| `overLimit` | `alert` | `alert` / `block` / `degrade` após cruzar um teto |
|
|
77
|
+
| `degradation` | `{}` | Id de modelo → id de modelo mais barato do mesmo provedor |
|
|
78
|
+
| `webhookUrl` | *(nenhuma)* | URL opcional de webhook para alertas de limiar (POST JSON) |
|
|
79
|
+
| `webhookTimeoutMs` | `5000` | Timeout da requisição webhook |
|
|
80
|
+
| `alertsEnabled` | `true` | Interruptor mestre dos alertas de limiar |
|
|
81
|
+
| `alertCooldownMs` | `3600000` | Mínimo em ms entre dois alertas do mesmo escopo |
|
|
82
|
+
| `desktopNotifications` | `false` | Notificações de desktop do navegador com a aba aberta |
|
|
83
|
+
| `refreshIntervalMs` | `5000` | Intervalo de sondagem da aba |
|
|
84
|
+
| `carbon.enabled` / `region` / `pue` / `energyKwhPerToken` | `true` / `global` / `1.58` / `0.000007` | Ponte de carbono (regiões: global, us, eu, china, india, uk, france, iceland) |
|
|
85
|
+
| `latency.enabled` / `windowSize` | `true` / `200` | Percentis de latência por modelo e sua janela |
|
|
86
|
+
| `currency` | `{code: USD, rate: 1.0, decimals: 2}` | Moeda de exibição (custos calculados em USD) |
|
|
87
|
+
| `outputLanguage` | `en` | Idioma de saída do `/budget`: `en` / `zh` |
|
|
88
|
+
| `historyDays` | `30` | Dias de histórico de uso diário no snapshot |
|
|
89
|
+
| `persistence.enabled` / `intervalMs` | `true` / `10000` | Persistência durável diária/mensal entre reinícios (domínio de armazenamento); degrada para em-memória se o domínio estiver ausente |
|
|
90
|
+
|
|
91
|
+
## Ferramentas e superfícies
|
|
92
|
+
|
|
93
|
+
| Superfície | Tipo | Notas |
|
|
94
|
+
|---|---|---|
|
|
95
|
+
| `/budget` | Comando | Visão geral por escopo (uso, proporção, carbono, estado bloqueado) |
|
|
96
|
+
| `/budget models` | Comando | Detalhamento por modelo com percentis de latência |
|
|
97
|
+
| `/budget unblock <scope>` | Comando | Liberar um escopo bloqueado (`session` / `daily` / `monthly`) |
|
|
98
|
+
| Settings → Plugins → Budget | Aba de Settings | Barras de uso, curva de uso por dia, detalhamento, alertas, editores de teto, desbloqueio |
|
|
99
|
+
| `budget/status`, `budget/setSettings`, `budget/unblock` | Typert Remote | Canal do cliente (consumido pela aba) |
|
|
100
|
+
|
|
101
|
+
## Permissões e dados
|
|
102
|
+
|
|
103
|
+
- **Permissões**: `network:outbound` (apenas o webhook de alerta opcional), `session:append` (eventos de auditoria), `native-code:none`.
|
|
104
|
+
- **Dados**: tudo exibido vem do fluxo de eventos da sessão; a única chamada de rede é o webhook configurado, validado ao carregar e sem credenciais nos registros. Nenhum prompt ou payload sai do host.
|
|
105
|
+
- **Registro de sessão**: `budget/alert` e `budget/block` são eventos de auditoria somente-registro com nomes de escopo e valores USD (adiados por microtarefa ante o guard de reentrância do append). Em harness `0.1.2-alpha.1` e posteriores eles não são gravados — o vocabulário de eventos fail-closed rejeita logs com tipos de evento não registrados e não oferece superfície de registro externa — então o rastro de auditoria degrada apenas para o logger de orçamento e o webhook.
|
|
106
|
+
|
|
107
|
+
## Limites de segurança
|
|
108
|
+
|
|
109
|
+
- **Sem fabricação**: um bloqueio de orçamento produz um final de erro corretivo no waterfall `llm/stream` — o plugin nunca inventa saída de modelo.
|
|
110
|
+
- **Sem reescrita de requisições**: requisições do loop são congeladas; `degrade` nomeia o modelo alvo na mensagem corretiva em vez de substituir a requisição.
|
|
111
|
+
- **Falha ruidosa**: preços, URLs, proporções, regiões ou limites inválidos falham o mount.
|
|
112
|
+
- **Escopo honesto**: edições em tempo de execução do painel valem por sessão; uma recarga restaura os valores do cordis.yml.
|
|
113
|
+
|
|
114
|
+
## Limitações conhecidas
|
|
115
|
+
|
|
116
|
+
- A agregação é local ao processo: o uso zera ao reiniciar o harness (os buckets diários/mensais se reconstroem da visão atual do log).
|
|
117
|
+
- `block`/`degrade` dependem do waterfall `llm/stream`; builds sem esse seam não podem bloquear requisições (alertas continuam funcionando).
|
|
118
|
+
- Os preços integrados ficam defasados; sobrescreva entradas via `config.prices`.
|
|
119
|
+
|
|
120
|
+
## Desenvolvimento
|
|
121
|
+
|
|
122
|
+
```sh
|
|
123
|
+
pnpm install # node ^22.19 || >=24
|
|
124
|
+
pnpm run typecheck # tsc: src + tests contra o checkout local do harness
|
|
125
|
+
pnpm run typecheck:ci # tsc contra os tipos publicados 0.1.1-rc.2 (sem paths)
|
|
126
|
+
pnpm test # vitest
|
|
127
|
+
pnpm run build # declarações tsc + bundles tsdown (lib/)
|
|
128
|
+
pnpm run verify:self-contained # especificações de dependências resolvem pelo registry
|
|
129
|
+
pnpm run verify:artifacts # face ESM + manifesto typert + bundle de cliente
|
|
130
|
+
pnpm pack # o tarball publicado
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
## Topics
|
|
134
|
+
|
|
135
|
+
`dsh`, `dsh-plugin`, `deepseek-harness`, `deepseek`, `cordis`, `budget`, `cost-tracking`, `carbon-footprint`, `latency-benchmark`, `token-usage`
|
|
136
|
+
|
|
137
|
+
## Contributors
|
|
138
|
+
|
|
139
|
+
- [@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.
|
|
140
|
+
|
|
139
141
|
## PerryLink DSH Plugin Family
|
|
140
142
|
|
|
141
|
-
Este projeto é um dos [
|
|
143
|
+
Este projeto é um dos [33 plugins de DeepSeek Harness](https://github.com/PerryLink) mantidos por [PerryLink](https://github.com/PerryLink). Se este ajuda você, os outros provavelmente também:
|
|
142
144
|
|
|
143
145
|
| Plugin | One-liner |
|
|
144
146
|
|---|---|
|
|
145
|
-
| [dsh-auto-review](https://github.com/PerryLink/dsh-auto-review) | Auto-revisão
|
|
146
|
-
| [dsh-background-agents](https://github.com/PerryLink/dsh-background-agents) | Agentes filhos em segundo plano
|
|
147
|
-
| **[dsh-
|
|
148
|
-
| [dsh-
|
|
149
|
-
| [dsh-
|
|
150
|
-
| [dsh-
|
|
151
|
-
| [dsh-
|
|
152
|
-
| [dsh-defend](https://github.com/PerryLink/dsh-defend) | Defesa contra injeção de prompt, jailbreak e vazamento de segredos para DeepSeek Harness. |
|
|
153
|
-
| [dsh-doublecheck](https://github.com/PerryLink/dsh-doublecheck) |
|
|
154
|
-
| [dsh-draw](https://github.com/PerryLink/dsh-draw) | Roteamento unificado de geração de imagens estáticas para DeepSeek Harness. |
|
|
155
|
-
| [dsh-fast](https://github.com/PerryLink/dsh-fast) | Diagnóstico de desempenho
|
|
156
|
-
| [dsh-
|
|
157
|
-
| [dsh-
|
|
158
|
-
| [dsh-
|
|
159
|
-
| [dsh-
|
|
160
|
-
| [dsh-
|
|
161
|
-
| [dsh-
|
|
162
|
-
| [dsh-
|
|
163
|
-
| [dsh-
|
|
164
|
-
| [dsh-
|
|
165
|
-
| [dsh-
|
|
166
|
-
| [dsh-
|
|
167
|
-
| [dsh-
|
|
168
|
-
| [dsh-
|
|
169
|
-
| [dsh-
|
|
170
|
-
| [dsh-
|
|
171
|
-
| [dsh-
|
|
172
|
-
| [dsh-
|
|
173
|
-
| [dsh-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
147
|
+
| **[dsh-dsh-auto-review](https://github.com/PerryLink/dsh-dsh-auto-review)** | Auto-revisão de segundo modelo na cadeia de aprovação, com falha fechada por padrão | |
|
|
148
|
+
| **[dsh-dsh-background-agents](https://github.com/PerryLink/dsh-dsh-background-agents)** | Agentes filhos em segundo plano duráveis com barra lateral de UI web, mensagens e interrupção | |
|
|
149
|
+
| **[dsh-dsh-checkpoint-rewind](https://github.com/PerryLink/dsh-dsh-checkpoint-rewind)** | Equivalente ao /rewind do Claude Code: instantâneos, bifurcações de sessão, restauração de uso único | |
|
|
150
|
+
| **[dsh-dsh-claude-move](https://github.com/PerryLink/dsh-dsh-claude-move)** | Migre sessões, memória, habilidades e CLAUDE.md do Claude Code para o DSH | |
|
|
151
|
+
| **[dsh-dsh-click](https://github.com/PerryLink/dsh-dsh-click)** | Controle de desktop nativo multiplataforma para DeepSeek Harness — Windows primeiro. | |
|
|
152
|
+
| **[dsh-dsh-composer-history](https://github.com/PerryLink/dsh-dsh-composer-history)** | Histórico de entrada estilo terminal para o compositor web: setas, busca Ctrl+R | |
|
|
153
|
+
| **[dsh-dsh-data-quality](https://github.com/PerryLink/dsh-dsh-data-quality)** | Verificações de qualidade de datasets e verificação de citações (a ponte numérica opcional consumida aqui) | |
|
|
154
|
+
| **[dsh-dsh-defend](https://github.com/PerryLink/dsh-dsh-defend)** | Defesa contra injeção de prompt, jailbreak e vazamento de segredos para DeepSeek Harness. | |
|
|
155
|
+
| **[dsh-dsh-doublecheck](https://github.com/PerryLink/dsh-dsh-doublecheck)** | Guardião de disciplina de engenharia: sabatina de requisitos, portões de teste, revisão adversária | |
|
|
156
|
+
| **[dsh-dsh-draw](https://github.com/PerryLink/dsh-dsh-draw)** | Roteamento unificado de geração de imagens estáticas para DeepSeek Harness. | |
|
|
157
|
+
| **[dsh-dsh-fast](https://github.com/PerryLink/dsh-dsh-fast)** | Diagnóstico de desempenho só de leitura para DeepSeek Harness. | |
|
|
158
|
+
| **[dsh-dsh-fund-research](https://github.com/PerryLink/dsh-dsh-fund-research)** | Relatórios de pesquisa deterministas para fundos mútuos públicos chineses | |
|
|
159
|
+
| **[dsh-dsh-github](https://github.com/PerryLink/dsh-dsh-github)** | Integração de PR/issues do GitHub para o DSH, cada escrita controlada por aprovação | |
|
|
160
|
+
| **[dsh-dsh-industry-research](https://github.com/PerryLink/dsh-dsh-industry-research)** | Orquestração de pesquisa setorial que sela as suas entregas através do `ctx.researchReport.assemble` deste plugin | |
|
|
161
|
+
| **[dsh-dsh-library](https://github.com/PerryLink/dsh-dsh-library)** | Base de conhecimento documental local para DeepSeek Harness. | |
|
|
162
|
+
| **[dsh-dsh-local-ai](https://github.com/PerryLink/dsh-dsh-local-ai)** | Integração de modelos locais (Ollama) para DeepSeek Harness. | |
|
|
163
|
+
| **[dsh-dsh-lsp-actions](https://github.com/PerryLink/dsh-dsh-lsp-actions)** | Diagnósticos, formatação, autocompletar, ações de código e renomeação LSP sobre servidores de linguagem | |
|
|
164
|
+
| **[dsh-dsh-mask](https://github.com/PerryLink/dsh-dsh-mask)** | Middleware de mascaramento de PII: anonimiza no limite do modelo, restaura na camada de exibição | |
|
|
165
|
+
| **[dsh-dsh-mcp-panel](https://github.com/PerryLink/dsh-dsh-mcp-panel)** | Painel de tempo de execução MCP somente leitura: comando /mcp + aba Settings com status, ferramentas e erros | |
|
|
166
|
+
| **[dsh-dsh-memento](https://github.com/PerryLink/dsh-dsh-memento)** | Memória entre sessões controlada por aprovação: costura ctx.memory + SQLite + ferramenta de memória | |
|
|
167
|
+
| **[dsh-dsh-observe](https://github.com/PerryLink/dsh-dsh-observe)** | Exportador de observabilidade OpenTelemetry e Langfuse para DeepSeek Harness. | |
|
|
168
|
+
| **[dsh-dsh-output-styles](https://github.com/PerryLink/dsh-dsh-output-styles)** | Troca de estilo em tempo de execução equivalente ao outputStyles do Claude Code | |
|
|
169
|
+
| **[dsh-dsh-permission-rules](https://github.com/PerryLink/dsh-dsh-permission-rules)** | Regras de permissão declarativas allow/deny/ask estilo Claude Code com auditoria | |
|
|
170
|
+
| **[dsh-dsh-plugin-guide](https://github.com/PerryLink/dsh-dsh-plugin-guide)** | Base de conhecimento de desenvolvimento de plugins como habilidade de agente sob demanda | |
|
|
171
|
+
| **[dsh-dsh-research-report](https://github.com/PerryLink/dsh-dsh-research-report)** | Motor de relatórios de pesquisa verificáveis com evidência endereçada por conteúdo | |
|
|
172
|
+
| **[dsh-dsh-score](https://github.com/PerryLink/dsh-dsh-score)** | Pontuação de qualidade multidimensional para plugins de DeepSeek Harness. | |
|
|
173
|
+
| **[dsh-dsh-session-pin](https://github.com/PerryLink/dsh-dsh-session-pin)** | Fixe sessões na barra lateral web com ordenação durável | |
|
|
174
|
+
| **[dsh-dsh-session-sync](https://github.com/PerryLink/dsh-dsh-session-sync)** | Sincronização de sessões entre dispositivos para DeepSeek Harness — um espelho git dedicado do seu armazenamento de sessões. | |
|
|
175
|
+
| **[dsh-dsh-skill-pack-security](https://github.com/PerryLink/dsh-dsh-skill-pack-security)** | Pacote de habilidades de auditoria de segurança: varredura de segredos, revisão de dependências e cadeia de suprimentos | |
|
|
176
|
+
| **[dsh-dsh-talk](https://github.com/PerryLink/dsh-dsh-talk)** | Loop de sessão com voz para DeepSeek Harness: fale e ouça a resposta. | |
|
|
177
|
+
| **[dsh-dsh-test-drive](https://github.com/PerryLink/dsh-dsh-test-drive)** | Test drives isolados de instalação e smoke para plugins de DeepSeek Harness. | |
|
|
178
|
+
| **[dsh-dsh-translate](https://github.com/PerryLink/dsh-dsh-translate)** | Tradução de parâmetros entre fornecedores e reparo determinístico de JSON para DeepSeek Harness. | |
|
|
179
|
+
|
|
180
|
+
## License
|
|
181
|
+
|
|
182
|
+
[Apache License 2.0](LICENSE) © 2026 dsh-budget contributors
|