途牛旅行助手

Reference 读取规则：首次使用某个 server、本轮涉及下单/取消、参数不确定或工具报错时，必须先 Read 该服务的 references/<server>.md（如 references/flight.md）。若该文件不存在，改用 tuniu schema <server> -o json 了解工具列表与参数，必要时再 tuniu help <server> <tool>；不要凭记忆拼参。

当用户询问航班、酒店、企业商旅酒店、门票、火车票、邮轮、度假产品、打包订等旅行服务时，通过 tuniu CLI 调用途牛服务。

意图分流决策表

酒店 / 商旅酒店分流（调用前必须执行）

场景	判断依据	server	参考文件	首选工具
普通/频道酒店	个人住宿、旅游住宿、民宿等	`hotel`	`references/hotel.md`	`tuniuHotelSearch`
企业商旅酒店	明确企业出差、员工差标、成本中心或审批单等	`ttms-hotel`	`references/ttms-hotel.md`	`hotelSearch`

分流规则（按序执行）：

先判断是否商旅语义：用户明确表达企业出差、员工差标、成本中心或审批单等 → 进入商旅路径；否则直接走 hotel。
进入商旅路径后，再检查 TUNIU_TTMS_API_KEY（sk- 开头；不能用普通 OAuth / TUNIU_API_KEY 替代）：
- 有商旅 Key → 调用 ttms-hotel 查商旅酒店。
- 无商旅 Key → 不要调用 ttms-hotel；提示用户：① 获取并配置 TUNIU_TTMS_API_KEY 后再查商旅；或 ② 改查频道酒店 hotel。由用户选择后再继续。
商旅查询失败（退出码 104/108/109 或业务失败）→ 说明原因；若用户同意改查频道酒店，再走 hotel。
ttms-hotel 与 hotel 工具名、认证方式不同，不可混用同一套参数。

机票国内 / 国际分流（调用前必须执行）

收到机票/航班类需求时，先按出发地、目的地判断航线类型，再选 server，不要直接默认 flight：

航线类型	判断依据（以城市为准）	server	参考文件	首选工具
国内	出发地与目的地均为中国大陆城市	`flight`	`references/flight.md`	`searchLowestPriceFlight`
国际	出发地或目的地任一为境外（含港澳台）	`intelflight`	`references/intelflight.md`	`list_intel_flights`

分流规则：

以出发地/目的地为准；用户口头说「国内/国际/出国」仅作参考。冲突时按城市判断选 server。
无法判断时先向用户确认航线类型，确认前不要调用任一机票 MCP。
国内只用 flight，国际只用 intelflight；工具名与参数体系不同，不可混用。
列表无 intelflight 时 → tuniu discovery refresh && tuniu discovery list。
往返、多城按每一航段独立判断；单次 tuniu call 只能选一个 server。

度假产品 / 打包订：意图识别

能力	用户要什么	参考文件	首选工具
`holiday`	买已上架成品线路（产品、团期）	`references/holiday.md`	`searchHolidayList`
`package-booking`	机票/火车/酒店/门票中至少两类自由组合	`references/package-booking.md`	`package_booking_create`
单品服务	只查/只订一类资源	对应 `references/<server>.md`	见该服务

判定顺序（命中即停）：① 明确要产品/线路/团期 → holiday；② 明确至少两类资源组合 → package-booking，首调 package_booking_create（确认后才 submit）；③ 只一类资源 → 单品服务；④ 意图不清（如「想去三亚玩」）→ 先问一句，不要默认调 holiday 或 package-booking。

用户说什么 → 用什么服务

普通 / 商旅酒店、国内 / 国际机票、度假 / 打包订的分流与降级规则见上文对应小节。其余意图按下表：

用户意图	server	参考文件	首选工具
门票/景点门票	`ticket`	`references/ticket.md`	`query_cheapest_tickets`
火车票/高铁/动车	`train`	`references/train.md`	`searchLowestPriceTrain`
邮轮/游轮	`cruise`	`references/cruise.md`	`searchCruiseList`

环境自检

运行环境须 Node.js 18+ 与 tuniu-cli。首次调用前执行：

bash

node --version    # 须 >= 18
npm --version
# 若 tuniu 未安装：npm install -g tuniu-cli@latest
tuniu --version   # 须 >= 头部 minCliVersion；不足则 tuniu update

认证与 API Key 安全

优先 OAuth。首次调用前检查：

bash

tuniu auth status

