Skip to Content
Основные ДеталиAPI Инструментов

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 универсальным помощником для широкого спектра задач.

Last updated on
Обзор ЯдраПроцессор Импорта Памяти