使用指南

一、快速入门

如果你是第一次接触这个项目，以门票查询为例，推荐先走这 5 步：

bash

# 1) 安装
npm install -g tuniu-cli@latest

# 2) 配置 API Key
export TUNIU_API_KEY=your_api_key

# 3) 查看有哪些服务
tuniu list

# 4) 查看门票服务下的工具列表
tuniu list ticket

# 5) 试一次真实调用
tuniu call ticket query_cheapest_tickets -a '{"scenic_name":"中山陵"}'

如果你更偏向临时使用或在 CI 中调用，也可以直接：

bash

npx tuniu-cli list

常见上手入口：

查看所有服务：tuniu list
查看某个服务的工具：tuniu list ticket
导出 Schema 给 Agent 初始化：tuniu schema --output json
安装/更新 Skill：tuniu skill install

二、命令分类速查

类型	命令	说明
🔍 查询	`tuniu list`	列出所有可用的服务（ticket、hotel、flight、train、cruise、holiday 等）
	`tuniu list <server>`	列出指定服务下的工具清单及简介，如 `tuniu list ticket` 可查看门票相关工具
	`tuniu health`	检查服务连通性与健康状态，支持指定服务或并行检查全部
🧭 服务发现	`tuniu discovery status`	查看服务发现启用状态、Discovery URL 及缓存状态
	`tuniu discovery list`	从 Discovery 获取当前可用服务列表（失败时会自动回退静态配置/缓存）
	`tuniu discovery refresh`	强制刷新 Discovery 缓存
🚀 调用	`tuniu call <server> <tool> -a '<JSON>'`	调用指定服务的工具，详见下文「调用工具」一节
⚙️ 配置	`tuniu config init`	初始化配置文件，在默认路径生成配置文件 `~/.tuniu-mcp/config.json`
	`tuniu config show`	查看当前加载的配置内容
🧩 Skill	`tuniu skill install`	将内置 Skill 安装到 Agent 可识别目录
ℹ️ 帮助	`tuniu help`	查看 CLI 使用帮助
	`tuniu help <server> <tool>`	查看指定工具的功能说明与参数详情
🔧 调试	`tuniu call ... -d`	调试模式，打印完整请求/响应
	`tuniu schema --output json`	导出所有工具的能力定义（Schema），供 Agent 或自动化脚本初始化时使用

三、调用工具（核心用法）

tuniu call 是调用途牛服务的核心命令，格式如下：

bash

tuniu call <server> <tool> --args '<JSON>'
# 或简写
tuniu call <server> <tool> -a '<JSON>'

参数	说明
`server`	服务名称，如 `ticket`（门票）、`hotel`（酒店）、`flight`（机票）、`train`（火车票）、`cruise`（邮轮）、`holiday`（度假产品）
`tool`	工具名称，如 `query_cheapest_tickets`、`tuniu_hotel_search` 等
`--args` 或 `-a`	工具的输入参数，必须是合法的 JSON 字符串

⚠️ 参数注意事项：

--args 的值必须是 JSON 格式，且用引号包裹，避免 Shell 解析错误
中文可直接写入 JSON 中，无需转义
无参数时用空对象：-a '{}'

服务能力速查

