World Monitor（worldmonitor）源码解读

仓库：https://github.com/koala73/worldmonitor
作者：Elie Habib（GitHub @koala73）
版本：v2.10.0 ｜ 许可证：AGPL-3.0-only
定位：Real-time global intelligence dashboard —— AI 驱动的新闻聚合、地缘政治监控与基础设施追踪，统一于态势感知界面。

---

1. 项目名称、作者及其介绍、作用和背景

1.1 名称与作者

• 项目名称：World Monitor（仓库名 worldmonitor，npm 包名 worldmonitor / 别名 wm）。
• 作者：Elie Habib（GitHub @koala73），版权声明 Copyright (C) 2024-2026 Elie Habib. All rights reserved.。仓库已有 5,000+ 次提交，是作者长期独立维护的大型项目。
• 协作与安全：贡献者以作者为主；安全致谢中提及 Cody Richard 在 2026 年负责任披露了 IPC 命令暴露、渲染进程↔sidecar 信任边界、fetch 补丁凭据注入三类问题。

1.2 作用（What It Does）

World Monitor 是一个实时全球情报仪表板，把分散在地缘政治、金融、能源、气候、航空、网络、军事、基础设施、新闻情报等 9 大领域的 530+ 上游主机、500+ 精选订阅源聚合成统一的可视化"态势感知"界面。核心能力包括：

• 500+ 精选新闻源（15 个分类），由 AI 合成为简报（brief）。
• 双地图引擎：3D 地球（globe.gl）与 WebGL 平面地图（deck.gl + MapLibre），共 56 种地图图层类型。
• 跨流关联（Cross-stream correlation）：军事 / 经济 / 灾害 / 升级（escalation）信号的汇聚（signal convergence）。
• 国家不稳定指数（CII，Country Instability Index）：服务端权威的 CII v8 压力评分，覆盖 31 个 Tier-1 国家。
• 金融雷达：29 个股票交易所、大宗商品、加密资产，以及 7 信号市场综合指标。
• 本地 AI：可配合 Ollama 完全离线运行，无需任何 API Key。
• 6 个站点变体（world / tech / finance / commodity / happy / energy）由同一套代码库构建。
• 原生桌面客户端（Tauri 2），覆盖 macOS / Windows / Linux。
• 26 种语言（含原生语种订阅源与 RTL 右到左排版支持）。

1.3 背景与动机

在信息高度碎片化的当下，单一信源难以形成全局态势判断。World Monitor 的出发点就是把"全球正在发生什么"压缩进一个可交互、可检索、可被 AI 代理程序化调用的面板里。它既服务于普通浏览器用户（公开部署在 worldmonitor.app 等 6 个域名），也通过 MCP 服务器、REST API、CLI、多语言 SDK 服务于自动化代理（agents）与脚本——这使它本质上是一个"人类与 AI 都能消费的情报平台"。许可证选择 AGPL-3.0，意味着自托管与商用均被允许，但需遵守 copyleft 与源码可得性义务。

---

2. 安装和使用教程、依赖的软件或硬件条件

2.1 快速开始（本地开发）

git clone https://github.com/koala73/worldmonitor.git
cd worldmonitor
npm install
npm run dev

• 默认打开 http://localhost:3000（可用 .env.local 中的 DEV_PORT 覆盖端口）。
• 应用 无需任何环境变量即可运行（零配置启动）。

变体专属开发：

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

2.2 质量门禁与构建

npm run typecheck      # 类型检查（tsc --noEmit）
npm run lint           # Biome 代码检查 + 安全 HTML 检查
npm run build:full     # 全量生产构建（含 openapi / agent-skills / blog / sitemap / crawlable corpus）
npm run build:desktop  # 构建 Tauri 桌面端（需 Rust 工具链）

变体构建脚本：build:tech / build:finance / build:happy / build:commodity / build:energy，均通过 cross-env VITE_VARIANT=<variant> 注入变体标识。

2.3 部署方式（自托管）

官方提供三种途径（详见 SELF_HOSTING.md）：

