Система инструментов

Система инструментов TinyElf управляется через ToolRegistry, отвечающий за регистрацию и выполнение инструментов. Компонент TinyElfToolRegistryBuilder отвечает за сборку полного набора инструментов при запуске сессии. Каждый инструмент реализует интерфейс ITool.

Процесс регистрации инструментов

graph TB
    Builder["TinyElfToolRegistryBuilder<br/>buildToolRegistry()"] --> Reg["ToolRegistry"]

    Builder -->|"1. FileSystem"| FS["createFileSystemTools()<br/>Read, Write, Edit, ListDir, Glob, Grep"]
    Builder -->|"2. Shell"| Shell["ShellTool<br/>Bash"]
    Builder -->|"3. Web Search"| WS["setupWebSearch()<br/>WebSearch / NativeSearch"]
    Builder -->|"4. Web Fetch"| WF["createWebFetchTool()<br/>WebFetch + summarizer"]
    Builder -->|"5. Skills"| SK["SkillsTool + ReadSkillTool<br/>list_skills, read_skill"]
    Builder -->|"6. SkillHub"| SH["SkillHubSearchTool + InstallTool<br/>skillhub_search, skillhub_install"]
    Builder -->|"7. Sub-Agent"| SA["SpawnTool<br/>spawn_agent"]
    Builder -->|"8. Sub-Agent Query"| SAQ["SubagentListTool + StatusTool"]
    Builder -->|"9. Slash Command"| CMD["SlashCommandTool<br/>slash_command"]
    Builder -->|"10. MCP"| MCP["loadMcpTools() + loadDirectMcpTools()<br/>mcp__*"]
    Builder -->|"11. Session"| SS["SessionsSpawn/List/Send/History"]
    Builder -->|"12. Control"| Ctrl["NotifyTool + SessionsYieldTool"]

    FS --> Reg
    Shell --> Reg
    WS --> Reg
    WF --> Reg
    SK --> Reg
    SH --> Reg
    SA --> Reg
    SAQ --> Reg
    CMD --> Reg
    MCP --> Reg
    SS --> Reg
    Ctrl --> Reg

Интерфейс ITool

interface ITool {
  readonly name: string;            // уникальное имя инструмента (используется при function_calling)
  readonly description: string;     // описание, читаемое LLM
  readonly parameters: JsonSchema;  // определение параметров в формате JSON Schema
  execute(params: Record<string, unknown>): Promise<string>;
}

ToolRegistry

class ToolRegistry {
  register(tool: ITool): void;
  registerAll(tools: ITool[]): void;
  unregister(name: string): boolean;
  get(name: string): ITool | undefined;
  has(name: string): boolean;
  getAll(): ITool[];
  getNames(): string[];
  getDefinitions(): ToolDefinition[];    // формат OpenAI function_calling
  createFiltered(allowedNames: string[]): ToolRegistry;
  execute(toolCallId, toolName, params): Promise<ToolCallResult>;
}

Процесс выполнения

Поиск инструмента → возврат ошибки, если не найден (с перечнем доступных инструментов)
Преобразование типов параметров → обработка распространённых ошибок типов LLM (string → number и т.д.)
Проверка обязательных параметров → возврат ошибки при отсутствии
Вызов tool.execute(params)
Усечение вывода → обрезка при превышении maxChars (по умолчанию 50 КБ) с добавлением метки (truncated)
Добавление подсказки к выводу ошибки → [Analyze the error above and try a different approach.]

Фильтрация инструментов

createFiltered() создаёт новый экземпляр ToolRegistry, содержащий только разрешённые инструменты. Используется для:

Режима plan, ограниченного инструментами только для чтения
Поля allowedTools в конфигурации агента
Метаданных allowed-tools у Slash-команд

Полная таблица инструментов

Инструменты файловой системы

Инструмент	Класс	Чувствительность	Параметры	Описание
`Read`	`ReadFileTool`	Безопасный	`path`, `offset?`, `limit?`	Чтение содержимого файла, поддерживает частичное чтение
`Write`	`WriteFileTool`	Чувствительный	`path`, `content`	Запись файла (создание или перезапись)
`Edit`	`EditFileTool`	Чувствительный	`path`, `old_string`, `new_string`, `replace_all?`	Точная замена строки
`ListDir`	`ListDirTool`	Безопасный	`path`	Просмотр содержимого директории
`Glob`	`GlobTool`	Безопасный	`pattern`, `path?`	Поиск файлов по шаблону имени
`Grep`	`GrepTool`	Безопасный	`pattern`, `path?`, `include?`	Поиск по содержимому файлов

