プラグインを追加したのにツールが表示されない、profileを変えると設定が消える、更新後にビルドが通らない。最短の解決策は、先に拡張目的を「ツール、モデル提供元、画面、ワークフロー」に分け、その後で単一能力の最小プラグインを作ることです。

今週は、複雑なプラグイン群を一度に組まず、設定、権限、互換性確認を別々の成果物として切り出してください。DeepSeek Harnessは2026年8月18日時点で開発者向けプレビューであり、互換性を壊す変更が予定されています。(github.com)

このページは、社内スクリプトをDeepSeek HarnessのツールにしたいAI Agentエンジニア、独自モデル端点やチームゲートウェイを接続したい開発者、共通の開発環境と受け入れ手順を整えたい技術責任者向けです。

最終的なAPI、ディレクトリ規約、ビルドコマンドは、作業日に公式リポジトリのmasterブランチで再確認してください。コミュニティ製プラグインの動作を、公式仕様として扱わないことが重要です。

01

まず拡張目的でプラグインの境界を決める

DeepSeek Harnessは「すべてがプラグイン」という設計です。Cordis上では、モデルアダプター、ツール登録、セッション管理、エージェントループまでが共有コンテキストに参加する構成になっています。プラグインのアンロード時には、登録した効果を戻せる設計も公式アーキテクチャで説明されています。(github.com)

最初に、次の条件で分岐してください。

  • 入力を受けて外部処理を呼び出すだけなら、ツールプラグインを選びます。 例は社内検索、チケット取得、リポジトリ操作です。単一の入力契約と出力契約を持たせ、失敗理由を返せるなら、1つの小さなプラグインに向いています。
  • モデル名、APIキー、ベースURL、モデル一覧を差し替えるなら、モデル提供元プラグインを選びます。 普通のツールプラグインに認証やモデル選択まで混ぜると、権限管理と切り戻しが難しくなります。
  • Web UIやブラウザー側の表示を追加するなら、画面プラグインとして分離します。 HostとClientを同じ処理として扱わず、サーバー側のサービス、遠隔呼び出し、ブラウザー資産を分けて検証してください。
  • 複数のツールや設定を組み合わせるなら、ワークフロー全体を1個の巨大プラグインにしないでください。 独立して停止できる能力は別プラグインにし、profileと設定の重ね合わせで実行形を作ります。

1つにまとめるか、分割するかの判断条件

  • 1つの権限で安全に実行でき、単独テストが可能なら、単一プラグインです。
  • 認証情報、権限、更新頻度のいずれかが異なるなら、複数プラグインに分けます。
  • 片方の機能障害で全体を停止させたくないなら、独立して無効化できる構成にします。
  • 同じ設定を試験用、検証用、継続実行用で変えるなら、コードを複製せずprofileを分けます。

公式アーキテクチャでは、profileが複数のbundleを順番に積み、profile固有のcordis.patch.ymlやホーム側の設定、--patchの上書きを重ねる仕組みが示されています。(github.com)

02

最小のdsh-pluginは能力を1つに絞る

dsh-pluginの最小構造を考えるとき、重要なのはファイル数ではなく、ロード、発見、実行失敗の3点を検証できることです。公式リポジトリは、パッケージごとにpackage.jsonのdshフィールドを使い、profileやbundleを宣言する構成を採用しています。(github.com)

公式APIが変わる可能性を踏まえた概念上の最小構成は、次のように整理できます。

my-dsh-plugin/
├── package.json
├── src/
│   ├── index.ts
│   └── tool.ts
├── tsconfig.json
└── README.md

ここでindex.tsは登録入口、tool.tsは単一能力の実装、README.mdは入力、出力、必要権限、失敗例の説明に使います。package.jsonの具体的なキーは、作業日に公式のサンプルと設定カタログを確認して決めてください。名前だけを合わせて、非公式の雛形を固定化するのは危険です。

成功信号は3つです。

  1. dshの起動時にプラグインのロードエラーが出ない。
  2. ツール一覧または対象の登録箇所から、能力名と入力スキーマを確認できる。
  3. 正常系だけでなく、権限不足、必須入力不足、外部サービスのタイムアウト時に診断可能なエラーが返る。

たとえば社内チケット検索なら、入力はprojectとquery、出力はチケット識別子、タイトル、状態に限定します。検索、更新、削除を最初から同じプラグインに入れると、権限確認と回帰テストの範囲が急に広がります。

03

モデル接続は認証情報と実装を分離する

モデル提供元プラグインは、普通のツールプラグインと責任範囲が異なります。APIキーだけでなく、接続先、モデル識別子、タイムアウト、利用可能なモデル一覧まで関係するためです。

公式開発ガイドでは、DEEPSEEK_API_KEYを環境変数またはGit管理対象外の.envから読み込み、DEEPSEEK_BASE_URLで接続先を上書きできる構成が示されています。認証情報をコミットしないこと、キーがない場合は実APIのE2Eテストを自動的にスキップできることも記載されています。(github.com)

実装時は次の3層に分けます。

  • コード: 認証情報の名前、接続処理、レスポンスの型だけを定義します。
  • 環境変数または安全な設定: APIキー、ベースURL、対象モデルを渡します。
  • profile: どのモデル提供元を、どのツール群と組み合わせるかを決めます。