• Vercel：Edge Functions + 静态文件，最贴近官方部署形态。
• Docker：仓库含多份 Dockerfile（Dockerfile、Dockerfile.relay、Dockerfile.digest-notifications、Dockerfile.publish-bootstrap-tiers、Dockerfile.seed-bundle-*、Dockerfile.umami*），并有 docker-compose.yml 与 deploy/nginx 反向代理配置。
• 静态（Static）：前端构建产物可纯静态托管。
• 桌面端：Tauri 二进制（Windows .exe / macOS Apple Silicon & Intel / Linux AppImage），由 CI 在 Release 时构建，一个二进制内含全部变体，应用内切换。

2.4 程序化访问（面向 Agent / 脚本）

• MCP 服务器：https://worldmonitor.app/mcp（Streamable HTTP）。tools/list 公开；tools/call 通过 X-WorldMonitor-Key 头或 OAuth 鉴权。
• REST API：基址 https://api.worldmonitor.app，由 openapi.yaml 描述。
• CLI：npx worldmonitor tools（免 key 列出全部 MCP 工具）；npm i -g worldmonitor 安装 worldmonitor（别名 wm）命令，如 worldmonitor risk IR --api-key wm_xxx。
• SDK：官方零依赖客户端库——Python worldmonitor-sdk（sdk/python/）、Ruby worldmonitor（sdk/ruby/）、Go github.com/koala73/worldmonitor/sdk/go（sdk/go/）。
• Agent 发现文件：llms.txt、/.well-known/agent-skills/index.json、/.well-known/api-catalog。

2.5 依赖的软件 / 硬件条件

软件依赖（来自 package.json）：

• 运行时：Node.js（.nvmrc 指定版本；ESM 模块，"type": "module"）。
• 包管理：npm（package-lock.json 锁文件）；.npmrc 配置镜像/作用域。
• 前端栈：Vanilla TypeScript + Vite 6、Preact（轻量视图层）、globe.gl + Three.js、deck.gl + MapLibre GL、d3、pmtiles、supercluster、h3-js。
• AI/ML（浏览器端）：@xenova/transformers（Transformers.js）+ onnxruntime-web（ONNX 推理）。
• 后端/边缘：Vercel Edge Functions + @vercel/functions；Convex（convex）；Upstash Redis（@upstash/redis / @upstash/ratelimit）。
• 协议契约：Protocol Buffers（@bufbuild/buf，295 个 proto / 36 个 service，sebuf HTTP 注解）。
• 桌面：Tauri 2（Rust 壳 + Node.js sidecar），需 Rust 工具链（cargo）。
• 测试：Playwright（e2e）、Vitest（dom/contract）、tsx --test（node 测试）。
• 代码质量：Biome 2、markdownlint-cli2。

数据源凭据（可选）： 部分功能源需要凭据，完整清单见 .env.example，例如 Finnhub、OpenSky、GDELT、ACLED、FRED、FIRMS、Wingbits（ADS-B 航空数据）、Oref（以色列警报）、Polymarket（预测市场）、Telegram 等。无凭据时核心面板仍可用（走引导种子缓存）。

硬件条件： 浏览器端即可运行；本地 AI 模式（Ollama）需要本机有可用算力跑嵌入/摘要模型。生产部署依赖 Vercel / Railway / Cloudflare / Convex / Upstash 等云服务账号。

---

3. 项目的工作流程和具体的执行步骤

World Monitor 的运行时是一条"上游摄取 → 边缘缓存 → 客户端 AI 合成 → 统一可视化"的流水线。下面按阶段拆解。

3.1 数据摄取（Ingestion）

1. 种子脚本（scripts/seed-*.mjs）：抓取上游源 → 转换为统一结构 → 调用 atomicPublish() 写入 Redis（atomicPublish 负责加锁、校验、写 seed-meta:<key> 元数据）。
2. AIS Relay 主播种器（Railway）：WebSocket 代理 + 种子循环，覆盖市场数据、航空延误、正向外事件、GPSJAM、风险评分（CII）、UCDP 冲突事件等。
3. Consumer Prices（Railway 容器）：用 Playwright 按国家"篮子"爬取消费者价格，结果经 Redis 发布。
4. 健康监控（api/health.js）：比对 seed-meta 的 maxStaleMin，返回 OK / STALE / WARN / EMPTY，供 seed-freshness-monitor.yml（15 分钟 cron）验收生产摄取。

