input-token-analysis

入力トークン分析

入力トークンの総消費量を説明します。数値を示して、次の3つの問いに答えてください。トークンはどこで消費されたか、どの消費元が大きな割合を占めているか、どの設定やプロンプトを変更すれば削減できるか。1ターンごとのシステムプロンプトブロックを監査する input-token-overheads とは異なり、このスキルではセッション、cron の実行、ツールのトラフィック全体の使用量を監査します。

使用するタイミング

• 月間または週間の入力トークン料金が高く、原因がわからない場合（例：「30日間で24億トークン」）
• トークン節約の変更を適用した後、ベースラインとの差を測定する場合
• cron ジョブのトークン使用量が暴走している疑いがある場合

ターンごとのコンテキストウィンドウの状態を確認するには、input-token-overheads を使用してください。API の請求に関する異議申し立てには、プロバイダーの使用状況ダッシュボードを使用してください。ローカルのテレメトリーでは、プロバイダー側のキャッシュを確認できません。

クイックスタート

監査スクリプトを実行します（読み取り専用、標準ライブラリのみ）。

python3 ~/.hermes/skills/agent-ops/input-token-analysis/scripts/audit.py --days 30
# other profiles: --db ~/.hermes/profiles/<name>/state.db
# custom cron ledger: --cron-audit /path/to/usage_audit.jsonl --jobs /path/to/jobs.json

スクリプトは、タスク、モデル、プロバイダーごとの合計、キャッシュ読み取りとキャッシュ書き込みの列、呼び出しごとの加重平均（長いセッションと短いセッションの下限）、上位セッション、問題のある cron、アクティブなツール結果の量とツールの占有率、大きすぎる結果の件数を出力します。すべて実際の DB 行から算出されます。スクリプトで測定できる場合は、決して手作業で推定しないでください。

事前確認の徹底

助言する前に確認してください。記憶を頼りにした助言は認められません。

1. 設定キーと現在の値 — まず実際の値を読み取ってください：hermes config get <key>。現在の値を記憶から述べたり、デフォルト値が適用されていると決めつけたりしないでください。
2. デフォルト値と仕組み — インストール済みビルド（hermes_cli/config_defaults.py）または Hermes のドキュメントで、設定キーの存在と機能を確認してください。インストール済みビルドとドキュメントの内容が異なる場合は、その旨を伝えてください。
3. プロバイダーの動作 — プロバイダーがキャッシュフィールドを報告する、価格設定階層を適用する、または特定の方法でトークンを数えると決めつけないでください。主張する前に、実際に確認するか、最新のドキュメントを調べてください。
4. 検証できない主張 — レポートでは未検証であることを明記してください。自信のある推測より、未知であると明示するほうが適切です。

未検証のキー、値、仕組みを根拠として示す提案は不完全です。事前確認を完了するか、その提案を取り下げてください。

解釈

利用量の多い対象を順位付けし、それぞれを事前に確認済みの調整手段に対応付けます。

