前言：当 Bloomberg Terminal 遇上开源精神

2026 年 7 月的 GitHub Trending 榜上，一个叫 WorldMonitor 的项目连续多日霸榜，Star 数冲到 68,000+。它的自我介绍很狂："Real-time global intelligence dashboard"——实时全球情报仪表板。

第一眼看截图，你会以为这是某个国防承包商的内部系统：3D 地球仪上叠着军事动态、航班轨迹、海运数据、地缘冲突热点；侧边栏滚动着 AI 合成的新闻简报；底部是 29 个证券交易所的行情雷达。而它实际上是一个 AGPL-3.0 开源项目，git clone 下来 npm run dev 就能跑，甚至不需要配置任何环境变量。

有人把它称为"Bloomberg Terminal 的开源精神续作"——只不过它覆盖的不是金融市场，而是全球安全态势：从 UCDP 冲突数据库到港口航运追踪，从消费价格指数到红色警报系统。

作为程序员，比起"它能看什么"，我更感兴趣的是"它是怎么做到的"。这篇文章我们从工程角度深度解剖 WorldMonitor：

• 为什么它敢用 Vanilla TypeScript（无框架） 撑起这么大的系统？
• 500+ 信源、65+ 数据提供商的聚合管道怎么设计？
• CII 国家不稳定指数的服务端评分模型如何工作？
• 281 个 Protobuf 文件、35 个服务的 API 契约体系有什么讲究？
• 一套代码怎么裂变出 6 个站点变体 + 桌面客户端？
• 以及，它为 AI Agent 时代做的那些"超前设计"——MCP Server、llms.txt、agent-skills manifest。

内容较长，建议先收藏再看。

一、项目全景：它到底做了什么

先把官方 README 里的核心能力清单翻译成人话：

这个清单里几乎每一行都够写一篇独立的技术文章。我们挑最有工程价值的几块深挖。

二、技术选型的"反潮流"：无框架 TypeScript

打开它的技术栈表格，第一行就很扎眼：

Frontend: Vanilla TypeScript, Vite, globe.gl + Three.js, deck.gl + MapLibre GL

没有 React，没有 Vue，没有 Svelte。一个渲染 56 种地图图层、25 种语言、6 个变体的重型 dashboard，用的是裸 TypeScript。

2.1 为什么这个选择是对的

对于 WorldMonitor 这类应用，虚拟 DOM 框架的收益其实很低，代价却很高：

1. 主战场在 WebGL，不在 DOM。 地球仪、地图图层、飞行轨迹全部走 Three.js / deck.gl 的 GPU 渲染管线，DOM 只承担面板、列表、弹窗这些"边角料"。为了边角料引入一整套 React 运行时 + 状态管理生态，属于杀鸡用牛刀。

2. 高频数据流对 diff 机制不友好。 实时行情、航班位置、事件流每秒都在变。走 React 的 setState → reconciliation → commit 链路，不如直接拿到 DOM 引用做定点更新：

// 无框架的定点更新模式（示意代码）
class TickerPanel {
  private priceEl: HTMLElement;
  private lastPrice = 0;

  constructor(container: HTMLElement) {
    this.priceEl = container.querySelector('.price')!;
  }

  // WebSocket 推送直达 DOM，没有中间商赚差价
  onTick(price: number) {
    if (price === this.lastPrice) return;
    this.priceEl.textContent = price.toFixed(2);
    this.priceEl.classList.toggle('up', price > this.lastPrice);
    this.priceEl.classList.toggle('down', price < this.lastPrice);
    this.lastPrice = price;
  }
}

3. 包体积与冷启动。 作为 PWA + 桌面应用双形态分发的产品，首屏加载每省 100KB 都是真金白银。Vite 构建裸 TS，Tree-shaking 干净利落。

2.2 代价是什么

当然，无框架不是免费午餐。你需要自己解决组件生命周期、状态同步、事件解绑这些框架帮你兜底的事情。WorldMonitor 能玩得转，一个重要前提是它的 UI 结构相对稳定——dashboard 的面板布局不像电商页面那样频繁重排。如果你的业务是表单密集型、路由复杂型，请不要盲目模仿。 选型永远看场景。

三、双地图引擎：globe.gl 与 deck.gl 为什么要并存

WorldMonitor 同时集成了两套地图渲染方案：

• globe.gl（基于 Three.js）：3D 地球仪视角
• deck.gl + MapLibre GL：WebGL 平面地图