未授权 → tuniu auth login。WorkBuddy 等会捕获认证 URL 后结束 auth 子进程的环境，使用 --daemon：

bash

tuniu auth login --daemon
tuniu auth status --daemon

OAuth 不可用时可用 TUNIU_API_KEY 兜底（export TUNIU_API_KEY=...）。

ttms-* 服务不支持普通 OAuth / TUNIU_API_KEY，必须单独配置 ttms-member 创建的 sk- 开头员工 CLI API Key：

bash

export TUNIU_TTMS_API_KEY=sk-your_ttms_api_key

安全约束：

已配置凭证时直接调用，不要要求用户重复提供；普通服务失效（退出码 104、108–112）提示更新或改用 OAuth；TTMS 服务检查 TUNIU_TTMS_API_KEY。
不要明文复述密钥；脱敏确认如 tn_****abcd / sk-****abcd。
不要代替用户执行含完整密钥的命令；持久化由用户在本地终端自行设置。
配置文件 ~/.tuniu-mcp/config.json 仅作最后兜底，须 chmod 600。

基本命令

业务调用

bash

tuniu call <server> <tool> -a '<JSON参数>'
tuniu list [server]              # 列出服务/工具
tuniu help <server> <tool>       # 查看参数说明（调用前不确定参数时必用）
tuniu schema [server]            # 导出工具 Schema（可加 -o json）；references 缺失时必用
tuniu update                     # 一键更新 CLI（并刷新本机已安装的 skill）
tuniu discovery refresh && tuniu discovery list   # 刷新服务列表

--args / -a 必须是合法 JSON 字符串；无参数用 -a '{}'。中文可直接写入。

服务工具链路（概览）

服务	搜索 → 详情 → 下单
`flight`	`searchLowestPriceFlight` → `multiCabinDetails` → `getBookingRequiredInfo` → `saveOrder`
`intelflight`	`list_intel_flights` → `get_intel_flight_details` → `getBookingRequiredInfo` → `create_intel_flight_order`
`hotel`	`tuniuHotelSearch` → `tuniuHotelDetail` → `tuniuHotelCreateOrder`
`ttms-hotel`	`hotelSearch` → `hotelDetail` → `hotelSubmitOrder` → `hotelConfirmOrder`；取消：`hotelCancelOrder`
`ticket`	`query_cheapest_tickets` → `create_ticket_order`
`train`	`searchLowestPriceTrain` → `queryTrainDetail` → `bookTrain`
`cruise`	`searchCruiseList` → `getCruiseProductDetail` → `getCruiseCabinAndRoom` → `saveCruiseOrder`
`holiday`	`searchHolidayList` → `getHolidayProductDetail` → `saveHolidayOrder`
`package-booking`	`package_booking_create` →（确认）→ `package_booking_submit`

各服务调用模板、翻页规则、展示规范、场景示例见对应 references/<server>.md。

服务发现

以下情况须先 tuniu discovery refresh && tuniu discovery list：

用户需求不在已知服务列表中
工具不存在（退出码 102）
首次使用 / 无 intelflight / 无 package-booking

响应与退出码

成功时 stdout 为 JSON：{"success": true, "result": {...}}。getBookingRequiredInfo、getHolidayBookingRequiredInfo、getCruiseBookingRequiredInfo 返回纯文本，勿强行 JSON 解析。

退出码	含义	处理建议
0	成功	解析 stdout JSON
101	连接失败	重试或检查网络
102	工具不存在	优先读取 `error.details.available_tools` 改用真实工具名并重试；否则 `tuniu list <server> -o json`，再用 `tuniu help` 或 `tuniu schema <server> -o json` 确认。禁止继续用错误工具名重试
103	参数错误	运行 `tuniu help <server> <tool>`
104	认证失败	普通服务检查 OAuth / `TUNIU_API_KEY`；TTMS 服务检查 `TUNIU_TTMS_API_KEY`
105	超时	使用 `-t 60` 增加超时
106	服务器错误	联系服务提供方或稍后重试
107	配置错误	运行 `tuniu config show` 检查配置
108	未配置 API Key	普通服务优先 OAuth；TTMS 服务设置 `TUNIU_TTMS_API_KEY`
109	API Key 无效	普通服务更新 `TUNIU_API_KEY` 或改用 OAuth；TTMS 服务更新 `TUNIU_TTMS_API_KEY`
110	需要 OAuth 登录	执行 `tuniu auth login`，再用 `tuniu auth status` 确认
111	OAuth 授权失败	检查 OAuth 配置/网络后重新执行 `tuniu auth login`
112	OAuth token 刷新失败	授权已失效，重新执行 `tuniu auth login`
199	未知错误	使用 `-d` 调试模式

