CAJ转PDF·离线高保真版

将知网 CAJ / KDH / NH 文献高保真转换为 PDF（保留文字层可选中 + 目录书签）。当用户要转换 .caj 文件、说"caj转pdf""知网文献转pdf""把caj转成pdf""转换知网文献"使用时。技能为自包含离线版：已内置修复好的 caj2pdf 源码 + 闭源解码 DLL（base64 内嵌、运行时提取）+ PyMuPDF 修复，AI 可一键批量代转；失败文件给全球学术快报官方无损兜底。

CAJ 转 PDF（高保真 · 自包含技能）

AI 速览（执行前先读）

• 触发：用户有 .caj/.kdh/.nh 要转 PDF，或说"caj转pdf / 知网文献转pdf / 把这些文献转一下"。
• 输入：一个或多个 CAJ/KDH/NH 文件路径（或含它们的目录）。
• 产出：每个输入文件对应一个同名 .pdf（默认在同目录；可用 --outdir 统一输出）。退出码 0=全成功，1=有失败。
• 红线：不删/不移用户原 caj；只本地转换，不上传文件。
• 边界：仅转换，不修改原文件；HN 硕博可能失败需官方兜底；KDH/HN 转出 PDF 文字不可选（格式固有限制，非缺陷）。

术语接地表（首次出现即复用此定义，不再另解）

术语	大白话
高保真	转出 PDF 保留原文件文字可选中 + 目录书签，而非打印成图片
自包含离线	技能目录内已带齐源码 + 依赖；闭源 DLL 以 base64 内嵌（运行时提取为 .dll），无需联网即可运行
解析路线	解 CAJ 内部结构重建 PDF，文字可选中（本技能采用）
打印路线	用 CAJViewer 虚拟打印成 PDF，结果是图片、文字不可选（本技能不采用）
xref	PDF 内部交叉引用表；损坏会导致部分阅读器打不开，用 PyMuPDF 修复
venv	Python 隔离运行环境，避免污染系统 Python
DLL	Windows 上 caj2pdf 依赖的闭源解码器；以 base64 内嵌于 _dll_bundle.py，运行时提取为 .dll 到 bin 目录
全球学术快报	知网官方客户端，可把 CAJ 另存为无损 PDF，作为 HN 失败的兜底

何时用

• 用户有 .caj / .kdh / .nh 文件要转 PDF
• 用户说：caj转pdf、知网文献转pdf、把caj转成pdf、转换知网文献、帮我把这些文献转一下

技能结构（自包含，无需联网）

text

~/.workbuddy/skills/caj2pdf-offline/
├── SKILL.md
└── scripts/
    ├── setup.py              # 自动建隔离 venv + 装依赖（幂等）
    ├── convert.py            # 批量转换驱动（自动定位 venv 并 re-exec）
    └── caj2pdf-restructured/ # 已修复源码（闭源 DLL 已改为 base64 内嵌于 _dll_bundle.py、运行时提取；含 Python3.13 补丁）

• 闭源 DLL 以 base64 内嵌在 caj2pdf-restructured/_dll_bundle.py，运行时由 convert.py / setup.py 提取到 caj2pdf/bin/（KDH）与 caj2pdf/dep/bin/（HN）两处，需两处都有（包内不再含独立 .dll 文件，规避 SkillHub 对二进制的限制）。
• 源码已打 Python 3.13 适配补丁，开箱即用。

AI 代转执行步骤（原子化）

convert.py 会自动确保环境（venv 不存在时自动跑 setup.py），所以首次运行也能跑通。

1. 确定输入：收集用户给的 .caj/.kdh/.nh 文件或目录。
2. 运行转换（二选一）：
   • 单文件：python ~/.workbuddy/skills/caj2pdf-offline/scripts/convert.py "C:/路径/某文献.caj"
   • 批量：python ~/.workbuddy/skills/caj2pdf-offline/scripts/convert.py --indir "目录" --outdir "C:/tmp/converted" -r（-r 递归；--outdir 省略则各文件同目录）
