DenisSergeevitch/ex-ussr-kinship-research · 上手攻略

  • 仓库：DenisSergeevitch/ex-ussr-kinship-research
  • 链接：https://github.com/DenisSergeevitch/ex-ussr-kinship-research
  • 分类：agent / genealogy / skill
  • 作者：spark
  • 更新：2026-10-29

0. 自检清单（三证）

  • [x] GitHub URL（已 fetch README + SKILL.md raw 正文）
  • [x] README 子模块 anchor（scripts/、references/、assets/、evals/、tests/ 五类目录结构已在 README 与 SKILL.md 中逐项核对）
  • [x] 论文/机构 anchor —— 本项目没有论文 venue；替代锚点为 SKILL.md front-matter 的 metadata.version: "1.18.0"、language: "ru"、region: "ex-USSR"，以及 MIT 许可与作者署名（Denis Shiryaev / @DenisSergeevitch）。它不是论文仓库，不适用顶会 venue 字段。
  • [x] 版本号浮动提示：README 未标注具体 release tag，SKILL.md 声明 version 1.18.0；references/changelog.md 是唯一权威版本源（本文写作时未逐条读取 ⚠️）

1. 是什么

这是一个给 AI Agent 用的"证据优先"家谱研究 Skill，不是软件包、不是 Web 服务，也不是数据集。它以 Agent Skill 的标准形态发布（一个 SKILL.md + references/ 参考手册 + scripts/ 脚本 + assets/ 模板），可直接装进 Codex、Claude Code 等 Agent Skills 运行时，也可通过 MCP 接入 Arca 家谱应用或 FamilySearch。

定位非常具体：把 Agent 变成一个谨慎的前苏联 / 苏联 / 俄罗斯帝国地区的家族史研究者。核心工作对象是教会簿（метрические книги）、民事登记（ЗАГС）、军人卡片、驱逐与镇压记录，以及大量未编目的档案扫描件。

作者是 Denis Shiryaev（GitHub: @DenisSergeevitch），约 1148 stars（仓库卡显示周增 +1713，典型的短期爆发式增长）。MIT 许可，语言主体为 Python（脚本）+ Markdown（指令）。

它和普通"家谱软件"的区别：它不产出结论，它产出证据链。每条关系都必须能追溯到一个具体的 artifact_id，而每条断言的状态由 audit_evidence.py 校验，不允许"声明式"地凭空升级。

2. 解决什么问题

做东欧/前苏联家谱研究的人，卡在四个具体的痛点上，而这个 Skill 就是逐个针对：

  1. 地名与管辖权错位。1937 年的某个村子属于哪个省、哪个县、哪个教区，今天看地图完全看不出来。Skill 强制"按事件发生日期解析历史管辖权"，而不是用今天的国界去检索。
  2. 人名变体爆炸。改革前的俄语拼写、乌克兰语/波兰语/罗马尼亚语/德语/意第绪语写法、父名缩略形、女性婚前姓与婚后姓、各种俄化改名——同一个祖先在档案里有十几种拼法。Skill 用"姓名变体矩阵"系统化处理。
  3. 同名不同人。Skill 强制在出现区分证据（门牌号、父母、教父母、精确出生日期、部队番号）之前，把同名者记成不同的 person_id，不合并。
  4. 假独立证据。同一份记录的复印件、镜像站、索引条目被当成三个来源互相"印证"，这是家谱研究里最常见的自欺。Skill 用 independence_group 强制把同一记录的多个副本归为一组，脚本会检查"被引用的 artifact 是否真的属于该组"——也就是说互证不能被声明出来，只能被证明出来。

另一个容易被忽略但很关键的设计：证据状态是离散标签，不是置信度百分比。状态包括 hypothesis（假设）、single-source（单一来源）、corroborated（已互证）、strongly-corroborated（强互证）、contradicted（矛盾）、unresolved（未决）。这跟 LLM 常见的"我有 85% 的信心是张三"是相反的设计哲学。

3. 快速安装

方式 A：Skills CLI（推荐，需要 Node.js）

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

CLI 会让你选择目标 Agent，默认安装到当前项目；加 -g 则装到个人目录（跨项目可用）。Node.js 的具体版本要求请查 vercel-labs/skills 的官方文档（README 原文："See its documentation for current Node.js requirements"，未硬编码版本号 ⚠️）。

方式 B：手动 clone 到 Agent 的 skills 目录

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

# Claude Code（个人级 skills）
git clone https://github.com/DenisSergeevitch/ex-ussr-kinship-research ~/.claude/skills/ex-ussr-kinship-research

单个项目用的话，把文件夹放进项目里的 .claude/skills/ 即可。

依赖要求

  • 脚本只需要 Python 3 + 标准库，不需要 pip 装第三方包。
  • build_pdf.py 额外需要一个 Chromium 内核浏览器（Chrome / Chromium / Edge），也可用 CHROME_PATH 环境变量指定路径。
  • build_pdf.py 的 --png-dir 参数还需要 pypdfium2（可选）。

初始化一个案子

