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

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

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

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

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

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

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

Настройка окружения разработки

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

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-code, так и контейнер изоляции, выполните build:all из корневого каталога:


npm run build:all

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

Запуск

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


npm start

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

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

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

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

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


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

После клонирования создайте файл precommit-хука git, чтобы ваши коммиты всегда были чистыми.


echo "
# Выполнить сборку npm и проверить на ошибки
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-code

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

React DevTools

Для отладки React-интерфейса CLI можно использовать 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.

Песочница

TBD

Ручная публикация

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


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