Skip to main content
Glama
trend-radar-mcp

trend-radar-mcp

by ngwddd
README.md
# trend-radar-mcp

[![ci](https://github.com/ngwddd/trend-radar-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ngwddd/trend-radar-mcp/actions/workflows/ci.yml)

**v0.4.4** · Python ≥ 3.10 · 零第三方依赖 · MIT

把 [trend-radar](https://github.com/ngwddd/trend-radar) 那个 skill 的**确定性部分**拆出来,做成一个有状态、可并发、按需读取的 **MCP 工具**。

原版 skill 保留不动,作为「判断协议 + 采集引擎」的历史版本;这个仓库是分支重写版。

> 一句话:原版让模型**照着 1,800 行说明书跑八个阶段**;这一版把取数、打分、分桶、记忆交给工具,
> 模型只负责判断与写作——**两次调用完成一份简报**。

---

## 事实清单(v0.4.4,逐项对过代码)

| 项目 | 值 | 出处 |
|---|---|---|
| 版本 | **0.4.4** | `pyproject.toml` / `trend_radar_mcp/__init__.py` |
| MCP 工具 | **4 个**:`radar_scan` / `radar_pack` / `radar_check` / `radar_potential` | `tools.py` 的 `TOOLS`(4 个 schema)与 `HANDLERS`(4 个 handler) |
| 源总数 | 注册表 **42** 个(`status` 全为 `OK`);默认 `deep=false` 会跳过唯一慢源 `arxiv-ai`(`kind: atom`)→ 一次 broad 实际请求 **41** 个、`skipped_slow=1`,`deep=true` 才是 42 | `registry.py` 的 `SOURCES` + `scan.py` |
| 源 · 按 stream | authority **16** / social **22** / trend **4** | 同上,`class` 字段 |
| 源 · 按 domain 标签 | social 14 / ai 23 / science 22(一个源可带多个 domain,故合计 59 > 42) | 同上,`domains` 字段 |
| 已知死路 | **13** 条(列在 `radar://registry` 的 `blocked`) | `registry.py` 的 `BLOCKED` |
| 闸门 | `CREDIBILITY_THRESHOLD = 0.6`;独立印证加成 `+0.12`(上限 1.0) | `registry.py` |
| 源权重覆盖 | 42 个源**全部**显式登记权重,没有落到 `SOURCE_WEIGHT.get(k, 0.50)` 兜底的源(`test_every_source_has_a_weight` 守着) | `registry.py` / `test_core.py` |
| borderline 带 | truth 或 comm 与 0.6 的差 ≤ 0.05 → 即 **0.55–0.65** | `scan.py` |
| 单测 | **38 个**(`Ran 38 tests`,全离线,不联网) | `python -m unittest discover -s tests` |
| 受控文件 | **32 个**(其中 `.py` 21 个) | `git ls-files` |
| 并发 / 限速 | 16 线程;单源超时封顶 10 s;主机间隔 arXiv 3 s、Crossref 0.35 s | `scan.py` / `config.py` |
| 缓存 | 源级 **300 s**(`SOFT_TTL`),没有后台刷新 | `scan.py` |
| 响应预算 | `radar_scan` ≤ **8000 字节**(超了先削分桶、再削 picks/briefs) | `tools._fit` |
| CI | Python 3.10 / 3.11 / 3.12 / 3.13 | `.github/workflows/ci.yml` |

---

## v0.4.4(2026-10-21)· 潜力新闻(opt-in 支路)

v0.4.0 加这个工具;v0.4.1「凌晨自动补潜力」;v0.4.2 **去掉凌晨时间限制**(任何时间没热点就补);
v0.4.3 AI / science 候选按主题命中过滤;v0.4.4 清掉本机绝对路径、测试数 33 → 38。
默认路径不变:`radar_scan` / `radar_pack` / `radar_check` 的参数、返回、耗时都不动。
新增第 4 个工具 `radar_potential`:

- **复用**同一个 `scan()` 与 300 s 缓存;5 分钟内有同 scope、同 `days` 的 run 就直接读它(**0 网络**)
- **不建新表**:每个事件的“新增独立源”从已有 `runs/*.json` 的差集算
- 只做数值预排:新增源速度、突发率、源层级 → **默认 8 条、上限 12 条**候选(同一主源最多 2 条)
- 语义判断交给模型;`candidates` 独立命名空间,**永不与 core/watch 混排**
- 异常只降级:无历史按层级+新鲜度(封顶 60 分)、富集超 1.5 s 回退、`try/except` 不外溢

热度还没起来(凌晨,或一整天都没热点)时用它;它不是“已确认新闻”,每条都带 `caveat: 潜力(未验证)`。

**自动触发(任何时间)**:只要 `radar_scan` 的 `notice` 提示 `core` 为空、或 `core` 里只有论文/单源硬证据,就说明今天没有热点新闻,模型会**自动补一次** `radar_potential`,不需要用户开口。有明确热点时不调用。

完整设计说明:[docs/design-v0.4.md](docs/design-v0.4.md)

---

## v0.3(2026-10-19)· 两轮完成

| 改动 | 之前 | 现在 |
|---|---|---|
| 模型轮次(典型) | 判类 → scan → entries → 写(4 轮) | **scan → 写(2 轮)** |
| 工具数 | 6 | **3**(scan / pack / check;v0.4 起多一个 `radar_potential`,共 4 个) |
| 判 scope | 模型先判,判不了才 broad | **工具内自动判**;判不进/跨类 → broad |
| 摘要 | 单独再调一次 entries | **scan 内联 briefs**(默认共 3 条,core 优先、再 watch) |
| 传播分 | 按独立源**数量**阶梯 | **按独立源质量加权**(低质转载不抬分) |
| 真值分 | corroboration 同时加 truth 和 comm | **只加 comm**(去掉双重计数) |
| 边界样本 | 0.59 / 0.61 处置相反 | **borderline 带**(0.55–0.65)标出来 |
| arXiv API | 每轮都抓(18 s 量级) | **默认跳过**,`deep=true` 才抓 |

v0.3 实测(2026-10-19):单类冷启 5–9 s(墙钟 = 最慢的源)、broad 冷启 ~13 s、缓存命中 **0.07 s**;扫描响应 5.9–7.3 KB(含 3 条摘要)。
这几个是当时的读数,现在以代码里的硬约束为准:**响应 ≤8000 字节**、**缓存 300 s**、**单源超时封顶 10 s**(v0.3.1 加的 `TIMEOUT_CAP`)——冷启的实际墙钟取决于当天有几个源在超时边缘。
**没有后台任务**:缓存只在请求路径上读写,超过 300 s 就重新抓;不做定时刷新、不做启动预热。

完整设计说明:[docs/design-v0.3.md](docs/design-v0.3.md) · 上一版:[docs/design-v0.2.md](docs/design-v0.2.md)

---

## 架构

![pipeline](docs/pipeline-v0.3.png)

```
radar_scan(query)
        │
        ├─ 自动判 scope(三类 / broad)· 选源(跳过 dead / 空源 / 慢源)
        ├─ 16 线程并发 + 按主机限速(arXiv 3s / Crossref 0.35s)+ 单源超时封顶 10s
        ├─ 源级缓存 300s(SOFT_TTL)→ 命中即返回(无后台刷新)
        ├─ 归一化 → 时间窗 → 事件级去重 → 勘误过滤
        ├─ SQLite:first_seen / times_seen / source_health
        ├─ truth = 0.4·源权重 + 0.6·证据权重
        │          (社会域换 0.30·平台 + 0.70·证据形式;热度榜硬压 0.45;
        │            无正文封顶 0.50;导购标题 −0.25 / 正文 −0.10)
        │  comm  = 独立源质量加权 → 0.6 闸门 → 5 桶(borderline = 与 0.6 相差 ≤0.05)
        └─ digest ≤8000 字节 + 内联 briefs(默认 3 条,core 优先、再 watch)
```

状态与缓存都在 `~/.trend-radar/`(可用 `TREND_RADAR_HOME` 覆盖):

```
~/.trend-radar/
├── state.db           # items(first_seen/times_seen) + runs + source_health
├── runs/<run_id>.json # 一次扫描的全部条目与统计(radar_pack / 潜力支路读这里)
├── cache/             # HTTP 响应(<hash>.bin)+ 源级解析结果(src-<hash>.json)
└── trace.jsonl        # 逐阶段 trace,默认开(TREND_RADAR_TRACE=0 关),8 MB 轮换成 trace.1.jsonl
```

---

## 工具(4 个)+ 资源

| 工具 | 作用 | 硬限制 |
|---|---|---|
| `radar_scan` | 自动判 scope + 采集 + 评分 + 分桶 + digest + 内联摘要 | 响应 ≤8000 字节;`briefs` ≤8;`top` ≤10/桶 |
| `radar_pack` | 按 id / bucket 取正文与细节 | `ids` ≤12;`limit` ≤20;摘要 ≤600 字 |
| `radar_check` | 发布前关联度 + 补搜条目打分 | 条目 ≤30;关键词 ≤8;补搜 ≤10 |
| `radar_potential` | 潜力预排:新增源速度 / 突发 / 层级 → 默认 8 条、上限 12 条未验证候选 | `top` ≤12(默认 8);复用 5 分钟内的同 scope run |

资源:`radar://registry`、`radar://history`、`radar://runs`、`radar://runs/{run_id}`、`radar://runs/{run_id}/entries`。

### 分桶语义(写简报前必须看)

| bucket | 含义 | 怎么用 |
|---|---|---|
| `core` | 双项达标,或单源硬证据(`peer-reviewed`) | 可作结论主体;单源必须标出来 |
| `watch` | 可信但还没传开 | **不是噪声**,往往是刚出来的论文 |
| `suspect` | 传得广但不可信 | 必须标出来,不许当事实 |
| `calibration` | 热榜 | 只校准传播度/发现遗漏,**永不作内容源** |
| `discarded` | 双项未达标 | 可查,不作依据 |

---

## 安装

默认零第三方依赖(`pyproject.toml` 的 `dependencies = []`),Python ≥ 3.10。
可选 `certifi`:系统 CA 库过期的环境会自动改用它的证书包,没装则回落到系统 SSL 库(`config.py`)。

```bash
git clone https://github.com/ngwddd/trend-radar-mcp.git
cd trend-radar-mcp
python -m unittest discover -s tests      # 38 tests, no network
```

### 接到 DeepSeek Harness

在 profile 的 `cordis.patch.yml` 里追加(和现有 MCP 服务同一写法):

```yaml
- insert:
    - id: trend-radar-mcp
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: trend-radar
        transport: stdio
        command: 'python'
        args:
          - '-m'
          - 'trend_radar_mcp'
        env:
          PYTHONIOENCODING: utf-8
          PYTHONUNBUFFERED: '1'
          TREND_RADAR_HOME: 'C:\Users\<你的用户名>\.trend-radar'
        toolCallTimeoutMs: 180000
        failOnStartupError: false
```

`radar_scan` 首轮的量级是十几秒(v0.3 实测 5–13 s,看是否命中缓存),上限由单源 10 s 超时封顶决定;失败源会逐条报出来,不会静默。

### 接到 Claude Desktop / 其他 MCP 客户端

```json
{
  "mcpServers": {
    "trend-radar": {
      "command": "python",
      "args": ["-m", "trend_radar_mcp"],
      "env": { "PYTHONIOENCODING": "utf-8" }
    }
  }
}
```

---

## 用法(模型侧契约)

1. 直接调 `radar_scan(query="用户原话")`。**不要先自己判类** —— 工具会判;
   判不进会自动 broad(注册表 42 个源,默认跳过慢源 `arxiv-ai` 后请求 41 个,`deep=true` 才 42),
   返回 `scope_source` 可审计。显式 `domain` 永远优先。
2. `radar_scan` 已经内联 `briefs`(默认 3 条,core 优先、再 watch)。够写就直接写;
   不够再用 `radar_pack(ids≤12, fields=["summary"])` 补 —— 不要整桶拉。
3. `truth` / `comm` 是引擎算的固定分,**不要自己估**,也不要把两个分合成一个。
   `borderline=true`(0.55–0.65)必须复核后再引用。
4. 分桶按上面那张表:`calibration` 只校准传播度,**永不作内容源**。
   「新」看 `new` / `first_seen`,不要凭印象。
5. 补搜条目走 `radar_check(external=[...])` 打分;写完用 `radar_check(bucket="core")`
   量关联度;`<0.6` 必须换角度重查,不许直接下结论。
6. 写简报:每条必须有 URL 与日期;预印本不许写成已发表;厂商自述不算独立验证;
   **「本次覆盖」必须如实写失败源、降级流、跳过的空源**。
7. 预算:`radar_scan` ≈6–8 KB、`radar_pack` ≈3 KB。默认值够用就不要加参数。
8. 没有热点就自动补潜力(任何时间,不要问用户):`notice` 提示「core 为空」或
   「core 里只有论文/单源硬证据」时,直接再调 `radar_potential(query=同一句, days=1, top=5)`,
   在简报末尾单独加「潜力(未验证)」一节,并写一句「今天热点不够,补一组潜力候选」。
   有明确热点时不要调用;用户明确要潜力时随时调用。
9. 潜力候选永远标「未验证」:不写成已确认新闻,不混进 core/watch 的引用;
   返回 `degraded` / 空就直说「今天信号还不够」,不要硬凑。

这九条同时写在 MCP `initialize` 的 `instructions` 里(`server.py`),客户端会自动拿到。

---

## 与 v1 的行为差异

只列**有意**的差异:

- **自动判 scope**:关键词分类器命中单一类且置信度 ≥0.7 才用,否则 broad。
- **质量加权传播**:两个低质站互转不再等于“两家印证”;单源起手 0.30(热度榜条目 0.35),都过不了 0.6 闸门。
- **真值不再叠加印证加成**:印证只影响传播分。
- **borderline 带**:0.55–0.65 标出来,不再一刀切。
- **默认跳过 arXiv API**:`deep=true` 恢复(4 分类 × 3s 礼貌间隔)。
- **状态**:`first_seen` 写入 SQLite;`is_new` = 第一次见到,或首次见到发生在窗口内。
- **空源**:连续 3 次 0 条 → 12 小时跳过,恢复自动解除。

判据没有放松:0.6 闸门、单源硬证据通道、撤稿短路、热榜封顶、front-matter、
身份去重全部保留。

---

## 测试

```bash
python -m unittest discover -s tests -v   # 38 个,全离线
python tests/smoke_stdio.py               # 真启一个 stdio server,跑握手/工具/资源
python tools/verify_run.py [run_id]       # 复盘一次真扫描的不变量(不给 run_id 就取最近一次)
```

38 个用例的分布:`test_core.py` 14(权重与证据序、身份合并、front-matter、单源/双源闸门、
trend 封顶、digest 跨类别、关联度、质量加权传播分)、`test_potential.py` 9(潜力支路的评分 /
run 复用 / 降级 / 同源封顶)、`test_server.py` 7(JSON-RPC 帧、`tools/list`、资源读取)、
`test_contract.py` 4(`radar_scan` 响应里不许出现 `candidates`、core 为空时给潜力提示)、
`test_scan.py` 4(fixture 替掉网络层,验证分桶、`is_new`、`first_seen` 稳定性、
broad 请求 41 源 + 跳过 1 个慢源、stream 兜底)。

CI 在 Python 3.10 / 3.11 / 3.12 / 3.13 上各跑一遍单测 + `pip install .` + import smoke。

---

## 路线

- [ ] ETag / If-Modified-Since 条件请求
- [ ] `since_run` 增量:只回上次之后的新事件
- [ ] 同一 `event_id` 的演进时间线
- [ ] 状态库样本 ≥20/源后,开 source 权重校准
- [ ] 采集适配器拆成 `sources/`,每个 kind 一个文件

## License

MIT · 与原版 skill 同作者、同许可。判据与权重的出处见源码注释。

TDQS

A3.9/5.0

Scored across 4 tools

Disambiguation4/5

Each tool has a fairly distinct role: radar_scan collects and buckets, radar_pack fetches full text, radar_check validates pre-publish entries, and radar_potential ranks emerging candidates. The main overlap is between scan and potential, both returning candidate sets, but descriptions clarify the opt-in, pre-heat use case for potential.

Naming Consistency5/5

All four tools use a consistent radar_ prefix followed by a short snake_case token. The pattern is predictable and readable throughout.

Tool Count4/5

Four tools is slightly thin but well-scoped for a focused scan-pack-check-potential pipeline. Each tool has a clear job and there is no obvious bloat.

Completeness4/5

The surface covers the core workflow: scanning, deepening with full text, pre-publish validation, and opt-in potential detection. Minor gaps exist, such as no explicit history/run lookup or configuration tool, but agents can work around these.

Maintenance

ActivityNo data
ResponsivenessOutdated data