Skip to Content
Руководство для разработчиковDevelopmentNPM

Обзор пакетов

Этот монорепозиторий содержит два основных пакета: @qwen-code/qwen-code и @qwen-code/qwen-code-core.

@qwen-code/qwen-code

Это основной пакет для Qwen Code. Он отвечает за пользовательский интерфейс, парсинг команд и всю остальную функциональность, с которой взаимодействует пользователь.

При публикации этот пакет собирается в один исполняемый файл. Этот бандл включает все зависимости пакета, включая @qwen-code/qwen-code-core. Это означает, что независимо от того, устанавливает ли пользователь пакет через npm install -g @qwen-code/qwen-code или запускает его напрямую через npx @qwen-code/qwen-code, он использует этот единый самодостаточный исполняемый файл.

@qwen-code/qwen-code-core

Этот пакет содержит основную логику CLI. Он отвечает за выполнение API-запросов к настроенным провайдерам, обработку аутентификации и управление локальным кешем.

Этот пакет не бандлится. При публикации он распространяется как стандартный Node.js-пакет со своими собственными зависимостями. Это позволяет использовать его как самостоятельный пакет в других проектах, если это необходимо. В пакет включается весь транспилированный JS-код из папки dist.

Процесс релиза

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

Как выпустить релиз

Релизы управляются через GitHub Actions workflow release.yml . Для ручного выпуска патча или хотфикса:

  1. Перейдите на вкладку Actions репозитория.
  2. Выберите workflow Release из списка.
  3. Нажмите кнопку выпадающего списка Run workflow.
  4. Заполните обязательные параметры:
    • Version: Точная версия для релиза (например, v0.2.1).
    • Ref: Ветка или SHA коммита, из которого будет собран релиз (по умолчанию main).
    • Dry Run: Оставьте true для тестирования workflow без публикации или установите false для выполнения реального релиза.
  5. Нажмите Run workflow.

Типы релизов

Проект поддерживает несколько типов релизов:

Стабильные релизы (Stable)

Обычные стабильные релизы для использования в production.

Превью-релизы (Preview)

Еженедельные превью-релизы каждый вторник в 23:59 UTC для раннего доступа к новым функциям.

Ночные релизы (Nightly)

Ежедневные ночные релизы в полночь UTC для тестирования самых свежих изменений в разработке.

Автоматическое расписание релизов

  • Nightly: Каждый день в полночь UTC
  • Preview: Каждый вторник в 23:59 UTC
  • Stable: Ручные релизы, запускаемые мейнтейнерами

Как использовать разные типы релизов

Для установки последней версии каждого типа:

# Stable (default)
npm install -g @qwen-code/qwen-code
 
# Preview
npm install -g @qwen-code/qwen-code@preview
 
# Nightly
npm install -g @qwen-code/qwen-code@nightly

Детали процесса релиза

Каждый запланированный или ручной релиз проходит следующие этапы:

  1. Получает указанный код (последний из ветки main или конкретный коммит).
  2. Устанавливает все зависимости.
  3. Запускает полный набор проверок preflight и интеграционных тестов.
  4. Если все тесты проходят успешно, вычисляется соответствующий номер версии в зависимости от типа релиза.
  5. Собирает и публикует пакеты в npm с соответствующим dist-tag.
  6. Создает GitHub Release для данной версии.

Обработка ошибок

Если какой-либо шаг workflow релиза завершается ошибкой, в репозитории автоматически создается новый issue с метками bug и специфичной для типа релиза меткой ошибки (например, nightly-failure, preview-failure). В issue будет содержаться ссылка на неудачный запуск workflow для упрощения отладки.

Валидация релиза

После публикации нового релиза необходимо провести smoke-тестирование, чтобы убедиться, что пакеты работают корректно. Для этого установите пакеты локально и запустите набор тестов для проверки их работоспособности.

  • npx -y @qwen-code/qwen-code@latest --version для проверки успешности публикации, если вы не использовали теги rc или dev
  • npx -y @qwen-code/qwen-code@<release tag> --version для проверки корректности публикации тега
  • Внимание: это удалит локальные пакеты npm uninstall @qwen-code/qwen-code && npm uninstall -g @qwen-code/qwen-code && npm cache clean --force && npm install @qwen-code/qwen-code@<version>
  • Рекомендуется провести базовое smoke-тестирование, выполнив несколько команд и инструментов LLM, чтобы убедиться в корректной работе пакетов. В будущем мы формализуем этот процесс.

