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

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

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

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

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

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

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

Управление каналами выпуска через Git-репозиторий

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

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

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

Пример процесса выпуска через Git-репозиторий

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

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

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

Выпуск через GitHub Releases

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

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

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

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

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

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

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

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

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

  1. Для конкретной платформы и архитектуры: {platform}.{arch}.{name}.{extension}
  2. Для конкретной платформы: {platform}.{name}.{extension}
  3. Универсальный: Если предоставлен только один ассет, он будет использоваться как резервный вариант.
  • {name}: имя вашего расширения.
  • {platform}: операционная система. Поддерживаемые значения:
    • darwin (macOS)
    • linux
    • win32 (Windows)
  • {arch}: архитектура. Поддерживаемые значения:
    • x64
    • arm64
  • {extension}: расширение файла архива (например, .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 должен находиться в корне архива.

Остальная структура должна полностью соответствовать типичному расширению. См. extensions.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: '20'
 
      - 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 Registry

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

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

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

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

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

my-extension/
├── package.json
├── qwen-extension.json
├── QWEN.md              # optional context file
├── commands/             # optional custom commands
├── skills/               # optional custom skills
└── agents/               # optional custom subagents

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

Публикация

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

# Publish to the default registry
npm publish
 
# Publish to a private/custom registry
npm publish --registry https://your-registry.com

Установка

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

# Install latest version
qwen extensions install @your-org/my-extension
 
# Install a specific version
qwen extensions install @your-org/my-extension@1.2.0
 
# Install from a custom registry
qwen extensions install @your-org/my-extension --registry https://your-registry.com

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

  • Расширения, установленные без фиксации версии (например, @scope/pkg), отслеживают dist-тег latest.
  • Расширения, установленные с указанием dist-тега (например, @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 считываются из текущей директории и домашней директории пользователя.

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

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

# Publish a beta release
npm publish --tag beta
 
# Users install beta channel
qwen extensions install @your-org/my-extension@beta

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

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