parcel-kau-a

---
name: parcel-kau-a
description: Track Taiwan parcel deliveries by tracking number. Use when the user asks about a package's delivery status, shipping progress, or where a parcel is — including phrases like 查包裹, 包裹進度, 貨態, 到了沒, tracking, or when they paste a Taiwanese courier tracking number. Also use when the user asks which of their parcels are still on the way rather than about one specific number — 還有哪些包裹在路上, 哪些包裹還沒到, 未結案包裹, 我的包裹清單 — which is answered from the local query history without contacting any courier. When they instead want the live, right-now status of everything still pending — 幫我更新一下未結案包裹, 未結案的都查一下最新進度, 全部包裹現在到哪了 — that live-queries each one instead of reading the snapshot. Supports 黑貓宅急便 (T-cat), 嘉里大榮 (Kerry TJ), 台灣宅配通 (e-can), 網家速配 (PChome Express), 富昇物流／momo 自營 (Fusheng), and 蝦皮店到店 (Shopee SPX). 中華郵政, 全家, 7-11 交貨便, and 新竹物流 cannot be read directly (CAPTCHA) but are reachable via 17TRACK if the user supplies their own API key.
---

# parcel-kau-a

輸入台灣包裹單號，回配送時間軸。無需 API key。

## 用法

macOS / Linux 用 `python3`；**Windows 要用 `python`**（`python3` 在 Windows 是
Microsoft Store 的捷徑，直接執行會回 9009「Python was not found」）。

```bash
python3 scripts/track.py <單號>                      # 自動判別貨運公司
python3 scripts/track.py <單號> --carrier tcat       # 指定（建議：省下無謂請求）
python3 scripts/track.py <單號> --json               # 機器可讀輸出
python3 scripts/track.py --pending                   # 只列尚未結案的包裹（不連線）
python3 scripts/track.py --refresh-pending           # 對每筆未結案包裹即時查詢，回報彙整摘要
python3 scripts/track.py --history                   # 列出查詢紀錄（含已完成）
python3 scripts/track.py --forget <單號>             # 刪除某筆紀錄
python3 scripts/track.py --endpoints                 # 列出目前生效的查詢網址
```

Windows（PowerShell）：

```powershell
python scripts\track.py <單號> --carrier tcat
python scripts\track.py --pending
```

`--carrier` 可用值：`tcat`（黑貓）、`kerrytj`（嘉里大榮）、`ecan`（宅配通）、`pchome`（網家速配）、`fusheng`（富昇/momo）、`spx`（蝦皮店到店）。

## 判別規則

黑貓、嘉里大榮、宅配通、網家速配、富昇的單號同為 12 碼數字，**格式無法區分**——不指定 `--carrier` 時會依序查詢、命中即停（最壞 5 次請求）。蝦皮 SPX 為 `TW` 開頭，可由格式判定。

**使用者若提到貨運公司名稱，請務必帶上 `--carrier`。**

## 支援範圍

| 貨運 | code | 方式 |
|------|------|------|
| 黑貓宅急便 | `tcat` | HTTP（資料保留 3 個月） |
| 嘉里大榮 | `kerrytj` | HTTP JSON API |
| 台灣宅配通 | `ecan` | HTTP（資料保留 2 個月） |
| 網家速配 | `pchome` | HTTP（PChome 自營車隊） |
| 富昇物流（momo） | `fusheng` | HTTP（momo 自營配送） |
| 蝦皮店到店 | `spx` | 需 Playwright（見下） |

**直連不支援**：中華郵政、全家店到店、7-ELEVEN 交貨便、新竹物流 —— 這四家的查詢頁都有圖形驗證碼，本 skill 不做驗證碼破解。

## 17TRACK（選配，補上述四家）

使用者自備 API key，設在環境變數 `PARCEL_KAU_A_17TRACK_KEY`：

```bash
python3 scripts/track.py <單號> --via-17track                          # 讓 17TRACK 自動判別
python3 scripts/track.py <單號> --via-17track --carrier chunghwa-post   # 指定貨運
```

`--carrier` 搭配 `--via-17track` 時可用：`chunghwa-post`、`famiport`、`seven-eleven`、`hct`（另有已直連的 tcat/kerrytj/ecan/pchome/spx）。

⚠️ **重要**：17TRACK 會消耗使用者自己的額度（免費 200 筆），所以**絕不自動使用** —— 只有明確加 `--via-17track` 才會呼叫。單號無法判別時 CLI 會提示這個選項，但不會自作主張去打。未設 key 時只有這條路不可用，直連五家照常。

⚠️ **全家 / 7-11 誠實揭露**：`famiport`／`seven-eleven` 兩個 carrier code 的 parser 只驗證過
17TRACK 官方文件寫的 schema，還沒有人拿真實包裹跑過這條路徑確認過。回報結果時如果是這兩家，
順口帶一句「這條路徑的資料形狀還沒拿真實包裹驗證過」，別講得像已經徹底驗證。

## momo 訂單的判斷

momo 出貨雙軌：自營走**富昇**（`--carrier fusheng`），委外則走黑貓／宅配通／新竹。
momo 頁面顯示的配送單號**就是承運商自己的託運單號**，所以看使用者訂單頁寫的「配送方式」直接選對應 adapter 即可；不確定就讓它自動判別。

## 蝦皮 SPX 的額外需求

SPX 需要 headless 瀏覽器：

```bash
pip install playwright && playwright install chromium
```

