dsh 設定ガイド：プロファイル・パッチ・エージェントプリセットの仕組み

すべてはプラグインツリー

実行中の dsh は、機能をボルトで付け足したバイナリではありません。プラグインツリー です。起動時に設定レイヤーから組み立てられる Cordis プラグインシステムで、すべての能力（ツール、モデルアダプター、ストレージ、サンドボックス、UI、メインループ）はそのツリー内のプラグインです。どのプラグインがどの順序で存在するかは、設定レイヤーが決めます。

これがメンタルモデルのすべてです。このガイドの残りはレイヤーの解説です。

レイヤー：下から上へ

設定は固定の順序で積み重なり、上位レイヤーが下位レイヤーを上書き します。

┌─────────────────────────────┐
│  patches      (your overrides)   ← wins
├─────────────────────────────┤
│  profiles     (your named assemblies)
├─────────────────────────────┤
│  bundles      (official plugin sets)
└─────────────────────────────┘

• Bundles ―― 公式がまとめて配布するプラグインセット。初回起動時のデフォルト体験は 1 つの bundle です。
• Profiles ―― 自分のマシン上の名前つき構成。「この bundles とプラグインを、この設定で読み込む」という宣言です。複数保持して切り替えられます。
• Patches ―― 自分専用のオーバーライドレイヤー。任意の単一プラグインエントリーを対象に、元のプロファイルに触れず置き換えられます。

すべてのレイヤーが単なる設定なので、環境の共有はファイルの共有です。プロファイルやパッチをコピーすることが、誰かが「自分の dsh」をあなたに渡す方法です。

パッチレイヤー：エージェントの着せ替えシステム

組み込みのパッチレイヤーは、他のエージェントと最もかけ離れて感じられる部分です。着せ替えシステム として考えてください。エージェントがどんな能力をまとうか、どんな条件でまとうかをあなたが決めます。

• ローカルエージェントをサブエージェントとしてマウント。 マシン上の Codex や Claude Code を、置き換える競合ではなく、ハーネスが委譲するサブエージェントとして登録できます。
• 能力を配線する。 ツール追加、外部サービス連携、実行権限の調整、全文検索の有効化を行うプラグインをインストール。
• UI を交換する。 インターフェースモジュールもプラグインです。スキン、パネル、UI コンポーネント全体までパッチで交換できます。
• ルールを条件付きにする。 ルールは JavaScript 式 なので、能力の適用範囲を絞れます。特定のリポジトリ、ファイルタイプ、時間帯だけ、という指定が可能です。

パッチは単一のプラグインエントリーを対象とするので、これらはすべて、下のプロファイルに触れずに追加・検査・削除できるオーバーライドです。

なぜ「プラグインのインストール」が設定編集なのか

「インストールして忘れる」意味での中央パッケージマネージャーは存在しません。プラグインのインストールとは プロファイルまたはパッチレイヤーにエントリーを追加すること で、正確な行はプラグインリポジトリの README に記載されています。次回起動時にプラグインはツリーに参加し、削除すれば登録したものはすべて取り消されます。登録は可逆な副作用でなければならないので、出来の悪いプラグインも残骸を残せません（プラグイン開発ガイド 参照）。

内蔵のプラグイン管理ページにできて、できないこと

0.1.6 の alpha 系（alpha.2、2026-09-17 公開）では dsh 本体にプラグイン管理ページが追加されました。プラグインのインストール、設定の編集、そして実行時の有効／無効切り替えまで可能です（この切り替え自体に再起動は不要）。同じリリースでプラグインの依存解決も実行時解決に変わり、実行時のアンロードもサポートされています。なお公式リリースノートでは、プラグイン開発者に対してロード／アンロード処理の見直しが明示的に求められています。安定系（npm の latest）は現在も 0.1.5-rc.2 なので、このページが見えない場合は alpha 系にいないということです。

使う前に、2 つの役割を分けて考えましょう。

• 内蔵ページが管理するのはすでにインストール済みのもの——起動中の profile に入っているプラグイン群と、各プラグインの options です。このページが説明してきたレイヤーが置き換わるわけではなく、同じ profile / patch 状態の入口が使いやすくなった、という位置づけです。
• 何を入れるべきかには答えてくれません。エコシステム全体のランキングも、シナリオ別のまとめも、「誰が誰と組み合わせて使っているか」も無いからです。そこがディレクトリサイトの役割なので、まずは プラグインコレクション か 十大ベストプラグイン でインストールコマンドを持っていき、その後の ON／OFF と設定を内蔵ページに任せるのが順序として自然です。

実行時解決による副作用も一つあります。今日は正常にロードできるプラグインも、ハーネス更新後に作者の追従が間に合わず失敗する可能性があります。その場合はトラブルシューティング第 8 節 のバージョン固定とロールバックを参照してください。

dsh がファイルを置く場所：ディスク上のパス一覧

「インストール＝設定編集」である以上、隠されたシステムフォルダに何かをコピーすることはほとんどありません。インストールが本当にやっているのは、プロファイルへ依存エントリーを書き込むことです。そして各プロファイルは、そのまま開いて中身を確認・バックアップできる普通のディレクトリです。