Особенности инструментов файловой системы:

Песочница путей: все пути разрешаются относительно корня рабочего пространства
Параметр restrictToWorkspace управляет доступом за пределами рабочего пространства
Read автоматически усекает большие файлы (>128 КБ); для файлов >10 МБ требуется указать offset/limit

Инструмент командной оболочки

Инструмент	Класс	Чувствительность	Параметры	Описание
`Bash`	`ShellTool`	Чувствительный	`command`	Выполнение команды оболочки

Функции безопасности инструмента Shell:

Чёрный список команд (критически запрещённые шаблоны): rm -rf /, format, mkfs, diskpart и др.
Предупреждения о высокорисковых командах: sudo, curl | sh, изменение прав доступа
Обнаружение путей за пределами рабочего пространства
Ограничение вывода: 100 КБ
Тайм-аут: по умолчанию 2 минуты, настраивается через execTimeout

Веб-инструменты

Инструмент	Класс	Чувствительность	Параметры	Описание
`WebSearch`	`WebSearchServiceTool`	Безопасный	`query`, `count?`	Веб-поиск
`WebFetch`	`WebFetchTool`	Безопасный	`url`, `prompt?`, `raw?`	Получение веб-содержимого

Особенности WebFetch:

Используется Readability для извлечения текста статьи
Преобразование HTML → Markdown (Turndown)
Содержимое объёмом более 4 КБ автоматически суммируется с помощью фоновой модели
Тайм-аут 30 секунд, максимальный ответ 5 МБ

Трёхуровневый резерв веб-поиска:

Нативный поиск (встроенный в Anthropic/OpenAI/Gemini/xAI)
WebSearchService (Tavily/Jina/Searxng)
Недоступен

Инструменты суб-агентов

Инструмент	Класс	Чувствительность	Параметры	Описание
`spawn_agent`	`SpawnTool`	Чувствительный	`prompt`, `agent?`, `model?`, `background?`, `maxIterations?`, `permissionMode?`, `tools?`	Запуск суб-агента
`subagent_list`	`SubagentListTool`	Безопасный	Нет	Список активных суб-агентов
`subagent_status`	`SubagentStatusTool`	Безопасный	`runId`	Запрос статуса суб-агента

Инструменты сессий

Инструмент	Класс	Чувствительность	Параметры	Описание
`SessionsSpawn`	`SessionsSpawnTool`	Чувствительный	`prompt`, `agentId?`, `title?`	Создание новой сессии
`SessionsList`	`SessionsListTool`	Безопасный	`limit?`, `offset?`	Список сессий
`SessionsSend`	`SessionsSendTool`	Чувствительный	`sessionId`, `message`	Отправка сообщения в сессию
`SessionsHistory`	`SessionsHistoryTool`	Безопасный	`sessionId`, `limit?`	Просмотр истории сессии
`SessionsYield`	`SessionsYieldTool`	Безопасный	`message`	Завершение цикла агента и возврат сообщения

Инструменты Skills

Инструмент	Класс	Чувствительность	Параметры	Описание
`list_skills`	`SkillsTool`	Безопасный	Нет	Список всех доступных навыков
`read_skill`	`ReadSkillTool`	Безопасный	`name`	Чтение содержимого навыка
`skillhub_search`	`SkillHubSearchTool`	Безопасный	`query`	Поиск навыков сообщества
`skillhub_install`	`SkillHubInstallTool`	Безопасный	`skillId`	Установка навыка из сообщества

MCP-инструменты

Инструмент	Класс	Чувствительность	Параметры	Описание
`mcp__<server>__<tool>`	Генерируется динамически	Чувствительный	Определяются MCP-сервером	Внешние MCP-инструменты

MCP-инструменты загружаются тремя способами:

User MCP (mcpServerIds) — подключение пользовательских stdio/http/sse серверов из Настройки → MCP через McpService
Built-in MCP (автосборка через McpProviderRegistry) — все встроенные MCP-обработчики выполняются в процессе, обёрнуты SDK через createSdkMcpServer, TinyElf регистрирует их как ITool, CLI обращается через центральный HTTP-мост BuiltinMcpHttpServer. Видимые MCP каждого агента определяются методом isEligible(ctx) провайдера (поле builtinMcpServers в конфигурации агента удалено в cleanup-legacy-mcp (2026-05-19))
Direct MCP (directMcpServers) — предварительно разобранные stdio MCP, объявленные в конфигурации агента (пользовательские сценарии, например вызов локальных Python-инструментов)

