edvardgrishin27/frameproof

frameproof — смотреть видео и уметь это доказать

Главное правило

Никогда не утверждай, что было на экране, если не видел кадра.

Инструмент честно печатает покрытие. Если в отчёте есть участок «БЕЗ КАДРА» — про этот промежуток говори прямо: «кадра здесь нет, по звуку — вот что». Догадка, поданная как наблюдение, обесценивает весь разбор.

Каждое утверждение про экран — с меткой [MM:SS / fNNNN]. Это не оформление: frameproof verify проверяет каждую такую метку по индексу. Выдуманная ссылка будет поймана арифметикой, без всякой модели.

Порядок работы

1. Индекс

frameproof index "<ссылка или путь>" --ocr

Выведет отчёт покрытия. Прочитай его прежде всего остального: сколько кадров, какой максимальный разрыв, есть ли участки без кадров.

Путь к индексу — в последней строке вывода. Дальше он нужен как --out.

--ocr включает распознавание текста на кадрах (macOS, офлайн). Это делает экран грепаемым: команды, имена файлов и URL находятся поиском без единой картинки. Распознаётся отдельная копия в родном разрешении, показ остаётся лёгким.

Полезные ключи: --max-gap 10 (плотнее покрытие), --max-frames 400 (длинное видео), --lang ru (язык расшифровки, если субтитров нет).

Если рядом с видео лежат готовые субтитры — --subs речь.srt, это точнее и быстрее расшифровки. Не на macOS распознавание подключается своим движком: --ocr-command "<программа>", она получает пути к картинкам и печатает путь<TAB>текст.

2. Прочитай карту

cat <индекс>/index.json

Маленький файл, читай целиком. В нём длительность, число кадров, источник транскрипта и — главное — блок coverage.

3. Ищи текстом, а не картинками

frameproof search "<запрос>" --out <индекс>

Ищет и по речи, и по тексту с экрана. Возвращает строки с тайм-кодами. Ни одной картинки — ноль визуальных токенов. Большинство вопросов закрывается здесь.

Поиск подстрочный (триграммы), русские падежи не мешают.

Для более сложных выборок грепай напрямую:

grep -i "docker" <индекс>/segments.jsonl | head
grep -i "npm" <индекс>/frames.jsonl | head

4. Смотри кадры только когда без них никак

frameproof frames --at 4:12 --out <индекс>          # момент
frameproof frames --ids f0043,f0044 --out <индекс>  # конкретные кадры

Единственная команда, отдающая изображения. Прочитай выданные пути через Read.

Бюджет: 4–8 кадров за раз. Один кадр 1280×720 стоит около 1196 визуальных токенов. Показать все кадры часового видео — это сотни тысяч токенов; так делать не надо.

5. Отвечай с доказательством

Формат утверждения об экране:

На 18:38 показана таблица маршрутизации моделей: MAIN — дорогая умная, AUXILIARY — дешёвая и быстрая. [18:38 / f0097]

Если человек попросил статью или конспект — вставляй кадры как иллюстрации по их путям из frames.jsonl и рядом ставь тайм-код.

6. Проверь себя — когда попросили

Метка [MM:SS / fNNNN] не украшение, а проверяемая ссылка. Механический аудит бесплатен и мгновенен, запускай его на любом разборе длиннее пары абзацев:

frameproof verify <файл-с-разбором.md> --out <индекс>

Он не знает ничего о смысле — он проверяет целостность ссылки: существует ли кадр, тот ли у него тайм-код, не попал ли момент в участок без кадров, запрашивался ли этот кадр вообще, встречается ли процитированная строка в тексте кадра или в речи рядом.

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

7. Слепой второй взгляд — только по явной просьбе

Когда человек говорит «проверь разбор», «перепроверь», «ты точно это видел» — запусти состязательную проверку.

frameproof verify <файл> --out <индекс> --plan

Команда выдаст JSON с заданиями. Делегируй их субагенту frameproof-adversary одним вызовом (не по агенту на утверждение — одного достаточно).

Что передавать субагенту: только пронумерованный список утверждений и пути к кадрам, ровно как в JSON.

Чего НЕ передавать, ни одним словом:

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

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

Что делать с вердиктами:

• CONFIRMED — оставить как есть.
• REFUTED — пометить, а не удалять: [не подтверждено вторым взглядом: <причина>]. Опровергатели ошибаются на верных утверждениях заметно чаще, чем кажется, поэтому решение принимает человек, а не ты.
• UNSUPPORTED — сказать честно: на кадре этого не видно, вывод сделан по звуку или по соседним моментам.

Не запускай этот проход по своей инициативе после каждого разбора. Он стоит токенов и времени, а механический слой ловит большую часть проблем бесплатно.

Чего делать нельзя

• Не пересказывай видео по одному транскрипту, называя это разбором экрана. Речь и экран расходятся: в ролике человек говорит «опенроутер», а на экране написано openrouter/pareto-code (min_coding_score 0.65). Второе есть только в кадрах и в OCR.
• Не загружай кадры пачками «на всякий случай». Сначала поиск, потом точечно кадры.
• Не выдавай OCR за дословный текст кода. Распознавание путает пунктуацию: [main читается как Imain. OCR нужен, чтобы НАЙТИ кадр; что на нём написано — смотри глазами.
• Не молчи о слепых участках. Если покрытие меньше 100 %, скажи об этом человеку.

Если чего-то не хватает

frameproof doctor

Покажет, что установлено и чего нет. Обязательны ffmpeg и numpy; yt-dlp нужен только для ссылок; расшифровка — mlx-whisper (быстро на Apple Silicon) или openai-whisper (везде). Ключи не нужны ни для чего.