# 数据查询

## 工具：`query_tool`

统一的 Keep 数据查询入口。用户的任何运动品类记录、身体数据、健康数据查询都调这一个工具，具体数据域与统计口径由服务端根据 `text` 自动识别与路由，Agent **不需要**预先分类。

## 使用场景

- 用户想查询运动明细数据：如「查一下我这个月跑步的详情」「查询我本周的运动详情」「本月我的步行数多少」
- 用户想查询运动品类统计数据：如「查一下我这个月跑步的公里数」「上周运动总时长是多少」「本年我运动了多长时间」
- 用户想查看身体数据：如「我最近一次体重是多少」「帮我看下我的腰围是多少」「」
- 用户想查看健康数据：如「我最近的饮食是什么」「我的睡眠时长是多少」「我的经期记录」

## 参数说明

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `text` | string | 是 | 用户的原始查询描述。保留自然语言与关键信息：数据类型、时间范围、统计口径（如"查一下我这个月每天跑步的公里数"） |

### `text` 组织建议

Agent 不做分类，但应**保留原始信息的完整度**，让服务端能正确路由：
不要主动追问用户补齐字段——如果缺失（例如只说了"我最近体重多少"），直接按原话传给 `query_tool`，由服务端决定返回最近一条还是需要更多信息。

## 调用示例

exec 方式（OpenClaw / Hermes）：

```bash
node {baseDir}/scripts/mcp-call.js query_tool '{"text":"查一下我这个月每天跑步的公里数"}'
```

原生 MCP 方式：

```json
{
  "method": "tools/call",
  "params": {
    "name": "query_tool",
    "arguments": {
      "text": "查一下我这个月每天跑步的公里数"
    }
  }
}
```

## 结果展示原则

Agent 不应编造缺失数据，也不应自行计算未由上游返回的统计值。上游返回内容作为事实来源。

- **优先展示返回内容**：如果上游有返回内容，则展示完整的上游返回内容
- **空结果**：说明没有查到对应数据，并提示用户换一个时间范围或数据类型
- **错误**：保留可行动提示，例如稍后重试或重新登录

## 返回与异常

`query_tool` 走绝对 URL 上游（`NLP_SPORTS_BASE`），Gateway 将上游 JSON **原样透传**给 MCP 调用方（不会像 Keep 相对路径 API 那样剥 `ok/errorCode` envelope）。常见成功形态可能是 `{ ok: true, ... }` 或 `{ data: { ... } }`，以实际上游为准。

Agent 按 [SKILL.md 的「结果呈现」](../SKILL.md#结果呈现) 从返回体中提取业务字段并格式化给用户，不要假设固定 schema。

常见错误码：`AUTH_REQUIRED` / `TOKEN_EXPIRED`（回 [鉴权流程](auth.md)）、`RATE_LIMITED`、`UPSTREAM_ERROR`。完整表见 [SKILL.md 通用错误码](../SKILL.md#通用错误码)。