Informe de Uso de Tokens

¿Qué hace Informe de Uso de Tokens?

Lee los archivos locales de registro del agente e imprime el uso del segmento de conversación más reciente más el de toda la sesión (dos líneas):

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

¿Por qué ambas líneas? Los números de toda la sesión se calculan localmente mediante el script (sin llamadas adicionales al modelo), por lo que reportarlos cuesta solo unas pocas decenas de caracteres extra en la respuesta — una sobrecarga de tokens insignificante, y el usuario puede comparar el turno actual contra el total de la sesión.

Cuándo ejecutarlo

• Ejecutar antes de componer la respuesta final de cada sesión.
• Frases desencadenantes: "token usage", "用量", "费用", "cost", "billing", "多少 tokens", "汇报", "spent".
• Por qué: le proporciona al usuario una línea de uso por turno que puede verificar contra la factura real del proveedor. El costo es una estimación (instantánea de precios), no la factura.

Cómo ejecutarlo

Script: scripts/usage_report.py — Python 3.9+, solo biblioteca estándar (sin instalación), excepto el paquete opcional zstandard necesario para los registros de DeepSeek Harness (DSH).

python3 <directorio-de-este-skill>/scripts/usage_report.py --latest   # segmento/sesión más reciente (predeterminado)
python3 <directorio-de-este-skill>/scripts/usage_report.py --whole    # sesión más reciente completa
python3 <directorio-de-este-skill>/scripts/usage_report.py --all      # lista por sesión
python3 <directorio-de-este-skill>/scripts/usage_report.py --agent zcode|codex|claude|opencode|dsh
python3 <directorio-de-este-skill>/scripts/usage_report.py --session <subcadena>   # fijar una sesión específica

Usa siempre la ruta absoluta al directorio de este skill. No hagas cd a otro lugar primero. Pasa --agent explícitamente cuando lo ejecutes desde una sesión de agente (la detección automática selecciona el archivo modificado más recientemente, que podría pertenecer a un agente diferente que se ejecuta concurrentemente); --session fija un archivo de sesión específico.

Adjunta la salida del script a la respuesta final tal cual — ambas líneas, en líneas separadas (本段会话 arriba, 整个会话 abajo). Si la respuesta es markdown, un salto de línea simple se renderiza como un espacio y fusiona las dos líneas, por lo que debes ponerlas dentro de un bloque de código delimitado (o dejar una línea en blanco entre ellas):

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

• Código de salida 0 → siempre incluir las líneas, incluso si los números parecen idénticos al informe anterior (el usuario las quiere en cada turno).
• Codex reporta una sola línea (sesión completa) — no hay datos de segmento.
• Código de salida 1 / "No usage data found" → omitir silenciosamente; no preguntar al usuario.
• Cualquier otro error → corregir la causa (Python faltante, directorio del skill movido) antes de responder; no omitir silenciosamente.

Agentes compatibles

Agente	Fuente de datos	Significado de --latest
ZCode	~/.zcode/cli/rollout/model-io-*.jsonl	Último segmento: registros desde la solicitud más reciente cuyo último mensaje es un prompt de usuario (ese turno incluye sus llamadas a herramientas)
Codex	~/.codex/sessions/**/rollout-*.jsonl	Última sesión (completa) — los registros de Codex almacenan totales acumulativos en ejecución, por lo que solo se reporta el total final, como una sola línea; los datos de segmento no están disponibles
Claude	~/.claude/projects/**/*.jsonl	Último segmento: registros desde el registro más reciente con "type":"user"
OpenCode	<data>/opencode/opencode.db (SQLite; %LOCALAPPDATA% en Windows, $XDG_DATA_HOME o ~/.local/share en otros casos)	Último segmento de la sesión más reciente (desde el último mensaje de usuario)
DSH	~/.dsh/sessions/**/session.jsonl[.zstd] (comprimido con zstd; necesita zstandard opcional)	Último turno (un intercambio de usuario) + sesión completa

Los cuatro se analizan a partir de formatos documentados, verificados localmente o bien conocidos. DeepSeek Harness (DSH) y otros agentes se pueden agregar con un pequeño analizador — consulta README.md para la receta.

Precisión y limitaciones

El informe es una estimación a partir de datos locales de registro + precios de lista, no la factura del proveedor. Las diferencias con la página de uso oficial pueden deberse a:

• Los totales de Codex son acumulativos: cada registro de total_token_usage es el total acumulado de la sesión, por lo que el script usa el último registro (nunca suma). Los números por solicitud y por segmento no están disponibles para Codex.
• El pico/valle se aplica por hora de inicio de la sesión, mientras que el proveedor factura cada solicitud por su propia hora. Una sesión que cruza un límite pico/valle (09:00–12:00 / 14:00–18:00 hora de Pekín) se factura incorrectamente para la parte cruzada.
• Los tokens de salida de razonamiento se incluyen en output para Codex (facturados a la tarifa de salida); los registros de ZCode no exponen un campo de razonamiento.
• Los registros locales pueden no capturar cada solicitud de la clave (streams abortados, llamadas no interactivas), por lo que los totales pueden ser inferiores al uso completo de la clave.
• Las tarifas son una instantánea; una clave de gateway/agregador o un ID de modelo diferente pueden facturar a precios distintos.

Modelo de costos

Tarifas oficiales pico/valle de DeepSeek, vigentes desde 2026-08-17 00:00 hora de Pekín (anunciado 2026-08-13). Horas pico: 09:00–12:00 y 14:00–18:00 hora de Pekín; todos los demás horarios son valle a la mitad del precio. Las sesiones anteriores al 2026-08-17 usan las tarifas fijas heredadas.

Modelo	Período	caché-acertado	fallo-entrada	salida	(CNY / 1M tokens)
deepseek-v4-flash	valle	0.05	1.5	4.5
deepseek-v4-flash	pico	0.10	3.0	9.0
deepseek-v4-pro	valle	0.15	4.5	13.5
deepseek-v4-pro	pico	0.30	9.0	27.0

El período de facturación proviene de la hora de inicio de la sesión (hora local de la máquina). Si las tarifas oficiales cambian, actualiza las tablas PRICES_* en scripts/usage_report.py; la fuente autorizada es platform.deepseek.com.

Integración (informe automático cada sesión)

Agrega esta regla al archivo de instrucciones a nivel de usuario del agente (~/.zcode/AGENTS.md, ~/.codex/AGENTS.md, CLAUDE.md, o un AGENTS.md del proyecto):

Ejecuta python3 <directorio-skill>/scripts/usage_report.py --agent <tu-agente> --latest (SIEMPRE pasa --agent — la detección automática puede leer datos de otro agente que se ejecuta concurrentemente) antes de cada respuesta final y adjunta sus dos líneas de salida textualmente: 本段会话：输入 X / 缓存命中 Y / 输出 Z / 命中率 N% / 费用 ¥M 整个会话：输入 X / 缓存命中 Y / 输出 Z / 命中率 N% / 费用 ¥M. Omite solo cuando el script imprima "No usage data found".

Seguridad

• El script solo lee archivos JSON de registro locales bajo el directorio home del usuario. Nunca lee, imprime ni requiere claves API, archivos .env o credenciales.
• Los archivos de registro pueden contener texto de los prompts — nunca debes mostrar su contenido. Imprime únicamente los números agregados que genera el script.