这不是炫技，而是两种视角服务于两类认知任务：

3D 地球仪适合"态势感知"——你想一眼看到全球哪里在冒烟。弧线（航班、导弹轨迹预警）、光柱（事件强度）、大圆航线在球面上的表达远比墨卡托投影直观，而且没有高纬度变形问题。

平面地图适合"精确分析"——你要看具体某个海峡的船舶密度、某条边境线的事件分布，2D + 瓦片底图 + deck.gl 的数据图层组合效率更高。

deck.gl 的图层化架构值得单独说一下。它的核心思想是把可视化拆成可组合的数据驱动图层，56 种图层类型大概率是这样组织的（基于 deck.gl 标准用法的示意）：

import { Deck } from '@deck.gl/core';
import { ScatterplotLayer, ArcLayer, HeatmapLayer } from '@deck.gl/layers';

// 每类情报数据 = 一个独立图层，可单独开关、更新
const conflictLayer = new ScatterplotLayer({
  id: 'conflict-events',
  data: conflictEvents,           // UCDP 冲突事件流
  getPosition: d => [d.lon, d.lat],
  getRadius: d => Math.sqrt(d.fatalities) * 1000,
  getFillColor: d => severityColor(d.escalation),
  updateTriggers: {               // 数据变更时只重算受影响的 attribute
    getFillColor: [escalationVersion],
  },
});

const flightLayer = new ArcLayer({
  id: 'flights',
  data: adsbFlights,              // Wingbits ADS-B 航班数据
  getSourcePosition: d => d.origin,
  getTargetPosition: d => d.current,
  getWidth: 1,
});

deck.setProps({ layers: [baseMap, conflictLayer, flightLayer, heatLayer] });

这种架构的好处：图层之间完全解耦，军事图层挂了不影响金融图层；新增一类数据源只需要新增一个图层类；GPU attribute 的增量更新（updateTriggers）让高频数据刷新不至于整层重建。

56 种图层背后对应的其实是 56 类结构化数据流——这才是真正的工程量所在。

四、数据管道：500+ 信源怎么不被自己噎死

WorldMonitor 聚合了 65+ 外部数据提供商、500+ 精选信息源，并且有一个覆盖 35 个信源分组的新鲜度监控器（freshness monitor）。这是整个系统最重的部分。

4.1 三级缓存体系

官方架构明确提到：Redis (Upstash) + 3-tier cache + CDN + Service Worker。结合它部署在 Vercel Edge Functions（60+ 个）上的事实，缓存链路大致是：

浏览器 Service Worker  ←  CDN 边缘缓存  ←  Redis (Upstash)  ←  上游数据源
     (秒级命中)            (区域级共享)      (全局共享+限流保护)     (真实成本)

这个设计解决的核心问题是：上游 API 有配额，而用户请求无上限。65+ 个提供商里一定有按调用量计费或严格限流的（金融行情、ADS-B 航班数据都是重灾区）。三级缓存的本质是把"每用户每次请求"降维成"每数据源每 TTL 周期一次回源"。

Service Worker 层的策略大概率是经典的 stale-while-revalidate（示意）：

// service worker：先给缓存的旧数据保证秒开，后台静默更新
self.addEventListener('fetch', (event) => {
  if (!event.request.url.includes('/api/feeds')) return;

  event.respondWith(
    caches.open('feeds-v1').then(async (cache) => {
      const cached = await cache.match(event.request);
      const network = fetch(event.request).then((resp) => {
        cache.put(event.request, resp.clone());
        return resp;
      });
      // 有缓存先返回缓存，没缓存等网络
      return cached || network;
    })
  );
});

对情报类产品，这个策略有个微妙的权衡：新鲜度就是产品价值本身。所以它才需要专门的 freshness monitor 盯着 35 个信源分组——缓存可以旧几分钟，但系统必须知道自己"有多旧"，并把数据时效标注给用户。这是很多做聚合类产品的团队会忽略的细节：宁可展示"5 分钟前的数据"，也不要假装是实时的。

4.2 AI 合成简报：LLM 作为管道的一环

500+ 信源的原始输出是人类不可读的——每天几万条新闻标题。WorldMonitor 的做法是把 LLM 塞进数据管道：按 15 个分类把信源聚类，AI 合成成简报（brief）。

关键的架构决策是 LLM 推理层的可插拔抽象：Ollama（本地）/ Groq / OpenRouter 三种后端可切换，浏览器端还内置了 Transformers.js 做轻量推理。这意味着：

