DeepSeek Harness を headless で --json 実行

DeepSeek Harness headless は Web UI ではない

DeepSeek Harness headless が答える問いは npx @deepseek-ai/dsh web とは別です。Web は手元の UI——多くは http://127.0.0.1:3080/——を起動し、止めるまで残ります。Headless は一タスクを走らせ、答えを出して終わります。待ち受けポートは開かず、背後に何も残しません。スクリプトと CI の面であり、初回クリック評価の面ではありません。

上流の表記は dsh --profile headless。公開パッケージでは同じ形が npx @deepseek-ai/dsh --profile headless "run the tests" です。確認した版を釘付けにしてください——2026 年 9 月 28 日時点で npm latest はまだ Pre-release RC——Node と資格情報は インストール。製品の定義は DeepSeek Harness とは。最初の一時間のブラウザ経路は npx クイックスタート。

headless パッケージ README と本ページが食い違えば、README が勝ちます。

一タスク、それから終了

sh
npx @deepseek-ai/dsh --profile headless "トップレベルのファイルを列挙し、README の最初の見出しを引用"

既定では最終答えを stdout に出します。空でない推論は stderr に dsh: reasoning: 見出し付きで出ます。終了コード 0 は最終ターン完了、1 は中断・エラー・使えるターンなし。ターン外の失敗も stderr に dsh: 行を出します。

位置引数を省略するか、単独の - を渡すと、タスクを stdin から渡せます。

sh
{ echo "Summarize these changes:"; git diff --stat; } | npx @deepseek-ai/dsh --profile headless

空の位置引数は用法エラーです。パイプが待っていても stdin を黙って飲みません。- を他のタスク語と混ぜるのも用法エラー。dsh --profile headless --help はヘルプだけ出し、走りません。

これはまだ一発です。同じプロセスに対話の続きはありません。多段は別実行に分けるか、下の --session-id で続けます。

--json は機械向けチャネルであり、Trajectory ではない

--json は stdout の最終テキスト行を改行区切り JSON のイベント流に置き換えます。stderr には dsh: 診断だけが残ります。流は session（今回の身元）で始まり、final で終わります。途中に status、text、thinking、tool_call、tool_result が出ることがあります。

監督プロセス向けの投影として扱い、損失のないセッションログだと思わないでください。末端の final 以外の文字列には上限があります（上流は文字列あたり約 8 KiB と truncated フラグ）。失敗後に開く永続ログは依然 Trajectory——Trajectory ログの読み方 と 可観測性の入門。

形の整った流でも失敗を表せます。ターン内の失敗は final（多くは空）で終わり、error イベントが無いことがあります。終了コード 1 とターン終了理由を信じてください。runner がターン外で上げた失敗は error を書き、final なしで終わります。

--session-id は空履歴を黙って作らない

毎回の実行は既定で新しい session-… 身元です。--json 時、その id は先頭の session イベントに出ます——起動した cwd と一緒に保存してください。後続の呼び出しで --session-id を渡し、その会話を続けます。

未知の id はタスク実行前に失敗します。空履歴を発明しません。別の作業ディレクトリで記録されたセッション、サブエージェントや fork、cwd 欠落、このプロセスで同じ id を掴む生きた Agent、headless プロファイルが組めない preset も拒否します。拒否こそが要点です。CI が他人の会話を黙って駆動してはいけません。

最初の実行と同じ捨てフォルダから再開してください。Node や npx 自体が起きないなら、まだ npx とポート 3080——headless は 3080 を使いませんが、壊れた Node は同じ床です。

十分の運用確認

1. 資格情報と既定モデルは Web と同じ確認。Headless が別の認証物語を作りません。
2. --json なしで退屈な一タスク。stdout に文、終了 0 を期待。
3. --json 付きで再実行。先頭の session id と起動 cwd を残す。
4. 同じディレクトリから --session-id で一度続ける。先に cd すれば拒否されるはず。
5. stdin で短いタスクを流す。空の位置引数がパイプを奪わないことを確認。
6. CI では終了 0、かつ --json なら流が final で終わりターン外 error が無いときだけ受け入れる。
7. 推論に敏感なパスが混ざりうるなら、stderr を共有ログに投げない。自分で経路を分ける。

この記事が扱わないこと

• 二通目の Web クイックスタートではない——npx クイックスタート。
• 0.1.7 RC の機能一覧ではない——0.1.7 RC の更新点。
• Computer Use や SSH リモートワークスペースの手順ではない。
• headless が本番認定だという主張ではない。上流はプレビュー互換が壊れると警告したままです。

次に開く場所

1. 契約とフラグ：釘付けにしたタグの headless README。
2. ブラウザの最初の一時間：インストール → npx クイックスタート。
3. 失敗のあと：Trajectory ログの読み方。