---
name: kuaidi100-logistics-pdf
description: Use when the user sends courier tracking numbers and wants a logistics-track PDF/PNG output via Kuaidi100, including EMS and SF orders, or says "返我 pdf", "快递单号出图", "物流轨迹 PDF", "查快递并合并 PDF". Produces local JSON, PNG, and merged A4 PDF artifacts; can optionally print only after explicit user instruction.
---

# 快递100物流轨迹 PDF

## Core Rules

- Input is one or more courier tracking numbers pasted by the user.
- Output is a merged A4 PDF path, plus the output directory path. Do not print unless the user explicitly says to print.
- Use the bundled script:

```bash
python3 $HOME/.codex/skills/kuaidi100-logistics-pdf/scripts/kuaidi100_workflow.py \
  --out-dir $HOME/Documents/Codex/2026-05-27/chrome-https-www-ems-com-cn/kuaidi100_outputs_<date-or-batch> \
  <tracking numbers...>
```

- For printable output, prefer the generated success-only PDF when any tracking numbers fail.
- Keep duplicate tracking numbers as duplicate PDF pages if the user pasted duplicates.
- The script reads Kuaidi100 credentials from CLI args first, then `KUAIDI100_CUSTOMER` / `KUAIDI100_KEY`, then macOS Keychain services `codex.kuaidi100.customer` and `codex.kuaidi100.key`.
- The default company mode is `--com postal`, which skips Kuaidi100 company auto-detection and tries EMS/China Post candidates directly. Use `--com auto` only when the pasted numbers may be non-postal couriers.
- The script queries unique tracking numbers concurrently with `--jobs 6` by default, then preserves the original input order and duplicate pages in the merged PDF.
- Do not echo secrets back to the user.

## Credentials

The script reads CLI args or:

```bash
KUAIDI100_CUSTOMER
KUAIDI100_KEY
```

If they are not present, it falls back to macOS Keychain:

```bash
security find-generic-password -s codex.kuaidi100.customer -a KUAIDI100_CUSTOMER -w
security find-generic-password -s codex.kuaidi100.key -a KUAIDI100_KEY -w
```

If no credentials are available, stop and ask the user for the Kuaidi100 `customer` and `key`, or use `--sample` only for layout testing.

## Workflow

1. Normalize pasted tracking numbers; preserve input order and duplicates.
2. Run the script without `--print`.
3. For ordinary EMS/China Post batches, keep the default `--com postal --jobs 6`; for mixed courier batches, add `--com auto`.
4. Check the command output for `error[...]` lines.
5. If some numbers failed, create a success-only PDF by filtering out JSON files with an `error` field while preserving duplicate successful input pages.
6. Report:
   - total input count
   - success count
   - failed tracking numbers and reason
   - full PDF path
   - success-only PDF path, if generated
7. Print only if the user explicitly asks to print, and submit one merged PDF to `M233sdn__537444_`.

## Current Rendering Preferences

- Render one PNG per tracking number, then merge to one A4 PDF.
- Do not display courier company.
- Do not display coarse location lines such as `北京市, 北京市`.
- Use compact, print-friendly timeline spacing:
  - large body text
  - tight event spacing
  - punctuation-aware wrapping
- Do not display unknown status badges.

## SF Notes

- SF usually requires a phone suffix. Known suffix candidates from prior work:
  - `0841`
  - `0140`
  - `6705`
- For SF-only tests, run with `--com shunfeng --phone <suffix> --no-reuse-existing`.
- If a suffix works for one SF order, merge that successful JSON back into the main output directory and regenerate PDFs from existing JSON.

## Validation

Run after script edits:

```bash
PYTHONPATH=$HOME/.codex/skills/kuaidi100-logistics-pdf/scripts \
  python3 -m unittest discover -s $HOME/.codex/skills/kuaidi100-logistics-pdf/tests -v
python3 -m py_compile $HOME/.codex/skills/kuaidi100-logistics-pdf/scripts/kuaidi100_workflow.py
```

For generated artifacts:

```bash
mdls -name kMDItemNumberOfPages <pdf>
ls -lh <pdf>
```

## Boundaries

- Do not bypass website CAPTCHAs or access controls.
- Do not buy Kuaidi100 plans or change account settings.
- Do not persist credentials in the skill, repository, shell profile, or output files. If the user explicitly asks for long-term setup, store them in macOS Keychain rather than plaintext files.