Расширения 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-сервера, который может быть указан в его конфигурации. Важно: Инструменты, указанные в excludeTools, будут отключены во всем контексте диалога и повлияют на все последующие запросы в текущей сессии.

При запуске 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".

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