接入指南

Appearance

常见问题 ​

Q1: 如何获取 API Key？ ​

前往 途牛开放平台 注册并登录账号，获取 API Key。具体流程可参考平台文档或联系项目负责人。

Q2: 提示「未配置 API Key」怎么办？ ​

确保已设置环境变量：

bash
export TUNIU_API_KEY=your_api_key

若使用配置文件，需确保其中占位符为 ${TUNIU_API_KEY}，与代码中的变量名一致。可执行以下命令重新初始化配置：

bash
tuniu config init --force

Q3: 如何更换 API Key？ ​

将环境变量 TUNIU_API_KEY 覆盖为新的 API Key 即可：

bash
export TUNIU_API_KEY=your_new_api_key

若使用配置文件，更新 ~/.tuniu-mcp/config.json 中对应 headers.apiKey 的占位符引用，或直接重新初始化配置文件：

bash
tuniu config init --force

Q4: 如何查看工具参数说明？ ​

以查询门票工具参数为例：

bash
tuniu help ticket query_cheapest_tickets

响应示例：

query_cheapest_tickets
描述: 查询指定景点的门票详情信息，包括门票的类型和价格等
参数:
  scenic_name (必填): string - 景点名称

Q5: 如何做 dry-run 测试？ ​

bash
tuniu call ticket query_cheapest_tickets --args '{"scenic_name":"上海迪士尼"}' --dry-run

Q6: 退出码含义？ ​

退出码含义建议操作
0成功解析 stdout JSON
101连接失败重试或检查网络
102工具不存在运行 tuniu list <server> 检查工具名
103参数错误运行 tuniu help <server> <tool> 查看参数
104认证失败检查 API Key
105超时增加 -t 超时或重试
106服务器错误联系服务提供方
107配置错误运行 tuniu config show
108未配置 API Key设置 TUNIU_API_KEY 环境变量
199未知错误使用 --detail 查看详情

Q7: 如何让 AI Agent 使用途牛 CLI？ ​

推荐按“准备环境 → 初始化能力 → 动态发现 → 注册 Skill → 工具调用”五步接入：

  1. 准备运行环境
  • 安装 CLI：npm install -g tuniu-cli
  • 配置 API Key：export TUNIU_API_KEY=your_api_key
  1. 初始化工具能力
  • 执行：tuniu schema --output json
  • 作用：让 Agent 获取最新工具列表、参数结构、必填项，用于意图路由和参数补全。
  1. 开启动态集成能力（可选但推荐）
  • 执行：tuniu discovery refresh（刷新服务列表）
  • 执行：tuniu discovery status / tuniu discovery list（查看发现状态与服务清单）
  • 作用：当平台新增服务或工具时，Agent 能在不改代码的情况下更新可用能力。
  1. 可选：注册 Skill
  • 如需手动安装/更新 Skill，可执行：tuniu skill install
  • 默认行为：仅安装到 ~/.agents/skills/tuniu-cli/（更低侵入性，适合通用 Agent 框架或无特定 Agent 目录时使用）。
  • 如需安装到指定 Agent / 多个 Agent：tuniu skill install cursor 或 tuniu skill install --agent cursor,claude
  • 如需安装到全部内置支持的 Agent：tuniu skill install --agent all
  • 说明：对于未内置适配的 Agent，请使用 tuniu skill install --dir <path> 安装到目标 Agent 的技能目录。
  1. 运行时调用工具

通过 Python subprocess 示例调用 CLI：

python
import subprocess, json

result = subprocess.run(
    ["tuniu", "call", "ticket", "query_cheapest_tickets",
     "-a", '{"scenic_name": "中山陵"}', "--output", "json"],
    capture_output=True, text=True
)
data = json.loads(result.stdout)

在任意 AI Agent 聊天窗口（如 Claude 终端），也可直接输入自然语言指令，Agent 会自动执行对应的 shell 命令：

"帮我用途牛命令行工具查这周六上海迪士尼的低价门票"

Q8: 可以直接配合 Skill 使用吗？ ​

若你的 Agent 运行环境支持安装 Skill，可以先查看 tuniu-cli Skill 说明，再配合其中的 tuniu-cli skill 使用。

