Перейти к содержимому
Chimera
Загрузка
Русский

← Навыки

chimera-ground-it-in-the-source

Берите сигнатуру из установленной версии, а не из памяти: правдоподобный API неотличим от настоящего, пока не будет запущен.

ПаттернПроисхождение: cleanСостояние: activev0.1.0 · Apache-2.0

Присвоено человеком, который прочитал карточку, а не заявлено файлом о самом себе. Карточка, которую агент выводит во время запуска, поглотившего недоверенное содержимое, рождается заражённой и удерживается на разбор, прежде чем её вообще извлекут.

Когда это вспоминается

  • вызываю чужую библиотеку
  • как называется параметр
  • API изменился между версиями
  • пишу под фреймворк по памяти
  • AttributeError на методе, который должен быть

Ценность обычно лежит в разделах «Избегать» и «Проверить». «Делать» — это раздел, который пишут все.

Текст карточки выше — перевод. Английский оригинал — это то, что импортирует командная строка, что читает агент во время работы и что подтверждает хеш ниже.

Повод

Вы собираетесь написать вызов в чужую библиотеку, фреймворк или CLI: имя метода, именованный аргумент, ключ конфигурации, форму возвращаемого значения, флаг. Особенно остро это, когда память уверена, потому что уверенность производится одинаково независимо от того, существует API или нет.

Это не относится к собственным встроенным средствам языка, которыми вы пользуетесь постоянно, и это не указание лезть в документацию перед тем, как написать dict.get. Граница проходит по тому, будет ли ошибка немедленно поймана следующим же запуском.

Делать

  1. Узнайте версию, которая реально установлена, а не ту, о которой вы что-то читали: uv pip show <pkg> или python -c "import pkg; print(pkg.__version__)".
  2. Прочтите установленное. python -c "import inspect, pkg; print(inspect.signature(pkg.fn))", либо откройте файл в site-packages, либо запустите --help у бинарника, который лежит в PATH. Это и есть источник истины, потому что именно этот код будет исполняться.
  3. Когда вы опираетесь на пост в блоге, README в вебе или собственную память, относитесь к этому как к гипотезе и подтверждайте по шагу 2. Сайты документации описывают последний релиз; ваш lockfile может быть закреплён не на нём.
  4. Выполните вызов один раз в черновом фрагменте и напечатайте фактическое возвращаемое значение, прежде чем писать код, индексирующийся в ваше представление о нём. Вложенные формы — ["choices"][0]["message"] — это место, где память наименее надёжна и где она реже всего падает громко.
  5. Оставьте свидетельство рядом с кодом: версию и ту сигнатуру или вывод --help, который вы прочли. Комментария или текста PR достаточно, и это скажет следующему читателю, против чего код был написан.

Избегать

Писать текст, который выглядит как API. Сбой здесь не опечатка — опечатка падает сразу и правится за секунды. Это имя, которое соблюдает все до единого соглашения об именовании этой библиотеки и при этом не существует.

Настоящий пример из этого репозитория, и суть именно в форме: догадка была не абсурдной, она была разумной:


from chimera.core.checkpoint import WorkspaceGuard, diff_snapshots   # ImportError

# Where it actually is. One grep, before writing the line, would have found it.
from chimera.core.checkpoint import WorkspaceGuard
from chimera.evolution.diff_gate import diff_snapshots

Ценой было не исключение — ImportError громок и дёшев. Цена в том, что такая же уверенная догадка о поведении падает молча, и вы узнаёте об этом, лишь когда выданное ею число оказывается неверным.

Также избегайте заземления не на той версии. Чтение текущей документации для пакета, закреплённого двумя мажорами раньше, даёт код, корректный относительно библиотеки, которую вы не запускаете, — а сообщение об ошибке, когда оно придёт, укажет на ваш вызов, а не на расхождение.

И не принимайте прошедший тайпчекер за заземление, если пакет не поставляет стабы. Против нетипизированной зависимости Any проглотит любой выдуманный вами атрибут; проверка отчитывается об успехе, потому что проверять ей было нечего.

Проверить

По каждому неочевидному вызову в диффе: можете ли вы указать, где вы его видели, — напечатанная сигнатура, строка в site-packages, запущенный --help? Если честный ответ хотя бы по одному — «выглядело правильно», этот вызов не проверен, и сказать об этом стоит одного предложения.

Более сильная проверка исполняема: запустите фрагмент из шага 4 против установленной версии и вставьте его вывод. Разрешившийся импорт и вызов, вернувший ожидаемую форму, — два разных факта; полагаетесь вы на второй.

Риск

Применённое ко всему подряд, это превращает рутинный код в исследование и замедляет работу без выгоды. Тратьте это на незнакомый вызов, на чувствительный к версии и на вложенную форму ответа — а не на сотню строк вокруг них.

Более тонкий риск — заземляться слишком буквально. Установленный исходник с удовольствием покажет вам _internal_helper, который существует, сегодня работает и никем не обещан. Исходник говорит, что там есть; документация говорит, что поддерживается. Когда они расходятся, предпочитайте документированную поверхность, а если сознательно выходите за неё — скажите об этом в комментарии, а не оставляйте следующего читателя думать, что так было санкционировано.

Как применить

Карточка — это данные. Склонируйте репозиторий и импортируйте её по пути: всё, что приходит по сети, считается заражённым и удерживается до одобрения — это и есть желаемое поведение, и поэтому здесь нет установщика в одну строку.

git clone https://github.com/brcampidelli/chimera-agent.git
chimera skills-import chimera-agent/skills/chimera-ground-it-in-the-source/SKILL.md

Целостность

SHA-256 файла в опубликованном виде. Импортёр может проверить, что полученное совпадает с показанным на этой странице.

9a51bb6b117c736dba1de11a166efed09ad200134e153ad553f4701302025398

Читать карточку в репозитории →