Aria Token Telemetry

aria-token-telemetry

用途

aria-token-telemetry 是一个 internal skill(复用 git-remote-helper US-012 Layer 3 "internal skill 作跨-skill 共享基础设施"先例),不直接被用户触发。它为以下消费方提供标准化的 Claude Code context/token 数据采集:

• aria-context-monitor (user-facing) — 消费实时 context 占用 (used%/remaining%/window)
• aria-plugin #18 ai-native-estimator (future) — 复用 raw token counts (per-turn input/output/cache),独立于 window% (Q2=a)

核心脚本: scripts/token_telemetry.py (stdlib-only Python)。

数据来源 (3 档 fallback)

数据 schema (statusLine stdin) 是通用 Claude Code 特性;relay 抓取依赖 statusLine 配置 + relay marker。

statusLine stdin schema 契约 (TASK-001 BLOCKING gate 固化, 2026-05-29)

证据: 2026-05-29 重新 capture 实测 (aria-plugin-benchmarks/context-monitor/statusline-stdin-sample.json), 验证 context_window_size 真实存在且为 number → gate PASS, 不触发回退条款。 Claude Code runtime version 2.1.156。

Claude Code runtime 每次渲染 statusLine 时 pipe 一个 JSON 到 statusLine command 的 stdin。冻结契约字段:

{
  "model": {
    "id": "claude-opus-4-8[1m]",            // ✅ 完整 ID 带 [1m] (transcript message.model 丢此后缀)
    "display_name": "Opus 4.8 (1M context)"
  },
  "context_window": {
    "context_window_size": 1000000,          // ✅🔑 window 大小 — 零推断 (gate 验证字段)
    "used_percentage": 14,                    // ✅ runtime 算好的 % (口径: total_input/window)
    "remaining_percentage": 86,               // ✅
    "total_input_tokens": 142208,             // ✅
    "total_output_tokens": 1274,
    "current_usage": {                        // ✅ raw counts (供 #18 estimator 复用)
      "input_tokens": 131, "output_tokens": 1274,
      "cache_creation_input_tokens": 980, "cache_read_input_tokens": 141097
    }
  },
  "exceeds_200k_tokens": false,               // ✅
  "transcript_path": "...",                   // ✅
  "session_id": "...", "version": "2.1.156",
  "cost": {...}, "rate_limits": {...}, "workspace": {...}, "fast_mode": false
}

relay cache 写入子集 (setup_relay.sh 中 jq 投影): schema_version + model.id + context_window.* + exceeds_200k_tokens + transcript_path + captured_at。不写 cost/rate_limits/session_id (隐私 + 非必要)。

字段级注解与 transcript 字段映射见 references/schema.md。

relay cache schema (.aria/cache/context-window.json)

{
  "schema_version": "1.0",                    // 顶层校验 (对比 issues.json 模式)
  "captured_at": "2026-05-29T...",            // relay 写入时刻 (ISO8601)
  "model_id": "claude-opus-4-8[1m]",
  "context_window_size": 1000000,
  "used_percentage": 14,
  "remaining_percentage": 86,
  "total_input_tokens": 142208,
  "current_usage": { "input_tokens": 131, "cache_read_input_tokens": 141097, "cache_creation_input_tokens": 980, "output_tokens": 1274 },
  "exceeds_200k_tokens": false,
  "transcript_path": "..."
}

window 大小 4 档 resolve (transcript fallback 时)

relay cache 命中 → window_source = "runtime" (恒定, 不得标其他值)。

transcript fallback 时按优先级:

公共接口 (token_telemetry.py)

python3 "${CLAUDE_PLUGIN_ROOT:-aria}/skills/aria-token-telemetry/scripts/token_telemetry.py" [--project-root DIR] [--json]

返回 JSON (供消费方解析):

{
  "source": "relay_cache | transcript_fallback | unavailable",
  "schema_version": "1.0",
  "context_window_size": 1000000,
  "window_source": "runtime | cached_size_reuse | config | empirical_peak | default",
  "used_percentage": 14,                  // relay 路径口径 (total_input/window); transcript 路径为 null
  "used_percentage_proxy": null,          // transcript 路径口径 (input+cache_read+cache_creation)/window; relay 路径为 null
  "remaining_percentage": 86,
  "total_input_tokens": 142208,
  "current_usage": {...},                 // raw counts (#18 复用; 独立于 window%)
  "model_id": "claude-opus-4-8[1m]",
  "exceeds_200k_tokens": false,
  "captured_at": "2026-05-29T...",
  "staleness_seconds": 12                  // relay 路径: now - captured_at; transcript/unavailable 路径为 null
}

口径不混用: relay 路径填 used_percentage,transcript 路径填 used_percentage_proxy —— 两者是不同的量,消费方按 source 读对应字段。unavailable 态两者皆 null。

Python 复用接口 (供消费 skill / #18 直接 import):

from token_telemetry import collect, parse_transcript_usage, resolve_window
result = collect(project_root=".")          # 完整 telemetry dict
usage  = parse_transcript_usage(jsonl_path) # raw counts only (window-independent, #18 axis)

错误处理 (graceful degradation, 永不抛异常给消费方)

相关文档

• references/schema.md — statusLine stdin + relay cache 字段级契约 + transcript 映射
• aria-context-monitor — user-facing 消费方
• git-remote-helper — internal-skill 先例
• Spec: openspec/changes/aria-context-monitor/proposal.md (#104)
• 决策: .aria/decisions/2026-05-29-context-monitor-architecture.md (DEC-20260529-001)

Skill 版本: 1.0.0 (2026-05-29, #104 Phase B) 类型: internal (user-invocable: false)