51 lines
2.8 KiB
Markdown
51 lines
2.8 KiB
Markdown
# usage-history レビュー
|
||
|
||
## 要件の充足
|
||
|
||
チケットが定義した要件は全て達成されている:
|
||
|
||
- **LogEntry::LlmUsage**: session-store のハッシュチェーンに乗る variant として追加。
|
||
`history_len` / `input_total_tokens` / `cache_read_tokens` / `cache_write_tokens` / `output_tokens` の5フィールド
|
||
- **RestoredState.usage_history**: `collect_state` の replay で `Vec<UsageRecord>` に時系列順で積まれる。history の構築には影響しない
|
||
- **save_usage**: `append_entry` 経由でハッシュチェーンに接続
|
||
- **既存ログ互換**: `LlmUsage` entry が無い既存ログを読んでも `usage_history` が空になるだけで壊れない
|
||
- **1リクエスト = 1 entry**: Timeline の `pending_usage` + `flush_usage()` で複数 Usage event を集約し、handler には1度だけ発火
|
||
|
||
## アーキテクチャ
|
||
|
||
レイヤー分担が明確で、各層の責務が逸脱していない:
|
||
|
||
| レイヤー | 責務 |
|
||
|---------|------|
|
||
| scheme (anthropic) | raw → 占有量への正規化。`input_tokens + cache_read + cache_creation` |
|
||
| Timeline | 1リクエスト内の複数 Usage event をフィールド単位 latest-non-None でマージ。`flush_usage()` で1度だけ発火 |
|
||
| Worker | ストリーム完了・エラー・キャンセルの全パスで `flush_usage()` を呼ぶ |
|
||
| UsageTracker (pod) | `note_request(history_len)` と `record_usage(event)` のペアリング。drain で Pod に渡す |
|
||
| Pod::persist_turn | drain した records を `save_usage` で session-store に書き出し |
|
||
|
||
## 指摘と対処
|
||
|
||
### 1. UsageEvent の doc comment（対処済み）
|
||
|
||
`UsageEvent.input_tokens` が「占有量（プロンプト全長、キャッシュ込み）」を意味することが
|
||
struct と各フィールドの doc comment に明記された。scheme 層での正規化規約も記載済み。
|
||
|
||
### 2. save_usage の引数が多い（非ブロッカー、未対処）
|
||
|
||
8引数。`UsageRecord` を直接受け取れば `drain()` の結果をそのまま渡せてシグネチャがきれいになるが、
|
||
他の `save_*` 関数がフラットな引数を取るパターンと一貫しているため、統一性の観点では現状でも妥当。
|
||
将来フィールドが増えた時点でまとめて `UsageRecord` 受け取りに変えればよい。
|
||
|
||
## テスト
|
||
|
||
- `replay_llm_usage_appends_to_usage_history`: 複数 LlmUsage entry の replay で usage_history が正しく積まれ、history.len() に影響しない
|
||
- `replay_without_llm_usage_keeps_usage_history_empty`: 既存ログ互換
|
||
- `llm_usage_entry_round_trip_via_json`: serde 往復
|
||
- `test_convert_usage_includes_cache_in_input_total`: Anthropic の占有量正規化
|
||
- `test_usage_aggregation_and_flush`: Timeline の集約 + flush
|
||
- UsageTracker: ペアリング、drain、未ペアの drop、複数リクエスト
|
||
|
||
## 判定
|
||
|
||
承認。
|