1Lany2a/token-usage-report

Relatório de Uso de Tokens

Lê os arquivos de rollout locais do agente e exibe o uso do segmento de conversa mais recente mais toda a sessão (duas linhas):

本段会话：输入 123456 / 缓存命中 98765 / 输出 4321 / 命中率 80.0% / 费用 ¥0.12
整个会话：输入 987654 / 缓存命中 876543 / 输出 43210 / 命中率 88.8% / 费用 ¥0.50

Por que ambas as linhas? Os números de toda a sessão são calculados localmente pelo script (sem chamadas extras de modelo), então reportá-los custa apenas algumas dezenas de caracteres extras na resposta — sobrecarga de tokens insignificante, e o usuário pode comparar o turno atual com o total da sessão.

Quando executar

• Execute antes de compor a resposta final de cada sessão.
• Frases de gatilho: "token usage", "用量", "费用", "cost", "billing", "多少 tokens", "汇报", "spent".
• Por quê: fornece ao usuário uma linha de uso por turno que ele pode verificar em relação à fatura real do provedor. O custo é uma estimativa (instantâneo de preços), não a fatura.

Como executar

Script: scripts/usage_report.py — Python 3.9+, apenas biblioteca padrão (sem instalação), exceto o pacote opcional zstandard necessário para logs do DeepSeek Harness (dsh).

python3 <caminho-absoluto-para-este-skill>/scripts/usage_report.py --latest   # segmento/sessão mais recente (padrão)
python3 <caminho-absoluto-para-este-skill>/scripts/usage_report.py --whole    # última sessão completa
python3 <caminho-absoluto-para-este-skill>/scripts/usage_report.py --all      # lista por sessão
python3 <caminho-absoluto-para-este-skill>/scripts/usage_report.py --agent zcode|codex|claude|opencode|dsh
python3 <caminho-absoluto-para-este-skill>/scripts/usage_report.py --session <substring>   # fixar uma sessão

Sempre use o caminho absoluto para o diretório deste skill. Não use cd para outro lugar primeiro. Passe --agent explicitamente ao executá-lo de dentro de uma sessão de agente (a detecção automática escolhe o arquivo modificado mais recentemente, que pode pertencer a um agente diferente executado simultaneamente); --session fixa um arquivo de sessão específico.

Anexe a saída do script à resposta final textualmente — ambas as linhas, em linhas separadas (本段会话 acima, 整个会话 abaixo). Se a resposta for markdown, uma única quebra de linha é renderizada como espaço e mescla as duas linhas, portanto coloque-as dentro de um bloco de código cercado (ou deixe uma linha em branco entre elas):

```text
本段会话：输入 123456 / 缓存命中 98765 / 输出 4321 / 命中率 80.0% / 费用 ¥0.12
整个会话：输入 987654 / 缓存命中 876543 / 输出 43210 / 命中率 88.8% / 费用 ¥0.50
```

• Código de saída 0 → sempre inclua as linhas, mesmo que os números pareçam idênticos ao relatório anterior (o usuário os quer a cada turno).
• Codex relata uma única linha (sessão completa) — não há dados de segmento.
• Código de saída 1 / "Nenhum dado de uso encontrado" → pule silenciosamente; não pergunte ao usuário.
• Qualquer outro erro → corrija a causa (Python ausente, diretório do skill movido) antes de responder; não pule silenciosamente.

Agentes suportados

Agente	Fonte de dados	Significado de --latest
ZCode	~/.zcode/cli/rollout/model-io-*.jsonl	último segmento: registros desde a última requisição cuja última mensagem é um prompt do usuário (aquele turno, incluindo suas chamadas de ferramenta)
Codex	~/.codex/sessions/**/rollout-*.jsonl	última sessão (completa) — os rollouts do Codex armazenam totais cumulativos, portanto apenas o total final é relatado, em uma única linha; dados de segmento não estão disponíveis
Claude	~/.claude/projects/**/*.jsonl	último segmento: registros desde o último registro "type":"user"
OpenCode	<data>/opencode/opencode.db (SQLite; %LOCALAPPDATA% no Windows, $XDG_DATA_HOME ou ~/.local/share caso contrário)	último segmento da sessão mais recente (a partir da última mensagem do usuário)
DSH	~/.dsh/sessions/**/session.jsonl[.zstd] (compactado com zstd; precisa de zstandard opcional)	último turno (uma troca do usuário) + sessão completa

