🚄 Railway 12306 Skill#

中国铁路12306火车票智能查询助手，帮你快速找到最合适的车次。

🎯 Purpose#

提供便捷的12306火车票查询服务，解决手动查票繁琐、车次选择困难的痛点。本技能通过调用公开查询接口，实现余票查询、智能推荐、价格对比等功能。

⚠️ 重要说明：

• 本skill仅提供查询功能，不支持购票
• 数据来源于12306公开查询接口
• 不涉及账号登录，无需个人信息
• 建议查询频率控制在每3秒一次以内

⏰ When to Use#

• ✅ 用户询问"火车票"、"高铁"、"动车"、"12306"
• ✅ 查询从A地到B地的车次
• ✅ 询问"哪天回去最好"、"车票贵不贵"
• ✅ 需要对比多日期价格
• ❌ 用户仅询问飞机票（请使用flight-search skill）
• ❌ 需要实际购票（请引导用户访问12306官网/APP）

🧠 Process#

步骤1：参数提取与智能补全#

从用户输入中提取：

• 出发地：城市名或车站名（如"北京"、"北京南"）

• 目的地：城市名或车站名

• 日期：

  • 明确日期："明天"、"2月25日"、"周五"
  • 模糊需求："初八之后"、"这周末"
  • 默认：今天

农历日期处理： 如果用户提到农历日期（如"正月初八"），使用 lunar-calendar skill 转换为公历。

bash

# 示例：查询正月初八
python /home/node/.openclaw/workspace/skills/lunar-calendar/scripts/lunar_calculator.py \
  --lunar "2026-01-08" --leap false

步骤2：车站代码转换#

12306使用三字码，需要转换：

• 读取 references/station_codes.json 获取车站代码
• 支持模糊匹配（如"北京"→可能是"BJP"北京、"VNP"北京南）
• 如有多个匹配，询问用户确认

步骤3：调用查询脚本#

bash

# 基础查询
node scripts/query_tickets.js \
  --from "北京" \
  --to "上海" \
  --date "2026-02-25"

# 多日期对比
node scripts/query_tickets.js \
  --from "丽水" \
  --to "上海" \
  --date "2026-02-25,2026-02-27,2026-02-28" \
  --compare-dates

# 智能推荐
node scripts/query_tickets.js \
  --from "丽水" \
  --to "上海" \
  --date "2026-02-27" \
  --recommend \
  --prefer "fastest"  # 或 "cheapest" / "direct"

步骤4：结果解析与呈现#

输出格式：

text

🚄 丽水 → 上海 (2026-02-27 周五)

【推荐车次】⭐
G7344  07:20-09:56  2h36m  二等座¥199  有票
├─ 优势：最早到达，全天可利用
└─ 余票：二等座99张、一等座20张

【经济实惠】💰
G7368  09:28-12:00  2h32m  二等座¥177  有票
├─ 优势：最便宜，中午到达
└─ 余票：二等座充足

【其他选择】
G7310  16:08-18:54  2h46m  二等座¥185  有票
G7350  18:53-21:35  2h42m  二等座¥185  有票

💡 建议：
- 推荐 G7344（早班）或 G7368（省钱）
- 所有车次余票充足，随时可买
- 周五回去最佳，周末在上海休息

步骤5：智能建议#

基于用户需求和查询结果，提供：

• 时间建议：工作日vs周末、早班vs晚班
• 价格建议：最优性价比车次
• 出行建议：到站后交通、行李提醒
• 购票建议：是否需要抢票、候补

📖 References#

必读文件#

1. references/station_codes.json - 车站代码映射表 json

   {
     "北京": "BJP",
     "北京南": "VNP",
     "上海": "SHH",
     "上海虹桥": "AOH",
     "丽水": "LSP"
   }
   
   

2. references/seat_types.json - 座位类型编码 json

   {
     "二等座": "O",
     "一等座": "M",
     "商务座": "9",
     "硬座": "1",
     "硬卧": "3",
     "软卧": "4"
   }
   
   

可选参考#

• references/holiday_tips.md - 节假日出行提醒
• references/station_transfer.md - 主要城市站间换乘指南

🛠️ Scripts#

scripts/query_tickets.js#

主查询脚本，使用Node.js实现，无需Python环境。

功能：

• 余票查询
• 多日期对比
• 智能推荐
• 价格排序

依赖：

• Node.js 内置模块（https, querystring）
• 无需额外安装npm包

关键逻辑：

javascript

// 1. 构造12306查询URL
const url = `https://kyfw.12306.cn/otn/leftTicket/query?` +
  `leftTicketDTO.train_date=${date}&` +
  `leftTicketDTO.from_station=${fromCode}&` +
  `leftTicketDTO.to_station=${toCode}&` +
  `purpose_codes=ADULT`;