适用方式如下：

  • 用户侧：直接描述旅行需求，由 Agent 自动调用 tuniu 命令，无需手动拼接参数。
  • Agent 侧：优先使用统一的 tuniu-cli skill，而不是分别在 flight、hotel、ticket、train、cruise 多个单独 skill 之间切换。
  • 运行前提：底层仍依赖本机已安装 tuniu-cli，并配置好 TUNIU_API_KEY。
  • 注册方式：npm 全局安装通常会由 postinstall 自动完成注册；如需手动安装/更新可执行 tuniu skill install（默认仅写入 ~/.agents/skills/tuniu-cli/；如需安装到指定的内置 Agent 目录可用 --agent）。
  • 其他 Agent：若未内置适配，请使用 tuniu skill install --dir <path> 指定技能安装目录。

Q9: 之前安装过机票、酒店等单独 Skill，现在应该怎么处理？ ​

如果你在安装 tuniu-cli 之前，已通过其他渠道安装过 tuniu-flight、tuniu-hotel、tuniu-ticket、tuniu-train、tuniu-cruise、tuniu-holiday 等单独服务 Skill，推荐按以下方式处理：

推荐方案：删除旧 Skill，统一使用 tuniu-cli ​

tuniu-cli skill 已整合了机票、酒店、门票、火车票、邮轮、度假产品等全部服务能力，且调用方式更简洁（统一通过 tuniu call 命令），无需在多个 skill 之间切换。建议：

  1. 删除已安装的单独 Skill：到 Agent 对应的 skills 目录下，手动删除旧的 skill 子目录。
bash
# 以 Cursor 为例，删除旧的单独 Skill
rm -rf ~/.cursor/skills/tuniu-flight
rm -rf ~/.cursor/skills/tuniu-hotel
rm -rf ~/.cursor/skills/tuniu-ticket
rm -rf ~/.cursor/skills/tuniu-train
rm -rf ~/.cursor/skills/tuniu-cruise
rm -rf ~/.cursor/skills/tuniu-holiday

# 以 Claude 为例
rm -rf ~/.claude/skills/tuniu-flight
rm -rf ~/.claude/skills/tuniu-hotel
rm -rf ~/.claude/skills/tuniu-ticket
rm -rf ~/.claude/skills/tuniu-train
rm -rf ~/.claude/skills/tuniu-cruise
rm -rf ~/.claude/skills/tuniu-holiday

# 通用目录
rm -rf ~/.agents/skills/tuniu-flight
rm -rf ~/.agents/skills/tuniu-hotel
rm -rf ~/.agents/skills/tuniu-ticket
rm -rf ~/.agents/skills/tuniu-train
rm -rf ~/.agents/skills/tuniu-cruise
rm -rf ~/.agents/skills/tuniu-holiday
  1. 确认 tuniu-cli skill 已安装：
bash
# 检查是否已安装
ls ~/.cursor/skills/tuniu-cli/SKILL.md 2>/dev/null && echo "已安装" || echo "未安装"

# 如未安装，执行以下命令
tuniu skill install cursor

两者可以共存吗？ ​

技术上可以共存，不会产生冲突。但同时存在多个 skill 时，Agent 可能会在意图路由时产生困惑（例如用户说"查机票"时不确定该用 tuniu-flight 还是 tuniu-cli）。为避免歧义，建议只保留 tuniu-cli 一个。

新旧 Skill 的主要区别 ​

旧的单独 Skill（如 tuniu-flight）新的统一 Skill（tuniu-cli）
调用方式通过 curl 直接调用 MCP HTTP 接口通过 tuniu call 命令调用
服务覆盖每个 skill 只覆盖一个服务一个 skill 覆盖全部服务
运行依赖仅需 curl需安装 tuniu-cli（Node.js 18+）
动态发现不支持支持（tuniu discovery），新服务上线后可自动发现
维护方式需逐个更新npm update -g tuniu-cli 一次更新全部

Q10: 如何卸载？ ​

bash
npm uninstall -g tuniu-cli

如需同时移除已安装的 Skill，请手动删除对应 Agent 目录下的 tuniu-cli 子目录。

相关文档 ​

Powered by VitePress

Copyright © 2026 途牛旅游网