Todos os quatro são analisados a partir de formatos documentados, verificados localmente ou bem conhecidos. O DeepSeek Harness (dsh) e outros agentes podem ser adicionados com um pequeno analisador — veja o README.md para a receita.

Precisão e limitações

O relatório é uma estimativa a partir de dados de rollout locais + preços de tabela, não a fatura do provedor. Diferenças em relação à página de uso oficial podem vir de:

• Totais do Codex são cumulativos: cada registro total_token_usage é o total corrente da sessão, então o script usa o último registro (nunca soma). Números por requisição e por segmento não estão disponíveis para Codex.
• Os horários de pico/fora de pico são aplicados por hora de início da sessão, enquanto o provedor precifica cada requisição pelo seu próprio horário. Uma sessão que cruza um limite de pico (09:00–12:00 / 14:00–18:00, horário de Pequim) é mal precificada para a parte que cruzou.
• Tokens de saída de raciocínio são incluídos em output para Codex (cobrados pela taxa de saída); os rollouts do ZCode não expõem campos de raciocínio.
• Rollouts locais podem não capturar todas as requisições na chave (streams abortados, chamadas não interativas), então os totais podem ser menores que o uso total da chave.
• As taxas são um instantâneo; uma chave de gateway/agregador ou um ID de modelo diferente pode cobrar em preços diferentes.

Modelo de custos

Preços oficiais da DeepSeek para pico/fora de pico, vigentes a partir de 2026-08-17 00:00, horário de Pequim (anunciado em 2026-08-13). Horários de pico: 09:00–12:00 e 14:00–18:00, horário de Pequim; todos os outros horários são fora de pico com preço pela metade. Sessões anteriores a 2026-08-17 usam as taxas fixas legadas.

Modelo	Período	cache-hit-in	cache-miss-in	out	(CNY / 1M tokens)
deepseek-v4-flash	fora-pico	0.05	1.5	4.5
deepseek-v4-flash	pico	0.10	3.0	9.0
deepseek-v4-pro	fora-pico	0.15	4.5	13.5
deepseek-v4-pro	pico	0.30	9.0	27.0

O período de cobrança vem do horário de início da sessão (horário local da máquina). Se as taxas oficiais mudarem, atualize as tabelas PRICES_* em scripts/usage_report.py; a fonte autoritativa é platform.deepseek.com.

Integração (relatar automaticamente a cada sessão)

Adicione esta regra ao arquivo de instruções do agente no nível do usuário (~/.zcode/AGENTS.md, ~/.codex/AGENTS.md, CLAUDE.md ou um AGENTS.md de projeto):

Execute python3 <caminho-do-skill>/scripts/usage_report.py --agent <seu-agente> --latest (SEMPRE passe --agent — a detecção automática pode ler dados de outro agente executado simultaneamente) antes de cada resposta final e anexe suas duas linhas de saída textualmente: 本段会话：输入 X / 缓存命中 Y / 输出 Z / 命中率 N% / 费用 ¥M 整个会话：输入 X / 缓存命中 Y / 输出 Z / 命中率 N% / 费用 ¥M. Pule apenas quando o script exibir "No usage data found".

Segurança

• O script lê apenas arquivos JSON de rollout locais no diretório home do usuário. Nunca lê, imprime ou requer chaves de API, arquivos .env ou credenciais.
• Os arquivos de rollout podem conter texto de prompt — nunca ecoe seu conteúdo. Imprima apenas os números agregados que o script produz.