// 2. 设置请求头（重要：避免被拦截）
const headers = {
  'User-Agent': 'Mozilla/5.0 ...',
  'Referer': 'https://kyfw.12306.cn/otn/leftTicket/init',
  'Cookie': '_jc_save_fromStation=...'  // 模拟Cookie
};

// 3. 解析返回数据（JSON格式）
// data.result 是列表，每项是管道符分隔的字符串
// 需要按位置提取：车次|出发站|到达站|时间|余票...

scripts/convert_station.js#

车站代码转换

bash

node scripts/convert_station.js --name "北京"
# 输出：BJP (北京) | VNP (北京南) | ...

scripts/compare_dates.js#

多日期价格对比

bash

node scripts/compare_dates.js \
  --from "丽水" \
  --to "上海" \
  --dates "2026-02-25,2026-02-27,2026-02-28"

🚨 Error Handling#

常见错误与解决#

1. 车站名称无法识别

text

❌ 未找到车站"北京西"
💡 提示：是否是"北京西站"(BXP)?

2. 无余票

text

❌ 2026-02-27 丽水→上海 无直达车票
💡 建议：
  - 尝试其他日期（2月25日有票）
  - 考虑中转方案（经杭州）

3. 查询频率过高

text

⚠️ 查询过于频繁，请等待3秒

4. 农历日期错误

text

❌ "正月初八"需要指定年份
💡 是指2026年正月初八吗？(2026-02-24)

🎯 Use Cases#

Case 1: 基础查询#

用户输入： "帮我查一下明天从丽水到上海的火车票"

处理流程：

1. 提取：丽水→上海，明天（2026-02-22）
2. 转换车站代码：LSP → AOH/SHH
3. 调用查询脚本
4. 展示结果 + 智能推荐

Case 2: 农历日期查询#

用户输入： "初八之后从丽水回上海，哪天回去最好"

处理流程：

1. 识别"初八"需要农历转换
2. 调用 lunar-calendar 确认：初八=2月24日
3. 查询2月25日-28日车票
4. 对比后推荐最佳日期

Case 3: 智能推荐#

用户输入： "周五回上海，要最早到的车"

处理流程：

1. 确定周五=2026-02-27
2. 查询所有车次
3. 按到达时间排序
4. 推荐G7344（07:20发，09:56到）

📊 Output Format#

标准输出#

markdown

🚄 {出发地} → {目的地} ({日期} {星期})

【推荐车次】⭐
{车次}  {发车}-{到达}  {耗时}  {座位}¥{价格}  {余票状态}
├─ 优势：{推荐理由}
└─ 余票：{详细余票}

【经济实惠】💰
{车次}  ...

【其他选择】
{车次}  ...
{车次}  ...

💡 建议：
- {出行建议1}
- {出行建议2}
- {购票提示}

多日期对比#

markdown

📅 价格日历 (丽水 → 上海)

2月25日(周三) 💰最便宜
├─ G7368  09:28发  ¥177  有票
└─ 建议：工作日，价格最优

2月27日(周五) ⭐推荐
├─ G7344  07:20发  ¥199  有票
└─ 建议：周五回，周末休息

2月28日(周六)
├─ G7368  09:28发  ¥177  有票
└─ 建议：周末，相对轻松

🔒 Safety & Privacy#

• ✅ 仅查询公开数据，无需登录
• ✅ 不存储用户个人信息
• ✅ 不缓存查询历史
• ⚠️ 控制查询频率，避免IP封禁
• ⚠️ 提醒用户前往官方渠道购票

🚀 Future Enhancements#

v1.1 计划：

• 支持候补监控
• 价格追踪（历史价格曲线）
• 换乘方案推荐
• 与农历节假日自动关联

v2.0 计划：

• 集成携程/去哪儿价格对比
• 飞机+火车组合方案
• 实时正晚点查询

📝 Development Notes#

创建时间：2026-02-21

作者：玉斧（ wangyuqin2@xiaohongshu.com）

动机：解决手动查询火车票繁琐的问题

参考：基于12306公开查询接口

许可：MIT License

---

⚡ Quick Start:

bash

# 查询明天的票
node scripts/query_tickets.js --from "丽水" --to "上海" --date "tomorrow"

# 智能推荐
node scripts/query_tickets.js --from "丽水" --to "上海" --date "2026-02-27" --recommend

# 多日期对比
node scripts/query_tickets.js --from "丽水" --to "上海" --dates "2026-02-25,2026-02-27" --compare