12306 Train Query

核心用法

本工具通过Node.js脚本直连中国铁路12306官方API，实现火车票查询功能。主要包含两大模块：

1. 车票查询（query.mjs）

• 基础查询：node {baseDir}/scripts/query.mjs <出发站> <到达站>
• 支持城市名自动解析为主站，或精确输入车站名
• 日期默认为当日，可通过-d指定具体日期
• 输出格式灵活：HTML文件（默认）、Markdown表格（-f md）、原始JSON（--json）

2. 车站查询（stations.mjs）

• 用于查询车站代码，如node {baseDir}/scripts/stations.mjs 杭州

显著优点

• 官方数据源：直连12306 API，无需注册或API密钥，数据实时准确
• 筛选功能丰富：支持按车型（G/D/Z/T/K）、出发/到达时段、最大行程时长、余票状态、座位类型等多维度过滤
• 输出格式多样：满足不同场景需求——HTML适合浏览器查看，Markdown适合聊天嵌入，JSON便于二次开发
• 智能缓存：车站数据缓存7天，减少重复请求
• 轻量依赖：仅需Node.js环境，无额外运行时负担

潜在缺点与局限性

• 地域限制：仅覆盖中国铁路系统，不支持国际列车或港澳台地区（除香港西九龙等已纳入12306的站点）
• 无购票功能：纯查询工具，无法完成实际订票、支付、改签等操作
• 座位代码需记忆：座位类型使用缩写（swz/zy/ze等），对用户有一定学习成本
• 时间格式严格：时间范围需符合HH:MM格式，不支持自然语言如"早上"
• 依赖12306稳定性：高峰期可能受官方接口限流或维护影响

适合人群

• 经常需要查询火车时刻与余票的商务人士
• 开发行程规划工具的开发者（JSON输出便于集成）
• 偏好命令行效率的技术用户
• 需要批量查询或自动化报告的场景

常规风险

• 数据隐私：查询行为经过12306官方服务器，虽无需登录，但IP和查询记录可能被记录
• 时效性风险：余票数据存在短暂延迟，热门时段建议最终决策前二次确认
• 脚本安全性：需确保{baseDir}/scripts/目录下脚本来源可信，避免被篡改植入恶意代码
• 网络依赖：必须连通12306服务器，内网或境外网络环境可能受限

核心功能

12306 Skill 是一款专为中国铁路出行设计的查询工具，核心能力包括：

• 列车余票查询：实时获取指定日期、区间的车次、时刻、余票数量及座位类型
• 智能筛选过滤：支持按车次类型(G/D/Z/T/K)、出发/到达时段、行程时长、座位余票等条件精准筛选
• 站点信息检索：模糊匹配城市或精确查询车站名称
• 多格式输出：HTML文件（默认）、Markdown表格（适合对话场景）、原始JSON

显著优点

1. 数据来源权威：直连12306官方API（kyfw.12306.cn），非第三方转接，信息实时准确
2. 零依赖架构：纯Node.js内置模块实现（fs/path/url/util），无第三方包引入，攻击面极小
3. 隐私安全：不收集用户身份信息，无需登录认证，仅访问公开接口
4. 使用门槛低：支持中文城市名自动解析，命令行参数直观易懂
5. 输出灵活：Markdown模式直接输出可阅读表格，适合嵌入对话；HTML模式生成交互式页面

局限与注意事项

• 网络依赖性强：完全依赖12306官方服务可用性，春运高峰或维护时段可能响应缓慢或受限
• 无购票功能：仅查询不可预订，需跳转官方渠道完成支付
• IP限流风险：频繁调用可能触发12306反爬机制，建议合理控制查询频率
• 缓存时效：站点数据缓存7天，若12306调整车站编码可能导致短暂匹配异常
• 无历史票价：仅显示实时余票，不提供历史价格趋势分析

适合人群

• 频繁国内出差/通勤需快速查票的商务人士
• 旅行规划阶段需比价选车的自由行用户
• 对命令行操作熟悉、追求效率的技术用户
• 注重隐私、不愿授权第三方平台登录12306账号的敏感用户

常规风险提示

• 查询结果仅供参考，实际购票以12306官方为准
• 建议出行前二次确认，避免因数据延迟导致误车
• 公共场合使用注意保护行程隐私，避免屏幕被窥视