用途：查询 AI Gateway 已有请求链路追踪（traces），分析流量、成本、延迟、错误率、模型使用、按用户活动、MCP 工具调用等。不适用于给自有应用添加埋点、配置网关模型与限流、查看容器日志或检查平台连通性。
主要能力：通过 POST /api/svc/v1/spans/query 查询 span。支持按时间、traceId、spanId、父 span、主体类型与标识、应用名、过滤条件等筛选，可翻页。可按 span 类型过滤 LLM、MCP、MCPGateway；从 spanAttributes 提取 gen_ai.usage.cost、tfy.request_cost、gen_ai.usage.input_tokens、gen_ai.usage.output_tokens 等成本与 token 字段，以及模型信息。filter 支持 spanFieldName、spanAttributeKey、gatewayRequestMetadataKey 三类，操作符含 eq、neq、contains、not_contains、starts_with、ends_with。响应含 span 详情、状态码、时长纳秒、创建主体与 feedbacks，并提供 nextPageToken 分页。
必要用法：先运行 status 技能确认 TFY_BASE_URL 与 TFY_API_KEY 有效。每个查询必须提供 tracingProjectFqn（如 tenant:tracing-project:name）或 dataRoutingDestination（如 default）之一，并给出 ISO 8601 的 startTime；endTime 缺省为当前时间。直接调用 API 时把 TFY_API_SH 设为 scripts/tfy-api.sh 的完整路径。示例：$TFY_API_SH POST '/api/svc/v1/spans/query' '{"startTime": "2026-03-26T00:00:00.000Z", "dataRoutingDestination": "default", "limit": 50, "sortDirection": "desc"}'。结果建议以表格呈现，durationNs 除以 1,000,000,000 得秒。
限制：400 常因缺少必需参数或时间格式错误；401 需检查 API key；空结果需核对时间范围、目标是否存在、过滤是否过严及该时段是否有请求；分页 token 过期需不带 pageToken 重新查询。收费、价格与具体效果暂未提供。