← Back to Skills Marketplace
1146
Downloads
8
Stars
7
Active Installs
8
Versions
Install in OpenClaw
/install 12306-train-assistant
Description
12306 查询与订票辅助技能，支持余票查询、经停站查询、中转换乘、候补查询与提交/取消、登录状态检查、密码登录与二维码登录、下单与支付链接获取；当用户提到火车票、高铁票、经停站、中转、候补或 12306 查票时触发。
README (SKILL.md)
12306 CLI Skill 🚄
目标
用本仓库的 client.py 完成 12306 相关查询与下单辅助，优先覆盖：
- 余票查询：
left-ticket - 中转换乘：
transfer-ticket - 中转下单：
transfer-book - 经停站：
route（支持--train-code自动解析） - 登录态检查：
status - 二维码登录：
qr-login-create - 候补管理：
candidate-queue/candidate-orders/candidate-submit/candidate-cancel/candidate-pay - 支付信息：
order-pay - 需要登录的操作：
passengers/orders/order-no-complete/book/transfer-book/order-pay/candidate-submit/candidate-cancel/candidate-pay
触发信号
用户提到下列需求时触发本技能：
- “查明天北京到上海余票”
- “G1033 经停站”
- “深圳到拉萨怎么中转”
- “把第1个中转方案下单”
- “候补排队状态怎么样”
- “12306 登录状态”
执行原则
- 默认用
text输出（便于用户阅读）；仅在用户明确要求结构化数据时加--json。 - 解析相对日期（今天/明天/后天）为
YYYY-MM-DD后再执行命令。 - 站名支持中文/拼音/三字码，直接传给命令即可。
route优先用--train-code，减少用户提供train_no的负担。- 失败时先给出可执行修复建议（缺参数、日期格式、站名不匹配、风控限制等）。
book/transfer-book成功后优先告知订单号，并提示下一步执行order-pay获取支付参数；若网页支付不可用，建议去 12306 App 的“待支付订单”继续支付。qr-login-create会自动后台启动登录检查；扫码确认后统一用status判断是否已登录。
常用示例
示例 1：余票查询
python3 client.py left-ticket --date 2026-03-23 --from 北京南 --to 上海虹桥
python3 client.py left-ticket --date 2026-03-23 --from 北京 --to 上海 --limit 10 --json
示例 2：中转换乘
python3 client.py transfer-ticket --date 2026-03-23 --from 深圳 --to 拉萨 --limit 10
python3 client.py transfer-ticket --date 2026-03-23 --from 深圳 --to 拉萨 --middle 西安 --json
示例 2.1：中转下单
# 先预检（不最终提交）
python3 client.py transfer-book --date 2026-03-23 --from 成都 --to 广安 --plan-index 1 --seat second_class --passengers 张三 --dry-run
# 正式提交
python3 client.py transfer-book --date 2026-03-23 --from 成都 --to 广安 --plan-index 1 --seat second_class --passengers 张三
示例 3：经停站
# 推荐：直接用车次号，脚本自动解析 train_no
python3 client.py route --train-code C956 --date 2026-03-23 --from 南部 --to 南充北
# 已知 train_no 时可直查
python3 client.py route --train-no 760000C95604 --date 2026-03-23 --from NBE --to NCE
示例 4：登录与状态
python3 client.py status
python3 client.py login --username \x3C账号> --password \x3C密码>
python3 client.py login --username \x3C账号> --id-last4 \x3C证件后4位> --send-sms
python3 client.py login --username \x3C账号> --id-last4 \x3C证件后4位> --sms-code \x3C6位验证码>
# 二维码登录流程
python3 client.py qr-login-create
python3 client.py status
示例 5：乘车人与订单
python3 client.py passengers --limit 50
python3 client.py orders --where G --page-size 20
python3 client.py orders --where H --start-date 2026-02-01 --end-date 2026-03-01
python3 client.py order-no-complete
python3 client.py order-no-complete --any --json
示例 6：订票（预检与提交）
# 只校验，不最终提交
python3 client.py book --date 2026-03-23 --from 北京南 --to 上海虹桥 --train-code G101 --seat second_class --passengers 张三 --dry-run
# 正式提交
python3 client.py book --date 2026-03-23 --from 北京南 --to 上海虹桥 --train-code G101 --seat second_class --passengers 张三
# 单人选座（D 会自动归一化为 1D）
python3 client.py book --date 2026-03-23 --from 北京南 --to 上海虹桥 --train-code G101 --seat second_class --passengers 张三 --choose-seats D
# 不下单，仅获取订单支付信息（普通/中转通用）
python3 client.py order-pay --pay-channel alipay
示例 7：候补查询
# 候补排队状态
python3 client.py candidate-queue
# 候补订单（进行中）
python3 client.py candidate-orders
# 候补订单（已处理）
python3 client.py candidate-orders --processed --start-date 2026-03-11 --end-date 2026-04-09 --limit 20
# 提交候补（建议目标席别余票为“无”时）
python3 client.py candidate-submit --date 2026-03-23 --from 北京南 --to 上海虹桥 --train-code G101 --seat second_class
# 取消候补
python3 client.py candidate-cancel --reserve-no \x3C候补单号>
# 候补支付参数（自动读取 reserve_no）
python3 client.py candidate-pay
# 候补支付参数（指定 reserve_no）
python3 client.py candidate-pay --reserve-no \x3C候补单号>
每个命令参数说明
全局参数（所有命令可用）
| 参数 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--timeout |
否 | 15 |
请求超时时间（秒） |
--json |
否 | 关闭 | 以 JSON 输出结果 |
left-ticket 余票查询
| 参数 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--date |
是 | 无 | 出发日期，YYYY-MM-DD |
--from |
是 | 无 | 出发站（中文/拼音/三字码） |
--to |
是 | 无 | 到达站（中文/拼音/三字码） |
--purpose |
否 | ADULT |
乘客类型 |
--endpoint |
否 | queryG |
余票接口类型，queryG 或 queryZ |
--limit |
否 | 20 |
文本输出时最多展示行数 |
transfer-ticket 中转换乘
| 参数 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--date |
是 | 无 | 出发日期，YYYY-MM-DD |
--from |
是 | 无 | 出发站 |
--to |
是 | 无 | 到达站 |
--middle |
否 | 空 | 指定换乘站，不传则自动推荐 |
--result-index |
否 | 0 |
分页游标 |
--can-query |
否 | Y |
是否继续查询更多方案（Y/N） |
--show-wz |
否 | 关闭 | 显示无座方案 |
--purpose |
否 | 00 |
中转接口乘客类型参数 |
--channel |
否 | E |
中转接口渠道参数 |
--endpoint |
否 | queryG |
中转接口类型，queryG 或 queryZ |
--limit |
否 | 20 |
文本输出时最多展示方案数 |
transfer-book 提交中转订单
| 参数 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--date |
是 | 无 | 出发日期，YYYY-MM-DD |
--from |
是 | 无 | 出发站 |
--to |
是 | 无 | 到达站 |
--middle |
否 | 空 | 指定换乘站，不传则自动推荐 |
--plan-index |
否 | 1 |
选择第几个中转方案（从 1 开始） |
--result-index |
否 | 0 |
中转查询分页游标 |
--can-query |
否 | Y |
是否继续查询更多方案（Y/N） |
--show-wz |
否 | 关闭 | 显示无座方案 |
--seat |
是 | 无 | 席别（如 second_class / O / 一等座） |
--passengers |
是 | 无 | 乘客姓名，多个用逗号分隔 |
--purpose |
否 | 00 |
中转乘客类型编码 |
--channel |
否 | E |
中转接口渠道参数 |
--endpoint |
否 | queryG |
中转接口类型（queryG/queryZ） |
--max-wait-seconds |
否 | 30 |
排队轮询最长等待秒数 |
--poll-interval |
否 | 1.5 |
排队轮询间隔（秒） |
--dry-run |
否 | 关闭 | 只检查不提交最终确认 |
route 经停站查询
| 参数 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--train-code |
二选一 | 无 | 车次号（如 C956、G1033），会自动解析 train_no |
--train-no |
二选一 | 无 | 内部车次号（如 760000C95604） |
--date |
是 | 无 | 查询日期，YYYY-MM-DD |
--from |
是 | 无 | 区间出发站 |
--to |
是 | 无 | 区间到达站 |
--endpoint |
否 | queryG |
仅 --train-code 模式下用于解析 train_no |
--purpose |
否 | ADULT |
仅 --train-code 模式下用于解析 train_no |
--limit |
否 | 200 |
文本输出时最多展示站点数 |
login 登录
| 参数 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--username |
是 | 无 | 12306 用户名/邮箱/手机号 |
--password |
否 | 交互输入或 KYFW_PASSWORD |
登录密码 |
--id-last4 |
否 | 无 | 证件号后 4 位，短信验证场景需要 |
--sms-code |
否 | 无 | 6 位短信验证码 |
--send-sms |
否 | 关闭 | 仅发送短信验证码，不执行完整登录 |
status 登录状态检查
无专属参数，仅使用全局参数。
qr-login-create 生成二维码登录图片（自动后台检查，不阻塞）
| 参数 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--appid |
否 | otn |
二维码登录 appid |
passengers 乘车人查询
| 参数 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--limit |
否 | 200 |
文本输出最多展示人数 |
orders 订单查询
| 参数 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--where |
否 | G |
G 未出行/近期，H 历史订单 |
--start-date |
否 | 自动计算 | 查询起始日期，YYYY-MM-DD |
--end-date |
否 | 今天（--where H 时为昨天） |
查询结束日期，YYYY-MM-DD；历史订单场景必须早于今天 |
--page-index |
否 | 0 |
页码 |
--page-size |
否 | 8 |
每页条数 |
--query-type |
否 | 1 |
查询类型：1 按订票日期，2 按乘车日期 |
--train-name |
否 | 空 | 按订单号/车次/姓名筛选（对应接口字段 sequeue_train_name） |
order-no-complete 查询 1 条未完成订单
| 参数 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--any |
否 | 关闭 | 默认仅返回可支付订单（pay_flag=Y）；开启后返回第一条未完成订单 |
candidate-queue 候补排队状态
无专属参数，仅使用全局参数。
candidate-orders 候补订单查询
| 参数 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--processed |
否 | 关闭 | 查询已处理候补订单；默认查询进行中 |
--page-no |
否 | 0 |
页码 |
--start-date |
否 | 今天 | 查询起始日期，YYYY-MM-DD |
--end-date |
否 | 起始日期+29天 | 查询结束日期，YYYY-MM-DD |
--limit |
否 | 20 |
文本输出最多展示条数 |
candidate-submit 提交候补订单
| 参数 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--date |
是 | 无 | 出发日期，YYYY-MM-DD |
--from |
是 | 无 | 出发站 |
--to |
是 | 无 | 到达站 |
--train-code |
是 | 无 | 目标车次（如 G101） |
--seat |
是 | 无 | 席别（如 second_class / O / 一等座） |
--passengers |
否 | 空 | 乘客姓名，多个用逗号分隔；不传时默认选首位乘车人 |
--purpose |
否 | ADULT |
乘客类型 |
--endpoint |
否 | queryG |
余票接口类型 |
--force |
否 | 关闭 | 即使余票不是“无”也尝试提交候补 |
--max-wait-seconds |
否 | 30 |
候补排队轮询最长等待秒数 |
--poll-interval |
否 | 1.0 |
候补排队轮询间隔秒数 |
说明：当前实现会继续执行候补确认与排队查询；若超时会返回“仍在排队中”，可继续用 candidate-orders/candidate-queue 查看。
candidate-cancel 取消候补订单
| 参数 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--reserve-no |
是 | 无 | 候补单号（reserve_no） |
candidate-pay 候补支付参数获取
| 参数 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--reserve-no |
否 | 自动读取 | 候补单号；不传则尝试从 candidate-queue 自动读取 |
--pay-channel |
否 | 空 | 支付渠道：alipay / wechat / unionpay |
order-pay 订单支付参数（不下单，普通/中转通用）
| 参数 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--pay-channel |
否 | 空 | 支付渠道：alipay / wechat / unionpay |
book 订票
| 参数 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--date |
是 | 无 | 出发日期，YYYY-MM-DD |
--from |
是 | 无 | 出发站 |
--to |
是 | 无 | 到达站 |
--train-code |
是 | 无 | 目标车次（如 G101） |
--seat |
是 | 无 | 席别（如 second_class / O / 一等座） |
--passengers |
是 | 无 | 乘客姓名，多个用逗号分隔 |
--purpose |
否 | ADULT |
乘客类型 |
--endpoint |
否 | queryG |
余票接口类型 |
--choose-seats |
否 | 空 | 选座（如 1D；单人可传 D） |
--max-wait-seconds |
否 | 30 |
排队轮询最长等待秒数 |
--poll-interval |
否 | 1.5 |
排队轮询间隔（秒） |
--dry-run |
否 | 关闭 | 只检查不提交最终确认 |
参数提取规则
- 出发站：
--from - 到达站：
--to - 日期：
--date（格式YYYY-MM-DD） - 经停场景：用户给车次号（如
G1033、C956）时用--train-code - 经停场景：用户给内部号（如
760000C95604）时用--train-no - 查询区间优先用用户提供的
from/to
输出策略
- 默认输出文本结果并概括关键信息。
- 若用户说“返回 JSON / 机器可读”，添加
--json并返回结构化摘要。 book/transfer-book成功时应突出order_id，并提示用户执行order-pay获取支付参数。
示例工作流
示例 A：余票
用户：“查明天北京到上海余票”
python3 client.py left-ticket --date \x3C明天日期> --from 北京 --to 上海
示例 B：经停站
用户：“C956 经停哪些站”
如果用户未给日期或区间，先补齐最小参数（日期、from、to）；拿到后执行：
python3 client.py route --train-code C956 --date \x3C日期> --from \x3C出发站> --to \x3C到达站>
示例 C：中转
用户：“深圳到拉萨怎么中转”
python3 client.py transfer-ticket --date \x3C日期> --from 深圳 --to 拉萨 --limit 10
示例 C.1：中转下单
用户：“把第1个中转方案给我下单，二等座，乘客张三”
python3 client.py transfer-book --date \x3C日期> --from \x3C出发站> --to \x3C到达站> --plan-index 1 --seat second_class --passengers 张三
# 下单成功后，单独获取支付参数/二维码
python3 client.py order-pay --pay-channel alipay
示例 D：候补
用户：“帮我看看候补订单有没有兑现”
python3 client.py candidate-orders --processed --start-date \x3C起始日期> --end-date \x3C结束日期> --limit 20
限制与注意
- 中转结果来自 12306 推荐，不保证覆盖所有可行组合。
- 可能触发风控（如
error.html），需提示用户稍后重试或降低频率。 - 订票链路依赖登录态与乘车人信息，建议先
status/passengers。 - 相对日期必须换算成绝对日期再执行命令。
- 支付阶段统一走
order-pay；脚本会尝试返回支付二维码/链接；也要主动提示用户去 12306 App 的“待支付订单”支付。
Usage Guidance
This skill appears to be what it claims: a 12306 ticket helper that runs the included client.py locally. Before installing/using it: (1) Inspect client.py for any network endpoints beyond kyfw.12306.cn (ensure no unexpected external domains). (2) Understand that you will provide 12306 credentials for login/book actions; session cookies and QR/login state are stored in a cache directory next to the script—treat those files as sensitive. (3) Run the script in a trusted environment (do not run as root) and back up/delete cache files if you want to remove persisted session state. (4) If you need higher assurance, request a full code review of the complete client.py to validate there is no hidden exfiltration or calls to third-party servers. I have medium confidence because I reviewed the SKILL.md and the visible portions of client.py (networking to kyfw.12306.cn, SM4 routines, local cache files) but did not execute a full automated trace of every network call in the entire source file.
Capability Analysis
Type: OpenClaw Skill
Name: 12306-train-assistant
Version: 0.1.7
The skill bundle is a comprehensive 12306 train ticket assistant providing functionalities for ticket querying, booking, and waitlist management. The 'client.py' script is a well-implemented CLI tool that interacts exclusively with the official 'kyfw.12306.cn' domain, using standard SM4 encryption for password handling and local file storage for session cookies and station caches. It includes a background worker mechanism for QR code login status polling and local QR code generation for payments, both of which are functionally justified. No evidence of data exfiltration, malicious execution, or prompt injection was found; the code logic and 'SKILL.md' instructions are strictly aligned with the stated purpose of assisting users with train ticket operations.
Capability Assessment
Purpose & Capability
Name/description (12306 查询与订票) align with the included client.py: the script targets kyfw.12306.cn, implements login, ticket queries, transfer/booking, QR login and candidate (候补) operations. No unrelated services, env vars, or binaries are requested.
Instruction Scope
SKILL.md instructs the agent to invoke the bundled client.py for all operations (queries, login, booking, payment info). This includes background QR login checks and storing/retrieving login state and cookies in the repository's cache directory—expected for this functionality but worth noting because credentials and session tokens are handled and persisted locally.
Install Mechanism
No install spec; this is an instruction-only skill that ships client.py. No remote downloads or package installs are requested, minimizing supply-chain risk. Code executes locally when the agent runs the script.
Credentials
The skill declares no environment variables but does perform login flows that require user credentials (username/password, SMS/ID last4, QR). That is proportionate to booking functionality. The code also contains a hard-coded SM4 key used to encrypt passwords before sending—this is consistent with client-side encryption for 12306 but you may want to review the implementation if you have concerns about how credentials are handled.
Persistence & Privilege
always is false and the skill doesn't request elevated system privileges. The client will create and update local cache files (cookies, qr login state, station index) under a cache directory next to the script—persistent storage of session tokens is normal here but users should be aware these files contain auth state and may persist across runs.
How to Use
- Make sure OpenClaw is installed (local or Docker)
- Run the install command in chat:
/install 12306-train-assistant - After installation, invoke the skill by name or use
/12306-train-assistant - Provide required inputs per the skill's parameter spec and get structured output
Version History
v0.1.7
- Added the new order-no-complete command to support querying for unfinished orders.
- Updated documentation to include order-no-complete usage examples and parameter descriptions.
- Expanded the description of required login actions for some commands in the overview.
- Bumped version metadata (inferred from overall context).
v0.1.6
Version 0.1.6
- 新增独立 `order-pay` 命令（取代 `book`/`transfer-book` 内支付环节），统一获取订单支付参数，更贴合 12306 实际操作流程。
- 所有与支付相关的提示和文档说明相应调整：`book`/`transfer-book` 下单成功后提示用户执行 `order-pay` 查询支付信息。
- SKILL.md 文档中同步修订所有支付相关的命令示例与执行原则。
- 无破坏性变更，对既有订票、候补等功能无影响。
v0.1.5
Version 0.1.5
- Updated version number in SKILL.md to 0.1.5.
- No user-facing feature, documentation, or logic changes outside of metadata.
v0.1.4
## 12306-train-assistant 0.1.4 Changelog
- Updated skill version to 0.1.4.
- Updated documentation in SKILL.md, including skill description, feature listing, usage examples, and parameter tables.
- No functional changes have been indicated in the provided `client.py`.
- Cleaned up feature and parameter documentation for accuracy and completeness.
v0.1.3
### 12306-train-assistant 0.1.3 Changelog
- Improved QR code login flow: generating a QR code now automatically starts background login status checking (manual polling command removed).
- Updated SKILL description and documentation reflecting the new QR code login process.
- Removed README.md to avoid duplication and outdated instructions.
- Minor documentation clarifications and updates for accuracy.
v0.1.2
12306-train-assistant v0.1.2
- Removed all login-related credential parameters (username, password, id-last4, sms-code) from documentation and usage examples.
- Updated example commands and parameter tables to reflect simplified and privacy-focused skill usage.
- Clarified that passenger and order queries no longer require explicit login parameters; authentication is handled automatically where needed.
- Minor cleanups to documentation for clarity and relevance.
v0.1.1
12306-train-assistant version 0.1.1
- Major update: Added new features and expanded supported commands for 12306 train query and booking.
- Added support for transfer booking (中转下单), QR code login, candidate order submission/cancellation, and payment link retrieval.
- Updated command list and parameters to include new operations such as qr-login-create, qr-login-check, candidate-submit, candidate-cancel, and transfer-book.
- Revised documentation and examples for improved clarity on usage and best practices.
- Improved output strategy: booking success now includes order number and payment link suggestions.
- Enhanced login and order flow, including asynchronous QR code login instructions.
v0.1.0
12306-train-assistant v0.1.0 – Initial Release
- Provides CLI-based assistance for 12306 train ticket queries, transfers, and booking.
- Supports functions: ticket availability, transfer options, station stops, candidate (waitlist) queries, order and passenger management, and login status checks.
- Responds to user requests such as ticket searches, train stop queries, transfer planning, waitlist status, and login verification.
- Implements clear parameter extraction and output strategies for both text and JSON.
- Offers robust usage examples and troubleshooting recommendations for common user issues.
Metadata
Frequently Asked Questions
What is 12306 Train Assistant?
12306 查询与订票辅助技能，支持余票查询、经停站查询、中转换乘、候补查询与提交/取消、登录状态检查、密码登录与二维码登录、下单与支付链接获取；当用户提到火车票、高铁票、经停站、中转、候补或 12306 查票时触发。 It is an AI Agent Skill for Claude Code / OpenClaw, with 1146 downloads so far.
How do I install 12306 Train Assistant?
Run "/install 12306-train-assistant" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.
Is 12306 Train Assistant free?
Yes, 12306 Train Assistant is completely free, licensed under MIT-0. You can download, install and use it at no cost.
Which platforms does 12306 Train Assistant support?
12306 Train Assistant is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).
Who created 12306 Train Assistant?
It is built and maintained by myxtype (@myxtype); the current version is v0.1.7.
More Skills