Как добавить инструмент помощнику

Каждый файл, который затрагивает новый инструмент, по порядку. Как ход пользуется инструментами: Как устроен помощник.

#Сначала решите

• Он читает или меняет? Инструмент чтения возвращает данные и ничего не меняет. Инструмент, который меняет граф, это инструмент сборки, и он обязан идти через движок команд. Инструмент, который предлагает, это инструмент предложений, он пишет черновик.
• Нужна ли ему сеть? Тогда он обязан слушаться «Настройки ▸ Помощник» (поиск, чтение страниц) и никогда не обращаться к этому компьютеру, локальной сети, ComfyUI или MCP-серверу. См. src/main/agent/web.ts.
• Обращается ли он к ComfyUI? Только через проверку «только чтение»; новому вызову MCP нужна своя схема в src/main/mcp/readOnly.ts. Чтение ComfyUI

#Инструмент чтения, знаний или предложений

1. Имя: добавьте его в AGENT_READ_TOOLS, AGENT_KNOWLEDGE_TOOLS или AGENT_PROPOSAL_TOOLS в src/shared/contracts/agentTools.ts.
2. Описание: текст и схема JSON в MAIN_TOOL_SPECS, src/main/agent/toolSpecs.ts. Пишите описание для модели: что возвращает, когда вызывать, какие пределы (страницы, размеры).
3. Код: запись define(name, zodSchema, run) в src/main/agent/tools.ts. Разбирайте аргументы через zod; возвращайте простые данные; скрывайте всё, где может оказаться ключ (src/shared/agent/redact.ts).
4. Запрос: если модели нужно знать, когда его предпочесть, одна строка в src/main/agent/prompt.ts; если это один из немногих инструментов, которые остаются при маленьком окне контекста, добавьте его в короткие списки в src/main/agent/turn.ts.
5. Чат: его подпись в каталоге текстов на обоих языках: agent.tools.<имя> (карточка инструмента) и chat.quiet.<имя> (тихая строка чтений) в src/shared/i18n/catalog.ts.
6. Тесты: tests/unit/agent/tools.test.ts (аргументы, результат, отказ на плохой аргумент).

#Инструмент сборки

1. Имя: AGENT_BUILD_TOOLS (и BUILD_STEP_TOOLS, если это видимый шаг) в src/shared/contracts/agentTools.ts.
2. Описание: src/shared/commands/toolSpecs.ts (общее с renderer, который рисует шаг).
3. Команда: если ни одно содержимое команды не подходит, добавьте новое в src/shared/commands/types.ts и примените его в src/main/commands/commit.ts / graphOps.ts (Движок команд и история).
4. Код: ветка в src/main/agent/buildTools.ts, которая превращает вызов в commitCommand с actor: 'ai' и id хода. Конфликт или отказ возвращается модели как неудачный шаг, а не исключение.
5. Шаг в чате: src/renderer/components/chat/buildSteps.ts и тексты chat.step.<имя> и chat.stepFailed.<имя> на обоих языках.
6. Тесты: tests/unit/agent/ и tests/integration/chatToGraph.test.ts для всего пути с заготовленной моделью.

#Перед запросом на слияние

• npm test, npm run type-check.
• xvfb-run -a npx playwright test tests/e2e/strict-chat-to-graph.test.ts --trace off для инструмента сборки.
• Если человек видит результат инструмента, скажите об этом на странице вики о помощнике, к которой он относится.

#См. также

• Для разработчиков
• Как устроен помощник
• IPC между окном и main