前言¶
在 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）。
