토큰 사용 보고서
에이전트의 로컬 롤아웃 파일을 읽고 가장 최근 대화 세그먼트 그리고 전체 세션의 사용량을 출력합니다 (두 줄):
本段会话：输入 123456 / 缓存命中 98765 / 输出 4321 / 命中率 80.0% / 费用 ¥0.12
整个会话：输入 987654 / 缓存命中 876543 / 输出 43210 / 命中率 88.8% / 费用 ¥0.50
왜 두 줄일까요? 전체 세션 수치는 스크립트가 로컬에서 계산합니다(추가 모델 호출 없음). 따라서 보고하는 데는 응답에 수십 개의 추가 문자만 필요하므로 토큰 오버헤드가 미미하며, 사용자는 현재 턴을 세션 총계와 비교할 수 있습니다.
실행 시기
- 매 세션의 최종 응답을 작성하기 전에 실행하세요.
- 트리거 문구: "token usage", "用量", "费用", "cost", "billing", "多少 tokens", "汇报", "spent".
- 이유: 사용자에게 제공자 실제 청구서와 교차 검증할 수 있는 턴별 사용량 라인을 제공합니다. 비용은 추정치(가격 스냅샷)이며 청구서가 아닙니다.
실행 방법
스크립트: scripts/usage_report.py — Python 3.9+, 표준 라이브러리만 필요(설치 불필요). 단, DeepSeek Harness(dsh) 로그에는 선택적 zstandard 패키지가 필요합니다.
python3 <this-skill-dir>/scripts/usage_report.py --latest # 가장 최근 세그먼트/세션 (기본값)
python3 <this-skill-dir>/scripts/usage_report.py --whole # 가장 최근 전체 세션
python3 <this-skill-dir>/scripts/usage_report.py --all # 세션별 목록
python3 <this-skill-dir>/scripts/usage_report.py --agent zcode|codex|claude|opencode|dsh
python3 <this-skill-dir>/scripts/usage_report.py --session <부분문자열> # 특정 세션 고정
항상 이 스킬 디렉토리의 절대 경로를 사용하세요. 먼저 cd로 이동하지 마세요. 에이전트 세션 내에서 실행할 때는 --agent를 명시적으로 전달하세요 (자동 감지는 가장 최근에 수정된 파일을 선택하는데, 이는 동시에 실행 중인 다른 에이전트의 파일일 수 있습니다). --session은 특정 세션 파일을 고정합니다.
스크립트 출력을 최종 응답에 그대로 추가하세요 — 두 줄 모두, 각각 별도 줄에 (위에 본段会话, 아래에 整个会话). 응답이 마크다운인 경우 단일 줄바꿈은 공백으로 렌더링되어 두 줄이 합쳐지므로, 코드 블록 안에 넣거나(또는 두 줄 사이에 빈 줄을 두세요):
```text
本段会话：输入 123456 / 缓存命中 98765 / 输出 4321 / 命中率 80.0% / 费用 ¥0.12
整个会话：输入 987654 / 缓存命中 876543 / 输出 43210 / 命中率 88.8% / 费用 ¥0.50
```
- 종료 코드 0 → 숫자가 이전 보고서와 동일해 보여도 항상 줄을 포함하세요 (사용자는 매 턴마다 이를 원합니다).
- Codex는 단일 줄(전체 세션)을 보고합니다 — 세그먼트 데이터가 없습니다.
- 종료 코드 1 / "No usage data found" → 조용히 건너뛰세요. 사용자에게 묻지 마세요.
- 다른 오류 → 응답하기 전에 원인(Python 없음, 스킬 디렉토리 이동 등)을 해결하세요. 조용히 건너뛰지 마세요.
지원되는 에이전트
| 에이전트 | 데이터 소스 | --latest 의미 |
|---|---|---|
| ZCode | ~/.zcode/cli/rollout/model-io-*.jsonl | 마지막 세그먼트: 마지막 메시지가 사용자 프롬프트인 최신 요청 이후의 레코드 (해당 턴과 그 도구 호출 포함) |
| Codex | ~/.codex/sessions/**/rollout-*.jsonl | 마지막 세션 (전체) — Codex 롤아웃은 누적 실행 합계를 저장하므로, 최종 합계만 단일 줄로 보고됩니다. 세그먼트 데이터는 사용할 수 없습니다. |
| Claude | ~/.claude/projects/**/*.jsonl | 마지막 세그먼트: 최신 "type":"user" 레코드 이후의 레코드 |
| OpenCode | <data>/opencode/opencode.db (SQLite; Windows는 %LOCALAPPDATA%, 그 외는 $XDG_DATA_HOME 또는 ~/.local/share) | 가장 최근 세션의 마지막 세그먼트 (최신 사용자 메시지부터) |
| DSH | ~/.dsh/sessions/**/session.jsonl[.zstd] (zstd 압축; 선택적 zstandard 필요) | 마지막 턴 (한 번의 사용자 교환) + 전체 세션 |
모두 문서화되고 로컬에서 확인되었거나 잘 알려진 형식에서 파싱됩니다. DeepSeek Harness(dsh) 및 기타 에이전트는 작은 파서로 추가할 수 있습니다 — README.md의 레시피를 참조하세요.
정확성 및 한계
보고서는 로컬 롤아웃 데이터와 목록 가격의 추정치이며, 제공자 청구서가 아닙니다. 공식 사용량 페이지와의 차이는 다음에서 발생할 수 있습니다:
- Codex 합계는 누적됨: 각
total_token_usage레코드는 실행 중인 세션 합계이므로, 스크립트는 마지막 레코드를 사용합니다(절대 합산하지 않음). Codex의 경우 요청별 및 세그먼트별 수치를 사용할 수 없습니다. - 피크/오프피크는 세션 시작 시간에 따라 적용되지만, 제공자는 각 요청을 자체 시간으로 가격을 책정합니다. 피크 경계(베이징 시간 09:00–12:00 / 14:00–18:00)를 넘나드는 세션은 경계를 넘는 부분에 대해 잘못 가격이 책정됩니다.
- 추론 출력 토큰은 Codex의
output에 포함됩니다(출력 요율로 청구). ZCode 롤아웃은 추론 필드를 노출하지 않습니다. - 로컬 롤아웃이 키의 모든 요청(중단된 스트림, 비대화형 호출)을 캡처하지 못할 수 있으므로 합계가 전체 키 사용량보다 낮을 수 있습니다.
- 요율은 스냅샷입니다. 게이트웨이/애그리게이터 키 또는 다른 모델 ID는 다른 가격으로 청구될 수 있습니다.
비용 모델
DeepSeek 공식 피크/오프피크 가격, 베이징 시간 2026-08-17 00:00부터 적용 (2026-08-13 발표). 피크 시간: 베이징 시간 09:00–12:00 및 14:00–18:00. 그 외 모든 시간은 절반 가격의 오프피크입니다. 2026-08-17 이전 세션은 고정 레거시 요율을 사용합니다.
| 모델 | 기간 | 캐시 적중 입력 | 캐시 미스 입력 | 출력 | (CNY / 100만 토큰) |
|---|---|---|---|---|---|
| deepseek-v4-flash | 오프피크 | 0.05 | 1.5 | 4.5 | |
| deepseek-v4-flash | 피크 | 0.10 | 3.0 | 9.0 | |
| deepseek-v4-pro | 오프피크 | 0.15 | 4.5 | 13.5 | |
| deepseek-v4-pro | 피크 | 0.30 | 9.0 | 27.0 |
청구 기간은 세션 시작 시간(머신 로컬 시간)에서 비롯됩니다. 공식 요율이 변경되면 scripts/usage_report.py의 PRICES_* 테이블을 업데이트하세요. 권위 있는 출처는 platform.deepseek.com입니다.
통합 (매 세션 자동 보고)
에이전트의 사용자 수준 명령 파일(~/.zcode/AGENTS.md, ~/.codex/AGENTS.md, CLAUDE.md 또는 프로젝트 AGENTS.md)에 다음 규칙을 추가하세요:
모든 최종 응답 전에
python3 <skill-dir>/scripts/usage_report.py --agent <your-agent> --latest를 실행하고 (항상--agent전달 — 자동 감지는 동시에 실행 중인 다른 에이전트의 데이터를 읽을 수 있음) 출력 두 줄을 그대로 추가하세요:本段会话：输入 X / 缓存命中 Y / 输出 Z / 命中率 N% / 费用 ¥M整个会话：输入 X / 缓存命中 Y / 输出 Z / 命中率 N% / 费用 ¥M. 스크립트가 "No usage data found"를 출력하는 경우에만 건너뛰세요.
보안
- 스크립트는 사용자 홈 디렉토리 아래의 로컬 롤아웃 JSON 파일만 읽습니다. API 키,
.env파일 또는 자격 증명을 읽거나, 출력하거나, 요구하지 않습니다. - 롤아웃 파일에는 프롬프트 텍스트가 포함될 수 있습니다 — 내용을 절대 출력하지 마세요. 스크립트가 출력하는 집계된 숫자만 출력하세요.