// LLM 后端抽象层（示意）
interface LLMBackend {
  synthesize(articles: Article[], opts: BriefOptions): Promise<Brief>;
}

class OllamaBackend implements LLMBackend {
  async synthesize(articles: Article[], opts: BriefOptions) {
    const resp = await fetch('http://localhost:11434/api/generate', {
      method: 'POST',
      body: JSON.stringify({
        model: opts.model ?? 'qwen2.5:7b',
        prompt: buildBriefPrompt(articles, opts.category),
        stream: false,
      }),
    });
    return parseBrief(await resp.json());
  }
}

// 云端配额耗尽 → 自动降级到本地
const backend = await pickBackend(['groq', 'openrouter', 'ollama']);

"Local AI — run everything with Ollama, no API keys required"这一条在 2026 年是非常聪明的产品决策：它同时解决了三个问题——用户隐私（情报浏览行为很敏感）、运营成本（不用为免费用户付推理费）、可用性（断网/被墙环境照样跑摘要）。

浏览器端的 Transformers.js 则大概率承担嵌入计算、分类打标这类小模型任务，把"每条新闻都要过一遍"的高频低智操作留在客户端，把"每小时合成一次简报"的低频高智操作交给大模型。这种按"调用频率 × 智力需求"二维拆分模型部署位置的思路，值得所有做 AI 应用的团队参考。

五、CII 国家不稳定指数：把地缘政治变成一个分数

WorldMonitor 最"情报机构范儿"的功能是 CII（Country Instability Index）国家不稳定指数，当前是 v8 版本，覆盖 31 个 Tier-1 国家，并且强调 server-authoritative（服务端权威）。

5.1 为什么必须 server-authoritative

这四个字是关键。如果 CII 在客户端计算，会出现两个致命问题：

1. 不同用户看到不同的分数——取决于各自客户端缓存到的数据切片，一个"指数"就失去了公信力；
2. 分数可以被伪造——对于一个可能被引用、被截图传播的指标，客户端计算等于放弃数据完整性。

所以 CII 的正确形态就是服务端统一计算、带版本号（v8）、全体用户读同一份。这和游戏服务器的"服务端权威状态"是同一个工程哲学：凡是需要一致性和可信度的状态，绝不能交给客户端。

5.2 多信号压力评分模型（推测性分析）

官方没有公开 CII v8 的完整公式，但从"cross-stream correlation（军事、经济、灾害、升级信号收敛）"的描述可以合理推断它是一个多信号加权模型，结构大致如下（以下为基于公开描述的示意伪代码，非官方实现）：

# CII 压力评分模型（示意伪代码）
def compute_cii(country: str, window: TimeWindow) -> CIIScore:
    signals = {
        # 军事信号：冲突事件密度、伤亡趋势（UCDP 等来源）
        "military":  conflict_density(country, window) * trend_multiplier(country),
        # 经济信号：汇率波动、CPI 异动、主权债利差
        "economic":  economic_stress(country, window),
        # 灾害信号：自然灾害等级与基础设施暴露度
        "disaster":  disaster_exposure(country, window),
        # 升级信号：红色警报、军事调动等离散事件
        "escalation": escalation_events(country, window),
    }

    # 关键设计：信号收敛加成——多个独立信号同时恶化时非线性放大
    convergence = convergence_bonus(signals)

    raw = sum(w[k] * normalize(v) for k, v in signals.items()) * convergence
    return CIIScore(
        value=clamp(raw, 0, 100),
        version="v8",
        components=signals,       # 可解释性：暴露分项
        computed_at=now_utc(),
    )

其中最值得学习的是"信号收敛"这个概念：单一维度的恶化（比如只是经济数据难看）不足为惧，但当军事、经济、社会信号在同一时间窗口内同向恶化时，系统性风险是非线性上升的。把这个直觉编码成 convergence 加成项，比简单加权求和高明得多。

做过风控系统的同学会觉得眼熟——这本质上和多因子风控引擎是同构的：单个弱信号不触发，多个弱信号共振就告警。地缘政治风险和信贷欺诈风险，在数学结构上是亲戚。

六、281 个 Protobuf、35 个服务：API 契约先行

技术栈里有一行容易被忽略但信息量巨大：

API Contracts: Protocol Buffers (281 protos, 35 services), sebuf HTTP annotations

一个"前端项目"维护着 281 个 proto 文件。这说明 WorldMonitor 走的是**契约先行（contract-first）**的 API 设计路线：

