Skip to Content
Руководство для пользователейРасширениеВыпуск расширений

Выпуск расширений

Существует три основных способа выпуска расширений для пользователей:

Выпуски через Git-репозиторий, как правило, являются самым простым и гибким подходом, в то время как релизы GitHub могут быть более эффективными при первоначальной установке, так как они поставляются в виде одного архива вместо клонирования репозитория, при котором каждый файл загружается отдельно. Релизы GitHub также могут содержать архивы, специфичные для платформы, если вам нужно поставлять платформозависимые бинарные файлы. Выпуски через реестр npm идеально подходят для команд, которые уже используют npm для распространения пакетов, особенно с частными реестрами.

Выпуск через Git-репозиторий

Это самый гибкий и простой вариант. Всё, что вам нужно сделать, — это создать общедоступный Git-репозиторий (например, публичный репозиторий на GitHub), после чего пользователи смогут установить ваше расширение с помощью qwen extensions install <uri-вашего-репозитория>, а для репозитория GitHub они могут использовать упрощённый формат qwen extensions install <орг>/<репозиторий>. При необходимости они могут указать конкретную ссылку (ветку/тег/коммит) с помощью аргумента --ref=<какая-то-ссылка>, по умолчанию используется ветка по умолчанию.

Когда коммиты отправляются в ссылку, от которой зависит пользователь, ему будет предложено обновить расширение. Обратите внимание, что это также позволяет легко выполнять откат: HEAD-коммит всегда считается последней версией независимо от фактической версии в файле qwen-extension.json.

Управление каналами выпуска с помощью Git-репозитория

Пользователи могут зависеть от любой ссылки из вашего Git-репозитория, например, ветки или тега, что позволяет вам управлять несколькими каналами выпуска.

Например, вы можете поддерживать ветку stable, которую пользователи могут установить так: qwen extensions install <uri-вашего-репозитория> --ref=stable. Или вы можете сделать её веткой по умолчанию, рассматривая свою ветку по умолчанию как стабильный канал выпуска, а разработку вести в другой ветке (например, dev). Вы можете поддерживать любое количество веток или тегов, обеспечивая максимальную гибкость для себя и своих пользователей.

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

Пример процесса выпуска с использованием Git-репозитория

Хотя существует множество вариантов управления выпусками с помощью Git-процесса, мы рекомендуем рассматривать вашу ветку по умолчанию как «стабильный» канал выпуска. Это означает, что поведение по умолчанию для qwen extensions install <uri-вашего-репозитория> — находиться в стабильной ветке.

Допустим, вы хотите поддерживать три стандартных канала выпуска: stable, preview и dev. Вы будете вести всю стандартную разработку в ветке dev. Когда вы будете готовы к предварительному выпуску, вы сольёте эту ветку в ветку preview. Когда вы будете готовы продвинуть предварительный выпуск в стабильный, вы сольёте preview в свою стабильную ветку (которая может быть вашей веткой по умолчанию или другой веткой).

Вы также можете выбирать отдельные изменения из одной ветки в другую с помощью git cherry-pick, но учтите, что это приведёт к тому, что ваши ветки будут иметь несколько расходящуюся историю, если только вы не будете принудительно отправлять изменения в свои ветки при каждом выпуске, чтобы восстановить историю с чистого листа (что может быть невозможно для ветки по умолчанию в зависимости от настроек вашего репозитория). Если вы планируете использовать cherry-pick, возможно, вам стоит избегать назначения ветки по умолчанию в качестве стабильной, чтобы избежать принудительной отправки в ветку по умолчанию, чего обычно следует избегать.

Выпуск через релизы GitHub

Расширения Qwen Code могут распространяться через релизы GitHub . Это обеспечивает более быструю и надёжную первоначальную установку для пользователей, так как нет необходимости клонировать репозиторий.

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

При проверке обновлений Qwen Code будет искать последний релиз на GitHub (вы должны отметить его как таковой при создании релиза), если только пользователь не установил конкретную версию, передав --ref=<какой-то-тег-релиза>. На данный момент мы не поддерживаем участие в предварительных релизах или семантическом версионировании.

Пользовательские предварительно собранные архивы

Пользовательские архивы должны быть напрямую прикреплены к релизу GitHub как ассеты и должны быть полностью самодостаточными. Это означает, что они должны содержать всё расширение; см. структура архива.

Если ваше расширение не зависит от платформы, вы можете предоставить один универсальный ассет. В этом случае к релизу должен быть прикреплён только один ассет.

Пользовательские архивы также могут использоваться, если вы хотите разрабатывать расширение в составе более крупного репозитория; вы можете собрать архив, структура которого отличается от структуры самого репозитория (например, это может быть архив только поддиректории, содержащей расширение).

Архивы для конкретных платформ

