# BioRadar

用途：检索并总结近期新闻、时事、宏观与行业动态，返回话题级整合结果，而不是零散网页链接。适合回答“最近发生了什么”“这件事会如何影响某个市场/行业”“某个热点背后的上下文是什么”。

## 何时触发
- 用户询问“最近 / 近期 / 最新”发生了什么
- 用户要求分析新闻、时事、宏观事件对市场、商品、行业、公司、政策的影响
- 用户想快速获得某个热点的背景、本周进展、最新动态、上下游话题关系
- 用户的问题核心是“新闻动态整合与解读”，而不是查单一事实或单篇文章

示例：
- “近期石油情况怎么样？”
- “霍尔木兹海峡局势会不会影响油价？”
- “最近 AI 行业新闻有什么重点？”
- “最近中美贸易摩擦有哪些新变化？”
- “近期黄金价格波动背后的新闻主线是什么？”

## 与 WebSearch 的选择
优先使用 BioRadar：
- 目标是得到“新闻主线 + 背景 + 最近进展 + 最新变化”的整合结果
- 需要从事件角度理解市场、行业或宏观影响
- 用户更需要概括、脉络和关联话题，而不是网页列表

优先使用 WebSearch：
- 用户要查单一事实、精确数字、公司公告、原文链接、官网文档
- 用户明确要来源链接或媒体原文
- 问题与新闻动态无关

## 调用策略
- 不要默认把 BioRadar 当成一次性查询工具。
- 先用一轮查询识别主话题，再判断是否需要继续补充查询。
- 如果首轮结果暴露出新的参与方、相邻驱动因素、相互矛盾的信号、时间线缺口或未解释清楚的因果关系，应继续追加查询。
- 只有在已经足够回答用户问题时才停止，不必固定调用轮数。

### 多话题问题的处理
- 如果用户一句话里包含多个话题，不要把它们混成一个 query 直接检索。
- 应先拆成多个单独话题，再按顺序分别调用 API。
- 常见需要拆分的形式包括：
  - 多个资产：如“黄金、原油、美元最近怎么了”
  - 多个地区或国家：如“中美欧最近贸易关系如何”
  - 多个公司或行业：如“英伟达、特斯拉、苹果最近有哪些大事”
  - “A 对 B 的影响”里同时需要先理解 A、再分析对 B 的传导
- 拆分后，先回答每个子话题的核心进展，再在最后做横向归纳。

### 何时继续追加查询
- 需要补足时间线
- 需要区分“直接原因”和“背景因素”
- 首轮结果出现新的关键词、地区、机构、资产或政策线索
- 不同结果之间存在张力或表述不一致
- 用户的问题本质上要求“全面理解”而不是“快速摘要”

### 迭代查询要求
- 可以根据上一轮返回结果决定下一轮 query，不必拘泥于用户原话。
- 优先沿着这些线索继续追问：
  - 结果中的 `parent` / `children`
  - `overview` 中出现但尚未展开的关键参与方、政策、地区、商品或机构
  - `weekly` 与 `latest` 之间出现的新变化
- 如果用户只想快速了解，不必展开所有子线；优先保留最关键的主线。

### Few-shot 示例

#### 示例 1：多话题问题要先拆分

用户：
> 最近黄金、原油、美元都发生了什么？

推荐做法：
1. 先把问题拆成三个单独话题：黄金、原油、美元
2. 依次调用三次 `POST /search`
3. 每次先取该话题最相关的主结果
4. 最后把三条主线做横向归纳，说明是否存在共同驱动因素

不要这样做：
- 不要把“黄金、原油、美元最近怎么了”直接作为一个 query 发给 API

可参考的调用方式：
```json
{"query":"近期黄金价格波动背后的新闻主线","top_k":3}
{"query":"近期原油市场变化背后的新闻主线","top_k":3}
{"query":"近期美元走势背后的新闻主线","top_k":3}
```

输出组织建议：
- 先分别总结黄金 / 原油 / 美元的主线
- 再补一句三者之间是否受同一宏观因素驱动，例如地缘政治、通胀预期、央行政策、避险情绪