// 示意：情报事件服务的契约定义
syntax = "proto3";
package worldmonitor.intel.v1;

service IntelFeedService {
  // sebuf 注解把 gRPC 风格契约映射到 HTTP 端点
  rpc ListEvents(ListEventsRequest) returns (ListEventsResponse);
  rpc GetCountryRisk(GetCountryRiskRequest) returns (CIIScore);
}

message ListEventsRequest {
  string category = 1;        // military / economic / disaster ...
  string country_code = 2;
  int32 page_size = 3;
  string page_token = 4;
}

message CIIScore {
  double value = 1;
  string version = 2;         // "v8"
  map<string, double> components = 3;
  int64 computed_at = 4;
}

为什么这套东西对 WorldMonitor 特别重要？因为它的消费端太多了：

• Web 端 6 个变体
• Tauri 桌面端（走 Node sidecar）
• 官方 CLI（npm 包 worldmonitor）
• 四种语言的 SDK：Python、Ruby、Go、Node
• MCP Server（给 AI Agent 用）
• 公开 REST API（带 OpenAPI spec）

如果没有统一契约，SDK 和客户端的类型漂移会在半年内把维护者拖死。Proto 作为单一事实来源（single source of truth），代码生成管道自动产出各语言的类型和客户端——这是"一个人维护一个平台级项目"能成立的前提条件之一。

sebuf HTTP annotations 是把 proto 服务映射到普通 HTTP/JSON 端点的注解方案，让契约既服务于内部 RPC，又能生成对外的 REST API 与 OpenAPI 文档。相比手写 OpenAPI YAML，这条路的维护成本低一个数量级。

七、一鱼六吃：单代码库的变体工程

WorldMonitor 从一套代码构建出 6 个站点：

• worldmonitor.app（全量：地缘政治）
• tech.（科技）、finance.（金融）、commodity.（大宗商品）、energy.（能源）
• happy.（只看好消息——这个变体挺有幽默感）

开发命令直接暴露了实现思路：

npm run dev:tech       # tech.worldmonitor.app
npm run dev:finance    # finance.worldmonitor.app
npm run dev:commodity  # commodity.worldmonitor.app

这是典型的**构建时变体（build-time variants）**方案：同一套组件库和数据管道，通过变体配置文件决定启用哪些信源分类、哪些地图图层、哪套主题色。相比运行时判断，构建时裂变的好处是每个变体的产物只包含自己需要的代码和配置，包体积和攻击面都更小。

更妙的是桌面端的处理：一个 Tauri 二进制，应用内切换变体（"One Tauri binary that switches variants in-app"）。桌面端不适合发 6 个安装包，于是变体从"构建时"退回"运行时"——同一个决策在不同分发渠道上做了不同的取舍。工程上没有教条，只有场景。

7.1 Tauri 2 + Node.js Sidecar 的安全课

桌面端架构是 Tauri 2（Rust 壳）+ Node.js sidecar。Tauri 负责窗口、系统集成和更新，真正的数据逻辑跑在旁挂的 Node 进程里——这样 Web 端的 TypeScript 数据管道代码可以原样复用。

但 README 的 Security Acknowledgments 部分泄露了这套架构的坑：安全研究员披露了三个安全问题，关键词是 "IPC command exposure"（IPC 命令暴露）、"renderer-to-sidecar trust boundary"（渲染进程到 sidecar 的信任边界）、"fetch patch credential injection"（fetch 补丁凭证注入）。

这三个词值得每个做 Tauri/Electron + sidecar 架构的团队抄在小本本上：

1. IPC 命令暴露：Tauri 的 command 默认注册给渲染进程就能调。如果把敏感操作（文件读写、进程管理）注册成 command 又没做权限校验，等于给潜在的 XSS 开了系统级后门。
2. 渲染进程 → sidecar 信任边界：渲染进程是最容易被攻破的（它跑着从网上拉的内容），sidecar 拿着 API 凭证和本地权限。两者之间必须当作不可信边界来设计——消息要校验、能力要收窄，不能因为"都是自己的代码"就互相裸通。
3. 凭证注入：如果桌面端通过 patch 全局 fetch 来自动附加 API Key，就要小心恶意页面内容诱导应用向攻击者域名发请求，把凭证带出去。凭证附加必须绑定域名白名单。

WorldMonitor 把这些披露公开致谢并修复，这个透明度在个人开源项目里算是模范水平。

八、为 Agent 时代而生：MCP、llms.txt 与四语言 SDK

