DeepSeek Harness: Bundle と Profile
最終更新：2026-08-31
DSH プロジェクトには複数の実行設定が必要な場合があります——Web UI 開発用、ヘッドレスデプロイ用、CI テスト用。Profile は名前付きの組み立てスキーム、Bundle は配布可能な設定＋コードパッケージです。この2つがあれば、DSH のデプロイはチャンネル切替のように簡単になります。
💡 ヒント：profile は「どのプラグインを選ぶか」、bundle は「どう設定するか」。Profile が組み合わせを選び、Bundle が詳細を設定します。この階層関係を理解すれば、DSH の設定アーキテクチャをマスターしたことになります。
📋 前提知識：12-local-plugin.md の完了、cordis.yml 設定を理解していること
1. 学習内容
- profile：名前付き組み立て（web/headless）
- bundle：設定＋コード配布フォーマット
- dsh.profile と dsh.bundle フィールド
- dsh-base / dsh-web-app / dsh-headless
- 設定レイヤー構成順序
- patch オーバーレイ機構
2. profile：名前付き組み立て
(1) profile の概念
profile は名前で識別されるプラグイン組み合わせのプリセット：
TEXT
📖 参照専用
web profile: → Web UI プラグイン、インタラクティブツールを含む
headless profile: → UI なし、純粋な API + スクリプト実行
ci profile: → 最小プラグインセット、テストに必要なもののみ
(2) profile の設定
package.json で profile を宣言：
JSON
{
"name": "my-dsh-project",
"dsh": {
"profiles": {
"web": {
"description": "Web UI mode for interactive development",
"plugins": [
"@deepseek-ai/dsh-web-app",
"@deepseek-ai/dsh-plugin-tools-interactive"
]
},
"headless": {
"description": "Headless mode for automation",
"plugins": [
"@deepseek-ai/dsh-headless",
"@deepseek-ai/dsh-plugin-tools-basic"
]
}
}
}
}
▶ サンプル 3：
BASH
# web profile を使用
pnpm dsh web --profile web
# headless profile を使用
pnpm dsh headless --profile headless
(4) profile の構成要素
| 構成要素 | 説明 |
|---|---|
| プラグインリスト | どのプラグインを含めるか |
| 説明 | profile の用途 |
| デフォルト設定 | プラグインのデフォルトパラメータ |
3. bundle：設定＋コード配布フォーマット
(1) bundle の概念
bundle は profile ＋設定＋コードのパッケージング形式で、npm パッケージのように配布可能：
TEXT
📖 参照専用
profile: どのプラグインを選ぶか
bundle: プラグイン＋設定＋バージョンロック → 配布可能パッケージ
▶ サンプル 2：
TEXT
📖 参照専用
dsh-bundle-my-team/
├── package.json ← dsh.bundle フィールド
├── cordis.yml ← デフォルト設定
├── plugins/
│ ├── team-tools/ ← 内蔵プラグイン
│ └── team-lint/ ← 内蔵プラグイン
└── profiles/
├── web.yml ← web profile 設定
└── headless.yml ← headless profile 設定
▶ サンプル 3：
JSON
{
"name": "@my-team/dsh-bundle",
"version": "1.0.0",
"dsh": {
"bundle": true,
"profiles": {
"web": "./profiles/web.yml",
"headless": "./profiles/headless.yml"
},
"baseConfig": "./cordis.yml",
"plugins": [
"./plugins/team-tools",
"./plugins/team-lint"
]
}
}
(4) bundle のインストール
BASH
# npm からインストール
pnpm add @my-team/dsh-bundle
# bundle の profile を使用して起動
pnpm dsh web --bundle @my-team/dsh-bundle --profile web
4. dsh-base / dsh-web-app / dsh-headless
(1) 組み込み Bundle
DSH は3つの組み込み bundle を提供：
| Bundle | 説明 | 含まれる主要プラグイン |
|---|---|---|
| dsh-base | 最小ベースセット | core, llm, sessions, trajectory |
| dsh-web-app | Web UI フル版 | dsh-base + web-ui, interactive-tools |
| dsh-headless | UI なし版 | dsh-base + headless-runner, basic-tools |
(2) 依存関係
graph TB
BASE[dsh-base<br/>core + llm + sessions] --> WEB[dsh-web-app<br/>+ Web UI + interactive tools]
BASE --> HEADLESS[dsh-headless<br/>+ Headless runner + basic tools]
(3) デフォルトの動作
--bundle パラメータなしの場合、DSH はデフォルトで dsh-web-app を使用：
BASH
# pnpm dsh web --bundle dsh-web-app と等価
pnpm dsh web
(4) ベース Bundle の選択
BASH
# 最小 bundle（コアのみ）
pnpm dsh web --bundle dsh-base
# Web UI bundle（デフォルト）
pnpm dsh web --bundle dsh-web-app
# ヘッドレス bundle
pnpm dsh headless --bundle dsh-headless
5. 設定レイヤー構成順序
(1) マルチレイヤー設定オーバーレイ
DSH の最終設定は複数レイヤーから構成され、下から上へ優先度が増加：
graph TB
L1[Layer 1：Bundle デフォルト設定<br/>cordis.yml] --> L2[Layer 2：Profile 設定<br/>profiles/web.yml]
L2 --> L3[Layer 3：プロジェクト設定<br/>project cordis.yml]
L3 --> L4[Layer 4：Patch 設定<br/>cordis.patch.yml]
L4 --> L5[Layer 5：CLI パラメータ<br/>--patch, --config]
(2) オーバーレイルール
TEXT
📖 参照専用
Bundle デフォルト： { plugins：[core, llm], port：5173 }
Profile： { plugins：[+web-ui], debug：true }
プロジェクト設定： { plugins：[+my-tool], port：8080 }
Patch： { plugins：[+debug-tool] }
最終結果： { plugins：[core, llm, web-ui, my-tool, debug-tool],
port：8080, debug：true }
(3) プラグインリストのマージ
| 操作 | 効果 |
|---|---|
| 新規プラグイン | そのまま末尾に追加 |
| 同名プラグイン | 後のレイヤーが前を上書き |
$insert |
リスト末尾に追加 |
$replace |
同名プラグインを置換 |
(4) 設定値のマージ
TEXT
📖 参照専用
下層： { a：1, b：{ x：1, y：2 } }
上層： { b：{ y：3, z：4 }, c：5 }
結果： { a：1, b：{ x：1, y：3, z：4 }, c：5 }
ネストされたオブジェクトはディープマージ、スカラー値は上書き。
6. patch オーバーレイ機構
(1) cordis.patch.yml
patch ファイルは最優先度の設定オーバーライドで、開発中の一時調整に適しています：
YAML
# cordis.patch.yml
plugins：
debug-tools：
$insert：./dev-plugins/debug-tools
llm：
config：
debug：true
logRequests：true
(2) --patch パラメータ
BASH
# patch レイヤーを適用
pnpm dsh web --patch
# patch を適用しない
pnpm dsh web
(3) マルチ環境パッチ
TEXT
📖 参照専用
config/
├── cordis.yml ← ベース設定
├── cordis.patch.dev.yml ← 開発用パッチ
├── cordis.patch.staging.yml ← ステージング用パッチ
└── cordis.patch.prod.yml ← 本番用パッチ
環境切替：
BASH
# 開発
cp config/cordis.patch.dev.yml cordis.patch.yml
pnpm dsh web --patch
# 本番
cp config/cordis.patch.prod.yml cordis.patch.yml
pnpm dsh web --patch
(4) CLI 直接オーバーライド
最優先度の設定方法：
BASH
# ポートを直接オーバーライド
pnpm dsh web --config.port=8080
# LLM モデルを直接オーバーライド
pnpm dsh web --config.plugins.llm.config.model=deepseek-reasoner
❓ よくある質問
Q profile と bundle の関係は？
A bundle が profile を含みます。1つの bundle に複数の profile（web/headless/ci 等）を定義でき、起動時に1つを選択します。
Q dsh フィールドを書かなくても DSH を使えますか？
A はい。DSH はデフォルトで dsh-web-app bundle のデフォルト設定を使用します。dsh フィールドはカスタマイズ時のみ必要です。
Q bundle と npm パッケージの違いは？
A bundle は npm パッケージの上位互換——
dsh.bundle フィールドが追加された npm パッケージで、DSH に設定とプラグインの読み込み方法を伝えます。Q 設定レイヤーの競合をトラブルシューティングするには？
A
--dump-config で最終設定を確認：bash pnpm dsh web --patch --dump-config すべてのレイヤーがマージされた結果が表示され、競合の発生源を特定しやすくなります。Q 組み込み bundle なしで DSH を使えますか？
A はい、
--bundle dsh-base で最小コアセットのみをロードし、cordis.yml で独自に組み立てられます。Q patch ファイルは git にコミットすべき？
A 開発用パッチはコミット可（チーム共有）；本番用パッチはコミット不可（機密設定を含む）。
.gitignore で cordis.patch.prod.yml を除外することを推奨。📖 まとめ
- profile は名前付きプラグイン組み合わせスキーム（web/headless/ci 等）
- bundle は profile＋設定＋コードを配布可能パッケージにまとめたもの
- 3つの組み込み bundle：dsh-base（最小）、dsh-web-app（Web UI）、dsh-headless（UI なし）
- 設定5層オーバーレイ：Bundle → Profile → Project → Patch → CLI；後のレイヤーが前を上書き
- cordis.patch.yml は最優先度設定ファイル；
--patchで有効化 --dump-configで最終マージ設定を確認；競合トラブルシューティングに必須
📝 練習問題
1. ⭐ 基礎：プロジェクトの package.json に dsh.profiles フィールドを追加し、web と headless profile を定義してください。各 profile で DSH を起動し、ロードされるプラグインリストを比較。
2. ⭐⭐ 応用：cordis.patch.dev.yml を作成し、開発モードで debug-tools プラグインをロードし、LLM リクエストロギングを有効にしてください。--patch で起動し、--dump-config で patch レイヤーのオーバーライド効果を確認。
3. ⭐⭐⭐ チャレンジ：カスタム profile、2つの内蔵プラグイン、デフォルト設定を含む完全な bundle パッケージを作成してください。ローカル npm レジストリ（または file: プロトコル）に公開し、別のプロジェクトからインストールしてこの bundle で起動。
