名词
- 上游 usage：API 响应体里的
usage（如 prompt_tokens / completion_tokens），由网关/模型侧生成；本仓库将其镜像为 jsonl 顶层字段及 usage_upstream（第二栏展平）。
- usage_official（第三栏）：仅当
OPENAI_BASE_URL / 代理上游指向可信官方面点主机（见 scripts/lib/official-usage-trust.mjs，可用 OFFICIAL_USAGE_TRUST_HOSTS 追加）时，将同一次 HTTP 响应中的 usage 截断写入；不是事后另调计费接口。经向量引擎时不写入第三栏数据。
- 本地 tokenizer：在本机用公开算法/SDK 对「请求文本 + 回复文本」再算一遍 token，得到
tokens_local_*，用于审计时对照上游是否自洽（无法单独证明计费倍率，详见仓库内审计文档）。
- 缓存类 token（如
cache_read_tokens）：多来自上游 usage 扩展字段；本地 tokenizer通常无法从文本复算，看板仍展示但不应视为「本地已覆盖」。
官方与行业参考
本仓库各模型族的本地计数方案（scripts/lib/tokenizer-router.mjs）
- Claude：
@anthropic-ai/tokenizer（对拼接后的 role+content 文本计数；与网关「官方 message 格式」若有细微差异，可能出现个位数偏差）。
- GPT / 多数 OpenAI 兼容：
tiktoken（encoding_for_model 或启发式 cl100k_base / o200k_base）。
- DeepSeek：
tiktoken 固定 cl100k_base（文档常见近似）。
- 豆包 / doubao：
cl100k_base 近似，jsonl 中 tokens_local_encoder=approx。
- Gemini：
@google/generative-ai 的 countTokens（需配置 GOOGLE_AI_API_KEY / GEMINI_API_KEY；未配则为 unavailable）。
为何会与上游 usage 不一致？
常见原因包括：流式末包未带 usage；本地与官方分词边界或 多模态 / 工具字段未完全对齐；网关对 usage 做了聚合或扩展字段；以及 Claude 本地包按「扁平文本」而非完整官方对话编码计数。若差值在很小比例内通常可接受；若长期系统性偏大/偏小应结合 npm run reconcile 与平台日志排查。
其他
- 矩阵烟测的
matrix_group 在表格「分组」列展示；jsonl 中 question 仍为统一题干。
- 更完整的作弊面与审计层级说明见仓库
docs/vectorengine_tokenizer_cc.md（需在 IDE 或 Git 中打开）。