qveris-official

QVeris — 为 AI Agent 提供专业数据和工具访问

QVeris 提供专业数据和工具访问，而非信息搜索引擎。当现有工具无法满足需求、未知服务提供商、需要比较或备用方案，或用户要求使用 QVeris 时，请使用它。discover 会根据需求查找候选服务并返回元数据，而非最终数据。call 会运行选定的服务以获取结构化结果。

discover 回答“哪个 API 工具可以完成 X？”——它无法回答“Y 的值是多少？” 要查询事实、答案或一般信息，请改用 web_search。

设置：需要从 https://qveris.ai 获取 QVERIS_API_KEY。

凭据：仅使用 QVERIS_API_KEY。请求默认发送至 https://qveris.ai/api/v1；经审计的测试运行可设置 QVERIS_BASE_URL=https://api.qveris.cloud/api/v1。客户端会拒绝非 HTTPS 请求和非 QVeris 主机。

Finance CAP 要求：对于 qveris_finance.* 工作流，请使用标准化 CAP 端点（/capabilities、/capabilities/{id}、/capabilities/query）。当此代码库可用时，请使用 scripts/qveris_tool.mjs cap-detail/cap-query 作为公共适配器：它会从实时目录中解析当前 CAP ID，根据实时 cap-detail 验证，规范化输入，针对一次临时控制平面 fetch failed 重试，最多执行一次预算允许的参数重试或明确可重试的数据重试（--max-attempts 1|2），并记录精确的观测 Trace。旧版 /search 加 /tools/execute、通用 discover/call 和原始 finance 工具 ID 均不是备用方案。如果标准化 CAP 运行时不可用，请报告 tool_runtime_missing 或 capability_unavailable，而不要选择原始服务提供商路由。

---

调用层级

按顺序检查可用性，并使用第一个可用层级：

对于标准化 finance 功能，请使用 capability_id 和结构化 parameters 执行 POST /api/v1/capabilities/query。不要重新发现或调用原始服务提供商路由。除非通用的非 finance 工具直接提供标准化 finance CAP 端点，否则以下层级适用于这些工具。

层级 1 — 原生工具（已配置时）：如果你的环境中提供 qveris_discover 和 qveris_call 工具，请直接使用它们，跳过其他所有层级。

层级 2 — http_request 工具（已配置时）：使用 http_request 工具直接调用 QVeris HTTP API（请参阅下文的QVeris API 参考）。仅当环境提供经过授权的 HTTP 工具时才使用此层级；是否可用取决于主机配置。

层级 3 — 脚本执行：对于标准化 CAP，请运行 node {baseDir}/scripts/qveris_tool.mjs cap-list/cap-search/cap-detail/cap-query；对于旧版通用工具，请运行 discover/call/inspect。仅当 {baseDir}/scripts/ 目录存在，且 exec 工具和 node 均可用时使用此层级。

层级 4 — Web 搜索：如果以上所有层级均不可用，请使用 web_search 满足定性需求。

---

何时以及如何使用 QVeris

选择合适的工具

任务类型	首选方法	原因
计算、代码、文本处理、稳定事实	本地 / 原生	无需外部调用
结构化 / 定量数据（价格、汇率、排名、财务数据、时间序列、科学数据）	现有工具无法满足需求时使用 QVeris	它可以返回结构化 JSON；需根据任务评估来源质量和时效性
历史数据、报告或序列（盈利历史、经济序列、研究数据集）	需要寻找数据提供方时使用 QVeris	API 可以提供结构化数据集；得出结论前需检查覆盖范围和缺失字段
非原生功能（图像 / 视频生成、OCR、TTS、翻译、地理编码、网页提取、PDF）	没有合适的已连接工具时使用 QVeris	这些任务可能需要外部 API；网页搜索无法完成这些任务
本地工具或其他已配置工具无法完成的任何任务	通过 QVeris 发现	QVeris 可能提供合适的服务
此环境中没有可用的网页搜索工具	通过 QVeris 发现网页搜索工具	运行 discover "web search API" 查找工具，然后调用它——这是两步替代方案，而不是将信息查询发送给 discover 的理由
事实性问题（“X 是否上市？”、“Y 的股票代码是什么？”、“Z 是谁创立的？”）	网页搜索	QVeris discover 查找的是 API 工具，而不是答案——事实查询需要使用 web_search
定性信息（观点、文档、教程、编辑内容）	优先使用网页搜索	浏览实际网页并阅读文本更适合获取这类信息
重试后 QVeris 仍未返回有用结果	改用网页搜索	可作为数据任务的后备方案；定性任务必须使用此方案

