前言¶
在 DeepSeek Harness (DSH) 的开发中，构建能够调用外部服务的智能体是常见需求。直接对接 12306 接口涉及复杂的鉴权流程和车站代码映射，开发者通常需要自行编写后端服务。xby-12306-ticket-purchase-search 插件基于 Model Context Protocol (MCP) 协议，将 12306 的购票信息检索能力封装为标准的 DSH 工具。这使得大模型无需关心底层 API 细节，即可直接查询余票、中转方案及列车经停信息。
插件定位¶
这是一个由 xby-skill 维护的联网工具类插件，旨在解决大模型在处理具体购票信息检索时的数据获取问题。它提供了统一的接口，允许 DSH 中的 Agent 调用 12306 的相关数据服务。
核心功能¶
该插件主要提供以下功能模块，用于处理购票相关的数据查询：
-
鉴权与基础工具
set_xby_apikey：在聊天上下文中设置 API 密钥，该密钥会自动持久化，重启后依然有效。get_current_date：获取当前日期，返回格式为 “yyyy-MM-dd”，时区固定为上海（Asia/Shanghai, UTC+8）。主要用于解析用户提到的相对日期（如“明天”、“下周三”）。
-
车站数据查询
get_stations_code_in_city：通过中文城市名查询该城市下所有火车站的名称及其对应的station_code。get_station_code_of_citys：通过中文城市名查询代表该城市的station_code，常用于出发地或到达地的初步筛选。get_station_code_by_names：通过具体的中文车站名查询其station_code和车站名，适用于已知具体站名的场景。get_station_by_telecode：通过车站的station_telecode查询详细信息（名称、拼音、城市等）。此接口主要用于调试或已知 telecode 的特殊查询场景。
-
购票信息查询
get_tickets：查询 12306 余票信息。get_interline_tickets：查询 12306 中转余票信息。get_train_route_stations：查询特定列车车次在指定区间内的详细经停信息，包括途径车站、到站/出发时间及停留时间。
安装与启用¶
通过 DSH 的命令行工具安装该插件，推荐使用方式一。
# 方式一：从 GitHub 直接安装（推荐）
dsh plugin --profile web add github:xby_skill/xby-12306-ticket-purchase-search
# 方式二：从本地目录安装（仅用于本地开发调试）
dsh plugin --profile web add /absolute/path/to/xby-12306-ticket-purchase-search
# 方式三：通过 cordis.patch.yml 开发调试
dsh web --profile web --patch /absolute/path/to/dsh-ocr-plugin/cordis.patch.yml
配置与使用¶
使用该插件前，需获取 API 密钥。
- 获取密钥：访问 小笨羊官网 注册并获取 API 密钥。
- 设置密钥：在 DSH 的对话中调用
set_xby_apikey工具，将获取到的密钥传入。 - 查询流程：通常流程为先使用
get_station_code_of_citys或get_station_code_by_names获取出发地和目的地的station_code，再调用get_tickets进行余票查询。
注意事项¶
- 密钥获取：获取 API 密钥需前往小笨羊官网注册，这是调用查询功能的前提。
- 中转票限制：
get_interline_tickets接口尚且只支持查询前十条结果。 - 开发模式：方式二和方式三仅用于本地开发调试，生产环境建议使用方式一安装。
- 权限与合规：插件以当前 DSH 进程的权限运行，安装前建议检查源码与许可证（MIT）。