cd ~/.claude/skills/ex-ussr-kinship-research

python scripts/init_case.py \
  --case-dir ~/kinship-cases/my-case \
  --research-question "Who were Maria's parents?" \
  --subject-label "Maria"

# 给每个保存下来的材料算校验和
python scripts/hash_artifact.py ~/kinship-cases/my-case/scans/marriage-1902.jpg

# 写结论前先审计证据链
python scripts/audit_evidence.py --case-dir ~/kinship-cases/my-case

# 生成可读 PDF 报告
python scripts/build_pdf.py \
  --html ~/kinship-cases/my-case/pdf-source/report.html \
  --out ~/kinship-cases/my-case/report.pdf

跑一遍自带单元测试：

python3 -m unittest discover -s tests

4. 核心用法

4.1 初始化后会生成什么

init_case.py 会铺出一整套"可复现登记表"（文件名来自 SKILL.md 步骤 2，与 README 的 assets/ 描述一致）：

文件 内容
case-intake.yaml 研究问题、已知事实、授权与边界、隐私约束
person-register.csv 候选人物（同名者各自独立 person_id）
artifact-register.csv 每份文档/网页/扫描件，含出处、可读性、independence_group
claims-register.csv 可检验的断言及其来源、矛盾
relationship-register.csv 人物之间的关系假设
search-log.csv 完整检索日志：查询、筛选、失败、CAPTCHA、下一步
research-state.md 剩余检查项与阻塞点（工作队列）
final-report.md 最终报告骨架
photos/ + README.md 找到的历史照片及说明

这套 CSV + YAML 的组合是它的核心价值：研究过程本身就是可审计的产物，而不是一段对话记录。

4.2 怎么跟 Agent 提需求

不需要你会写检索式，直接用自然语言描述家族问题即可。README 给的三个例子：

"My great-grandfather was exiled to Kazakhstan in the 1930s. Help me find his parents in church records."

"Here are scans of a marriage certificate and a soldier card. Check whether they are the same person and build the evidence chain."

"Find the parish and the right FamilySearch film for a village in Podolia in the 1890s and read the births for the surname X."

Skill 的默认行为是长时自主研究：不会每个阶段都回来问"要继续吗"，而是自己推进直到用例被覆盖、可访问路由耗尽、用户明确叫停或触及环境限额。

4.3 语言策略（一个容易被误解的设计）

Skill 指令本体是俄语写的，但 Agent 对你的回复语言跟随你最后一条消息的语言（英文、乌克兰语、俄语、波兰语、德语等）。同时：

  • 来源引用保留原始拼写并附翻译；
  • 检索式用来源的语言构建（俄语、乌克兰语、波兰语、罗马尼亚语、德语、意第绪语），不是用你对话的语言；
  • CSV 的列名、ID 字段（person_id/claim_id/artifact_id）和状态词（single-source/corroborated）不翻译。

这个设计对中文用户意味着：你用中文提问，它用中文回答，但去 FamilySearch 或档案目录检索时会自动切到俄语/波兰语等原始语言。

4.4 区域专门参考文档

references/ 下有若干专题手册，按需读即可（不需要一次全读）：

  • habsburg-galicia-bukovina.md — 哈布斯堡统治下的加利西亚与布科维纳
  • chechnya-deportation.md — 车臣家庭、1944 年驱逐、特别定居点、改名村庄
  • germany-forced-labour.md — 1941–1945 德国强制劳工、Arolsen 档案、德国民事登记
  • bessarabia-moldova.md — Bessarabia、摩尔多瓦、MASSR、第聂斯特河边境地带
  • field-lessons.md — 真实案例实战经验（含"视觉读取核查"、女性姓氏断链的绕行路线）
  • ex-ussr-locale-guide.md — 管辖权、姓名变体、历法、各时期记录类型
  • ww1-search.md — GWAR 一战人员/地点检索
  • familysearch-indexes.md / familysearch-mcp.md — FamilySearch 索引浏览 / MCP 连接
  • photo-search.md — 照片的查找、鉴定、定年与存储

SKILL.md 里一条值得注意的执行纪律：只有在出现历史边界、语言/书写体系变更、歧义或失真的地名时，才去读 ex-ussr-locale-guide.md；并强调"目录文件的头几行不能代表它的完整覆盖范围"，要通读整个目录再挑相关章节。

5. 典型适用场景

  • 确认两人是否为同一人（同名消歧），并给出可复核的证据链；
  • 追溯被驱逐者/被镇压者的父母，从教会簿与民事登记入手；
  • 为家族分支建立证据化家谱树，每条边都标注状态；
  • 给档案馆/图书馆写询证信（经授权可代发，避免重复发送，回信按证据处理）；
  • 批量整理未编目扫描件：图片落盘、算 SHA-256、登记为 artifact、抽成 claim；
  • 与 Arca 协同：Arca 的树只当"线索"读入，研究确立的结果再带来源与证明标记写回，用户既有记录永不被覆盖。

