Публикация плагина DeepSeek Harness: npm / GitHub / tarball
Локальная установка уже работает; мы можем распространить плагин для использования другими.
Публикация в реестре не требуется; есть три подхода: npm, tarball и Git.
У этих трёх совершенно разные требования к артефактам сборки; неправильный выбор приведёт к подводным камням на стороне пользователя.
Сравнение трёх способов распространения
В официальной документации приведены три способа распространения, ключевое различие — распространяются ли предварительно собранные артефакты.
| Метод | Команда установки для пользователя | Что устанавливается | Требуется ли одобрение сборки |
|---|---|---|---|
| npm publish | dsh plugin add your-package | Предварительно собранныйlib/Code | Не требуется |
| Доставка tarball | dsh plugin add ./hello-plugin-0.1.0.tgz | pnpm packСобранный пакет | Не требуется |
| Установка из Git | dsh 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 профиля, вот так.
Пример
# Скопируйте точный ключ пакета, выведенный 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 у пользователя.
Вопросы для самопроверки:
- Почему установка через git завершается ошибкой для TypeScript-пакетов? Что нужно сделать автору?
- Когда у пользователей pnpm ≥ 10 происходит сбой при первом add, как dsh предлагает это исправить?
- Почему рекомендуется зафиксировать sha коммита?