DeepSeek Harness バンドル bundle と profile:2 つの manifest
前の章では、私たちは--patchoverlay でローカルプラグインを読み込んでいましたが、この記事からはそれらをインストール可能なバンドルにパッケージ化します。
この章では、最も基本的な 2 つの概念を明確に説明します:bundle(バンドル)とprofile、およびそれらそれぞれの manifest。
2 つの概念、2 つの manifest
インストールの仕組みは 2 つの概念に基づいており、どちらも 1 つの package.json で記述されます。
それらはdshキーの下で保持する manifest の種類が異なり、答える問いも異なります。
バンドルは、1 つの設定レイヤーを伴う npm パッケージです。
その manifest は宣言しdsh.bundle、「このパッケージは何に貢献するのか」に答えます:プラグイン行を挿入または置換する patch ファイルです。
profile は$DSH_HOME/profiles/<name>の下に位置し、起動可能な構成一式を記述するディレクトリです。
その manifest は宣言しdsh.profile、「この構成はどのバンドルがどの順序で構成されるのか」に答えます。
bundleは、あなたが作成して配布するものです;profileはユーザーが
dsh --profile <name>で起動するものです。両方に該当するものはありません。
| 概念 | manifest キー | 答える問い | 誰が書く / 誰が使う |
|---|---|---|---|
| bundle(バンドル) | dsh.bundle | このパッケージが何に貢献するか(1 つの patch ファイル) | プラグイン作者が作成し、パッケージとともに配布 |
| profile | dsh.profile | この構成はどの bundle がどの順序で構成されるか | 由 dsh plugin自動で作成・保守され、ユーザーが起動 |
profile はインストールディレクトリの外部にあり、パステンプレートは$DSH_HOME/profiles/<name>。
実践:hello-plugin バンドルを作成
公式チュートリアルに従い、まずパッケージディレクトリを作成します。
例
mkdir -p hello-plugin
バンドルのディレクトリ構造は以下の通りで、全部で 3 つのファイルです。
例
hello-plugin/ ├── package.json # 声明 dsh.bundle ├── cordis.patch.yml # profile 列出该 bundle 时应用的配置层 └── index.js # patch 行引用的插件模块
作成しhello-plugin/package.json、バンドル manifest を宣言します。
例
"name": "dsh-hello-plugin",
"version": "0.1.0",
"type": "module",
"main": "index.js",
"files": ["index.js", "cordis.patch.yml"],
"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
}
package.json の各フィールドの意味は以下の通りです。
| フィールド | 説明 |
|---|---|
name | パッケージ名。Node のモジュール解決はこれを使ってインストール済みのコードを見つけます |
version | バージョン番号 |
type | "module"ESM モジュール形式を使用することを示します |
main | エントリファイル |
files | 公開時にのみ含めるファイルのリスト |
dsh.bundle.patch | バンドル manifest:貢献する patch ファイルのパスを宣言 |
作成しhello-plugin/index.js、プラグインエントリを書き込みます。
例
export const name = 'hello-plugin' // プラグイン名。ログと診断に使用
export function apply() {
console.log('[hello-plugin] plugin loaded!') // ロード時に 1 行のログを出力
}
作成しhello-plugin/cordis.patch.yml。
例
# この patch は、これまで使ってきた --patch overlay と同じく、patch エントリの YAML 配列です
# 違い:プラグイン行は相対ソースパスではなくパッケージ名で参照するため、Node のモジュール解決でインストール済みのコードを見つけられます
- insert:
- id: hello
name: dsh-hello-plugin
この patch は--patchoverlay と完全に同型です。
重要な違いはnameフィールドにあります:ここではパッケージ名を書きますdsh-hello-plugin、相対ソースパスではありません。
インストール後、pnpm がパッケージを node_modules にリンクするため、Node のモジュール解決はパッケージ名でインストール済みのコードを見つけられます。
「宣言を持たない」
dsh.bundleパッケージでもインストール可能ですが、通常の依存関係としてのみです。この場合
dsh plugin警告を出力し、いかなるレイヤーもアクティブにしません。ライブラリがプラグインパッケージによる import 用であり、ユーザーが有効化するためのものではない場合は、このパッケージ形式を使用します。
profile manifest:手書きは一切不要
profile ディレクトリには 2 つのファイルが含まれます。
1 つ目はpackage.json、profile のツリー外プラグイン依存関係(pnpm が管理)と、dsh.profilemanifest およびその順序付けられたbundlesリストが含まれます。
2 つ目はcordis.patch.yml、ユーザー自身の patch レイヤーであり、各バンドルレイヤーの後に適用されます。
profile manifest は手書きする必要は一切ありません。
dsh pluginがその作成と保守を担当します。次の記事でプラグインをインストールする際に、その実際の結果を紹介します。
発展:表層バンドルに独自のコマンドラインを持たせる
実行可能なアプリケーションを定義するバンドルは、通常のプロバイダープラグインをマウントすることで、独自のコマンドラインを持つことができます。
このプロバイダープラグインはエクスポートしinject = ['cmdlineArgs']、自身の commander program を使って呼び出しparseCmdline、さらに program 自身の action 内でアプリケーション独自のサービスを提供します。
例
- id: hello-startup
name: 'dsh-hello-plugin/startup'
これらのパラメータで設定された行はプロバイダーサービスの注入を受け、自身の!!jsオプションでそれを読み取り、同時にデプロイ時の値を横にフォールバックとして記述します。
例
- id: my-app
name: '@example/my-app'
inject: [myAppStartup]
config:
port: !!js ctx.myAppStartup.port ?? 8080
ランチャーは自身の flag 以降の同一の不変パラメータを各プラグインに渡すため、アプリケーション固有の flag を追加してもランチャーを変更する必要はなく、複数のプラグインが同じスナップショットを解析できます。
に遭遇した場合--help、プロバイダーはそのサービスを公開しないため、これらの行はアクティブになりません。
Loader は構成を一度だけマウントし、各行の通常の注入を待ってから、その注入済みコンテキストに基づいてその行の!!js設定を評価します。
まとめとセルフテスト
バンドルは宣言しdsh.bundle「何に貢献するか」に答えます。profile は宣言しdsh.profile「どの bundle で構成されるか」に答えます。両者は 1 つの package.json に格納されますが、manifest は異なります。
自己テスト問題:
- bundle の manifest はどのキーを宣言し、どのような質問に答えますか?
- profile はどのディレクトリにあり、その manifest はどのような質問に答えますか?
- なぜ hello-plugin の cordis.patch.yml では相対ソースパスではなくパッケージ名を使うのですか?