CH 05 · コマンドラインで動かす:headless + CLI
この章の目標
前章までは Web UI の中でクリックばかりでした。この章では形態を変えます:界面は一切開かず、ターミナルで 1 コマンド、dsh に 1 つの仕事をさせて終了—— これが headless です。ついでに dsh という「起動器」が一体どの扉を開けられるかも一通りなぞります。今後スクリプトを書いたり、CI に掛けたり、バッチで仕事をさせたりする時に全部使えます。
まず理解する:dsh は複数エントリの起動器
dsh は「あの Web ページ」だけではありません。dsh は起動器(launcher)で、同じ Harness、同じプラグインスタックを、異なる形態で起動できます:
公式が提供するエントリは次の扉だけです:
| エントリ | 用途 | 平たく言えば |
|---|---|---|
web | 界面付き Web ワークベンチ | 前章まで使ったあれ |
headless | 1 タスク実行、回答出力、終了 | コマンドラインのワンショットタスク、本章の主役 |
sdk | JSON-RPC stdio サービス | プログラムからバックエンドとして呼び出せる |
acp | ACP stdio サービス | 自動化クライアントにサービスを提供 |
plugin | profile のプラグイン管理 | プラグインのインストール、特定の profile への依存追加 |
どの扉から入っても、下で動いているのは同じプラグインスタックです。CH 02 で「すべてがプラグイン」と述べたのを、ここで実感できるはずです:「エントリ」自体もプラグインの組み合わせなのですから。
headless:1 文で 1 タスク
headless はコマンドラインモードのワンショットタスクです。使い方はとてもシンプル:
dsh --profile headless "やってほしいこと"挙動は公式の 1 文で言い切っています:新しい永続セッションを開く → タスク実行 → 最終回答を出力 → 終了。
ポイントをいくつか:
- 作業ディレクトリ = コマンド実行時の現在のディレクトリ。コマンドを叩いた場所で作業します(Web UI のように手動で作業ディレクトリを選ぶ必要なし)。
- 「新しい永続セッションを開く」は文字通り:headless を実行するたびに、現在の作業ディレクトリで新しいセッションが開かれ、
$DSH_HOME/sessionsに保存されます。ここで混乱しやすいので整理します —— ファイルレベル:セッションは作業ディレクトリ別に保存され、C:\Users\<ユーザー名>\.dsh\sessions\の下に作業ディレクトリのパスで名前付けされたディレクトリ(例:--E-software-workspace-...--)があり、中に圧縮されたセッションファイルが入っています;Web UI レベル:headless で生成されたセッションは未分類に表示され、特定の作業ディレクトリグループには自動では紐付きません(現在のバージョンでは)。ファイル保存は作業ディレクトリ別、界面表示は未分類 —— これは別物です。下の実操作で見ます。 - デフォルトモデルは
deepseek-v4-flash:CLI シナリオには界面がなく、画像を見る必要もないので、公式デフォルトは最もコスパの良い flash です。 - 界面がなくても完全パイプライン:文脈注入、計画、ツール呼び出し、思考、収束、すべて揃っています、ただ描画しないだけです。
実操作:初めての headless タスク
Agent に「重い仕事」を与えます:リポジトリの読み込み、アーキテクチャのまとめ、中国語ドキュメントの作成。作業ディレクトリで実行:
dsh --profile headless "通读 deepseek-harness 子目录的代码和文档，总结 DeepSeek Harness 的整体架构（插件机制、分层结构、入口、主要包和目录），写一份中文 markdown 架构文档保存到当前目录，文件名用 deepseek-harness-arch.md"実行後の出力:
已完成。我通读了 deepseek-harness 子目录的关键源码与文档，整理成中文架构文档并保存到当前目录。
文件：E:\software-workspace\DeepSeek harness demo\deepseek-harness-arch.md（约 295 行）Web UI に戻ってこのセッションを確認:セッション一覧にこのセッションが見つかります、ただし未分類に表示され、特定の作業ディレクトリグループには属していません(headless セッションは自動でグループ化されません、これは現在のバージョンの実際の挙動です):
右側には実行過程が完全に出ています:文脈注入 → 思考 → Pwsh でディレクトリ列挙 → ドキュメント読み取り → ファイル書き込み、底部統計バーは 1 ターン · 18 ステップ、LLM 2m1s、キャッシュヒット 92%、入力 1.1M トークン。
CLI パラメータ早見表
| コマンド | 役割 |
|---|---|
dsh --profile <名前> "タスク" | 指定 profile(headless など)で起動 |
dsh web | --profile web の別名、Web UI 起動 |
dsh --dump-config | 合成後の完全な設定ツリーを出力(トラブルシュート神器、下記参照) |
dsh --dump-default-config | ユーザー変更なしのデフォルト設定ツリーを出力 |
dsh --patch <パス> | profile の上にもう 1 レイヤーの設定を重畳 |
dsh plugin --profile <名前> add <パッケージ> | ある profile にプラグインをインストール |
dsh --help | 起動器自身のヘルプを表示 |
--dump-config は個別に説明の価値あり:これはある profile で最終的に有効になるプラグインの組み合わせを出力します。実走すると:
見えるのは @deepseek-ai/dsh-* のプラグインが積み重なったツリーで、llm(モデル)、session(セッション)、credentials(キー)、session-persistence-jsonl(セッション永続化)…… さらに agent-default-model が deepseek-v4-flash に設定されているのも直接見えます。今後トラブルシュートで「この挙動はどこ由来か」を調べたいときは、まず dump して設定ツリーを見てください。
トラブルシュートのさらに省力な方法:AI 自身にこのコマンドを走らせる。例えばセッションで「dsh --profile headless --dump-config で現在の設定ツリーをチェックして、なぜデフォルトモデルが私が使いたいものと違うのか調べて」「あるプラグインが効いていないか確認して」と聞く —— AI は自分で --dump-config を実行し、設定ツリーを読み、設定を 1 件ずつ追跡して問題を定位してくれます。トラブルシュート時の便利なコンボです。
headless と web はいつ使い分けるか
| シナリオ | どちらを使う |
|---|---|
| Agent の作業を眺め、随时中断し、ステップ・バイ・ステップでトラブルシュートしたい | web |
| スクリプト、CI、定时任务、バッチ処理、結果のみ必要 | headless |
| 他のプログラム/ツールが dsh の能力を呼び出したい | sdk / acp |
| 設定を確認したい、起動問題を排查したい | --dump-config / --help |
公式の境界も覚えてください:headless は毎回 1 タスクのみ実行、対話的な追问はできない、多輪にしたい、動かしているところを見たいなら web に戻ってください。
この章で学んだこと
下の項目を自力で達成できれば合格です:
- [ ] dsh の少なくとも 4 つのエントリ(web / headless / sdk / acp / plugin)の役割を言える
- [ ]
dsh --profile headless "タスク"でコマンドラインのワンショットタスクを走らせ、その挙動を説明できる(新セッション → 実行 → 回答出力 → 終了) - [ ] headless の作業ディレクトリはコマンド実行時の現在のディレクトリであり、毎回永続セッションが開かれること($DSH_HOME/sessions は作業ディレクトリ別に保存、Web UI のセッション一覧では headless セッションは未分類)を知っている
- [ ] headless が适合するシナリオ(バッチ、CI、定时、リポジトリ分析)と公式の境界(1 呼び出し 1 タスクのみ、インタラクションなし)を言える
- [ ]
dsh --dump-configで設定ツリーを確認でき、トラブルシュート用途を知っている - [ ] あるシナリオで web と headless のどちらを使うべきか判断できる