--- name: hp-extraction description: > Извлечение ивритского текста из PDF-исходника «Гарри Поттера» и сборка в структурированный markdown. Используй этот skill всегда, когда пользователь просит обработать страницы из исходника Гарри Поттера, извлечь иврит из PDF, распаковать архив со страницами книги, создать markdown из ивритского текста, или упоминает файлы вида «Исходник_Гарри_Поттер_*.pdf». Также используй, если пользователь говорит «обработай страницы», «извлеки текст», «сделай markdown» в контексте ивритского Гарри Поттера. Метод строго фиксирован: работать только полностраничными изображениями, читать их глазами; запрещено нарезать/кропать картинки, создавать промежуточные изображения и писать любые скрипты, кроме готового scripts/prepare_pdf.py. Задача — распознать видимый текст, попутно исправляя только явные опечатки автора, но ничего не выдумывать: знание сюжета может лишь отбраковать неверное прочтение, а не поставлять его. Догадки, реконструкции и исправления фиксируются в отдельном файле-протоколе; огласовки (никуд) копируются лишь те, что реально видны. --- # Извлечение markdown из исходника Гарри Поттера ## Входные данные Все данные — от пользователя. Это первый скил в текстовой ветке pipeline; предыдущих шагов нет. 1. **PDF-исходник** — файл с исходником главы. Может быть в двух форматах: - **ZIP-архив** с расширением `.pdf` (внутри `N.jpeg` и `N.txt`) — старый формат - **Настоящий PDF-документ** — новый формат 2. **Номер главы** 3. **Диапазон страниц** — первая и последняя страницы **Пример задания:** «файл Исходник Гарри Поттер 1 книга 1 стр 1 35.pdf, глава 1, обработай с 30 страницы по 35 страницу» Если пользователь не указал какой-либо из параметров — запросить. ## Выходные файлы Скилл создаёт **два** файла рядом друг с другом: 1. **Основной markdown** — распознанный текст главы: ``` HP_ch{номер_главы}_{первая_страница}_{последняя_страница}.md ``` Пример: `HP_ch1_30_35.md`. Это вход для скила `hp-translate`. 2. **Протокол расхождений** — лог всех догадок и исправлений опечаток автора: ``` HP_ch{номер_главы}_{первая_страница}_{последняя_страница}_протокол.md ``` Пример: `HP_ch1_30_35_протокол.md`. Файл для человека-проверяющего; в pipeline не передаётся. Формат — см. раздел «Распознавание, догадки и исправления». Если ни одной догадки и ни одного исправления не было — протокол всё равно создаётся, с явной строкой «Расхождений нет». --- ## Подготовка: скрипт `prepare_pdf.py` Перед визуальным чтением нужно подготовить изображения страниц. Скрипт `scripts/prepare_pdf.py` автоматически определяет формат файла и извлекает страницы в единообразную структуру. ### Запуск ```bash python scripts/prepare_pdf.py "<путь_к_файлу>.pdf" <первая_стр> <последняя_стр> [--output-dir <папка>] [--dpi 300] ``` **Пример:** ```bash python scripts/prepare_pdf.py "Гарри Поттер книга 1 глава 3.pdf" 3 8 --output-dir ./tmp ``` ### Что делает скрипт 1. Определяет формат файла (ZIP-архив или настоящий PDF) 2. **Если ZIP** — извлекает `N.jpeg` из архива 3. **Если PDF** — конвертирует страницы в PNG через `pymupdf` (устанавливает автоматически при необходимости) 4. В обоих случаях извлекает вспомогательный текст в `N.txt` ### Результат ``` output_dir/ ├── 3.png — изображение страницы ├── 3.txt — вспомогательный текст ├── 4.png ├── 4.txt ├── ... ``` ### Важно о файлах `.txt` Файлы `.txt` — это **текстовый слой исходника, а не OCR-мусор**. Для PDF-формата они постранично совпадают с картинкой (`14.txt` ↔ `14.png` и т.д.) и содержат и нарративный ивритский текст, и таблицу слов с русскими переводами. Это полезный **вспомогательный** источник, но **не замена** изображению, потому что: - **часть строк перевёрнута** (RTL→LTR) — напр. `הַאגְרִיד` может стоять как `די ִרְגא ַה`. Перевёрнуты не все строки, а отдельные, поэтому **порядку строк и слов доверять нельзя**. - **огласовки оторваны от букв**, сдвинуты пробелами и местами искажены (`דַ מְ בֶּלְדוֹר`) — никуд из `.txt` **недостоверен**. - **лишние пробелы разрывают слова** даже без огласовок. **Правила использования `.txt`:** - **Источник истины — всегда изображение (`N.png` / `N.jpeg`).** Огласовки, точный порядок букв/строк и написание берутся только с картинки. - `.txt` можно использовать как **сверку согласного костяка**: если слово трудночитаемо на картинке, но видно в `.txt` (с поправкой на возможный переворот), это считается опорой для прочтения — исход `догадка-чтение`, а не реконструкция `без опоры`. - **Нельзя копировать строку из `.txt` напрямую**: её надо сопоставить с изображением и при необходимости мысленно «развернуть». `.txt` — это *сверка*, а не *диктовка*. - Русские переводы в таблице слов удобно брать из `.txt` (там они в нормальном порядке). --- ## Структура каждой страницы (что видно на изображении) Каждая страница содержит: 1. **Иллюстрация** (верхняя часть) — рисунок-набросок, **игнорируем** 2. **Текст главы на иврите** — основной блок текста. Содержит: - Нарративный текст и прямую речь - Частичную вокализацию (никуд): в основном на именах собственных и отдельных сложных словах - Иногда **жирный шрифт** для выделений 3. **Таблица сложных слов** — в нижней части страницы: - Может быть в **одну колонку** (иврит | русский) или **две колонки рядом** (две пары «иврит | русский») - В обоих случаях объединяем в одну markdown-таблицу ### Особая страница — начало главы (стр. 1) Первая страница главы содержит заголовок: номер главы (פרק) и название. Его нужно отразить в markdown. --- ## Порядок работы (алгоритм) ### Метод и границы — прочитать до начала работы Это извлечение текста **визуальным чтением полностраничных изображений**. Способность модели читать иврит прямо с `N.png` (300 dpi) — единственный и достаточный инструмент. Не нужно строить вокруг этого никакой обработки. **Разрешено ровно одно действие с файлами, помимо чтения изображений и записи итогового `.md`:** один запуск `scripts/prepare_pdf.py` для подготовки страниц. **Запрещено (без исключений):** - ❌ Писать любые `.py`, `.ps1`, `.sh` и прочие скрипты, кроме готового `prepare_pdf.py`. Никакого собственного кода. - ❌ Нарезать, кропать, делить страницу на слова/области/строки; вырезать таблицу или её ячейки. - ❌ Создавать любые промежуточные изображения и папки для них (`crop`, `tmp_hi`, `cells`, `words` и т.п.). - ❌ Запускать OCR и библиотеки обработки изображений (PIL/Pillow, OpenCV, tesseract, numpy-обработку пикселей и пр.). - ❌ Менять `--dpi`, перерендеривать отдельные страницы «покрупнее», делать второй проход по картинкам ради «надёжности». **Если фрагмент трудночитаем** — это **не повод** запускать обработку, кроп или OCR. Трудные места разрешаются внимательным чтением с полной страницы, а не кодом. Достраивать прочтение можно только по реально видимым буквам; сюжет ГП при этом — фильтр, а не источник. Точные правила (что считать догадкой, что выдумкой, что записывать) — см. раздел «Распознавание, догадки и исправления» ниже. Если возникает мысль «сейчас напишу скриптик / сделаю кроп / прогоню OCR, чтобы прочитать точнее» — **это и есть запрещённое поведение. Остановиться, прочитать глазами с полной страницы, при необходимости — восстановить по контексту и записать в протокол.** ### Распознавание, догадки и исправления **Главная задача — точно перенести тот текст, что видно на странице.** Не «весь текст любой ценой», а именно видимое. Модель здесь — **транскрайбер, а не автор и не переводчик**: она не «знает» текст, она его видит. Чего не видела — того для неё нет. **Знание сюжета «Гарри Поттера» может только ИСКЛЮЧАТЬ, но не ПОДСКАЗЫВАТЬ.** Сюжетом можно отбраковать неверное прочтение («тут не может стоять это слово»), но **нельзя поставлять прочтение** («по сюжету тут логично такое»). Конкретный ивритский перевод не выводится из сюжета — его нельзя сгенерировать по памяти. Сюжет — это фильтр, а не источник. Исходник набран человеком без вычитки — встречаются явные опечатки. Их можно исправлять, но **строго в пределах опечатки**, не переписывая автора. Любая догадка, реконструкция и исправление фиксируются в файле-протоколе. #### Четыре исхода для каждого места 1. **Читается** — переносить как есть. Ничего не фиксировать. 2. **Трудночитаемо, но буквы частично видны** (смазана буква, плотная печать): достроить по видимым буквам + контексту до наиболее вероятного **реально написанного** слова. В протокол → `догадка-чтение`. 3. **Явная опечатка автора** (битая/лишняя/пропущенная буква, очевидно неверная форма): исправить минимально. В протокол → `исправление`. 4. **Букв не видно, графической опоры нет** (но место восстановимо по смыслу соседнего читаемого текста): в основной `.md` вписать лучшую реконструкцию, но **обязательно** пометить в протоколе → `без опоры`. Это **исключение, а не норма**: каждая такая строка — кандидат на ошибку, и человек проверяет их первыми. **Критерий между п.2 и п.4:** «я вижу буквы и понимаю, что написано именно это» → `догадка-чтение`. «Букв не вижу, но по смыслу подходит» → `без опоры`. Не маскировать второе под первое: честная пометка `без опоры` важнее красивой уверенности. #### Жёсткие ограничения - **Огласовки (никуд) — только реально видимые.** Не выдумывать вокализацию: если на странице её нет или она нечитаема — не добавлять «из эрудиции», даже когда «правильная» огласовка известна. Достраивается максимум согласный костяк слова, но не его огласовка. - **Не нормализовать орфографию.** Ктив мале / ктив хасер (полное и неполное написание), выборочная простановка никуда автором — это **не** опечатки. Не трогать. - **`без опоры` — пословно и редко.** Реконструировать без графической опоры можно отдельное слово или короткий оборот, но **не целыми предложениями и не абзацами**. Если на странице физически отсутствует или уничтожен крупный кусок (нечего транскрибировать) — **не сочинять его по памяти ГП**, а остановиться и сообщить пользователю. Много пометок `без опоры` на странице = страница слишком повреждена → сказать пользователю, не «вытягивать» текст фантазией. - **Тест перед записью любого нетривиального слова:** «могу ли я показать на странице буквы, из которых это слово?» Если да — это чтение (п.1/п.2). Если нет, но смысл диктует — это `без опоры` (п.4), и так и помечается. Третьего («просто впишу, потому что по сюжету так») — нет. #### Формат файла-протокола Отдельный файл `HP_ch{гл}_{первая}_{последняя}_протокол.md`: ```markdown # Протокол расхождений — Глава {гл}, страницы {первая}–{последняя} ## Страница {N} | Тип | На странице | В выходном файле | Основание | |---|---|---|---| | догадка-чтение | הגרי? (смазано) | הָגְרִיד | видны ה-ג-ר, контекст — имя Хагрид | | исправление | והוא הלך הלך | והוא הלך | удвоение слова — опечатка набора | | без опоры | ?????? (не читается) | אמר הארי | букв не видно; по смыслу соседних реплик — слова Гарри | ``` Три типа: `догадка-чтение`, `исправление`, `без опоры`. Если расхождений нет — файл с одной строкой: `Расхождений нет.` ### Шаг 1: Подготовка изображений ```bash python scripts/prepare_pdf.py "<файл>.pdf" <первая> <последняя> --output-dir <рабочая_папка> ``` Скрипт сам определит формат и подготовит изображения. Если `pymupdf` не установлен — установит автоматически. ### Шаг 2: Обработка каждой страницы из диапазона Для каждой страницы N от первой до последней. Источник — **только полностраничное изображение `N.png`** (или `N.jpeg`), читаемое глазами целиком; см. «Метод и границы» выше. 1. **Открыть изображение `N.png`** (или `N.jpeg`) целиком — это единственный источник 2. **Прочитать ивритский текст** визуально с полной страницы - Сохранять оригинальную вокализацию (никуд) как на изображении - Не добавлять собственные огласовки - Сохранять жирный шрифт как `**жирный**` в markdown - Прямая речь — в кавычках-ёлочках ״...״ 3. **Прочитать таблицу слов** визуально с той же полной страницы - Если таблица в две колонки — объединить в одну - Ивритские слова записывать с огласовками, как на картинке - Русские переводы — как на картинке 4. *(Опционально)* Если есть файл `N.txt` — использовать его как **сверку**, а не как источник: подтвердить согласный костяк трудночитаемых ивритских слов (с поправкой на возможный переворот строк) и взять русские переводы для таблицы. Огласовки, порядок и написание — только с картинки; строку из `.txt` не копировать напрямую. Подробнее — см. «Важно о файлах `.txt`» **Трудночитаемые места** разрешать чтением с опорой на контекст и фиксировать в протоколе — см. «Распознавание, догадки и исправления». Не кропать, не перерендеривать, не писать код (см. «Метод и границы»). ### Шаг 3: Сборка файлов Собрать все страницы в основной markdown по шаблону (см. раздел «Шаблон выходного файла»). Параллельно собрать файл-протокол со всеми догадками и исправлениями по каждой странице (см. «Распознавание, догадки и исправления»). ### Проверка выхода Перед выдачей проверить (проверка — это перечитывание глазами полных изображений, без какой-либо обработки; см. «Метод и границы»): - [ ] Ивритский текст соответствует изображениям с учётом зафиксированных в протоколе догадок и исправлений (особенно огласовки на именах собственных) - [ ] Огласовки взяты только из реально видимых на странице — ни одна не выдумана (никуд из `.txt` не использован) - [ ] `.txt` использован только как сверка: ни одна строка не скопирована из него напрямую, порядок и написание сверены с картинкой - [ ] Сюжет ГП нигде не использован как источник слов: каждое слово либо видно (на картинке или, как сверка, в `.txt`), либо помечено `без опоры` - [ ] Записей `без опоры` мало и они пословные; нет реконструкции целыми предложениями/абзацами по памяти - [ ] Исправлены только явные опечатки; ктив мале/хасер и авторская простановка никуда не тронуты - [ ] Имена собственные с огласовками (דַּמְבֶּלְדוֹר, מֶקְגוֹנֶגֶל, הָגְרִיד, פּוֹטֶר) - [ ] Кавычки ивритские ״...״ - [ ] Жирный шрифт сохранён как `**...**` - [ ] Таблица сложных слов полная — все слова с каждого изображения присутствуют - [ ] Нет лишних или пропущенных абзацев - [ ] Все страницы из диапазона обработаны - [ ] Создано ровно два итоговых файла: основной `.md` и `..._протокол.md`. Каждая догадка/исправление из текста есть в протоколе, и наоборот - [ ] Не создано ни одного лишнего файла: только итоговые `.md` и подготовленные `prepare_pdf.py` страницы. Папок/файлов вида `crop`, `tmp_hi`, `*.py` быть не должно Трудные места не «дочитываются» кодом или кропом — они распознаются по контексту и попадают в протокол. В финальном сообщении пользователю кратко указать, сколько внесено `догадок-чтения`, `исправлений` и `без опоры`, и где смотреть протокол. Если записей `без опоры` много — прямо предупредить, что страница плохо читаема и текст требует ручной сверки. --- ## Шаблон выходного файла Имя файла — по конвенции из раздела «Выходные файлы». ### Структура ```markdown # Гарри Поттер — Глава {номер_главы} (иврит). Страницы {первая}–{последняя} --- ## Страница {N} ### Текст на иврите {текст, прочитанный с изображения, с сохранением оригинальных огласовок} ### Сложные слова | Слово на иврите | Перевод на русский | |---|---| | {слово с огласовками} | {перевод} | | ... | ... | --- ## Страница {N+1} ... ``` --- ## Правила работы с текстом ### Иврит - **Точно копировать** вокализацию с изображения — не добавлять и не убирать никуд (огласовки берутся только реально видимые; см. «Распознавание, догадки и исправления») - Согласный костяк слова можно достроить/исправить лишь в рамках догадки-чтения или явной опечатки — с записью в протокол; авторскую орфографию (ктив мале/хасер) не нормализовать - Имена собственные всегда с огласовками, как в оригинале - Жирный текст → `**текст**` - Длинное тире — как в оригинале - Прямая речь в ивритских кавычках ״...״ ### Таблица слов - Брать **только** слова, которые есть на изображении — не добавлять свои - Порядок слов: как на изображении (сначала правая колонка сверху вниз, потом левая — если две колонки) - Многословные выражения и устойчивые сочетания записываются целиком (напр. הֵרִים אֶת מַבָּטוֹ) --- ## Ссылка на образец Образец готового результата: файл `references/HP_ch1_20_25.md` в папке этого skill. При использовании в Claude Project — прочитай этот файл через `view` перед началом работы, чтобы точно воспроизвести формат.