Когда нужно мержить изменение версии, а когда нет?

Описанный выше паттерн создания патчей или хотфиксов на основе текущих или старых коммитов оставляет репозиторий в следующем состоянии:

  1. Тег (vX.Y.Z-patch.1): Этот тег корректно указывает на исходный коммит в main, содержащий стабильный код, который вы планировали выпустить. Это критически важно. Любой, кто сделает checkout этого тега, получит именно тот код, который был опубликован.
  2. Ветка (release-vX.Y.Z-patch.1): Эта ветка содержит один новый коммит поверх тегированного. Этот коммит включает только изменение номера версии в package.json (и других связанных файлах, например package-lock.json).

Такое разделение полезно. Оно сохраняет историю ветки main чистой от специфичных для релиза изменений версии до тех пор, пока вы не решите их смержить.

Это ключевое решение, которое полностью зависит от типа релиза.

Мерж обратно для стабильных патчей и хотфиксов

Для любого стабильного патча или хотфикса ветку release-<tag> почти всегда нужно мержить обратно в main.

  • Зачем? Основная причина — обновить версию в package.json ветки main. Если вы выпустите v1.2.1 из старого коммита, но никогда не смержите изменение версии обратно, package.json в main по-прежнему будет содержать "version": "1.2.0". Следующий разработчик, который начнет работу над релизом с новыми функциями (v1.3.0), будет создавать ветку от кодовой базы с некорректным, устаревшим номером версии. Это приведет к путанице и потребует ручного обновления версии в будущем.
  • Процесс: После создания ветки release-v1.2.1 и успешной публикации пакета создайте pull request для мержа release-v1.2.1 в main. Этот PR будет содержать всего один коммит: chore: bump version to v1.2.1. Это чистая и простая интеграция, которая синхронизирует ветку main с последней выпущенной версией.

НЕ мержить обратно для пре-релизов (RC, Beta, Dev)

Ветки релизов для пре-релизов обычно не мержат обратно в main.

  • Зачем? Пре-релизные версии (например, v1.3.0-rc.1, v1.3.0-rc.2) по определению нестабильны и носят временный характер. Не стоит засорять историю ветки main серией изменений версии для релиз-кандидатов. package.json в main должен отражать последнюю стабильную версию, а не RC.
  • Процесс: Создается ветка release-v1.3.0-rc.1, выполняется npm publish --tag rc, и на этом ветка выполняет свою задачу. Вы можете просто удалить её. Код для RC уже находится в main (или в feature-ветке), поэтому функциональный код не теряется. Ветка релиза служила лишь временным носителем для номера версии.

Локальное тестирование и валидация: изменения в процессе упаковки и публикации

Если вам нужно протестировать процесс релиза без фактической публикации в NPM или создания публичного GitHub Release, вы можете запустить workflow вручную через интерфейс GitHub.

  1. Перейдите на вкладку Actions  репозитория.
  2. Нажмите на выпадающий список “Run workflow”.
  3. Оставьте опцию dry_run включенной (true).
  4. Нажмите кнопку “Run workflow”.

Это запустит весь процесс релиза, но пропустит шаги npm publish и gh release create. Вы можете изучить логи workflow, чтобы убедиться, что всё работает корректно.

Крайне важно тестировать любые изменения в процессе упаковки и публикации локально перед коммитом. Это гарантирует корректную публикацию пакетов и их ожидаемую работу после установки пользователем.

Для валидации изменений вы можете выполнить dry run процесса публикации. Это симулирует публикацию без фактической отправки пакетов в реестр npm.

npm_package_version=9.9.9 SANDBOX_IMAGE_REGISTRY="registry" SANDBOX_IMAGE_NAME="thename" npm run publish:npm --dry-run

Эта команда выполнит следующее:

  1. Соберет все пакеты.
  2. Запустит все скрипты prepublish.
  3. Создаст tar-архивы пакетов, которые были бы опубликованы в npm.
  4. Выведет сводку по пакетам, готовым к публикации.

Затем вы можете проверить сгенерированные tar-архивы, чтобы убедиться, что они содержат правильные файлы и что package.json обновлены корректно. Архивы будут созданы в корне директории каждого пакета (например, packages/cli/qwen-code-0.1.6.tgz).

Выполняя dry run, вы можете быть уверены, что ваши изменения в процессе упаковки корректны и пакеты будут успешно опубликованы.

Детальный разбор процесса релиза

