CH 29 · オブザーバビリティとコンテキスト管理
本章のゴール
Agent が動き出してから、迟早こうした疑問にぶつかります：なぜさっきあの判断をしたのか？ このラウンドは何 Token かかった？ 長会話が遅く・高くなるのはどうしよう？
dsh のやり方は、Agent の一歩一歩をあなたの前に並べます——何を見たか、何を考えたか、何をしたか、何コストがかかったか、すべて追跡可能にします。前の CH 04 で軌跡画面の基礎を扱い、CH 16 でキャッシュヒット率に触れました。本章でオブザーバビリティとパフォーマンスを完全にはっきりさせます：軌跡の見方、セッションログの保管場所、Token とキャッシュ指標の読み方、コンテキストの管理方法。これらを習得すれば、「使える」から「効率良く、安定して使える」へ進むことができます。
軌跡（Trajectory）：Agent の完全なフロー記録
軌跡とは何か
一般的な Agent ツールが表示するのは「チャット履歴」——あなたが言ったこと、Agent が返したこと。しかしその間で何が起きたか？ どのファイルを読んだか、どのツールを呼んだか、ツールは何を返したか、なぜこのツールを呼んであのツールでなかったのか——これらはチャットビューには見えません。
軌跡（Trajectory）はこの問題を解決します：Agent の完全な実行過程をタイムラインで記録するもので、「モデル視点のフロー記録」であり、「ユーザー視点のチャット履歴」ではありません。
記録される内容：
| カテゴリ | 記録内容 |
|---|---|
| システムプロンプト | 各リクエストでモデルに送られた完全な system prompt |
| ユーザー入力 | 送信したメッセージ、注入されたコンテキスト |
| モデルリクエスト | モデルに送られた完全な内容、モデルが返した完全な内容 |
| ツール呼び出し | どのツールを呼んだか、パラメータは何、戻り値は何 |
| サブ Agent スケジューリング | サブ Agent を何体起動したか、各々が何をしたか、結果がどう集約されたか |
| 承認インタラクション | どの操作が承認を求めたか、あなたが許可したか拒否したか |
これらすべては単一の追記専用セッションログに書き込まれます——追加のみで改変なし、記録の完全性と監査可能性を保証します。
軌跡の閲覧場所
Web UI のセッション画面の上部に**軌跡（Trajectory）**タブがあるので、クリックして開きます。
画面はブラウザの開発者ツールのネットワークパネルのような見た目です：
- 上部のタイムライン：実際の開始・終了時刻に従い左から右へ描かれ、各ラウンドのリクエストが 1 区間を占める
- 左のイベント一覧：1 行 1 記録、ターンごとにグループ化され、種類（LLM / TOOL / SUBAGENT / APPROVAL）が表示される
- 右の詳細パネル：記録をクリックすると展開され、完全な内容が見られる——ツール呼び出しの Schema / Payload / Result、モデルリクエストの完全なプロンプトとレスポンス
軌跡は何に使えるか
- トラブルシュート：Agent が想定外の挙動をした？ 軌跡を遡って、そのとき何が入力されていたか、なぜその判断をしたかを確認する。「AI が暴走した」の 90% は軌跡から原因を特定できる——大抵はあなたが気づかなかったファイルを読み込んでいた、あるいはツールが異常値を返していた。
- レビュー：タスクがうまく進んだ/進まなかった、軌跡を遡ってどのステップが転機だったか、どのステップが Token を浪費したかを確認する。次回はプロンプトや流れを最適化できる。
- 実験の再現：Agent 研究を行う際、軌跡は完全な実験記録である——同じ入力、同じツール、同じモデルバージョンで同じ結果を再現できる。
- 監査：チーム共有時、軌跡は「いつ・なぜこのファイルを変更したか」に答えられる——git log より粒度が細かく、「なぜ変更したか」まで記録されている。
セッションログ：保管場所と使い方
軌跡データは最終的にメモリだけでなくローカルファイルにも落ちます。
保存場所
すべてのセッションは ~/.dsh/sessions/ ディレクトリ（Windows：C:\Users\<your-username>\.dsh\sessions\）に保存され、ワークスペースディレクトリごとに整理されます。
ワークスペースディレクトリ名はパスをエスケープした形式になっています——-- で囲み、パスの区切り文字は - に置換、特殊文字は URL エンコード。たとえばワークスペース E:\software-workspace\DeepSeek harness demo はディレクトリ名 --E-software-workspace-DeepSeek~0020harness~0020demo-- に対応します。
各セッションはサブディレクトリで、名前は session-<uuid> 形式（Web UI 作成）または純粋な <uuid>（headless 実行）となっており、session.jsonl.zstd（zstd 圧縮の JSONL、1 行 1 イベント）が含まれます。
~/.dsh/sessions/
├── --E-software-workspace-DeepSeek~0020harness~0020demo--/
│ ├── session-05da13b1-c7bf-4f42-843b-.../
│ │ └── session.jsonl.zstd
│ ├── session-06451c43-35fb-4338-bc87-.../
│ │ └── session.jsonl.zstd
│ └── 37e884fa-7c73-40fa-81fc-.../ ← headless で実行されたセッション
│ └── session.jsonl.zstd
└── --E-software-workspace-doubaowork-DeepSeekHarnessGuide--/
└── session-f417b4dd-3c8f-4098-85.../
└── session.jsonl.zstdセッションの 3 つの機能
このログに基づき、dsh は 3 つの操作をサポートします：
- 再開（Resume）：dsh を閉じて再度開いても、前回のセッションが残っており、チャットを続けられる——ログが永続化されており、メモリ内ではないため。
- 分岐（Fork）：履歴メッセージの下にある分岐アイコンをクリックすると、そのメッセージから新しい経路を開始できる。元のセッションには触れない。たとえば Agent がステップ 5 まで進み方向が間違っていると感じたら、ステップ 4 から分岐して別のプロンプトを試せる。元のセッションは保存される。分岐で生まれた新セッションは名前に
(1)、(2)などの接尾辞が付き、元と区別される。 - 再生（Replay）：セッションのイベントストリームを再生し、各ステップの入力と出力を確認する。プラグインのデバッグや問題の再現に向く。
パフォーマンス指標：Token、キャッシュ、コンテキスト
dsh は画面のあちこちに主要なパフォーマンス指標をリアルタイム表示します。これらを読めるようになれば、コストと速度をコントロールできます。
Token 使用量
各ラウンドのリクエスト後、画面下部にそのラウンドの Token 統計が表示されます：
- Input Token：モデルに送られたトークン総数（システムプロンプト、会話履歴、ツール結果を含む）
- Output Token：モデルが生成したトークン
- Cache hit Token：入力のうち DeepSeek のコンテキストキャッシュがヒットした部分
累積使用量はセッション統計にあります——セッション全体で何 Token 消費したか、いくらコストがかかったか。
コンテキスト占有率
入力ボックスの右側にリングがあり、現在のコンテキスト占有率パーセンテージを表示します。これは dsh 独自デザインで、「あとどのくらいのコンテキスト余地があるか」をリアルタイムで見える化します。
コンテキストは有限です（モデルによりウィンドウサイズは異なるが、一般的に 128K から）。占有率が 100% に近づくと、dsh は自動でコンテキストを圧縮します——古い履歴を要約にまとめ、複数ターンの会話に置き換えて、ウィンドウ超過で止まらずに会話が続くようにします。
自動圧縮はフォールバック機構です。そのためより推奨されるやり方は：適切なタイミングで自分で圧縮をトリガーする——入力ボックスで /compact コマンドを打てば、dsh は即座に現在の会話を要約に圧縮し、複数ターンの履歴と置き換えます。自分のリズムで圧縮すれば、重要な情報を失わずに済みます。
占有率がほぼ埋まったら、2 つの選択肢：/compact で手動圧縮する、もしくは新しいセッションを開く。
コンテキスト管理：長セッションを落とさずに保つ方法
Agent セッションには自然な問題があります：長くチャットするほど Token を消費し、モデルは前の方を「覚えて」いる割合が減る。dsh はこれを管理するツールをいくつか用意しています。
いつ新しいセッションを開くか
すべてのタスクを 1 つのセッションでやる必要はありません。以下のような状況では新規セッションを開くべきです：
- タスクの種類が変わった：さっきまでコードを書いていたが次は PPT を作る——新規セッションを開く、コードのコンテキストに PPT タスクを汚させない
- ワークスペースが変わった：プロジェクトディレクトリを切り替えた——新規セッションを開く、dsh のセッションはワークスペースに紐付くため
- コンテキスト占有率が 70% 超：このまま進めるとモデルが古い内容を落とし、反応も遅くなる——突然モデルが馬鹿になったと感じることがあるがそれが原因。新規セッションを開くか、
/compactで先に圧縮する
コスト抑制の習慣
- 1 つのセッションで全部やらない——タスクごとにセッションを分割すれば、各セッションはコンテキストが短く、キャッシュヒット率が高く、コストが低い
- 大きなファイルを繰り返し読まない——Agent が 1000 行のファイルを読み込むたびに Token を消費する。一度読んだら、キーとなる情報を要約ファイルに書かせ、以降は要約だけ読む
- 適切なモデルを使う——簡単なタスクは flash、複雑な推論は pro、視覚タスクは vision——何にでも最高額モデルを使わない
- 累積使用量を定期的に確認——セッション統計に総 Token と推定コストが出る、月末の請求書で驚かないように
この章で学んだこと
以下の項目を自分で達成できれば合格です：
- [ ] 軌跡とは何か、どこで見るか、軌跡に何が記録されているかを知っている
- [ ] セッションログが
~/.dsh/sessions/に保存され、再開・分岐・再生をサポートすることを知っている - [ ] Token 統計における Input / Output / Cache hit を理解できる
- [ ] コンテキスト占有率の表示場所と、ほぼ埋まったときの対処を知っている
- [ ]
/compactコマンドの使い方を理解し、いつ手動圧縮すべきか知っている - [ ] コスト抑制の習慣を 3 つ以上挙げられる