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

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

• Репозиторий Git
• Релизы на Github

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

Релиз через репозиторий git

Это самый гибкий и простой вариант. Все, что вам нужно сделать, это создать общедоступный репозиторий git (например, публичный репозиторий на GitHub), после чего пользователи смогут установить ваше расширение с помощью команды qwen extensions install <ваш-uri-репозитория>. Для репозитория на GitHub можно использовать упрощенный формат qwen extensions install <организация>/<репозиторий>. При необходимости пользователи могут указать конкретную ссылку (ветку/тег/коммит), используя аргумент --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 со своей стабильной веткой (которая может быть вашей веткой по умолчанию или другой веткой).

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

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

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

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

При проверке обновлений Qwen Code будет искать последний релиз на GitHub (вы должны отметить его соответствующим образом при создании релиза), если только пользователь не установил конкретный релиз, передав параметр --ref=<some-release-tag>. В настоящее время мы не поддерживаем возможность использования предварительных релизов или семантического версионирования (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