SDCofA/mena-threat-index

## 执行摘要 MENA 威胁指数 (MTI) 是一个持续维护的工具，将中东和北非的开放新闻流转化为单一、可审计的地缘政治风险读数 —— 为二十四个国家/地区提供 1–10 级的评级，以及战略加权的区域综合指标 —— 每两小时刷新一次。该指数对该读数进行向前预测，并将其与全球市场（石油、黄金、外汇和国防股）相关联，以描述价格如何应对区域风险。 MTI 专为需要可重复、有证据支持的事态感知信号，而非一次性叙述性评估的分析师、风险官员和决策者而设计。它是**边境邻国威胁指数 (BNTI)** 的继任者，从土耳其的七个邻国扩展到整个 MENA 战区，并在经过实质性改进的方法论基础上进行了重构。该指数发布的每一个读数都是可复现的，在失败时会被暂缓发布，并且可以追溯到其来源。 ## 评估说明 MTI 是一个**新闻频率的地缘政治风险指数**。它衡量区域报道的数量和严重程度，并将其渲染为每个国家/地区 1–10 级的评级和战略加权的区域综合指标，然后对该信号进行向前预测并将其与观察到的市场行为联系起来。该指数衡量以下内容： - **覆盖范围与深度。** 24 个 MENA 国家，从精选的媒体源和有保障的 Google 新闻层获取数据，以每个市场占主导地位的当地语言以及泛区域英语源进行查询。 - **严重性，而非噪音。** 每个标题都被映射到一个固定权重的事件类别。国家得分应用了近因衰减、来源可信度加权和经验贝叶斯缩减。权重在运行期间从不改变，因此可以精确重构任何历史读数。 - **具有明确不确定性的前瞻路径。** AR(1) / 阻尼 Holt / 持续性阶梯模型将平滑后的指数向前预测 24 小时，并带有不断扩大的 80% 预测区间。 - **市场联动。** 该指数为包括布伦特原油、WTI 原油、黄金、VIX 指数、标普 500 指数、国防与航空航天 (ITA) 以及区域外汇在内的工具计算滞后的“威胁 beta”——在错误发现率控制下进行，启动统计数据由 BNTI 初始化。 - **每次读数均提供置信度。** 每个国家/地区和综合指标都带有 0–1 的置信度分数，该分数结合了事件量、来源多样性（Shannon 熵）和跨来源印证。 - **发布前的纪律性。** 未能通过验证或低于数据源覆盖阈值的运行将被*暂缓发布*：系统将保留最后已知良好的快照，而不是发布降级的读数。 ## 方法论与来源 公司坚持一个首要原则 —— **在得出结论之前先提供证据**。该指数发布的每一个数据都带有其来源、收集时间以及得出该数据的方法。处理链是固定且可检查的： ``` RSS / Google News (24 countries, multilingual) │ feeds.py fetch · dedupe · 72h window ▼ categorize.py keyword engine (+ optional NVIDIA LLM) ▼ score.py recency-decay · source credibility · volume shrinkage │ per-country index = 1 + 9·(1 − e^(−raw/5·1.2)) │ composite = strategic-weighted mean, EWMA spike-guard ▼ history.py append reading to data/history.jsonl (persistent, growing) ▼ forecast.py AR(1)-with-drift (cold-start ladder) → 24h path + bands ▼ markets.py Yahoo + FRED prices · lagged correlation · "threat beta" │ · BNTI-seeded · project market moves from forecast path ▼ briefing.py templated regional summary (+ optional LLM polish) ▼ publish.py assemble + validate → mena_data.json (atomic, withhold-on-failure) ``` **类别与权重。** 每个标题被分配一个对应于固定严重性权重的类别 —— 军事冲突 8，恐怖主义 7，边境安全 5，政治不稳定 4，人道主义危机 3，外交紧张 2.5，贸易或局势缓和 −2，中性 0。固定权重设计遵循既定的事件数据严重性量表（Goldstein 1992; CAMEO），并确保每次运行都是可审计的。 **国家/地区得分。** `1 + 9·(1 − e^(−eff/5·1.2))`，其中 `eff` 是经过近因衰减（18 小时半衰期）、来源可信度加权的平均事件权重，并通过经验贝叶斯方法向该国/地区的历史基准线进行缩减。该级别反映的是**严重性，而非原始数量**。 **综合指标。** 各国得分的战略加权平均值，使用非对称 EWMA 进行平滑处理 —— 对真实的激增做出响应，同时抵御两小时内的来回波动。 **预测。** 将 AR(1) / 阻尼 Holt / 持续性阶梯模型应用于平滑序列，向前预测 24 小时，并带有不断扩大的 80% 预测带。 **市场。** 每种工具的滞后“威胁 beta”，通过市场模型事件研究法进行估算，并由最小样本量、符号稳定性、滞后搜索校正和 Benjamini–Hochberg 错误发现率控制进行门控。这种关系被报告为**关联，而非因果关系**；发布当日的统计数据由 BNTI 初始化，并已作相应标记。 完整的公式、常数及其背后的学术参考文献位于 `config/settings.yml`、应用内的**方法论**页面以及 [`METHODOLOGY_REVIEW.md`](METHODOLOGY_REVIEW.md) 中。 ### 每个数据的来源 秉承公司准则 —— 仅使用公开来源，每次读数均可追溯： - 每个事件都带有其**来源**、**收集窗口**、近因衰减权重及其来源可信度系数。 - 综合指标和各国历史记录以仅追加的方式存储在 `data/history.jsonl` 和 `data/countries/*.jsonl` 中，作为系统的真实数据源。 - 每次运行的市场快照被写入 `data/markets/instruments.jsonl`。 - 收集过程合法且仅限开源。可选的语言模型步骤严格从环境中读取其密钥，从不持久化存储。未能通过 schema 验证或覆盖阈值的运行将被暂缓发布，而不会对外发布。 ## 覆盖范围 该指数涵盖了中东和北非的二十四个国家，以每个市场占主导地位的当地语言以及泛区域英语源进行查询。泛区域媒体 —— **半岛电视台、中东之眼、The New Arab、Al-Monitor** —— 仅抓取一次，只有在标题指明具体国家时才将其归因于该国，以防止在整个战区内重复计算。覆盖范围在广度上是有意广泛的，但在深度上明确不均；每次读数的置信度分数披露了在给定运行中对任何一个国家/地区的观测是稀少还是丰富。 ### 预览 ## 数据与来源 | 数据流 | 来源 | |---|---| | **新闻** | 精选媒体 RSS/Atom 源以及有保障的 Google 新闻 RSS 层，涵盖 24 个 MENA 国家和多种语言。泛区域源仅在标题指明具体国家时才归因于该国。 | | **市场** | 从 Yahoo Finance 免密钥提取的价格序列，并以 FRED 作为备用，涵盖 `config/markets.yml` 中定义的能源、金属、利率、股票和外汇工具。 | | **历史** | 仅追加的 `data/history.jsonl`（综合指标）、`data/countries/*.jsonl`（各国）、`data/markets/instruments.jsonl`（每次运行的市场快照）—— 系统的真实数据源。 | | **种子** | 位于 `data/seed/` 中的原 BNTI 历史数据，用于初始化发布当日的相关性。 | 这些数据流背后的技术设备： - **Pipeline。** Python 3.11 —— `feedparser`、`requests`、`numpy`、`pandas`、`PyYAML`。所有统计 —— AR(1)、OLS、Newey–West、相关性、bootstrap —— 均在 NumPy 中实现，以保持 pipeline 精简且 CI 稳健。 - **可选的语言模型。** NVIDIA 的 OpenAI 兼容 API（`integrate.api.nvidia.com`，默认模型 `meta/llama-3.3-70b-instruct`），用于标题分类和简报润色。完全可选 —— 当不存在密钥时，pipeline 在关键词引擎上确定性地运行。 - **前端。** 静态单页应用 —— `index.html` 加上 `support.js`，一个独立的基于 React 的模板 runtime。无需构建步骤，无需打包器。 - **市场数据。** Yahoo Finance 和 FRED，无需 API 密钥。 - **自动化。** GitHub Actions —— **MTI Pipeline** 工作流（`cron: 0 */2 * * *`，每两小时）重新计算指数，提交 `mena_data.json` 和 `data/`，并部署 Pages。 - **托管。** GitHub Pages（静态）。**在线演示：** - **测试。** 一个 `pytest` 测试套件，涵盖源、分类、评分、预测、市场、schema 以及前端数据契约。 ### 仓库布局 | 路径 | 功能 | |---|---| | `index.html` | Web 应用程序（由 GitHub Pages 提供服务）。 | | `support.js` | 模板 runtime。 | | `mena_data.json` | 最新发布的快照 —— 由 pipeline 提交。 | | `config/*.yml` | 国家和源、市场工具、类别词典、设置。 | | `pipeline/*.py` | 数据 pipeline（通过 `python -m pipeline.run` 运行）。 | | `data/history.jsonl` | 仅追加的综合历史记录（真实数据源）。 | | `data/countries/*.jsonl` | 各国历史记录。 | | `data/markets/instruments.jsonl` | 每次运行的市场快照。 | | `data/seed/` | 原 BNTI 历史数据，用于初始化相关性。 | | `scripts/` | 一次性实用程序 —— BNTI 种子数据注入、预测回测、敏感性分析。 | | `.github/workflows/` | 定时 pipeline 和 Pages 部署。 | | `tests/` | `pytest` 测试套件。 | ## 复现 无法从干净的代码检出中重新推导出的读数就是一个隐患。该指数可端到端复现。 **在线部署：** ### 在本地运行 pipeline ``` pip install -r requirements.txt # 确定性运行（keyword categorizer，无 LLM）： python -m pipeline.run # 使用 LLM categorization + briefing polish（NVIDIA，OpenAI-compatible API）： export NVIDIA_API_KEY=nvapi-xxxxxxxx # Windows PowerShell: $env:NVIDIA_API_KEY="nvapi-..." python -m pipeline.run # Serve the site： python -m http.server 8000 # then open http://localhost:8000/ ``` `python -m pipeline.run` 会写入并刷新 `mena_data.json`，向 `data/` 追加内容，并在运行未通过验证或源覆盖率过低时**暂缓**更新 —— 保留最后已知良好的文件。使用 `pytest` 运行测试套件。 ### 部署（GitHub Pages + Actions） 1. 推送此仓库，并设置 **Settings → Pages → Build and deployment → Source: GitHub Actions。** 2. *(可选)* 在 **Settings → Secrets and variables → Actions** 下添加 `NVIDIA_API_KEY`。在没有它的情况下，pipeline 也能完全在关键词分类器上运行。 3. **MTI Pipeline** 工作流每两小时运行一次（cron），重新计算指数，提交 `mena_data.json` 和 `data/`，并部署 Pages。可通过 **Actions → MTI Pipeline → Run workflow** 手动触发。 ## 标准 - **在得出结论之前先提供证据。** 每次读数都附带其来源、收集时间和方法。任何没有来源的数据都不会出现在仪表板上。 - **仅限合法、开源收集。** 仅限公开来源。可选的 NVIDIA 密钥仅作为 GitHub Actions secret 存在，在 runtime 从 `NVIDIA_API_KEY` 读取，从不写入此仓库中的任何文件。如果密钥以明文形式暴露，请在 轮换密钥。 - **可复现性。** 该指数可以从干净的代码检出中精确重构；固定权重和仅追加的历史记录保证了任何过去的读数都可以被复现。 - **设计上的故障安全。** 降级的运行会被暂缓发布，而不是对外发布。宁可保持沉默，也不发出错误的信号。 - ** Apache-2.0 许可下授权** —— 参见 [`LICENSE`](LICENSE)。© 2026 Monarch Castle Holdings · 土耳其安卡拉。

_{安卡拉战略数据公司 · 安卡拉 · 土耳其 · MMXXVI}

标签：代码示例, 后端开发, 地缘政治, 安全规则引擎, 宏观经济, 恶意代码分类, 数据分析, 逆向工具, 金融量化