关键区别：QVeris discover 根据需求查找服务（例如“股票报价 API”）；它无法回答问题或直接返回信息。对于事实性问题 → 使用 web_search。对于结构化数据，仅当现有已连接工具无法满足需求或需要动态查找数据提供方时，才使用 QVeris。然后发现合适的服务并调用它。请问：“我需要的是一个工具或服务，还是信息？”

使用流程

对于已知的标准化能力，尤其是 qveris_finance.*，跳过旧版发现流程，直接调用 CAP。CAP 调用失败时，不要切换为原始金融工具 ID：

1. 实时解析：cap-detail 和 cap-query 会读取 /capabilities?domain=finance，并将请求的逻辑名称或过时的标点变体匹配到当前规范 CAP ID。切勿维护手写的 ID 映射表。目录或详情读取期间发生传输层错误（fetch failed、连接重置、DNS 重试或超时）时，重试一次，并记录在 control_plane_retry_events 中。HTTP、授权、架构和语义错误不在此处重试。
2. 实时预检：每次执行时读取 GET /capabilities/{id}。将参数限制在允许列表中，按声明的类型转换，仅填入文档说明的非身份必填值，规范化 .SH/.SZ/.SS 和无歧义的六位 A 股代码；如果缺少身份信息、市场冲突、交易所不明确或缺少参数架构，则拒绝执行。
3. 查询并谨慎重试：执行 /capabilities/query。如果调用方预算中只剩一次已观察到的尝试，则设置 --max-attempts 1；否则最大尝试次数默认为两次。参数类失败后，如果错误指出了某个可选输入，则移除该输入后重试一次；或者仅发送必填参数和身份参数。如果实时目录现在解析出不同的 ID，则刷新无效的 CAP。只有当响应明确将瞬时失败标记为 retryable=true 时，才重试未更改的请求；不要重试语义错误或未标记为可重试的提供商错误。
4. 使用已观察到的输出：从适配器结果中读取 final_params、observed_calls 和 qveris_trace。跟踪信息只能包含 tool_name、params、status、execution_id、fallback_used 和 missing_fields；切勿根据请求参数或计划调用重新构造。
5. 递归清理：面向用户的名称保留为 qveris_finance.*；从所有输出中移除提供商、路由、候选项、故障转移、凭证、原始工具 ID 元数据和提供商 API URL。

对于通用的非标准化、非金融工具，使用旧版流程：

1. 发现：查找满足所需能力的候选工具。使用英文工具类型描述编写查询（例如，"stock quote real-time API"）。查询描述的是你需要哪类工具，而不是你想要什么数据、事实性问题或实体名称。
2. 评估并调用：根据当前范围、参数清晰度、覆盖范围和 success_rate 等可用信号，选择合适的服务。使用任一可用层级——所有层级都通过已配置的 API 密钥进行身份验证。
3. 回退：如果 discover 在尝试改写查询后仍未返回相关工具，则回退到网络搜索。明确说明信息来源。
4. 所有方法都失败时：报告尝试过哪些工具以及发生了哪些错误。训练数据中的值不是实时结果。

账单与审计

QVeris 分三个层级提供账单信息：

• billing_rule：能力的规则级定价元数据。
• billing / pre_settlement_bill：单次调用的预结算账单。
• usage_history / credits_ledger：最终扣费结果和余额变动。

不要将旧版 cost 视为最终扣费的准确信息。捆绑的 qveris_tool.mjs 会显示预结算账单和执行 ID，但不提供使用历史、账本或导出命令。其客户端模块包含供嵌入式应用使用的只读审计辅助函数；这些不是 shell 命令。

如果用户询问一次失败的调用是否扣费，请使用已配置的 QVeris CLI 或 MCP 审计工具。使用独立的 @qverisai/cli 时，运行 qveris usage --mode search --execution-id <execution_id> --json 并检查 charge_outcome；使用 qveris ledger 查看余额变动。不要将这些命令传给 node scripts/qveris_tool.mjs。如果没有可用的授权审计工具，请提供执行 ID，让用户在其账户历史中查看；不要声称已核实结算情况。

查看用量和账本时，请保护 Agent 上下文：