#### 示例 2：需要基于返回结果继续迭代查询

用户：
> 霍尔木兹海峡局势会不会影响油价？

推荐做法：
1. 第一轮先检索主问题，识别核心话题
2. 读取返回里的 `overview`、`weekly`、`latest`、`parent`、`children`
3. 如果发现还缺少“传导路径”“相关地区”“替代供应”“航运扰动”等关键信息，再发起下一轮查询
4. 最终把多轮结果整合成：事件主线、影响路径、时间线、不确定性

第一轮调用示例：
```json
{"query":"霍尔木兹海峡局势对油价的影响","top_k":3}
```

如果第一轮结果显示：
- `overview` 提到了伊朗、海湾航运、OPEC 供应
- `children` 出现了油轮运输、中东局势、原油出口

则第二轮可以继续查询：
```json
{"query":"霍尔木兹海峡航运扰动对原油运输的影响","top_k":3}
{"query":"中东供应风险对国际油价的影响","top_k":3}
```

输出组织建议：
- 先用 200-300 字说明结论
- 再用简短时间线说明“先发生了什么、随后市场如何反应、现在市场在看什么”
- 如果证据不足，要明确告诉用户哪些环节仍存在不确定性

#### 示例 3：最终回答应如何组织

用户：
> 最近 AI 行业新闻有什么重点？

推荐做法：
1. 先检索 AI 行业主话题
2. 如果结果里出现多个子方向，例如模型发布、监管、芯片供应、融资并购，可按需要追加 1-2 轮查询
3. 最终不要只罗列结果，要整理成一段可直接给用户阅读的回答

回答结构建议：
- 第一段：先给 200-300 字概览，只说最重要的主线
- 第二段：补一个简短时间线，说明“这几天/这周发生了什么”
- 第三段：如果需要，再补影响与不确定性

参考回答风格：
> 最近 AI 行业新闻的主线，集中在三件事：一是头部模型与应用继续快速迭代，竞争焦点从单纯比参数和能力，转向落地速度、成本控制与企业采用；二是监管与版权问题持续升温，行业一边扩张一边面对更明确的合规约束；三是上游算力与芯片供给仍然决定行业节奏，谁能稳定拿到算力、控制推理成本，谁就更容易把产品推向大规模商业化。
>
> 从时间线上看，先是新模型或新产品发布带动关注，随后市场迅速转向讨论商业化效果与实际采用，再往后监管、版权、基础设施瓶颈这些问题重新成为焦点。也就是说，当前 AI 新闻不只是“技术突破”，而是“技术、商业化、监管、供给”四条线在同时推进。
>
> 如果你愿意，我可以继续按“模型进展 / 监管政策 / 芯片与算力 / 重点公司”四个方向拆开讲。

## 输出要求
- 不要只根据第一轮结果作答，要综合多轮结果后给出整合结论。
- 最终答案应尽量组织为：主线、时间线、驱动因素、影响、仍不确定之处。
- 如果用户不需要很多细节，优先给出一个 200-300 字的概览，再补充简短时间线。
- 如果用户需要更细节，再展开 `weekly`、`latest` 或事件列表。

### 结果字段如何理解
- `description`：一句话概括，适合做标题或主线结论。
- `overview`：背景与主线说明，通常可优先提炼其开头 200-300 字作为概览。
- `weekly`：近 7 天进展，适合整理为“本周发生了什么”。
- `latest`：最新动态，适合补在回答开头或时间线末尾。
- `parent`：更上层的话题背景，可用于解释宏观上下文。
- `children`：更细的子话题，可用于判断是否值得继续细分查询。
- `events`：按时间排序的具体事件，适合在用户要求细节、证据或时间线时再展开。
- `score`：语义相关度，仅作辅助，不应机械地把最高分视为唯一正确答案。

BioRadar 是面向 AI Agent 的新闻话题 API，提供话题级语义搜索和信号摘要能力。一次调用可以获取某个新闻话题的背景概述、本周进展、最新动态、层级关系（父话题/子话题）以及可选的关联事件。

