# Railway 12306

> 中国铁路12306火车票查询助手。支持余票查询、智能推荐车次、价格对比、时刻表查询。 核心能力： - 实时余票查询（支持高铁/动车/普速） - 智能推荐车次（最快/最便宜/直达/中转） - 多日期价格对比 - 车站代码自动转换 - 农历节假日智能提醒 触发场景：当用户询问"火车票"、"高铁"、"动车"、"12306"、"余票"、"车次"或需要查询铁路出行信息时激活。 输出物：车次列表 + 余票信息 + 价格对比 + 出行建议。

- Skill: `johnalbertini14-glitch/railway-12306` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add johnalbertini14-glitch/railway-12306`
- Raw SKILL.md: https://api.skillmd.com/api/skills/johnalbertini14-glitch/railway-12306/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: johnalbertini14-glitch (https://skillmd.com/u/johnalbertini14-glitch)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/johnalbertini14-glitch/railway-12306

---


# 🚄 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：结果解析与呈现

**输出格式：**
```
🚄 丽水 → 上海 (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. 车站名称无法识别**
```
❌ 未找到车站"北京西"
💡 提示：是否是"北京西站"(BXP)?
```

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

**3. 查询频率过高**
```
⚠️ 查询过于频繁，请等待3秒
```

**4. 农历日期错误**
```
❌ "正月初八"需要指定年份
💡 是指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
```