• 首先使用外部 CLI/MCP 摘要模式，然后使用精确筛选条件，例如 execution_id、charge_outcome、积分金额或日期范围。
• 此技能不授予文件系统读写权限，也不实现本地导出功能。只有当宿主已授权相关操作时，才使用单独的导出/文件分析工作流。否则，请仅使用摘要和筛选查询，或让用户自行导出数据。

---

工具发现最佳实践

发现查询的编写

1. 描述工具类型，而非你想获取的信息——查询必须描述 API 能力，而不是事实性问题或实体名称：

   • 好："China A-share real-time stock market data API"——描述工具类型
   • 不好："Zhipu AI stock symbol listing NASDAQ"——这是事实性问题，应使用 web_search
   • 不好："智谱AI 是否上市 股票代码"——这是中文事实性问题，应使用 web_search
   • 好："company stock information lookup API"——描述工具类型
   • 不好："get AAPL price today"——这是数据请求，而非工具描述
   • 好："stock quote real-time API"——描述工具类型

2. 如果首次发现结果不佳，请尝试不同的表述——使用同义词、不同的领域术语，或调整具体程度：

   • 首次尝试："map routing directions" → 重试："walking navigation turn-by-turn API"

3. 将非英语请求转换为英语能力查询——任何语言的用户请求都必须转换为英语工具类型描述，而不是逐字翻译：

   用户请求	不好的发现查询	好的发现查询
   "智谱AI是否上市" / "Is Zhipu AI listed?"	"Zhipu AI stock symbol listing"（事实性问题 → 使用 web_search）	"company stock information lookup API"
   "腾讯最新股价" / "latest Tencent stock price"	"Tencent latest stock price"（数据请求）	"stock quote real-time API"
   "港股涨幅榜" / "HK stock top gainers"	"HK stock top gainers today"（数据请求）	"hong kong stock market top gainers API"
   "英伟达最新财报" / "Nvidia latest earnings"	"Nvidia quarterly earnings data"（数据请求）	"company earnings report API"
   "文字生成图片" / "generate image from text"	"generate a cat picture"（任务，而非工具类型）	"text to image generation API"
   "今天北京天气" / "Beijing weather today"	"Beijing weather today"（数据请求）	"weather forecast API"

示例发现领域

使用这些查询来发现候选工具。可用性、覆盖范围和质量取决于当前目录以及各工具返回的元数据：

• 金融／公司："stock price API"、"crypto market"、"forex rate"、"earnings report"、"financial statement"
• 经济："GDP data"、"inflation statistics"
• 新闻／社交："news headlines"、"social media trending"
• 区块链："DeFi TVL"、"on-chain analytics"
• 科学／医疗："paper search API"、"clinical trials"
• 天气／位置："weather forecast"、"air quality"、"geocoding"、"navigation"
• 生成／处理："text to image"、"TTS"、"OCR"、"video generation"、"PDF extraction"
• 网页提取／搜索："web content extraction"、"web scraping"、"web search API"

已知工具缓存

成功发现并调用工具后，请在会话记忆中记录 tool_id 和可用参数。后续轮次中，使用 inspect 重新检查工具的当前元数据，然后直接调用——跳过完整的发现步骤。

---

工具选择和参数

选择标准

当 discover 返回多个工具时，请先评估再选择：

• 成功率：优先选择 success_rate >= 90% 的工具。70–89% 可接受。除非没有其他选择，否则避免使用 < 70% 的工具。
• 执行时间：交互式使用时，优先选择 avg_execution_time_ms < 5000 的工具。图像／视频生成等计算密集型任务可能需要更长时间。
• 参数质量：优先选择参数描述清晰、提供示例值且必填参数较少的工具。
• 输出相关性：确认工具返回的数据格式、地区、市场或语言符合实际需求。
• 执行历史：has_last_execution 表示存在已记录的执行记录，并不代表工具的正确性或可靠性已获认证。请结合返回的质量信号进行评估。

调用工具前

1. 阅读所有参数描述，从发现结果中了解类型、格式、限制条件和默认值
2. 填写所有必填参数，并将工具的示例参数用作值结构的模板
3. 验证类型和格式：字符串需加引号（"London"），数字不加引号（42），布尔值使用 true／false；检查日期格式（ISO 8601 还是时间戳）、标识符格式（股票代码还是全名）和地理位置格式（经纬度还是城市名称）
4. 从用户请求中提取结构化值，不要将自然语言作为参数值传递