Основная цель процесса релиза — взять исходный код из директории packages/, собрать его и сформировать чистый, самодостаточный пакет во временной директории dist в корне проекта. Именно содержимое директории dist публикуется в NPM.

Ключевые этапы:

Этап 1: Предварительные проверки и версионирование

  • Что происходит: Перед перемещением файлов процесс гарантирует, что проект находится в стабильном состоянии. Это включает запуск тестов, линтинг и проверку типов (npm run preflight). Номер версии в корневом package.json и packages/cli/package.json обновляется до новой версии релиза.
  • Зачем: Это гарантирует, что будет выпущен только качественный и рабочий код. Версионирование — первый шаг, сигнализирующий о новом релизе.

Этап 2: Сборка исходного кода

  • Что происходит: Исходный код TypeScript в packages/core/src и packages/cli/src компилируется в JavaScript.
  • Перемещение файлов:
    • packages/core/src/*/.ts -> компилируется в -> packages/core/dist/
    • packages/cli/src/*/.ts -> компилируется в -> packages/cli/dist/
  • Зачем: Код TypeScript, написанный в процессе разработки, необходимо преобразовать в обычный JavaScript, который может выполняться в Node.js. Пакет core собирается первым, так как пакет cli зависит от него.

Этап 3: Бандлинг и сборка финального пакета для публикации

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

  1. Создание бандла:

    • Что происходит: Скрипт prepare-package.js создает чистый дистрибутив в директории dist.
    • Ключевые преобразования:
      • Копирует README.md и LICENSE в dist/
      • Копирует папку locales для поддержки интернационализации
      • Создает чистый package.json для дистрибутива только с необходимыми зависимостями
      • Минимизирует зависимости дистрибутива (без бандлинга runtime-зависимостей)
      • Сохраняет опциональные зависимости для node-pty

  2. Создание JavaScript-бандла:

    • Что происходит: Собранный JavaScript из packages/core/dist и packages/cli/dist бандлится в один исполняемый JS-файл с помощью esbuild.
    • Расположение файла: dist/cli.js
    • Зачем: Это создает единый оптимизированный файл, содержащий весь необходимый код приложения. Это упрощает пакет, устраняя необходимость в сложном разрешении зависимостей во время установки.

  3. Копирование статических и вспомогательных файлов:

    • Что происходит: Важные файлы, не являющиеся частью исходного кода, но необходимые для корректной работы или описания пакета, копируются в директорию dist.
    • Перемещение файлов:
      • README.md -> dist/README.md
      • LICENSE -> dist/LICENSE
      • locales/ -> dist/locales/
      • Vendor-файлы -> dist/vendor/
    • Зачем:
      • README.md и LICENSE — стандартные файлы, которые должны включаться в любой NPM-пакет.
      • locales поддерживает функции интернационализации
      • Vendor-файлы содержат необходимые runtime-зависимости

Этап 4: Публикация в NPM

  • Что происходит: Команда npm publish выполняется из корневой директории dist.
  • Зачем: Запуск npm publish из директории dist гарантирует, что в реестр NPM будут загружены только файлы, тщательно собранные на Этапе 3. Это предотвращает случайную публикацию исходного кода, тестов или конфигураций для разработки, обеспечивая чистый и минимальный пакет для пользователей.

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

NPM Workspaces

В этом проекте используются NPM Workspaces  для управления пакетами внутри монорепозитория. Это упрощает разработку, позволяя управлять зависимостями и запускать скрипты для нескольких пакетов из корня проекта.

Как это работает

Корневой файл package.json определяет workspaces для этого проекта:

{
  "workspaces": ["packages/*"]
}

Это указывает NPM, что любая папка внутри директории packages является отдельным пакетом, который должен управляться как часть workspace.

Преимущества Workspaces

  • Упрощенное управление зависимостями: Запуск npm install из корня проекта установит все зависимости для всех пакетов в workspace и свяжет их между собой. Это означает, что вам не нужно запускать npm install в директории каждого пакета.
  • Автоматическое связывание: Пакеты внутри workspace могут зависеть друг от друга. При запуске npm install NPM автоматически создаст символические ссылки между пакетами. Это означает, что при внесении изменений в один пакет они сразу становятся доступны другим пакетам, которые от него зависят.
  • Упрощенный запуск скриптов: Вы можете запускать скрипты любого пакета из корня проекта, используя флаг --workspace. Например, для запуска скрипта build в пакете cli выполните npm run build --workspace @qwen-code/qwen-code.
Last updated on
Руководство разработчика плагинов каналовТелеметрия