---
name: bill-pdf-split
description: Split scanned hotel/bill PDFs into one PDF per company or unit. Use when the user asks to拆分账单PDF, 按公司名称拆账单, 扫描账单按单位生成PDF, or says printed company names may be crossed out and handwritten names should take priority.
---

# Bill PDF Split

## Goal

Split one scanned monthly bill PDF into company/unit-specific PDFs and a zip package. Preserve original scanned pages; only change grouping and output filenames.

Critical rule: if a printed company name is crossed out or corrected, use the handwritten name. Do not trust OCR or the printed company field when handwriting conflicts with it.

## Workflow

1. Locate the source PDF.
   - Prefer the user's stated path.
   - If they say "iCloud 下的某文件", search `~/Library/Mobile Documents/com~apple~CloudDocs`.
   - Run `pdfinfo` or PyMuPDF to get page count.

2. Identify non-detail pages.
   - Monthly handwritten summary pages are useful for cross-checking names, dates, and amounts.
   - Do not place mixed summary pages into any company PDF unless the user explicitly asks.

3. Generate review artifacts before splitting.
   - Use `scripts/split_bill_pdf.py review <pdf>`.
   - Inspect `review_contact.jpg` and `mapping_template.csv`.
   - For each detail page, fill the final output company/unit name in the CSV.
   - If the printed name is crossed out, use the handwritten name. If handwriting is uncertain, mark the filename with `手写疑似：...` rather than presenting a guess as certain.

4. Split only after the mapping is reviewed.
   - Use `scripts/split_bill_pdf.py split <pdf> --mapping <csv>`.
   - The script creates per-company PDFs, a manifest JSON/Markdown, and a zip.
   - Preserve original page images and order.

5. Verify.
   - Total pages in generated PDFs must equal the intended detail page count.
   - Zip integrity must pass.
   - Report ambiguous handwritten names separately.
   - Reveal the zip in Finder with `open -R`.

## Script Usage

Create review artifacts:

```bash
python3 ~/.codex/skills/bill-pdf-split/scripts/split_bill_pdf.py review \
  "/path/to/五月份账单.pdf" \
  --start-page 4
```

Split from reviewed CSV:

```bash
python3 ~/.codex/skills/bill-pdf-split/scripts/split_bill_pdf.py split \
  "/path/to/五月份账单.pdf" \
  --mapping "/path/to/mapping_template.csv"
```

CSV columns:

```text
page,company,notes
4,南大（常熟）研究院有限公司,
25,奥特冷机,printed company crossed out
27,手写疑似：泓昇学院（原苏州东坡文化传播有限公司）,handwriting uncertain
```

## Naming Rules

- Use the company/unit name as the PDF filename.
- Keep `（原...）` only when it helps reconcile crossed-out printed names.
- Use `手写疑似：` for uncertain handwritten names.
- Do not silently merge pages with different handwritten final names even if the printed company is the same.

## Completion Checklist

- Source PDF found and page count recorded.
- Summary/mixed pages excluded or explicitly handled.
- Review sheet generated and mapping reviewed.
- Crossed-out printed names replaced by handwritten names.
- Per-company PDFs generated from original pages.
- Manifest and zip generated.
- Total generated PDF pages equals intended detail pages.
- Zip test passes.
- Ambiguous handwritten names disclosed.