## 认证

通过环境变量 `NEWSPILOT_API_KEY` 读取 API Key，以 Bearer Token 方式传递。

```
Authorization: Bearer <NEWSPILOT_API_KEY>
```

API Key 格式为 `np_` 开头的十六进制字符串。注册地址：https://api.newspilot.cc/register

**重要：安装完成后立即引导用户配置 API Key，不要等到第一次调用失败：**
- 检查 `NEWSPILOT_API_KEY` 环境变量是否已设置
- 若未设置，直接给用户两个选项：
  - 让 agent 帮用户完成配置（推荐）：用户提供 API Key 后，由 agent 帮用户写入 `~/.bashrc`、`~/.zshrc` 或对应的 shell 配置文件中
  - 用户自行配置：引导用户 1) 访问 https://api.newspilot.cc/register 注册 2) 登录后前往 https://api.newspilot.cc/dashboard 创建 API Key 3) 在终端运行 `export NEWSPILOT_API_KEY=np_xxxxxxxx`
- Credits 不足（收到 429 错误）：引导用户前往 https://api.newspilot.cc/pricing 查看套餐并充值

## 计费

采用 Credits 预付费模式，按实际返回的话题数量扣费。

| 端点 | 扣费规则 |
|------|----------|
| POST /search | 返回多少个话题扣多少 Credits（即 top_k 的实际结果数） |
| GET /digest/new_signal | max(1, 结果数 / 5) |
| GET /digest/hot_signal | max(1, 结果数 / 5) |

Credits 耗尽时返回 `429 RATE_LIMITED`。

## 数据更新

话题数据按日生成快照。`date` 字段表示对应的 UTC+0 日期。`new_signal` 返回该日新增话题，`hot_signal` 按该日新增事件数排序，属于日级快照而非实时数据。

## Base URL

```
https://api.newspilot.cc/api/v1
```

所有端点返回 JSON。Content-Type: `application/json`。

---

## 端点

### POST /search

输入一段事件描述，返回语义最相关的新闻话题列表。每个话题包含多维度描述和可选的关联事件。

**参数（JSON Body）：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| query | string | 是 | 事件描述。建议直接描述事件本身，避免把多个话题混在一个 query 里 |
| top_k | int | 否 | 返回话题数量，1-20，默认 5 |
| events_per_topic | int | 否 | 每个话题返回的事件数。0=不返回（默认），-1=全部，N=最近 N 条按时间降序 |

**请求示例：**

```bash
printf '{
  "query": "A tech company faces antitrust investigation",
  "top_k": 3,
  "events_per_topic": 2
}' | curl -k -X POST https://api.newspilot.cc/api/v1/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NEWSPILOT_API_KEY" \
  -d @-
```

中文查询示例：

```bash
printf '{
  "query": "中美贸易摩擦升级，双方加征关税",
  "top_k": 3,
  "events_per_topic": 2
}' | curl -k -X POST https://api.newspilot.cc/api/v1/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NEWSPILOT_API_KEY" \
  -d @-
```

**返回结构：**

```json
{
  "results": [
    {
      "description": "话题简要描述（一句话）",
      "overview": "话题的详细背景概述（多段）",
      "weekly": "近七天该话题的发展概况",
      "latest": "最新一条动态摘要",
      "parent": "父话题描述，若不存在为 null",
      "children": ["子话题描述1", "子话题描述2"],
      "score": 0.87,
      "events": [
        {
          "text": "事件原文摘要",
          "channel": "来源频道名称",
          "published_at": "2026-04-15T08:00:00+08:00"
        }
      ]
    }
  ],
  "total": 3
}
```

**字段说明：**

- `description` — 话题的一句话概括
- `overview` — 详细背景叙述，通常最适合先提炼成短概览
- `weekly` — 最近 7 天动态综述
- `latest` — 最新一条相关动态摘要
- `parent` — 上层话题，无则为 null
- `children` — 子话题列表
- `score` — 与查询的语义相似度，范围 0-1，越高越相关
- `events` — 关联的具体新闻事件列表，仅在 `events_per_topic > 0` 时返回

