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

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

Процесс внесения изменений

Ревью кода

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

Настройка окружения и рабочий процесс

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

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

Требования:

Node.js:
- Для разработки: Используйте Node.js ~20.19.0. Эта конкретная версия необходима из-за проблемы с зависимостью для разработки в upstream-пакете. Для управления версиями Node.js можно использовать nvm .
- Для продакшена: Для запуска CLI в продакшен-окружении подойдёт любая версия Node.js >=20.
Git

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

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


git clone https://github.com/QwenLM/qwen-code.git # Or your fork's 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.

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

В проекте используются два типа тестов: юнит-тесты и интеграционные тесты.

Юнит-тесты

Чтобы запустить набор юнит-тестов проекта:


npm run test

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

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

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

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


npm run test:e2e

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

Линтинг и префлайт-проверки

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


npm run preflight

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

Совет

После клонирования создайте файл git precommit 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/: Интерфейс командной строки (CLI).
- core/: Основная серверная логика Qwen Code.
docs/: Содержит всю документацию проекта.
scripts/: Вспомогательные скрипты для сборки, тестирования и задач разработки.

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

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

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

Требования

Убедитесь, что установлен Node.js (версии 18+)
Убедитесь, что доступны 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

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

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.

Песочница (Sandboxing)

TBD

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

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


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