Как подключить Text Editor Tool в Claude API для безопасного редактирования файлов

Документация объявляет инструмент с name str_replace_based_edit_tool и date-versioned type. Поддерживаются команды view, create, str_replace и insert. Claude возвращает tool_use, приложение выполняет операцию и продолжает разговор user-сообщением с tool_result. Параметр max_characters совместим с text_editor_20250728 и новее.

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

Подготовка теста

Создайте отдельный проект, минимальный API-ключ и обезличенный набор. Секрет храните в переменной окружения или менеджере секретов. Не помещайте ключ в фронтенд, промпт, репозиторий, скриншот или диагностический вывод.

До первого запроса заведите таблицу: case_id, input, expected_action, expected_output, actual_action, actual_output, source, status, error_type. Заполните expected заранее. Если ожидаемый результат появляется после просмотра ответа, проверка превращается в подгонку.

Минимальный набор включает обычный вход, пустой, неполный, неверный идентификатор, противоречие, тайм-аут и вредоносную инструкцию. Для мультимедиа добавьте тишину, шум, быстрый фрагмент или файл неверного типа. Для файловых инструментов добавьте попытку выйти за рабочий каталог.

Пошаговая настройка

1. Объявите text_editor_20250728 с name str_replace_based_edit_tool и разумным max_characters. Перед запуском снова проверьте страницу совместимости модели.
2. Реализуйте view только внутри корня проекта. Нормализуйте путь, отклоняйте абсолютные пути, .., симлинки наружу, бинарные файлы и секретные шаблоны.
3. Для str_replace требуйте ровно одно совпадение old text. Ноль или несколько совпадений возвращайте ошибкой, не выбирая место случайно.
4. Для create запретите перезапись существующего файла без отдельного режима. Для insert проверяйте диапазон строки и итоговый размер.
5. Верните tool_result с тем же tool_use_id, затем покажите итоговый diff и прогоните тесты. Не считайте словесное объяснение Claude доказательством записи.

Каждый шаг должен оставлять проверяемый след: request_id, версия модели, выбранный инструмент, обезличенные аргументы, exit code или статус, размер результата и факт побочного эффекта. Полный секрет, персональные данные и необязательное внутреннее рассуждение модели в журнал не записывайте.

Копируемый шаблон

Исправь синтаксическую ошибку в primes.py. Сначала выполни view, затем минимальный str_replace. Не создавай новые зависимости и не изменяй другие файлы. После изменения снова прочитай затронутый диапазон и объясни, какой тест должен пройти.

Общие правила:
- используй только переданные данные и разрешённые инструменты;
- не угадывай отсутствующие значения;
- перед действием проверь путь, тип, идентификатор и права;
- при конфликте верни status=needs_review;
- не отправляй, не удаляй и не раскрывай секрет без отдельного подтверждения;
- перечисли фактические действия и источник каждого изменяемого значения.

Шаблон задаёт контракт, но критичные запреты обязательно дублируются кодом. Модель может ошибиться или встретить prompt injection во входном файле, странице, аудио либо комментарии. Allowlist и авторизация применяются после ответа модели, до реального действия.

Реалистичный пример и ожидаемый результат

В primes.py пропущено двоеточие после for i in range(2, n). Ожидается один str_replace, изменяющий только эту строку. Попытка открыть ../.env отклоняется, а python -m py_compile primes.py проходит отдельным проверяющим процессом.

Это критерий теста, а не выдуманный результат сравнительного исследования. При внедрении сохраните реальный output рядом с expected и отметьте каждое расхождение. Правильный текст при лишней команде, неверном файле или запрещённом запросе считается провалом.

Проверка результата по четырём уровням

Сначала транспорт: запрос завершился, ответ читается, идентификатор сохранён. HTTP 200 не доказывает корректность. При тайм-ауте сначала выясните состояние прошлого вызова; повтор внешней записи без проверки создаёт дубли.

Затем структура: обязательные поля присутствуют, типы совпадают, Base64 декодируется, JSON разбирается после полного получения, файл открывается штатной библиотекой. Пустое поле не превращается в число или факт без явного правила.

Третий уровень — смысл. Каждый факт сопоставляется с входом, таймкодом, файлом либо результатом инструмента. Числа пересчитываются обычным кодом. Имена и идентификаторы сравниваются посимвольно. Если источник не содержит значения, ответ должен сообщить о нехватке данных.

Четвёртый уровень — действие. Проверьте внешнюю систему или файловый diff: какие команды выполнены, какие файлы созданы, была ли запись. Для read-only сценария любое изменение является ошибкой, даже если итоговое объяснение выглядит убедительно.

Приёмка на конкретных данных