🚄 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 转换为公历。
# 示例：查询正月初八
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：调用查询脚本
# 基础查询
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：结果解析与呈现
输出格式：
🚄 丽水 → 上海 (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
必读文件
-
references/station_codes.json - 车站代码映射表
{ "北京": "BJP", "北京南": "VNP", "上海": "SHH", "上海虹桥": "AOH", "丽水": "LSP" } -
references/seat_types.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包
关键逻辑：
// 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
车站代码转换
node scripts/convert_station.js --name "北京"
# 输出：BJP (北京) | VNP (北京南) | ...
scripts/compare_dates.js
多日期价格对比
node scripts/compare_dates.js \
--from "丽水" \
--to "上海" \
--dates "2026-02-25,2026-02-27,2026-02-28"
🚨 Error Handling
常见错误与解决
1. 车站名称无法识别
❌ 未找到车站"北京西"
💡 提示：是否是"北京西站"(BXP)?
2. 无余票
❌ 2026-02-27 丽水→上海 无直达车票
💡 建议：
- 尝试其他日期（2月25日有票）
- 考虑中转方案（经杭州）
3. 查询频率过高
⚠️ 查询过于频繁，请等待3秒
4. 农历日期错误
❌ "正月初八"需要指定年份
💡 是指2026年正月初八吗？(2026-02-24)
🎯 Use Cases
Case 1: 基础查询
用户输入： "帮我查一下明天从丽水到上海的火车票"
处理流程：
- 提取：丽水→上海，明天（2026-02-22）
- 转换车站代码：LSP → AOH/SHH
- 调用查询脚本
- 展示结果 + 智能推荐
Case 2: 农历日期查询
用户输入： "初八之后从丽水回上海，哪天回去最好"
处理流程：
- 识别"初八"需要农历转换
- 调用 lunar-calendar 确认：初八=2月24日
- 查询2月25日-28日车票
- 对比后推荐最佳日期
Case 3: 智能推荐
用户输入： "周五回上海，要最早到的车"
处理流程：
- 确定周五=2026-02-27
- 查询所有车次
- 按到达时间排序
- 推荐G7344（07:20发，09:56到）
📊 Output Format
标准输出
🚄 {出发地} → {目的地} ({日期} {星期})
【推荐车次】⭐
{车次} {发车}-{到达} {耗时} {座位}¥{价格} {余票状态}
├─ 优势：{推荐理由}
└─ 余票：{详细余票}
【经济实惠】💰
{车次} ...
【其他选择】
{车次} ...
{车次} ...
💡 建议：
- {出行建议1}
- {出行建议2}
- {购票提示}
多日期对比
📅 价格日历 (丽水 → 上海)
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:
# 查询明天的票
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