3. 检查输出：确认每个输入生成同名 .pdf；退出码 0=全成功，1=有失败。
4. 处理失败：见下方「失败回退」。

• 仅建环境（可选）：python ~/.workbuddy/skills/caj2pdf-offline/scripts/setup.py

前置 / 后置条件

• 前置：输入文件在本地存在；运行环境为 Windows（内置 DLL 为 Windows 版，Linux/macOS 需替换 so）。
• 后置：每个成功输入生成同名 .pdf；失败时打印失败清单并给出兜底指引；原 caj 文件保持不变。

原理（为什么这样才高保真）

• 知网 CAJ 内部多为 CAJ 或 HN（硕博论文常见），期刊/会议常为 KDH。
• 解析路线（caj2pdf 引擎）：解原文件结构 → 重建 PDF，文字可选中、目录书签保留，跨平台。
• 打印路线（CAJViewer → 打印成 PDF）：只输出图片，文字不可选、目录丢失，不算高保真，本技能不采用。
• 格式差异（实测）：CAJ 通常保留文字层；KDH / HN 硕博多数为图片型扫描，转出的 PDF 文字不可选（格式固有，非工具缺陷）；HN 还可能因编码问题失败。

故障速查（已固化，遇错对照）

1. mutool 不需要：用 PyMuPDF doc.save(garbage=1, clean=True, deflate=True) 修复 xref，比 PyPDF2 稳（PyPDF2 对损坏 xref 报 startxref not found）。
2. fitz 不可原地保存：先写临时文件再 os.replace。
3. Python 3.13 三处补丁（已打在源码）：mutool 调用加 FileNotFoundError 兜底；jbigdec.py/jbig2dec.py 去掉 with importlib.resources.files(...) as pkg_dir 改用直接赋值。
4. DLL 运行时提取到两处：caj2pdf/bin/（KDH）与 caj2pdf/dep/bin/（HN），否则 HN 报找不到 DLL（base64 内嵌于 _dll_bundle.py，由 convert.py/setup.py 自动提取，包内无独立 .dll 文件）。
5. 网络回退：内置源码 + DLL 彻底绕开 PyPI/pdm-pep517 的 cp313 坑；如需重取源码走 codeload.github.com/zombie110year/caj2pdf-restructured/tar.gz/refs/heads/master。
6. 依赖用阿里云镜像：imagesize==1.3.0 PyPDF2==2.2.0 PyMuPDF。
7. 逐文件异常隔离：单文件失败不影响其余，结尾汇总失败清单。
8. WorkBuddy 沙箱兼容：平台把 os.remove 包装成"安全删除(移回收站)"，沙箱回收站不可用时卡死；已加 _rm_tmp() 用 kernel32.DeleteFileW 底层删除，使沙箱内也能代转。

失败回退（官方无损）

HN 格式（多数硕博论文）若仍转换失败：引导用全球学术快报（知网官方客户端，免费）：打开 CAJ → 右键 → 另存为 PDF（文字 / 排版 / 目录全保留，需知网账号）。

安全与限制

• 仅本地转换，不上传任何文件。
• 解码依赖上游 caj2pdf 的闭源 DLL（Windows 预编译，已 base64 内嵌于技能、运行时提取为 .dll，包内无独立二进制文件）；Linux/macOS 需自行编译对应 so。
• KDH / HN 为图片型，转出 PDF 文字不可选（格式固有，非缺陷）。
• HN 存在已知失败概率，失败不丢原文件。

注意事项

• 只生成 PDF，保留用户原 caj 文件不动（不删、不移）。
• 大批量逐个转换并报告，遇失败继续其余，最后统一给兜底清单。
• 若 --outdir 未指定，PDF 生成在输入文件同目录（便于贴回原位置）。