Introduction

In the development of DeepSeek Harness (DSH), building agents that can call external services is a common requirement. Integrating directly with the 12306 API involves complex authentication flows and station code mappings, which usually require developers to build their own backend service. The xby-12306-ticket-purchase-search plugin, based on the Model Context Protocol (MCP) protocol, encapsulates 12306 ticket purchase information search capabilities into standard DSH tools. This allows large models to directly query remaining tickets, transfer plans, and train stop information without worrying about low-level API details.

Plugin Positioning

This plugin is a networked tool-type plugin maintained by xby-skill, designed to solve data retrieval issues when large models need to search specific ticket purchase information. It provides a unified interface, allowing Agents in DSH to call 12306 related data services.

Core Features

The plugin mainly provides the following functional modules for processing ticket-related data queries:

  • Authentication and Basic Tools

    • set_xby_apikey: Sets an API key in the chat context. The key is automatically persisted and remains valid after restart.
    • get_current_date: Gets the current date, returned in “yyyy-MM-dd” format, with the timezone fixed to Shanghai (Asia/Shanghai, UTC+8). It is mainly used to parse relative dates mentioned by users (e.g., “tomorrow”, “next Wednesday”).

  • Station Data Queries

    • get_stations_code_in_city: Queries the names and corresponding station_code of all railway stations in a city by the Chinese city name.
    • get_station_code_of_citys: Queries the station_code representing a city by the Chinese city name, often used for preliminary filtering of departure or destination cities.
    • get_station_code_by_names: Queries the station_code and station name by a specific Chinese station name, suitable for scenarios where the exact station name is known.
    • get_station_by_telecode: Queries detailed information by a station’s station_telecode (name, pinyin, city, etc.). This interface is mainly used for debugging or special query scenarios where the telecode is known.

  • Ticket Purchase Information Queries

    • get_tickets: Queries 12306 remaining ticket information.
    • get_interline_tickets: Queries 12306 transfer remaining ticket information.
    • get_train_route_stations: Queries detailed stop information for a specific train number within a specified range, including passed stations, arrival/departure times, and dwell time.

Installation and Enablement

Install the plugin using DSH’s command-line tools. Method 1 is recommended.

# 方式一：从 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

Configuration and Usage

Before using this plugin, you need to obtain an API key.

  1. Obtain the Key: Visit the Xiaobenyang Official Website to register and obtain an API key.
  2. Set the Key: In DSH conversation, call the set_xby_apikey tool and pass in the obtained key.
  3. Query Flow: The typical flow is to first use get_station_code_of_citys or get_station_code_by_names to obtain the station_code for the departure and destination, then call get_tickets to query remaining tickets.

Notes

  • Key Acquisition: Obtaining an API key requires registering on the Xiaobenyang Official Website. This is a prerequisite for calling the query features.
  • Transfer Ticket Limitation: The get_interline_tickets interface currently only supports querying the first ten results.
  • Development Mode: Methods 2 and 3 are for local development/debugging only. For production environments, installation with Method 1 is recommended.
  • Permissions and Compliance: The plugin runs with the permissions of the current DSH process. Before installation, it is recommended to check the source code and license (MIT).