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

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

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

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

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

Вы можете включать расширения с помощью команды qwen extensions enable extension-name. Также можно включить расширение для конкретного workspace, используя команду qwen extensions enable extension-name --scope=workspace внутри этого 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-сервера, которая может быть указана в его конфиге.

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

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

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

Пример

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

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

Предоставит следующие команды:

• /deploy - Отображается как [gcp] Custom command from deploy.toml в справке
• /gcs:sync - Отображается как [gcp] Custom command from 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".

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