DeepSeek Harness（dsh）プラグインのトラブルシューティング：インストール失敗・cordis.patch.yml 競合・Profile が反映されない場合の対処（2026）

このページを使うタイミング

「プラグインを見つけた」から「プラグインが動いている」までのどこかで問題が起きたときにお読みください。dsh plugin add の失敗、monorepo での pnpm-workspace allowlist エラー、cordis.patch.yml を変更しても反映されない、起動する Profile が想定と違う、といったケースを扱います。各セクションは「症状 → 原因 → 対処コマンド」の順でまとめています。

まだインストール作業に進んでいない場合は プラグインの安全なインストール から。どの設定レイヤーを編集しているのか分からない場合は 設定ガイド を先にお読みください。

その前にひとつだけ鉄則を：設定を変更したら必ず dsh を再起動してください。プラグインツリーは起動時に Cordis コンテナが組み立てるため、「何も起こらない」報告の半分は、設定変更後に再起動していなかっただけです。

1. インストール時にプラグインが見つからない

症状：dsh plugin add dsh-some-tool が解決エラーで失敗する、または正常終了したのにプラグインがどこにも現れない。

原因：CLI は npm レジストリから正確なパッケージ名で解決します。パッケージ名のタイポ、@scope/ プレフィックスの欠落、GitHub 限定配布（npm に存在しない）、または --profile <name> が起動時と食い違っていて別の Profile に入り込む、が主な原因です。

対処法：

1. まず npm view dsh-some-tool でパッケージ名とスコープを確認します。プラグインの詳細ページとリポジトリの README に正しいインストールコマンドが記載されています（コミュニティプラグインの導入方法はプラグイン自身が管理しています）。
2. GitHub 限定のプラグインはソースからブランチ・タグを指定してインストールします：dsh plugin add github:owner/repo#main
3. フラグと起動方法を揃えます：dsh plugin --profile web add <package> で入れたなら dsh --profile web で起動します（dsh 単体ではダメです）。
4. 開発中のプラグインはディレクトリを直接リンク：dsh plugin add ./path/to/my-dsh-plugin

2. インストールが止まる・失敗する：pnpm workspace allowlist

症状：pnpm monorepo 内でインストールがハングする、または pnpm-workspace allowlist・module not found・ESM & CJS 解決エラーで失敗する。特に git やローカルビルドから入れた場合に多い。

原因：pnpm は依存関係の境界を厳密にチェックします。GitHub から入れたプラグインは実質ワークスペースの一部になるため、パッケージが境界内に宣言されていないとリンクされず、実行時にモジュールを解決できません。

対処法：

1. 境界内に宣言します：ワークスペースルートの package.json の dependencies（または pnpm-workspace.yaml の allowlist/catalog）にプラグインを追加し、ルートで pnpm install を実行します。
2. プラグインを入れ直して再起動します：dsh plugin add <package> → 再起動して再構築されたツリーを読み込みます。
3. npm に公開版があるならそちらを優先します。公開パッケージは依存を同梱しているため、境界問題を回避できます。
4. ランタイムを確認します：node -v が 20.0.0 以上であることを確認してください。

3. cordis.patch.yml の競合（上書き順序の問題）

症状：2 つのプラグインが重複する（サイドバーが 2 つ、OCR エンジンが 2 つ、同一サービスの実装が 2 つ）、一方の設定が無視される、Profile patch collision / Override order issue が表示される。

原因：patch は bundle と profile の上に重ねる最上位のオーバーライド層であり、後ろに書いたエントリが優先されます。同じサービスや UI パネルを登録するエントリが複数ある場合、宣言順で決着が付きます。YAML のキー重複やインデントずれが、エントリの意味を静かに書き換えてしまうこともあります。

対処法：

1. 実際に使っているファイルを開きます：cat ~/.dsh/profiles/<name>/cordis.patch.yml（ワークスペース内は <プロジェクトルート>/.dsh/cordis.patch.yml）。
2. 順序を調整します：優先させたいプラグインを plugins: リストの末尾に移動します（後ろのエントリが前のエントリを上書きします）。
3. 競合を止めたいだけなら共存させます：片方のエントリを enabled: false にします。
4. 長期的にきれいなのは分離です：競合するプラグインを別の Profile に分け、dsh --profile <name> で起動します。
5. 再起動前に YAML を検証します：インデント 1 つでエントリの意味が変わります。yq eval . cordis.patch.yml

