Skip to content
Back to search

ex-ussr-kinship-research

Исследует родственные связи и семейную историю по персональным данным и документам с фокусом на бывший СССР, СССР и Российскую империю. Использовать для генеалогического поиска, сопоставления однофамильцев, архивных, метрических, военных, миграционных и репрессивных записей, построения доказательной цепочки и итогового отчёта. Не использовать для слежки за живыми людьми, поиска их текущих контактов или адресов, доступа к закрытым данным, обхода защиты и утверждения биологического родства без независимого подтверждения. EN — evidence-first genealogy and family-history research for the former USSR, the USSR and the Russian Empire (church/metric books, civil registration, military, migration, deportation and repression records, unindexed archive scans, namesake disambiguation, evidence chains, final report). Reads existing family trees as leads and exports source-cited trees in GEDCOM format when requested. Replies in the user's language. Not for tracking living people.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/denissergeevitch--ex-ussr-kinship-research/badge.svg)](/listings/denissergeevitch--ex-ussr-kinship-research)

HTML

<a href="/listings/denissergeevitch--ex-ussr-kinship-research"><img src="/api/listings/denissergeevitch--ex-ussr-kinship-research/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

With Node.js installed, you can use the optional [Skills CLI](https://github.com/vercel-labs/skills):

npx skills add https://github.com/DenisSergeevitch/ex-ussr-kinship-research

The CLI lets you choose your agent and installs into the current project by default; add `-g` for a personal installation across projects. See its documentation for current Node.js requirements.

Alternatively, clone the repository directly into your agent's skills folder:

# Codex
git clone https://github.com/DenisSergeevitch/ex-ussr-kinship-research ~/.codex/skills/ex-ussr-kinship-research

# Claude Code (personal skills)
git clone https://github.com/DenisSergeevitch/ex-ussr-kinship-research ~/.claude/skills/ex-ussr-kinship-research

For a single project, put the folder in `.claude/skills/` inside the repository. Most scripts need only Python 3 and the standard library. The optional `scan_montage.py` helper needs Pillow; `build_pdf.py` needs a Chromium-based browser.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 294 lines
  1. ---
  2. name: ex-ussr-kinship-research
  3. description: Исследует родственные связи и семейную историю по персональным данным и документам с фокусом на бывший СССР, СССР и Российскую империю. Использовать для генеалогического поиска, сопоставления однофамильцев, архивных, метрических, военных, миграционных и репрессивных записей, построения доказательной цепочки и итогового отчёта. Не использовать для слежки за живыми людьми, поиска их текущих контактов или адресов, доступа к закрытым данным, обхода защиты и утверждения биологического родства без независимого подтверждения. EN — evidence-first genealogy and family-history research for the former USSR, the USSR and the Russian Empire (church/metric books, civil registration, military, migration, deportation and repression records, unindexed archive scans, namesake disambiguation, evidence chains, final report). Reads existing family trees as leads and exports source-cited trees in GEDCOM format when requested. Replies in the user's language. Not for tracking living people.
  4. compatibility: Предпочтительны внутренний браузер или веб-поиск, чтение PDF/DOCX/изображений и создание файлов. Использует доступные средства веб-поиска, каталоги/API и локальные материалы; отсутствие одного инструмента не останавливает остальные проверки. Работает как skill для Codex и Claude Code.
  5. metadata:
  6. version: "1.51.0"
  7. language: "ru"
  8. reply_language: "user"
  9. region: "ex-USSR"
  10. ---
  11. # Назначение
  12. Установить или опровергнуть родственные связи через воспроизводимое исследование. Сохранять происхождение каждого артефакта, отделять запись от её интерпретации, учитывать исторические границы и варианты имён, а выводы ранжировать по силе доказательств.
  13. При чтении предоставленной метрической страницы или поиске в конкретной книге выбрать объём по запросу. Для точечной задачи достаточно выписки или результатов поиска с локаторами и оговорками. Рабочие приёмы — в `references/metric-books-scans.md`.
  14. # Язык общения / Language
  15. **Always reply in the user's language.** This file is written in Russian, but that does not mean replies should be in Russian.
  16. 1. Общаться с пользователем на языке его последнего сообщения: английском, украинском, русском, польском, немецком и т. д. Если пользователь прямо просит другой язык — использовать его.
  17. 2. Цитаты из источников приводить в оригинальном написании (кириллица, латиница, старая орфография). Рядом давать перевод на язык пользователя, если он нужен для понимания.
  18. 3. Шаблоны из `assets/` (отчёт, реестры) заполнять на языке пользователя: заголовки и пояснения переводить. Имена столбцов CSV, идентификаторы (`person_id`, `claim_id`, `artifact_id`) и статусы (`single-source`, `corroborated` и т. д.) не переводить.
  19. 4. Поисковые запросы составлять на языке источника (русском, украинском, польском, румынском, немецком, идиш и т. д.), а не на языке общения.
  20. 5. Язык общения фиксировать в `case-intake.yaml` в поле `requested_output_language`. По умолчанию `auto` — язык пользователя.
  21. # Обновления навыка
  22. В начале исследования один раз проверить новые изменения в [каноническом репозитории](https://github.com/DenisSergeevitch/ex-ussr-kinship-research). Если есть обновление, уведомить пользователя и спросить: «Вышло обновление навыка. Обновить?» Агент пользователя выполнит обновление обычными доступными ему средствами после согласия. Пока ответа нет или пользователь отказался, продолжать исследование текущей версией без повторных предложений в каждом цикле.
  23. # Автономное исследование
  24. По умолчанию вести исследование самостоятельно в длительном, при необходимости многочасовом цикле. Не завершать работу после каждого этапа вопросом «продолжать?».
  25. 1. Уточнения задавать один раз сообщением или неблокирующим инструментом, не переходя в ожидание ответа. Сразу работать с известными фактами; неизвестное отмечать как неизвестное, предположения — как гипотезы. Отсутствие ответа не блокирует исследование.
  26. 2. Повторять цикл: выбрать следующую проверку из очереди → найти и прочитать источник → сохранить артефакт и происхождение → обновить утверждения и журнал → выбрать следующий полезный шаг. Проверенные поиски не повторять без новых оснований.
  27. 3. CAPTCHA и вход обрабатывать по `references/browser-and-captcha.md`, разделы 5–5а. Если нужно участие пользователя, открыть соответствующую вкладку при наличии такой возможности и оставить шаг в очереди; блокируется только этот маршрут. Продолжать другие источники, варианты имени, семейные ветви и разбор уже полученных материалов.
  28. 4. Сохранять находки в реестрах, а оставшиеся проверки и блокировки — в рабочем плане дела, например `research-state.md`. Использовать уже имеющийся план и не переписывать в него содержимое реестров. После перерыва продолжать с очередного полезного шага.
  29. 5. Продолжать, пока остаются полезные доступные проверки в рамках задачи. Завершать при выполнении задачи и покрытии объёма, исчерпании доступных маршрутов, явной остановке пользователем или лимите среды. Перед вынужденным завершением сохранять состояние и достигнутый результат; один вопрос без ответа или один недоступный сайт не являются завершением всей работы.
  30. В браузере переиспользовать рабочие страницы и закрывать свои ненужные вкладки после проверки или партии. Перед итоговым ответом и при досрочной остановке, если управление ещё доступно, выполнить ту же проверку по разделу «Рабочие вкладки» в `references/browser-and-captcha.md`.
  31. После перерыва восстанавливать работу по текущим реестрам и решениям пользователя по `references/research-coordination.md`, раздел «Возобновление и сохранение дела». Исправления и состав связанного дерева оценивать по `references/evidence-protocol.md`.
  32. Если несколько исполнителей работают с общим делом или служебная обработка растёт быстрее полезного результата, читать `references/research-coordination.md`. Это условные рекомендации по разделению записи, передаче результатов и объёму обработки; они не требуют запускать дополнительных агентов или менять выбранное пользователем хранилище.
  33. # Генеалогическое древо в GEDCOM
  34. Если пользователь просит построить или экспортировать древо, подготовить локальный файл `.ged` по `references/gedcom.md`: GEDCOM 5.5.1 в UTF-8 по умолчанию для совместимости, либо версию, указанную пользователем или поддерживаемую выбранной им программой, например GEDCOM 7. Сохранить ссылки на источники и степень доказанности; реестры, журнал и нерешённые версии остаются в деле. Имеющееся древо разбирать как исходный материал по `references/source-strategy.md`, раздел 7, сохраняя оригинал.
  35. Программу для древа и место результата выбирает пользователь. Установка приложений, подключение MCP и автоматическая синхронизация внешнего древа находятся вне области навыка; наличие подключения само по себе не выбирает приложение и не поручает запись в него.
  36. # Работа с FamilySearch через MCP
  37. Если доступны инструменты FamilySearch MCP, использовать их для соответствующих операций в пределах задачи по `references/familysearch-mcp.md`: сначала проверить аккаунт, среду и фактические возможности подключения. Структурированное чтение, разрешённые изменения древа и просмотр неиндексированных сканов — разные маршруты; подключение MCP не заменяет оценку источников и не расширяет доступ. Без MCP продолжать обычное исследование через браузер и локальные материалы.
  38. # Неподлежащие нарушению правила
  39. 1. Считать любой новый материал **артефактом, а не фактом**. Не переносить утверждение из артефакта в вывод без оценки происхождения, читаемости, прямоты и независимости.
  40. 2. Не считать копии, зеркала, индексы и пересказы одной записи независимыми подтверждениями. Назначать им общий `independence_group`.
  41. 3. Не присваивать связи статус `corroborated` без как минимум двух независимых доказательных цепочек. Даже сильный первичный документ до кроссподтверждения помечать `single-source`.
  42. 4. Не сливать двух одноимённых людей только по ФИО, возрасту или населённому пункту. До разрешения личности вести отдельные `person_id`.
  43. 5. Сохранять исходное написание имён, дат и мест. Нормализованные варианты хранить отдельно и явно помечать как исследовательскую форму.
  44. 6. Не скрывать противоречия. Фиксировать их рядом с выводом и сохранять альтернативные гипотезы.
  45. 7. Для живых людей минимизировать данные. Не искать и не публиковать текущие адреса, телефоны, личные аккаунты, документы-идентификаторы, сведения о несовершеннолетних или иные данные, не необходимые для семейно-исторической задачи.
  46. 8. Не загружать пользовательские документы, ДНК-данные или фотографии в сторонние сервисы без явного разрешения пользователя.
  47. 9. Не обходить ограничения доступа и лимиты. Для CAPTCHA допустима одна попытка через обычный интерфейс внутреннего браузера агента, если позволяют инструменты и правила сайта; вход выполняет пользователь. Порядок попытки, открытия вкладок и передачи заблокированного шага — `references/browser-and-captcha.md`, разделы 5–5а.
  48. 10. Не выдавать отсутствие результата поиска за доказательство отсутствия человека или события.
  49. 11. Не выдумывать недостающие сведения и не повышать семейную память до документального факта. При исчерпании полезных доступных проверок сохранить результат и оставшиеся вопросы; не повторять без новых оснований одни и те же поиски.
  50. # Рабочий процесс
  51. Это опорный маршрут: возвращаться к нужным шагам по мере находок, а не ждать полного заполнения предыдущего этапа. Скрипты помогают вести дело; если инструмент недоступен, выполнить доступную часть работы средствами агента.
  52. ## Шаг 1. Зафиксировать задачу и допустимый объём
  53. 1. Сформулировать рабочую цель из запроса. При широкой задаче начать с наиболее надёжно известной ветви и расширять поиск по находкам.
  54. 2. Зафиксировать известные имена, варианты написания, примерные даты, населённые пункты, конфессию или общину только если это релевантно архивному поиску, занятия, родственников и миграции.
  55. 3. Отметить, какие лица могут быть живы. Для них записать заявленную пользователем связь, согласие или иную законную и неинтрузивную основу исследования. Если дальнейшее действие зависит от того, жив ли человек (беседа, ДНК-тест, запрос от его имени), сперва сверить `living_status` и уже полученные сведения в деле. При `unknown` сохранить статус и планировать это действие условно с учётом правил для потенциально живых лиц. Если ответ нужен для выбора действия и его ещё нет в материалах, задать один точечный вопрос по разделу «Автономное исследование», п. 1. Пока ответ неизвестен, продолжать доступную работу и учитывать полезную альтернативу по задаче.
  56. 4. Учитывать уже указанные ограничения. Не превращать пустые поля шаблона в дополнительный опрос; обычный поиск, чтение, локальный анализ и сохранение доступных исторических материалов по задаче выполнять самостоятельно. Уже полученные разрешения не переспрашивать.
  57. 5. При наличии входных файлов сохранить оригиналы без изменений и работать с копиями.
  58. 6. **Один раз уточнить имеющиеся материалы:** «Какие материалы по этой семье у вас уже есть?» Если они уже описаны или приложены, не переспрашивать. Ответ учесть в `input_materials` и, если он касается прежних исследований, в `prior_family_research`. Пока ответа нет, отметить это в `notes` и сразу продолжить поиск по известным данным.
  59. Использовать структуру `assets/case-intake.template.yaml`. Подробные ограничения читать в `references/privacy-and-safety.md`.
  60. ## Шаг 2. Инициализировать дело и реестры
  61. Продолжить существующее дело или самостоятельно выбрать отдельную папку вне навыка, например в `~/kinship-cases/`. Повторно инициализировать уже созданное дело не нужно. Для нового дела:
  62. ```bash
  63. python scripts/init_case.py --case-dir <путь> --research-question "<вопрос>" --subject-label "<основной человек>"
  64. ```
  65. Заполнять по мере работы, сохраняя неизвестные сведения как неизвестные:
  66. - `case-intake.yaml` — задача, рамки, исходные данные и ограничения;
  67. - `person-register.csv` — отдельные кандидаты на личность;
  68. - `artifact-register.csv` — каждый документ, веб-результат, изображение или запись;
  69. - `claims-register.csv` — проверяемые утверждения, извлечённые из артефактов;
  70. - `relationship-register.csv` — гипотезы о связях между `person_id`;
  71. - `search-log.csv` — запросы, фильтры, неудачи, CAPTCHA и следующие шаги;
  72. - рабочий план, например `research-state.md`, — оставшиеся проверки и блокировки (необязательный шаблон в `assets/`; при наличии другого плана дела продолжать его);
  73. - `final-report.md` — рабочий текст исследования по необязательному шаблону;
  74. - `report.html` — самостоятельный итоговый HTML-отчёт (шаг 12), создаётся по мере подготовки результата;
  75. - `photos/` — найденные фотографии и `README.md` с их описанием (шаг 6а);
  76. - `report.pdf` — дополнительный экспорт отчёта только по явному запросу пользователя (шаг 12).
  77. Для локального файла вычислить контрольную сумму:
  78. ```bash
  79. python scripts/hash_artifact.py <путь-к-файлу>
  80. ```
  81. ## Шаг 3. Разобрать материалы пользователя
  82. 1. Извлечь текст, таблицы, подписи, штампы, номера актов, архивные шифры и оборотные пометы.
  83. 2. Для сканов указать страницу, область и качество чтения. Нечитаемые места обозначать `[неразборчиво]`; предположения — `[предположительно: ...]`.
  84. 3. Не исправлять молча фамилии, даты и географию. Сохранять `names_as_written`, `place_as_written` и исходную дату.
  85. 4. Для каждого материала создать `artifact_id` и записать происхождение, дату получения, локальный путь или URL, тип оригинала/копии, читаемость и `independence_group`.
  86. 5. Существенные для ответа утверждения оформить отдельными `claim_id`, чтобы их источники и противоречия можно было проверить.
  87. Подробную схему оценки читать в `references/evidence-protocol.md`.
  88. Если дерево и исследовательские заметки дают разные версии существенной связи, сопоставить их по `references/source-strategy.md`, раздел 7, сохранив оригиналы и историю выводов.
  89. ## Шаг 4. Построить историко-географическую модель
  90. 1. Для каждого события определить юрисдикцию **на дату события**, а не только современную страну.
  91. 2. Установить нужные для поиска уровни юрисдикции и архив-преемник. При неоднозначности вести несколько вариантов и проверять их по каталогам и документам.
  92. 3. Составить варианты старых и новых топонимов, языков и письменностей.
  93. 4. Записать исходный календарь; не выполнять скрытую конвертацию дат.
  94. 5. Построить матрицу вариантов имени: исходное написание, дореформенная форма, местный язык, кириллица/латиница, патроним, фамильное окончание, возможная русификация и бытовые формы.
  95. 6. Не считать переводные или созвучные имена эквивалентными без дополнительных признаков.
  96. 7. Выбирать существенные варианты под язык, место и период; расширять их при пробелах и новых находках. Например:
  97. - е/ё и окончания -ев/-ов/-ёв, полное и сокращённое отчество («Данилович»/«Даниилович»), записи без отчества;
  98. - женские формы (-ова/-ов, -ская/-ский, -ина/-ин) и для женщин — **девичью и все брачные фамилии**;
  99. - польское, идишское, немецкое, румынское и латинское написание (`references/ex-ussr-locale-guide.md`);
  100. - церковную форму имени и бытовую (Евдокия/Авдотья, Иоанн/Иван, Мордух/Мордко/Марк).
  101. 8. Если режим поиска требует точного совпадения заполненных полей, проверять обоснованные сочетания форм имени, отчества и фамилии; варианты отчества и имена, которые путали, вести отдельными поисковыми гипотезами (`references/ex-ussr-locale-guide.md`, раздел 4, «Базы с точным совпадением полей»).
  102. Читать `references/ex-ussr-locale-guide.md` только когда появляются исторические границы, смена языка/письменности, неоднозначные или искажённые топонимы. Неопознанное название места расшифровывать по нескольким записям той же единицы (раздел 1 справочника), а не по одному созвучию. Для дел, связанных с Галицией или Буковиной, читать `references/habsburg-galicia-bukovina.md`. Для Бессарабии, Молдовы, МАССР читать `references/bessarabia-moldova.md`. Для армянских семей и поиска по Южному Кавказу читать `references/armenia-south-caucasus.md`. Для Оренбургского казачьего войска, Челябинского и Верхнеуральского уездов Оренбургской губернии читать `references/orenburg-chelyabinsk-verkhneuralsk.md`. Для чеченских семей, выселения 1944 года и спецпоселения в Казахстане и Киргизии читать `references/chechnya-deportation.md`. Для угнанных в Германию, остарбайтеров и советских граждан, умерших или учтённых в Германии в 1941–1945 годах, читать `references/germany-forced-labour.md`.
  103. ## Шаг 5. Составить план поиска
  104. 1. Начать с наиболее позднего надёжно установленного события и двигаться назад по одной связи за раз. Место захоронения не доказывает место происхождения; исходную гипотезу о происхождении проверять по документам. Для городской биографии XX века известный работодатель или место проживания могут дать следующий маршрут поиска.
  105. 2. Для каждого пробела определить подходящий тип записи: акт ЗАГС, метрическая книга, исповедная ведомость, ревизская сказка, посемейный/домовой список, перепись, военная запись, эвакуация, репрессия, миграция, адрес-календарь, некролог, кладбищенская запись и т. п.
  106. 3. Выбирать источник по вопросу, покрытию и доступности. От индекса или семейной страницы переходить к указанному оригиналу; наводки помогают продолжать поиск, но не заменяют проверку доказательств.
  107. 4. По мере появления записывать существенные гипотезы и различающие их проверки.
  108. 5. Составить запросы по вариантам имени, месту, диапазону лет, родственникам, профессии, воинской части и архивному шифру.
  109. 6. Намечать проверки по вопросу, месту и периоду, используя `references/source-strategy.md`, раздел 12, и подходящие источники каталога. В журнале отражать фактически выполненные поиски и ограничения, а оставшиеся полезные шаги держать в плане.
  110. 7. В биографическом и семейном исследовании проверять семейные публикации и фотографии, если они могут помочь задаче; для короткого точечного вопроса выбирать относящиеся к нему проверки.
  111. 8. Если женская линия упирается в смену фамилии, проверить маршрут «надгробие → кандидат в родственники → военная запись» (`references/field-lessons.md`, раздел 4). Для советской гражданской биографии использовать документы о работе, наградах и эвакуации по месту события (`references/field-lessons.md`, раздел 9); региональные примеры не ограничивают охват бывшего СССР. Если фамилия или отчество ребёнка не совпадают с отцом из семейного рассказа, вести версии раздельно и проверять их по `references/field-lessons.md`, раздел 10.
  112. Подробную тактику и приоритеты источников читать в `references/source-strategy.md`. Каталог стартовых ресурсов, поддерживаемый автором навыка, находится в `references/seed-sources.md` и не заменяет проверку актуальности и происхождения. Просмотреть структуру всего каталога и изучить подходящие разделы, в том числе в конце файла; первые строки каталога не определяют его полное покрытие.
  113. Практические приёмы для неиндексированных сканов (FamilySearch, архивные порталы), документов о репрессиях и депортациях, военных баз, исчезнувших хуторов, оккупированных территорий и ситуации «открытые источники исчерпаны» читать в `references/field-lessons.md`.
  114. Для российских справок ЗАГС с дополнительными сведениями, дел о политических репрессиях и реабилитации и доступа к ним, документов о раскулачивании и лишении избирательных прав, а также кладбищенских записей читать `references/russia-records-access.md`.
  115. ## Шаг 6. Искать доступными инструментами
  116. Использовать веб-поиск, каталоги/API и браузер по возможностям источника:
  117. 1. Использовать поиск, переходы, фильтры каталогов и просмотр документов последовательно; не отправлять массовые запросы.
  118. 2. Для каждого поиска сразу записывать точный запрос, локаль/язык, фильтры, URL, дату доступа и результат в `search-log.csv`.
  119. 3. При обнаружении записи сохранить устойчивый идентификатор, архивный шифр, номер страницы/кадра и прямую ссылку, если она существует.
  120. 4. Для сканированных PDF и изображений просматривать саму страницу, а не полагаться только на OCR или сниппет. Готовность содержимого просмотрщика проверять по `references/browser-and-captcha.md`, раздел 2, «Загрузка кадров и указателей». Для поиска в метрической книге и подробного чтения записи использовать `references/metric-books-scans.md`; для других рукописных таблиц и спорных чтений — «Проверку визуального чтения» в `references/field-lessons.md`, раздел 1. При длительном чтении серий сканов применять небольшие партии и сохранение прогресса по `references/research-coordination.md`, раздел «Длительное чтение сканов».
  121. 5. Не использовать фрагмент поисковой выдачи как конечный источник, если доступна исходная страница.
  122. 6. При недоступности браузера использовать другие доступные средства поиска и чтения, а также предоставленные материалы. Указывать фактические ограничения, не заявляя невыполненные проверки.
  123. 7. После находки вернуться к оставшимся существенным вопросам и выбрать следующий полезный источник. Найденное можно сообщать сразу, явно указывая покрытие и незавершённые проверки.
  124. 8. **Мемориальные и семейные сайты проверять их собственным поиском, когда он доступен.** Пустая внешняя веб-выдача не подтверждает отсутствие записи во внутренней базе. Форматы поисковых ссылок — в `references/source-strategy.md`, раздел 12.
  125. 9. Для точечного поиска в индексах FamilySearch по месту/DGS и локального анализа разрешённых фрагментов читать `references/familysearch-indexes.md`. Если индекса нет, использовать маршрут чтения сканов из `references/field-lessons.md`.
  126. 10. Для документов Первой мировой на GWAR читать `references/ww1-search.md`: поиск человека и ограниченный поиск по местности с учётом правил источника. Полученные карточки помогают различить кандидатов, но не являются переписью населения и не доказывают родство.
  127. 11. Результаты этих скриптов добавлять в существующие `artifact-register.csv` и `search-log.csv` через `scripts/register_search.py` или вручную. Автоматический перенос сохраняет наводки и исходные данные; личности, утверждения, связи и независимость устанавливать по шагам 7–10. Не создавать отдельное дело для каждого источника.
  128. При проверке охвата или смысла индексированной выдачи, повторном использовании поиска, библиографической находке или конфликте каталога читать `references/search-result-validation.md`. Этот же справочник использовать для проверки архивных ссылок, включая предполагаемые исправления шифров и перемещения дел, и для сопоставления покрытия нескольких архивных дел.
  129. ### 6а. Фотографии человека
  130. Искать фотографии в том же проходе, что и документы, а не после отдельной просьбы:
  131. 1. Выбор источников, опознание, датировку и хранение вести по `references/photo-search.md`. Не применять распознавание лиц; сомнительные подписи не считать доказанным опознанием.
  132. 2. Сохранять доступные исторические снимки по задаче без отдельного вопроса о каждом файле, соблюдая ограничения источника. Учитывать их как артефакты и описывать в `photos/README.md`.
  133. 3. Записать покрытие поиска. `not-found` означает «не найдено в проверенных источниках», а не доказательство, что фотографий никогда не существовало.
  134. При входе, CAPTCHA и ошибках доступа использовать `references/browser-and-captcha.md`: недоступный маршрут отметить и продолжить другие проверки.
  135. ## Шаг 6б. Запросить сведения у учреждения
  136. Если ответ требует неопубликованной записи или помощи хранителя, можно подготовить и по поручению пользователя отправить запрос в архив, библиотеку, вуз, музей или другое подходящее учреждение.
  137. 1. Выбрать хранителя и проверить официальный канал обращения; примеры адресатов, состав письма и порядок отправки — в `references/correspondence.md`. Для записи ЗАГС или государственной услуги использовать точки входа и проверку способа получения в `references/government-portals.md`.
  138. 2. Использовать доступную почтовую интеграцию. Если её нет, предложить пользователю подключить почту через штатный интерфейс среды или передать готовое письмо для самостоятельной отправки. Подключение ящика само по себе не разрешает отправку.
  139. 3. Выполнить уже разрешённую отправку без повторного согласования в пределах поручения; учитывать ограничения адресатов, вложений и платных действий. При отсутствии разрешения подготовить конкретное письмо и запросить согласие на его отправку, продолжая остальные проверки.
  140. 4. Проверить результат, сохранить письмо/номер обращения и обработать ответ как источник. При неоднозначной ошибке сначала проверить, ушло ли письмо, чтобы не отправить дубль.
  141. ## Шаг 7. Оценить артефакты и извлечь утверждения
  142. Для каждого артефакта отдельно оценить:
  143. - происхождение и архивную ссылку;
  144. - оригинал, изображение оригинала, индекс, копию или пересказ;
  145. - современность событию;
  146. - информанта и его возможную осведомлённость;
  147. - прямое или косвенное отношение к утверждению;
  148. - читаемость и полноту;
  149. - независимость от других артефактов;
  150. - признаки ошибки, позднего исправления или заимствования.
  151. Не использовать числовой «процент истины». Присваивать утверждениям только объяснимые статусы:
  152. - `hypothesis` — рабочая гипотеза;
  153. - `single-source` — поддержана одной доказательной цепочкой;
  154. - `corroborated` — поддержана минимум двумя независимыми цепочками без неразрешённого существенного конфликта;
  155. - `strongly-corroborated` — несколько независимых цепочек, включая хотя бы одну прямую запись с установленным происхождением;
  156. - `contradicted` — сильное противоречащее свидетельство;
  157. - `unresolved` — данных недостаточно или конфликт не разрешён.
  158. ## Шаг 8. Разрешить личности
  159. 1. Сопоставлять не только имя, но и совокупность дат, мест, родственников, профессии, адреса, сословия/статуса, конфессии, свидетелей, воинской части и миграционного маршрута.
  160. 2. Вести конкурирующих кандидатов раздельно до появления различающих признаков.
  161. 3. Зафиксировать причины каждого слияния или разделения `person_id`.
  162. 4. Проверить круг семьи: супругов, родителей, детей, братьев/сестёр, восприемников, свидетелей и соседей, если это помогает идентификации.
  163. 5. Не трактовать проживание в одном хозяйстве как биологическое родство.
  164. ## Шаг 9. Проверить родственную цепочку
  165. 1. Строить сложную связь из отдельных рёбер: например, дед/внук требует двух независимо проверенных связей родитель–ребёнок.
  166. 2. Различать биологическую, юридическую, приёмную, опекунскую, сводную и хозяйственную связь.
  167. 3. Для каждого ребра перечислить поддерживающие и противоречащие `artifact_id`/`claim_id`.
  168. 4. Не выводить родство из общей фамилии, ДНК-совпадения без контекста, семейного дерева пользователя или сообщения на форуме.
  169. 5. Чувствительные открытия — усыновление, возможное несоответствие отцовства, репрессии, этничность, религия — формулировать нейтрально, только в объёме, необходимом для ответа, и с явной ссылкой на источник.
  170. 6. Оценивать принадлежность записи человеку и доказанность каждого родственного ребра отдельно: установленная личность не повышает статус связи. Отчество само по себе не доказывает отцовство (`references/evidence-protocol.md`, раздел «Разрешение личности»).
  171. ## Шаг 10. Провести аудит доказательств
  172. Запустить:
  173. ```bash
  174. python scripts/audit_evidence.py --case-dir <путь>
  175. ```
  176. Проверить ссылки между реестрами и отчётом, независимость источников и обоснования статусов. Скрипт проверяет реестры и рабочий `final-report.md`, если он есть; итоговый HTML сверить с реестрами средствами агента, без обязательной Markdown-копии ради аудита. Ошибки ссылочной целостности исправить; предупреждения разобрать по источникам, сохранив нерешённые вопросы. Не повышать статус ради прохождения проверки. `single-source`, `hypothesis` и `unresolved` — допустимые рабочие результаты. Файл GEDCOM аудит не проверяет: сверить экспорт с реестрами по `references/gedcom.md`.
  177. Перед выдачей убедиться, что существенные выводы имеют источники, противоречия видимы, покрытие описано честно, а лишние данные живых людей исключены. Неполное покрытие явно обозначить; оно не мешает сообщить уже установленное и продолжать поиск.
  178. ## Шаг 11. Подготовить итоговое исследование
  179. Использовать `assets/final-report.template.md` как ориентир под задачу. Краткий ответ должен содержать вывод, источники, неопределённость и следующий полезный шаг; для подробного исследования добавить хронологию, проверку родственных связей, противоречия и покрытие поиска. Неприменимые разделы пропускать, неизвестные сведения не выдумывать.
  180. Фактические выводы сопровождать ссылками на артефакты `[A-0001; A-0007]`. Обновлять отчёт по мере находок, не ждать исчерпания всех направлений ради промежуточного результата.
  181. В содержательном отчёте о проходе показывать новые проверки и результаты. Если доступны только заголовок или описание, сразу указать это и назвать установленный шифр, если он есть. Отдельно указать прочитанные записи или страницы, что в них сверено, и какие вопросы остаются открытыми. При продолжении брать исходный охват из журнала поиска и объяснять основания существенных повторов по `references/research-coordination.md`.
  182. При содержательном промежуточном отчёте или передаче дела можно добавить компактный упорядоченный список следующих проверок, если он помогает выбрать маршрут или продолжить работу. Число пунктов и подробность выбирать по задаче; после каждой операции такой список не требуется. Доступные проверки агент продолжает самостоятельно, сохраняя текущий план дела.
  183. Для существенных пунктов пояснять, какой вопрос или родственное звено они помогут проверить, где источник, какова его фактическая доступность, кто выполняет проверку и от чего она зависит. Упорядочивать по ожидаемой пользе для исследовательского вопроса с учётом усилий и зависимостей. Стоимость и сроки указывать, если известны; непроверенный доступ и неизвестные затраты отмечать прямо, неприменимые поля пропускать. У родственников можно уточнять наличие документов и записывать семейные воспоминания, различая их происхождение и доказательную силу по `references/evidence-protocol.md`.
  184. Задания и передачу результатов при уже согласованной параллельной работе оформлять по `references/research-coordination.md`.
  185. ## Шаг 12. Подготовить HTML-отчёт; PDF — только по запросу
  186. По умолчанию итоговый отчёт — полноценный HTML-файл, например `<дело>/report.html`: самостоятельный результат для чтения и передачи, а не только исходник для PDF. По умолчанию использовать редакционную вёрстку `assets/report.template.html` с семейным древом в шапке и ссылками от показанных связей к их основаниям; адаптировать схему и разделы к известным данным по комментариям шаблона. Для дерева только связанной семьи применять `references/evidence-protocol.md`, раздел «Связанное дерево для читателя». Сохранять исходные алфавиты имён и подходящие системные шрифты. При необходимости подготовить HTML другими доступными средствами агента. Для короткого ответа достаточно текста или Markdown; явно запрошенный пользователем формат имеет приоритет.
  187. Создавать PDF **только по явному запросу пользователя**. Просьба подготовить отчёт для семьи сама по себе не означает PDF. Не предлагать конвертацию как обязательный следующий шаг и не запускать сборку PDF по собственной инициативе.
  188. - Объяснять надёжность понятными словами, сохраняя различие между подтверждением, гипотезой, нехваткой данных и противоречием во всех разделах, включая сводки. Общий исторический фон отделять от сведений о семье. Архивные шифры и ссылки оставить.
  189. - Фотографии, военную службу, репрессии и другие тематические блоки включать по содержанию дела. Отсутствие фото или полного ответа не мешает подготовить отчёт.
  190. - Оригиналы изображений сохранять; рабочие копии обрезать или уменьшать только по потребности, сохраняя читаемость.
  191. - Для развёрнутого семейного отчёта можно отделить рассказ от рабочего плана. Хронологию, схему родства с местом читателя, карту, снимки документов, пояснения терминов и готовые письма выбирать по задаче и имеющимся материалам. План следующих проверок оформлять по шагу 11.
  192. - Перед передачей семье полезно перечитать готовый текст глазами читателя без контекста дела: проверить противоречия, путаницу имён и непонятные слова, сверить выводы с реестрами. При редактуре биографии сверяйте источники и связи по пункту «Сохраняйте основания при редактуре биографии» в `references/research-coordination.md`. Это может сделать сам агент; отдельное «холодное» чтение другим исполнителем — дополнительный приём, если доступен, в пределах существующих правил приватности и координации, а не условие готовности отчёта.
  193. Проверить читаемость HTML, ссылки и изображения; передать пользователю ссылку на готовый файл. Для HTML-отчёта не нужны PDF, Chromium или постраничный просмотр. Если HTML создать сейчас невозможно, сохранить полезный результат в доступном формате и явно указать ограничение, продолжая исследование.
  194. Если пользователь явно запросил PDF, использовать готовый HTML как исходник, например:
  195. ```bash
  196. python scripts/build_pdf.py --html <дело>/report.html --out <дело>/report.pdf
  197. ```
  198. Для запрошенного PDF проверить читаемость и вёрстку страниц. Если этот способ сборки недоступен, использовать другой доступный инструмент или передать HTML и сообщить, что PDF пока не подготовлен, продолжая исследование.
  199. # Обработка ошибок
  200. - Если документ не читается, сохранить его как артефакт, описать дефект и при необходимости запросить лучшую копию; до ответа работать с другими материалами и источниками.
  201. - Если источник исчез, проверить официальный каталог, веб-архив только в допустимых пределах и зеркала; зеркала не считать независимыми.
  202. - Если архивная юрисдикция неясна, проверить правдоподобные места, приходы и архивы параллельно; до разрешения не объединять кандидатов.
  203. - Если результаты дают несколько однофамильцев, расширить семейный кластер и не выбирать кандидата по интуиции.
  204. - Если источники противоречат друг другу, сохранить обе версии, оценить информанта и искать третий независимый источник.
  205. - Если поиск затрагивает явно живого человека без достаточной семейно-исторической основы, сузить исследование до предоставленных пользователем материалов или прекратить интрузивную часть.
  206. - Если документ и семейная память расходятся (например, место рождения в паспорте и в рассказе), сохранить обе версии как отдельные утверждения со своими источниками. Не подгонять документ под рассказ и не наоборот. Различать «родился» и «вырос».
  207. - Если в одной базе найдено много документов, вернуться к оставшимся существенным вопросам и выбрать следующую полезную проверку.
  208. - Если все полезные доступные маршруты в рамках задачи исчерпаны, один раз перечислить установленное, неустановленное и покрытие; маршруты, ожидающие действия пользователя, назвать отдельно и не считать исчерпанными. Сохранить рабочий план, вопросы родственникам и проекты архивных запросов (`references/field-lessons.md`, раздел 8); продолжить с этого состояния при появлении новых данных или доступа.
README.md · README · 155 lines
  1. # ex-USSR Kinship Research
  2. ![ex-USSR Kinship Research cover](docs/cover.jpg)
  3. Languages: [English](README.md) / [Русский](README.ru.md) / [Беларуская](README.be.md) / [Қазақша](README.kk.md) / [Українська](README.uk.md) / [Polski](README.pl.md) / [Deutsch](README.de.md) / [Română](README.ro.md) / [Eesti](README.et.md) / [Latviešu](README.lv.md) / [Lietuvių](README.lt.md) / [ქართული](README.ka.md) / [Հայերեն](README.hy.md) / [Azərbaycanca](README.az.md) / [Кыргызча](README.ky.md) / [Тоҷикӣ](README.tg.md) / [Türkmençe](README.tk.md) / [O‘zbekcha](README.uz.md) / [日本語](README.ja.md)
  4. **An evidence-first genealogy skill for AI agents (Codex, Claude Code and other Agent Skills runtimes).** It turns an agent into a careful family-history researcher for the former USSR, the Soviet Union and the Russian Empire. The agent reads church books and civil records, military, deportation and repression files, and unindexed archive scans. It keeps every find traceable, separates records from interpretation and says plainly what is proven and what is not.
  5. Coverage includes all 15 former Soviet republics: Russia, Ukraine, Belarus, Moldova, Estonia, Latvia, Lithuania, Georgia, Armenia, Azerbaijan, Kazakhstan, Kyrgyzstan, Tajikistan, Turkmenistan and Uzbekistan. Archives are chosen by the event's historical jurisdiction and current record custodian; a regional example does not replace local research.
  6. The skill's instructions are written in Russian, but **the agent talks to you in your language**: English, Ukrainian, Russian, Polish, German and so on. It quotes sources in their original spelling with a translation, and builds search queries in the languages of the records.
  7. ---
  8. ## What it does
  9. - **Case intake and scope.** One research question, known facts, who may be alive, what is off-limits.
  10. - **Reproducible registers.** Persons, artifacts, claims, relationships and a full search log (CSV), plus a final report template.
  11. - **Historical jurisdiction model.** It resolves every event to the state, province, district, parish or civil registry *as of the event date*, not today's map.
  12. - **Name-variant matrices.** Pre-reform Russian, Ukrainian, Polish, Romanian, German and Yiddish forms, patronymics, maiden names and transliterations.
  13. - **Source strategy.** Originals first, then official catalogs, indexes, published document collections, and only then trees and forums as leads.
  14. - **Evidence protocol.** Claims get explainable statuses, not percentages: `hypothesis`, `single-source`, `corroborated`, `strongly-corroborated`, `contradicted`, `unresolved`. Copies and mirrors of one record share an `independence_group`, so they never count as independent proof.
  15. - **Identity resolution.** Namesakes stay separate `person_id`s until distinguishing evidence appears: house number, parents, godparents, exact birth date or military unit.
  16. - **Audit script.** It checks referential integrity and flags weak corroboration before you write conclusions. An independence group counts only when a cited artifact belongs to it, so corroboration cannot be declared into existence. It also checks IDs and statuses in the working Markdown report, if present; the agent checks the delivered HTML against the registers. A summary shows what is still uncorroborated or marked illegible.
  17. - **Institutional requests.** Draft and, when authorized, send focused requests to archives, libraries, universities and museums using available email or official web tools. If needed, offer a supported mail integration or a ready-to-send letter. Record the outcome, avoid duplicate sends and treat replies as evidence. See [correspondence guidance](references/correspondence.md).
  18. - **Archive request form.** An anonymized [CANO vital-record request template](assets/cano-vital-record-request.template.docx) preserves the supplied form's layout for an editable case copy. Verify the archive's current form and submission requirements before use.
  19. - **Government services.** Choose an official civil-registration or archive request route, checking eligibility and how the result is delivered ([government portals](references/government-portals.md)).
  20. - **Final report.** A complete HTML report is the default deliverable, with each relationship laid out edge by edge, contradictions, failed searches and concrete next steps. PDF is an optional export only when you explicitly request it.
  21. - **Targeted indexed-record research.** Find relevant FamilySearch books by place or DGS through an existing lawful browser session, view specific records, and retain only evidence fragments permitted by the source. Local helpers search relatives, witnesses and name variants in saved fragments, preserving their context and file checksums. [Workflow and coverage limits](references/familysearch-indexes.md).
  22. - **Connected FamilySearch MCP.** Use a connected server for structured searches, profiles, relatives and sources, and authorized tree changes with explicit scope and read-back. Keep indexed search separate from unindexed scan reading, and check the connector's actual browser, privacy and write capabilities. [Workflow and access limits](references/familysearch-mcp.md).
  23. - **WWI source search.** Search GWAR reports, hospital, award and prisoner-of-war records by person or locality, compare settlement spellings across saved cards to decode a distorted place name, then locate the source image. [Workflow](references/ww1-search.md). Both helpers feed the existing artifact register and search log; they do not establish identities or kinship automatically.
  24. Release history: [changelog](references/changelog.md).
  25. ## Install
  26. With Node.js installed, you can use the optional [Skills CLI](https://github.com/vercel-labs/skills):
  27. ```bash
  28. npx skills add https://github.com/DenisSergeevitch/ex-ussr-kinship-research
  29. ```
  30. The CLI lets you choose your agent and installs into the current project by default; add `-g` for a personal installation across projects. See its documentation for current Node.js requirements.
  31. Alternatively, clone the repository directly into your agent's skills folder:
  32. ```bash
  33. # Codex
  34. git clone https://github.com/DenisSergeevitch/ex-ussr-kinship-research ~/.codex/skills/ex-ussr-kinship-research
  35. # Claude Code (personal skills)
  36. git clone https://github.com/DenisSergeevitch/ex-ussr-kinship-research ~/.claude/skills/ex-ussr-kinship-research
  37. ```
  38. For a single project, put the folder in `.claude/skills/` inside the repository. Most scripts need only Python 3 and the standard library. The optional `scan_montage.py` helper needs Pillow; `build_pdf.py` needs a Chromium-based browser.
  39. ## Use
  40. Describe the family question. The agent works from available information and continues while questions or access requests await a reply. For example:
  41. - *"My great-grandfather was exiled to Kazakhstan in the 1930s. Help me find his parents in church records."*
  42. - *"Here are scans of a marriage certificate and a soldier card. Check whether they are the same person and build the evidence chain."*
  43. - *"Find the parish and the right FamilySearch film for a village in Podolia in the 1890s and read the births for the surname X."*
  44. Keep private case data outside the skill's Git checkout. From the skill folder:
  45. ```bash
  46. python scripts/init_case.py --case-dir ~/kinship-cases/my-case --research-question "Who were Maria's parents?" --subject-label "Maria"
  47. python scripts/hash_artifact.py ~/kinship-cases/my-case/scans/marriage-1902.jpg # SHA-256 for every saved artifact
  48. python scripts/audit_evidence.py --case-dir ~/kinship-cases/my-case # check registers before the final report
  49. ```
  50. `init_case.py` refuses to create a case inside the skill folder, including with
  51. `--force`. Git ignores common legacy case-folder names as an additional safeguard;
  52. check staged files before contributing, especially if moving an existing case.
  53. The agent prepares a complete HTML report, for example `my-case/report.html`, using `assets/report.template.html` or its existing tools. The default editorial layout puts a family tree in the header, with relationship evidence one click away, readable multilingual system-font fallbacks, and layouts for small screens and print. The tree follows the available evidence; missing relatives do not delay the report. Open it directly in a browser or share the HTML with its local images. Short answers may remain text or Markdown; an explicitly requested format takes precedence. A family-facing report does not imply PDF.
  54. Only when you explicitly request PDF, the agent can export the same HTML:
  55. ```bash
  56. python scripts/build_pdf.py --html ~/kinship-cases/my-case/report.html --out ~/kinship-cases/my-case/report.pdf
  57. ```
  58. This optional export needs Chrome, Chromium or Edge installed (or `CHROME_PATH`). With `--png-dir` it also renders pages to PNG for review if `pypdfium2` is available. HTML delivery needs no PDF renderer.
  59. For PDF export, use static HTML with local or embedded images. The exporter rejects active HTML and network image sources; source links remain clickable. A failed render preserves any existing output PDF.
  60. ## Family trees in GEDCOM
  61. [GEDCOM](https://gedcom.io/specs/) is a standard format for exchanging genealogical data between programs. When you ask the agent to build or export a tree, it prepares a local `.ged` file with source citations and evidence notes. The default is GEDCOM 5.5.1 in UTF-8 for compatibility; use another supported version, such as GEDCOM 7, when you or your chosen program require it.
  62. An existing tree is research input and a set of leads, not proof of its relationships. The agent preserves the original file and keeps unresolved claims, unsupported details, evidence registers and the search log in the case folder. Exports follow the evaluated evidence and do not overwrite your files.
  63. You choose the software. Installing tree applications, configuring MCP connections and automatically synchronizing external trees are outside the skill's scope. See [the GEDCOM workflow](references/gedcom.md).
  64. ## Repository layout
  65. ```
  66. SKILL.md main instructions (workflow, hard rules, language policy)
  67. references/
  68. source-strategy.md source hierarchy, query patterns, catalogs, archive requests
  69. correspondence.md recipients, mail integration, authorized sending and replies
  70. government-portals.md civil-registration services and request delivery routes
  71. evidence-protocol.md artifact assessment, statuses, identity resolution, conflicts
  72. ex-ussr-locale-guide.md jurisdictions, name variants, calendars, record types by period
  73. browser-and-captcha.md browsing, sign-in, one CAPTCHA attempt and hand-off, rate limits
  74. privacy-and-safety.md living people, minors, DNA, sensitive findings
  75. seed-sources.md curated starting resources with reliability classes
  76. field-lessons.md practical lessons from a real case
  77. changelog.md release history
  78. photo-search.md finding, identifying, dating and storing photos
  79. habsburg-galicia-bukovina.md Galicia and Bukovina under the Habsburgs and after
  80. chechnya-deportation.md Chechen families: 1944 deportation, special settlement, names and renamed villages
  81. germany-forced-labour.md Forced labourers in Germany 1941-1945: Arolsen Archives and German civil registers
  82. bessarabia-moldova.md Bessarabia, Moldova, MASSR and the Dniester borderland
  83. familysearch-indexes.md targeted browser research, permitted local snapshots and coverage
  84. familysearch-mcp.md connected tools, structured reads, scoped writes and verification
  85. ww1-search.md GWAR WWI person/locality search and source-image locators
  86. gedcom.md portable family-tree exports with sources and evidence notes
  87. assets/ case intake, CSV registers, final report template,
  88. photos README template, research-state template, HTML report template (report.template.html)
  89. scripts/ init_case.py, hash_artifact.py, audit_evidence.py, build_pdf.py
  90. familysearch.py, gwar.py, register_search.py, scan_montage.py (needs Pillow)
  91. check_gedcom.py (optional GEDCOM lint), and shared local analysis modules
  92. evals/discovery-and-logic.yaml trigger and reasoning test cases
  93. tests/ unit tests (python3 -m unittest discover -s tests)
  94. ```
  95. ## Responsible use
  96. - **Family history, not surveillance.** The skill refuses to look up current addresses, phones or accounts of living people, and it minimizes their data in reports.
  97. - **Access checks.** The agent may try an actual CAPTCHA once through normal controls in its internal browser when supported and allowed. If user action is needed, it opens the relevant tab when possible and provides the URL and required action; sign-ins are done by the user. No external solvers, protection bypass, paywall, geo-block or rate-limit evasion, or leaked databases. See [browser guidance](references/browser-and-captcha.md).
  98. - **No uploads of your documents or DNA data** to third-party services without your explicit consent.
  99. - **Sensitive findings** (deportation, repression, adoption, DNA surprises) are reported neutrally and only as far as the question requires.
  100. - **Authorized correspondence.** The skill can send institutional requests through available tools when the user has authorized them; it does not ask again for an already authorized send. Connecting a mailbox alone does not authorize sending, attachments or paid services. Verify the current official contact and procedure, and keep credentials and private case correspondence outside the skill repository.
  101. ## Contributing
  102. New sources are welcome in `references/seed-sources.md`. Record verified owner, jurisdiction, collection, provenance, IDs, access, restrictions and check date where known; mark gaps instead of guessing. Keep personal data out of examples.
  103. When a readable search log is present, the audit summary lists artifact IDs without a search-log reference. Use the list to check unlinked finds. User-supplied material may appear there without any action needed.
  104. Source-search helpers use Python's standard library and the existing case registers. Run `python3 -m unittest discover -s tests` to check local parsing, GWAR checkpoints, access failures, unresolved coverage and evidence registration against synthetic data. FamilySearch discovery and targeted viewing use the existing lawful browser session; its Python helpers analyze saved fragments. Keep private research files outside this checkout.
  105. ## License
  106. [MIT](LICENSE) © 2026 Denis Shiryaev.
  107. ---
  108. Maintained by Denis Shiryaev ([@DenisSergeevitch](https://github.com/DenisSergeevitch)).
  109. Special thanks to [Viktor](https://tiulp.in/) for the conversations about using Claude for family-history research that helped inspire this skill.
scripts/gwar.py · Bundled script · 347 lines
  1. #!/usr/bin/env python3
  2. """Find WWI source records and locality clusters without inferring kinship."""
  3. from __future__ import annotations
  4. import argparse
  5. import difflib
  6. import re
  7. import ssl
  8. import sys
  9. import unicodedata
  10. import xml.etree.ElementTree as ET
  11. from pathlib import Path
  12. sys.path.insert(0, str(Path(__file__).resolve().parent)) # `python -I` omits the script folder
  13. from research_common import (configure_utf8_stdio, SourceClient, SourceError, fingerprint, outside_skill, output_json,
  14. read_json, save_json, state_lock, timestamp)
  15. BASE = "https://gwar.mil.ru"
  16. KINDS = {"reports": "chelovek_donesenie", "hospitals": "chelovek_gospital", "awards": "chelovek_nagrazhdenie", "pows": "chelovek_plen"}
  17. def source_client():
  18. # Extra certificates apply only to this client, never to the system trust store.
  19. context = ssl.create_default_context()
  20. for name in ("russian_trusted_root_ca.pem", "russian_trusted_sub_ca.pem"):
  21. path = Path(__file__).resolve().parent / "ca" / name
  22. if not path.is_file():
  23. raise SourceError("Отсутствует сертификат GWAR из scripts/ca; проверка TLS не отключается.")
  24. context.load_verify_locations(cafile=str(path))
  25. return SourceClient(BASE, context=context, referer=BASE + "/heroes/")
  26. def query_body(fields, offset, size, entities, builder="Heroes"):
  27. return {"indices": ["gwar"], "entities": entities, "queryFields": fields,
  28. "filterFields": {}, "facetField": None, "from": offset, "size": size, "builderType": builder}
  29. def fetch_page(client, fields, offset, size, entities, builder="Heroes"):
  30. data = client.request("/gt_data/?builder=" + builder, query_body(fields, offset, size, entities, builder))
  31. if isinstance(data, dict) and "response" in data:
  32. data = data["response"]
  33. box = data.get("hits") if isinstance(data, dict) else None
  34. if not isinstance(box, dict) or not isinstance(box.get("hits"), list):
  35. raise SourceError("GWAR: неожиданный формат выдачи.")
  36. total = box.get("total")
  37. if isinstance(total, dict):
  38. if total.get("relation", "eq") != "eq":
  39. raise SourceError("GWAR не сообщил точное число результатов; полнота неизвестна.")
  40. total = total.get("value")
  41. if type(total) is not int or total < 0:
  42. raise SourceError("GWAR: отсутствует точный счётчик записей.")
  43. for hit in box["hits"]:
  44. if not isinstance(hit, dict) or not hit.get("_id") or not isinstance(hit.get("_source"), dict):
  45. raise SourceError("GWAR: карточка без ID или исходных полей.")
  46. return box["hits"], total
  47. def hit_key(hit):
  48. return "|".join(str(hit.get(field, "")) for field in ("_index", "_type", "_id"))
  49. def collect(client, fields, entities, limit, checkpoint=None):
  50. identity = {"source": "gwar", "query": fields, "entities": entities}
  51. state = {**identity, "fingerprint": fingerprint(identity), "total": None, "hits": [],
  52. "next_offset": 0, "started_at": timestamp(), "captured_at": timestamp(), "coverage": {"complete": False}}
  53. if checkpoint and Path(checkpoint).exists():
  54. state = read_json(checkpoint)
  55. if state.get("fingerprint") != fingerprint(identity):
  56. raise SourceError("Сохранённая выдача GWAR относится к другому запросу.")
  57. if not isinstance(state.get("hits"), list) or type(state.get("next_offset")) is not int:
  58. raise SourceError("Некорректное состояние выдачи GWAR.")
  59. if limit < len(state["hits"]):
  60. raise SourceError("Лимит меньше уже сохранённой выдачи; выберите другой файл или прежний лимит.")
  61. hits = {hit_key(hit): hit for hit in state["hits"]}
  62. if len(hits) != len(state["hits"]):
  63. raise SourceError("В контрольной точке GWAR есть повторные ID.")
  64. blocked, incomplete_reason = None, ""
  65. try:
  66. if state["total"] is None or state["next_offset"] < state["total"]:
  67. client.request("/heroes/", as_json=False)
  68. while len(hits) < limit and (state["total"] is None or state["next_offset"] < state["total"]):
  69. requested_size = min(1000, limit - len(hits))
  70. page, total = fetch_page(client, fields, state["next_offset"], requested_size, entities)
  71. if len(page) > requested_size:
  72. raise SourceError("GWAR вернул больше запрошенного объёма; проверьте формат API.")
  73. if state["total"] is not None and state["total"] != total:
  74. raise SourceError("Число результатов GWAR изменилось; проверьте выдачу новым запросом.")
  75. state["total"] = total
  76. state["captured_at"] = timestamp()
  77. previous_count = len(hits)
  78. for hit in page:
  79. key = hit_key(hit)
  80. if key in hits and hits[key] != hit:
  81. raise SourceError("Содержимое карточки GWAR изменилось во время получения выдачи.")
  82. hits[key] = hit
  83. state["next_offset"] += len(page)
  84. state["hits"] = list(hits.values())
  85. if not page or len(hits) == previous_count:
  86. if len(hits) < total:
  87. incomplete_reason = "empty-or-repeated-page-before-total"
  88. break
  89. if checkpoint:
  90. save_json(checkpoint, state)
  91. except SourceError as exc:
  92. blocked = {"status": exc.status, "message": str(exc)}
  93. finally:
  94. complete = state["total"] is not None and len(hits) == state["total"] and not blocked and not incomplete_reason
  95. state.update({"hits": list(hits.values()), "updated_at": timestamp(), "blocked": blocked,
  96. "coverage": {"complete": complete, "retrieved_records": len(hits), "reported_total": state["total"],
  97. "limit": limit, "reason": incomplete_reason or (("limit-reached" if len(hits) >= limit else "source-window-incomplete") if not complete and not blocked else ""),
  98. "scope": "returned-source-records-not-population-census"}})
  99. if checkpoint:
  100. save_json(checkpoint, state)
  101. return state
  102. def parse_scan(xml):
  103. xml = str(xml or "")
  104. image = re.search(r"[A-Za-z0-9_\-/]+\.(?:jpe?g|png|tiff?)", xml, flags=re.IGNORECASE)
  105. path = image.group(0) if image else None
  106. zones = []
  107. try:
  108. root = ET.fromstring(xml)
  109. for element in root.iter():
  110. if element.tag.rsplit("}", 1)[-1] == "s":
  111. zones.append(dict(element.attrib))
  112. except ET.ParseError:
  113. # Some source payloads are XML fragments rather than a full document.
  114. for match in re.finditer(r"<s\s+([^>]+?)/?>", xml):
  115. zones.append(dict(re.findall(r'([\w:]+)\s*=\s*"([^"]*)"', match.group(1))))
  116. return {"image_path": path, "image_url": BASE + "/cdn/imagesfww/" + path.lstrip("/") if path else None,
  117. "zones": zones, "raw": xml}
  118. def pages(client, page_ids):
  119. client.request("/heroes/", as_json=False)
  120. result = []
  121. for page_id in dict.fromkeys(page_ids):
  122. hits, total = fetch_page(client, {"linkedPages": [int(page_id)]}, 0, 100, ["stranitsa"], "HeroesStranitsa")
  123. result.append({"pages_id": page_id, "total": total, "complete": len(hits) == total,
  124. "records": [{"id": hit["_id"], "source": hit["_source"],
  125. **parse_scan(hit["_source"].get("obraz_s_oblastyami", ""))} for hit in hits]})
  126. return {"source": "gwar-pages", "captured_at": timestamp(), "pages": result,
  127. "coverage": {"complete": all(item["complete"] for item in result), "scope": "selected-pages"}}
  128. PLACE_UNITS = (("gubernia", re.compile(r"\b(?:губ(?:ерния)?|обл(?:асть)?)\.?$")),
  129. ("uezd", re.compile(r"\b(?:уезд|у)\.?$")),
  130. ("volost", re.compile(r"\bвол(?:ость)?\.?$")))
  131. SETTLEMENT_TYPE = re.compile(r"^(?:селение|село|деревня|дер|хутор|местечко|колония|слобода|н\.\s?п|с|д|х|м|к|сл)\.?\s+")
  132. def place_parts(source):
  133. """Split the card's place into units and the settlement, keeping each string as written."""
  134. parts = {unit: str(source.get("birth_place_" + unit) or "").strip() for unit, _ in PLACE_UNITS}
  135. rest = []
  136. for token in (item.strip() for item in str(source.get("birth_place") or "").split(",")):
  137. if not token:
  138. continue
  139. unit = next((name for name, pattern in PLACE_UNITS if pattern.search(token.lower())), None)
  140. if unit and not parts[unit]:
  141. parts[unit] = token
  142. elif not unit:
  143. rest.append(token)
  144. parts["settlement"] = ", ".join(rest)
  145. return parts
  146. def name_key(name):
  147. return "".join(char for char in unicodedata.normalize("NFC", name).lower().replace("ё", "е")
  148. if char.isalpha())
  149. def place_key(name):
  150. name = SETTLEMENT_TYPE.sub("", name.lower().replace("ё", "е").strip())
  151. return re.sub(r"[^a-zа-яіїєґăâîșțş]", "", name)
  152. def similarity(left, right, key=place_key, vowels="аеиоуыэюяіїєйăâîьъ"):
  153. left, right = key(left), key(right)
  154. if not left or not right:
  155. return 0.0
  156. skeleton = ["".join(char for char in value if char not in vowels) for value in (left, right)]
  157. scores = [difflib.SequenceMatcher(None, left, right).ratio()]
  158. if all(skeleton):
  159. scores.append(difflib.SequenceMatcher(None, *skeleton).ratio())
  160. return round(max(scores), 2)
  161. def saved_cards(states):
  162. """Merge cards of saved search/volost files by full key; refuse conflicting snapshots."""
  163. cards, inputs = {}, []
  164. for name, state in states:
  165. if (not isinstance(state, dict) or state.get("source", "gwar") != "gwar"
  166. or not isinstance(state.get("hits"), list)):
  167. raise SourceError(f"{name}: это не выдача gwar.py search/volost.")
  168. coverage = state.get("coverage")
  169. if not isinstance(coverage, dict):
  170. raise SourceError(f"{name}: отсутствуют сведения о полноте выдачи GWAR.")
  171. inputs.append({"file": name, "query": state.get("query"),
  172. "complete": coverage.get("complete") is True})
  173. for hit in state["hits"]:
  174. if (not isinstance(hit, dict) or not hit.get("_id")
  175. or not isinstance(hit.get("_source"), dict)):
  176. raise SourceError(f"{name}: карточка GWAR без ID или исходных полей.")
  177. key = hit_key(hit)
  178. if key in cards and cards[key]["_source"] != hit["_source"]:
  179. raise SourceError(f"{name}: версии одной карточки GWAR различаются; сравните исходные файлы.")
  180. cards.setdefault(key, hit)
  181. if not inputs:
  182. raise SourceError("Укажите хотя бы одну сохранённую выдачу GWAR.")
  183. return cards, inputs
  184. def places(states, target=None):
  185. """Group settlement spellings of saved cards by gubernia, uezd and volost; no network access."""
  186. cards, inputs = saved_cards(states)
  187. groups = {}
  188. for hit in cards.values():
  189. parts = place_parts(hit.get("_source") or {})
  190. group = groups.setdefault((parts["gubernia"], parts["uezd"], parts["volost"]), {})
  191. entry = group.setdefault(parts["settlement"], {"as_written": parts["settlement"], "cards": 0, "card_ids": [], "card_keys": []})
  192. entry["cards"] += 1
  193. entry["card_ids"].append(hit["_id"])
  194. entry["card_keys"].append(hit_key(hit))
  195. result = []
  196. for (gubernia, uezd, volost), settlements in groups.items():
  197. items = list(settlements.values())
  198. for item in items:
  199. if target:
  200. item["similarity"] = similarity(target, item["as_written"])
  201. items.sort(key=lambda item: (-item.get("similarity", 0), -item["cards"], item["as_written"]))
  202. result.append({"gubernia": gubernia, "uezd": uezd, "volost": volost, "settlements": items})
  203. result.sort(key=lambda group: (-max((item.get("similarity", 0) for item in group["settlements"]), default=0),
  204. group["gubernia"], group["uezd"], group["volost"]))
  205. return {"source": "gwar-places", "captured_at": timestamp(), "target": target, "inputs": inputs,
  206. "cards": len(cards), "groups": result,
  207. "coverage": {"complete": all(item["complete"] for item in inputs),
  208. "scope": "spellings-in-saved-cards-not-settlement-list"}}
  209. def surnames(states, target=None):
  210. """Group surname spellings of saved cards and rank them against a target; no network access."""
  211. cards, inputs = saved_cards(states)
  212. spellings = {}
  213. fields = ("first_name", "middle_name", "birth_place", "birth_place_volost",
  214. "birth_place_uezd", "birth_place_gubernia")
  215. for key, hit in cards.items():
  216. source = hit["_source"]
  217. written = str(source.get("last_name") or "")
  218. card = {"card_id": hit["_id"], "card_key": key}
  219. card.update({field: source[field] for field in fields if source.get(field)})
  220. spellings.setdefault(written if written.strip() else "", []).append(card)
  221. items = [{"as_written": written, "cards": len(rows), "card_context": rows}
  222. for written, rows in spellings.items()]
  223. target_key = name_key(target) if target else ""
  224. if target_key:
  225. for item in items:
  226. item["similarity"] = similarity(target, item["as_written"], key=name_key,
  227. vowels="аеиоуыэюяіїєйăâîьъaeiouy")
  228. items.sort(key=lambda item: (not item["as_written"], -item.get("similarity", 0),
  229. bool(target_key) and name_key(item["as_written"]) != target_key,
  230. -item["cards"], item["as_written"]))
  231. return {"source": "gwar-surnames", "captured_at": timestamp(), "target": target, "inputs": inputs,
  232. "cards": len(cards), "surnames": items,
  233. "coverage": {"complete": all(item["complete"] for item in inputs),
  234. "scope": "surname-spellings-in-saved-cards-not-kinship"}}
  235. def positive(value):
  236. number = int(value)
  237. if number < 1:
  238. raise argparse.ArgumentTypeError("Нужно положительное число.")
  239. return number
  240. def parser():
  241. root = argparse.ArgumentParser(description="Документы Первой мировой: поиск человека и сбор по местности.")
  242. commands = root.add_subparsers(dest="command", required=True)
  243. search = commands.add_parser("search", help="Поиск по имени, месту или части")
  244. for flag in ("surname", "given", "patronymic", "event-place", "regiment", "birth-place", "gubernia"):
  245. help_text = ("Населённый пункт в поле birth_place сайта (место жительства / призыва; не доказанное место рождения)"
  246. if flag == "birth-place" else None)
  247. search.add_argument("--" + flag, help=help_text)
  248. volost = commands.add_parser("volost", help="Собрать найденные записи по волости и губернии")
  249. volost.add_argument("--volost", required=True, help="Волость в поле birth_place_volost сайта")
  250. volost.add_argument("--gubernia", required=True)
  251. for command in (search, volost):
  252. command.add_argument("--kind", nargs="+", choices=("all", *KINDS), default=["all"])
  253. command.add_argument("--max-records", type=positive, default=1000)
  254. command.add_argument("--out", required=True, help="JSON вне папки навыка; также контрольная точка")
  255. spellings = commands.add_parser("places", help="Сравнить написания местностей в сохранённых выдачах (без сети)")
  256. spellings.add_argument("--input", nargs="+", required=True, help="JSON-выдачи search/volost")
  257. spellings.add_argument("--target", help="Неопознанное название, с которым сравнить написания")
  258. spellings.add_argument("--out", help="JSON вне папки навыка; без него вывод в консоль")
  259. names = commands.add_parser("surnames", help="Сравнить написания фамилий в сохранённых выдачах (без сети)")
  260. names.add_argument("--input", nargs="+", required=True, help="JSON-выдачи search/volost")
  261. names.add_argument("--target", help="Фамилия, с которой сравнить написания")
  262. names.add_argument("--out", help="JSON вне папки навыка; без него вывод в консоль")
  263. page = commands.add_parser("page", help="Найти скан и координаты строк по pages_id")
  264. page.add_argument("--pages", nargs="+", type=positive, required=True)
  265. page.add_argument("--out", required=True)
  266. return root
  267. def main(argv=None):
  268. args = parser().parse_args(argv)
  269. try:
  270. if args.command in ("places", "surnames"):
  271. path = outside_skill(args.out) if args.out else None
  272. if path is not None:
  273. for name in args.input:
  274. source = Path(name).expanduser().resolve()
  275. if path == source or (path.exists() and source.exists() and path.samefile(source)):
  276. raise SourceError("Выходной файл не должен заменять исходную выдачу GWAR.")
  277. compare = places if args.command == "places" else surnames
  278. result = compare([(name, read_json(name)) for name in args.input], args.target)
  279. output_json(result, path)
  280. return 0 if result["coverage"]["complete"] else 1
  281. path = outside_skill(args.out)
  282. if args.command == "page":
  283. result = pages(source_client(), args.pages)
  284. output_json(result, path)
  285. else:
  286. if args.command == "volost":
  287. fields = {"birth_place_volost": args.volost, "birth_place_gubernia": args.gubernia}
  288. else:
  289. mapping = {"surname": "last_name", "given": "first_name", "patronymic": "middle_name",
  290. "event_place": "event_place", "regiment": "military_unit_name",
  291. "birth_place": "birth_place", "gubernia": "birth_place_gubernia"}
  292. fields = {field: getattr(args, key) for key, field in mapping.items() if getattr(args, key)}
  293. if not fields:
  294. raise SourceError("Укажите имя, местность или воинскую часть.")
  295. kinds = list(KINDS) if "all" in args.kind else list(dict.fromkeys(args.kind))
  296. with state_lock(str(path) + ".lock"):
  297. result = collect(source_client(), fields, [KINDS[kind] for kind in kinds], args.max_records, path)
  298. return 0 if result["coverage"]["complete"] else 1
  299. except (SourceError, OSError, ValueError, TypeError, KeyError) as exc:
  300. print("Ошибка: " + (str(exc) if isinstance(exc, SourceError) else "Некорректный файл или ошибка локального ввода/вывода."), file=sys.stderr)
  301. return 1
  302. if __name__ == "__main__":
  303. configure_utf8_stdio()
  304. raise SystemExit(main())

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.