調査結果	指標	調整手段
長時間のセッションが大半を占める	上位セッションが >200 api_calls、>40M input	まずプロバイダーのキャッシュ割引を確認します。キャッシュを使うと、継続中のセッションで履歴を再読み込みするコストを抑えられます。未キャッシュの不要なコンテキストが大半を占める場合に限り、リセットします。リセットのたびに、プレフィックス全体を定価で再度読み込むことになります。圧縮が実際に動作しているか確認します（compact count >0）
background_review の割合が大きい	task='background_review' が合計の >5%	auxiliary.background_review.max_input_tokens（デフォルト 600000）を設定するか、enabled: false にします。手動の /refine は引き続き利用できます。また、auxiliary.background_review.model をより安価なモデルに変更します。別のモデルなら、完全なトランスクリプトではなく、簡潔なダイジェストを読み込み直します
1つの cron ジョブが大半を占める	実行あたりの平均 prompt_tokens が数百万	読み込み予算を設けるようプロンプトを書き換えます。対象データを日付で絞り、大きすぎる項目をスキップし、スクロール範囲を狭め、上限に達したら停止して後回しにします
Cron のコストが下限に達している	実行あたりの平均トークン数が呼び出しごとの下限（25〜30k）付近	固定の基盤コストに実行回数を掛けた値が大半を占めています。プロンプトを縮小するより、実行頻度を下げるかジョブを統合します
ツールの結果がコンテキストの大半を占める	ツールの文字数が STORED のアクティブコンテンツの >70%（送信量の上限値。スクリプトが割合を表示します）	tool_output.max_bytes（デフォルト 50000）、file_read_max_chars（デフォルト 100000）、オーバーフロー予算を設定します。プロバイダーキャッシュを利用している場合、節約効果が集中するのは、結果が初めて表示されるターンと、圧縮を回避できる場面です。キャッシュ経由で再読み込みする安定した結果は低コストです。大きすぎる結果は、プレビューとパスとして $HERMES_HOME/cache/spillover/ に保存されます
スキルが重複して読み込まれる	同じスキルの本文がセッション内で N 回読み込まれる	行動ルールとして、すでにコンテキストにあるスキルについて skill_view を再度呼び出さないようにします。キャッシュを利用していれば直接の再読み込みは割引されます。実際の問題は、コンテキストの圧迫によって圧縮が早まり、キャッシュが無効になることです
短いセッションで呼び出しごとの下限が高い	<50-call セッションに対するスクリプトの加重平均（通常 25〜40k）	固定のベースライン（システムプロンプト + ツールスキーマ）が原因です。input-token-overheads で削減してください。このスキルで対処する項目ではありません
サブエージェントの呼び出しが多い	delegate_task の起動が多く、それぞれでシステムプロンプト全体 + ツールスキーマを未キャッシュで再度読み込む	機械的なサブタスクでは delegation.model をより安価なモデルに変更します。呼び出しを多数のエージェントに分散させる代わりに、複数のツール呼び出しを1つの execute_code 呼び出しにまとめます。同時実行するサブエージェント数にも上限を設定します
圧縮が頻繁に実行される	セッションあたりの圧縮イベント数が多い。compression_ineffective_count >0	圧縮のたびに履歴が新しいプレフィックスとして書き換えられるため、それ以降はすべてキャッシュミスとなり、定価が適用されます。compression.threshold とプロバイダーのキャッシュ割引を比較検討します。圧縮要約モデル（auxiliary.compression.model）には安価なモデルを指定します。要約モデルは会話全体を読み込みます
プロバイダーの cache_read ≈ 0	プロバイダーがキャッシュ済みトークンのフィールドをまったく出力しない場合（その場合、ローカルの input がプロンプト全体となり、割合は測定できません。プロバイダーの課金ダッシュボードを確認してください）、またはフィールドは報告するものの値が 0 の場合（キャッシュが実際に無効です。短いセッション、不安定なプレフィックス、TTL の期限切れが原因の可能性があるため、調査してください）
高価なモデルで安価なタスクが実行される	メインモデルの title_generation/approval/vision 行	各 auxiliary.<task>.model に flash クラスのモデルを指定します。頻度の高い小規模な呼び出しで、ほぼ無料の節約が見込めます
トークン数の順位とコストの順位が一致しない	安価なモデルのトークン消費量が高価なモデルの10倍	billing_provider ごとに estimated_cost_usd/actual_cost_usd で順位付けします。限界費用がゼロの billing_mode='subscription_included' の行は最適化の対象から除外します

手順

1. ベースラインを確立する

対象期間についてスクリプトを実行します。合計 input、タスク別の内訳、上位10セッション、コストの高い cron ジョブの統計、ツール文字数の割合、キャッシュ列、コスト合計を記録します。出力は、実施予定の変更と一緒に保存します。

完了条件：最終レポートのすべての数値を、スクリプト内の該当行までたどれること。

2. 各候補のレバーを事前確認する

提案に含める前に、実稼働中のインスタンスで各レバーを確認します。キーが存在すること（hermes config get）、現在の値、仕組みがインストール済みのビルドまたはドキュメントと一致していることを確認してください。キャッシュ関連の主張をする前に、プロバイダーのレポート動作を確認します。

完了条件：草案の提案に含まれるすべてのレバーについて、確認済みのキーと現在の値があるか、不足している情報とともに UNVERIFIED として記載されていること。

3. 順位付けして対応付ける

トークン数と推定コストの両方で利用元を並べます（順位は一致しない場合があります）。上位 3 件それぞれについて、事前確認済みのレバーを記載します。利用元に対応するレバーがない場合は、作り上げずにその旨を明記してください。

完了条件：上位 3 件の利用元それぞれについて、事前確認済みのレバーがあるか、「ローカルで変更できるレバーなし」と明示されていること。

4. 変更を提案する

影響度の高い順に、各提案へ設定キーまたはプロンプトの編集内容、予想される節約額、元に戻す手順を含めます。billing_provider ごとに、そのプロバイダーのキャッシュ割引を適用して予想される節約額を計算します。プロバイダーがキャッシュ項目を報告しない場合は、推定値に上限があることを明記し、プロバイダーダッシュボードで確認してください。設定の編集には hermes config set を使用してください。config.yaml の直接編集はツールによってブロックされます（2026-09-02 に確認済み）。cron のプロンプトを編集する場合は、まず古いプロンプトをバックアップし、編集後に形式（{"jobs": [...], "updated_at": ...}）とスケジュールが維持されていることを確認してください。

完了条件：ユーザーが各変更を承認し、変更が適用され、読み戻して確認されていること。

5. 差分確認をスケジュールする

