nikolareljin/vigilant-core
GitHub: nikolareljin/vigilant-core
VigilantCore 是一款隐私优先的本地事件监控应用，利用本地 LLM 对多来源新闻与警报进行影响评估和预测分析。
Stars: 2 | Forks: 0
# VigilantCore
[](https://github.com/nikolareljin/vigilant-core/actions/workflows/ci.yml)
[](https://github.com/nikolareljin/vigilant-core/actions/workflows/compatibility.yml)
VigilantCore 是一款本地、跨平台的监控应用，用于追踪特定主题的**重大事件**（Impactful Events），它利用本地 LLM (Ollama) 对影响力进行评估并生成预测性结果。它专为非技术用户设计，力求简单易用，同时提供 AI 驱动且具备位置感知能力的信号。
**所有 AI 处理均在您的本地计算机上完成 - 不会向外部服务器发送任何数据。**
## 🚀 快速开始
**使用一行命令开始：**
- **Linux/macOS:**
```
curl -fsSL https://raw.githubusercontent.com/nikolareljin/vigilant-core/main/scripts/quickstart.sh | bash
```
- **Windows:**
```
git clone https://github.com/nikolareljin/vigilant-core.git
cd vigilant-core
.\scripts\quickstart.ps1
```
[**→ 跳转到详细的安装说明**](#quickstart-one-command-setup)
## 核心功能
- **AI 驱动的洞察**：提出特定的监控问题，获取 AI 生成的解答
- **影响评分**：根据相关性和紧迫性，对每个警报进行 1-10 分的评分
- **位置感知**：支持通过邮政编码、坐标或半径过滤警报
- **自动本地发现**：当您提供邮政编码时，会自动查找：
- 您所在州的 NWS 天气警报
- 当地警察、消防和应急管理部门的警报
- 停电地图（包括 `poweroutage.us` 搜索覆盖范围）和公用事业警报
- 水、天然气、太阳能和风能基础设施的事故信号
- 交通/运输/公共交通/机场和航空公司的中断信号
- 当地新闻和政府来源
- **具备上下文感知能力的极端事件覆盖**：针对洪水、龙卷风、野火、冬季风暴、地震、工业事故以及冲突/危机的监控查询
- **国际区域覆盖**：加拿大、欧洲（优先）、北非、中国/远东、澳大利亚、南非、中美洲、南美洲，以及更广泛的中东/南亚/东南亚/撒哈拉以南非洲/全球备用区域
- **坐标优先的来源发现**：仅需经度/纬度即可推断出所在区域，并自动填充相关的区域来源 URL 和本地化的 Google News 提要
- **来源预览 UI/API**：设置页面的预览功能和 `/api/source-preview` endpoint 会在保存前显示推断出的区域和精选来源 URL
- **来源健康指标**：在仪表板和 `/api/source-health` 中跟踪每个来源的上次成功获取时间、累计错误次数和最新获取延迟
- **AI 建议操作开关**：可在设置中启用/禁用显示在 AI 洞察结果旁边的可执行建议
- **统一的事件标准化**：所有警报都会被标准化为一致的 schema，包含 `severity`、`confidence`、UTC 标准化时间戳以及结构化的位置字段
- **事件去重引擎**：将来自不同 feed/搜索提供商的重叠警报合并为一个规范事件，并汇总来源归属
- **SQLite 本地缓存**：存储标准化警报以及 `event_history` 和 `source_metadata` 记录，实现可追溯的本地事件持久化
- **多种数据来源**：NewsAPI、DuckDuckGo、Google CSE、RSS feed、本地发现以及精选的全球来源（包括灾难/危机信号来源）
- **跨平台**：提供 Web 仪表板和 Qt 桌面应用
- **隐私优先**：所有处理均通过 Ollama 在本地完成
## 用户流程
1. **首次运行**：打开应用，输入您的监控主题、位置以及可选的 RSS feed/API 密钥。
2. **设置监控问题**：提出具体问题，例如“停电的最高风险期是什么时候？”
3. **实时影响动态**：仪表板显示带有 AI 生成洞察的评分警报（默认情况下，时间戳使用主机的本地时间，或者在 `.env` 中设置了 `DISPLAY_TIMEZONE` 时使用该时区）。
4. **影响评分**：根据相关性和紧迫性，每条警报的评分范围为 1–10。
5. **保持信息同步**：新警报会近乎实时地出现并存储在本地。
## 影响评分逻辑（概述）
- **1–3**：相关性低或影响较弱。
- **4–6**：中等影响或早期预警信号。
- **7–10**：重大影响事件、警告或即将发生的中断。
## 位置匹配
VigilantCore 通过结合以下因素优先考虑本地信号：
- 基于邮政编码的离线地理编码，定位到中心点。
- 半径过滤（默认 50 公里）。
- 对位置名称和邮政编码进行关键词匹配。
## 自动本地来源发现
当您提供邮政编码或坐标时，VigilantCore 会自动发现相关的本地来源：
**天气和紧急警报：**
- 针对您所在州的 NWS（国家气象局）CAP 警报
- 恶劣天气警告和警报
**紧急服务：**
- 当地警察部门的警报
- 消防部门的新闻
- 县应急管理更新
- 道路封闭和旅行建议
**公用事业：**
- 电力公司的停电信息
- 电力服务警报
- 自来水公司的公告和沸水警报
- 天然气紧急情况和泄漏通知
- 相关的可再生能源基础设施事故（太阳能/风能）
**当地新闻：**
- 县/市政府新闻 feed
- 当地报纸的 RSS feed
**交通和关键基础设施：**
- 交通和 DOT（交通部）事故更新
- 公共交通/铁路服务中断警报
- 机场/航空公司延误和取消信号
**全球危机/冲突（主题驱动）：**
- 如果您的监控主题提及战争/冲突/危机等词汇，VigilantCore 会扩展国际冲突和人道主义风险更新的搜索/feed 查询范围
**国际区域（位置/经纬度感知）：**
- 加拿大、欧洲、北非、中国/远东、澳大利亚、南非、中美洲和南美洲的区域来源 URL 和搜索将被自动优先处理
- 额外的备用覆盖范围包括中东、南亚、东南亚和撒哈拉以南非洲（只要有公开来源可用）
## 区域来源发现（详细）
VigilantCore 现在采用分层来源发现方法来进行停电/极端事件的监控：
1. 通过邮政编码、位置文本或经纬度推断所在区域（仅凭经纬度也可生效）。
2. 选择精选的区域 URL（公用事业、应急机构、气象服务、交通/航空运营以及主要区域新闻）。
3. 使用特定于区域的区域设置（`gl`、`hl`、`ceid`）生成本地化的 Google News RSS feed。
4. 针对公用事业、交通、灾难以及冲突/人道主义危机扩展上下文感知的搜索。
5. 从候选站点发现 RSS feed，并与用户提供的 feed 和其他搜索/API 来源合并。
这改善了直接 RSS feed 不一致或不可用地区的覆盖情况。
## 事件去重
在 AI 解析和 SQLite 持久化之前，VigilantCore 会通过以下方式对传入的警报进行去重：
- URL 级别的重复抑制
- 语义重叠检查（标题/正文的 token 相似度）
- 事件时间邻近度检查（默认为 6 小时重叠窗口，仅在两个事件都有时间戳时应用）
当多个来源描述同一事件时，VigilantCore 会存储一个合并后的事件，并结合来源归属（例如：`Source A | Source B`）。
有关详细的行为说明，请参见 `docs/event-deduplication.md`。
### 坐标优先行为
如果您仅提供坐标：
- `latitude`
- `longitude`
VigilantCore 依然能够：
- 推断出大概的区域
- 选择本地化的区域来源 URL
- 生成本地化的 Google News feed
- 在保存前预选定的区域/来源
### 来源预览（Web 设置 + API）
设置页面包含一个**区域来源预览**面板，显示：
- 推断出的区域 key/标签
- 精选来源 URL 数量
- 将被优先处理的精选来源 URL
- 坐标值在推断区域前会进行范围验证（`lat=-90..90`，`lon=-180..180`）
通过代码进行预览：
```
curl "http://127.0.0.1:8765/api/source-preview?latitude=48.8566&longitude=2.3522"
```
另一个示例：
```
curl "http://127.0.0.1:8765/api/source-preview?location_name=Toronto,%20Ontario,%20Canada"
```
有关完整的覆盖列表和实现行为，请参见 `docs/source-discovery.md`。
例如，邮政编码 `08544`（新泽西州普林斯顿）会自动添加新泽西州的 NWS 警报，搜索 PSE&G 停电信息，并查找默瑟县的应急资源。
## 环境要求
- **Python 3.10+** (Linux/macOS)
- **Python 3.12** (Windows)
- Git（用于克隆/更新）
- Ollama（由快速入门脚本自动安装）
## 快速入门（一行命令设置）
为您的操作系统选择相应的命令：
| 平台 | 命令 |
|----------|---------|
| **Linux** | `curl -fsSL https://raw.githubusercontent.com/nikolareljin/vigilant-core/main/scripts/quickstart.sh \| bash` |
| **macOS** | `curl -fsSL https://raw.githubusercontent.com/nikolareljin/vigilant-core/main/scripts/quickstart.sh \| bash` |
| **Windows (PowerShell)** | `.\scripts\quickstart.ps1 -TargetDir "."`（克隆仓库后） |
| **Windows (CMD)** | `set TARGET_DIR=.` 然后 `.\scripts\quickstart.bat`（克隆仓库后） |
### Linux/macOS
**在系统任意位置运行（无需克隆仓库）：**
```
curl -fsSL https://raw.githubusercontent.com/nikolareljin/vigilant-core/main/scripts/quickstart.sh | bash
```
或使用 wget：
```
wget -qO- https://raw.githubusercontent.com/nikolareljin/vigilant-core/main/scripts/quickstart.sh | bash
```
**如果您已经克隆了该仓库：**
```
./scripts/quickstart.sh
```
### Windows
**第 1 步：克隆仓库（仅限首次）**
```
git clone https://github.com/nikolareljin/vigilant-core.git
cd vigilant-core
```
**第 2 步：运行快速入门脚本**
**PowerShell（推荐）：**
```
.\scripts\quickstart.ps1 -TargetDir "."
```
**命令提示符：**
```
set TARGET_DIR=.
.\scripts\quickstart.bat
```
**快速入门脚本会执行以下操作：**
- ✅ 确保 Windows 上有 Python 3.12（如果缺失则自动安装）
- ✅ 安装/检查 Git
- ✅ 克隆或更新仓库
- ✅ 创建并激活虚拟环境
- ✅ 安装所有 Python 依赖
- ✅ **安装 Ollama CLI**（通过官方安装程序或 winget）
- ✅ **启动 Ollama 服务**
- ✅ **下载默认 AI 模型** (llama3.2:1b - ~900MB)
- ✅ 在 http://127.0.0.1:8765 启动 Web 仪表板
**首次设置需要 5-10 分钟**（主要是下载 AI 模型）。随后的运行是瞬间完成的。
### 特定平台的注意事项
**Linux:**
- 需要通过 `curl` 或 `wget` 进行远程安装
- Ollama 通过 ollama.com 的官方脚本安装
- 某些软件包的安装可能需要 `sudo`
**macOS:**
- 安装 Ollama 需要 Homebrew
- 如果未安装 Homebrew，请从 [brew.sh](https://brew.sh) 获取
- 所有安装均无需 sudo
**Windows:**
- 为了在 Windows 上获得一致的依赖支持，**必须使用 Python 3.12**
- 自动安装 Ollama 需要 [winget](https://learn.microsoft.com/en-us/windows/package-manager/winget/)
- Windows 11 和 Windows 10（较新版本）已内置 winget
- 替代方案：从 [ollama.com/download](https://ollama.com/download) 手动下载 Ollama
- PowerShell：以普通用户身份运行（无需管理员权限）
- 命令提示符：以普通用户身份运行（无需管理员权限）
### 快速入门故障排除
**“Ollama 安装失败”**
- 从 [ollama.com/download](https://ollama.com/download) 手动下载并安装
- 安装后再次运行快速入门脚本
**“模型下载速度慢”**
- llama3.2:1b 模型大小约为 900MB
- 速度取决于您的网络连接
- 您可以取消（Ctrl+C）并在之后使用以下命令继续：`ollama pull llama3.2:1b`
**“未找到 Python”或“未找到 Git”**
- **Windows：** 从 [python.org](https://www.python.org/downloads/windows/) 安装 Python 3.12.x
- 如果快速入门自动安装了 Python，请关闭当前终端并重新运行快速入门，以便应用 PATH 的更改
- **Linux/macOS：** 通过您的包管理器或 [python.org](https://www.python.org/downloads/) 安装 Python 3.10+
- 从 [git-scm.com](https://git-scm.com/downloads) 安装 Git
- 确保两者都已到系统的 PATH 中
## 手动安装
如果您更喜欢手动设置，或者快速入门脚本不适用于您的系统：
1. 克隆仓库
2. 运行启动脚本：
**Linux/macOS:**
```
./run.sh # Start web dashboard (default)
./run.sh qt # Start Qt desktop app
./run.sh both # Start both (web in background)
./run.sh stop # Stop all instances
./run.sh status # Check what's running
```
**Windows:**
```
run.bat # Start web dashboard
run.bat qt # Start Qt desktop app
run.bat stop # Stop all instances
```
启动器将自动创建虚拟环境并安装依赖项。
### Web 仪表板
配置仪表板：
在上面的示例中，公共位置是使用经度/纬度定义的。您可以使用您自己的位置、邮政编码、地址和经度/纬度。
在浏览器中打开：**http://127.0.0.1:8765**
搜索的初始结果。
带有 AI 生成内容的结果视图：
### Qt 桌面应用
使用 `./run.sh qt` 启动（或在 Windows 上使用 `run.bat qt`）。
带有 AI 生成内容的结果视图：
## 监控问题与 AI 洞察
**监控问题**功能允许您针对被监控的主题提出具体问题。AI 会分析最近的警报并生成针对性的洞察。
**问题示例：**
- “我所在地区停电风险最高的预期时间是几点？”
- “我现在应该清理车道，还是等雪停了再说？”
- “是否有影响 I-95 公路的出行建议？”
洞察会作为警报列表上方的可展开卡片显示，展示：
- **摘要**：对您问题的简要回答
- **解释**：带有支持证据的详细分析
在“设置”下的“AI 设置”中配置刷新间隔。
## Web 仪表板
Web 界面位于：**http://127.0.0.1:8765**
设置页面会提示输入：
- **事件/主题** - 要监控的内容
- **监控问题** - 用于获取 AI 洞察的具体问题
- **位置 / ZIP / GPS** - 地理位置过滤
- **半径（公里）** - 搜索区域
- **AI 设置** - 模型偏好，洞察刷新率
- **数据来源** - RSS feed，API 密钥
- **来源健康指标** - 各来源的获取健康状况表（上次成功时间、错误、延迟和条目计数）
附加数据视图：`http://127.0.0.1:8765/data`
## 零输入发现
如果您未提供任何 RSS feed 或 API 密钥，VigilantCore 依然会：
- 自动检测您的城市/区域 + ZIP + 坐标（尽力而为）。
- 从 **30 个精选的全球来源**进行种子填充，并发现 RSS/Atom feed。
- 添加基于您的主题 + 位置构建的 Google News RSS 查询，以获得更广泛的覆盖。
- 添加当地的公共安全查询（警察、治安官、消防、应急管理）。
- 尝试发现您位置附近的当地警察/政府和当地新闻 RSS feed。
- 通过与您的主题和位置绑定的 Reddit 搜索 RSS 获取社交讨论。
### RSS feed 与精选来源
默认情况下，您添加的任何 RSS feed 都会与内置的精选来源*合并*。
如果您只想使用自己提供的 RSS feed，请在“设置”中启用**“仅使用上面列出的 RSS feed”**。
要完全跳过 RSS 并仅使用 API/搜索提供商，请启用**“禁用 RSS 获取”**。
### 轮询间隔
您可以控制应用检查新数据的频率（默认为 **5 分钟**）。
- Web UI：**轮询间隔（分钟）**
- Qt UI：**轮询间隔（分钟）**
## 可选的搜索 API 密钥（获得更好的覆盖）
如果您设置了以下任何 API 密钥，VigilantCore 将自动使用它们。如果未设置，它将回退到 RSS 和内置的发现机制。
### Google Programmable Search Engine (CSE)
1. 创建一个 Custom Search Engine，并将其设置为**搜索整个网络**：
https://programmablesearchengine.google.com/
2. 启用 Custom Search JSON API 并创建一个 API 密钥：
https://developers.google.com/custom-search/v1/overview
3. 设置：
```
GOOGLE_CSE_API_KEY=your_key
GOOGLE_CSE_CX=your_search_engine_id
```
### Bing Web Search API
1. 在 Azure 中创建一个 Bing Search v7 资源：
https://learn.microsoft.com/en-us/bing/search-apis/bing-web-search/create-bing-search-service-resource
2. 设置：
```
BING_SEARCH_KEY=your_key
# 可选覆盖
BING_SEARCH_ENDPOINT=https://api.bing.microsoft.com/v7.0/search
BING_SEARCH_MARKET=en-US
BING_SEARCH_SAFE=Moderate
```
### DuckDuckGo Web Search（无需密钥）
无需 API 密钥即可使用 DuckDuckGo HTML 搜索。在“设置”中启用/禁用它：
- Web UI：**启用 DuckDuckGo web search**
- Qt UI：**启用 DuckDuckGo web search**
### 网络共享 / 低带宽模式
如果您使用的是移动热点或网络共享连接，请启用：
- Web UI：**针对共享 / 低带宽连接进行优化**
- Qt UI：**针对共享 / 低带宽连接进行优化**
此模式通过限制来源发现/查询预算并限制 feed 轮询/发现的广度，来减少请求量。
### Facebook & Instagram (Meta Graph API)
Meta 不提供通用的公开搜索 API。访问通常需要：
- 具有已批准权限的 Meta 应用
- 特定的主页/IG 商业帐户上下文
如果您拥有主页或 IG 商业帐户并希望进行定向摄取，请提交一个 issue，我们可以针对特定主页 ID 添加提供商。
### 精选的全球来源（已扩展）
默认列表现在包括美国、欧洲、东欧、中国、澳大利亚、南美洲和非洲的主要媒体。有关完整列表，请参见 `vigilant-core/utils/sources.py`。
## 辅助脚本 (script-helpers)
此仓库可以像该工作空间中的其他项目一样，使用共享的 `script-helpers` 库。
如果 submodule 不存在（例如在 CI 中），脚本将回退到最小化日志记录。
要在本地使用完整的辅助功能，请初始化一次 submodule：
```
./update
```
## 一行命令安装与运行（所有主要平台）
这些命令将创建本地虚拟环境、安装依赖并启动应用。
### macOS / Linux
```
python3 -m venv venv && source venv/bin/activate && pip install -r requirements.txt && python src/main.py
```
### Windows (PowerShell)
```
py -3.12 -m venv venv; .\\venv\\Scripts\\Activate.ps1; pip install -r requirements.txt; python src\\main.py
```
### Windows (CMD)
```
py -3.12 -m venv venv && call venv\\Scripts\\activate && pip install -r requirements.txt && python src\\main.py
```
## 一行命令安装脚本
对于非技术用户，这些脚本可处理设置和启动：
### macOS / Linux
```
./install.sh
```
### Windows (PowerShell)
```
./install.ps1
```
## 一键打包（可执行文件）
构建原生应用包，以便非技术用户无需 Python 即可运行：
```
pyinstaller --onefile --windowed src/main.py --name VigilantCore
```
## CI 自动化 (ci-helpers)
GitHub Actions 使用来自 `ci-helpers` 的可重用工作流进行 lint、测试和构建：
- 工作流文件：`.github/workflows/ci.yml`
- 可重用工作流：`nikolareljin/ci-helpers/.github/workflows/python.yml@production`
## 开发者设置
```
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python src/main.py
```
## 本地 LLM
默认情况下，应用使用来自 Ollama 的 `qwen2.5:7b`。如果 RAM 为 8GB 或更小，它会自动回退到 `qwen2.5:3b`，除非设置了 `OLLAMA_MODEL`。您可以通过以下方式进行覆盖：
```
export OLLAMA_MODEL=qwen2.5:7b
```
## 打包（一键应用）
```
pyinstaller --onefile --windowed src/main.py --name VigilantCore
```
## 仓库提示
- **仓库名称**：`vigilant-core`
- **分支保护**：在合并到 `main` 分支之前需要进行 PR 审查。
### NewsAPI 时间窗口
您可以控制 NewsAPI 结果的新鲜度。默认值为 **6 小时**。
- Web UI：**新闻时间窗口（小时）**
- Qt UI：**新闻时间窗口（小时）**
### NewsAPI 排序顺序
默认排序为**受欢迎程度** (popularity)。您也可以从“设置”UI 中选择**发布时间** (publishedAt) 或**相关性** (relevancy)。
## 文档
完整文档可在 `docs/` 文件夹中找到：
- [安装指南](docs/installation.md) - 详细的设置说明
- [配置指南](docs/configuration.md) - 所有配置选项
- [功能说明](docs/features.md) - 完整的功能文档
- [示例](docs/examples.md) - 实际使用示例（冬季风暴、停电等）
## 更新日志
有关发布历史和更改，请参见 [CHANGELOG.md](CHANGELOG.md)。
事件 schema 详情：[docs/event-normalization.md](docs/event-normalization.md)
## 克隆流量
_每日更新。过去 14 天的总计和独立克隆次数。_
VigilantCore 是一款本地、跨平台的监控应用，用于追踪特定主题的**重大事件**（Impactful Events），它利用本地 LLM (Ollama) 对影响力进行评估并生成预测性结果。它专为非技术用户设计，力求简单易用，同时提供 AI 驱动且具备位置感知能力的信号。
**所有 AI 处理均在您的本地计算机上完成 - 不会向外部服务器发送任何数据。**
## 🚀 快速开始
**使用一行命令开始：**
- **Linux/macOS:**
```
curl -fsSL https://raw.githubusercontent.com/nikolareljin/vigilant-core/main/scripts/quickstart.sh | bash
```
- **Windows:**
```
git clone https://github.com/nikolareljin/vigilant-core.git
cd vigilant-core
.\scripts\quickstart.ps1
```
[**→ 跳转到详细的安装说明**](#quickstart-one-command-setup)
## 核心功能
- **AI 驱动的洞察**：提出特定的监控问题，获取 AI 生成的解答
- **影响评分**：根据相关性和紧迫性，对每个警报进行 1-10 分的评分
- **位置感知**：支持通过邮政编码、坐标或半径过滤警报
- **自动本地发现**：当您提供邮政编码时，会自动查找：
- 您所在州的 NWS 天气警报
- 当地警察、消防和应急管理部门的警报
- 停电地图（包括 `poweroutage.us` 搜索覆盖范围）和公用事业警报
- 水、天然气、太阳能和风能基础设施的事故信号
- 交通/运输/公共交通/机场和航空公司的中断信号
- 当地新闻和政府来源
- **具备上下文感知能力的极端事件覆盖**：针对洪水、龙卷风、野火、冬季风暴、地震、工业事故以及冲突/危机的监控查询
- **国际区域覆盖**：加拿大、欧洲（优先）、北非、中国/远东、澳大利亚、南非、中美洲、南美洲，以及更广泛的中东/南亚/东南亚/撒哈拉以南非洲/全球备用区域
- **坐标优先的来源发现**：仅需经度/纬度即可推断出所在区域，并自动填充相关的区域来源 URL 和本地化的 Google News 提要
- **来源预览 UI/API**：设置页面的预览功能和 `/api/source-preview` endpoint 会在保存前显示推断出的区域和精选来源 URL
- **来源健康指标**：在仪表板和 `/api/source-health` 中跟踪每个来源的上次成功获取时间、累计错误次数和最新获取延迟
- **AI 建议操作开关**：可在设置中启用/禁用显示在 AI 洞察结果旁边的可执行建议
- **统一的事件标准化**：所有警报都会被标准化为一致的 schema，包含 `severity`、`confidence`、UTC 标准化时间戳以及结构化的位置字段
- **事件去重引擎**：将来自不同 feed/搜索提供商的重叠警报合并为一个规范事件，并汇总来源归属
- **SQLite 本地缓存**：存储标准化警报以及 `event_history` 和 `source_metadata` 记录，实现可追溯的本地事件持久化
- **多种数据来源**：NewsAPI、DuckDuckGo、Google CSE、RSS feed、本地发现以及精选的全球来源（包括灾难/危机信号来源）
- **跨平台**：提供 Web 仪表板和 Qt 桌面应用
- **隐私优先**：所有处理均通过 Ollama 在本地完成
## 用户流程
1. **首次运行**：打开应用，输入您的监控主题、位置以及可选的 RSS feed/API 密钥。
2. **设置监控问题**：提出具体问题，例如“停电的最高风险期是什么时候？”
3. **实时影响动态**：仪表板显示带有 AI 生成洞察的评分警报（默认情况下，时间戳使用主机的本地时间，或者在 `.env` 中设置了 `DISPLAY_TIMEZONE` 时使用该时区）。
4. **影响评分**：根据相关性和紧迫性，每条警报的评分范围为 1–10。
5. **保持信息同步**：新警报会近乎实时地出现并存储在本地。
## 影响评分逻辑（概述）
- **1–3**：相关性低或影响较弱。
- **4–6**：中等影响或早期预警信号。
- **7–10**：重大影响事件、警告或即将发生的中断。
## 位置匹配
VigilantCore 通过结合以下因素优先考虑本地信号：
- 基于邮政编码的离线地理编码，定位到中心点。
- 半径过滤（默认 50 公里）。
- 对位置名称和邮政编码进行关键词匹配。
## 自动本地来源发现
当您提供邮政编码或坐标时，VigilantCore 会自动发现相关的本地来源：
**天气和紧急警报：**
- 针对您所在州的 NWS（国家气象局）CAP 警报
- 恶劣天气警告和警报
**紧急服务：**
- 当地警察部门的警报
- 消防部门的新闻
- 县应急管理更新
- 道路封闭和旅行建议
**公用事业：**
- 电力公司的停电信息
- 电力服务警报
- 自来水公司的公告和沸水警报
- 天然气紧急情况和泄漏通知
- 相关的可再生能源基础设施事故（太阳能/风能）
**当地新闻：**
- 县/市政府新闻 feed
- 当地报纸的 RSS feed
**交通和关键基础设施：**
- 交通和 DOT（交通部）事故更新
- 公共交通/铁路服务中断警报
- 机场/航空公司延误和取消信号
**全球危机/冲突（主题驱动）：**
- 如果您的监控主题提及战争/冲突/危机等词汇，VigilantCore 会扩展国际冲突和人道主义风险更新的搜索/feed 查询范围
**国际区域（位置/经纬度感知）：**
- 加拿大、欧洲、北非、中国/远东、澳大利亚、南非、中美洲和南美洲的区域来源 URL 和搜索将被自动优先处理
- 额外的备用覆盖范围包括中东、南亚、东南亚和撒哈拉以南非洲（只要有公开来源可用）
## 区域来源发现（详细）
VigilantCore 现在采用分层来源发现方法来进行停电/极端事件的监控：
1. 通过邮政编码、位置文本或经纬度推断所在区域（仅凭经纬度也可生效）。
2. 选择精选的区域 URL（公用事业、应急机构、气象服务、交通/航空运营以及主要区域新闻）。
3. 使用特定于区域的区域设置（`gl`、`hl`、`ceid`）生成本地化的 Google News RSS feed。
4. 针对公用事业、交通、灾难以及冲突/人道主义危机扩展上下文感知的搜索。
5. 从候选站点发现 RSS feed，并与用户提供的 feed 和其他搜索/API 来源合并。
这改善了直接 RSS feed 不一致或不可用地区的覆盖情况。
## 事件去重
在 AI 解析和 SQLite 持久化之前，VigilantCore 会通过以下方式对传入的警报进行去重：
- URL 级别的重复抑制
- 语义重叠检查（标题/正文的 token 相似度）
- 事件时间邻近度检查（默认为 6 小时重叠窗口，仅在两个事件都有时间戳时应用）
当多个来源描述同一事件时，VigilantCore 会存储一个合并后的事件，并结合来源归属（例如：`Source A | Source B`）。
有关详细的行为说明，请参见 `docs/event-deduplication.md`。
### 坐标优先行为
如果您仅提供坐标：
- `latitude`
- `longitude`
VigilantCore 依然能够：
- 推断出大概的区域
- 选择本地化的区域来源 URL
- 生成本地化的 Google News feed
- 在保存前预选定的区域/来源
### 来源预览（Web 设置 + API）
设置页面包含一个**区域来源预览**面板，显示：
- 推断出的区域 key/标签
- 精选来源 URL 数量
- 将被优先处理的精选来源 URL
- 坐标值在推断区域前会进行范围验证（`lat=-90..90`，`lon=-180..180`）
通过代码进行预览：
```
curl "http://127.0.0.1:8765/api/source-preview?latitude=48.8566&longitude=2.3522"
```
另一个示例：
```
curl "http://127.0.0.1:8765/api/source-preview?location_name=Toronto,%20Ontario,%20Canada"
```
有关完整的覆盖列表和实现行为，请参见 `docs/source-discovery.md`。
例如，邮政编码 `08544`（新泽西州普林斯顿）会自动添加新泽西州的 NWS 警报，搜索 PSE&G 停电信息，并查找默瑟县的应急资源。
## 环境要求
- **Python 3.10+** (Linux/macOS)
- **Python 3.12** (Windows)
- Git（用于克隆/更新）
- Ollama（由快速入门脚本自动安装）
## 快速入门（一行命令设置）
为您的操作系统选择相应的命令：
| 平台 | 命令 |
|----------|---------|
| **Linux** | `curl -fsSL https://raw.githubusercontent.com/nikolareljin/vigilant-core/main/scripts/quickstart.sh \| bash` |
| **macOS** | `curl -fsSL https://raw.githubusercontent.com/nikolareljin/vigilant-core/main/scripts/quickstart.sh \| bash` |
| **Windows (PowerShell)** | `.\scripts\quickstart.ps1 -TargetDir "."`（克隆仓库后） |
| **Windows (CMD)** | `set TARGET_DIR=.` 然后 `.\scripts\quickstart.bat`（克隆仓库后） |
### Linux/macOS
**在系统任意位置运行（无需克隆仓库）：**
```
curl -fsSL https://raw.githubusercontent.com/nikolareljin/vigilant-core/main/scripts/quickstart.sh | bash
```
或使用 wget：
```
wget -qO- https://raw.githubusercontent.com/nikolareljin/vigilant-core/main/scripts/quickstart.sh | bash
```
**如果您已经克隆了该仓库：**
```
./scripts/quickstart.sh
```
### Windows
**第 1 步：克隆仓库（仅限首次）**
```
git clone https://github.com/nikolareljin/vigilant-core.git
cd vigilant-core
```
**第 2 步：运行快速入门脚本**
**PowerShell（推荐）：**
```
.\scripts\quickstart.ps1 -TargetDir "."
```
**命令提示符：**
```
set TARGET_DIR=.
.\scripts\quickstart.bat
```
**快速入门脚本会执行以下操作：**
- ✅ 确保 Windows 上有 Python 3.12（如果缺失则自动安装）
- ✅ 安装/检查 Git
- ✅ 克隆或更新仓库
- ✅ 创建并激活虚拟环境
- ✅ 安装所有 Python 依赖
- ✅ **安装 Ollama CLI**（通过官方安装程序或 winget）
- ✅ **启动 Ollama 服务**
- ✅ **下载默认 AI 模型** (llama3.2:1b - ~900MB)
- ✅ 在 http://127.0.0.1:8765 启动 Web 仪表板
**首次设置需要 5-10 分钟**（主要是下载 AI 模型）。随后的运行是瞬间完成的。
### 特定平台的注意事项
**Linux:**
- 需要通过 `curl` 或 `wget` 进行远程安装
- Ollama 通过 ollama.com 的官方脚本安装
- 某些软件包的安装可能需要 `sudo`
**macOS:**
- 安装 Ollama 需要 Homebrew
- 如果未安装 Homebrew，请从 [brew.sh](https://brew.sh) 获取
- 所有安装均无需 sudo
**Windows:**
- 为了在 Windows 上获得一致的依赖支持，**必须使用 Python 3.12**
- 自动安装 Ollama 需要 [winget](https://learn.microsoft.com/en-us/windows/package-manager/winget/)
- Windows 11 和 Windows 10（较新版本）已内置 winget
- 替代方案：从 [ollama.com/download](https://ollama.com/download) 手动下载 Ollama
- PowerShell：以普通用户身份运行（无需管理员权限）
- 命令提示符：以普通用户身份运行（无需管理员权限）
### 快速入门故障排除
**“Ollama 安装失败”**
- 从 [ollama.com/download](https://ollama.com/download) 手动下载并安装
- 安装后再次运行快速入门脚本
**“模型下载速度慢”**
- llama3.2:1b 模型大小约为 900MB
- 速度取决于您的网络连接
- 您可以取消（Ctrl+C）并在之后使用以下命令继续：`ollama pull llama3.2:1b`
**“未找到 Python”或“未找到 Git”**
- **Windows：** 从 [python.org](https://www.python.org/downloads/windows/) 安装 Python 3.12.x
- 如果快速入门自动安装了 Python，请关闭当前终端并重新运行快速入门，以便应用 PATH 的更改
- **Linux/macOS：** 通过您的包管理器或 [python.org](https://www.python.org/downloads/) 安装 Python 3.10+
- 从 [git-scm.com](https://git-scm.com/downloads) 安装 Git
- 确保两者都已到系统的 PATH 中
## 手动安装
如果您更喜欢手动设置，或者快速入门脚本不适用于您的系统：
1. 克隆仓库
2. 运行启动脚本：
**Linux/macOS:**
```
./run.sh # Start web dashboard (default)
./run.sh qt # Start Qt desktop app
./run.sh both # Start both (web in background)
./run.sh stop # Stop all instances
./run.sh status # Check what's running
```
**Windows:**
```
run.bat # Start web dashboard
run.bat qt # Start Qt desktop app
run.bat stop # Stop all instances
```
启动器将自动创建虚拟环境并安装依赖项。
### Web 仪表板
配置仪表板：
在上面的示例中，公共位置是使用经度/纬度定义的。您可以使用您自己的位置、邮政编码、地址和经度/纬度。
在浏览器中打开：**http://127.0.0.1:8765**
搜索的初始结果。
带有 AI 生成内容的结果视图：
### Qt 桌面应用
使用 `./run.sh qt` 启动（或在 Windows 上使用 `run.bat qt`）。
带有 AI 生成内容的结果视图：
## 监控问题与 AI 洞察
**监控问题**功能允许您针对被监控的主题提出具体问题。AI 会分析最近的警报并生成针对性的洞察。
**问题示例：**
- “我所在地区停电风险最高的预期时间是几点？”
- “我现在应该清理车道，还是等雪停了再说？”
- “是否有影响 I-95 公路的出行建议？”
洞察会作为警报列表上方的可展开卡片显示，展示：
- **摘要**：对您问题的简要回答
- **解释**：带有支持证据的详细分析
在“设置”下的“AI 设置”中配置刷新间隔。
## Web 仪表板
Web 界面位于：**http://127.0.0.1:8765**
设置页面会提示输入：
- **事件/主题** - 要监控的内容
- **监控问题** - 用于获取 AI 洞察的具体问题
- **位置 / ZIP / GPS** - 地理位置过滤
- **半径（公里）** - 搜索区域
- **AI 设置** - 模型偏好，洞察刷新率
- **数据来源** - RSS feed，API 密钥
- **来源健康指标** - 各来源的获取健康状况表（上次成功时间、错误、延迟和条目计数）
附加数据视图：`http://127.0.0.1:8765/data`
## 零输入发现
如果您未提供任何 RSS feed 或 API 密钥，VigilantCore 依然会：
- 自动检测您的城市/区域 + ZIP + 坐标（尽力而为）。
- 从 **30 个精选的全球来源**进行种子填充，并发现 RSS/Atom feed。
- 添加基于您的主题 + 位置构建的 Google News RSS 查询，以获得更广泛的覆盖。
- 添加当地的公共安全查询（警察、治安官、消防、应急管理）。
- 尝试发现您位置附近的当地警察/政府和当地新闻 RSS feed。
- 通过与您的主题和位置绑定的 Reddit 搜索 RSS 获取社交讨论。
### RSS feed 与精选来源
默认情况下，您添加的任何 RSS feed 都会与内置的精选来源*合并*。
如果您只想使用自己提供的 RSS feed，请在“设置”中启用**“仅使用上面列出的 RSS feed”**。
要完全跳过 RSS 并仅使用 API/搜索提供商，请启用**“禁用 RSS 获取”**。
### 轮询间隔
您可以控制应用检查新数据的频率（默认为 **5 分钟**）。
- Web UI：**轮询间隔（分钟）**
- Qt UI：**轮询间隔（分钟）**
## 可选的搜索 API 密钥（获得更好的覆盖）
如果您设置了以下任何 API 密钥，VigilantCore 将自动使用它们。如果未设置，它将回退到 RSS 和内置的发现机制。
### Google Programmable Search Engine (CSE)
1. 创建一个 Custom Search Engine，并将其设置为**搜索整个网络**：
https://programmablesearchengine.google.com/
2. 启用 Custom Search JSON API 并创建一个 API 密钥：
https://developers.google.com/custom-search/v1/overview
3. 设置：
```
GOOGLE_CSE_API_KEY=your_key
GOOGLE_CSE_CX=your_search_engine_id
```
### Bing Web Search API
1. 在 Azure 中创建一个 Bing Search v7 资源：
https://learn.microsoft.com/en-us/bing/search-apis/bing-web-search/create-bing-search-service-resource
2. 设置：
```
BING_SEARCH_KEY=your_key
# 可选覆盖
BING_SEARCH_ENDPOINT=https://api.bing.microsoft.com/v7.0/search
BING_SEARCH_MARKET=en-US
BING_SEARCH_SAFE=Moderate
```
### DuckDuckGo Web Search（无需密钥）
无需 API 密钥即可使用 DuckDuckGo HTML 搜索。在“设置”中启用/禁用它：
- Web UI：**启用 DuckDuckGo web search**
- Qt UI：**启用 DuckDuckGo web search**
### 网络共享 / 低带宽模式
如果您使用的是移动热点或网络共享连接，请启用：
- Web UI：**针对共享 / 低带宽连接进行优化**
- Qt UI：**针对共享 / 低带宽连接进行优化**
此模式通过限制来源发现/查询预算并限制 feed 轮询/发现的广度，来减少请求量。
### Facebook & Instagram (Meta Graph API)
Meta 不提供通用的公开搜索 API。访问通常需要：
- 具有已批准权限的 Meta 应用
- 特定的主页/IG 商业帐户上下文
如果您拥有主页或 IG 商业帐户并希望进行定向摄取，请提交一个 issue，我们可以针对特定主页 ID 添加提供商。
### 精选的全球来源（已扩展）
默认列表现在包括美国、欧洲、东欧、中国、澳大利亚、南美洲和非洲的主要媒体。有关完整列表，请参见 `vigilant-core/utils/sources.py`。
## 辅助脚本 (script-helpers)
此仓库可以像该工作空间中的其他项目一样，使用共享的 `script-helpers` 库。
如果 submodule 不存在（例如在 CI 中），脚本将回退到最小化日志记录。
要在本地使用完整的辅助功能，请初始化一次 submodule：
```
./update
```
## 一行命令安装与运行（所有主要平台）
这些命令将创建本地虚拟环境、安装依赖并启动应用。
### macOS / Linux
```
python3 -m venv venv && source venv/bin/activate && pip install -r requirements.txt && python src/main.py
```
### Windows (PowerShell)
```
py -3.12 -m venv venv; .\\venv\\Scripts\\Activate.ps1; pip install -r requirements.txt; python src\\main.py
```
### Windows (CMD)
```
py -3.12 -m venv venv && call venv\\Scripts\\activate && pip install -r requirements.txt && python src\\main.py
```
## 一行命令安装脚本
对于非技术用户，这些脚本可处理设置和启动：
### macOS / Linux
```
./install.sh
```
### Windows (PowerShell)
```
./install.ps1
```
## 一键打包（可执行文件）
构建原生应用包，以便非技术用户无需 Python 即可运行：
```
pyinstaller --onefile --windowed src/main.py --name VigilantCore
```
## CI 自动化 (ci-helpers)
GitHub Actions 使用来自 `ci-helpers` 的可重用工作流进行 lint、测试和构建：
- 工作流文件：`.github/workflows/ci.yml`
- 可重用工作流：`nikolareljin/ci-helpers/.github/workflows/python.yml@production`
## 开发者设置
```
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python src/main.py
```
## 本地 LLM
默认情况下，应用使用来自 Ollama 的 `qwen2.5:7b`。如果 RAM 为 8GB 或更小，它会自动回退到 `qwen2.5:3b`，除非设置了 `OLLAMA_MODEL`。您可以通过以下方式进行覆盖：
```
export OLLAMA_MODEL=qwen2.5:7b
```
## 打包（一键应用）
```
pyinstaller --onefile --windowed src/main.py --name VigilantCore
```
## 仓库提示
- **仓库名称**：`vigilant-core`
- **分支保护**：在合并到 `main` 分支之前需要进行 PR 审查。
### NewsAPI 时间窗口
您可以控制 NewsAPI 结果的新鲜度。默认值为 **6 小时**。
- Web UI：**新闻时间窗口（小时）**
- Qt UI：**新闻时间窗口（小时）**
### NewsAPI 排序顺序
默认排序为**受欢迎程度** (popularity)。您也可以从“设置”UI 中选择**发布时间** (publishedAt) 或**相关性** (relevancy)。
## 文档
完整文档可在 `docs/` 文件夹中找到：
- [安装指南](docs/installation.md) - 详细的设置说明
- [配置指南](docs/configuration.md) - 所有配置选项
- [功能说明](docs/features.md) - 完整的功能文档
- [示例](docs/examples.md) - 实际使用示例（冬季风暴、停电等）
## 更新日志
有关发布历史和更改，请参见 [CHANGELOG.md](CHANGELOG.md)。
事件 schema 详情：[docs/event-normalization.md](docs/event-normalization.md)
## 克隆流量
_每日更新。过去 14 天的总计和独立克隆次数。_标签：AI分析, AI风险缓解, LLM评估, Ollama, 库, 应急响应, 情报预警, 本地大模型, 本地监控, 逆向工具