Frameproof

---
name: frameproof
description: |
  Смотрит любое видео (YouTube, Loom, Kinescope, запись Zoom, локальный mp4) и отвечает на вопросы
  по нему БЕЗ СЛЕПЫХ ЗОН, с обязательной ссылкой на момент. Строит индекс «кадр ↔ тайм-код
  ↔ реплика», ищет по речи И по тексту с экрана, кадры показывает только по запросу.
  Умеет ПРОВЕРИТЬ собственный разбор: механически сверяет каждую метку с индексом, а по
  просьбе запускает слепого субагента, который смотрит на кадр и пытается опровергнуть.
  Работает офлайн: yt-dlp + ffmpeg + локальная расшифровка, API-ключи не нужны.
  Используй, когда просят «посмотри это видео», «разбери ролик / созвон / лекцию»,
  «что показано на экране», «в какой момент он говорит про X», «сделай статью из видео».
when_to_use: |
  /frameproof <ссылка>, посмотри видео, разбери ролик, что на экране, найди момент в видео,
  транскрипт с кадрами, сделай конспект видео, проанализируй запись созвона.
argument-hint: "<ссылка или путь к видео>"
allowed-tools: Bash(frameproof:*) Bash(python3 -m frameproof:*) Read Grep Glob
---

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

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

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

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

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

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

### 1. Индекс

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

```bash
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]` не украшение, а проверяемая ссылка. Механический аудит бесплатен
и мгновенен, запускай его на любом разборе длиннее пары абзацев:

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

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

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

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

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

```bash
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 %, скажи об этом человеку.

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

```bash
frameproof doctor
```

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