核心用法
QVeris 是专为 AI 代理设计的能力发现与工具调用引擎，采用「先发现、后调用」的两步工作流：
1. `discover` — 通过英文能力描述搜索 API 工具，返回候选工具列表（含成功率、执行耗时、参数说明等元数据）
2. `call` — 选定工具后传入参数执行，获取结构化 JSON 数据
支持四级调用方案：原生工具 → http_request → Node 脚本 → Web 搜索回退，确保环境兼容性。
典型应用场景
- 金融数据：实时股价、加密货币、外汇汇率、财报数据
- 数据服务：经济指标、天气、空气质量、地理位置
- 内容生成：文生图、TTS、OCR、视频生成、PDF 处理
- 学术研究：论文检索、临床试验数据
- Web 能力：网页提取、搜索 API
关键设计原则
- 工具描述 ≠ 信息查询：发现查询必须是「API 能力类型」描述（如
"stock quote real-time API"），而非具体问题（如"AAPL 股价多少"） - 事实性问题应使用
web_search，结构化数据需求优先用 QVeris - 多语言用户请求需转换为英文工具类型描述
显著优点
| 优势 | 说明 |
|------|------|
| **结构化数据质量** | 直接返回 JSON，避免网页解析的噪声与脆弱性 |
| **专业 API 聚合** | 覆盖数千个专业 API，无需单独配置多个服务 |
| **多层级降级** | 从原生工具到 HTTP 到脚本，适应不同安全环境 |
| **工具元数据透明** | 成功率、耗时、参数说明辅助选型 |
| **缓存复用机制** | 记录 `tool_id` 后可通过 `inspect` 直接调用 |
潜在局限
- 认知门槛：用户需区分「工具发现」与「信息搜索」两种模式，易误用
- 英文查询限制：非英语请求需转换能力描述，增加使用摩擦
- API Key 依赖：完全依赖外部服务，无离线能力
- 参数调试成本：失败多为参数格式问题，需反复尝试
- 实时性不确定：工具成功率/耗时为历史统计，非实时保证
适合人群
- 需结构化专业数据的 AI 代理开发者（量化分析、财经、科研）
- 需要非原生能力（图像生成、OCR、TTS）但不愿单独对接服务商的用户
- 企业级 AI 工作流中需统一工具发现层的架构师
常规风险
| 风险类型 | 说明 |
|----------|------|
| **认证泄露** | `QVERIS_API_KEY` 需在环境中配置，存在泄露风险 |
| **数据溯源** | 依赖第三方 API，数据质量与合规性由底层服务商决定 |
| **成本不可控** | 专业 API 调用可能产生费用，需监控用量 |
| **服务依赖** | `qveris.ai` 单点依赖，网络或平台故障将完全不可用 |
| **结果截断** | 大数据量返回 `full_content_file_url`，需额外处理流程 |