TrainClaw

3-in-1 China 12306 query — tickets, route stops, transfer plans. Zero login. Filter 高铁/动车/火车 by type, time, duration. Pure Python, text/json/csv output. 火车票/...

Security Scan

TrainClaw's declared purpose (CLI queries against 12306 for tickets/routes/transfers) matches the included instructions and code; it makes network requests to 12306, caches station data locally, and does not request unrelated credentials or suspicious endpoints.

Purpose & Capability

Name/description (12306 ticket/route/transfer queries) align with code and SKILL.md. The code uses 12306 endpoints (kyfw.12306.cn, search.12306.cn) and implements ticket/query/route/transfer subcommands as documented. No unrelated services or credentials are requested.

Instruction Scope

SKILL.md instructs running trainclaw.py with appropriate arguments; the script and config are included and the runtime actions described (HTTP requests to 12306, parsing station JS, caching stations) match the code. The instructions do not ask the agent to read unrelated system files or exfiltrate data to third-party endpoints.

Install Mechanism

This is an instruction-only skill (no install spec). Files are bundled in the skill (trainclaw.py, config.py). Dependencies are minimal (requests). No remote downloads or obscure install URLs are used.

Credentials

The skill declares no required environment variables or credentials. The code does not read external secrets or require unrelated tokens; it only performs HTTP requests to 12306. No excessive env access detected.

Persistence & Privilege

The tool creates a local cache (cache/stations.json) under the package directory to store station data (7-day TTL). This is expected for functionality but does mean the skill writes files to disk (requires write permission). always:false and no special privileges are requested.

Assessment

TrainClaw appears coherent and implements exactly what it claims: CLI queries to 12306 with local caching. Before installing or enabling it for autonomous use, consider: 1) it will make network requests to kyfw.12306.cn and search.12306.cn (ensure your environment permits outbound HTTP and this is acceptable); 2) it writes a station cache under the skill's directory (cache/stations.json) — check file-write permissions and sandboxing if you are concerned about persistence; 3) the packaged files show minor version mismatches in README/ __version__ vs registry metadata — not a security issue but worth noting (origin is 'unknown' in registry metadata despite GitHub links in files); 4) verify you have Python 3.8+ and the requests library available; 5) if you require stricter isolation, run the script locally in a sandbox/container first to audit behavior and network traffic. Overall the bundle is internally consistent and not requesting unrelated secrets or contacting unexpected endpoints.

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)

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

# 基础查询
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)

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

python trainclaw.py route -c G1033 -d 2026-03-04
python trainclaw.py route -c G1 -d 2026-03-04 -o json

3. 中转查询 / Transfer Plans (transfer)

查询需要换乘的中转方案。

# 自动推荐中转站
python trainclaw.py transfer -f 深圳 -t 拉萨 -n 5

# 指定中转站
python trainclaw.py transfer -f 深圳 -t 拉萨 -m 西安 -d 2026-03-04

参数说明 / Parameters

通用参数 / Common Parameters

参数	说明	默认值
-d, --date	查询日期 (yyyy-MM-dd)	今天
-o, --format	输出格式: text / json / csv	text

筛选参数 / Filter Parameters (query / transfer)

参数	说明	默认值
-f, --from	出发站（站名/城市名/三字母代码）	必填
-t, --to	到达站（站名/城市名/三字母代码）	必填
--type	车次类型筛选（见下表）	不筛选
--earliest	最早出发小时 (0-24)	0
--latest	最晚出发小时 (0-24)	24
--sort	排序: startTime / arriveTime / duration	不排序
--reverse	倒序排列	否
-n, --limit	最大结果数	query: 不限, transfer: 10

车次类型代码 / Train Type Codes

代码	含义
G	高铁/城际（G/C 开头）
D	动车
Z	直达特快
T	特快
K	快速
O	其他（非 GDZTK）
F	复兴号
S	智能动车组

可组合使用，如 --type GD 表示高铁+动车。

车站名解析 / Station Name Input

支持三种输入格式，自动识别：

1. 精确站名: 北京南、上海虹桥、南京南 → 直接匹配
2. 城市名: 北京、上海、南京 → 匹配该城市代表站
3. 三字母代码: BJP、SHH、NJH → 直接使用

输出格式 / Output Formats

text 格式（默认，推荐给用户阅读）

车次 | 出发站→到达站 | 出发→到达 | 历时 | 席位信息 | 标签
G25 | 北京南→上海虹桥 | 17:00→21:18 | 04:18 | 商务座:1张/2318.0元, 一等座:有票/1060.0元 | 复兴号

json 格式（推荐程序处理）

完整 JSON 数组，包含所有字段。

csv 格式（仅 query 支持）

标准 CSV，含表头行。

文件位置 / Files

• 主程序: trainclaw.py
• 配置文件: config.py
• 缓存目录: cache/（车站数据自动缓存 7 天）

注意事项 / Notes

1. 日期限制: 仅支持查询今天及未来 15 天内的车票
2. 网络依赖: 首次运行需下载车站数据（~3000 站），之后使用本地缓存
3. 错误输出: 错误信息输出到 stderr，数据输出到 stdout，支持管道操作
4. 中转限制: 中转查询结果取决于 12306 的推荐，非所有组合都有结果
5. 依赖: 仅需 Python 3.8+ 和 requests 库

使用场景示例 / Usage Scenarios

日常查票 / Daily Check

用户: "明天北京到上海有什么高铁？"
→ python trainclaw.py query -f 北京 -t 上海 -d {明天日期} --type G

时间筛选 / Time Filter

用户: "上午 8 点到 12 点从南京到杭州的动车"
→ python trainclaw.py query -f 南京 -t 杭州 --type D --earliest 8 --latest 12

查经停站 / Route Stops

用户: "G1033 都停哪些站？"
→ python trainclaw.py route -c G1033 -d {今天日期}

中转方案 / Transfer Plan

用户: "从北京怎么坐火车去成都？"
→ python trainclaw.py transfer -f 北京 -t 成都 -n 5

作者 / Author

公益技能，免费开源。 / Community-driven, open-source, free for everyone.

• Email: [e-mail]
• 小红书 / Xiaohongshu: @深度连接
• GitHub: AI4MSE/TrainClaw