---

### GET /digest/new_signal

获取某个 UTC+0 日期对应的新出现话题信号。数据基于日级快照，访问速度快。

**参数（Query String）：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| limit | int | 否 | 返回信号数量，0-5000；0 表示全部，默认 0 |

**请求示例：**

```bash
curl -k "https://api.newspilot.cc/api/v1/digest/new_signal?limit=10" \
  -H "Authorization: Bearer $NEWSPILOT_API_KEY"
```

**返回结构：**

```json
{
  "date": "2026-04-20",
  "new_signals": [
    {
      "cluster_id": "cluster_xxx",
      "description": "话题简要描述",
      "overview": "详细背景概述",
      "weekly": "近七天发展概况",
      "latest": "最新动态摘要",
      "parent": "父话题描述或 null",
      "children": ["子话题1", "子话题2"],
      "new_events_count": 12,
      "rank": 1
    }
  ],
  "total": 10
}
```

每个信号的主体字段与 `/search` 返回的结果相近，但默认不包含 `score` 和 `events`。服务端底层基于每日快照中的 topic 索引回填完整内容。

---

### GET /digest/hot_signal

获取某个 UTC+0 日期对应的热门话题，按该日新增事件数量排序。

**参数（Query String）：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| limit | int | 否 | 返回信号数量，0-5000；0 表示全部，默认 0 |

**请求示例：**

```bash
curl -k "https://api.newspilot.cc/api/v1/digest/hot_signal?limit=5" \
  -H "Authorization: Bearer $NEWSPILOT_API_KEY"
```

**返回结构：**

```json
{
  "date": "2026-04-20",
  "hot_signals": [
    {
      "cluster_id": "cluster_xxx",
      "description": "话题简要描述",
      "overview": "详细背景概述",
      "weekly": "近七天发展概况",
      "latest": "最新动态摘要",
      "parent": "父话题描述或 null",
      "children": ["子话题1", "子话题2"],
      "new_events_count": 23,
      "rank": 1
    }
  ],
  "total": 5
}
```

`new_events_count` 表示该话题当日新增事件数量；`rank` 表示该话题在当日 digest 中的排序位置。服务端底层基于每日快照中的 topic 索引回填完整内容。

---

## 错误格式

所有错误返回统一 JSON 结构：

```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description"
  }
}
```

| HTTP 状态码 | code | 场景 |
|-------------|------|------|
| 400 | INVALID_QUERY | query 为空或格式错误 |
| 401 | UNAUTHORIZED | API Key 无效或缺失 |
| 429 | RATE_LIMITED | Credits 已耗尽 |
| 500 | INTERNAL_ERROR | 服务器内部错误 |
| 503 | DIGEST_CACHE_UNAVAILABLE / DIGEST_CACHE_INVALID | digest 快照不可用或格式无效 |

---

## Windows 注意事项

在 Windows 环境下使用 curl 调用 API 时，注意以下几点：

1. **SSL 证书**：所有示例已包含 `-k` 参数以跳过 SSL 验证，避免证书链不完整导致的连接失败。

2. **JSON Body 编码**：Windows 的 `cmd.exe` 对单引号和 Unicode 支持不佳。推荐以下任一方式：
   - 使用 PowerShell（原生支持 Unicode）：
     ```powershell
     $body = @{query="中美贸易摩擦"; top_k=3} | ConvertTo-Json -Compress
     Invoke-RestMethod -Uri "https://api.newspilot.cc/api/v1/search" -Method Post -Headers @{Authorization="Bearer $env:NEWSPILOT_API_KEY"} -ContentType "application/json" -Body $body
     ```
   - 使用 WSL 或 Git Bash（与 Linux/macOS 用法一致）
   - 使用 `printf | curl -d @-` 方式传递 JSON（本文档示例已采用此方式，兼容 bash/zsh/Git Bash）