用 WorkBuddy 把 1689 本藏书的书名一键中文化（实战教程）

一句话：把 Calibre 书库里成片的拼音名、英文原名、乱码书名，治理成规范中文名——全程官方 CLI，零直写数据库，首批 65 本一次跑通。

一、为什么需要这个

多台机器、多个旧书库合并之后，Calibre 书库很容易变成这样：

• 拼音名重灾区：Xi You Ji - Wu Cheng En、Jing Shi Yi Zhuan
• 英文原版混杂：The Wealth of Nations、Min Fa Dian
• 乱码孤本：QT4参考? 这类疑似编码事故

书名不规范的连锁反应：Calibre-web / Jellyfin 显示难看、ebook-convert 批量抽取时文件名混乱、检索「西游记」永远搜不到那本 Xi You Ji。

我用 WorkBuddy 开发了一个技能 calibre-chinese-title-normalizer，对自己的真实书库（1689 册）做了实测：需治理 666 册，占 39.4%，其中纯拼音/英文 590 册。本文记录从扫描到首批 65 本改名完成的完整过程，以及踩过的三个坑。

二、技能设计：三道安全闸门

治理书库最怕两件事：改错了回不去、脚本失控写坏 metadata.db。所以这个技能从设计上就规避：

1. 只读扫描：扫描脚本以 SQLite mode=ro URI 打开数据库，物理上不可能写库。输出四类清单：garbled（乱码）/ empty（空名）/ no-cjk（纯拼音或英文）/ mixed（中英混杂）
2. 人工映射表：每本书改成什么名，必须人工逐条确认后写进 CSV——技能红线，未经确认绝不改名
3. calibredb 小批次改名：只走官方 CLI 的 set_metadata，默认 dry-run，单批上限 10 本，逐条比对旧书名（发现漂移整批中止），全量执行日志落盘

三、完整操作流程

第 1 步：只读扫描（约 1 分钟，零风险）

报告会把所有需关注的书按四类分组列出 book_id / 当前书名 / 路径，直接作为下一步的映射表底稿。

第 2 步：整理映射表（人工确认，这是灵魂）

CSV 格式四列：

两个实用技巧：

• 旧书名直接从数据库取精确值，不要手工转录——空格、标点差一个字符就会触发防漂移中止（这恰恰是保护）
• 用 WorkBuddy 对话式生成映射表效率极高：把扫描报告喂给它，说「按通行中译名起草映射表，英文原版保持原名」，人只做终审

第 3 步：dry-run 校验

不加 --apply 就是预览模式，逐条显示 旧名 → 新名 和校验结果。

第 4 步：分批执行 + 复查

确认无误后加 --apply，每批 10 本，跑完重扫一遍核对数字变化。我首批 65 本，扫描报告从 666 册降到 601 册，精确 -65，一本不多一本不少。

四、实战踩过的三个坑（精华都在这）

坑 1：Calibre GUI 开着，calibredb 全部拒绝写入

现象：每本书都报错退出。原因：Calibre 主程序运行时锁住书库，官方 CLI 拒绝并发写——这其实是保护机制。解法：改名前退出 Calibre 主程序（连后台残留的 calibre-parallel.exe 也一并确认退出）。

坑 2：环境变量污染，calibredb 启动即崩

现象：calibredb 返回 rc=1，报 site.py 相关错误。原因：某些 AI 工具链会设置 PYTHONPATH 环境变量，污染 Calibre 自带的私有 Python 解释器。解法：调用 calibredb 前清掉 PYTHON 系列环境变量（技能脚本里已内置环境隔离，子进程以干净环境启动）。

坑 3：calibredb「假失败」——rc=1 但实际写成功了

这是最隐蔽的一个：calibredb 的执行顺序是先把新标题提交进数据库，再搬迁磁盘上的书目录（复制新目录、删旧目录）。搬迁环节偶发失败时进程报错退出，但标题其实已经写进去了。如果这时盲目重试，防漂移校验反而会报「书名不匹配」。

解法：以数据库现状为准做增量续跑——重扫书库，已是新书名的自动剔除，只对真正没改成功的继续执行；最后统一对账，清理搬迁半途留下的孤儿副本目录（我用这方法清了 44 个）。判据很简单：DB 里 title 字段对了、磁盘上存在 DB 路径指向的目录，就算治理完成。

五、收益盘点

六、给你的行动清单

1. 在 WorkBuddy 技能市场搜「Calibre 中文书名」安装技能（或按本文流程手动跑脚本）
2. 先只跑第 1 步扫描，看看自己书库的「病情」报告
3. 映射表务必人工确认——书名是你的藏书门面，AI 起草、人终审
4. 改名前退出 Calibre、备份 metadata.db，然后小批次推进

有任何问题欢迎评论区交流，祝大家的书库早日告别 Xi You Ji。

本文方法纯 Python 标准库实现，零第三方依赖，欢迎按流程复现并交流。