Память проверенных обходов и рабочих приёмов для OpenCode,
близкая к телу: агент узнаёт знакомую задачу или ловушку и использует успешный
опыт до очередной серии долгих итераций.
Публичная поставка — npm-пакет opencode-gotcha. Репозиторий разработки в SourceCraft закрытый.
Первый MVP работает в OpenCode V1 и V2. Он хранит зацепки в Markdown, предоставляет
пять инструментов, автоматически добавляет ранжированный индекс в контекст
и восстанавливает его после компакции и перезапуска. Проверена работа
в OpenCode 1.19.3 и 2.2.6, включая установку из tarball в чистом окружении.
Собственных runtime-зависимостей нет; V2-вход не требует SDK,
для V1 используется опциональная peer-зависимость @opencode-ai/plugin.
Фоновое извлечение — следующий этап. Внутренняя документация разработки,
проектная память, тесты и CI-конфигурация в npm-пакет не входят.
Быстрый старт
Для OpenCode V2 подключить npm-пакет в проектном opencode.jsonc:
Конфигурация V2 обновляется автоматически; принудительное обновление — /reload.
Индекс появится в контексте автоматически. При первом
сохранении создаётся .opencode/gotcha/; включайте его в обычный PR с кодом.
Для проверки пути можно попросить агента вызвать gotcha_index.
Также поддерживаются checkout и собранный tarball для участников закрытого репозитория.
V1-вход index.js сохранён; ему дополнительно нужен peer @opencode-ai/plugin.
V2 не импортирует SDK V1 и загружает npm-пакет через экспорт ./server.
Что такое зацепка
Зацепка — короткое прикладное знание: при таких условиях возникает такая
задача или проблема; вот проверенный приём и успешный пример решения.
Сохраняем проверенные обходы проблем и приёмы выполнения повторяющихся задач,
которые сокращают нетривиальный поиск или долгие итерации. Возникновение ошибки
необязательно: достаточно неочевидного рабочего способа, который пригодится
снова. Ценность зацепки — в экономии будущих итераций и предотвращении тупиков.
У записи должны быть:
узнаваемая задача или симптом: цель работы, сообщение об ошибке, поведение инструмента;
условия применимости: инструмент, окружение, версия или особенности проекта;
конкретный рабочий приём: действия, команда или запрос;
воспроизводимый успешный пример: исходные данные, действие и ожидаемый результат;
основание: наблюдаемый результат проверки и, когда доступен, источник.
Неработающий путь добавляется, если он действительно был и его легко повторить.
Для повторяющейся задачи важно показать, какой поиск или какие действия экономит
приём. Частота задачи сама по себе недостаточна: запись должна сохранять полезный
неочевидный опыт.
Что сохраняем
Подходит
Что делает запись полезной
Обход повторяющегося сбоя инструмента
Узнаваемый симптом, условия и проверенный способ продолжить
Неочевидная особенность команды или API
Работающий пример с условиями и проверкой результата
Короткий путь после долгого поиска решения
Объяснение, когда он применим и какие итерации экономит
Приём выполнения повторяющейся задачи
Воспроизводимый успешный пример: входные данные, действия и ожидаемый результат
Примеры повторяющихся задач: запуск нужной проверки без полной пересборки,
подбор рабочей формы сложного API-запроса или короткий сценарий проверки плагина.
Для каждой такой записи нужен проверенный пример и объяснение сокращённого пути.
Живой статус задачи остаётся в исходной системе. Разбор исправленного бага —
в задаче или PR; повторно применимый вывод из него может стать зацепкой.
Общие предпочтения пользователя, обычная справка и очевидные инструкции
относятся к соответствующим правилам и документации.
Если актуальный ответ уже есть в коде, документации, AGENTS.md или схеме
инструмента, зацепка ссылается на него и объясняет неочевидную ловушку или
сокращённый путь. Предположение о причине обозначается в тексте; рабочий приём
подтверждается проверкой. Условия и результат важнее уверенной формулировки.
Как агент пользуется памятью
Получает компактный индекс зацепок в контексте работы.
Перед повторяющейся задачей, повторной попыткой после знакомой ошибки или
долгим перебором подходов проверяет индекс на подходящую задачу, симптомы и условия.
Читает полную релевантную запись через gotcha_read, сверяет её применимость
и проверяет результат выбранного приёма.
После найденного и проверенного приёма или обхода ищет существующую зацепку:
уточняет её или сохраняет новую через gotcha_save.
При пересмотре обновляет изменившиеся условия и удаляет потерявшие смысл записи.
Сохранённая зацепка — контекст прошлого опыта. Актуальные условия, код и
документация определяют, можно ли применить её сейчас.
Где живут зацепки
Основной режим — проектная память, которая хранится и коммитится вместе с кодом:
Одна зацепка — один Markdown-файл со стабильным ключом. Ссылки в MEMORY.md
относительны каталогу хранилища. Плагин сообщает выбранный каталог агенту,
чтобы подробные записи находились независимо от рабочей директории.
Проектные записи и индекс включаются в обычный PR. Так участники получают
зацепки после checkout, а изменение приёма можно обсудить вместе с кодом.
Сам плагин обновляет файлы; Git-коммиты и публикация выполняются в рамках
обычного процесса работы с репозиторием.
Выбор хранилища
Место подключения плагина задаёт область по умолчанию. Существующая проектная
память имеет приоритет:
Ситуация
Выбранное хранилище
В проектной области OpenCode уже есть .opencode/gotcha/
Проектное, в том числе при глобальном подключении плагина
Плагин подключён локально, проектного хранилища ещё нет
Проектное; создаётся при первом сохранении
Плагин подключён глобально, проектного хранилища нет
Обычно глобальный каталог — ~/.config/opencode/gotcha/. Проектные записи
физически находятся в проекте; глобальная память — самостоятельный карман
общих зацепок.
Проектный путь определяется относительно проектной конфигурации или локального
каталога плагинов, который обнаружил OpenCode. Запуск из подкаталога выбирает
то же хранилище этой проектной области. Вложенная проектная конфигурация задаёт
собственную область; worktree с собственной копией конфигурации и памяти
использует её.
Для каждой операции выбирается одно хранилище, общее для инструментов и инъекции.
Путь к npm-модулю в кэше OpenCode сам по себе не определяет область подключения.
Ранжированный индекс
MEMORY.md — читаемый индекс и единственный источник счётчиков и дат:
# MEMORY| Использований | Запись | Описание | Создана | Обновлена | Последнее использование || ---: | --- | --- | --- | --- | --- || 3 | [bash-grep-sigpipe](bash-grep-sigpipe.md) | Exit 141 при grep -q и включённом pipefail | 2026-10-28 | 2026-10-28 | 2026-10-28 |
Создание зацепки = 1 использование.
Каждый успешный gotcha_read добавляет 1 и обновляет дату использования.
Повторное сохранение обновляет содержимое, описание и дату изменения,
сохраняя накопленный счётчик, даты создания и последнего использования.
Порядок строк — по убыванию счётчика, при равенстве — по ключу.
Показ индекса, пересмотр, инъекция и компакция счётчики не увеличивают.
Метрики находятся в таблице. Изменения индекса записываются атомарно;
работа нескольких процессов с одним хранилищем требует блокировки записи.
«Использование» здесь означает создание или явное чтение полной записи.
Это показатель востребованности, а не доказательство успешного применения
приёма. Популярность определяет порядок просмотра; задача, симптомы и условия —
релевантность конкретной задаче.
В контекст попадает индекс, подробности читаются по необходимости. При росте
индекса сначала сокращаются описания, затем остаются ключи в ранжированном
порядке. Целевой размер индекса — 20 000 байт; при очень большом числе записей
список ключей может превышать этот размер, поскольку ключи не отбрасываются.
Сжатие выполняется для запроса без переписывания пользовательских файлов.
Формат записи
# Короткое название зацепки## Когда пригодитсяПовторяющаяся задача или симптом; условия, инструмент, окружение и версия.## Что не помогает (необязательно)Неудачный подход, если он был и его легко повторить.## Рабочий приёмКонкретные действия и объяснение, какой поиск или какие итерации они сокращают.## Успешный примерИсходные данные, команда или запрос и ожидаемый результат.## Как провереноНаблюдаемый результат, условия проверки и доступный источник.
Пример: grep находит строку, но конвейер завершается с кодом 141
Ниже — пример готовой зацепки. Команды проверены для Bash с pipefail:
получены коды 141 для раннего завершения, 0 при совпадении после обхода
и 1 при отсутствии совпадения.
# Раннее завершение grep -q вызывает SIGPIPE у производителя## Когда пригодитсяВ Bash включён pipefail. Достаточно большой конечный поток передан в grep -q;совпадение встречается в начале. grep завершается с кодом 0, но производительполучает SIGPIPE, и весь конвейер возвращает 141.## Что не помогаетПовторять тот же конвейер: проблема связана с ранним закрытием канала,а не с отсутствием искомой строки.## Рабочий приёмДля конечного потока дать grep дочитать вход, перенаправив найденные строкив /dev/null. Обход применим, когда допустимо дождаться завершения производителя.Для бесконечного потока нужен другой способ остановки производителя.## Успешный примерСледующий конечный поток содержит строку 1. Команда возвращает 0:```bashset -o pipefailseq 100000 | grep '^1$' > /dev/null```## Как провереноВ Bash с pipefail команда seq 100000 | grep -q '^1$' возвращает 141.Вариант без -q с перенаправлением в /dev/null возвращает 0.
Пример: повторно проверять счётчики без запуска OpenCode
Это пример приёма для повторяющейся задачи без предшествующей ошибки.
Он относится к файловому ядру в этом репозитории и опирается на
самодостаточный тест в test/store.test.mjs.
# Проверять счётчики и сортировку отдельным тестом хранилища## Когда пригодитсяВ этом репозитории нужно повторно проверить изменение счётчиков и порядокиндекса. В test/store.test.mjs есть самодостаточный тест, который создаётизолированное хранилище и вызывает методы GotchaStore напрямую.## Рабочий приёмИз корня репозитория запустить только этот сценарий через фильтр node:test.Это сокращает ручную проверку с запуском OpenCode и последовательностью вызововинструментов. Сценарий проверяет файловые операции, а интеграция с хостомпроверяется отдельно.## Успешный примерНужны установленные зависимости проекта. Команда:```bashnode --test --test-name-pattern='^индекс ранжируется по использованию, при равенстве — по ключу$' test/store.test.mjs```Ожидаемый результат: один прошедший тест и код завершения 0. Сценарий создаёттри записи со счётчиком 1, читает beta один раз и gamma дважды, затем уточняетgamma. Итоговый порядок: gamma — 3, beta — 2, alpha — 1.## Как провереноКоманда выполнена: один тест прошёл, код завершения 0. Проверяются такжесохранение счётчика при обновлении и порядок после создания нового экземпляра ядра.
Инструменты первого MVP
Эти инструменты предоставляет основной вход opencode-gotcha.
Параметры и критерии сохранения доступны агенту во встроенных описаниях инструментов.
Инструмент
Назначение
gotcha_save
Создать или уточнить зацепку, обновить индекс
gotcha_read
Прочитать полную запись и увеличить счётчик
gotcha_index
Показать ранжированный индекс
gotcha_forget
Удалить запись и её строку индекса
gotcha_review
Пересмотреть записи, их востребованность и условия применимости
В первом MVP агент следует директиве плагина и сам вызывает сохранение, когда
найден проверенный повторно применимый обход или рабочий приём для задачи.
Фоновое извлечение оценивается отдельным этапом на реальных сессиях.
Поэтапное развитие
Каждый этап — отдельный небольшой PR с проверяемым результатом.
Этапы 1–6 завершены: первый MVP готов. Следующий этап — фоновое извлечение
зацепок из реальных сессий.
Этап
Состав
Критерий готовности
1. Концепция
Назначение, критерии сохранения, область памяти, формат и примеры
Понятно, что сохранять и когда читать
2. Каркас и хранилище
Пакет opencode-gotcha, файлы записей, перенос ранжированного индекса, блокировка записи
Файловые операции проверяются независимо от OpenCode, включая несколько процессов
3. Область памяти
Выбор проектного или глобального каталога
Локальное и глобальное подключение, подкаталоги и worktree выбирают ожидаемое хранилище
4. Инструменты
gotcha_save/read/index/forget/review и директива использования
Агент проходит полный цикл работы с зацепкой
5. Контекст
Инъекция индекса, восстановление после перезапуска и компакции
Зацепки доступны в новой и продолженной сессии
6. Установка
Инструкции и проверка упакованного пакета в чистом окружении
Установка и ручная проверка в OpenCode воспроизводимы
Основные части реализации: хранилище, выбор области, инструменты и подключение
к контексту. Адаптеры V1 и V2 используют общее ядро, схемы и выполнение
инструментов; ядро проверяется отдельно.
При извлечении учитываются результаты инструментов и проверок. Синтетические
инъекции, служебные запросы и уже показанные зацепки отделяются от нового опыта.
Повторный опыт уточняет существующую запись.
Замена шаблона на '^0$' возвращает 1: проверка отсутствия совпадения сохраняется.
Источник: test/store.test.mjs, тест «индекс ранжируется по использованию,
при равенстве — по ключу».
7. Фоновое извлечение
Поиск приёмов для повторяющихся задач и обходов после неудач или долгих итераций
Извлекаются проверенные приёмы с успешными примерами, без самоповторов