12306 Android Adb

12306-specific knowledge for booking train tickets via the Android app. Covers UC WebView virtual list behavior, proven booking flow, and common pitfalls. Us...

12306 Train Booking (Android)

12306-specific knowledge, workflows, and pitfalls. The app (com.MobileTicket) uses Alipay Nebula UC WebView for the train list and booking pages, which has unique automation challenges. This doc reflects two successful end-to-end bookings on the current app version (2026-08-30, Realme RMX3350 1080x2400).

🚨 Setup (proven)

bash

# venv (one-time):
python3 -m venv ~/.openclaw/workspace/.venv-12306
~/.openclaw/workspace/.venv-12306/bin/pip install uiautomator2 rapidocr-onnxruntime opencv-python onnxruntime

PY=~/.openclaw/workspace/.venv-12306/bin/python
# App must be installed + logged in. If missing, see "Install & Login".
$PY -c "import uiautomator2 as u2; d=u2.connect(); d.app_start('com.MobileTicket')"

Do NOT use the Appium bridge for 12306 on consumer phones — Realme etc. block WRITE_SECURE_SETTINGS, so Appium settings/IME fail and the session never starts. Direct uiautomator2 + OCR works (atx-agent needs no special permission). All interaction goes through the OCR loop: ocr_bridge.py in the appium-android-adb skill — screenshot → RapidOCR → click/swipe → re-OCR verify.

⚠️ Critical: UC WebView Virtual List Behavior

The train list uses a virtual list inside the UC WebView:

• Accessibility tree / DOM is mostly collapsed (all non-current items share y≈407 or y≈2255, h=6px) and intermittently renders. Never depend on it.
• OCR is the dependable eye: RapidOCR reads Chinese out of the box (no tesseract language packs needed).
• Raw adb shell input tap is filtered by the WebView. d.click(x, y) (uiautomator2) reliably delivers touches.
• The list skips sections when scrolling: a departure-time window (e.g. 06:32) can be jumped over repeatedly.

New-App UI: Card Expansion + Per-Row 预订 (2026-08 version)

Collapsed train cards have NO 预订 button. The flow is:

1. Tap the seat row of a card (e.g. "二等" label area) → the card expands in place, showing seat rows: 二等 / 一等 / 商务 / 无座, each with price (e.g. 二等 ¥41 9折).
2. Each expanded row has its own 预订 button on the right edge (on 1080px width: x≈898–980, h≈48, at the row's y).
3. Tap that row's 预订 → 确认订单 page.

bash

# after OCR shows target train card on screen:
$PY ocr_bridge.py tap-text 二等                      # expand the card
$PY ocr_bridge.py tap-text 预订 --y0 <row_top> --y1 <row_bottom>  # row's 预订

(Example coordinates from the real run: card row at (141, 2026) expanded; 二等 row 预订 at (939, 1987); order page followed.)

⚠️ Departure-Station Filter — Do This BEFORE Scrolling (一车多站)

Without the filter, the list mixes departures from multiple stations and time order breaks. A train that stops at several departure stations (一车多站, e.g. G7357) appears once per stop-time, all grouped adjacently — so you see 08:10 / 08:35 / 08:52 for the same train number and can't scan by time. Hit this in production (thought "no 08:16 train exists" — there was one).

Fix: tap the departure-station filter chip at the top of the list first (chips row, y≈669-708 on 1080x2400; e.g. 上海松江 / 杭州南 / 上海虹桥 / 上海南):

python

chip = [x for x in t if '松江' in x[0] and x[2] < 600]   # OCR: station name near top
d.click((chip[0][1]+chip[0][3])//2, (chip[0][2]+chip[0][4])//2)

After filtering: one row per train, sorted by departure time, target times are findable by simple scrolling.

⚠️ The filter resets after every re-query (查询车票) — re-apply the chip each time.

Booking Flow (proven end-to-end)

Step 0: Install & Login (only if app missing)

• Download the official APK from the 12306 site (kyfw.12306.cn 下载页), e.g. curl the direct link → adb install -r app.apk
• The user must log in manually (SMS/face) — automation cannot do this step.

Step 1: Home Page — Stations & Date

Stations: tap the station field → search box opens. Chinese input via clipboard (IME switching is blocked):

bash

$PY ocr_bridge.py type 苏州 --x 400 --y 330   # set_clipboard + long-press field
$PY ocr_bridge.py dump                        # find 粘贴 in OCR
$PY ocr_bridge.py tap-text 粘贴               # paste → results appear
$PY ocr_bridge.py tap-text 苏州站              # pick the main station

Date: the date picker opens with day cells — OCR the month grid and tap the day cell (e.g. tomorrow's cell right of 今天).

Step 2: Query & Navigate the Train List

Tap 查询车票. The list loads with earliest departures first.

bash

$PY ocr_bridge.py deps        # HH:MM markers at x<250 = which time window is visible
$PY ocr_bridge.py swipe up --scale 0.35     # normal forward scroll (≈2 cards)

• Track position with deps — you always know where you are, DOM or not.
• Apply the departure-station filter chip FIRST (see section above) — without it the list is not time-ordered.
• Filter further if available: tap 只看高铁/动车 (or 只看高铁) to shorten the list.
• List keeps skipping the target section: $PY ocr_bridge.py jump --n 3 (3 rapid scale-0.5 swipes breaks the stuck point), then micro-swipes back: swipe up --scale 0.25, micro down, or d.swipe(540, 1900, 540, 800, duration=0.4).
• Trains to your destination: match OCR train numbers with regex ^[GDCK]\d+ plus the destination name in the row text (ignore trains to other destinations, e.g. 太仓 when heading to 苏州).

Step 3: Expand Card & Tap the Row's 预订

• Tap the target card's seat-row label (二等) to expand → verify expansion by OCR (prices ￥41 etc. appear).
• Tap the expanded row's 预订 on the right edge.
• If a quiet-carriage dialog appears (静音车厢 rules) → tap its confirm button (选择/继续).

Step 4: Select Passenger

• On the 确认订单 page, verify train info + price via OCR markers.
• Tap 选择乘车人 → passenger list appears → tap-text <name> (e.g. 熊天放).
• Verify selection: OCR shows 已选 next to the name.
• Tap 确认 / 完成 (bottom button).

Step 5: Submit Order & Verify

bash

$PY ocr_bridge.py tap-text 提交订单
$PY ocr_bridge.py wait-text 订单处理中      # order processing
$PY ocr_bridge.py markers                   # look for 快速支付 / 立即支付

• 订单处理中 → wait and re-OCR (can take ~20-60s).
• 快速支付 or 立即支付 + countdown at top = order locked, success. Report: train, date, route, seat, price, passenger, seat number, countdown.
• Payment is manual: the user pays in Alipay/WeChat on the phone (指纹/密码 can't be automated). Typical lock window ≈19 minutes.

车票信息已过期 (M0013) — Recovery

If the list data sat too long before submitting, the order page throws "车票信息已过期(M0013)". Detect it by polling markers after 提交订单:

python

for i in range(8):
    time.sleep(4)
    markers = [x[0] for x in shot() if any(k in x[0] for k in
               ('立即支付','快速支付','订单处理','温馨提示','取消订单','已过期','确定'))]
    if any('已过期' in m or '确定' in m for m in markers): break   # ERROR
    if any('立即支付' in m for m in markers): break                # SUCCESS

Recovery (proven):

1. Tap 确定 on the dialog.
2. d.press('back') ×2 → home page. (Pull-to-refresh on the list did NOT refresh the data — don't bother.)
3. Tap 查询车票 for a full re-query → fresh list.
4. Re-apply the departure-station filter chip (it resets on re-query).
5. Scroll to the train → expand → 预订 → passenger → 提交订单. Fresh data submits without the error.

Scroll Tactics Cheat Sheet

Situation	Command
Normal advance	swipe up --scale 0.35
Fine-tune position	micro up / micro down (scale 0.15)
Precise pixel scroll	d.swipe(540, 1900, 540, 800, duration=0.4)
List stuck / skips target window	jump --n 3, then micro back
Back up a little	swipe down --scale 0.3

Decision Tree

text

OCR markers:
  ├─ 查询车票                    → HOME — set stations/date → tap 查询车票
  ├─ 提交订单 / 选择乘车人        → ORDER PAGE — passenger → 提交订单
  ├─ 订单处理中                  → wait, re-OCR
  ├─ 车票信息已过期 / 确定对话框  → EXPIRED — 确定 → back → 查询车票 → re-filter → re-book
  ├─ 快速支付 / 立即支付          → SUCCESS — tell user to pay
  ├─ deps() times + train numbers → TRAIN LIST — scroll/find → expand → 预订
  ├─ 粘贴 menu visible           → after clipboard type, tap 粘贴
  └─ unknown                     → dump full OCR and re-orient

🛡️ Safety & Consent

• Use only when the user explicitly asks to book a ticket — never speculatively.
• Confirm before submitting: show the user the train, date, route, seat, price and passenger, and wait for confirmation before tapping 提交订单.
• Payment (立即支付, Alipay/WeChat, password/fingerprint) is ALWAYS done by the user on the phone — never automated.
• Screenshots may contain personal data; they are stored in a private 0700 dir (~/.cache/ocr-bridge) — see appium-android-adb for cleanup.

Common Pitfalls (all hit in production)

1. Never trust the DOM — it collapses and lies. OCR every time.
2. Raw ADB taps are filtered by UC WebView — always d.click.
3. Appium is dead on Realme (WRITE_SECURE_SETTINGS blocked) — don't waste time on it.
4. IME switching blocked — Chinese input = set_clipboard + long-press 粘贴.
5. The list skips departure windows — jump past the stuck point, then micro-scroll.
6. Clicking 二等 toggles the card — if it collapsed again, re-expand and click the row's right-edge 预订, not the label.
7. Screen auto-lock — adb shell svc power stayon true.
8. 一车多站 mixes the time order — same train number appears at multiple departure times (one per 发站), grouped adjacently. Always apply the departure-station filter chip before scanning for a time.
9. Stale list → 车票信息已过期(M0013) — list data expires while you sit on it. Recovery: 确定 → back → full re-query → re-apply station filter → re-book. Pull-to-refresh does NOT refresh the data.
10. The station filter resets on re-query — re-apply the chip every time after 查询车票.
11. OCR misreads — filter by region (x/y bounds), re-shoot after animations (sleep 2-3s).
12. Train numbers: OCR gives G3314 (no spaces); DOM gives G 3 3 1 4. Regex on OCR text.
13. USB/ADB can drop mid-session — app state (filter + scroll position) survives; ask the user to replug, then continue where you left off.