Чтобы Qwen Code мог автоматически найти правильный ассет релиза для каждой платформы, необходимо следовать следующему соглашению об именовании. CLI будет искать ассеты в следующем порядке:

  1. По платформе и архитектуре: {платформа}.{архитектура}.{имя}.{расширение}
  2. По платформе: {платформа}.{имя}.{расширение}
  3. Универсальный: Если предоставлен только один ассет, он будет использоваться как универсальный запасной вариант.
  • {имя}: Имя вашего расширения.
  • {платформа}: Операционная система. Поддерживаемые значения:
    • darwin (macOS)
    • linux
    • win32 (Windows)
  • {архитектура}: Архитектура. Поддерживаемые значения:
    • x64
    • arm64
  • {расширение}: Расширение файла архива (например, .tar.gz или .zip).

Примеры:

  • darwin.arm64.my-tool.tar.gz (только для Mac на Apple Silicon)
  • darwin.my-tool.tar.gz (для всех Mac)
  • linux.x64.my-tool.tar.gz
  • win32.my-tool.zip

Структура архива

Архивы должны быть полностью самодостаточными расширениями и соответствовать всем стандартным требованиям — в частности, файл qwen-extension.json должен находиться в корне архива.

Остальная структура должна в точности соответствовать типичному расширению; см. introduction.md.

Пример рабочего процесса GitHub Actions

Вот пример рабочего процесса GitHub Actions, который собирает и выпускает расширение Qwen Code для нескольких платформ:

name: Release Extension
 
on:
  push:
    tags:
      - 'v*'
 
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
 
      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '22'
 
      - name: Install dependencies
        run: npm ci
 
      - name: Build extension
        run: npm run build
 
      - name: Create release assets
        run: |
          npm run package -- --platform=darwin --arch=arm64
          npm run package -- --platform=linux --arch=x64
          npm run package -- --platform=win32 --arch=x64
 
      - name: Create GitHub Release
        uses: softprops/action-gh-release@v1
        with:
          files: |
            release/darwin.arm64.my-tool.tar.gz
            release/linux.arm64.my-tool.tar.gz
            release/win32.arm64.my-tool.zip

Выпуск через реестр npm

Вы можете публиковать расширения Qwen Code как scoped-пакеты npm (например, @your-org/my-extension). Это хороший вариант, когда:

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

Требования к пакету

Ваш npm-пакет должен включать файл qwen-extension.json в корне пакета. Это тот же конфигурационный файл, который используется всеми расширениями Qwen Code — npm-тарбол — это просто ещё один механизм доставки.

Минимальная структура пакета выглядит так:

my-extension/
├── package.json
├── qwen-extension.json
├── QWEN.md              # необязательный контекстный файл
├── commands/             # необязательные пользовательские команды
├── skills/               # необязательные пользовательские навыки
└── agents/               # необязательные пользовательские под-агенты

Убедитесь, что qwen-extension.json включён в публикуемый пакет (т.е. не исключён через .npmignore или поле files в package.json).

Публикация

Используйте стандартные инструменты публикации npm:

# Публикация в реестр по умолчанию
npm publish
 
# Публикация в частный/пользовательский реестр
npm publish --registry https://your-registry.com

Установка

Пользователи устанавливают ваше расширение, используя scoped-имя пакета:

# Установка последней версии
qwen extensions install @your-org/my-extension
 
# Установка конкретной версии
qwen extensions install @your-org/my-extension@1.2.0
 
# Установка из пользовательского реестра
qwen extensions install @your-org/my-extension --registry https://your-registry.com

Поведение при обновлении

  • Расширения, установленные без фиксации версии (например, @scope/pkg), отслеживают dist-tag latest.
  • Расширения, установленные с dist-tag (например, @scope/pkg@beta), отслеживают этот конкретный тег.
  • Расширения, закреплённые за точной версией (например, @scope/pkg@1.2.0), всегда считаются актуальными и не будут предлагать обновления.

Аутентификация для частных реестров

Qwen Code автоматически считывает учётные данные npm:

  1. Переменная окружения NPM_TOKEN — наивысший приоритет
  2. Файл .npmrc — поддерживает записи _authToken как на уровне хоста, так и для определённого пути (например, //your-registry.com/:_authToken=TOKEN или //pkgs.dev.azure.com/org/_packaging/feed/npm/registry/:_authToken=TOKEN)

Файлы .npmrc считываются из текущей директории и домашней директории пользователя.

Управление каналами выпуска

Вы можете использовать dist-tags npm для управления каналами выпуска:

# Публикация бета-версии
npm publish --tag beta
 
# Пользователи устанавливают бета-канал
qwen extensions install @your-org/my-extension@beta

Это работает аналогично каналам выпуска на основе веток Git, но использует собственный механизм dist-tag от npm.

Last updated on
ВведениеУстранение неполадок