6. 坑与注意

  1. 案件目录绝对不能放在 skill 仓库内部。init_case.py 会直接拒绝在 skill 目录下建案，即使加 --force 也不行；.gitignore 还额外屏蔽了常见的旧式案卷文件夹名。迁移旧案卷时记得 git status 检查暂存区。
  2. 版本号会漂移，且更新检查是 Agent 的运行时行为。SKILL.md 要求 Agent 在研究开始时查一次上游仓库是否更新，询问用户后由用户 Agent 执行更新。你可能跑着跑着就被提示升级——遇到时先确认当前版本号（metadata.version，写作时为 1.18.0）。
  3. build_pdf.py 的 HTML 沙箱是硬性的：只接受静态 HTML + 本地/内嵌图片，主动拒绝带活动脚本和网络图片源的 HTML（源链接仍可点击）。渲染失败时保留已有输出 PDF，不会破坏旧文件。这既是安全设计也会让某些自定义报告模板失效。
  4. 首次 import 浏览器式工具会很慢：文档明确说某些场景首次启动可能耗时数分钟，只发生一次。
  5. CAPTCHA 只有一次机会，且必须走正常交互路径、用户自己登录。Skill 明确禁止：外部打码服务、绕过保护、绕付费墙、绕地域限制、绕速率限制、使用泄露数据库。遇到 CAPTCHA 应转交用户。
  6. 不要把"没搜到"当成"不存在"（SKILL.md 规则第 10 条）。空结果只说明当前路由没命中，不代表人没存在。
  7. 敏感信息有边界：拒绝查找在世者的现住址、电话、账号；对未成年人、DNA 意外发现、收养信息等中性报告且只报必要范围；未经明确同意不上传你的文档、DNA 数据或照片到第三方服务。
  8. Arca 与 FamilySearch 是"可选连接"，不是必需。没连上时 Skill 依然通过浏览器 + 本地材料工作；连上 MCP 也不等于绕过访问控制，且 FamilySearch MCP 的实际浏览器、隐私与写入能力需要自己核实。
  9. 第三方数据源各有凭据要求：FamilySearch 需要合法登录会话与 DGS 编号知识；GWAR 是卡片索引而非人口普查；Arca 的历史连接在实现 MCP 前也依赖已有数据。这三条都不能自动建立身份或亲缘关系。
  10. 许可与授权的边界：用户授权发信 ≠ 授权发附件或付费服务；接入邮箱 ≠ 授权发送。凭据与私人通信必须留在 skill 仓库之外。
  11. ⚠️ 本文未逐一核验 references/changelog.md 的逐条版本记录，也未运行 python3 -m unittest discover -s tests 实测；命令行参数以 SKILL.md 原文为准，最新参数以你本地的 --help 为准。

7. 与同类对比

维度 本 Skill Arca（家谱应用 + MCP） FamilySearch（外部） 普通家谱网站/论坛
形态 Agent 指令+脚本（MIT） 桌面家谱应用 + MCP 端点 商业机构档案平台 网页应用
核心能力 证据协议 + 检索策略 + 审计脚本 树的存储与可视化 索引与扫描原件 社区互助
亲缘结论可信度 强制状态标签 + 脚本校验互证 依赖用户标注，树链接默认只是假设 提供原件，不做亲缘推断 依赖他人上传，质量参差
覆盖范围 前苏联 15 个加盟共和国 + 俄罗斯帝国，含驱逐/镇压 取决于用户数据 全球教会簿与民事登记 有限
  • 对比 Arca：Arca 是"数据存储与展示层"，本 Skill 是"研究方法层"。两者互补，Skill 专门写了 references/arca.md 说明如何把 Arca 当作输入源与输出目标。
  • 对比 FamilySearch：Skill 不替代 FamilySearch，只是更懂怎么在它上面检索（按地点/DGS 找对 film、按变体名匹配、区分索引检索与未索引扫描阅读两条路径）。
  • 对比 WikiTree / Geneanet / 论坛：那些是"信息聚合 + 社区互助"，缺少独立性与矛盾处理机制；independence_group + audit_evidence.py 在这类平台上无法落地。
  • 对比传统纸质族谱方法论：Skill 本质是把资深族谱学者的作业纪律（原始件优先、管辖权建模、同名分离、证据分级）编码成 Agent 可执行的检查表。学习曲线在"研究方法"而非"软件操作"。

8. 一句话推荐结论

如果你（或你的 Agent）真的要做前苏联/东欧家族史这件需要跨档案、跨语言、跨几十年的事，这是目前少见地把"证据纪律"和"自动化"真正缝在一起的方案，值得装；但它治不了"找不到"——它只保证你找到的每一条都能被追溯，档案本身的缺失、加密与访问限制仍需你自己面对。

同时提醒一句：这个仓库 star 增长极快（仓库卡记录一周 +1713），但 SKILL.md 声明的 version 1.18.0 仍是 beta 性质的高频迭代项目，脚本接口与 references/ 内容都可能在小版本间变化；正式用于严肃家谱研究前，建议先固定一个 commit 或 release tag 再开工。