3.2 四层缓存（Caching Hierarchy）

Bootstrap seed (Railway → Redis)
  ↓ miss
In-memory cache (Vercel 实例内)
  ↓ miss
Redis (Upstash, cachedFetchJson 合并并发 miss，防 stampede)
  ↓ miss
Upstream API fetch → 写回 Redis + seed-meta

• 缓存分级：fast(300s) / medium(600s) / slow(1800s) / static(7200s) / daily(86400s) / no-store(0)。
• ETag 用 FNV-1a 对响应体哈希，客户端 If-None-Match 命中返回 304。
• CDN-Cache-Control 长于 Cache-Control，Cloudflare 经 ETag 重验。

3.3 引导水合（Bootstrap Hydration）

• /api/bootstrap 批量读取 Redis 缓存键。
• SPA 并发拉取 fast（3s 超时）与 slow（5s 超时）两层，各自独立 abort。
• 各面板通过 getHydratedData(key) 按需消费已水合数据。

3.4 客户端 AI 合成（完全在浏览器 Worker 内）

• ml.worker.ts：运行 ONNX 推理（@xenova/transformers），执行 MiniLM-L6 嵌入、情感分析、摘要、NER（命名实体识别），并用内置向量库存标题记忆。
• analysis.worker.ts：新闻聚类（Jaccard 相似度）、跨域关联检测（signal convergence / focal points）。
• vector-db.ts：IndexedDB 支撑的向量库，提供语义搜索。
• 启动时 App.init() 阶段 2 准备 ONNX 模型（嵌入 / 情感 / 摘要）。

关键设计：AI 合成完全在客户端 Worker 完成，服务端不调用 LLM（除"直连 LLM 配额"等高级 RPC 外）。这带来隐私与离线优势。

3.5 网关请求处理（Edge Gateway Pipeline）

server/gateway.ts 的 createDomainGateway(routes) 返回处理器，按 19 步顺序执行（详见第 4 节 server/ 模块）。核心顺序：请求净化 → 源站检查（403）→ CORS（fail-closed 500）→ OPTIONS 预检（204）→ 内部 MCP HMAC 校验 → 会话解析 → API Key 校验 → 权益（Entitlement）检查 → 路由匹配 + POST→GET 兼容 → 幂等键 → 速率限制 → 处理器执行 → 响应头合并 + 缓存/ETag 决策。

3.6 前端渲染与刷新

• App.init() 八阶段：① Storage + i18n → ② ML Worker 准备 → ③ Sidecar 等待（桌面）→ ④ Bootstrap 两层并发水合 → ⑤ Layout 渲染 → ⑥ UI 组件 + 关联引擎 → ⑦ Data 并行加载 → ⑧ Refresh 轮询启动。
• startSmartPollLoop()：指数退避、视口条件刷新、标签隐藏暂停。
• 双图系统：面板可在平面（DeckGLMap）与地球（GlobeMap）间切换，配置持久化到 localStorage。

3.7 部署拓扑（Production Topology）

服务	平台	角色
SPA + Edge Functions	Vercel	静态文件、API、中间件
CORS Preflight Worker	Cloudflare	边缘 CORS（短接 OPTIONS）
AIS Relay	Railway	WebSocket 代理、种子循环、RSS 代理
Consumer Prices	Railway	Playwright 爬虫 + Redis 发布
Redis	Upstash	缓存、stampede 保护、限流
Convex	Convex Cloud	计费、用户态、历史情报向量库
Desktop	Tauri 2.x	macOS/Windows/Linux 桌面端
容器镜像	GHCR	多架构 Docker 镜像

