S02 · Tool Use — Learn Claude Code

«Цикл вообще не изменился, я просто добавил что-то в массив ИНСТРУМЕНТЫ». - s02_tool_use.py Оригинальные слова.

Сколько мест нужно переместить, чтобы добавить инструмент?

Агент S01 знает только bash. Как бы вы изменили его, чтобы также включить read_file / write_file / edit_file?

Первой реакцией многих людей является: изменить цикл. неправильный. Не трогайте ни одной строки цикла. Нужно всего три вещи:

<ол>

Напишите функцию-обработчик Python (run_read(path, limit)).

Зарегистрируйте его в таблице сопоставления TOOL_HANDLERS ("read_file": лямбда **kw: run_read(...)).

Добавьте оператор схемы JSON в массив TOOLS (сообщая модели, как называется инструмент и какие параметры он принимает).

Когда цикл обнаружит блок tool_use, нажмите block.name, чтобы найти функцию в карте диспетчеризации, выполнить ее и вернуть выходные данные обратно в tool_result. Он следует по тому же пути, что и bash.

# Карта отправки: имя → лямбда-обработчик
ИНСТРУМЕНТ_HANDLERS = {
    "bash": lambda **kw: run_bash(kw["command"]),
    "read_file": lambda **kw: run_read(kw["path"], kw.get("limit")),
    "write_file": lambda **kw: run_write(kw["path"], kw["content"]),
    "edit_file": lambda **kw: run_edit(kw["path"], kw["old_text"], kw["new_text"]),

Посмотрите, как маршрутизируется отправка

Следующий виджет позволяет щелкнуть запрос tool_use, который может быть отправлен моделью, чтобы увидеть, как он направляется к определенной функции Python. Примечание: имя_блока определяет, какую строку использовать.

Safe_path: линия защиты, которую нельзя пропустить

Предоставьте агенту права доступа к файлу. Наиболее вероятным сбоем безопасности является уход пути: модель должна была работать в /home/user/project/, но в итоге она отправила read_file("../../etc/passwd").

В s02 есть небольшая функция, которая занимается этим:

def safe_path(p: str) -> Путь:
    path = (WORKDIR / p).resolve() # Нормализация, разрешение .. и программные ссылки
    if не path.is_relative_to(WORKDIR):
        raise ValueError(f"Путь выходит за пределы рабочей области: {p}")
    обратный путь

Ключ заключается в двух шагах: .resolve() + .is_relative_to() — анализе абсолютного пути и последующей проверке, находится ли он все еще в песочнице. Без первого может пройти foo/../../etc; без последнего даже проверка не производится.

Определить безопасность пути

Следующие 5 путей — это все параметры read_file, которые могут отправляться моделью. Какие из них будут разрешены safe_path, а какие будут отклонены? Предположим, WORKDIR = /home/user/project.

Не добавляйте в агент опасные инструменты

Добавлять инструменты легко, но помните: Каждый добавляемый вами инструмент — это новая граница возможностей модели. В s02 bash уже имеет черный список (rm -rf /, sudo, shutdown), а write_file имеет ограничения safe_path. Прежде чем добавлять инструменты в производство, задайте себе три вопроса:

<ул>

Может ли этот инструмент позволить модели совершать необратимые действия? (rm, отправить электронное письмо, git push)

Что может утечка? (переменные окружения, .ssh, файлы cookie)

Будет ли вывод ошибок рассматриваться как отзыв команды? (быстрое внедрение через выходные данные инструмента)

В лекции s07 будет добавлен «уровень разрешений», который позволит извлечь эти решения из кода и сделать их декларативными.

模型发来的 tool_use 块

TOOL_HANDLERS 映射表

执行结果 · tool_result 块

(点上面任意一条 tool_use 触发路由)

Виджет 2 · Безопасный путь · Обнаружение побега по 5 путям

Каждый путь будет обработан функцией safe_path(). Предположим, WORKDIR = /home/user/project, нажмите «Освободить» или «Отклонить» — это зависит от того, верна ли ваша интуиция относительно выхода из пути.

答对 0 / 5

Виджет 3 · Добавить инструмент · Что необходимо изменить, чтобы добавить к агенту инструмент glob?

Предположим, вы хотите добавить новый инструмент glob(pattern), чтобы позволить агенту находить файлы в пакетном режиме. Заполните пропуски: Все три должны быть изменены, ни один из них не может быть пропущен.

第 1 处 · 写一个 handler 函数

def run_glob(pattern: str) -> str:
    import glob
    return "\n".join(glob.glob(pattern))

第 2 处 · 注册到 dispatch map（选正确一行）

第 3 处 · 在 TOOLS 数组里加 schema（选正确一组）

Цикл не изменился, просто инструментов стало больше