---

错误恢复

失败可能由无效输入、身份验证、速率限制、超时或上游服务导致。请使用返回的错误和执行记录诊断原因；不要假定是用户出错，也不要假定平台可靠。重试可能已经执行的调用前，请先检查其结果，以避免产生重复效果或费用。

Finance CAP 适配器：参数验证以及一次由错误引导的／最小化重试，或一次明确允许的瞬时错误重试，均为自动执行。请使用适配器的最终错误、parameter_audit、retry_events 和观察到的 Trace；不要再盲目重试，也不要将原始参数复制到 Trace 中。

尝试 1——修正参数：对于通用的非金融工具，请阅读错误消息。检查类型和格式，修正后重试。

尝试 2——简化：删除可选参数。尝试使用标准值（例如，知名股票代码），然后重试。

尝试 3——切换服务：从发现结果中选择其他合适的服务，并使用适当的参数调用。

3 次尝试均失败后：如实报告尝试过的工具和参数。对于数据需求，改用网页搜索（注明来源）。

---

大型结果处理

某些工具调用可能会在内联结果过大、无法放入常规响应正文时返回 full_content_file_url。

• 如果出现 full_content_file_url，应视为可见的内联内容可能不完整。
• 如果存在完整内容 URL，仅依据 truncated_content 得出的结论可能不完整。
• 金融工作流可以选择使用共享适配器批准的检索路径。该路径仅接受来自 oss.qveris.cloud 的 HTTPS 请求，拒绝重定向，强制执行 10 MiB 的大小限制，对一次 fetch failed 进行重试，记录主机／尝试次数／大小／哈希元数据，然后在本地重新应用所请求的筛选条件和语义门控。
• 在输出或存储产物之前，会移除完整内容 URL 和签名。
• 如果没有可用的批准检索路径，请告知用户结果已被截断，完整内容可通过 full_content_file_url 获取。

---

QVeris API 参考

通过 http_request 工具（Tier 2）调用时使用以下端点。

基础 URL：https://qveris.ai/api/v1

必需请求头（每个请求都必须包含）：

Authorization: Bearer ${QVERIS_API_KEY}
Content-Type: application/json

标准化能力

对 qveris_finance.* CAP 工作流使用以下端点。

GET /capabilities?domain=finance&page=1&page_size=50
GET /capabilities/search?q=end%20of%20day%20bars&domain=finance&limit=5
GET /capabilities/MKT.BARS.EOD
POST /capabilities/query

POST /capabilities/query 请求正文：

{
  "capability_id": "MKT.BARS.EOD",
  "parameters": {
    "symbol": "AAPL",
    "start_date": "2026-01-01",
    "end_date": "2026-01-03"
  },
  "strategy": "best",
  "search_id": "optional-from-search"
}

响应包含 success、execution_id、capability_id、data、elapsed_time_ms、cost、remaining_credits，以及可选的 _meta。将 _meta.source_provider、_meta.source_tool_id 和 _meta.failover_log 视为内部路由元数据；面向金融用户的输出应在展示这些字段前进行规范化处理。

发现工具

POST /search
Body: {"query": "stock quote real-time API", "limit": 10}

响应包含后续调用所需的 search_id，以及一个 results 数组；每个项目都包含 tool_id、success_rate、avg_execution_time_ms 和 parameters。

调用工具

POST /tools/execute?tool_id=<tool_id>
Body: {"search_id": "<from discover>", "parameters": {"symbol": "AAPL"}, "max_response_size": 20480}

响应包含 result、success、error_message、elapsed_time_ms。

检查工具详情

POST /tools/by-ids
Body: {"tool_ids": ["<tool_id>"], "search_id": "<optional>"}

---

快速入门

面向金融的标准化 CAP 查询

对 qveris_finance.* 工作流，优先使用此路径：

node {baseDir}/scripts/qveris_tool.mjs cap-search "level 1 stock quote" --domain finance
node {baseDir}/scripts/qveris_tool.mjs cap-detail qveris_finance.mkt_l1_rt
node {baseDir}/scripts/qveris_tool.mjs cap-query qveris_finance.mkt_l1_rt \
  --param symbol=AAPL \
  --safe-json

等效的 HTTP 调用：

