DeepSeek Harness のコンテキスト圧縮を13フレームで分解
ソース解説動画をコマごとに追い、dsh の圧縮がいつ発火し、何を切り詰め、何を要約し、追記専用ログがどうセッションを再構築するかを整理します。
最終更新: 2026-10-15
本ページは、ソースコードレベルで DeepSeek Harness のコンテキスト管理と圧縮を解説する動画を、コマごとに読み解くものです。最初に、動画の性質を確認しておきます：原動画はナレーション付きの仕組み解説アニメーションで、スライドに圧縮パイプラインを一枚ずつ描くスタイルであり、製品 UI の実機録画ではありません。だからこそ各機構が1枚にきれいに分離されており、アーキテクチャの教科書として読めます。
文中の数値——デフォルト発火しきい値 80%、8192 コードポイントのトリム（先頭 4096 + 末尾 1024 を保持）、直近 16% の原文保持——は 2026-09-23 時点で deepseek-harness 公式リポジトリのドキュメントと突き合わせ、一致を確認しています（thresholdRatio 0.8、thresholdChars 8192、retainRatio 0.16）。公式ドキュが詳細を定義しない部分（チェックポイントの8分類など）は、動画作者・小木頭によるソース読解の図示であり、本文中でその旨を明示しています。
まずは要約から
- ▸圧縮は dsh に組み込みではなくプラグイン能力：ctx.compaction が能力インターフェース、compaction-basic がデフォルト実装。コンテキストがウィンドウの約 80% に達するか、サーバー側の超過報告、あるいはアイドル時の /compact 入力で発火します。
- ▸要約の前にトリム：8192 コードポイントを超えるツール結果は先頭 4096 と末尾 1024 だけを残し、トリム後に収まれば要約のモデル呼び出し自体を省略します。
- ▸圧縮された履歴は構造化チェックポイントに変わり、直近約 16% は原文のまま保持。永続ログが全イベントを残すため、モデルのビューはいつでもリプレイで再構築できます。
圧縮パイプライン、12ステップ
アーキテクチャの中の圧縮
- 1
まず位置：DeepSeek のリクエストには圧縮ステージがある
動画はリクエスト構造の比較から始まります。Codex 方式のリクエストは入力 + コンテキスト + モデル呼び出し。DeepSeek Harness はこの間に専用の圧縮ステージを挿入します。この1枚が動画全体の地図——圧縮は事後対処ではなく、リクエストパイプラインの正規の一段だという話です。
パイプラインのコンテキストとモデル呼び出しの間に、圧縮の一段が増える。0:32 の場面を見る - 2
登場人物：1つの能力を複数プラグインで分担
圧縮はケイパビリティシームとして分割されています。/compact コマンドが手動入口、ctx.compaction が能力インターフェース、その背後のデフォルト実装が compaction-basic。周囲に任意の相棒が2つ——圧力を測る token meter と、ツール結果を切り詰める tool result pruner です。compaction-basic を差し替えても他はそのまま動きます。
$ctx.compaction$dsh-compaction$compaction-basic$command-compact
能力の継ぎ目1本に、5つの役割：コマンド、インターフェース、デフォルト実装、そして2つの任意パートナー。2:18 の場面を見る - 3
3つのトリガーを覚える
圧縮の起点は3つ。毎リクエスト前の pre-step チェックは推定圧力をデフォルト 80% のしきい値（モデル別に設定可）と比較。サーバーがすでにコンテキスト超過を報告している場合は回復フローに入り、通常しきい値をスキップして先に現場を修復。エージェントのアイドル中に /compact を打てば、80% を待たずに随時整理します。
$agent/pre-step$context-overflow$/compact · agent idle
発火の道は3本。80% を本当に待つのは1本だけ。3:50 の場面を見る - 4
メーターの読み方：プロバイダー値 + 変化の推定
token meter は推定であることを隠しません。直近の成功呼び出しでプロバイダーが報告した使用量をアンカーにし、以降の可視コンテンツの変化を積算します——新規メッセージは増加、置換は減少にもなり得る。スライドのバーは定性イメージで、実測比率ではありません。
メーターは推定：最後の公式読み取りに、その後のドリフトを足したもの。4:20 の場面を見る
トリム・選択・要約
- 5
測る前に、まずログを切る
最初のレバーは要約ではなく削除。巨大なツール結果1本でコンテキストの半分以上を占めることは珍しくなく、中間部分を切り落とすだけで圧力がしきい値を下回ることがあります。以降の章の機構はすべて、この最も安い工程が済んだ前提で動きます。
まず切る。巨大なツール結果1本が問題の全部かもしれない。1:15 の場面を見る - 6
プリナー分解：8192 コードポイント、4096 + 1024 を保持
テキストが 8192 Unicode コードポイントを超えたツール結果（3つの Web プリセットの現在設定）は書き換えられます：先頭 4096 コードポイント、トリムマーカー、末尾 1024。単位はトークンではなくコードポイントで、この工程はモデルを一切呼びません。数値は公式 compaction-tool-result-pruner のデフォルト（thresholdChars 8192、headChars 4096、tailChars 1024）と一致しています。
$threshold: 8192 code points$keep head 4096 + tail 1024
しきい値は 8192 コードポイント。先頭 4096、マーカー、末尾 1024。5:40 の場面を見る - 7
レンジ選択：直近 16% を原文保持、切断線はペアを避ける
トリム後も圧力が超過なら compaction-basic がレンジを選びます。最新メッセージから遡り、ウィンドウ予算の約 16%（公式 retainRatio のデフォルト）に達するまで原文を保持。切断線は必ずツール呼び出しとその結果の外側に引かれ、ペアが分断されません。メッセージノード単位の累計なので実際の保持量は 16% を少し超え得ます。この時点では範囲が選ばれただけで、要約はまだ生成されていません。
最新から遡る。切断線が呼び出しと結果の間を通ることはない。6:00 の場面を見る - 8
チェックポイント生成：compaction/start と8分類
要約は追記指示として実行されます。リクエストは元の system・tools・選ばれた旧メッセージを保持したまま、末尾に user メッセージを追加し、会話を構造化チェックポイントへ整理するよう指示。動画はこれを8分類で図示します——ユーザーの目標と意図、重要な技術概念、ファイルとコード、エラーと修正、未完了タスク、現在の作業、次のアクション、重要な背景と制約。公式ドキュもチェックポイント前文の存在を確認できますが、8分類の内訳は作者の模式的読解です。
$compaction/start
要約指示は構造化チェックポイントを求める——8分類は作者による模式図。7:05 の場面を見る - 9
合格した要約だけが置換を許される
要約が履歴を置き換えるには3つの関門があります。モデルが最後まで完了し空でないテキストを返したこと（エラー・中断・出力上限での打ち切りは失敗）。text コンテンツのみを保持すること——reasoning と tool calls はチェックポイントに入らず、画像出力は即拒否。ラッパー込みの要約推定量が置換対象区間より小さいこと。
どれか1つでも落ちれば、要約はモデルの前に出られない。7:56 の場面を見る
置換・リプレイと限界
- 10
ログは追記、モデルのビューが置き換わる
成功すると、永続ログに start・summary・checkpoint・end の一連のイベントが追記され、モデルの可視履歴はサーフェス置換で一新されます。スライドには surfaceOp の置換操作として描かれます。チェックポイントが先、保持された直近原文が後。上流では何も削除されず、ログが完全な記録であり続けます。
$surfaceOp: { op: 'replace' }$compaction/start · summary · end
ログは増える一方。差し替えられるのはモデルのビューの側。8:48 の場面を見る - 11
回復はログのリプレイで
ログが追記専用かつ完全である限り、回復に元のコンテキストは不要です。イベントを順に読み返し、surfaceOp の append / replace を1件ずつ適用すれば、旧コンテンツ→チェックポイント→直近原文の順でモデルビューが再構築されます。圧縮済みセッションが再起動に耐えるのはこの仕組みのおかげです。
$surfaceOp: append / replace
回復は追記専用ログの決定論的リプレイ。9:05 の場面を見る - 12
まとめ：安定したインターフェース、交換可能な実装
最終スライドはパイプラインを4つの動詞に圧縮します——圧力を測る、ツール結果をトリムする、必要なら要約する、モデルビューを置き換える。そして役割分担：ctx.compaction が安定したインターフェース、compaction-basic が現行のデフォルト実装、agent loop・token meter・/compact 入口がその周囲。どの部品も他を壊さずに進化できます。
動詞4つ、安定したインターフェース1本、交換可能な実装1つ。10:00 の場面を見る
メーターを読む：実際の UI での Token usage
ここまでは仕組みの話。ここからは実際の画面です。以下の 2 枚は AISeeKing の週次レビューから（録画時点は 0.1.5-rc.1 開発者プレビュー。現在のリリースでは表記が多少異なる場合があります）。累計 300 万トークンの実行を終えたセッションの Token usage ポップアップは、キャッシュヒット 99%、非キャッシュ入力 33,671、キャッシュ済み入力 2,931,968、出力 50,350 と内訳を示します。ウィンドウを安定させ、書き換えず追記する——接頭辞が繰り返しキャッシュに命中するのはそのためで、圧縮してきた見返りは、このメーターに表れます。
公式 0.1.7 との接点
このページが分解するのはプラグインパイプラインですが、公式 0.1.7 系は同じ継ぎ目を製品側から磨いています——アルファのリリースノートは、プロアクティブ圧縮のための出力容量とコンテキストヘッドルームの確保、待機タイムアウト後の長時間コマンドのバックグラウンド継続を明記。長時間タスクの実際のコストを知るには、 トークン使用量とコスト追跡ガイドを読む.
内蔵 compaction-basic パッケージと headroomTokens
0.2.x 系では圧縮が内蔵パッケージ——packages/compaction/compaction-basic——として同梱されており、この公式パッケージ名自体が検索語になっています。重要な調整ポイントは 2 つ。まず自動スイッチ：公式ディスカッション #8774 で示された設定名では、バックグラウンドのトリガーは compaction-basic.auto で、これをオフにすると自動要約が停止し、/compact は手動でいつでも使えます。
もう 1 つの調整ポイントは headroomTokens——要約が着地するための予約領域です。公式ディスカッション #8785 が厄介な点を記録しています：デフォルトの 65,536 はウィンドウサイズに合わせて縮まないため、短いコンテキストのモデルでは予約領域自体が守るべき履歴を押し出しかねません——小さいウィンドウでは明示的に設定してください。予約を調整するより天井を上げたいなら、tyan66666/billion-context-dsh（★124）がコミュニティの答えです。
コンテキスト管理・圧縮ツール：内蔵とコミュニティ 3 本の比較
ここまで解説した圧縮パイプラインは内蔵の仕組みです。その周りには、コンテキスト管理プラグインの小さな生態系が育っています。ウィンドウの中身を見える化するダッシュボード、代替圧縮エンジン、そしてハードリミットのガード。以下のスター数は 2026-10-08 に GitHub API で確認しました――どれも、拡張あるいは置き換える対象である内蔵 compaction-basic と比べて評価してください。
基準線：内蔵 compaction-basic
このページで分解したデフォルト実装そのものです。3 つのトリガー（80% 事前チェック、サーバー側オーバーフロー、手動 /compact）、8192 コードポイントのツール結果トリム、16% の直近保持、チェックポイントの差し替えと再生。dsh に同梱されインストール不要――以下のコミュニティツールはすべてこれを基準に調整したものなので、まず内蔵が正常に動くことを確認してから重ねてください。
bowenliang123/dsh-context（★1,892）――まずコンテキストを見える化
他を大きく引き離すクラスタの筆頭：Context ダッシュボード・ブラウザー・サイドバーに context コマンドを添えて、ウィンドウの中身の内訳を開示します――統計、構成、そして圧縮・プリューニングイベントの推移。自ら圧縮は行わず、内蔵圧縮が仕事をしているか見届ける観測レイヤーです。このセクションで 1 つだけ入れるならこれ。
yoza10635/dsh-argp（★9）――監査できる圧縮
別エンジン、別の契約：LLM は提案するだけで、裁定は決定論的なガードが行います。逐語ガード付きのアトム単位シュリンク、モデル呼び出しゼロの遅延参照グラフ追い出し、追記型ログからのバイト単位の再呼び出し――約束した圧縮率が正確に実現され、履歴は決して破壊されません。要約への疑いが信頼を上回るならこちら。
AllShadowAnan/dsh-context-compressor（★0）――絶対的な天井
3 本の中で最も新しいもの：専用設定ページでコンテキストの絶対上限を設定すると、セッションがその線に達した瞬間に自動圧縮します――80% デフォルトに依存しないハードストップ。実ウィンドウが公称より小さいモデルのために作られたもので、まさに次の FAQ で分解する故障の種類です。
メモリとコンテキスト系のおすすめ――ナレッジグラフ、セッション横断リコール、コンテキストエンジニアリング――は メモリ＆コンテキスト コレクション.
手動 /compact：DeepSeek Harness の圧縮を自分のタイミングで（0.2.1-alpha.3）
0.2.1-alpha.3（alpha チャンネル、2026-10-14 公開）で圧縮は一人前のコマンドになりました。Web・デスクトップ版では /compact で現在の会話を手動圧縮でき、ミニマルモードは長い会話を自動で圧縮します（画像の読み取りにも対応）。中身で回っているのはこのページで分解したのと同じパイプライン——同じトリム、同じチェックポイント、同じ置換とリプレイ——トリガーが圧力計からあなたに移っただけです。
バージョン確認：alpha.3 は npm の alpha タグで、stable latest は依然 0.2.0-rc.2 です。Web/デスクトップに /compact がまだ無いのはそのため。このページの残りの内容（しきい値、トリム、リプレイ）は、stable にすでに同梱されている compaction-basic パッケージの話で、エージェント待機中の手動トリガーはステップ 3 のとおりです。
手動実行が効く場面：すでに重いセッションに長い文書を流し込む前。ツール出力が密集した作業の後で、逐字記録がもう要らないと分かっているとき。そして使用メーターの圧力が高いのに、約 80% の自動トリガーがまだ来ないとき。
ディスカッションが計測したもの：圧縮の実際のコストと故障形態
公式ディスカッションは、圧縮を設計から台帳に変えました。以下は実測の発見とディスカッション番号の対です。生のレポートは deepseek-ai/deepseek-harness リポジトリの Discussions タブにあります。
#9629 —— 圧縮 1 回で約 25 万トークンの非キャッシュ消費
圧縮サマリーのリクエストにはセッションの reasoningEffort が乗っておらず、キャッシュキーが前後のメインリクエストと異なります。結果、ウィンドウ全体を再読み込みするこの 1 発だけがキャッシュに当たりません。報告者の環境（opencode-go ルート、kernel 0.1.7-rc.2）では、圧縮ごとに約 25 万トークンの避けられたはずの非キャッシュ消費でした。
#9643 —— 毎ターンの動的注入が KV プレフィックスキャッシュを無効化
毎ターン注入されるコンテンツ（メモリ・コンテキスト系プラグイン）が会話履歴の前に置かれるため、プロンプトのプレフィックスが前のリクエストと一致しません。ローカルの LM Studio エンジンの実測では KV プレフィックス再利用は恒常的に 0%、毎ターン 9 万〜14 万トークンをフルで prefill し直しています。レポートは注入をプロンプト末尾へ移すことを提案。ローカルモデルで GPU 時間が爆発したら、まずこの 1 件です。
#9404 —— ウィンドウ 40% で自動圧縮のループ
0.2.1-alpha.2 とローカル llama.cpp モデル（96k ウィンドウ）の組み合わせで、約 3.79 万トークン（約 40%）から自動圧縮が始まり、連続で再発火。圧縮ログが流れ続けて会話が前に進まなくなりました。
#9544 —— モデルのウィンドウを超えたセッションはそのまま死亡
長時間稼働のセッションがモデルのウィンドウを超えると、以降の毎ターンが 400 を返します。再起動すると UI 全体がフル再生され、圧縮はデッドロック、予定タスクは静かに失敗——製品内に復活手段はありません。
#9635 —— オーバーフローしても手動復旧の道がない
alpha.2 での三重故障：トークン見積もりの過小評価、サマライザー自身のリプレイがウィンドウを再び溢れる、そして手動復旧手段なし——セッションは恒久的に使用不能に。#9404・#9544 と合わせ、圧縮の挙動がおかしいとき最初に照合すべきループ群です。
よくある質問
コスト、消失の範囲、限界——フレームだけでは分からない部分。
圧縮でトークンは余計に消えますか？
はい、要約1回につきモデル呼び出し1回分です。チェックポイント指示がモデルへ送られ、テキストの回答だけが保持されます。対照的に、巨大ツール結果のトリムはノーコスト——プリナーはモデルを呼ばず、トリムだけで圧力がしきい値以下に収まれば要約呼び出し自体がスキップされます。
手動の /compact と何が違いますか？
パイプラインは同じ、トリガーが違うだけです。自動圧縮は約 80% の圧力しきい値（またはサーバー超過）を待ち、/compact はアイドル中にしきい値に関係なく即実行。コマンドは圧縮した項目数と推定トークン削減を報告し、実行中に送ったメッセージは完了後に処理されます。
圧縮後、コンテキストは失われますか？
古いターンの原文はモデルの視界から外れますが、無にはなりません。目標・ファイル・エラー・未完了タスクをカバーする構造化チェックポイントに整理され、直近のスライス（デフォルトでウィンドウの 16%）は原文のまま、永続ログも全イベントを保持します。失われるのはモデルによる旧原文の直接参照であって、記録自体ではありません。
これらの数値は固定ですか？
いいえ。80% は thresholdRatio、16% は retainRatio のデフォルトで、プロバイダー・モデルごとに設定可能です。プリナーの 8192/4096/1024 コードポイント予算も設定できます。本ページの数値は 2026-09-23 時点の公式パッケージドキュとの照合値です。定数ではなく現行デフォルトとして扱ってください。
圧縮でも救えない場合は？
システムプロンプト、ツール定義、セッション接頭辞は縮められず、1本の巨大ツール呼び出しのような分割不能な単位も分割されません——動画が硬い境界として挙げる点です。単一の成果物が予算を超えるなら、タスクを分割するか、サブエージェントやバックグラウンドジョブに作業を移し、メインセッションには結論だけ受け取らせましょう。
自動コンテキスト圧縮をオフにするには？
compaction-basic.auto を false にします——公式ディスカッション #8774 で示された設定名で、この投稿は Web GUI にワンクリックスイッチを加える提案でもあります。オフにするとバックグラウンド要約が止まり、/compact は手動実行のまま残ります。ついでに headroomTokens も確認を：デフォルトの 65,536 はウィンドウに応じて縮まず（#8785）、短いコンテキストのモデルではこの予約自体が圧力の種になります。トレードオフには注意：自動圧縮なしでは長いセッションはオーバーフロー閾値に近づきます。越えたときに会話を終わらせるのは dsh ではなくプロバイダーです。
圧縮が何度も走り続ける――圧縮ループになってしまった？
症状：圧縮が終わった直後のリクエストでまた圧縮が走り、ループがいつまでも収束しない。メカニズムレベルの報告は公式ディスカッション #9041 です。ルートが異常に大きな maxTokens を宣言していると、自動トリガーのしきい値計算が崩れ、毎ターンが過圧と判定されて自動圧縮が永久に再実行されます。修正が来るまでの回避策：そのルートの maxTokens を下げるか、妥当な値のルートへタスクを移す。compaction-basic.auto: false でバックグラウンドトリガーを切り、必要なときは手動 /compact。追記型ログは残しておく――ループの有無にかかわらず再生リカバリーは機能します。
圧縮がまったく発火しない――なのにプロバイダーにセッションを拒否されるのはなぜ？
公式ディスカッション #9022 が記録したサイレント失敗です：あるモデルの宣言 contextWindow が dsh のモデル情報リゾルバーに届いていないケース。圧力推定がしきい値を超えず、自動圧縮は始まらず、最初に見えるサインはゲートウェイのコンテキストオーバーフロー拒否が曖昧なエラーメッセージを着ているものです。まずモデルのコンテキストウィンドウが本当に登録されているか確認し（モデル切替ガイドが解決チェーンを解説）、つなぎで手動 /compact。長いセッションの突然の 400 は、まずオーバーフローとして読み、クォータはその次です。
コンテキストがいっぱいになったらどうする？会話の移行が必要？
公式ディスカッション #9071 にそのまま投稿された質問です。短い答え：移行は不要です。dsh は毎リクエスト前に圧力を確認し、上限に近づくと圧縮します――古いターンは構造化チェックポイントになり、最近の末尾は逐語保持、追記型ログにすべてが残るので、セッションはその場で続きます。上のループやサイレント失敗で固まってしまったら：エージェントのアイドル中に /compact を打つか、新しいセッションを開始してチェックポイントに結論を持ち越させます。生のセッションファイルをどうしても移したいときはエクスポートツールが使えます。
Web UI の「Cache hit」のパーセントは何？
このピルは、入力のうちどれだけがプロバイダーのプロンプトキャッシュから提供され、全額の再計算を避けられたかを示します――上の Token usage の静止画は 99% の実例で、入力・キャッシュ読み書き・出力に分けて表示されます。キャッシュ読みは新規入力の一部の料金で済むため、高いヒット率は気づかない最安の高速化です。意味づけはプロバイダー依存：ローカル Ollama エンドポイントでは有用な数字が出ないこともあり、DeepSeek ゲートウェイはキャッシュを別項目で計上します――公式ディスカッション #9091 はまさにこのピルの公式ドキュメントを求めた投稿です。圧縮とも相互作用します：安定したプレフィックスはヒットし続け、履歴の書き換えでリセットされます。
自動圧縮を待たずに /compact を手動で打つべきタイミングは？
3 つあります。すでに長いセッションに大きめの追加（長い仕様書、ファイルのダンプ）を流し込む前。ツール出力が密集した作業の後で、逐字記録がもう不要なとき。そして使用メーターの圧力が高いのに約 80% トリガーが来ないとき。手動実行も同じ濃縮パイプラインなので、余計なものは失われません。なお Web/デスクトップの /compact コマンド自体は 0.2.1-alpha.3（alpha チャンネル）の機能です。stable では compaction-basic がエージェント待機中の手動トリガーに対応しており、上のステップ 3 のとおりです。
圧縮したのに、なぜ費用が逆に上がるのか？
圧縮が減らすのはウィンドウの空きであって、支出とは限りません。逆向きに働く実測メカニズムが 2 つ：#9629——サマリーリクエストのキャッシュキーが異なり（reasoningEffort なし）、圧縮のたびにウィンドウ全体を約 25 万トークンの非キャッシュ読み込みとして消化する。#9643——毎ターンの注入が履歴の前に置かれ、ローカルエンジンの KV プレフィックスキャッシュが完全に無効化され、毎ターン prefill をフルで払い直す。請求が圧縮イベントの前後で跳ねるなら、まずこの 2 件と突き合わせてください。
関連ガイド
DSH 学習パスの隣接トラック。
DeepSeek Harness のトークン使用量とコスト追跡
圧縮でどれだけ節約できたかは、測ってこそ。セッション内・ログ・プロバイダーの利用ページで突き合わせましょう。
ガイドを読むDeepSeek Harness の4モード比較
standard・code（PTC）・cordis の各 Web プリセットは同じ圧縮グループを共有。それ以外の違いはこちら。
ガイドを読むDeepSeek Harness トラブルシューティング
コンテキスト超過エラーや圧縮リトライなど、長時間セッションの落とし穴と確実な直し方。
ガイドを読むDeepSeek Harness サブエージェント実践ガイド
1つのコンテキストでは足りないとき：長いタスクをサブエージェントとバックグラウンドジョブに分担させましょう。
ガイドを読むdsh TUI ターミナルガイド
ask_user_question とバックグラウンドジョブが同一画面に並ぶ、長時間タスクに最適なターミナル
ガイドを読むdsh のシステムプロンプトの組み立て方
コンテキストのもう半分：毎ターンのシステムプロンプトの構成順序と、それを書き換えるプラグイン
ガイドを読むdsh のコンテキストウィンドウを可視化
dsh-context プラグインのウォークスルー：構成モーダル、リクエストごとのトレンド、コンテキストの各要素に価格を付けるリクエストブラウザー。
ガイドを読む出典とクレジット
13枚のフレームはすべて同一動画の静止画です——ナレーション付きの仕組み解説アニメーションであり、公式製品 UI や実機録画ではありません。各画像は元動画の該当秒へ深リンクします。同一解説は YouTube では 01Coder、Bilibili では 五里墩茶社 が公開しています（同一作者：小木頭）。