> ## Agent Instructions
>
> Base URL: https://api.anysite.io
> Authentication: send the `access-token` header. Do NOT use `Authorization: Bearer`.
> Full endpoint catalog: https://app.anysite.io/docs
# 数据分析

对通过 MCP 服务器获取的数据进行分页、筛选、聚合、合并和导出，无需发起新的 API 调用。

目标：用 `execute` 获取一次数据，然后在服务器端处理完整结果，而不是重新获取或把全部数据加载进对话。

通常你只需要用自然语言告诉客户端（比如“只保留柏林的，导出一个 CSV”）；这些工具由客户端自行选用。
本页说明它们各自的作用，方便你知道该怎么提要求。

## 缓存是如何工作的

1. `execute` 会把**完整**结果存在服务器上，并返回前 10 条结果、`total` 和一个 `cache_key`。如果还有
   更多条目，响应中还会带 `next_offset`。
2. 下面的每个工具都使用这个 `cache_key`。它们都不会重新调用数据源，也都不消耗用量。
3. 缓存结果和你的 `execute` 调用历史会保留 7 天。之后，`cache_key` 会返回
   `No data found for this cache_key. It may have expired — re-run execute().`

## 分页浏览结果

`get_page(cache_key, offset, limit)` 返回从 `offset` 开始的条目，并带有 `next_offset` 和 `has_more`。
一页最多包含 50 条；如果 `limit` 更大，会返回 50 条以及提示从 `next_offset` 继续获取。

## 筛选与排序

`query_cache(cache_key, conditions, sort_by, sort_order, limit, offset)` 返回匹配的条目及其 `total`。

```json
{
  "cache_key": "<cache_key>",
  "conditions": [
    {"field": "location", "op": "contains", "value": "Berlin"},
    {"field": "follower_count", "op": ">", "value": 1000}
  ],
  "sort_by": "follower_count",
  "sort_order": "desc",
  "limit": 10
}
```

- 所有条件都必须满足（AND）。
- 运算符：`=`、`!=`、`>`、`<`、`>=`、`<=`、`contains`、`not_contains`。`contains` 和 `not_contains` 不
  区分大小写；`>`、`<`、`>=`、`<=` 用于数值比较。
- 嵌套字段用点号表示，例如 `"field": "company.name"`。
- `sort_order` 为 `asc`（默认）或 `desc`。
- 字段名就是 `execute` 返回的条目中的字段名。如果没有任何匹配但缓存中确实有数据，工具会给出提示 ——
  检查字段名和取值是否正确。

## 聚合

加上 `aggregate` 可以得到一个数字，而不是一批条目：

```json
{"cache_key": "<cache_key>", "aggregate": {"field": "follower_count", "op": "avg"}}
```

- 函数：`count`、`sum`、`avg`、`min`、`max`、`uniq`（不同值的数量）。`count` 不需要指定字段。
- 加上 `group_by` 可以按组返回每组一个值，按从大到小排序，最多 `limit` 个组（默认 10 个）：
  `{"aggregate": {"op": "count"}, "group_by": "industry"}` 会返回 `{"groups": {"Software": 42, ...}}`。
- `conditions` 会在聚合之前应用。

## 合并多个结果

`merge_data(cache_keys, dedupe_by)` 把 2 到 20 个缓存结果（总共最多 10 万行）合并成一个新的
`cache_key`，本页的每个工具都可以直接使用它。

- 完全相同的行始终会被合并去重。
- `dedupe_by`（最多 10 个字段名，例如 `["url"]`）还会合并这些字段取值相同的行。如果其中任何字段缺失
  或为空，该行会被保留，并计入 `rows_without_key`。
- 已过期的 key 会被跳过并在提示中列出；其余的会被正常合并。

## 导出文件

`export_data(cache_key, output_format, list_unpack)` 返回一个 `file_url`、行数 `total`、文件大小和一份
预览。

- 格式：`json`（默认）、`csv`、`jsonl`、`xlsx`。
- 导出始终包含该 `cache_key` 下的**全部**条目。`query_cache` 的筛选条件不会缩小导出范围。如果要把多次
  获取的结果导出为一个文件，先用 `merge_data` 合并，再导出合并后的 key。
- `list_unpack`（仅 CSV 和 XLSX，取值 0–255，默认 1）设置每个嵌套列表中有多少个条目会被展开成单独的
  列。
- 下载链接不需要密钥 —— 任何拿到链接的人都能下载文件，所以数据敏感时不要分享该链接。只要缓存结果还
  在，链接就会一直有效。

## 查找之前的结果

`search_requests(source, category, endpoint, query, since, until, limit, offset)` 按时间从新到旧列出你
之前的 `execute` 调用，包含参数、条目数、时间和 `cache_key`。`query` 会匹配参数中的文本；`since` 和
`until` 接受 ISO 8601 格式的时间。用它代替重新获取同样的数据。

## 故障排查

| 消息 | 解决方法 |
|---|---|
| `No data found for this cache_key. It may have expired — re-run execute().` | 结果已超过 7 天，或 key 不正确。请重新获取。 |
| `No items matched the given conditions (N items in cache). Check condition fields and values.` | 字段名或取值与条目不匹配。先用 `get_page` 看一条具体的条目。 |
| `Invalid operator: …` / `Invalid aggregate: …` | 请使用上面列出的运算符或函数之一。 |
| `Unsupported format '…'. Use: json, csv, jsonl, xlsx` | 请选择一个受支持的 `output_format`。 |
| `cache_keys must contain at least 2 different cache_key values` / `Too many cache_keys` / `Too many rows to merge` | 合并的结果数量应在 2 到 20 个之间，总行数不超过 10 万行。 |