4. dsh bundle 形式エラー

症状：dsh は起動するのにプラグイン構成がドキュメントとまったく違う、コピーした設定ファイルが競合エラーを出し続けて読み込まれない。

原因：3 つの設定レイヤーは役割が異なります。bundle は dsh に同梱される公式プラグインセット、profile は自分の「bundle + プラグイン」の組み合わせ、patch は単一のプラグイン項目に対する外科的なオーバーライドです。cordis.patch.yml が bundle 全体（数十のエントリと profile 層に属する設定）を再宣言していると形式が混ざり、bundle が提供する内容と上書きが衝突し始めます。

対処法：

1. patch は最小限にします：プラグイン 1 つにつきエントリ 1 つ、enabled と options だけにしましょう。

# ~/.dsh/profiles/default/cordis.patch.yml
plugins:
  dsh-vision-toolkit:
    enabled: true
    options:
      ocrEngine: 'default'

2. 一式まとめて有効化したいなら profile 層の仕事です。patch に全エントリを貼り付けるのではなく、profile の組み合わせとして定義します。
3. 重複エントリを削除して保存し、dsh を再起動します。競合メッセージなしでプラグインのツール・パネルが読み込まれれば完了です。

5. Profile が反映されない

症状：cordis.patch.yml を編集して再起動したのに何も変わらない、特定の Profile 用に入れたプラグインがどこにもない。

原因：よくある 3 パターンのどれかです。① 間違ったファイルを編集している（設定ファイルは 2 箇所あり、プロジェクト側がグローバル側を上書きする）、② 起動時の Profile 名と編集したディレクトリ名が一致しない、③ そもそも再起動していない。

対処法：

1. 2 箇所を確認します：ls ~/.dsh/profiles/*/cordis.patch.yml 2>/dev/null と、プロジェクトルートで ls .dsh/cordis.patch.yml 2>/dev/null
2. 優先順位を思い出します：両方ある場合 <プロジェクトルート>/.dsh/cordis.patch.yml が ~/.dsh/profiles/<name>/cordis.patch.yml より優先されます。
3. フラグとディレクトリを一致させます：~/.dsh/profiles/web/cordis.patch.yml を編集したなら dsh --profile web で起動します（dsh 単体や dsh --profile headless ではダメです）。
4. 再起動して確認します：dsh --profile web でツール・パネルが現れるか確認してください。まだの場合は次のセクションへ。

6. インストール済みなのに読み込まれない（failed to register）

症状：インストールは成功、設定も正しいはずなのに、起動時に Plugin failed to register / Lifecycle timeout が出る、またはエラーなしで読み込まれない。

原因：ランタイムが古い（Node.js 20 未満）、依存が不足している（git インストールはビルドが必要）、宣言順が別のプラグインと衝突する、エントリが enabled: false のまま。もう一つのよくある原因がサンドボックスです。dsh はデフォルトで read-only のため、ディスクやネットワークにアクセスするプラグインは読み込み時に Permission denied / Sandbox security policy violation でブロックされます。

対処法：

1. ランタイムを確認します：node -v —— 20.0.0 以上（推奨：Node 22 LTS）にアップグレードします。
2. ソースインストールはビルドが必要です：プラグインディレクトリで pnpm install && pnpm build を実行してから再起動します。
3. クリーンにインストールし直します：dsh plugin remove <package> → cordis.patch.yml のエントリを確認 → dsh plugin add <package>
4. エントリが有効か確認します：dsh plugin add は enabled: true を書き込みますが、手編集した場合はそのまま残っているか確認してください。
5. サンドボックスが原因で、プラグインが信頼できる場合は権限を上げて起動します：dsh --sandbox workspace-write（詳細はセキュリティガイド）。
6. dsh-market の Web UI から入れた場合は Settings → Plugin Market でステータスを確認してください。バックエンドが設定を適用してホットリロードするため、失敗状態もそこに表示されます。

それでも解決しない場合

• プラグインの安全なインストール —— インストール方法と CLI コマンド早見表
• 設定ガイド —— bundle・profile・patch、どのレイヤーを編集しているのか
• プラグインを登録する —— プラグインの README と実際の挙動が食い違う場合は、リポジトリに issue を開いてください。dsh --profile の起動コマンドとエラー全文を添えると解決が早くなります。自身が開発者なら README を修正してディレクトリに登録しましょう。