package
Память проверенных обходов и рабочих приёмов для повторяющихся задач в OpenCode.
npm install opencode-gotchaGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Tagged topics.
Estimated unpacked size across 1 packages.
63.5 kB
Includes dependencies.
Память проверенных обходов и рабочих приёмов для 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:
{
"$schema": "https://opencode.ai/config.json",
"plugins": [{
"package": "opencode-gotcha@latest",
"options": { "origin": { "scope": "local" } }
}]
}Конфигурация 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.Сохранённая зацепка — контекст прошлого опыта. Актуальные условия, код и документация определяют, можно ли применить её сейчас.
Основной режим — проектная память, которая хранится и коммитится вместе с кодом:
.opencode/gotcha/
├── .gitignore
├── MEMORY.md
├── bash-grep-sigpipe.md
└── <ключ>.mdОдна зацепка — один Markdown-файл со стабильным ключом. Ссылки в MEMORY.md
относительны каталогу хранилища. Плагин сообщает выбранный каталог агенту,
чтобы подробные записи находились независимо от рабочей директории.
Проектные записи и индекс включаются в обычный PR. Так участники получают зацепки после checkout, а изменение приёма можно обсудить вместе с кодом. Сам плагин обновляет файлы; Git-коммиты и публикация выполняются в рамках обычного процесса работы с репозиторием.
Место подключения плагина задаёт область по умолчанию. Существующая проектная память имеет приоритет:
| Ситуация | Выбранное хранилище |
|---|---|
В проектной области OpenCode уже есть .opencode/gotcha/ | Проектное, в том числе при глобальном подключении плагина |
| Плагин подключён локально, проектного хранилища ещё нет | Проектное; создаётся при первом сохранении |
| Плагин подключён глобально, проектного хранилища нет | <каталог глобальной конфигурации 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 |gotcha_read добавляет 1 и обновляет дату использования.«Использование» здесь означает создание или явное чтение полной записи. Это показатель востребованности, а не доказательство успешного применения приёма. Популярность определяет порядок просмотра; задача, симптомы и условия — релевантность конкретной задаче.
В контекст попадает индекс, подробности читаются по необходимости. При росте индекса сначала сокращаются описания, затем остаются ключи в ранжированном порядке. Целевой размер индекса — 20 000 байт; при очень большом числе записей список ключей может превышать этот размер, поскольку ключи не отбрасываются. Сжатие выполняется для запроса без переписывания пользовательских файлов.
# Короткое название зацепки
## Когда пригодится
Повторяющаяся задача или симптом; условия, инструмент, окружение и версия.
## Что не помогает (необязательно)
Неудачный подход, если он был и его легко повторить.
## Рабочий приём
Конкретные действия и объяснение, какой поиск или какие итерации они сокращают.
## Успешный пример
Исходные данные, команда или запрос и ожидаемый результат.
## Как проверено
Наблюдаемый результат, условия проверки и доступный источник.Ниже — пример готовой зацепки. Команды проверены для Bash с pipefail:
получены коды 141 для раннего завершения, 0 при совпадении после обхода
и 1 при отсутствии совпадения.
# Раннее завершение grep -q вызывает SIGPIPE у производителя
## Когда пригодится
В Bash включён pipefail. Достаточно большой конечный поток передан в grep -q;
совпадение встречается в начале. grep завершается с кодом 0, но производитель
получает SIGPIPE, и весь конвейер возвращает 141.
## Что не помогает
Повторять тот же конвейер: проблема связана с ранним закрытием канала,
а не с отсутствием искомой строки.
## Рабочий приём
Для конечного потока дать grep дочитать вход, перенаправив найденные строки
в /dev/null. Обход применим, когда допустимо дождаться завершения производителя.
Для бесконечного потока нужен другой способ остановки производителя.
## Успешный пример
Следующий конечный поток содержит строку 1. Команда возвращает 0:
```bash
set -o pipefail
seq 100000 | grep '^1$' > /dev/null
```
## Как проверено
В Bash с pipefail команда seq 100000 | grep -q '^1$' возвращает 141.
Вариант без -q с перенаправлением в /dev/null возвращает 0.
Это пример приёма для повторяющейся задачи без предшествующей ошибки. Он относится к файловому ядру в этом репозитории и опирается на самодостаточный тест в test/store.test.mjs.
# Проверять счётчики и сортировку отдельным тестом хранилища
## Когда пригодится
В этом репозитории нужно повторно проверить изменение счётчиков и порядок
индекса. В test/store.test.mjs есть самодостаточный тест, который создаёт
изолированное хранилище и вызывает методы GotchaStore напрямую.
## Рабочий приём
Из корня репозитория запустить только этот сценарий через фильтр node:test.
Это сокращает ручную проверку с запуском OpenCode и последовательностью вызовов
инструментов. Сценарий проверяет файловые операции, а интеграция с хостом
проверяется отдельно.
## Успешный пример
Нужны установленные зависимости проекта. Команда:
```bash
node --test --test-name-pattern='^индекс ранжируется по использованию, при равенстве — по ключу$' test/store.test.mjs
```
Ожидаемый результат: один прошедший тест и код завершения 0. Сценарий создаёт
три записи со счётчиком 1, читает beta один раз и gamma дважды, затем уточняет
gamma. Итоговый порядок: gamma — 3, beta — 2, alpha — 1.
## Как проверено
Команда выполнена: один тест прошёл, код завершения 0. Проверяются также
сохранение счётчика при обновлении и порядок после создания нового экземпляра ядра.
Эти инструменты предоставляет основной вход 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 используют общее ядро, схемы и выполнение инструментов; ядро проверяется отдельно.
При извлечении учитываются результаты инструментов и проверок. Синтетические инъекции, служебные запросы и уже показанные зацепки отделяются от нового опыта. Повторный опыт уточняет существующую запись.
| 7. Фоновое извлечение | Поиск приёмов для повторяющихся задач и обходов после неудач или долгих итераций | Извлекаются проверенные приёмы с успешными примерами, без самоповторов |