Расширения Qwen Code

Расширения Qwen Code упаковывают подсказки, серверы MCP и пользовательские команды в привычный и удобный формат. С помощью расширений вы можете расширить возможности Qwen Code и делиться этими возможностями с другими. Они разработаны для легкой установки и совместного использования.

Управление расширениями

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

Обратите внимание, что эти команды не поддерживаются из самой CLI, хотя вы можете перечислить установленные расширения, используя подкоманду /extensions list.

Обратите внимание, что все эти команды будут отражены только в активных сессиях CLI после перезапуска.

Установка расширения

Вы можете установить расширение, используя команду qwen extensions install с указанием URL на GitHub или локального пути.

Обратите внимание, что мы создаем копию установленного расширения, поэтому вам нужно будет запустить qwen extensions update, чтобы применить изменения как для локально определенных расширений, так и для расширений с GitHub.

qwen extensions install https://github.com/qwen-cli-extensions/security

Это установит расширение Qwen Code Security, которое предоставляет поддержку команды /security:analyze.

Удаление расширения

Чтобы удалить расширение, выполните команду qwen extensions uninstall имя-расширения. В случае из примера выше это будет:

qwen extensions uninstall qwen-cli-security

Отключение расширения

Расширения по умолчанию включены во всех рабочих областях. Вы можете отключить расширение полностью или для определенной рабочей области.

Например, команда qwen extensions disable extension-name отключит расширение на уровне пользователя, поэтому оно будет отключено повсюду. Команда qwen extensions disable extension-name --scope=workspace отключит расширение только в текущей рабочей области.

Включение расширения

Вы можете включать расширения с помощью команды qwen extensions enable extension-name. Также можно включить расширение для определенной рабочей области, используя команду qwen extensions enable extension-name --scope=workspace из этой рабочей области.

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

Обновление расширения

Для расширений, установленных из локального пути или репозитория git, вы можете явно обновить их до последней версии (как указано в поле version файла qwen-extension.json) с помощью команды qwen extensions update имя-расширения.

Вы можете обновить все расширения с помощью:

qwen extensions update --all

Создание расширений

Мы предоставляем команды, которые упрощают разработку расширений.

Создание заготовки расширения

Мы предлагаем несколько примеров расширений: context, custom-commands, exclude-tools и mcp-server. Вы можете ознакомиться с этими примерами здесь .

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

qwen extensions new путь/к/директории custom-commands

Связывание локального расширения

Команда qwen extensions link создаст символическую ссылку из каталога установки расширений в путь разработки.

Это удобно, чтобы вам не приходилось запускать qwen extensions update каждый раз, когда вы вносите изменения, которые хотите протестировать.

qwen extensions link path/to/directory

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

При запуске Qwen Code ищет расширения в <home>/.qwen/extensions

Расширения существуют как каталог, содержащий файл qwen-extension.json. Например:

<home>/.qwen/extensions/my-extension/qwen-extension.json

qwen-extension.json

Файл qwen-extension.json содержит конфигурацию расширения. Файл имеет следующую структуру:

{
  "name": "my-extension",
  "version": "1.0.0",
  "mcpServers": {
    "my-server": {
      "command": "node my-server.js"
    }
  },
  "contextFileName": "QWEN.md",
  "excludeTools": ["run_shell_command"]
}

• name: Имя расширения. Оно используется для уникальной идентификации расширения и разрешения конфликтов, когда команды расширения имеют то же имя, что и пользовательские или проектные команды. Имя должно быть в нижнем регистре или состоять из цифр, а также использовать тире вместо подчеркиваний или пробелов. Именно так пользователи будут ссылаться на ваше расширение в CLI. Обратите внимание, что мы ожидаем совпадения этого имени с именем каталога расширения.
• version: Версия расширения.
• mcpServers: Карта серверов MCP для настройки. Ключ — это имя сервера, а значение — конфигурация сервера. Эти серверы будут загружены при запуске так же, как серверы MCP, настроенные в файле settings.json. Если и расширение, и файл settings.json настраивают сервер MCP с одинаковым именем, преимущество получает сервер, определенный в файле settings.json.
  • Обратите внимание, что поддерживаются все параметры конфигурации сервера MCP, кроме trust.
• contextFileName: Имя файла, содержащего контекст для расширения. Он будет использоваться для загрузки контекста из каталога расширения. Если это свойство не используется, но в каталоге расширения присутствует файл QWEN.md, тогда будет загружен именно этот файл.
• excludeTools: Массив имен инструментов, которые нужно исключить из модели. Вы также можете указать ограничения для конкретных команд у инструментов, которые это поддерживают, например, у инструмента run_shell_command. Например, "excludeTools": ["run_shell_command(rm -rf)"] заблокирует команду rm -rf. Обратите внимание, что это отличается от функциональности excludeTools сервера MCP, которую можно перечислить в конфигурации сервера MCP. Важно: Инструменты, указанные в excludeTools, будут отключены для всего контекста разговора и повлияют на все последующие запросы в текущей сессии.

При запуске Qwen Code загружает все расширения и объединяет их конфигурации. При наличии конфликтов приоритет получает конфигурация рабочей области.

Пользовательские команды

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

Пример

Расширение с именем gcp со следующей структурой:

.qwen/extensions/gcp/
├── qwen-extension.json
└── commands/
    ├── deploy.toml
    └── gcs/
        └── sync.toml

Будет предоставлять следующие команды:

• /deploy — отображается как [gcp] Пользовательская команда из deploy.toml в справке
• /gcs:sync — отображается как [gcp] Пользовательская команда из sync.toml в справке

Разрешение конфликтов

Команды расширений имеют самый низкий приоритет. Когда возникает конфликт с пользовательскими или проектными командами:

1. Без конфликта: Команда расширения использует свое естественное имя (например, /deploy)
2. При конфликте: Команда расширения переименовывается с префиксом расширения (например, /gcp.deploy)

Например, если и пользователь, и расширение gcp определяют команду deploy:

• /deploy - Выполняет пользовательскую команду deploy
• /gcp.deploy - Выполняет команду deploy расширения (помечена тегом [gcp])

Переменные

Расширения Qwen Code позволяют использовать подстановку переменных в qwen-extension.json. Это может быть полезно, например, если вам нужна текущая директория для запуска сервера MCP с использованием "cwd": "${extensionPath}${/}run.ts".

Поддерживаемые переменные: