用途
meter-reconcile 是一个技能原生的 CocoMeter 转录对账与适配器金丝雀工具，属于 snowflake-labs/cocoplus。其目标是将 CocoMeter 会话总量与权威 JSONL 转录记录进行对账，且仅使用转录中命名的字段。它替代了原先的 meter-reconcile 和 adapter-self-test 运行时辅助工具。
主要能力
- 接受直接调用参数，或从 .cocoplus/v2-runtime-requests.jsonl 读取排队请求。
- 输入包括：transcript_path、session_file、out、threshold（默认 0.05）、session_id、idempotency_key，以及可选 operation: "adapter-canary"（用于迁移自检）。
- 幂等性：提供 idempotency_key 时使用该键；否则由 session_id、transcript_path、session_file 和 out 派生。若 .cocoplus/v2-runtime-settlements.jsonl 中已存在该键的 state: "completed" 且 out 存在，则报告已有产物路径并停止。
- 转录适配器规则：逐行读取 JSONL；对每个有效 JSON 对象，仅保留计量所需的命名字段，包括 id、message_id、parent_id、timestamp、type、role、event、kind、model、model_tier、actual_model、usage、tokens、input_tokens、output_tokens、cache_read_input、cache_write_input。未知字段被忽略；格式错误的行产生 kind: "other" 适配器记录，且不会中止对账。
- 去重：当 message_id 存在时按 message_id 对助手消息去重；否则使用 role、timestamp、model 和 usage 字段的稳定指纹。
- 对账：读取 session_file（若存在）并捕获运行时令牌总量；通过上述适配器规则读取转录；汇总来自助手/工具用量记录的转录派生令牌总量；计算 gap_fraction = abs(runtime_tokens - transcript_tokens) / max(runtime_tokens, transcript_tokens, 1)。
- 状态标记：gap_fraction <= threshold 时为 matched；超过阈值时为 gap；运行时文件缺失但转录有用量时为 transcript_only；两个来源均无用量时为 not_run。
- 模型漂移：在可用时保留配置模型层级与实际模型层级；当两者均存在且不同时，设置 model_drift = true。
- 原子写入对账产物，字段包括 session_id、reconciliation_status、runtime_tokens、transcript_derived_tokens、authoritative_tokens、gap_fraction、duplicate_count、model_tier_configured、model_tier_actual、model_drift、adapter_records、computed_at。
- 对于 operation: "adapter-canary"，写入相同的适配器摘要，并附加 canary_status 字段到 .cocoplus/meter/adapter-self-test.json。
- 队列结算：当从 .cocoplus/v2-runtime-requests.jsonl 调用时，遵循 execution-engine/runtime-queue：用 claim_token 认领请求；原子写入对账产物；追加带 artifact: out 的 completed 结算；在转录格式错误、文件缺失或字段形状异常时，追加 failed 及原因，除非契约明确允许 not_run。
使用方式
可通过直接调用参数或排队请求触发。关键输入为 transcript_path、session_file、out、threshold、session_id、idempotency_key，以及可选的 operation: "adapter-canary"。对账结果以原子方式写入 out 指定的产物；金丝雀模式额外写入 .cocoplus/meter/adapter-self-test.json。
适用场景
- 需要将 CocoMeter 会话统计与 JSONL 转录记录进行一致性核对时。
- 需要检测运行时令牌与转录派生令牌之间是否存在显著差距时。
- 需要检测配置模型层级与实际模型层级是否漂移时。
- 迁移过程中需要运行适配器自检（adapter-canary）时。
- 在队列模式下需要按 idempotency_key 恰好结算一次时。
限制
- 不得从自然语言描述中推断令牌总量；只有转录适配器中的命名字段和数值型运行时计量字段可计入总量。
- 未知字段被忽略；格式错误的行不会中止对账，而是产生 kind: "other" 适配器记录。
- 退出标准要求：转录读取仅使用命名字段适配器；在最终确定总量前对助手消息去重；出现实质性差距时写入对账产物；配置与实际模型不同时模型漂移可见；排队请求按 idempotency_key 恰好结算一次。
- 关于收费、价格、平台支持范围等具体信息，资料中暂未提供。