Cloudflare 区域配置要点：/mcp 与 /oauth/* 在 apex 重定向豁免列表中为关键负载项（删除会破坏 MCP 客户端或 OAuth 注册，见 issue #4938）。mcp-live-smoke.yml 每 6 小时探测 MCP/OAuth 成员列表。

---

4. 项目的各个文件的内容和作用（按模块）

仓库为单一代码库（非 npm workspaces，靠脚本协调 blog-site、pro-test 等子项目），根目录共 54 个文件 + 23 个目录。下面按模块梳理。

4.1 根目录配置文件（节选关键）

文件	作用
package.json	项目清单：name=world-monitor、version=2.10.0、AGPL-3.0、全部 npm 脚本与依赖（见第 2 节）。
package-lock.json	依赖锁文件。
tsconfig.json / tsconfig.api.json / tsconfig.dom-tests.json / tsconfig.contract-tests.json	多套 TypeScript 配置（前端 / API / DOM 测试 / 契约测试）。
vite.config.ts	Vite 构建配置（前端 SPA + PWA）。
vercel.json	Vercel 部署配置（Edge Functions、路由）。
middleware.ts	Vercel 中间件（机器人过滤、OG 图像处理）。
biome.json	Biome 2 代码检查/格式化规则。
playwright.config.ts	Playwright e2e 测试配置。
vitest.config.mts / vitest.dom.config.mts	Vitest 单测配置（含 DOM 测试）。
Dockerfile + Dockerfile.*	多份镜像定义（主站、relay、digest 通知、bootstrap tiers 发布、seed bundle 各类、umami 及其留存）。
docker-compose.yml	本地多容器编排。
Makefile	常用任务快捷命令。
nixpacks.toml	Nixpacks 构建配置（Railway 等）。
.env.example	全部可选数据源凭据清单（Finnhub / OpenSky / GDELT / ACLED / FRED / FIRMS / Wingbits / Oref / Polymarket / Telegram 等）。
server.json	服务端运行/构建配置。
index.html / settings.html / mcp-grant.html / live-channels.html / embed.html	入口 HTML 与功能页（设置、MCP 授权、直播频道、嵌入）。
README.md / README.zh-CN.md / README.ja-JP.md	多语言主页文档。
ARCHITECTURE.md	架构文档（分层、数据流、模块边界、部署拓扑）。
CONCEPTS.md	共享领域词汇表（缓存/出口、通知、计费、态势、MCP 等术语骨架）。
AGENTS.md	给 AI 代理的贡献/协作约定。
SELF_HOSTING.md	自托管指南（Vercel / Docker / 静态）。
SECURITY.md	安全披露政策。
CONTRIBUTING.md / CODE_OF_CONDUCT.md / CHANGELOG.md	贡献指南、行为准则、变更日志。
LICENSE	AGPL-3.0-only 全文。
.impeccable.md / compound-engineering.local.md	工程实践/复合工程本地笔记。
.husky/	Git hooks（pre-commit / pre-push）。
.github/	Issue 模板、PR 模板、dependabot.yml、30+ CI 工作流（build-desktop.yml、deploy-gate.yml、seed-freshness-monitor.yml、mcp-live-smoke.yml、proto-check.yml、lint-*、test-*、publish-*-sdk 等）。

4.2 api/ —— 边缘函数（Serverless，按文件独立打包）

每个文件是一个独立部署的 Vercel Edge Function，禁止跨目录引入 ../server/ 或 ../src/（由 tests/edge-functions.test.mjs 强制）。主要分为三类：

• 领域情报网关（由 proto 生成，经 createDomainGateway 打包）。按领域拆分子目录 */v1/[rpc].ts：
  aviation（航空）、batch（批量）、climate（气候）、conflict（冲突）、consumer-prices（消费价格）、cyber（网络）、displacement（流离失所）、economic（经济）、forecast（预测）、giving（捐赠）、imagery（ imagery）、infrastructure（基础设施）、intelligence（情报）、leads、maritime（海事）、market（市场）、military（军事）、natural（自然灾难）、news（新闻）、positive-events（正向事件）、prediction（预测）、radiation（辐射）、research、resilience（韧性）、sanctions（制裁）、scenario（情景推演）、seismology（地震）、supply-chain（供应链，含 hormuz-tracker.js 霍尔木兹追踪、country-products.ts、multi-sector-cost-shock.ts）、trade-flows 等。
