Now liveThe Skillselion MCP - thousands of ranked skills, loaded into your agent mid-task. No install.Get it →
kirorab avatar

12306

  • 583 installs
  • 9 repo stars
  • Updated March 5, 2026
  • kirorab/12306-skill

12306 is a Node-based agent skill that queries China Railway 12306 for train schedules, remaining tickets, and station filters for developers who need terminal or agent access to China high-speed and conventional rail av

About

12306 is a kirorab agent skill that wraps China Railway's 12306 service with a Node script at scripts/query.mjs. Developers pass origin and destination station names—such as 北京 to 上海—with optional flags to retrieve schedules and remaining ticket counts for the current day by default. Output modes include HTML file generation that prints a saved path, or Markdown tables via the -f md flag printed directly to stdout. The skill metadata requires a node binary and targets agent workflows where users ask about 火车, 高铁, tickets, or schedules within China. Reach for 12306 when building travel assistants, internal trip planners, or automation that must surface live China rail inventory without writing scraper plumbing from scratch.

  • Node `query.mjs` CLI: from/to stations plus rich filters (date, train type, time windows, seats)
  • Output modes: HTML file path, markdown table to stdout, or JSON for downstream automation
  • Filters for bookable-only trains, max duration, depart/arrive ranges, and seat classes (e.g. second class `ze`)
  • Defaults to today’s date when `--date` is omitted
  • Requires `node` on PATH per skill metadata

12306 by the numbers

  • 583 all-time installs (skills.sh)
  • +5 installs in the week ending Aug 2, 2026 (Skillselion tracking)
  • Ranked #111 of 550 CLI & Terminal skills by installs in the Skillselion catalog
  • Security screen: HIGH risk (skills.sh audit)
  • Data as of Aug 2, 2026 (Skillselion catalog sync)
npx skills add https://github.com/kirorab/12306-skill --skill 12306

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

Listed on Skillselion
Installs583
repo stars9
Security audit3 / 3 scanners passed
Last updatedMarch 5, 2026
Repositorykirorab/12306-skill

How do you query China 12306 train tickets from CLI?

Query China Railway 12306 schedules, remaining tickets, and station filters from the terminal when planning travel or building China rail features into an agent workflow.

Who is it for?

Developers building China rail-aware CLI tools or agents who need scripted 12306 schedule and availability lookups.

Skip if: International rail systems outside China or workflows that cannot install Node or execute bundled query scripts.

When should I use this skill?

A user asks about China train, 高铁, or 12306 tickets, schedules, stations, or availability in terminal or agent context.

What you get

HTML ticket report files or Markdown schedule tables with station filters and remaining seat counts.

  • HTML schedule report file
  • Markdown ticket availability table

Files

SKILL.mdMarkdownGitHub ↗

12306 Train Query

Query train schedules and remaining tickets from China Railway 12306.

Query Tickets

node {baseDir}/scripts/query.mjs <from> <to> [options]
  • HTML mode (default): writes file, prints path to stdout
  • Markdown mode (-f md): prints table to stdout

Examples

# All trains from Beijing to Shanghai (defaults to today)
node {baseDir}/scripts/query.mjs 北京 上海

# Markdown table output (to stdout, good for chat)
node {baseDir}/scripts/query.mjs 北京 上海 -t G -f md

# Morning departures, 2h max, with second class available
node {baseDir}/scripts/query.mjs 上海 杭州 -t G --depart 06:00-12:00 --max-duration 1h --seat ze

# Only bookable trains arriving before 6pm
node {baseDir}/scripts/query.mjs 深圳 长沙 --available --arrive -18:00

# Custom output path
node {baseDir}/scripts/query.mjs 广州 武汉 -o /tmp/tickets.html

# JSON output (to stdout)
node {baseDir}/scripts/query.mjs 广州 武汉 --json

