Qwen Code Core: Tools API

Ядро Qwen Code (packages/core) включает надежную систему для определения, регистрации и выполнения инструментов. Эти инструменты расширяют возможности модели, позволяя ей взаимодействовать с локальной средой, извлекать веб-контент и выполнять различные действия, выходящие за рамки простой генерации текста.

Основные концепции

Tool (tools.ts): Интерфейс и базовый класс (BaseTool), определяющий контракт для всех инструментов. Каждый инструмент должен иметь:
- name: Уникальное внутреннее имя (используется в API-вызовах к модели).
- displayName: Удобочитаемое имя.
- description: Четкое описание того, что делает инструмент. Эта информация передается модели.
- parameterSchema: JSON-схема, описывающая параметры, которые принимает инструмент. Это критично важно, чтобы модель понимала, как правильно вызвать инструмент.
- validateToolParams(): Метод для валидации входящих параметров.
- getDescription(): Метод, возвращающий человекочитаемое описание того, что инструмент сделает с конкретными параметрами перед выполнением.
- shouldConfirmExecute(): Метод, определяющий, требуется ли подтверждение пользователя перед выполнением (например, для потенциально деструктивных операций).
- execute(): Основной метод, выполняющий действие инструмента и возвращающий ToolResult.
ToolResult (tools.ts): Интерфейс, определяющий структуру результата выполнения инструмента:
- llmContent: Фактическое содержимое, которое будет включено в историю и отправлено обратно LLM для контекста. Может быть простой строкой или PartListUnion (массив объектов Part и строк) для richer content.
- returnDisplay: Удобочитаемая строка (часто Markdown) или специальный объект (например, FileDiff) для отображения в CLI.
Возврат rich content: Инструменты не ограничены простым текстом. llmContent может быть PartListUnion — массивом, который может содержать как объекты Part (для изображений, аудио и т.д.), так и строки. Это позволяет одному вызову инструмента вернуть сразу несколько элементов rich content.
Реестр инструментов (tool-registry.ts): Класс (ToolRegistry), отвечающий за:
- Регистрацию инструментов: Хранит коллекцию всех доступных встроенных инструментов (например, ReadFileTool, ShellTool).
- Обнаружение инструментов: Также может динамически находить инструменты:
  - Command-based Discovery: Если в настройках указан tools.toolDiscoveryCommand, эта команда будет выполнена. Ожидается, что она выведет JSON с описанием кастомных инструментов, которые затем регистрируются как экземпляры DiscoveredTool.
  - MCP-based Discovery: Если указан mcp.mcpServerCommand, реестр может подключиться к серверу по протоколу Model Context Protocol (MCP), получить список инструментов и зарегистрировать их как DiscoveredMCPTool.
- Предоставление схем: Отдает модели схемы FunctionDeclaration всех зарегистрированных инструментов, чтобы модель знала, какие инструменты доступны и как их использовать.
- Получение инструментов: Позволяет ядру получить конкретный инструмент по имени для выполнения.

Встроенные инструменты

Ядро поставляется с набором предопределённых инструментов, обычно расположенных в packages/core/src/tools/. Среди них:

Инструменты для работы с файловой системой:
- LSTool (ls.ts): выводит содержимое директории.
- ReadFileTool (read-file.ts): читает содержимое одного файла. Принимает параметр absolute_path, который должен быть абсолютным путем.
- WriteFileTool (write-file.ts): записывает данные в файл.
- GrepTool (grep.ts): ищет совпадения по шаблону в файлах.
- GlobTool (glob.ts): находит файлы, соответствующие glob-паттернам.
- EditTool (edit.ts): выполняет изменения внутри файлов (часто требует подтверждения).
- ReadManyFilesTool (read-many-files.ts): читает и объединяет содержимое нескольких файлов или glob-паттернов (используется командой @ в CLI).
Инструменты выполнения:
- ShellTool (shell.ts): выполняет произвольные shell-команды (требует тщательной изоляции и подтверждения от пользователя).
Веб-инструменты:
- WebFetchTool (web-fetch.ts): загружает контент по URL.
- WebSearchTool (web-search.ts): выполняет поиск в интернете.
Инструменты памяти:
- MemoryTool (memoryTool.ts): взаимодействует с памятью ИИ.

Каждый из этих инструментов расширяет класс BaseTool и реализует необходимые методы для своей конкретной функциональности.

Порядок выполнения инструмента

Запрос модели: Модель, основываясь на запросе пользователя и предоставленных схемах инструментов, решает использовать инструмент и возвращает часть FunctionCall в своем ответе, указывая имя инструмента и аргументы.
Core получает запрос: Core парсит этот FunctionCall.
Получение инструмента: Core ищет запрошенный инструмент в ToolRegistry.
Валидация параметров: Вызывается метод инструмента validateToolParams().
Подтверждение (если необходимо):
- Вызывается метод инструмента shouldConfirmExecute().
- Если он возвращает данные для подтверждения, core передает их обратно в CLI, который запрашивает подтверждение у пользователя.
- Решение пользователя (например, продолжить, отменить) отправляется обратно в core.
Выполнение: Если параметры прошли валидацию и получено подтверждение (или подтверждение не требуется), core вызывает метод инструмента execute() с переданными аргументами и AbortSignal (для возможной отмены).
Обработка результата: ToolResult из метода execute() получает core.
Ответ модели: llmContent из ToolResult упаковывается в FunctionResponse и отправляется обратно модели, чтобы она могла продолжить генерацию ответа для пользователя.
Отображение пользователю: returnDisplay из ToolResult отправляется в CLI для отображения пользователю того, что сделал инструмент.

Расширение с помощью пользовательских инструментов

Хотя прямая программная регистрация новых инструментов пользователями явно не описана как основной рабочий процесс в предоставленных файлах для типичных конечных пользователей, архитектура поддерживает расширение через:

Обнаружение на основе команд: Продвинутые пользователи или администраторы проекта могут определить tools.toolDiscoveryCommand в settings.json. Эта команда при запуске ядром должна выводить JSON массив объектов FunctionDeclaration. Затем ядро сделает их доступными как экземпляры DiscoveredTool. Соответствующая команда tools.toolCallCommand будет отвечать за фактическое выполнение этих пользовательских инструментов.
MCP сервер(ы): Для более сложных сценариев можно настроить один или несколько MCP серверов через параметр mcpServers в settings.json. Ядро сможет обнаруживать и использовать инструменты, предоставляемые этими серверами. Как упоминалось ранее, если у вас несколько MCP серверов, имена инструментов будут иметь префикс с именем сервера из вашей конфигурации (например, serverAlias__actualToolName).

Эта система инструментов обеспечивает гибкий и мощный способ расширения возможностей модели, делая Qwen Code универсальным помощником для широкого спектра задач.