Как внести вклад

Мы будем рады принять ваши исправления и дополнения к этому проекту.

Процесс внесения вклада

Проверка кода

Все отправляемые изменения, включая изменения от участников проекта, требуют проверки. Для этого мы используем GitHub pull requests .

Настройка разработки и рабочий процесс

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

Настройка среды разработки

Предварительные требования:

Node.js:
- Разработка: Пожалуйста, используйте Node.js >=22. Ink 7 (используемый TUI) требует Node 22, а react@^19.2.0 является соответствующей peer-зависимостью. Вы можете использовать инструмент вроде nvm для управления версиями Node.js.
- Продуктивность: Для запуска CLI в продуктивной среде подойдёт любая версия Node.js >=22.
Git

Процесс сборки

Чтобы клонировать репозиторий:


git clone https://github.com/QwenLM/qwen-code.git # Или URL вашего форка
cd qwen-code

Чтобы установить зависимости, указанные в package.json, а также корневые зависимости:


npm install

Чтобы собрать весь проект (все пакеты):


npm run build

Эта команда обычно компилирует TypeScript в JavaScript, собирает ресурсы и подготавливает пакеты к выполнению. За более подробной информацией о том, что происходит во время сборки, обращайтесь к скриптам scripts/build.js и package.json.

Включение изоляции (Sandboxing)

Изоляция (Sandboxing) настоятельно рекомендуется и требует, как минимум, установки QWEN_SANDBOX=true в файле ~/.env и наличия провайдера изоляции (например, macOS Seatbelt, docker или podman). Подробнее см. в разделе Изоляция (Sandboxing).

Чтобы собрать как утилиту CLI qwen, так и контейнер изоляции, выполните build:all из корневого каталога:


npm run build:all

Чтобы пропустить сборку контейнера изоляции, можно использовать npm run build.

Запуск

Чтобы запустить приложение Qwen Code из исходного кода (после сборки), выполните следующую команду из корневого каталога:


npm start

Если вы хотите запустить собранную из исходников версию за пределами папки qwen-code, вы можете использовать npm link path/to/qwen-code/packages/cli (см. документацию ) для работы с qwen.

Запуск тестов

Этот проект содержит два типа тестов: модульные тесты и интеграционные тесты.

Модульные тесты

Чтобы выполнить набор модульных тестов проекта:


npm run test

Это запустит тесты, расположенные в каталогах packages/core и packages/cli. Убедитесь, что тесты проходят, прежде чем отправлять изменения. Для более комплексной проверки рекомендуется выполнить npm run preflight.

Интеграционные тесты

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

Чтобы запустить интеграционные тесты, используйте следующую команду:


npm run test:e2e

Более подробную информацию о фреймворке интеграционного тестирования можно найти в документации по интеграционным тестам.

Линтинг и предварительная проверка

Чтобы обеспечить качество кода и единообразие форматирования, выполните предварительную проверку:


npm run preflight

Эта команда запустит ESLint, Prettier, все тесты и другие проверки, определённые в package.json проекта.

ProTip

после клонирования создайте файл git pre-commit hook, чтобы гарантировать, что ваши коммиты всегда будут чистыми.


echo "
# Run npm build and check for errors
if ! npm run preflight; then
  echo "npm build failed. Commit aborted."
  exit 1
fi
" > .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit

Форматирование

Чтобы отдельно отформатировать код в этом проекте, выполните следующую команду из корневого каталога:


npm run format

Эта команда использует Prettier для форматирования кода в соответствии со стилем проекта.

Линтинг

Чтобы отдельно выполнить линтинг кода в этом проекте, выполните следующую команду из корневого каталога:


npm run lint

Соглашения о коде

Пожалуйста, придерживайтесь стиля, шаблонов и соглашений, используемых в существующей кодовой базе.
Импорты: Обратите особое внимание на пути импорта. Проект использует ESLint для ограничения относительных импортов между пакетами.

Структура проекта

packages/: Содержит отдельные подпакеты проекта.
- cli/: Интерфейс командной строки.
- core/: Основная серверная логика Qwen Code.
docs/: Содержит всю документацию проекта.
scripts/: Вспомогательные скрипты для сборки, тестирования и задач разработки.

Более подробную информацию об архитектуре см. в docs/architecture.md.

Разработка документации

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

Предварительные требования

Убедитесь, что у вас установлен Node.js (версия 22+)
Убедитесь, что у вас есть npm или yarn

Настройка сайта документации локально

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

Перейдите в каталог docs-site:
```
cd docs-site
```
Установите зависимости:
```
npm install
```
Свяжите содержимое документации из основного каталога docs:
```
npm run link
```
Это создаст символическую ссылку из ../docs на content в проекте docs-site, позволяя содержимому документации обслуживаться сайтом Next.js.
Запустите сервер разработки:
```
npm run dev
```
Откройте http://localhost:3000 в браузере, чтобы увидеть сайт документации с обновлениями в реальном времени по мере внесения изменений.

Любые изменения в файлах документации в основном каталоге docs будут немедленно отражены на сайте документации.

Отладка

VS Code:

Запустите CLI для интерактивной отладки в VS Code с помощью F5
Запустите CLI в режиме отладки из корневого каталога:
```
npm run debug
```
Эта команда запускает node --inspect-brk dist/index.js в каталоге packages/cli, приостанавливая выполнение до подключения отладчика. Затем вы можете открыть chrome://inspect в браузере Chrome для подключения к отладчику.
В VS Code используйте конфигурацию запуска “Attach” (находится в .vscode/launch.json).

В качестве альтернативы вы можете использовать конфигурацию “Launch Program” в VS Code, если предпочитаете запускать текущий открытый файл напрямую, но в целом рекомендуется использовать ‘F5’.

Чтобы установить точку останова внутри контейнера изоляции, выполните:


DEBUG=1 qwen

Примечание: Если у вас есть DEBUG=true в файле .env проекта, это не повлияет на qwen из-за автоматического исключения. Используйте файлы .qwen/.env для настроек отладки, специфичных для qwen.

React DevTools

Для отладки пользовательского интерфейса CLI на React вы можете использовать React DevTools. Ink, библиотека, используемая для интерфейса CLI, совместима с React DevTools версии 4.x.

Запустите приложение Qwen Code в режиме разработки:
```
DEV=true npm start
```
Установите и запустите React DevTools версии 4.28.5 (или последнюю совместимую версию 4.x):

Вы можете установить их глобально:
```
npm install -g react-devtools@4.28.5
react-devtools
```
Или запустить напрямую с помощью npx:
```
npx react-devtools@4.28.5
```
Ваше запущенное CLI-приложение должно подключиться к React DevTools.

Изоляция (Sandboxing)

TBD

Публикация вручную

Мы публикуем артефакт для каждого коммита в нашем внутреннем реестре. Но если вам нужно вручную сделать локальную сборку, выполните следующие команды:


npm run clean
npm install
npm run auth
npm run prerelease:dev
npm publish --workspaces