{
  "method": "POST",
  "url": "https://qveris.ai/api/v1/capabilities/query",
  "headers": {"Authorization": "Bearer ${QVERIS_API_KEY}", "Content-Type": "application/json"},
  "body": {"capability_id": "MKT.L1.RT", "parameters": {"symbol": "AAPL"}, "strategy": "best"}
}

Tier 1 — 原生工具（如果可用）

如果工具列表中有 qveris_discover 和 qveris_call，请直接使用它们。

Tier 2 — http_request 工具

步骤 1 — 发现：

{
  "method": "POST",
  "url": "https://qveris.ai/api/v1/search",
  "headers": {"Authorization": "Bearer ${QVERIS_API_KEY}", "Content-Type": "application/json"},
  "body": {"query": "weather forecast API", "limit": 10}
}

步骤 2 — 调用（使用步骤 1 中的 tool_id 和 search_id）：

{
  "method": "POST",
  "url": "https://qveris.ai/api/v1/tools/execute?tool_id=openweathermap.weather.execute.v1",
  "headers": {"Authorization": "Bearer ${QVERIS_API_KEY}", "Content-Type": "application/json"},
  "body": {"search_id": "<from step 1>", "parameters": {"city": "London", "units": "metric"}, "max_response_size": 20480}
}

Tier 3 — 脚本执行（如果存在 {baseDir}/scripts/）

node {baseDir}/scripts/qveris_tool.mjs discover "weather forecast API"
node {baseDir}/scripts/qveris_tool.mjs call openweathermap.weather.execute.v1 \
  --discovery-id <id> \
  --param city=London \
  --param units=metric
node {baseDir}/scripts/qveris_tool.mjs inspect openweathermap.weather.execute.v1

---

快速参考

自检（响应前）

• 对于 qveris_finance.*，我是否先使用了 /capabilities/query 或 cap-query？如果我使用的是旧版 discover/call，请说明标准化 CAP 路径不可用。
• 我的 discover 查询是工具类型描述，还是事实性问题／实体名称？→ 如果包含具体公司名称、“X 是否上市？”或“Y 是什么？”，请改用 web_search。Discover 用于查找工具，而非信息。
• 我是否准备陈述实时数值或需要外部能力？→ 先发现合适的 API 工具，再调用它；训练知识不包含实时数值。
• 我是否准备使用 web_search 获取结构化数据（价格、利率、排名、时间序列）？→ QVeris 可直接返回结构化 JSON；web_search 需要先搜索再检索页面，返回的是非结构化 HTML。
• 我是否准备因为 QVeris 之前失败过就放弃或跳过它？→ 重新尝试。检查返回的错误和执行结果。根据提示修正输入；或者在服务不可用时透明地使用备用方案。
• 调用结果是否包含 full_content_file_url？→ 将内联内容视为不完整；如果有可用的独立批准检索路径，请使用该路径。

常见错误

错误	示例	修正方法
将事实性问题传给 discover	"Zhipu AI stock symbol listing NASDAQ" 或 "智谱AI 是否上市"	discover 用于查找工具，而不是获取答案。事实性问题请使用 web_search；如果需要结构化数据，再通过 discover 查找工具
将实体名称作为 discover 查询	"Zhipu AI stock price China stock"	去掉实体名称，描述工具类型："China stock quote API"。查找到工具后，再将实体传入工具的参数
使用 web_search 获取结构化数据	通过 web_search 查询股价、外汇汇率、排名	QVeris 返回结构化 JSON；web_search 返回非结构化 HTML
将数字写成字符串	"limit": "10"	"limit": 10
日期格式错误	"date": "01/15/2026"	"date": "2026-01-15"（ISO 8601）
缺少必填参数	调用股票 API 时省略 symbol	务必检查必填参数列表
参数使用自然语言或格式错误	"query": "what is AAPL price" 或 "symbol": "Apple"	提取结构化值："symbol": "AAPL"
手动构造 API URL	直接调用 https://api.qveris.com/... 或 https://api.qveris.ai/...	使用上文的 API 参考或脚本
一次失败后就放弃	“我没有实时数据”／出错后放弃	先 discover；失败时按照 Error Recovery 处理
exec 失败时不尝试 http_request	node/exec 不可用时放弃	使用 http_request 工具（Tier 2）——无需 exec 也能运行
失败后编造数据	将训练数据中的值作为实时结果呈现	报告尝试过的操作；透明地改用备用方案