DeepSeek Harness npmとソースビルド、どちら？

公式READMEに示されている実行経路は、npm経由とソースコード経由の2つです。しかも現行リポジトリはDeveloper Previewで、互換性を壊す変更があり得るため、試用ならnpm、コア変更やプラグイン境界の調査ならソース、遠隔納品なら安定用npmと開発用ソースを分離する判断が適切です。(公式README)

症状： Web UIや基本的なAgent処理を確認したいだけなのに、最初から巨大な開発環境を整えようとしている。
最短解決： Node.jsを確認し、固定したnpmパッケージで最小タスクを再現します。コアを変更する必要が出た時点で、別ディレクトリにソース環境を追加します。

この記事は、DeepSeek Harnessを短時間試したい開発者、プラグインや内部機能を改修したい貢献者、Mac上の実行環境をチームへ納品したいプラットフォーム担当者向けです。Web、Headless、ACPなどの実行モードではなく、配布パッケージとソースワークスペースの保守責任を比較します。

※最終更新：2026年8月18日。Node.js、pnpm、ビルド手順、実行経路は、公式README、公式package.json、公式開発ガイドを確認しています。

最初に決めるべきなのは性能ではなく保守範囲です

npmとソースビルドを、単純な起動速度や処理性能だけで比べるのは適切ではありません。両者は同じDeepSeek Harnessを扱っていても、変更できる範囲、再現性、障害時に戻る手順が異なります。

公式READMEでは、npm経由は npx @deepseek-ai/dsh web、ソース経由はリポジトリを取得して pnpm install、pnpm run build、pnpm dsh web を実行する流れです。npm経路では公開済みパッケージを呼び出しますが、ソース経路では依存関係、型検査、ホスト側とクライアント側のビルドまで管理対象になります。Node.jsのバージョン管理方法については、Node.js公式のリリース情報も納品時の確認資料に加えます。

npmは自動的に安定する仕組みではありません。Developer Previewである以上、パッケージを更新すれば挙動が変わる可能性があり、実行前にバージョンを記録しなければ再現性は残りません。反対に、ソースビルドも高性能になるわけではなく、変更可能性と検証責任が増える経路です。

公開プラグインの利用と開発は分けて考えます

既存プラグインをインストールして動かすことと、DeepSeek Harness本体のソースを変更することは別の作業です。公開インターフェースだけでプラグインの設定、読み込み、基本動作を確認できるなら、npm経路のまま検証した方が、問題の原因を本体のビルド環境へ広げずに済みます。

一方、プラグインの読み込み境界、API変更、イベントの受け渡し、HostとClientの接続を調べる場合は、ソースワークスペースが必要になります。外部プラグインだけを作る場合は、まず独立リポジトリで公開インターフェースに依存し、本体のmonorepoを抱え込まない構成を優先します。公式READMEも、プラグインリポジトリには dsh-plugin トピックを付けるよう案内しています。

次の条件ならnpm、次の条件ならソースへ切り替えます。

• 公開プラグインを設定するだけなら、npmを選びます。
• プラグイン単体のテストで完結するなら、独立リポジトリを選びます。
• 本体の型定義や読み込み処理を変更するなら、ソースを選びます。
• 上流への修正提案やコア機能の変更を行うなら、ソースを選びます。
• プラグインで障害が出たとき、無効化した設定へ戻せないなら、導入を止めます。

遠隔Macの納品では「どのnpm版か」より証拠を残します

遠隔MacへDeepSeek Harnessを配備する場合、固定すべきなのは「常に最新版」ではありません。実行日に検証して問題がなかったパッケージ版を明示し、起動コマンドへ組み込み、同じ環境を再構築できることを確認します。

npm経路では、曖昧なタグのまま npx を実行するのではなく、確認済みのパッケージ版を明示する運用にします。具体的な版番号は、公開パッケージ情報と公式リポジトリの状態を照合したうえで決め、記事や納品書へ推測で記載しません。npmの package.json では、依存関係のNode.js条件を engines で示せるため、納品時にはNode.jsの実行版とともに記録します。

納品前には、次の5点を別ファイルへ保存します。

1. Node.jsのバージョン。
2. DeepSeek Harnessのパッケージ版、またはソースのコミットID。
3. 起動コマンドと作業ディレクトリ。
4. 環境変数や設定ファイルの保管場所。
5. 基本タスクの入力、結果、実行日時、復旧手順。

新しいMacや別の遠隔環境で同じ設定を再構築し、同じ基本タスクを完了できれば、納品の最低限の再現性を確認できます。Web UIが表示されるだけでは不十分で、モデル接続、作業領域、プラグインの有無まで一致させます。

チーム運用は安定用npmと研究用ソースの二軌道です

プラットフォームチームには、npmとソースのどちらか一方へ全員を寄せるより、役割を分ける構成を推奨します。安定環境は確認済みのnpm版で固定し、研究環境はソースのコミットを明示します。プラグインやコア変更は研究環境で基準タスクを通過させてから、安定環境へ段階的に反映します。

選択条件を最終確認すると、次のようになります。

• Web UI、モデル、作業領域、基本タスクの確認だけなら、npmです。
• 公開プラグインの利用だけなら、npmを先に選びます。
• 外部プラグインの開発で本体を変更しないなら、独立リポジトリとnpmです。
• HostやClientの処理、本体パッケージを変更するなら、ソースです。
• 安定運用とコア開発を同時に行うなら、二軌道です。
• 重要な会話や作業領域が一つの環境にしかないなら、その環境で直接アップグレードしません。

自前のMacでこの分離を行う場合、Node.jsの切り替え、依存関係の保存、アクセス制御、再起動後の復旧まで担当者が持つことになります。短期の検証や一時的な開発環境では、VNCMacのMacクラウド環境を使い、安定用と研究用を分けて構築する方が、自分の作業Macへ状態を混在させずに済みます。

現在の構成が単一のローカルMacだけの場合、試験版の更新で作業領域まで巻き込まれやすく、担当者が変わった際にNode.jsや起動方法が再現できず、障害時の回退先も不足しがちです。npmを固定した安定環境とソースを置く研究環境を分けたい場合は、Macクラウドの利用条件と運用方法を確認し、必要な期間だけ独立したMac環境を用意する判断が現実的です。