Parcel Kau A

parcel-kau-a

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

用法

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

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）：

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：

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 瀏覽器：

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：

未結案包裹（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），查完印出依結果分類的彙整：

未結案包裹更新（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、未獲授權。僅供個人低頻查詢；站方改版即可能失效。使用者需自行遵守各站服務條款。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: AugustusW
• Source: AugustusW/parcel-kau-a
• License: MIT

Install and usage instructions live in the source repository linked above.