DeepSeek Harness: комбинированный бандл и профиль: два манифеста
В предыдущих главах мы использовали--patchОверлей загружает локальные плагины; начиная с этой статьи, мы упаковываем их в устанавливаемые бандлы.
В этом разделе мы разъясним два самых фундаментальных понятия:бандлипрофиль, а также их соответствующие манифесты.
Две концепции, два вида манифестов
Механизм установки построен на двух концепциях, обе описываются одним package.json.
Они находятся вdsh. Тип манифеста, содержащегося под ключом, различается, как и вопросы, на которые он отвечает.
Бандл — это npm-пакет с присоединённым слоем конфигурации.
Его манифест объявляетdsh.bundle, отвечает на вопрос "что вносит этот пакет": файл патча, который вставляет или переопределяет строки плагинов.
Профиль находится под$DSH_HOME/profiles/<name>, описывая каталог загрузочного бандла.
Его манифест объявляетdsh.profile, отвечает на вопрос: «какие бандлы составляют эту конфигурацию и в каком порядке».
bundle— это то, что вы пишете и распространяете;profileиспользуется пользователем
dsh --profile <name>то, что нужно загрузить.Ничто не может быть одновременно и тем, и другим.
| Концепции | ключ манифеста | Отвечает на вопросы | Кто пишет / кто использует |
|---|---|---|---|
| bundle (комбинированный пакет) | dsh.bundle | Что вносит этот пакет (файл патча) | Написан автором плагина, распространяется вместе с пакетом |
| profile | dsh.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, записанный в точку входа плагина.
Пример
export const name = 'hello-plugin' // Имя плагина, используется для логирования и диагностики
export function apply() {
console.log('[hello-plugin] plugin loaded!') // Вывести строку лога при загрузке
}
Создайте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: hello-startup
name: 'dsh-hello-plugin/startup'
Строки, настроенные этими параметрами, внедрят сервис провайдера и прочитают его в своих собственных!!jsoptions, записывая значение развёртывания рядом как резервное.
Пример
- 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, но имеют разные манифесты.
Вопросы для самопроверки:
- Какой ключ объявляет манифест бандла, и на какой вопрос он отвечает?
- В каком каталоге расположен профиль, и на какой вопрос отвечает его манифест?
- Почему в cordis.patch.yml плагина hello-plugin используется имя пакета вместо относительного пути к исходному коду?