このレイアウトを踏まえて、押さえておきたい習慣が 2 つあります。プラグインが「見当たらない」ときは、ファイルシステムを掘る前にプロファイルの一覧を確認すること。dsh plugin --profile web list は、そのプロファイルが持つ依存エントリーと、それをどのディレクトリから読んだかを正確に示します。そして環境のバックアップや共有も、結局はファイルのコピーです。プロファイルディレクトリとパッチファイルがセットの全体であり、真っさらな状態に戻すときも同じパスを消すことになります（プラグインのアンインストールとクリーンアップ 参照）。

セッションのアーカイブと掃除

セッションは harness ホーム（~/.dsh、DSH_HOME で変更可）の下にあるファイルです。よく混同される 3 つの操作を分けておきます。

• アーカイブは表示の変更です。セッションがアクティブな一覧から外れるだけで、ディスク上には残ります。ここはまだ荒削り——ディスカッション #8344 が問いているのはアーカイブ済みセッションの削除と一覧表示で、セッション単位の削除コマンドは公式に文書化されていません。
• エクスポートは公式ドキュメントに書かれた「アーカイブ」です。セッションログのエクスポートには ZIP 圧縮のアーカイブポリシーが付きます（設定カタログ参照）。会話の持ち出し用コピーが欲しいなら、掃除の前にエクスポートを。
• 掃除は harness ホーム下のセッションファイルの削除です。このページの他の操作と同じ規則——まずバックアップ。~/.dsh ごと削除するのが完全リセット（手順はアンインストールガイド）。harness のアップグレード前には、dsh-lanes のようなコミュニティのマルチインスタンス管理ツールでインストール単位に会話をバックアップしておけば、失敗したアップグレードに履歴まで持ち去られることはありません。

同じレイアウトゆえに「セッション管理」は独立したテーマになります——パネル・クリーンアップ・アーカイブの各ツールはセッションマネージャーコレクションを参照してください。

dsh コマンド早見表

dsh コマンドは上記すべての入り口であり、0.2.0-rc.2 からはデスクトップの第一級機能にもなりました。macOS と Windows のデスクトップアプリのメニューバーに 「Manage dsh command」 が加わり、dsh コマンドのインストールと管理（プラグイン込み）を、Node.js や pnpm を別途導入しないで行えます。ターミナルで dsh: command not found が出たら、このメニュー項目が公式の新しい解決策です（トラブルシューティング §11 も参照）。

それ以外の人にとって、日常で覚えるのはこの程度です。

習慣としておすすめは 2 つ。調査の前に必ず dsh --version を確認すること、そしてインストール時の --profile と起動時の --profile を一致させること——「プラグインが消えた」の最大の原因はここです。続きはトラブルシューティングへ。印刷版は dsh CLIチートシートに——よく使うコマンド・フラグ・起動モードを1ページにまとめてあります。

エージェントプリセット：1 セッションの形

UI 上部のモードセレクターは Agent Preset を選びます。それはこのセッションのエージェントの完全な定義です。

• どの ツール を持つか
• システムプロンプト
• どの スキル が読み込まれるか
• サブエージェントとワークフロー の構成

プリセットはプラグインリストにプロンプトを足したものではなく、セッションが従う契約全体です。だからセッションは内容が入った時点でプリセットをロックします。途中で切り替えると、履歴にすでにあるツール呼び出しが解釈不能になるからです。

組み込みの 4 プリセット：

自分のプリセットを作る

Creation モードが新しいプリセットを設計する公式の方法です。欲しいものを説明します（「ファイルを一切編集せず、中国語で答える読み取り専用コードレビュアー」）。するとハーネスが実行中のランタイムを検査し、メモリ上でプラグインを試し、設定を下書きし、マウントして再利用できるよう保存します。

実践版はフレーム検証済みのウォークスルーカスタム Agent プリセット実践ガイドへ。Creation モードから保存されたプリセットが動くまでを、すべてスクリーンショット付きでたどれます。

ドキュメントにある 2 つの注意点を繰り返しておきます。

• Creation モードはモデルが書いたコードをランタイムに対して実行します。シェルアクセスと同じ信頼度で扱ってください。
• プリセットは設定です。デフォルトにする前に、保存された内容をレビューしましょう。

設定をやめるタイミング

気持ちのよいデフォルトはこれです。Standard を動かし、ほぼ何も変えない。 プロファイルやパッチに手を出すのは、同じセットアップを繰り返すとき（チームで 1 つのプロファイルを共有）、1 つの仕事に固定の道具箱が欲しいとき、1 つの部品（別のモデルアダプター、より厳しい承認ポリシー）を交換したいときです。上位レイヤーは、全体をフォークせずに 1 点だけ上書きするために存在します。

次に読む

• おすすめ人気プラグイン Top 10＆スターターパック ―― 1 コマンドで導入できる定番セット
• 2026 年おすすめ必装プラグイン 12 選
• 目的別コレクション一覧
• プラグインの安全なインストール方法
• プラグインのアンインストールとクリーンアップ ―― 1 つのプラグインを外す、ハーネス本体を削除する、~/.dsh を消す
• サンドボックス・承認・シークレット ―― これらのレイヤーが差し込まれる安全モデル
• クイックスタート：5 分で dsh を動かす
• dsh プラグインのエコシステム