Управляющие инструменты

Инструмент	Класс	Чувствительность	Параметры	Описание
`Notify`	`NotifyTool`	Безопасный	`title`, `body?`	Отправка десктопного уведомления
`slash_command`	`SlashCommandTool`	Безопасный	`command`, `args?`	Выполнение Slash-команды

Классификация инструментов по чувствительности

private static readonly SAFE_TOOLS = new Set([
  'Read', 'ListDir', 'Glob', 'Grep',
  'WebSearch', 'WebFetch',
  'list_skills', 'read_skill',
  'Notify', 'SessionsYield', 'SessionsHistory',
]);

Правила классификации:

Присутствует в SAFE_TOOLS → никогда не требует подтверждения
В режиме acceptEdits инструменты Write и Edit тоже не требуют подтверждения
Все остальные инструменты (включая MCP) → требуют подтверждения

Наследование инструментов

Суб-агенты могут наследовать часть инструментов от родительского агента:

const inheritableToolNames = new Set([
  'list_skills', 'read_skill', 'slash_command'
]);
// + все MCP-инструменты, имя которых начинается с mcp__

Ключевые файлы

Файл	Путь	Описание
Интерфейс ITool	`tinyelf/tools/ToolInterface.ts`	Базовый интерфейс инструмента
ToolRegistry	`tinyelf/tools/ToolRegistry.ts`	Реестр инструментов
ToolRegistryBuilder	`tinyelf/TinyElfToolRegistryBuilder.ts`	Строитель инструментов
FileSystemTools	`tinyelf/tools/FileSystemTools.ts`	Инструменты файловой системы
ShellTool	`tinyelf/tools/ShellTool.ts`	Инструмент командной оболочки
WebTools	`tinyelf/tools/WebTools.ts`	WebFetch
WebSearchServiceTool	`tinyelf/tools/WebSearchServiceTool.ts`	WebSearch
SpawnTool	`tinyelf/tools/SpawnTool.ts`	Инструмент суб-агента
SessionTools	`tinyelf/tools/SessionTools.ts`	Инструменты управления сессиями
SkillsTool	`tinyelf/tools/SkillsTool.ts`	Инструмент навыков
SkillHubTools	`tinyelf/tools/SkillHubTools.ts`	Инструменты SkillHub
McpToolAdapter	`tinyelf/tools/McpToolAdapter.ts`	Адаптер MCP-инструментов
NotifyTool	`tinyelf/tools/NotifyTool.ts`	Инструмент уведомлений
YieldTool	`tinyelf/tools/YieldTool.ts`	Инструмент завершения цикла
SubagentTools	`tinyelf/tools/SubagentTools.ts`	Инструменты запроса суб-агентов
SlashCommandTool	`tinyelf/tools/SlashCommandTool.ts`	Slash-команды

Все пути указаны относительно packages/desktop/app/main/services/agent-core/engine/.

Точки расширения

Новый инструмент: реализовать интерфейс ITool → зарегистрировать в TinyElfToolRegistryBuilder
Изменить чувствительность: добавить/удалить из набора TinyElfAgentLoop.SAFE_TOOLS
Пользовательское наследование инструментов: изменить набор inheritableToolNames
Загрузка MCP-инструментов: адаптировать новый транспорт MCP через McpToolAdapter

Связанные модули

Модуль	Путь	Связь
TinyElfAgentLoop	`tinyelf/TinyElfAgentLoop.ts`	Вызывает выполнение инструментов
ExecutionFirewall	`platform/security/ExecutionFirewall.ts`	Проверка путей инструментов файловой системы
McpService	`capabilities/tools/mcp-users/McpService.ts`	Источник MCP-инструментов
SkillsLoader	`tinyelf/skills/SkillsLoader.ts`	Зависимость инструмента навыков
SubagentManager	`tinyelf/tools/SpawnTool.ts`	Зависимость spawn_agent

Процесс регистрации инструментов​

Интерфейс ITool​

ToolRegistry​

Процесс выполнения​

Фильтрация инструментов​

Полная таблица инструментов​

Инструменты файловой системы​

Инструмент командной оболочки​

Веб-инструменты​

Инструменты суб-агентов​

Инструменты сессий​

Инструменты Skills​

MCP-инструменты​

Управляющие инструменты​

Классификация инструментов по чувствительности​

Наследование инструментов​

Ключевые файлы​

Точки расширения​

Связанные модули​