• MCP 子系统（api/mcp/）：手写操作端点 mcp.ts；registry/（工具注册：analysis-tools.ts、cache-tools.ts、company-intel-tools.ts、nlp-tools.ts、rpc-tools.ts、index.ts）；ui/（MCP 可渲染的迷你应用：chokepoint-monitor-app.ts、conflict-events-app.ts、country-brief-app.ts、country-risk-app.ts、forecasts-app.ts、market-radar-app.ts、natural-disasters-app.ts、news-intelligence-app.ts、prediction-markets-app.ts、world-brief-app.ts、shell.ts、registry.ts）；auth.ts / billing-denial.ts / quota.ts / dispatch.ts / downstream.ts / filters.ts / freshness.ts / handler.ts / jmespath.ts / prompts/ / resources/ / rpc.ts / telemetry.ts / types.ts / usage.ts 等。对应 README 提到的 get_signal_convergence、get_focal_points、get_alert_digest 等 MCP 工具。
• 操作型端点（手写）：auth/oauth（授权服务器、受保护资源、Clerk 会话）、_api-key.js（API Key 校验，含 _user-api-key.js、_enterprise）、bootstrap.js + _bootstrap-*.js（引导水合与 tier key 发布）、health.js（健康/新鲜度）、mcp-proxy.ts、chat-analyst.ts、ask.ts、create-checkout.ts / customer-portal.ts（Dodo Payments 计费）、notify.ts / notification-channels.ts（通知投递）、security/report.js（安全报告）、rss-proxy.js（RSS 代理）、oref-alerts.js（以色列警报）、opensky.js（航空）、polymarket.js（预测市场）、gpsjam.js、reverse-geocode.js、symbol-search.ts、download.js（桌面下载）、docs-mcp.ts、skills/fetch-agentskills.ts 等。
• 共享内部模块（api/_*.js / api/_*.ts）：_cors.js、_crypto.js、_session.js、_rate-limit.js、_client-ip.js、_json-response.js、_sentry-*.js（Sentry 错误监控）、_idempotency.js、_seed-envelope.js、_upstash-json.js、_content-freshness.js、_product-catalog.generated.js 等，带大量 *.test.mjs 单测。

4.3 server/ —— 服务端核心（被 esbuild 打进 Edge Functions）

文件/目录	作用
gateway.ts	统一网关工厂 createDomainGateway(routes)，实现 19 步请求管道（源站检查→CORS→OPTIONS→内部 MCP HMAC→会话→API Key→权益→路由→POST→GET 兼容→幂等→限速→LLM 配额→执行→响应头/缓存/ETag）。
router.ts	路由匹配器 createRouter(routes)，支持方法分发与降级。
worldmonitor/	各领域处理程序（domain handlers），被网关调用执行业务逻辑。

gateway.ts 管道关键函数（来自源码）：
stripClientUserIdHeader（去除客户端伪造的受信头）→ isDisallowedOrigin（403）→ getCorsHeaders（fail-closed 500）→ OPTIONS 返回 204 → 内部 MCP HMAC 预检（verifyInternalMcpRequest / claimInternalMcpReplayNonce / checkProMcpAccess）→ resolveClerkSession → validateApiKey（区分企业/用户/会话键，validateUserApiKey 走 Convex 后备）→ 权益门（checkEntitlementDetailed，#4611 活跃订阅门）→ router.match + POST→GET 兼容（POST_TO_GET_MAX_ARRAY_VALUES_PER_KEY=200）→ getRequiredBboxDiagnostic（军事 RPC 必填 bbox）→ peekIdempotency/beginIdempotency（防重复计费）→ checkEndpointRateLimit/checkRateLimit（#3199 每账户 API 限制，reserveDailyMeter ENFORCE/SHADOW 模式）→ reserveDirectLlmQuota → runWithUsageScope(handler) → 合并头 + drainSuccessStatusOverride → GET 200 按 RPC_CACHE_TIER 设 Cache-Control / CDN-Cache-Control / ETag。

4.4 shared/ —— 共享核心

跨 src/、server/、api/ 复用的领域模型、类型、常量与工具（如 CII 评分、关联算法、地理工具、i18n key 等）。与 server/ 一样被 esbuild 打包进 Edge Functions，是前后端一致的"单一事实源"。

4.5 src/ —— 前端 SPA（Vanilla TS + Preact）

