DeepSeek Harnessドキュメントに学ぶ七つの防御パターン
Updated August 16, 2026 · first published August 16, 2026
DeepSeek Harness には短い防御パターン集があり、各項目が一般則として書かれ、それを生んだ具体的なバグが添えられています。リポジトリの中で最も転用しやすいファイルです。どれもハーネスの採用を前提とせず、各項目が自作のエージェントランタイムで実際に現れる失敗モードに対応します。
1. 直交する結果は独立に報告する
あるフラグの報告を別のフラグの条件分岐の中に入れ子にしてはいけません。プロセスはタイムアウトしかつゼロで終了しうる。シグナルを捕捉して綺麗に終了した場合です。タイムアウトを非ゼロ終了の分岐でしか報告しなければ、その結末は消えます。タイムアウト、シグナル、終了コードは独立した事実であり、独立したフィールドが必要です。
コストへの含意：黙って飲み込まれたタイムアウトはリトライループの温床です。呼び出し側は成功と見なし、有用な結果を得られず、また試します。
2. 公開契約を両側で守る
結果に複数の妥当な表現がある場合は、公開する前に正規化します。例として挙がるのはモデルリクエストの失敗です。実装は例外を投げることもエラーの finish チャンクを出すこともあり、API 境界はすべてを終端の finish チャンクへ正規化します。そうしないと、例外を捕まえた呼び出し側は、それがプロバイダ由来か、ミドルウェア由来か、ロギング由来か、自分のコード由来か判別できません。
3. 非同期状態は同期状態ではない
ステータス照会は特定の非同期操作と因果的に結びついていません。ある一通のメッセージの完了信号としてエージェントの idle 状態を待つのは誤りです。キューに並んだ複数の操作が実行区間を共有するため、idle は自分の処理が走る前にも、他人の処理の後にも訪れうるからです。
示されている対処は、実行を所有する自動化の呼び出し側が自分の区間を明示的に定義することです。受信箱への到着から次のエージェント全体の idle までを区間とし、出力を個々のメッセージではなくその区間に帰属させます。待つものが何もない分岐も扱ってください。さもないと呼び出し側は永久にハングします。
誤った idle 信号を待ってハングする自動化ハーネスは、セッションとその子を常駐させ続けます。請求されるのはハングそのものではなく、その背後で生き続けているすべてです。
4. dispose は静止を要求するのではなく到達する
終了を要求することは終了を達成することではありません。dispose は戻る前に子の実際の終了を待ちます。さらにリスナーレジストリは kill シグナルの送信前に閉じ、遅れて届く完了が半ば解体されたシステムへコールバックを撃ち込むのではなく静かに落ちるようにします。
財務的な切れ味が最も明快なパターンです。早期に戻る dispose は、孤児となったサブプロセスと閉じられていないサンドボックスを走らせたままにします。従量課金の計算資源は、親が忘れたからといって止まりません。
5. コールバック例外はディスパッチャで封じ込める
ディスパッチループを try/catch で包みます。一つの購読者の失敗が、ディスパッチの Promise を reject したり、後ろに並ぶリスナーを飢えさせたりしてはいけません。エージェントランタイムでは、飢えるリスナーがしばしば会計処理を担う当のリスナーです。こうして利用実績が、何のエラーも表に出ないまま失われます。
6. 信頼できない出力に環境や予測可能なパスを渡さない
文書中で最も強い規則であり、最初に採用すべきものです。起動するコマンドの環境をスクラブしてください。サブプロセスの開始前に key、secret、token、password に一致する変数を取り除きます。予測可能なパスではなく、所有者のみの権限で作った専用ディレクトリ、ランダムなファイル名、排他的な所有者専用オープンを使います。
脅威は二つあります。環境のスクラブは、ハーネスの資格情報がサブプロセス出力へ漏れ、それをモデルが読むことを防ぎます。いったん読まれれば、その出力はセッションログとコンテキストウィンドウの中です。ランダムな名前と排他生成は、共有一時ディレクトリでのシンボリックリンク競合を塞ぎます。
7. リンク状のパスは unlink する
削除前にパスがシンボリックリンクかを確認し、辿らずにリンクそのものを削除します。再帰削除は実在すると確認できたディレクトリに限ります。リンクを辿って対象へ入り込むことがあり、ジャンクションでは例外を投げるためです。自分が作った以上のものを消すクリーンアップコードは、被害に上限のない失敗モードです。
このリストの使い方
- パターン 1 と 4 を今日、サブプロセスとサンドボックスの後始末コードへ持ち込む。金が漏れるのはそこです。
- パターン 6 を、モデルが出力を読むプロセスを起動するあらゆる箇所へ持ち込む。
- パターン 3 を自動化層へ、とくに待機が「エージェントが idle になるまで」と表現されている箇所へ持ち込む。
- パターン 5 をテレメトリ基盤へ持ち込み、失敗するリスナーが会計用リスナーを飢えさせないことを確認する。
Related
Want this applied to your own LLM spend? FinOps LLM runs a free audit of your AI costs and shows where the savings are. Book free audit →