zen-code-docs/website/content/ru/core/tools-api.md

Qwen Code Core: Tools API

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

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

• Инструмент (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).
  • Обнаружение инструментов: Также может динамически находить инструменты:
    • Обнаружение через команду: Если в настройках указан toolDiscoveryCommand, эта команда будет выполнена. Ожидается, что она выведет JSON с описанием пользовательских инструментов, которые затем регистрируются как экземпляры DiscoveredTool.
    • Обнаружение через 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-команды (требует тщательной песочницы и подтверждения от пользователя).
• Web-инструменты:
  • WebFetchTool (web-fetch.ts): Получает данные по URL.
  • WebSearchTool (web-search.ts): Выполняет поиск в интернете.
• Инструменты памяти:
  • MemoryTool (memoryTool.ts): Взаимодействует с памятью ИИ.

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

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

1. Запрос модели: Модель, основываясь на запросе пользователя и предоставленных схемах инструментов, решает использовать инструмент и возвращает часть FunctionCall в своем ответе, указывая имя инструмента и аргументы.
2. Ядро получает запрос: Ядро парсит этот FunctionCall.
3. Получение инструмента: Оно ищет запрашиваемый инструмент в ToolRegistry.
4. Валидация параметров: Вызывается метод инструмента validateToolParams().
5. Подтверждение (если необходимо):
   • Вызывается метод инструмента shouldConfirmExecute().
   • Если он возвращает данные для подтверждения, ядро передает их обратно в CLI, который запрашивает решение у пользователя.
   • Решение пользователя (например, продолжить, отменить) отправляется обратно в ядро.
6. Выполнение: Если параметры прошли валидацию и получено подтверждение (или подтверждение не требуется), ядро вызывает метод инструмента execute() с переданными аргументами и AbortSignal (для возможной отмены).
7. Обработка результата: ToolResult из метода execute() получает ядро.
8. Ответ модели: llmContent из ToolResult упаковывается как FunctionResponse и отправляется обратно модели, чтобы она могла продолжить генерацию ответа для пользователя.
9. Отображение пользователю: returnDisplay из ToolResult отправляется в CLI, чтобы показать пользователю, что сделал инструмент.

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

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

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

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