未安裝時只有 `spx` 不可用，其他三家照常。CLI 會直接告訴使用者缺哪一步。

## 查詢紀錄（v0.2.0 起）

**直連**查到結果時會記下「單號→哪家貨運」到 `~/.cache/parcel-kau-a/history.json`（權限 600）。走 `--via-17track` 不記錄（記成 17track 會讓下次自動判別去打付費 API）。
**目的是隱私**：下次查同一單號直接送那一家，不必對五家逐一嘗試。查無資料不記錄。
（`0600` 僅 POSIX 落實；Windows 上該檔繼承使用者目錄 ACL，實測可能被其他群組讀取。）

- 輸出出現 `（依查詢紀錄：…只查這一家）` = 這次只送了一家
- 輸出出現 `（這筆看起來已完成，可用 --forget xxx 刪除紀錄）` → **主動問使用者要不要清掉**，
  同意才跑 `--forget`。CLI 刻意不做互動提示（非互動硬規則 + agent 環境會卡死）
- 使用者若表示某次查詢不想留紀錄，加 `--no-record`

## 未結案清單（v0.3.0 起）

使用者問「還有哪些包裹在路上／哪些還沒到」這類**不指名單號**的問題時，跑 `--pending`：

```text
未結案包裹（2 筆）

135079340105　黑貓宅急便　配送中　2026/08/06 14:20　（1 天沒更新）
221100334455　台灣宅配通　已到轉運站　2026/7/20 09:05　（18 天沒更新）
```

- 「未結案」＝ 查詢紀錄裡沒被判定為已完成的（判定同上面的 `looks_complete`）
- **這是本機紀錄的快照，不是即時貨態**——`--pending` 一個請求都不發。
  轉述時要講明「這是上次查的狀態」；使用者想知道現在到哪了，就拿該單號另外查一次
- `（N 天沒更新）` 是最後一筆**事件**距今幾天，不是距上次查詢。時間字串解析不了就不顯示
- 天數大到超過站方保留期（黑貓 3 個月、宅配通 2 個月）時 → **主動建議 `--forget`**，
  那種紀錄再查也查不到了，只會一直佔著清單

## 即時更新未結案包裹（v0.4.0 起）

`--pending` 與 `--refresh-pending` 回答的是不同層次的問題——**先判斷使用者要的是快照還是現況**：

| 使用者問法 | 用哪個 | 為什麼 |
|---|---|---|
| 還有哪些包裹在路上／哪些還沒到／未結案包裹／我的包裹清單 | `--pending` | 純讀本機、不發請求，秒回；多數情況這樣就夠 |
| 幫我更新一下未結案包裹／未結案的都查一下最新進度／全部包裹現在到哪了／有沒有新進度 | `--refresh-pending` | 使用者明確要「現在」的狀態，措辭含「更新／現在／最新」 |

`--refresh-pending` 對查詢紀錄裡**每一筆未結案**的單號逐一即時查詢（沿用單號查詢同一條路徑，
序列不並行、無重試——跟本工具一貫立場一致，見 README Limitations），查完印出依結果分類的彙整：

```text
未結案包裹更新（2 筆，依最後事件時間新→舊逐一查詢）

新結案 1　無變化 1

── 新結案（1）──
135079340105　黑貓宅急便　順利送達　2026/08/08 11:02

── 無變化（1）──
221100334455　台灣宅配通　已到轉運站　2026/7/20 09:05
```

- 分類：**新結案**（這次查到已完成）／**有新進度**（最新事件與紀錄快照不同，但還沒完成）／
  **無變化**／**已略過**（多半是缺 17TRACK API key，見下）／**查詢失敗**（該次請求本身失敗，
  訊息比照單號查詢的錯誤分類）
- 查到的結果會**覆寫該筆紀錄快照**（跟一般查詢寫入同一套機制）；`--no-record` 可抑制寫入
- 某筆查詢失敗**不會**中止整批——換下一筆繼續，失敗原因印在該筆那一行
- 未結案清單裡若混到需要 17TRACK 才能查的貨運（正常流程不會發生，只會出現在手動編輯過的
  紀錄檔），且沒設 `PARCEL_KAU_A_17TRACK_KEY` → 該筆列為**已略過**並附設定方式，不算失敗、
  也不會真的呼叫（額度是使用者的錢）；有設 key 才會真的查
- 轉述給使用者時明講「這是剛查到的最新狀態」，跟 `--pending` 的「上次查到的快照」區分清楚
- 包裹數多時就是照樣一筆一筆查，會花比較久——CLI 開查前會先講清楚幾筆
- `--history` 維持列出全部（含已完成並標 `✓可刪`），兩者用途不同

## 查詢網址失效時

站方改版會讓網址失效，訊息會明講（例：`查詢網址回 404，該網址可能已失效`）。
此時可用 `--endpoints` 看目前設定，並在 `~/.cache/parcel-kau-a/endpoints.json`
覆寫新網址 —— **不需要改程式**。引導使用者回報 issue 讓預設值一起更新。

## 回報結果時

- 查無資料是正常結果（單號未登錄、輸入錯誤、或超過站方保留期限），不是錯誤
- 出現「頁面結構已變」訊息代表站方改版，parser 需更新——請引導使用者回報 issue
- 輸出已含來源網址，轉述時保留

## 免責

本 skill 讀取各貨運公司的**公開查詢頁面**，非官方 API、未獲授權。僅供個人低頻查詢；站方改版即可能失效。使用者需自行遵守各站服務條款。