服务	功能	可用工具	详细说明
`ticket`	景点门票查询与预订，支持查询票型价格并在线下单	`query_cheapest_tickets`（门票查询） `create_ticket_order`（创建订单）	门票服务
`hotel`	酒店搜索、详情查询与在线预订，支持城市/日期/关键词筛选	`tuniu_hotel_search`（酒店搜索） `tuniu_hotel_detail`（酒店详情） `tuniu_hotel_create_order`（创建订单）	酒店服务
`flight`	国内航班搜索与预订，支持低价/时段/价格区间等 6 种查询模式	`searchLowestPriceFlight`（航班搜索） `multiCabinDetails`（舱位查询） `getBookingRequiredInfo`（预订信息） `saveOrder`（创建订单） `cancelOrder`（取消订单）	机票服务
`train`	火车票车次查询与预订，支持搜索车次列表并在线下单	`searchLowestPriceTrain`（查询车次） `queryTrainDetail`（车次详情） `bookTrain`（预订下单） `queryTrainOrderDetail`（订单详情） `cancelOrder`（取消订单）	火车票服务
`cruise`	邮轮产品搜索与预订，支持按日期/航线/品牌筛选，兼容"游轮"说法	`searchCruiseList`（邮轮搜索） `getCruiseProductDetail`（产品详情） `getCruiseBookingRequiredInfo`（预订信息） `saveCruiseOrder`（创建订单）	邮轮服务
`holiday`	度假产品搜索与预订，支持目的地/出游日期/品类筛选，兼容跟团、自助游、自驾游、当地游等表述	`searchHolidayList`（度假列表搜索） `getHolidayProductDetail`（产品详情与团期日历） `getHolidayBookingRequiredInfo`（预订说明） `saveHolidayOrder`（创建订单）	度假服务

建议：Agent 在运行前先执行 tuniu schema --output json 获取最新工具参数定义；当服务侧新增/变更工具时，可配合 tuniu discovery refresh 做动态更新。

四、场景示例：

🎫 门票完整预订流程

以"查询中山陵门票并下单"为例，展示从查询到下单的完整流程。其他服务（酒店、机票、火车票、邮轮、度假产品）的完整流程请参考上方表格中各服务文档。

第一步：查询景点门票

bash

tuniu call ticket query_cheapest_tickets -a '{"scenic_name": "中山陵"}'

返回门票列表，记录结果中的 productId 和 resId（下单时必需）：

json

{
  "scenic_name": "南京中山陵",
  "tickets": [
    { "productId": 12345, "resId": "res001", "price": "50", "ticketType": "成人票" }
  ]
}

第二步：创建订单

将上一步获取的 productId（对应 product_id）和 resId（对应 resource_id）传入下单：

bash

tuniu call ticket create_ticket_order -a '{
  "product_id": 12345,
  "resource_id": "res001",
  "depart_date": "2026-04-01",
  "adult_num": 1,
  "contact_name": "张三",
  "contact_mobile": "***********",
  "tourist_1_name": "张三",
  "tourist_1_mobile": "***********",
  "tourist_1_cert_type": "身份证",
  "tourist_1_cert_no": "*****************"
}'

返回订单号与支付链接：

json

{
  "success": true,
  "orderId": "ORD2026040100001",
  "paymentUrl": "https://m.tuniu.com/u/gt/order/ORD2026040100001?orderType=75",
  "message": "订单创建成功"
}

⚠️ 下单成功后请将 paymentUrl 发给用户，提醒用户点击链接完成支付。

五、全局选项

可在任意命令后附加以下全局选项：

选项	短选项	说明	示例
`--detail`	`-d`	调试模式，打印完整请求/响应	`tuniu call ... -d`
`--output`	`-o`	输出格式：`json` / `table` / `yaml`	`tuniu list -o table`
`--profile`	`-p`	环境配置（默认 `production`）	`tuniu list -p development`
`--config`	`-c`	指定配置文件路径	`tuniu config show -c ./config.json`
`--timeout`	`-t`	设置请求超时时间（秒）	`tuniu call ... -t 60`
`--version`	`-V`	显示版本号	`tuniu -V`

下一步

查看 CLI 命令列表了解所有命令的详细参数说明
遇到问题？查阅常见问题

使用指南 ​

一、快速入门 ​

二、命令分类速查 ​

三、调用工具（核心用法） ​

服务能力速查 ​

四、场景示例： ​

五、全局选项 ​

下一步 ​

使用指南

一、快速入门

二、命令分类速查

三、调用工具（核心用法）

服务能力速查

四、场景示例：

五、全局选项

下一步