trainclaw

# TrainClaw 🚄 - China Rail Ticket Query / 车票查询AI助手

## 概述 / Overview

**3-in-1 China 12306 query: tickets + route stops + transfer plans, zero login.**
**三合一 12306 查询：余票 + 经停站 + 中转换乘，零登录。**

调用 `trainclaw.py` 一条命令完成查询。无需登录、无需API Key、无需额外配置——仅依赖 Python + requests，开箱即用。支持车次类型筛选、时间窗口、排序，text/json/csv 多格式输出。

One command via `trainclaw.py`. No login, no API key, no extra config — just Python + requests, ready to go. Filter by train type, time window, sort by duration. Output: text / json / csv.

## 触发方式 / Trigger

用户提到火车票、高铁票、动车票、车次查询、余票、经停站、中转换乘、12306等关键词时触发。

Trigger when user mentions train tickets, bullet train, remaining tickets, route stops, transfer, 12306, China rail, etc.

### 快速示例 / Quick Examples

- **"查一下明天北京到上海的高铁票"** → 余票查询
- **"Any bullet trains from Beijing to Shanghai tomorrow?"** → Ticket query
- **"G1033 经停哪些站？"** → 经停站查询
- **"What stops does G1033 make?"** → Route stops
- **"从深圳到拉萨怎么中转？"** → 中转查询
- **"How to get from Shenzhen to Lhasa by train?"** → Transfer plan
- **"南京到上海的动车，上午出发，按时长排序"** → 带筛选的余票查询
- **"EMU trains Nanjing to Shanghai, morning only, sort by duration"** → Filtered query

## 工作流程 / Workflow

```
用户说："查明天北京到上海的高铁"
    ↓
提取参数：出发=北京，到达=上海，日期=明天，类型=G
    ↓
执行命令：
  python trainclaw.py query -f 北京 -t 上海 -d 2026-03-04 --type G
    ↓
返回余票信息（text 格式，直接展示给用户）
```

## 子命令 / Subcommands

### 1. 余票查询 / Ticket Query (query)

查询两站之间的余票信息，支持筛选和排序。

```bash
# 基础查询
python trainclaw.py query -f 北京 -t 上海

# 完整参数
python trainclaw.py query -f 北京 -t 上海 -d 2026-03-04 \
  --type G --earliest 8 --latest 18 --sort duration -n 10 -o text
```

### 2. 经停站查询 / Route Stops (route)

查询某车次的所有经停站信息。

```bash
python trainclaw.py route -c G...

# TrainClaw 🚄

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/AI4MSE/TrainClaw/blob/master/LICENSE)
[![GitHub](https://img.shields.io/badge/GitHub-AI4MSE%2FTrainClaw-black.svg)](https://github.com/AI4MSE/TrainClaw)

[English](README_ENG.md) | 中文

**3-in-1 China 12306 查询：余票 + 经停站 + 中转换乘，零登录。**
**3-in-1 China 12306 query: tickets + route stops + transfer plans, zero login.**

12306 铁路火车票 CLI 查询工具 — 无需登录、零 API Key、开箱即用。查询余票、经停站、中转方案。

12306 China Rail ticket CLI query tool — no login, no API key, plug & play. Query remaining tickets, route stops, and transfer plans.

> 更多技能：查航班 (FlyClaw)、导航 (NavClaw) 等，详见 https://github.com/AI4MSE/
>
> More skills: flight query (FlyClaw), navigation (NavClaw), etc. See https://github.com/AI4MSE/

## 功能 / Features

- **OpenClaw 技能** — 支持作为 OpenClaw 技能使用，参考 SKILL.md / Supports OpenClaw skill integration, see SKILL.md
- **余票查询** (`query`) — 查询两站之间的余票信息，支持按车次类型、出发时间筛选，按时间/历时排序，输出 text/json/csv / Query remaining tickets between two stations with train type, time window filtering, sorting, and multi-format output
- **经停站查询** (`route`) — 查询指定车次的全部经停站信息，输出 text/json / Query all stops for a given train, output text/json
- **中转查询** (`transfer`) — 查询需要换乘的中转方案，支持指定中转站，输出 text/json / Query transfer plans with optional mid-station, output text/json
- **日志系统** (`-v/--verbose`) — 可选的详细日志输出，DEBUG 级别显示 HTTP 请求细节 / Verbose logging with HTTP request details
- **查询冷却** — API 请求间隔可设置，避免请求过于频繁 / Configurable cooldown between API requests
- **友好错误信息** — 中文错误提示、车站名候选建议、空结果操作建议 / Friendly error messages with station name suggestions

## 安装 / Install

```bash
# 仅需 Python 3.8+ 和 requests 库 / Requires only Python 3.8+ and requests
pip install requests
```

## 使用示例 / Usage...