caj-to-pdf

概述

CAJ to PDF Converter

Convert CAJ (知网) files to PDF format. Produces text-selectable PDFs when possible; falls back to image-type PDF for scanned formats.

When to Use

• User uploads .caj files
• User asks to convert CAJ to PDF
• User needs to process CNKI (中国知网) literature
• User wants to extract text from CAJ files

Supported Formats

All formats are supported. HN/C8 requires libjbigdec-w64.dll (bundled in skill). If the DLL is unavailable, HN/C8 files are converted to image-type PDF via page image extraction.

Scan Detection

After conversion, the script automatically detects whether the output PDF is text-selectable or scanned (image-only). This is reported in the output:

• [文字可选中] — text-selectable PDF
• [扫描版/图像型] — scanned PDF, OCR needed for text editing

Limitations

• Encrypted/DRM-protected CAJ files may fail to convert
• Very old or corrupted CAJ files may not be recognized
• HN/C8 format always produces image-type PDF (text not selectable)

Dependencies

The caj2pdf library is bundled within the skill (scripts/lib/caj2pdf/), with mutool calls patched to use pymupdf internally. The following runtime dependencies must be available:

1. PyPDF2 (Python package, version 2.2.0)
   • Install: pip install PyPDF2==2.2.0
2. imagesize (Python package, version 1.3.0)
   • Install: pip install imagesize==1.3.0
3. pymupdf (Python package, provides MuPDF functionality)
   • Used internally for PDF structure repair and scan detection
   • Install: pip install pymupdf

No external mutool CLI installation is needed.

Check Dependencies

Run the dependency check script first using the Python available in the environment:

python scripts/setup_check.py

If dependencies are missing, install them:

pip install PyPDF2==2.2.0 imagesize==1.3.0 pymupdf

Note: Run commands with the python available in the runtime (WorkBuddy's managed

Python resolves python automatically). Do NOT hardcode user-specific paths such as

C:/Users/xxx/.workbuddy/binaries/... in commands.

Conversion Workflow

Step 1: Check Dependencies

Run scripts/setup_check.py. If any dependency is missing, install it (see above).

Step 2: Perform Conversion

All commands should be run from the skill's root directory.

Single file:

python scripts/convert.py "input.caj" -o "output.pdf"

Batch conversion (directory):

python scripts/convert.py "./caj_files/" -o "./pdf_files/"

Batch conversion (glob pattern):

python scripts/convert.py "*.caj" -o "./output/"

Show file info without converting:

python scripts/convert.py "input.caj" --info

Important: Use the python command available in the runtime environment.

Do NOT hardcode user-specific paths. The runtime should resolve the correct

python path automatically.

Step 3: Review Results

After batch conversion, the script prints a summary:

• Total files processed
• Success / Failed counts
• List of failed filenames (if any)
• Each output PDF is labeled as [文字可选中] or [扫描版]

Check the output directory for the generated PDFs.

Step 4: Report to User

Report to user:

• Number of files converted successfully
• Output file location(s)
• Any failed filenames and likely reasons
• Whether the PDFs are text-selectable or scanned

Script Reference

scripts/setup_check.py

Checks whether required dependencies are available.

Output:

• Reports status of each dependency (OK / missing)
• Reports whether HN format DLL is available
• Exits with code 0 if all core dependencies are available

scripts/convert.py

Converts CAJ files to PDF format. Supports single file and batch mode. In batch mode, prints a failed-file list at the end.

Usage:

# Single file
python scripts/convert.py <input.caj> -o <output.pdf>

# Batch conversion (directory)
python scripts/convert.py <input_dir/> -o <output_dir/>

# Options
--keep-toc       Preserve table of contents (default: enabled)
--no-toc         Do not preserve table of contents
--info            Show CAJ file info without converting

Batch mode output example:

Found 11 CAJ file(s) to convert.

[1/11] [9%] file1.caj
  Format: KDH
  [OK] Success: file1.pdf (1024 KB) [文字可选中]

[2/11] [18%] file2.caj
  Format: HN
  [OK] Success: file2.pdf (2048 KB) [扫描版/图像型]

...

=======================================================
  Total: 11, Success: 9, Failed: 2

  Failed files:
    - corrupted_file.caj
    - encrypted_file.caj
=======================================================

Error Handling

Dependency Missing

If caj2pdf or pymupdf is not found:

1. Run python scripts/setup_check.py to identify missing dependencies
2. Install missing dependencies with pip

Conversion Failed for a File

If conversion fails for a specific file:

1. Check file format: python scripts/convert.py <file.caj> --info
2. Check whether file is encrypted or corrupted
3. Try converting without TOC: --no-toc
4. If all files in a batch fail, check the CAJ files directory path
5. Failed filenames are listed at the end of batch output

File Permission Error

If cannot read/write files:

1. Check input file exists and is readable
2. Check output directory is writable
3. Try a different output directory

Troubleshooting

Q: Conversion produces PDF but text is not selectable A: The CAJ file is a scanned version (HN/C8 format or scanned KDH/CAJ). For text-selectable output, use an OCR tool (e.g. PaddleOCR) on the output PDF.

Q: caj2pdf command not found after installation A: The caj2pdf library is bundled within the skill (scripts/lib/caj2pdf/), not installed via pip. The conversion script (convert.py) imports it directly. No separate caj2pdf command is needed.

Q: Batch conversion fails halfway A: Check the failed file list at the end of the output. Try converting failed files individually to identify the specific error. Some files may be encrypted, corrupted, or in an unsupported sub-format.

Q: Chinese characters in filenames cause errors A: The scripts support UTF-8 filenames. If errors occur, try moving the file to a path without special characters and retry.

Q: HN format files produce scanned PDF A: This is expected. HN/C8 format stores page elements as images. The skill converts these to image-type PDFs. Text is not selectable. Use OCR if you need selectable text.

License

This skill is distributed under the GPL-3.0 license. The bundled caj2pdf library and supporting native decoders carry their own licenses (FreeType Project License, LGPL-3.0), documented together with the full GPL-3.0 text in THIRD_PARTY_NOTICES.md.

Publishing note: The CAJ format is a proprietary CNKI format. Before publishing or

redistributing this skill, ensure compliance with CNKI's terms of service and your

platform's content policy regarding format-reverse-engineering tools.