Options

  • -d, --date <YYYY-MM-DD>: Travel date (default: today)
  • -t, --type <G|D|Z|T|K>: Filter train types (combinable, e.g. GD)
  • --depart <HH:MM-HH:MM>: Depart time range (e.g. 08:00-12:00, 18:00-)
  • --arrive <HH:MM-HH:MM>: Arrive time range (e.g. -18:00, 14:00-20:00)
  • --max-duration <duration>: Max travel time (e.g. 2h, 90m, 1h30m)
  • --available: Only show bookable trains
  • --seat <types>: Only show trains with tickets for given seat types (comma-separated: swz,zy,ze,rw,dw,yw,yz,wz)
  • -f, --format <html|md>: Output format — html (default, saves file) or md (markdown table to stdout)
  • -o, --output <path>: Output file path, html mode only (default: {baseDir}/data/<from>-<to>-<date>.html)
  • --json: Output raw JSON to stdout

Output Columns

ColumnMeaning
商务/特等Business class / Premium (swz)
一等座First class (zy)
二等座Second class (ze)
软卧/动卧Soft sleeper / Bullet sleeper (rw/dw)
硬卧Hard sleeper (yw)
硬座Hard seat (yz)
无座Standing (wz)

Values: number = remaining seats, = available (qty unknown), = not applicable

Station Lookup

node {baseDir}/scripts/stations.mjs 杭州
node {baseDir}/scripts/stations.mjs 香港西九龙

Important Notes for AI Assistant

⚠️ Station Name Resolution Warning

CRITICAL: When querying by city name (e.g., "武汉", "上海", "深圳", "广州"), the API may return trains from/to ANY station in that city, not just the main station.

Common Pitfalls:

  • 武汉 includes: 武汉站 (main), 汉口站 (Hankou), 武昌站 (Wuchang), 武汉东站
  • 上海 includes: 上海虹桥 (Hongqiao), 上海站 (main), 上海南站, 上海松江站
  • 深圳 includes: 深圳北站 (main), 深圳站 (Luohu), 福田站, 深圳东站
  • 广州 includes: 广州南站 (main), 广州站, 广州东站, 广州北站

Best Practice - Always verify exact stations: 1. First, use stations.mjs to list all stations in the city:

   node {baseDir}/scripts/stations.mjs 武汉

2. Then, query with exact station names for accurate results:

   node {baseDir}/scripts/query.mjs 武汉 上海虹桥 -f md

🔄 Transfer/Connection Guidelines

When planning transfers (中转):

  • Use JSON output (--json) to verify exact station names
  • Ensure both segments use the SAME station (e.g., both use 武汉站, not 武汉→汉口)
  • Recommended minimum transfer time: 20-30 minutes for same station
  • Different stations in same city require additional travel time (e.g., 武汉→汉口 = 30+ min by subway)

📋 Query Workflow Recommendation

For accurate results, follow this workflow:

1. List stations in departure city:

   node {baseDir}/scripts/stations.mjs 北京

2. List stations in arrival city:

   node {baseDir}/scripts/stations.mjs 上海

3. Query with exact station names (e.g., 北京南 → 上海虹桥):

   node {baseDir}/scripts/query.mjs 北京南 上海虹桥 -d 2026-03-05 -f md

4. For transfers: Always verify both segments use the same station by checking fromStation and toStation in JSON output.

Technical Notes

  • Data comes directly from 12306 official API (no key needed)
  • Station data is cached for 7 days in {baseDir}/data/stations.json
  • Works for all train types: G (高铁), D (动车), Z (直达), T (特快), K (快速)

Related skills

FAQ

How do you run the 12306 ticket query script?

The 12306 skill runs node {baseDir}/scripts/query.mjs with origin and destination station arguments, defaulting to today's trains, and optional -f md for Markdown table output instead of HTML file generation.

What runtime does the 12306 skill require?

The 12306 skill metadata lists node as a required binary under openclaw requires.bins, so agents must have Node available before executing scripts/query.mjs.

Is 12306 safe to install?

skills.sh reports 3 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.

This week in AI coding

Five minutes, every Monday - the tools, releases and tactics for developers.

unsubscribe anytime.