接入指南

Appearance

常见问题 ​

Q1: 推荐使用哪种认证方式？ ​

推荐使用 OAuth，首次使用执行：

bash
tuniu auth login
tuniu auth status

如果运行环境无法打开浏览器，可使用 API Key 作为兜底。前往 途牛开放平台 注册并登录账号后获取 API Key。

Q2: 提示需要 OAuth 登录怎么办？ ​

执行：

bash
tuniu auth login
tuniu auth status

若当前环境不能完成浏览器授权，可改用 API Key：

bash
export TUNIU_API_KEY=your_api_key
export TUNIU_AUTH_TYPE=apiKey

Q3: 如何强制选择 OAuth 或 API Key？ ​

通过 TUNIU_AUTH_TYPE 选择认证方式：

bash
export TUNIU_AUTH_TYPE=oauth   # 强制 OAuth，不发送 API Key
export TUNIU_AUTH_TYPE=apiKey  # 强制 API Key
export TUNIU_AUTH_TYPE=auto    # 默认：有 API Key 时优先使用，否则使用 OAuth

认证方式的优先级为：环境变量 > 服务配置 / Discovery 配置 > 内置默认值。

如需退出当前 OAuth 授权：

bash
tuniu auth logout

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通用认证失败普通服务检查 OAuth / TUNIU_API_KEY；TTMS 服务检查 TUNIU_TTMS_API_KEY
105超时增加 -t 超时或重试
106服务器错误联系服务提供方
107配置错误运行 tuniu config show
108未配置 API Key普通服务优先 tuniu auth login；TTMS 服务设置 TUNIU_TTMS_API_KEY
109API Key 无效更新 TUNIU_API_KEY，或改用 OAuth
110需要 OAuth 登录执行 tuniu auth login
111OAuth 授权失败检查授权流程或网络后重试
112OAuth token 刷新失败重新执行 tuniu auth login
199未知错误使用 --detail 查看详情

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

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

  1. 准备运行环境
  • 安装 CLI：npm install -g tuniu-cli
  • 推荐完成 OAuth 授权：tuniu auth login
  • 无法使用浏览器时再配置 API Key：export TUNIU_API_KEY=your_api_key

在 WorkBuddy 等会捕获授权 URL、随后结束 auth 子进程的环境中，使用：

bash
tuniu auth login --daemon
tuniu auth status --daemon
  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 auth login，无法使用浏览器时再配置 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），新服务上线后可自动发现
维护方式需逐个更新tuniu update（或 npm install -g tuniu-cli@latest）一次更新全部

Q10: 如何卸载？ ​

bash
npm uninstall -g tuniu-cli

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

Q11: 如何更新？ ​

推荐使用一键更新命令（全局 npm 安装场景）：

bash
# 检查是否有新版本（不安装）
tuniu update --check

# 更新 CLI，并同步刷新本机已安装的 Agent Skill
tuniu update

# 只更新 CLI，不刷新 Skill
tuniu update --cli-only

# 更新到指定版本
tuniu update --to 1.1.2

说明：

  • tuniu update 会查询 npm latest，执行 npm install -g tuniu-cli@<version>；安装前会清理 .tuniu-cli-* 残留临时目录，遇 ENOTEMPTY 时自动卸载后重装。
  • 默认会刷新本机已经安装过的 Agent Skill 目录（如 ~/.cursor/skills/tuniu-cli/、~/.codex/skills/tuniu-cli/）；未装过的 Agent 不会新建。
  • 仅刷新 Skill（不升级 CLI）请用：tuniu skill install（可加 --agent / --dir）。
  • 源码开发 / npm link / npx 场景无法原地全局升级，请按提示改用手动安装或在仓库内更新代码。

也可手动升级：

bash
npm install -g tuniu-cli@latest
tuniu skill install --agent / --dir   # 如需同步刷新内置 Skill
tuniu -V

相关文档 ​

Powered by VitePress

Copyright © 2026 途牛旅游网