# GeoRisk

**Repository Path**: jkhgnl/geo-risk

## Basic Information

- **Project Name**: GeoRisk
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-09
- **Last Updated**: 2026-10-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# GeoRisk

**跨境贸易地缘政治风险监测与预警平台**

把每天的地缘新闻，落到自己在手的贸易链路上

[项目特点](#项目特点) · [快速开始](#快速开始) · [目标用户](#目标用户) · [解决痛点](#解决痛点)

![GeoRisk 系统运行框架](submission/diagrams/system-flow.gif)

*系统运行框架：录入新闻 → 抽取与核验 → 检索与筛查 → 预警输出（动画，7 秒循环）*

![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A522-339933) ![Python](https://img.shields.io/badge/Python-3.10+-3776AB) ![React](https://img.shields.io/badge/React-19-61DAFB) ![Express](https://img.shields.io/badge/Express-5-000000) ![SQLite](https://img.shields.io/badge/SQLite-3-003B57)

</div>

GeoRisk 回答一个每天都会遇到的问题：今天的地缘新闻里，哪几条与自己在手的贸易链路有关？

用户录入贸易要素——企业、贸易关系、交易，然后只粘贴新闻原文。系统自动完成结构化抽取、权威数据核验、法规条款检索，以贸易关系为单位筛查全量新闻，输出按优先级排序的链路预警；每条结论都附有可在新闻正文中逐字定位的引用。

## 项目特点

| | |
|---|---|
| **以贸易关系为单位扫新闻** | 判断依据是企业自己的履约要素：途经航道与港口、敞口时间窗、结算方式、是否单一来源。先用这些要素做确定性召回，再由模型分流相关性，输出「哪条链路值得看」的排序；录入新闻后自动触发增量筛查 |
| **模型只做判断，不做数字** | 候选召回、引用校验、优先级打分全部由确定性代码完成，模型只输出相关性判断与原文摘录。优先级由纯函数算出，同样输入永远同样输出，落库带 `rule_version`，可复现、可回溯 |
| **结论必须能回到原文** | 每条引用都要能在新闻正文中逐字找到，改写或翻译的一律作废；拿不出引用的相关判定优先级封顶；模型漏答标为 unjudged 落库，不静默丢弃；被独立数据反驳的新闻自动降级。实测数据集中，25 条相关结论全部附有通过校验的引用 |
| **多语言一手源** | 阿拉伯语报道常比英文源更早提及航道异常。用 105 条阿-中-英名称对照表（48 条经人工确认）做地点归一，阿语新闻里的「مضيق هرمز」能命中中文交易里的「霍尔木兹海峡」 |
| **六层链路可运行，每层自带评测** | 录入 → LLM 结构化抽取 → 权威数据核验（IMF PortWatch / OpenSanctions）→ 法规条款级混合检索（1188 条分块，向量 + BM25 + 重排）→ 关系中心筛查 → 预警输出。各层评测见 `rag/eval/`、`verification/tests/`、`scripts/screening-eval.mjs` |
| **失效可见** | 数据缺失、核验失败、模型未判定各有独立状态，不混为一谈、不静默吞掉；数据源自身的偏差（如危机期间船舶关闭 AIS 导致通行量低估）随结论一并披露 |

## 快速开始

环境要求：Node.js ≥ 22（后端使用内置 `node:sqlite`，无需原生编译依赖）；检索与核验服务需要 Python 3.10+。

```bash
# 1. 配置模型：复制 .env.example 为 .env，填三项
#    LLM_BASE_URL / LLM_API_KEY / LLM_MODEL
# 2. 安装依赖
npm install
# 3. 一键启动（检查环境、按需下载模型、拉起服务并打开浏览器）
start.bat
```

打开 http://127.0.0.1:5173 ，点顶部「示例数据」载入演示案例（13 家企业、6 条贸易关系、4 笔交易，以及 14 条新闻原文）。录入顺序建议：企业与主体 → 贸易关系 → 交易录入 → 风险事件。示例新闻载入后只完成「录入」，停在「待结构化」；在「分析链路」里点「运行工作流」才会依次触发结构化、核验与筛查，结论见「风险筛查」页。

两点说明：

- 未配置 `.env` 时链路仍可运行，但结构化抽取与相关性分流会标为待复核；
- RAG 检索服务（`npm run rag:dev`，端口 8790）不可用时，筛查自动退回纯结构化召回，不阻断。

其它命令：`stop.bat` 停止三个服务（start.bat 的窗口关掉后也用它）；`npm run build` 生产构建；`npm run db:info` 查看数据库表结构与行数；`npm run rag:build` 从 `rag/raw` 的法规原文重建检索索引。

## 目标用户

没有专职地缘政治风险分析团队的中型出海制造企业：员工数百人，海外收入占两到三成，关键客户或零部件依赖单一海外航线。日常使用者是海外业务负责人与供应链管理者——采购、销售、战略各掌握一部分信息，但没有人负责把它们拼起来。

## 解决痛点

人工盯新闻的方式，工作量是 N 笔交易 × M 条新闻的逐条比对。当前演示数据集的规模是 **6 条关系 × 52 条候选新闻 = 312 次**，而这只是一天的输入量。

| 痛点 | 现状 |
|---|---|
| **语种门槛** | 最有价值的一手报道往往最早出现在阿拉伯语源；通用翻译工具能翻句子，给不出「哪条跟我有关」 |
| **时间成本** | 逐条比对一天的输入量要花数小时，而地缘事件的处置窗口往往只有几天 |
| **无法复现** | 人工判断没有统一口径，换个人、换一天，同一条新闻可能得出不同结论 |

现有工具各自的局限性：

| 已有工具 | 它做到哪 | 缺口 |
|---|---|---|
| 资讯聚合 | 汇总地缘新闻、按地区与主题分类 | 不知道你的敞口在哪 |
| 制裁名单筛查 | 核对交易对手是否在名单上 | 只回答「能不能做」，不回答「货能不能按时到、钱能不能按时回」 |
| 通用 AI 问答 | 总结单篇新闻、解释背景 | 给不出可逐字核对的引用 |

GeoRisk 补的是中间那一步——把外部事件接到企业自己的履约要素上。

---



更多设计与接口文档见 `docs/`、`rag/README.md`、`verification/README.md`。