• 入口与状态：AppContext 中央可变对象（无外部状态库）；App.init() 八阶段启动（见 3.6）。
• 地图引擎：
  • DeckGLMap：deck.gl + maplibre-gl，WebGL 渲染；支持 Scatterplot / GeoJson / Path / Icon / Polygon / Arc / Heatmap / H3Hexagon 图层；PMTiles 自托管底图；Supercluster 聚合。
  • GlobeMap：globe.gl 3D 地球；单一 htmlElementsData 数组 + _kind 判别；大气着色器、空闲自转。
  • src/config/map-layer-definitions.ts：56 种图层定义（渲染器支持、高级状态、变体过滤）。
• 面板系统：108 个面板类（Panels），按领域挂载到布局（layout），配置持久化。
• Workers：见 4.6。
• 矢量库：vector-db.ts（IndexedDB）。

4.6 workers/ —— Web Workers（ML 与分析）

文件	作用
ml.worker.ts	ONNX 推理：嵌入（MiniLM-L6）、情感、摘要、NER；标题记忆向量库。
analysis.worker.ts	新闻聚类（Jaccard 相似度）、跨域关联检测（signal convergence / focal points）。
vector-db.ts（若置于此）	语义搜索向量库。

4.7 proto/ —— 协议契约

• 295 个 .proto 文件、36 个 service，使用 sebuf + Protobuf + HTTP 注解。
• 由 buf 生成 src/generated/（客户端 RPC 桩）与 docs/api/（OpenAPI），CI 通过 proto-check.yml 强制生成代码新鲜度。
• OpenAPI 注入脚本（gen:openapi:*）补充安全、示例、必填、服务器、webhook、幂等、限流错误、异步任务、中国决策信号等。

4.8 src-tauri/ —— 桌面端（Tauri 2）

• Rust 壳 + Node.js Sidecar；Sidecar 在运行时动态加载 api/ 模块，使桌面端复用同一套边缘函数逻辑。
• 含 sidecar/local-api-server.test.mjs、open-url-safety.test.mjs 等安全测试（应对披露过的 IPC / 信任边界问题）。

4.9 cli/ —— 官方 CLI 包

• 源码对应 npm 包 worldmonitor（别名 wm）；npx worldmonitor tools 免 key 列出全部 MCP 工具，worldmonitor risk IR --api-key wm_xxx 等子命令。

4.10 sdk/ —— 多语言 SDK

• sdk/python/ → PyPI worldmonitor-sdk（零依赖）。
• sdk/ruby/ → RubyGems worldmonitor。
• sdk/go/ → github.com/koala73/worldmonitor/sdk/go。
• 三者镜像 CLI 能力，发布由 publish-python.yml / publish-ruby.yml / publish-go.yml 工作流完成。

4.11 convex/ —— 计费与用户态

• Convex Cloud 部署：计费（Dodo Payments）、权益（Entitlement）、用户态、历史情报向量库。typecheck:api 含 audit-convex-string-calls 审计。

4.12 scripts/ —— 构建 / 种子 / 校验脚本

• 种子：seed-*.mjs（抓取→转换→atomicPublish() 写 Redis）。
• 中继：ais-relay.cjs（AIS WebSocket 代理 + RSS 代理 + 种子循环）。
• 构建：build-sidecar-sebuf.mjs、build-sidecar-handlers.mjs、build-openapi-*.mjs、build-agent-skills-index.mjs、build-sitemap.mjs、build-crawlable-corpus.mjs。
• 校验/门禁：lint-boundaries.mjs、enforce-sebuf-api-contract.mjs、enforce-safe-html.mjs、enforce-rate-limit-policies.mjs、sync-locale-keys.mjs、check-unicode-safety.mjs、docs-stats.mjs（派生文档计数并 --check 强制同步）、source-attribution.mjs、validate-rss-feeds.mjs、desktop-package.mjs 等。

4.13 其余目录

• consumer-prices-core/：Consumer Prices 的 Playwright 爬虫核心（按国家篮子抓取）。
• data/：静态数据（如 city-coords 城市坐标）。
• deploy/：nginx 反代、部署辅助。
• docker/：Docker 构建素材。
• docs/：Mintlify 文档源（docs/architecture.mdx、docs/license.mdx、docs/data-sources 等）。
• e2e/：Playwright e2e 用例（变体冒烟、MCP 授权、新闻请求预算、视觉黄金截图等）。
• tests/：Node 单测（*.test.mjs / *.test.mts）+ 韧性校验 schema / 回测。
• public/：静态资源（含博客、openapi.yaml、地图底图、图标）。
• blog-site/：博客子项目（postinstall 自动 npm ci 构建并拷入 public/blog）。
• pro-test/：Pro 层级测试子项目（build:pro 自动 npm ci 构建）。

