SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsexpress-tracking

express-tracking

Office & productivity

View repository

Updated 10-19 07:52

About this skill

express-tracking - Express mailing tracking and evidence trail

Positioning

Evidence-chain tool for mailing handover:register → query → retain evidence → write back. The source of truth for data is the case.yaml 邮寄跟踪 section (maintained by the case-progress skill's add-mailing / set-mailing; for the schema see its references/schema.md §2.17). Tracking PDF proof is saved in the case 08 - 🏛️ 法院送达/ directory.

Design reference: the express query module of the existing internal browser automation reference implementation (browser-automated official website query + watermarked PDF). This skill is its lightweight replica in the ZCode + ego-browser environment.

Browser session and login-state management (avoid repeated logins — core design)

Goal: scan to log in once and it lasts a year; pass verification once and it lasts seven days; nothing is lost even if Chrome is closed and restarted.

Mechanism Description
Persistent profile ~/.cache/express-tracking/chrome-profile（launch_persistent_context(user_data_dir) persistent mode is isomorphic) — cookies/localStorage/sessionStorage are all written to disk,the tab does not need to stay open
Login cookie gehCYwtM3CvqO(httpOnly) measured validity periodone year; risk-control verification marker gehCYwtM3CvqP validity periodseven days
Login-state determination cookie is authoritative（Network.getCookies presence of gehCYwtM3CvqO); the page showing "Log in/Sign up" in the upper right corner may just be stale DOM not refreshed — reload restores it
Idempotent startup Always run scripts/ensure_chrome.shfirst: if CDP 9222 is alive, reuse it (never restart a running instance, login state is in memory + on disk); only start it if not running
trusted input Form filling/clicking must go through Input.insertText/Input.dispatchMouseEvent(isTrusted=true); synthetic events are detected by risk control → verification popup + login UI reset (see references §0.5)

Session expiry characteristic: the query page pops up a scan-to-login window (rather than a security verification) → have the userquery page tab scan in place (the persistent profile practice), about once a year.

Trigger scenarios

  • After mailing: the user provides an order screenshot/SMS screenshot/waybill photo → register the mailing
  • In transit: the user says "check the express" → query tracking and produce proof
  • After delivery: tracking shows delivered → write back status + delivery date
  • Batch: the user says "refresh all in-transit express" → enumerate in-transit tracking numbers across cases and query in batch

Workflow

1. Registration (at mailing time)

Tracking number sources (in priority order): tracking number in screenshot/SMS (model extracts directly from the image) > user dictation > waybill barcode photo (iPhone photos go to the photo library via iCloud; Vision can recognize Code128 barcodes).

/usr/bin/python3 .claude/skills/case-progress/scripts/case_store.py add-mailing <短码> <单号> \
  --carrier ems|sf|other --content "内装材料" --sent YYYY-MM-DD \
  --sender 寄件人 --to 收件方 --file "08 - 🏛️ 法院送达/YYMMDD 邮寄凭证 <单号>.jpg"

Note:/usr/bin/python3(the default brew python3 + old pyyaml will definitely crash, see environment notes). First copy the proof image into the 08 directory, then register the relative path.

2. Tracking Query (CDP direct connection to Chrome — main route)

Do not use the ego-lite embedded browser: its window is hidden after handOff, invisible and uncontrollable (verified pitfall on 2026-10-09). The main route is isomorphic to existing practice: CDP direct connection to a real Chrome window (9222 + persistent profile), the window is always visible, and login/verification state can accumulate.

# 0. 幂等确保工位（已跑则复用会话，不重启）
scripts/ensure_chrome.sh

# 1. 脚本化操作（scripts/cdp_ems.js，node≥22 免依赖，内置 trusted 输入）
node scripts/cdp_ems.js status                      # 探测页面状态（验证码/登录/输入框）
node scripts/cdp_ems.js query 1234567890123         # 填单查询（自动消登录弹窗、trusted 输入；示例单号，虚构）
node scripts/cdp_ems.js text                        # dump 页面文本（轨迹解析）
node scripts/cdp_ems.js pdf 1234567890123 <路径.pdf> # 水印注入 + printToPDF

Key points:

  • EMS can be queried without login butonly the latest 2 tracking records are shown; if the login cookie is present, it is complete ("Please log in to view complete logistics information" = possible page UI false alarm, check the cookie first)
  • When security verification/QR code login appears: the Chrome window is visible, let the user handle it manually; background polling can be attached (status every 5s, auto pdf once verification disappears)

Key points:

  • EMS can be queried without login butonly the latest 2 tracking records are shownand an image-text security verification pops up; after login, complete tracking records ("Please log in to view complete logistics information")
  • When security verification/QR code login appears: the Chrome window is visible, let the user handle it manually; background polling can be attached (status every 5s, auto pdf once verification disappears)
  • SF Express process reference references/query-flows.md §2 (ported from internal reference implementation, not tested)

3. PDF record (watermark + printToPDF)

After the tracking page is fully loaded,page.evaluate inject a page-header watermark (fixed top bar): left = current time YYYY-MM-DD HH:MM:SS, right = page URL; then via page.cdp("Page.printToPDF", …) export A4 PDF (key parameters see references/query-flows.md §3).

Naming:YYMMDD <承运商>轨迹 <单号>.pdf, saved to the 08 directory.

4. Status write-back

/usr/bin/python3 .claude/skills/case-progress/scripts/case_store.py set-mailing <短码> <单号> \
  --status in_transit|signed|abnormal --latest "最近一条轨迹摘要" \
  [--signed YYYY-MM-DD] --file "08 - 🏛️ 法院送达/YYMMDD EMS轨迹 <单号>.pdf"

When signed for, also add a timeline event (event type = evidence, status done). Wrap up log-work auto --type 整理。

Batch refresh process

  1. list Iterate over cases → each show get 邮寄跟踪 in 状态 ∈ {pending, in_transit} tracking numbers
  2. Group by carrier; for EMS paste ≤20 tracking numbers per batch into the query box, for SF Express one by one (official website tracking number query)
  3. Write back one by one (signed/in transit/exception + latest tracking); list problematic tracking numbers for manual review

Boundaries

  • Only ems / sf / other (other is only registered, not queried)
  • Do not scan codes automatically, do not pass captchas automatically: simulating a WeChat client carries account risk-control risk, always handOff to manual handling
  • No background scheduled monitoring: manual trigger ("check express"/"refresh in transit"), if automatic push is needed then evaluate Kuaidi100 subscription (paid)
  • PDF evidence is a snapshot at query time and does not replace a notarized document; important evidence fixation requires separate notarization

Environment notes

  • case_store CLI always /usr/bin/python3(brew python3.14 + pyyaml4.2 will collections.Hashable crash)
  • scripts/cdp_ems.js requires node ≥22 (native WebSocket, zero dependencies); Chrome CDP's /json/list returning empty in Chrome 155 is normal, the script already uses /json/new fallback
  • scripts/ensure_chrome.sh idempotently manage a dedicated Chrome workstation (CDP 9222 + persistent profile ~/.cache/express-tracking/chrome-profile）
  • 2026-10-09 tested closed loop: 13-digit EMS tracking number query → trusted input bypasses verification popup → watermark PDF (364KB) → set-mailing write-back; cookie mechanism confirmed (login valid one year/verification seven days)