Публикация расширений

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

Git репозиторий
GitHub Releases

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

Релиз через 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 flow, но мы рекомендуем использовать вашу default ветку как “стабильную” (stable) ветку релиза. Это означает, что стандартное поведение команды qwen extensions install <your-repo-uri> будет устанавливать расширение из стабильной ветки.

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

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

Публикация через GitHub Releases

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

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

При проверке обновлений qwen code будет искать последний релиз на github (вы должны отметить его как таковой при создании релиза), если только пользователь не установил конкретный релиз, передав --ref=<some-release-tag>. В настоящее время мы не поддерживаем возможность выбора предварительных релизов или использование semver.

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

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

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

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

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

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

Специфичный для платформы и архитектуры: {platform}.{arch}.{name}.{extension}
Специфичный для платформы: {platform}.{name}.{extension}
Универсальный: Если предоставлен только один ассет, он будет использоваться как универсальный запасной вариант.

{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.

Пример workflow в GitHub Actions

Вот пример workflow в 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