DeepSeek Harness バンドル bundle と profile:2 つの manifest

前の章では、私たちは--patchoverlay でローカルプラグインを読み込んでいましたが、この記事からはそれらをインストール可能なバンドルにパッケージ化します。

この章では、最も基本的な 2 つの概念を明確に説明します:bundle(バンドル)とprofile、およびそれらそれぞれの manifest。


2 つの概念、2 つの manifest

インストールの仕組みは 2 つの概念に基づいており、どちらも 1 つの package.json で記述されます。

それらはdshキーの下で保持する manifest の種類が異なり、答える問いも異なります。

bundle 与 profile 关系图

バンドルは、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 ファイル)プラグイン作者が作成し、パッケージとともに配布
profiledsh.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、プラグインエントリを書き込みます。

例

// ファイルパス:hello-plugin/index.js
export const name = 'hello-plugin'  // プラグイン名。ログと診断に使用

export function apply() {
  console.log('[hello-plugin] plugin loaded!')  // ロード時に 1 行のログを出力
}

作成しhello-plugin/cordis.patch.yml。

例

# ファイルパス: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 は任意、name は bundle パッケージ内の startup モジュールを指す
- id
: hello-startup
  name
: 'dsh-hello-plugin/startup'

これらのパラメータで設定された行はプロバイダーサービスの注入を受け、自身の!!jsオプションでそれを読み取り、同時にデプロイ時の値を横にフォールバックとして記述します。

例

# 例:ポート番号はプロバイダーサービスから取得し、取得できない場合は 8080 にフォールバック
- 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 は異なります。

自己テスト問題:

  1. bundle の manifest はどのキーを宣言し、どのような質問に答えますか?
  2. profile はどのディレクトリにあり、その manifest はどのような質問に答えますか?
  3. なぜ hello-plugin の cordis.patch.yml では相対ソースパスではなくパッケージ名を使うのですか?
その他の拡張