10cg aria-context-monitor
用途
让 AI 机读当前会话的 context 占用, 替代"凭感觉"估算 (实证 #104: 凭感觉 +22% 偏差导致不必要暂停)。
数据来自 Claude Code runtime 渲染 statusLine 时 pipe 的 stdin JSON (context_window_size /
used_percentage 等真实值), 经 statusLine relay 写入 .aria/cache/context-window.json, 由本 skill 读取。
底层数据层是 internal skill aria-token-telemetry (3 档 fallback)。
何时使用
- 十步循环 Phase B/C 实施期, AI 判断"当前会话继续 vs 暂停 (形成 commit boundary)"
- 用户问"还剩多少 context"/"该暂停吗"
- 长会话接近窗口上限前的主动预警
不使用: 本 skill 只提供数据, 不自动中断会话。暂停决策由 AI / phase skill 判断 (DEC: 不自动暂停)。
执行
python3 "${CLAUDE_PLUGIN_ROOT:-aria}/skills/aria-token-telemetry/scripts/token_telemetry.py" --project-root .
读返回 JSON 后, AI 按 source 字段选对应口径解读 (见下)。
首次使用 / relay 未安装
若返回 source=transcript_fallback 或 confidence=estimate 且用户期望精确值, 引导安装 relay:
bash "${CLAUDE_PLUGIN_ROOT:-aria}/skills/aria-context-monitor/scripts/setup_relay.sh" # 幂等注入
bash "${CLAUDE_PLUGIN_ROOT:-aria}/skills/aria-context-monitor/scripts/setup_relay.sh --status" # 查状态
注入后需 statusLine 渲染一次 (任意交互) relay cache 才写入; 之后即走 source=relay_cache (runtime-truth)。
setup_relay.sh 退出码: 0 成功 (injected / no-op / minimal-reference-created) / 2 参数错 / 3 jq 缺失 / 4 找不到 input=$(cat) 锚点 / 5 statusLine command 非脚本文件 (需手动注入)。
输出解读 (口径不混用)
source |
confidence |
读哪个占用字段 | 含义 |
|---|---|---|---|
relay_cache |
high |
used_percentage (proxy=null) |
runtime-truth, statusLine 算好的 % — 0 偏差 |
transcript_fallback |
estimate |
used_percentage_proxy (used_percentage=null) |
transcript usage 推算, window 可能非精确 (见 window_source) |
unavailable |
estimate |
两者皆 null | 无 statusLine + 无 transcript, 无法判定 — 不报错, 不可用此信号 |
⚠️ 绝不混用: relay 路径只看
used_percentage, transcript 路径只看used_percentage_proxy。两者是不同口径的量 (前者 total_input/window, 后者 input+cache 合计/window), 混用会重蹈 #104 的 22% drift。
staleness 判定
staleness_seconds ≤ 300(configcontext_monitor.staleness_threshold_seconds可覆盖): relay cache 可信,confidence=highstaleness_seconds > 300: token_telemetry 自动降级到 transcript fallback (confidence=estimate)- transcript / unavailable 路径:
staleness_seconds = null(不适用)
window_source (window 大小来源)
relay_cache 命中恒 = runtime。transcript_fallback 时 4 档: cached_size_reuse > config > empirical_peak > default (200K 兜底)。empirical_peak/default 时 window 可能低估真实大小 → 占用 % 偏高, 仅作下界参考。
决策阈值建议 (advisory)
used_percentage (relay 路径) |
建议 |
|---|---|
| < 70% | 继续推进 (容量充足) |
| 70–85% | 留意; 找自然 commit boundary |
| > 85% | 建议暂停 + commit, 避免硬撞限丢上下文 |
transcript fallback (used_percentage_proxy) 因 window 可能低估, 阈值放宽解读 (proxy 偏高时实际余量可能更多)。
消费集成点 (phase-b-developer / phase-c-integrator 调用建议) 见各 skill 文档。
错误处理
| 情况 | 行为 |
|---|---|
| relay cache 缺失 | 自动 transcript fallback (estimate) |
| relay cache corrupt / schema 不匹配 | 忽略 cache, transcript fallback; corrupt 不抛异常 |
| 无 statusLine 且无 transcript | source=unavailable, 不报错; 提示安装 relay |
| jq 缺失 | relay 写入侧失效 (aria-doctor 提示); transcript fallback 仍可用 |
可移植性
数据 schema (statusLine stdin) 是通用 Claude Code 特性, 任何项目可用。relay 抓取依赖 statusLine 配置 + relay marker (故有 3 档 fallback + setup_relay.sh helper)。无 statusLine 的 sandbox 项目跑本 skill → transcript fallback / unavailable, 不报错。
相关文档
- aria-token-telemetry — 底层数据层 (relay 读 + transcript 解析 + window resolve)
- aria-doctor — relay 3 态检测 + jq 可用性
- 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)