WorldMonitor 有一句自我定位很超前："built for agents and scripts as well as browsers"——它把 AI Agent 当作和人类浏览器平级的一等公民。落地在四件事上：

8.1 MCP Server

它暴露了一个 Streamable HTTP 的 MCP 端点 https://worldmonitor.app/mcp，tools/list 公开可访问，tools/call 用 X-WorldMonitor-Key 或 OAuth 鉴权：

# 不需要任何 key 就能看它暴露了哪些工具
npx worldmonitor tools

# 查询某国风险评分（CLI 内部走同一套契约）
worldmonitor risk IR --api-key wm_xxx

这个"list 公开、call 收费"的设计是 MCP 服务商业化的标准姿势：让 Agent（和它背后的开发者）零成本发现能力，付费才真正调用。

8.2 Agent 发现文件

它在标准位置放齐了三件套：

• llms.txt —— 给 LLM 爬虫看的站点说明
• .well-known/agent-skills/index.json —— Agent 技能清单
• .well-known/api-catalog —— API 目录

这套东西在今天绝大多数网站上都不存在。WorldMonitor 提前把"被 Agent 集成"的路铺好了——当你的用户开始用 AI 助手获取信息时，你的服务是助手能直接调用的那一个，还是被摘要转述的那一个，商业价值天差地别。

8.3 零依赖 SDK 矩阵

Python（worldmonitor-sdk）、Ruby、Go、Node 四种官方 SDK，全部强调 zero-dependency（零依赖）。零依赖对 SDK 是美德：没有传递依赖冲突、没有供应链攻击面扩大、安装秒完成。能做到零依赖，还是因为上游契约统一（proto 生成），SDK 只是薄薄一层 HTTP 封装。

九、冷思考：光环下的风险清单

按惯例，泼几盆冷水。

1. 数据源的合规与持续性风险。 65+ 上游提供商，每一家的 ToS、配额政策、API 稳定性都是不可控变量。ADS-B 航班数据靠 Wingbits "graciously provided"（无偿提供），这类合作关系一旦变化，核心功能就会缺一角。聚合类产品的宿命是：你的可用性是所有上游可用性的乘积。

2. "情报"的准确性边界。 AI 合成简报意味着幻觉风险直接进入了"情报"语境——在地缘政治领域，一条被 LLM 扭曲的摘要可能造成真实的误判。CII 指数看起来客观，但权重设计里全是主观判断。用它做态势感知可以，做决策依据需要极其谨慎。README 没有明显的"情报免责与置信度说明"体系，这是产品层面的欠账。

3. 单人项目的巴士系数。 版权署名是个人开发者（Copyright 2024-2026），核心维护高度集中。68k Star 的关注度和一个人的维护带宽之间，长期看必然出现缺口。AGPL + 商业授权双轨制是对的路，但能否养活一个可持续团队还是未知数。

4. AGPL 的商用门槛。 AGPL-3.0-only 意味着任何基于它做 SaaS 的团队都必须开源自己的修改。这保护了作者，但也劝退了一大批潜在的企业贡献者。对想借鉴它的团队：看架构、学思路没问题，抄代码进闭源产品是法律雷区。

十、总结：这个项目真正值得抄的四件事

WorldMonitor 表面上是个"新闻聚合大屏"，工程内核上它示范了四件事：

1. 技术选型服务于渲染主战场——主体是 WebGL 就不要为 DOM 边角料引入框架税；deck.gl 的图层化架构是多源可视化的正确抽象。
2. 聚合系统的生命线是缓存与新鲜度的显式管理——三级缓存扛成本，freshness monitor 保诚实，两者缺一不可。
3. 契约先行是多端矩阵的唯一解——281 个 proto 生成 Web/桌面/CLI/四语言 SDK/MCP 的全部类型，单人维护平台级项目的秘密就在这里。
4. 为 Agent 铺路要趁早——MCP Server、llms.txt、agent-skills manifest，这些今天看是加分项，两年后会是基础设施。

最后说句实在话：这种项目最大的价值不是让你去部署一个"个人情报中心"（虽然确实很酷），而是它把一个平台级系统的完整工程实践——数据管道、评分模型、多端分发、Agent 集成、安全响应——全部摊开在你面前供你翻阅。68k Star 里，至少有一半是给这份"可学习性"的。

仓库地址：github.com/koala73/worldmonitor，AGPL-3.0，clone 下来跑一遍，比读十篇分析文章都有用。