Публикация плагина DeepSeek Harness: npm / GitHub / tarball

Локальная установка уже работает; мы можем распространить плагин для использования другими.

Публикация в реестре не требуется; есть три подхода: npm, tarball и Git.

У этих трёх совершенно разные требования к артефактам сборки; неправильный выбор приведёт к подводным камням на стороне пользователя.


Сравнение трёх способов распространения

В официальной документации приведены три способа распространения, ключевое различие — распространяются ли предварительно собранные артефакты.

三种发布途径对比图

МетодКоманда установки для пользователяЧто устанавливаетсяТребуется ли одобрение сборки
npm publishdsh plugin add your-packageПредварительно собранныйlib/CodeНе требуется
Доставка tarballdsh plugin add ./hello-plugin-0.1.0.tgzpnpm packСобранный пакетНе требуется
Установка из Gitdsh plugin --profile demo add github:you/hello-pluginИсходный код (не результат сборки)Требуется (pnpm ≥ 10)

Ни npm, ни tarball не требуют разрешений на сборку, что делает их подходящими для сценариев, где вы не хотите, чтобы пользователи выполняли дополнительную авторизацию.

Установка из Git — самая гибкая, но ей нужно преодолеть препятствие «скрипт сборки».


Установка из Git: препятствие в виде скрипта сборки

Установка из Git загружает исходный код, а не артефакты сборки.

Ни один шаг не запускает ваш скрипт сборки, поэтому когда приходит TypeScript-пакет, нетlib/вывода, и загрузка завершится ошибкой.

Обе стороны должны сделать по одному действию.

На стороне автора вам нужно предоставить скриптprepare.

pnpm запускает его после установки из git, собирая точку входа для публикации из исходного кода.

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

turtle-uiЭто рабочий пример: его prepare запускает отдельный конфиг tsdown, который напрямую транспилируетsrc/, без ссылок на проекты и без проверки типов.

Пример

{
  "name": "dsh-hello-plugin",
  "scripts": {
    "prepare": "tsdown -c tsdown.publish.ts"
  }
}

Приведённый выше скрипт prepare должен быть самодостаточным: напрямую транспилироватьsrc/, не завися от соседней рабочей копии монорепозитория.

На стороне пользователя нужно одобрить сборку.

pnpm ≥ 10 отказывается запускать prepare-скрипты для git-зависимостей, пока это явно не разрешено, поэтому первая команда add завершится ошибкой.

dsh укажет на исправление: скопируйте точный ключ пакета, который вывел pnpm, в файлpnpm-workspace.yaml этого профиля。

dsh plugin --profile demo add github:you/hello-plugin

Первая команда add завершится ошибкой, потому что prepare не авторизован, и pnpm выведет точный ключ пакета.

Скопируйте это в pnpm-workspace.yaml профиля, вот так.

Пример

# Путь к файлу: $DSH_HOME/profiles/demo/pnpm-workspace.yaml
# Скопируйте точный ключ пакета, выведенный pnpm, разрешив ему запустить prepare
allowBuilds
:
  dsh-hello-plugin
: true

Затем снова выполните add.

dsh plugin --profile demo add github:you/hello-plugin   # 第二次通过

Будьте честны насчёт этого одобрения: оно позволяет коду пакета выполняться на вашей машине во время установки, а не внутри какой-либо песочницы, в которой работает агент.

Разрешайте только те пакеты, исходному коду которых вы доверяете, и фиксируйте коммит (github:you/hello-plugin#<sha>), чтобы будущие push-операции не могли незаметно изменить то, что фактически выполняется.

Синтаксис установки для фиксации коммита выглядит так.

dsh plugin --profile demo add github:you/hello-plugin#a1b2c3d   # 锁定到具体 commit

npm и tarball: авторизация без сборки

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

Ни один из следующих двух способов не требует разрешений на сборку.

Первый подход: публикация в npm.

Вpnpm publishсборка выполняется в это времяlib/, пользовательdsh plugin add your-packageУстанавливается предварительно собранный код.

# 作者侧:先构建再发布
pnpm build
pnpm publish

# 用户侧:安装的是预构建代码,无需授权
dsh plugin add your-package

Второй вариант: доставка tarball.

используйтеpnpm packдля упаковки, пользователь выполняетdsh plugin add ./hello-plugin-0.1.0.tgz。

# 作者侧:打出 tgz
pnpm pack

# 用户侧:直接安装 tarball 文件
dsh plugin add ./hello-plugin-0.1.0.tgz

Рекомендации: если исходный код вызывает доверие и вы хотите пропустить процесс сборки, используйте установку через git и зафиксируйте коммит; обычным пользователям лучше предпочитать публикацию в npm или доставку tarball, что позволяет пользователям устанавливать напрямую без каких-либо разрешений.


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

Три способа распространения различаются тем, распространяются ли предварительно собранные артефакты: npm и tarball не требуют разрешения на сборку; установка через Git загружает исходный код и требует наличия у автора самодостаточного скрипта prepare и разрешения allowBuilds у пользователя.

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

  1. Почему установка через git завершается ошибкой для TypeScript-пакетов? Что нужно сделать автору?
  2. Когда у пользователей pnpm ≥ 10 происходит сбой при первом add, как dsh предлагает это исправить?
  3. Почему рекомендуется зафиксировать sha коммита?
Другие расширения