DeepSeek Harness: комбинированный бандл и профиль: два манифеста

В предыдущих главах мы использовали--patchОверлей загружает локальные плагины; начиная с этой статьи, мы упаковываем их в устанавливаемые бандлы.

В этом разделе мы разъясним два самых фундаментальных понятия:бандлипрофиль, а также их соответствующие манифесты.


Две концепции, два вида манифестов

Механизм установки построен на двух концепциях, обе описываются одним package.json.

Они находятся вdsh. Тип манифеста, содержащегося под ключом, различается, как и вопросы, на которые он отвечает.

bundle 与 profile 关系图

Бандл — это npm-пакет с присоединённым слоем конфигурации.

Его манифест объявляетdsh.bundle, отвечает на вопрос "что вносит этот пакет": файл патча, который вставляет или переопределяет строки плагинов.

Профиль находится под$DSH_HOME/profiles/<name>, описывая каталог загрузочного бандла.

Его манифест объявляетdsh.profile, отвечает на вопрос: «какие бандлы составляют эту конфигурацию и в каком порядке».

bundle— это то, что вы пишете и распространяете;profileиспользуется пользователемdsh --profile <name>то, что нужно загрузить.

Ничто не может быть одновременно и тем, и другим.

Концепцииключ манифестаОтвечает на вопросыКто пишет / кто использует
bundle (комбинированный пакет)dsh.bundleЧто вносит этот пакет (файл патча)Написан автором плагина, распространяется вместе с пакетом
profiledsh.profileКакие бандлы составляют эту конфигурацию и в каком порядкеотdsh pluginАвтоматически создаётся и поддерживается, запускается пользователем

Профиль расположен вне каталога установки; шаблон пути:$DSH_HOME/profiles/<name>。


Практическое задание: создайте составной пакет hello-plugin

Согласно официальному руководству, сначала создайте каталог пакета.

Пример

mkdir -p hello-plugin

Структура каталога бандла следующая, всего три файла.

Пример

hello-plugin/
├── package.json       # 声明 dsh.bundle
├── cordis.patch.yml   # profile 列出该 bundle 时应用的配置层
└── index.js           # patch 行引用的插件模块

Создайтеhello-plugin/package.json, объявите манифест составного пакета.

Пример

{
  "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 следующие.

FieldsОписание
nameИмя пакета; разрешение модулей Node использует его для поиска установленного кода
versionНомер версии
type"module"Указывает на использование формата модулей ESM
mainФайл точки входа
filesСписок файлов, включаемых только при публикации
dsh.bundle.patchМанифест бандла: объявляет путь к добавляемому файлу патча

Создайтеhello-plugin/index.js, записанный в точку входа плагина.

Пример

// Путь к файлу: hello-plugin/index.js
export const name = 'hello-plugin'  // Имя плагина, используется для логирования и диагностики

export function apply() {
  console.log('[hello-plugin] plugin loaded!')  // Вывести строку лога при загрузке
}

Создайтеhello-plugin/cordis.patch.yml。

Пример

# Путь к файлу: hello-plugin/cordis.patch.yml
# Этот патч, как и обычный оверлей --patch, представляет собой YAML-массив записей патча.
# Отличие: строки плагина ссылаются по имени пакета, а не по относительному пути к исходному коду, поэтому разрешение модулей Node может найти установленный код
- insert
:
    - id
: hello
      name
: dsh-hello-plugin

Этот патч и--patchоверлей полностью изоморфны.

Ключевое отличие — полеname: здесь указывается имя пакетаdsh-hello-plugin, а не относительный путь к исходному коду.

После установки pnpm создаёт ссылку на пакет в node_modules, поэтому механизм разрешения модулей Node может найти установленный код по имени пакета.

нетdsh.bundleОбъявленный пакет всё ещё можно установить, но только как обычную зависимость.

на данный моментdsh pluginОн выведет предупреждение и не активирует ни одного слоя.

Если библиотека предназначена для импорта пакетами плагинов, а не для включения пользователями, используйте этот формат пакета.


манифест профиля: никогда не нужно писать вручную

Каталог профиля содержит два файла.

Первый — этоpackage.json, содержит внешние (out-of-tree) зависимости плагинов профиля (управляемые pnpm), плюсdsh.profileМанифест и его упорядоченный списокbundles.

Второй — этоcordis.patch.yml, это собственный слой патчей пользователя, применяемый после слоя каждого бандла.

Манифест профиля никогда не нужно писать вручную.

dsh pluginотвечает за его создание и поддержку; следующая статья покажет его реальные результаты при установке плагина.


Продвинутый уровень: позволить surface-бандлу хранить собственную командную строку

Бандл, определяющий запускаемое приложение, может подключить обычный плагин-провайдер, чтобы хранить собственную командную строку.

Этот плагин-провайдер экспортируетinject = ['cmdlineArgs'], вызывайте его с помощью своей программы commanderparseCmdline, затем предоставить собственные сервисы приложения в собственном действии программы.

Пример

# Плагин-провайдер монтирования: id произвольный, name указывает на стартовый модуль в пакете bundle.
- id
: hello-startup
  name
: 'dsh-hello-plugin/startup'

Строки, настроенные этими параметрами, внедрят сервис провайдера и прочитают его в своих собственных!!jsoptions, записывая значение развёртывания рядом как резервное.

Пример

# Пример: номер порта берётся из сервиса провайдера; если недоступен, используется резервное значение 8080.
- id
: my-app
  name
: '@example/my-app'
  inject
: [myAppStartup]
  config
:
    port
: !!js ctx.myAppStartup.port ?? 8080

Лаунчер передаёт одни и те же неизменяемые аргументы после своих собственных флагов каждому плагину, поэтому добавление флагов, специфичных для приложения, не требует изменений в лаунчере, а несколько плагинов могут разобрать один и тот же снимок.

encounter--helpкогда , провайдер не опубликует сервис, поэтому эти строки не будут активированы.

Загрузчик монтирует композицию только один раз, ожидает обычной инъекции каждой строки, а затем вычисляет строку на основе её внедрённого контекста.!!jsКонфигурация.


Итог и самопроверка

Объединённое объявление пакетаdsh.bundleЧтобы ответить на вопрос "что вносится", профиль объявляетdsh.profileОтветьте, "из каких бандлов он состоит"; оба содержатся в одном package.json, но имеют разные манифесты.

Вопросы для самопроверки:

  1. Какой ключ объявляет манифест бандла, и на какой вопрос он отвечает?
  2. В каком каталоге расположен профиль, и на какой вопрос отвечает его манифест?
  3. Почему в cordis.patch.yml плагина hello-plugin используется имя пакета вместо относительного пути к исходному коду?
Другие расширения