Расширения 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 extension-name.

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

qwen extensions update --all

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

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

Создание шаблона расширения

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

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

qwen extensions new path/to/directory 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".

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