---

5. 项目的优势、不足、创新点和亮点

5.1 优势（Strengths）

1. 极致的信息聚合广度：530+ 上游主机、500+ 精选源、9 大领域、31 国 CII、29 个交易所——单屏态势感知能力罕见。
2. 真正的"人类 + AI 双消费"设计：浏览器面板、MCP 服务器、REST API、CLI、多语言 SDK、agent 发现文件一应俱全，是"代理优先（agent-first）"的典范。
3. 隐私与离线友好：AI 合成完全在浏览器 ONNX Worker 内完成，可配合 Ollama 零 Key 离线运行，服务端不持有用户分析。
4. 工程纪律强：30+ CI 工作流、边界检查（禁止跨层引入）、限流/权益/幂等/ETag/安全 HTML 等多重门禁，文档计数由 docs-stats --check 强制与代码同步。
5. 统一代码库多形态交付：6 个站点变体 + 4 平台桌面二进制 + 多语言 SDK，全部源自一套代码，维护成本低。
6. 双地图引擎 + 56 图层：deck.gl 平面与 globe.gl 3D 地球可切换，满足不同态势表达需求。

5.2 不足 / 风险（Weaknesses / Risks）

1. 复杂度极高、学习曲线陡：单一仓库横跨前端、边缘函数、Convex、Redis、Railway、Cloudflare、Tauri、proto 生成，新人上手与本地全量复现成本高。
2. 强依赖外部数据生态：大量高级能力（航空、警报、预测市场、消费价格）需要第三方凭据；无凭据时功能降级。
3. AGPL-3.0 许可约束：虽允许商用，但 SaaS / 专有闭源使用需履行 copyleft 与源码可得性义务，品牌权另需商业授权——对企业用户是摩擦点。
4. 边缘函数边界严格：api/ 禁止跨目录引入 ../server/、../src/，虽利于隔离，但也带来一定代码重复与生成代码依赖。
5. 历史负担与规模：5,000+ 提交、巨型 api/ 目录（数十个领域子目录），可维护性与 PR 审查压力随规模增长。
6. 本地 AI 性能依赖客户端算力：ONNX 推理在低端设备可能卡顿；重型 RPC 仍需配额与后端。

5.3 创新点与亮点（Innovation / Highlights）

1. sebuf + Protobuf 契约驱动：295 proto / 36 service 经 buf 同时生成客户端桩与 OpenAPI，契约即文档，CI 强制新鲜度——把"API 契约"做成工程一等公民，是大型 SPA+边缘函数的先进实践。
2. "引导水合"双层并发加载：fast(3s)/slow(5s) 独立 abort + getHydratedData(key) 按需消费，兼顾首屏速度与数据完整，是边缘缓存 SPA 的精致模式。
3. 网关 19 步管道的安全纵深：源站 403、CORS fail-closed、内部 MCP HMAC + 重放 nonce、权益门、幂等防重复计费、每账户 reserveDailyMeter（ENFORCE/SHADOW）、ETag/304——把计费与安全的每一道闸门都显式建模。
4. 浏览器端 AI 合成 + 向量库：用 Transformers.js + ONNX 在 Worker 内做嵌入/摘要/聚类/跨域关联，配合 IndexedDB 向量库实现"端侧情报分析"，无需服务端 LLM。
5. MCP 即产品：把全部情报能力暴露为 MCP 工具并配 ui/ 迷你应用（冲突、国家风险、市场雷达、预测市场等），让 LLM 代理能直接"打开"可视化面板——情报平台的范式升级。
6. CII v8 服务端权威压力评分与跨流信号汇聚（signal convergence / focal points / escalation），将定性地缘风险量化为可排序、可检索的指标。
7. Tauri 桌面端动态加载 api/ 模块：复用同一套边缘函数逻辑于本地 sidecar，避免桌面与云端两套实现。