DeepSeek Harness: ローカルプラグインのロード
最終更新：2026-08-31
プラグインロード機構を理解することは、「プラグインを書いた」から「効率的にプラグインを開発する」への重要な飛躍です。cordis.yml は DSH の設定ハブであり、--patch オーバーレイ機構により、デフォルト設定を変更せずにローカルプラグインを柔軟にレイヤーできます。
--patch 機構のコアアイデアは「置き換えではなくレイヤー」——デフォルト設定はそのまま、ローカルの変更が上に重ねられます。これにより、開発デバッグとプロダクションデプロイが同じベース設定を共有できます。
📋 前提知識：11-first-plugin.md の完了、最小プラグインを作成できること
1. 学習内容
- cordis.yml 設定ファイルの詳細
$insertと$replace操作- 絶対パスと相対パスの選択
--patchオーバーレイ機構の原理--dump-configで最終設定を確認- ローカル開発とデバッグのワークフロー
2. cordis.yml 設定の詳細
(1) 設定ファイルの位置
cordis.yml は DSH のコア設定ファイルで、プロジェクトルートにあります：
my-dsh-project/
├── cordis.yml ← メイン設定
├── cordis.patch.yml ← パッチ設定（オプション）
├── package.json
└── src/
▶ サンプル 2：
# cordis.yml basic structure
plugins:
plugin-name:
# Plugin configuration items
enabled: true
config:
key: value
# Global configuration
hostname: localhost
port: 5173
(3) プラグインエントリフォーマット
各プラグインエントリは3つの情報を含みます：
| フィールド | 説明 | 例 |
|---|---|---|
| プラグイン名 | キーがプラグイン識別子 | my-plugin: |
| パス | どこからロードするか | $insert または npm パッケージ名 |
| 設定 | プラグインに渡すパラメータ | config: の下のフィールド |
plugins:
# npm パッケージプラグイン
@dsh-plugin/database:
config:
connection: "postgresql://localhost/mydb"
# ローカルプラグイン
my-local-plugin:
$insert: /home/alice/dev/my-plugin
config:
debug: true
3. $insert と $replace 操作
(1) $insert：プラグインの追加
$insert はプラグインを既存のプラグインリストに追加します：
plugins:
my-tool:
$insert: /home/alice/dev/dsh-plugin-my-tool
効果は以下と同等：
Default plugin list: [core, llm, tools, shell, ...]
After insert: [core, llm, tools, shell, ..., my-tool]
(2) $replace：プラグインの置き換え
$replace は既存のプラグインを新しい実装で置き換えます：
plugins:
# デフォルトの LLM アダプタをカスタム版に置き換え
llm:
$replace: /home/alice/dev/custom-llm-adapter
効果：
Default: llm → @deepseek-ai/dsh-plugin-llm
Replaced: llm → /home/alice/dev/custom-llm-adapter
⚠️ $replace は既存のプラグイン名を指定する必要があります；存在しないエントリは置き換えられません。
▶ サンプル 3：
plugins:
# ローカルツールの追加
my-tool:
$insert: /home/alice/dev/dsh-plugin-my-tool
# デフォルト shell をセキュア版に置き換え
shell:
$replace: /home/alice/dev/dsh-plugin-safe-shell
# 別のローカルプラグインの追加
my-monitor:
$insert: /home/alice/dev/dsh-plugin-monitor
(4) 操作の優先順位
同じプラグインに $insert と $replace の両方がある場合：
Priority: $replace > $insert
$replace のターゲットが存在しない場合、$insert の動作にフォールバックします。
4. パス戦略
▶ サンプル 1：
plugins:
my-plugin:
$insert: /home/alice/dev/my-plugin
利点：
- 作業ディレクトリに影響されない
- デバッグ時にパスが明確
- プロジェクト間で設定を再利用可能
欠点：
- ユーザーパスがハードコードされ、ポータブルでない
- チームメンバーのパスが異なる
(2) 相対パス
plugins:
my-plugin:
$insert: ./plugins/my-plugin
相対パスは cordis.yml を含むディレクトリを基準に解決されます。
利点：
- ポータブル、チームコラボレーションに適している
- プラグインをプロジェクトと一緒にバージョン管理可能
欠点：
- 起動時の作業ディレクトリに依存
- ネストされたディレクトリでパス計算が複雑
(3) パス選択の推奨
| シナリオ | 推奨 | 理由 |
|---|---|---|
| 個人開発 | 絶対パス | 明確で曖昧さなし |
| チームコラボレーション | 相対パス | ポータブル、環境間で一貫 |
| CI/CD | 相対パス | ビルド環境のパスが変動 |
| 一時的デバッグ | 絶対パス | 素早く特定、パス問題なし |
5. --patch オーバーレイ機構
(1) 設定レイヤーモデル
DSH 設定は複数のレイヤーから構築されます：
graph TB
BASE[Base Layer<br/>Default Configuration] --> BUNDLE[Bundle Layer<br/>dsh-base / dsh-web-app]
BUNDLE --> PROFILE[Profile Layer<br/>web / headless]
PROFILE --> PATCH[Patch Layer<br/>cordis.yml + --patch]
PATCH --> FINAL[Final Configuration]
各レイヤーは前のレイヤーの同名設定項目を上書きし、CSS カスケード優先度に似ています。
(2) --patch パラメータ
# 起動時にパッチレイヤーを適用
pnpm dsh web --patch
--patch なしの場合、DSH はデフォルト設定のみを読み取り、cordis.yml の $insert/$replace を無視します。--patch ありの場合、cordis.yml のオーバーライド操作が有効になります。
(3) cordis.patch.yml
メイン設定に加えて、cordis.patch.yml を追加パッチレイヤーとして使用できます：
# cordis.patch.yml — 開発環境のみ
plugins:
debug-tools:
$insert: ./dev-plugins/debug-tools
--patch は cordis.yml と cordis.patch.yml の両方を読み取り、後者がより高い優先順位を持ちます。
(4) オーバーレイマージルール
Base config: { a: 1, b: 2, c: 3 }
Patch layer: { b: 20, d: 4 }
─────────────────────────────
Final config: { a: 1, b: 20, c: 3, d: 4 }
- 同名フィールド：パッチレイヤーがベースレイヤーを上書き
- 新規フィールド：直接追加
- 影響を受けないフィールド：変更なし
6. --dump-config で最終設定を確認
(1) 基本的な使用方法
pnpm dsh web --patch --dump-config
完全にマージされた最終設定を出力：
# === Merged Configuration ===
hostname: localhost
port: 5173
plugins:
core:
enabled: true
llm:
enabled: true
config:
provider: deepseek
tools:
enabled: true
my-tool: # ← あなたの insert
$insert: /home/alice/dev/my-tool
config:
debug: true
debug-tools: # ← patch.yml で追加
$insert: ./dev-plugins/debug-tools
(2) 設定問題のデバッグ
プラグインが期待通りにロードされない場合、--dump-config でトラブルシューティング：
# トラブルシューティング手順
pnpm dsh web --patch --dump-config > config-dump.yml
# プラグインが最終設定に表示されているか確認
# $insert パスが正しいか確認
(3) 特定プラグインのみ表示
# 特定のプラグイン設定をフィルタリング
pnpm dsh web --patch --dump-config | grep -A 10 "my-plugin"
7. ローカル開発とデバッグのワークフロー
(1) 標準開発ループ
graph LR
CODE[Write Plugin Code] --> REG[Register in cordis.yml]
REG --> START[Start dsh web --patch]
START --> TEST[Test Plugin Behavior]
TEST --> BUG{Bugs?}
BUG -->|Yes| CODE
BUG -->|No| DONE[Done]
(2) クイックイテレーションのコツ
ツールプラグイン開発時の Alice の典型的なワークフロー：
# 1. 一度だけ cordis.yml を設定
cat > cordis.yml << 'EOF'
plugins:
my-tool:
$insert: /home/alice/dev/dsh-plugin-my-tool
EOF
# 2. 開発ループ
# コードを編集 → 再起動 → テスト
pnpm dsh web --patch
# テスト完了後、Ctrl+C で停止
# 3. 設定の確認
pnpm dsh web --patch --dump-config | grep my-tool
(3) マルチプラグイン並行開発
Bob が2つのプラグインを同時に開発：
# cordis.yml
plugins:
tool-a:
$insert: /home/bob/dev/dsh-plugin-a
tool-b:
$insert: /home/bob/dev/dsh-plugin-b
別々のターミナルで開発；DSH 再起動時に両方のプラグインがロードされます。
(4) プラグインの一時無効化
アンインストール不要——設定でコメントアウトするだけ：
plugins:
my-tool:
$insert: /home/alice/dev/my-tool
# experimental-tool: # 一時的に無効化
# $insert: /home/alice/dev/exp-tool
❓ よくある質問
cordis.yml は Cordis フレームワークの設定で、プラグインのロードとオーバーライドを管理します。dsh.config.yaml は DSH アプリケーションの設定で、モード、承認ポリシー等を管理します。互いに補完し、競合しません。package.json を含めることを推奨します。--patch なしの場合、DSH はデフォルト設定を使用し、cordis.yml を無視します。これは意図的——開発設定が誤ってプロダクションに影響するのを防ぐためです。cordis.patch.yml のみサポートされています。複数のパッチセットが必要な場合、ファイルの内容を手動で切り替えてください。📖 まとめ
- cordis.yml は DSH のプラグイン設定ハブで、プラグインのパスと設定項目を含む
$insertはプラグインの追加、$replaceは既存プラグインの置き換え- 絶対パスは個人開発向け、相対パスはチームコラボレーション向け
--patchはオーバーレイ機構を有効にし、cordis.yml をデフォルト設定の上にレイヤー--dump-configは最終マージ設定を表示——ロード問題のトラブルシューティングに強力なツール- 開発ループ：コードを編集 → cordis.yml に登録 →
dsh web --patch→ テスト
📝 練習問題
1. ⭐ 基礎：前のレッスンの hello-world プラグインを cordis.yml で $insert を使って登録し、--dump-config で最終設定に表示されることを確認してください。
2. ⭐⭐ 応用：同じプラグインを絶対パスと相対パスの両方で登録し、--dump-config で2つの設定の出力の違いを比較してください。
3. ⭐⭐⭐ チャレンジ：2つのローカルプラグイン A と B を作成し、cordis.yml に両方を $insert してください。$replace を使って DSH の内蔵ツールプラグインの1つをカスタム版で置き換え、--dump-config で置き換えを確認すること。
