小说人物分析器
把一篇小说（PDF / DOCX / DOC / TXT / MD，中文或英文）端到端转化为
「全文 MD + 人物关系图谱 + 角色列表 + 故事梗概 + 客观评价」。
核心认知：角色识别无法完全自动——日译人名异写、颜色词碰撞、英文姓氏与普通词同形
（Grey/grey、Frank/frank）都会骗过计数器。因此采用
脚本做确定性工作（提取/召回/计数/渲染/质检）+ AI 做判读工作（确认身份/别名/关系/结局/评价）。
何时使用
- 用户给小说文件，要求「转 md / 分析人物 / 画关系图 / 总结情节 / 查评价」。
- 批量处理多本小说。
- 英文公版书（Project Gutenberg 风排版、全大写标题、页眉书名、维多利亚时期断词）同样走本流程。
脚本一览（scripts/）
| 脚本 | 职责 |
|---|---|
convert_to_md.py |
五格式正文提取；v3 自动页眉/重复折叠/断词还原/英文标题/提取报告 |
scan_names.py |
v3 新增 候选角色名召回（中文「XX说」模式；英文称谓+全名+非句首大写词；可选 spaCy NER） |
count_chars.py |
别名合并精确计数、guard 排除、第一人称统计、英文同形词风险提示 |
build_outputs.py |
总装：--formats html,png,docx,md，孤立节点检查 |
render_graph.py |
Pillow 力导向 PNG（中文字体自动探测），被 build_outputs 调用 |
build_docx.py |
python-docx 报告（图谱在前，梗概/评价/人物表在后），被调用 |
verify_output.py |
v3 新增 交付前质检（E 级阻断 / W 级警告） |
batch.py |
v3 新增 读 books.json 批量提取+候选扫描 |
工作流程（严格按顺序）
1. 提取正文 → Markdown
# PDF（英文公版书通常要跳过书名页；v3 默认自动去页眉/断词/折叠，无需手工噪声）
python scripts/convert_to_md.py INPUT.pdf "中文书名-English Title.md" \
--start-page 2 --book-title "中文书名" --workdir _work
# 其余格式
python scripts/convert_to_md.py INPUT.docx OUT.md --book-title "书名" --workdir _work
python scripts/convert_to_md.py INPUT.doc OUT.md --book-title "书名" # 最佳努力，优先 DOCX
python scripts/convert_to_md.py INPUT.txt OUT.md --workdir _work
python scripts/convert_to_md.py INPUT.md OUT.md
v3 PDF/通用自动处理（可用对应 --no-* 关闭）：
- 跨页重复页眉/页脚：同文本出现在多页顶/底带区即自动剔除（日志列出每条）。
- 近邻重复行折叠：PDF 把标题重复渲染 3-4 次时折叠为 1，折叠明细进报告。
- 英文断词：billiard-\nroom → billiard-room、行内 to- night → to-night（保留 hyphen）。
- 英文标题：全大写短行、罗马数字独立行、居中 "In Which…" 副标题（字号无差异也能识别）。
- 花押字行：如 R. L. S. L. O. 自动剔除。
必做检查：
- 看 stderr 日志与 _work/<stem>.report.json（章节数、字数、断词数、折叠行、自动噪声）。
- 有 <stem>.gaps.txt 时读它：高置信缺字形据上下文修回 md，不确定保留 □。
- 抽查开头/结尾/章节衔接；合集/合著作品要核对收录是否完整（见英文专项文档）。
2. 候选角色名召回 → AI 判读定名册
# 自动判语；英文输出 honorific/fullname/非句首频次排序的候选表
python scripts/scan_names.py OUT.md --lang en --json _work/cand.json \
--skeleton _work/NAMES.json --skeleton-k 15
- 英文：脚本只负责召回排序；AI 必须读原文上下文确认：同一人的名/姓/昵称/称谓
（如 Ethelbertha = Little Mother、Gideon = Gid = Forsyth）合并到同一 canonical；
删地名/普通词误报；对同形词（Grey/Frank/St）在 NAMES.json 写guard。 - 中文：候选来自「XX+说道问笑」与称谓模式，仍需读原文确认译名异写。
- 本机有 spaCy 时加
--spacy合并 PERSON 实体；没有也不影响规则召回。 - 用
count_chars.py精确计数（骨架已含first_person_pronoun，自动统计 I/我）：
bash python scripts/count_chars.py OUT.md _work/NAMES.json --out _work/counts.json
留意 stderr 的「全小写同形词」风险提示。
3. 撰写 chars.json（AI 填主观项）
按 references/methodology.md 的 v2 模板：name/relation/ending/status/edges，
count 可留空（build_outputs 自动统计）；另写 summary（≤500 字）与 evaluation（≤500 字，注明来源）；
背景人物放 minor_characters 不入图。英文书补 english_title、author。
4. 生成产物
python scripts/build_outputs.py chars.json --md OUT.md --outdir DIR --formats all
# all = html + png + docx + md；只要 DOCX+PNG 可写 --formats png,docx
DOCX 结构固定：封面 → 一、图谱（内嵌 PNG）→ 二、故事梗概 → 三、客观世界评价 →
四、人物表 → 五、背景人物。注意脚本会警告孤立节点，补边后重生成。
5. 客观世界评价（联网取证）
中文书：销量、评分、权威评论、获奖、批评争议。英文书的标准取证字段与来源分级见
references/english_workflow.md（首载体与年份、作者自述、经典化历程、中译本、改编、流派地位）。
区分「已查证事实」与「一方观点」，关键事实附 URL。
6. 交付前质检（必做）
python scripts/verify_output.py OUT.md --chars chars.json \
--png "DIR/书名_人物关系图谱.png" --docx "DIR/书名-人物关系图谱.docx"
E 级（残留重复行、主角缺失、边指向不存在角色、DOCX 无图无表）必须修复；W 级逐条判断。
再用 Read 肉眼检查 PNG（中文是否方块、标签是否严重重叠）。
7. 批量处理
python scripts/batch.py books.json --workdir _work # 多本书一把提取+候选扫描
books.json 每项含 input/output/book_title/start_page/noise/lang，字段见 batch.py 头部。
批量只做确定性步骤；判读、chars.json 主观项、评价仍逐本人工完成。
8. 交付
用 present_files 交付全文 MD 与 DOCX（HTML/PNG 按需），并口头给出：角色数、
离世/存活清点、译本/收录边界提示。任务完成后按用户偏好清理 _work 等中间文件。
注意
- 英文小说专项（译名核实、guard 写法、评价字段、收录完整性）见
references/english_workflow.md。 - 方法细节、chars.json v2 schema、常见坑见
references/methodology.md。 - 原书章节缺副标题、个别古拼/旧连字符（to-night, billiard-room）属原排版，保留不「修正」。
- 关系图节点建议 ≤12；扫描版 PDF 无文本层，本流程不适用（需先 OCR）。
- 依赖：
pip install pymupdf python-docx Pillow（DOC 另需 olefile；spaCy 可选）。