全局约束

凭证与 PII 安全：勿在回复或日志中暴露 OAuth token、refresh token、TUNIU_API_KEY、TUNIU_TTMS_API_KEY；联系人姓名、手机号、乘客姓名、证件号仅在预订时发送至 MCP 服务。
认证：普通服务认证错误（退出码 104、108、109、110、111、112）优先 tuniu auth login / tuniu auth status；TTMS 服务检查 TUNIU_TTMS_API_KEY。
日期格式：所有日期均为 YYYY-MM-DD。
参数验证：下单前必须先调用搜索/详情接口获取必需参数（如 cabinPriceId、productId、resId、queryId、sourceId、preBookParam 等）。
翻页：各服务翻页参数不同，注意区分（详见各 references/<server>.md）。
下单结果：下单成功后展示 orderId/order_id 与支付或详情链接，提醒用户完成支付，并在途牛 App/小程序跟进订单与出行通知。
调试模式：遇到问题时使用 -d 参数查看详细请求/响应。
团期价格展示：成人/儿童价格均需基于可售团期原始字段展示；儿童价为 0 时不展示儿童价，双 0 团期不展示。
TTMS 身份边界：companyId、employeeId 和权限 Scope 只能来自服务端认证上下文，禁止作为 Tool 参数传入；提交订单必须使用最新 preBookParam，并在用户明确确认后单独调用 hotelConfirmOrder。

其他命令

认证

bash

tuniu auth status                # 查看 OAuth 授权状态（stdout 输出 JSON）
tuniu auth login                 # 登录授权（CLI 打开浏览器并阻塞至完成）
tuniu auth logout                # 清除本地 OAuth 授权

Agent 会 kill auth 子进程时，login/status/logout 加 --daemon。

CLI 更新

bash

tuniu update                     # 检查并更新 CLI 到 npm latest，并刷新本机已安装的 skill
tuniu update --check             # 仅检查是否有新版本（不安装）
tuniu update --cli-only          # 只更新 CLI，不刷新 skill
tuniu update --to 1.1.2          # 更新到指定版本
tuniu -V                         # 查看当前 CLI 版本

Agent 发现 CLI/Skill 过旧或能力缺失时，优先执行 tuniu update，不要手工卸载/清缓存再装。仅刷新 Skill 时用 tuniu skill install。

Skill 管理

bash

tuniu skill install              # 安装/更新 skill（默认 ~/.agents/skills/tuniu-cli/）
tuniu skill install --agent cursor,claude   # 指定 Agent
tuniu skill install --agent all             # 本机已检测到的全部支持 Agent
tuniu skill install --dir <skills根目录>    # 自定义目录
tuniu skill version              # 查看已安装 skill 版本

安装产物含 SKILL.md + references/；优先从开放平台下载 zip，失败则用 CLI 内置 skill/ 目录。

配置

bash

tuniu config show                # 查看当前配置（退出码 107 时排查）
tuniu config init                # 初始化配置文件
tuniu config init -f             # 覆盖已有配置
tuniu config set <key> <value>   # 设置配置项

默认配置文件：~/.tuniu-mcp/config.json。

Skill 版本

CLI 版本须 ≥ 头部 minCliVersion；不足时执行 tuniu update。查看版本：tuniu -V / tuniu skill version。

途牛旅行助手 ​

意图分流决策表 ​

酒店 / 商旅酒店分流（调用前必须执行） ​

机票国内 / 国际分流（调用前必须执行） ​

度假产品 / 打包订：意图识别 ​

用户说什么 → 用什么服务 ​

环境自检 ​

认证与 API Key 安全 ​

基本命令 ​

业务调用 ​

服务工具链路（概览） ​

服务发现 ​

响应与退出码 ​

全局约束 ​

其他命令 ​

认证 ​

CLI 更新 ​

Skill 管理 ​

配置 ​

Skill 版本 ​

途牛旅行助手

意图分流决策表

酒店 / 商旅酒店分流（调用前必须执行）

机票国内 / 国际分流（调用前必须执行）

度假产品 / 打包订：意图识别

用户说什么 → 用什么服务

环境自检

认证与 API Key 安全

基本命令

业务调用

服务工具链路（概览）

服务发现

响应与退出码

全局约束

其他命令

认证

CLI 更新

Skill 管理

配置

Skill 版本