約 30 日後に、このスキルを古いベースラインとともにプロンプトで再実行する単発の cron を作成します。ベースラインの数値、適用した変更の一覧、変更ごとの合格基準（例：「job X の avg prompt_tokens/fire >2M = 未解決」）を含めてください。

完了条件：差分確認用の cron が存在し（hermes cron list に表示され）、そのプロンプトにベースラインの数値、適用した変更の一覧、合格基準が含まれていること。

注意点

1. state.db は読み取り専用で開きます（file:...?mode=ro、uri=True、パスは URL エンコードします）。稼働中のファイルで、数百 MB になることもあります。書き込み接続はロックを引き起こすおそれがあります。
2. input_tokens の意味はプロバイダーのワイヤ形式によって異なります。 Anthropic 形式のワイヤでは、cache_read_tokens は input に追加して報告されます（実際のプロンプト ≈ input + cache_read + cache_write）。OpenAI 形式の prompt_tokens では、キャッシュされたトークンは内訳として含まれます。実測での確認方法：ある行で cache_read > input_tokens なら、そのプロバイダーはキャッシュを input に含めていません。プロバイダー間で生の input_tokens を比較してはいけません。billing_provider ごとに実効プロンプトを計算してください。キャッシュ共有率は、同じ規則の範囲内でのみ意味があります。
3. jobs.json には確認されている形式が2種類あります — {"jobs": [...], "updated_at": ...} と、リスト単体です。編集前と編集後の両方で、どちらの形式にも対応してください。書き込み後は、コンテナーの形式を確認してください。
4. キャッシュ共有率が 0 でも、キャッシュがないとは限りません。 一部のプロバイダーは usage にキャッシュ済みトークンのフィールドを返しません（そのようなプロバイダーの1つでは、2026-09-02 に確認したところ、usage オブジェクトには prompt/completion/total だけが含まれていました）。そのため、ローカルのテレメトリーではキャッシュが把握できません。呼び出しごとにキャッシュ読み取りを報告するプロバイダーもあります。実態を確認するには、各プロバイダーのドキュメントと課金ダッシュボードを確認してください。
5. sessions.input_tokens と session_model_usage の差は、タイミングだけでなく帰属方法にもあります。 タスク行はセッションごとの累積値で、last_seen に帰属します（ウィンドウ前の使用量がウィンドウ内に含まれます）。一方、セッションごとのランキングは開始日／アクティビティ日を使用します。合計が一致しない場合は、偏りの方向を明記してください。2つの合計を1つの合計に混在させてはいけません。
6. token_count 列が NULL のことはよくあります — LENGTH() でコンテンツのサイズを測定し、文字数 ≈ トークン数/4 はあくまで大まかな目安であることに留意してください。
7. コンパクションと非アクティブ状態は、保存されたコンテンツに偏りをもたらします。 active=1 でメッセージをフィルターしてください。コンパクションされた行は要約に置き換えられ、非アクティブな行は送信されなくなっています。保存されているアクティブなコンテンツも、送信されたコンテンツの上限値です（キャプチャ時にすでに切り詰められています）。ライブとコンパクション済みの内訳を見ると、セッションの DB サイズがコンテキストを上回る理由がわかります。
8. 1回の実行が他のすべてを大きく上回ることがあります — 平均を取る前に、cron 台帳で max(prompt_tokens) を確認してください。数百万トークンの実行1回が、健全に見える平均値の中に隠れていることがあります。
9. cron 台帳の prompt_tokens の意味は、実行ごとの値ですが、十分に文書化されていません — 実行ごとに1行ですが、エージェント型の実行では、コンテキストを各呼び出しで再送信しながら、多数の API 呼び出しが行われます。avg tokens/fire は実際の cron 入力の下限値として扱い、精度が重要な場合は、その実行のセッション行と照合してください。
10. 呼び出しごとの平均は加重する必要があります — セッションごとの比率の AVG ではなく、SUM(input)/SUM(calls) を使ってください。そうしない場合、200回呼び出すセッションと10,000回呼び出すセッションが同じ重みで扱われます。

検証チェックリスト

• 関連するすべてのプロファイル DB（デフォルトおよびアクティブなプロファイル）に対して、スクリプトを読み取り専用で実行した
• 帰属の偏りを明記したうえで合計を相互確認した（last_seen によるタスク行と、開始日／アクティビティ日によるセッション）
• 使用量上位の各項目について、事前確認済みの対策を割り当てるか、「ローカルでの対策なし」と記した
• 提案する各対策を事前確認した：キーが存在すること、現在の値を実環境で読み取ったこと、仕組みを確認したこと
• 適用した変更を読み戻して検証した（hermes config get、cron jobs.json の再解析）
• 古いプロンプト／設定をバックアップし、保存先のパスを記録した
• ベースラインと合格基準をプロンプトに含めて、差分確認 cron をスケジュールした