リポジトリにキーを書かないだけでは不十分です。ログ出力、エラー文字列、デバッグ用の設定ダンプにも秘密情報が混ざらないか確認してください。接続先を変更したときに、ツールプラグイン側のコードを変更しなくても切り替えられる状態が目標です。

04

HostとClientを分けてWeb UIを検証する

Web UIを持つ拡張では、サーバー側の処理とブラウザー側の資産を同じTypeScriptプロジェクトとして雑に扱わないでください。公式開発ガイドでは、Host集約とClient集約が分離され、通常のパッケージはどちらか一方に登録されます。Host側で生成された遠隔呼び出し用の型を、Client側が利用する順序も定められています。(github.com)

公式のビルド順は、概ね次の流れです。

tsc -b tsconfig.host.json
tsdown --env.DSH_BUILD_FACE host
tsc -b tsconfig.client.json
tsdown --env.DSH_BUILD_FACE client
pnpm run build:web

この順番を変えると、Client側が必要とする生成済みの型や遠隔インターフェースが存在せず、ローカルでは見えにくいビルドエラーになります。Web UIの動作確認では、表示だけでなく、Hostからの応答、切断時のエラー表示、権限不足時の操作制限を個別に確認してください。

公式の開発環境は、Node.js 22.19以上または24系を前提とし、CIでは22.19、24、26が対象です。pnpmはpackage.jsonで11.7.0に固定され、Gitは2.26以上が前提です。(github.com)

05

profileで実行形を組み立てる

DeepSeek Harnessのprofileは、単なる環境変数の置き場ではありません。bundle、プラグイン、設定の上書き層を組み合わせて、実際に起動するプラグインツリーを作る単位です。

指定profileにプラグインを読み込ませるときは、まず公式ドキュメントにある実際のprofile構成を確認し、そのprofileのbundle一覧とパッチ適用順を把握します。起動する構成は次のコマンドで確認できます。

dsh --profile web --dump-config

このコマンドで表示された行を基準に、対象IDをパッチで置き換えます。公式アーキテクチャでは、bundle、profileのパッチ、ホーム階層のパッチ、--patchオーバーレイの順で適用されます。(github.com)

profileの用途 置くもの 失敗時の戻し方
試験 新しいツール、実験的なモデル設定 profileから対象bundleを外す
検証 固定した依存関係、再現用パッチ 検証用profileを再作成する
継続作業 安定したツール、承認済み設定 直前のパッチへ戻す

試験用profileで動いたからといって、全員が使うprofileへ直接コピーしないでください。依存関係や設定上書きの差で、同じプラグインでも見えるツールや権限が変わる可能性があります。

06

公開前は5段階で受け入れる

第一歩は、公式の開発環境をそろえることです。リポジトリから取得した後、依存関係をインストールし、初回の型チェックを通します。

pnpm install
pnpm run typecheck

公式READMEに記載されたソース起動では、ビルド後にWeb UIを起動します。標準のWeb UIは127.0.0.1:3080で提供されます。(github.com)

第二歩は、最小実行です。対象profileで起動し、プラグインがロードされ、ツールが発見され、正常な入力に応答することを確認します。

第三歩は、失敗系です。次の項目を実行ログとともに保存してください。

  • 必須入力を外した場合のエラー
  • APIキーがない場合の挙動
  • 接続先が応答しない場合のタイムアウト
  • 権限が不足している場合の拒否
  • プラグインを無効化した後の既定機能

第四歩は、クリーン環境への導入です。既存のキャッシュや個人のホーム設定がない状態で、依存関係の導入、ビルド、profile適用をやり直します。ここでだけ再現する問題は、依存パッケージ、Node.js、環境変数、ローカルパッチのいずれかに原因があります。

第五歩は、アンインストールと切り戻しです。プラグインを外しても、profileが起動し、残った設定が不要なサービスを参照しないことを確認します。検証記録には、確認したコミット、パッケージバージョン、Node.jsのバージョン、確認日を残してください。

既存の作業環境とMac環境をどう使い分けるか

手元の環境だけで進める場合、設定が個人端末に残りやすく、複数人で同じNode.jsやpnpm条件を再現しにくい点が弱点です。CIだけに寄せる場合は、Web UIの確認、認証を伴う実API試験、長時間のデバッグがやりにくくなります。

Macを自前で用意する方法は、長期的に同じ高負荷作業を続けるチームには向いています。一方、短期の検証や複数案件の並行開発では、保守、初期設定、端末の空き状況が負担になります。まずはMac開発環境のサポート情報で必要な接続方法を確認し、チームで使う場合はMacレンタルの構成選びと照らし合わせてください。

DeepSeek HarnessのWeb UIやprofileを継続的に検証するなら、既存のローカル環境は「個人の試作」、VpsMeshのMac環境は「共有できる検証拠点」として分けると運用しやすくなります。特に、構築担当者が変わるたびに依存関係を入れ直す、設定を手作業で戻す、画面確認のために端末を空けてもらう、といった負担が発生しているなら、遠隔接続できる開発環境を検討する段階です。

ただし、常時稼働の重い処理、物理ポートへの接続、長期間の固定運用が中心なら、自前のMacや専用環境の方が合う場合もあります。短期のプラグイン開発、頻繁なprofile切り替え、複数人の受け入れ試験が中心なら、必要な期間だけVpsMeshのMacを確保する方が、端末購入後の保守負担を抱えずに済みます。