智能星球计划 - 面向数据博弈的"智能软关基"态势感知系统

项目概述

核心愿景： 构建人类智能空间的"实时全景图"

在智能时代，人类认识宇宙的方式本身发生了变化。我们不再只生活在一个由物理空间、自然资源和地理边界所构成的现实层宇宙之中。我们同时生活在一个由信息流、传播结构与智能系统共同塑造的认知层宇宙里。这两个层级的宇宙相互叠加、持续耦合，通过智能系统不断重构人类对存在、秩序与意义的理解。

系统架构

当前仓库的核心形态是“Web Earth 可视化 + React 运维台 + FastAPI 数据与 AI 编排后端 + 独立模型适配层”。物理大屏与 UE 客户端仍是长期方向，但不再作为本地开发和当前发布的必需运行单元。

┌─────────────────────────────────────────────────────────────────────┐
│                         浏览器展示与运维层                            │
│  ┌──────────────────────────────┐  ┌──────────────────────────────┐ │
│  │ Web Earth                    │  │ React 运维台                  │ │
│  │ frontend/public/earth        │  │ frontend/src                  │ │
│  │ Three.js 地球 / HUD / 新闻    │  │ 数据源 / 告警 / AI 设置       │ │
│  │ 国界精度 / 品牌内容配置       │  │ 提示词配置 / 用户与系统配置   │ │
│  └──────────────────────────────┘  └──────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
                       │ REST / WebSocket
                       ▼
┌─────────────────────────────────────────────────────────────────────┐
│                       FastAPI 业务与编排后端                          │
│  ┌────────────────────┐ ┌────────────────────┐ ┌─────────────────┐ │
│  │ 数据 API 与认证     │ │ Earth 新闻增强      │ │ 告警与态势简报   │ │
│  │ JWT / 权限 / 审计   │ │ 位置推断 / 本地化   │ │ BGP / 告警研判   │ │
│  └────────────────────┘ └────────────────────┘ └─────────────────┘ │
│  ┌────────────────────┐ ┌────────────────────┐ ┌─────────────────┐ │
│  │ 系统运行配置        │ │ 默认提示词注册表     │ │ 未来 Agent Runtime│ │
│  │ system_settings     │ │ 代码发布 + DB 覆盖  │ │ 工具/证据/工作流   │ │
│  └────────────────────┘ └────────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
        │ SQLAlchemy / Redis Stream            │ 纯净 LLM 调用
        ▼                                      ▼
┌──────────────────────────────┐      ┌──────────────────────────────┐
│ PostgreSQL / Redis            │      │ aiprovider                   │
│ 用户、配置、采集结果、新闻     │      │ provider + protocol adapter  │
│ Stream、缓存、运行状态         │      │ OpenAI / MiniMax / Ollama 等 │
└──────────────────────────────┘      └──────────────────────────────┘
        ▲
        │ 采集器 / 外部数据源
        ▼
┌─────────────────────────────────────────────────────────────────────┐
│ RSS 新闻、BGP 观测、公开数据源、后续 WebSearch/OCR/语音识别等工具      │
└─────────────────────────────────────────────────────────────────────┘

架构边界:

• backend 负责业务语义、证据收集、提示词选择、AI 任务编排、权限和数据落库。
• aiprovider 只负责把纯净模型请求适配到不同供应商或协议，不内置具体业务提示词。
• 默认提示词随代码发布并保存在 backend/app/ai_tasks/default_prompts.json，运维台可在数据库中保存覆盖值，重置时回到当前代码版本的默认提示词。
• Earth 新闻保留英文原文，中文展示结果存入 localizations，前端默认展示 zh-CN 的 display_title、display_summary 和中文地域/状态文案。
• Earth LLM 指令、语音识别、多角色态势研判属于后续 Agent Runtime 方向，计划见 docs/plans/agents-earth-command-runtime-plan.md。

四大核心要素

层级	要素	描述
L1	新兴技术支撑	AI算力、模型生态、云基础设施
L2	关键基础设施	卫星、海底光缆、IXP、路由
L3	组织制度资源	规则制定权、顶层设计
L4	文化内容供给	新闻、社交视频、舆论情绪

技术栈

后端 (Python FastAPI)

组件	版本	用途
FastAPI	0.109+	Web 框架
SQLAlchemy	2.0+	ORM
uv	-	Python 依赖与命令运行
Redis	7.0+	缓存、Stream 与运行协调
PyJWT	-	认证
APScheduler / 后台任务	-	采集、增强与运行时任务

前端 (React Admin)

组件	用途
React 18	UI 框架
Ant Design Pro	管理后台组件
Axios	HTTP 客户端
Socket.io-client	WebSocket 客户端
ECharts	统计图表
Three.js	Earth 3D 地球渲染
Bun	前端包管理与脚本运行

前端工程统一使用 Bun：

• 安装依赖使用 bun install
• 运行脚本使用 bun run <script>
• 不使用 npm、pnpm、yarn

大屏与 3D 展示方向

当前发布优先使用浏览器 Web Earth。UE5 / Cesium for Unreal / Niagara 可作为后续物理大屏方向接入，但不是本地开发闭环的必需组件。

数据库

组件	用途
PostgreSQL 15+	关系数据
Redis 7+	缓存、Stream、运行状态

部署

组件	用途
Docker 24+	容器化
Docker Compose	本地部署
Nginx	反向代理

角色权限

角色	权限范围
超级管理员	全部权限
管理员	除用户管理外的全部
操作员	查看 + 操作
只读用户	仅查看大屏和报表

数据采集策略

优先级	数据源	采集频率
P0	TOP500	每 4 小时
P0	Epoch AI	每小时
P0	Hugging Face	每 2 小时
P0	GitHub	每 4 小时
P0	海底光缆 / IXP / 卫星等基础设施数据	每日或按源刷新
P0	PeeringDB	每 2 小时
P1	Cloudflare Radar / TeleGeography	每小时
P1	CAIDA BGPStream	每 15 分钟

项目结构

├── backend/               # FastAPI 后端
│   ├── app/
│   │   ├── api/          # API 路由
│   │   ├── core/         # 核心配置
│   │   ├── models/       # 数据模型
│   │   ├── schemas/      # Pydantic 模型
│   │   ├── services/     # 业务逻辑与 AI 任务编排
│   │   └── ai_tasks/     # 默认提示词与 AI 任务定义
│   └── tests/
├── aiprovider/            # 独立模型供应商适配层
├── frontend/              # React 管理后台
│   ├── src/
│   │   ├── components/   # 组件
│   │   ├── pages/        # 页面
│   │   ├── services/     # API 服务
│   │   └── store/        # 状态管理
│   ├── public/earth/      # Web Earth 静态应用
│   └── tests/             # 前端测试
├── data/                  # 数据文件
├── docs/                  # 文档
├── scripts/               # 脚本
├── docker-compose.yml
├── AGENTS.md
└── README.md

快速启动

# 新机器或空项目首次初始化
./planet.sh init
# 会自动安装/检查 uv、bun，同步 Python/前端依赖
# 会在缺少时生成 backend/.env、aiprovider/.env、frontend/.env.local
# 会启动 PostgreSQL/Redis，并创建表、默认数据源和本地默认用户

# 启动前后端服务
./planet.sh start

# 仅重启后端
./planet.sh restart -b

# 仅重启前端
./planet.sh restart -f

# 交互创建用户
./planet.sh createuser

# 查看服务状态
./planet.sh health

# 删除容器、卷、镜像和本地编译状态，执行前需要输入 Y 确认
./planet.sh destroy

前端命令约定：

cd frontend
bun install
bun run dev
bun run build

不要使用 npm run ...，避免在 WSL/Windows 混合环境里触发 cmd.exe 路径兼容问题。

API 文档

启动服务后访问: http://localhost:8000/docs

WSL / Windows 局域网访问

如果服务运行在 WSL 中，而你希望：

• Windows 本机浏览器访问开发服务
• 同一局域网内的手机或其他电脑访问开发服务

推荐按下面顺序排查和配置。

端口占用、iphlpsvc / portproxy、摄像头和依赖问题的集中排障入口见 常见问题。

1. 在 WSL 中启动服务

./planet.sh start --allow-lan

这会让前端监听 0.0.0.0:3000，后端监听 0.0.0.0:8000，AI Provider 通过 Docker 发布到 0.0.0.0:8010。启动前脚本会检查这三个端口；如果 WSL/Linux 侧无法释放端口，并检测到 Windows 侧 listener 或旧 portproxy，会请求管理员 PowerShell 清理。

2. 先确认 WSL 内部服务正常

在 WSL 中执行：

curl http://localhost:3000
curl http://localhost:8000/health
curl http://localhost:8010/health
ss -ltnp | grep -E ':3000|:8000|:8010'

预期：

• 3000 返回前端 HTML
• 8000/health 返回健康检查 JSON
• 8010/health 返回 AI Provider 健康检查 JSON
• ss 中能看到 0.0.0.0:3000、0.0.0.0:8000 和 0.0.0.0:8010，或 Docker 已发布 8010

如果这一步不通，先不要继续做 Windows 转发。

3. 在 Windows 本机验证 localhost 直通

在 Windows PowerShell 中执行：

curl http://localhost:3000
curl http://localhost:8000/health
curl http://localhost:8010/health

在常见的 WSL2 开发环境下，Windows 通常可以直接通过 localhost 访问 WSL 中的服务。

4. 如果需要让局域网设备访问，清理端口和防火墙

./planet.sh start --allow-lan 不再启动额外的 Windows 端口转发进程。它直接让开发服务对 3000 / 8000 / 8010 开放，并在启动前尝试释放这些端口。端口被 Windows 侧 listener 或旧 portproxy 占用时，脚本会请求一次管理员 PowerShell 清理。

如果以前手动配置过持久 portproxy，若自动请求被取消，可以手动清理，避免 iphlpsvc 继续占用端口：

netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=3000
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8000
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8010

脚本会检测 Windows 防火墙是否已放行 3000 / 8000 / 8010。如果缺少规则，会触发一次 Windows UAC 管理员 PowerShell 请求来自动创建。若自动请求被取消，也可以手动执行：

New-NetFirewallRule -DisplayName "WSL Planet 3000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 3000
New-NetFirewallRule -DisplayName "WSL Planet 8000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8000
New-NetFirewallRule -DisplayName "WSL Planet 8010" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8010

5. 查 Windows 局域网 IP，并让其他设备访问

在 Windows PowerShell 中执行：

ipconfig

找到当前联网网卡的 IPv4 地址，例如 192.168.8.228。

局域网其他设备可访问：

• http://<Windows局域网IP>:3000/earth
• http://<Windows局域网IP>:3000/admin
• http://<Windows局域网IP>:8000/health
• http://<Windows局域网IP>:8010/health

例如：

• http://192.168.8.228:3000/earth

6. 常见现象与判断

• WSL 中 curl localhost:3000 能通，但 Windows 访问 WSL 的局域网 IP:3000 不通：这是正常现象之一，优先验证 Windows 的 localhost:3000
• Windows localhost:3000 能通，但局域网设备访问 Windows 局域网 IP:3000 不通：通常是 Windows 防火墙、网络配置或旧 portproxy 残留
• whoami /groups 中 S-1-5-32-544 显示 deny only：说明当前 PowerShell 不是提权管理员窗口

7. 本项目一次性验证顺序

建议固定按这个顺序验证：

1. WSL 中执行 curl http://localhost:3000
2. WSL 中执行 curl http://localhost:8000/health
3. WSL 中执行 curl http://localhost:8010/health
4. Windows 中执行 curl http://localhost:3000
5. Windows 中执行 curl http://localhost:8000/health
6. Windows 中执行 curl http://localhost:8010/health
7. 按脚本提示完成 Windows 防火墙或端口清理 UAC 请求
8. 用手机或其他电脑访问 Windows 对外端口，例如 http://<Windows局域网IP>:3000/earth

启动容错参数

planet.sh 现在为依赖安装、数据库、AI Provider 启动加入了有限次重试，并会在数据库与 aiprovider 启动后额外等待 Docker healthcheck。

可通过环境变量临时调整:

# 例: 放宽 AI Provider 与数据库在网络抖动下的自愈次数
AI_PROVIDER_START_MAX_RETRIES=5 \
AI_PROVIDER_RETRY_INTERVAL=10 \
DATABASE_START_MAX_RETRIES=5 \
DATABASE_RETRY_INTERVAL=10 \
./planet.sh restart

常用参数:

• DEPENDENCY_INSTALL_MAX_RETRIES / DEPENDENCY_INSTALL_RETRY_INTERVAL: 控制 uv sync、bun install 的重试次数与间隔，默认 3 次、5 秒
• DATABASE_START_MAX_RETRIES / DATABASE_RETRY_INTERVAL: 控制 postgres、redis 的启动/重启与健康检查自愈，默认 3 次、5 秒
• AI_PROVIDER_START_MAX_RETRIES / AI_PROVIDER_RETRY_INTERVAL: 控制 aiprovider 的构建/启动与容器重启自愈，默认 3 次、5 秒
• BACKEND_MAX_RETRIES: 控制后端进程启动重试次数，默认 3
• FRONTEND_MAX_RETRIES: 控制前端 dev server 启动重试次数，默认 3
• BACKEND_HEALTH_CHECK_ATTEMPTS / BACKEND_HEALTH_CHECK_INTERVAL: 控制后端 HTTP 健康检查等待次数与间隔，默认 60 次、2 秒
• FRONTEND_HEALTH_CHECK_ATTEMPTS / FRONTEND_HEALTH_CHECK_INTERVAL: 控制前端 HTTP 可访问检查等待次数与间隔，默认 10 次、2 秒
• AI_PROVIDER_HEALTH_CHECK_ATTEMPTS / AI_PROVIDER_HEALTH_CHECK_INTERVAL: 控制 aiprovider HTTP 健康检查等待次数与间隔，默认 10 次、2 秒

AI 与智能体接口

项目现在采用“三段式”边界:

• backend: 暴露业务接口，负责选择任务提示词、组织证据、调用工具、保存 AI 设置和结果。
• aiprovider: 暴露模型网关接口，只负责 provider / protocol 适配，不写入 BGP、新闻、告警等业务提示词。
• 模型供应商: OpenAI 兼容、MiniMax、Anthropic、Ollama 或其他兼容网关。

这样前端和业务代码不直接依赖某个模型供应商，后续增加 Agent Runtime、Earth 一键 LLM 指令、语音识别或多角色态势研判时，也可以把业务工作流放在后端，而不是污染模型适配层。

当前已落地的 AI 配置能力:

• 运维台 AI 设置可维护 provider、模型、协议、超时、token 等运行配置。
• 运维台 AI 设置中的“提示词”页可选择不同功能入口，手动覆盖提示词，并一键重置到默认值。
• 默认提示词随代码发布，位于 backend/app/ai_tasks/default_prompts.json。
• 覆盖值保存在数据库运行配置中，升级代码后可继续保留现场配置，也可重置到新版本默认提示词。
• 态势摘要、告警研判、新闻本地化等入口应使用各自任务提示词；调用 aiprovider 时只传递当前任务所需的 prompt / system_prompt。

主后端建议配置:

AI_PROVIDER_SERVICE_URL=http://localhost:8010
AI_PROVIDER_SERVICE_TOKEN=change_me
AI_PROVIDER_TIMEOUT_SECONDS=60

aiprovider 服务建议配置:

AI_PROVIDER=minimax
AI_PROVIDER_API=anthropic-messages
AI_BASE_URL=https://api.minimaxi.com/anthropic
AI_API_KEY=your_api_key
AI_MODEL=MiniMax-M2.7
AI_TIMEOUT_SECONDS=60
AI_PROVIDER_SERVICE_TOKEN=change_me

推荐映射关系:

• vLLM / LM Studio / One API: AI_PROVIDER=openai + AI_PROVIDER_API=openai-completions
• MiniMax: AI_PROVIDER=minimax + AI_PROVIDER_API=anthropic-messages
• Claude 兼容网关: AI_PROVIDER=anthropic + AI_PROVIDER_API=anthropic-messages
• Ollama: AI_PROVIDER=ollama + AI_PROVIDER_API=ollama-generate

比如 MiniMax 可以这样配置:

AI_PROVIDER=minimax
AI_PROVIDER_API=anthropic-messages
AI_BASE_URL=https://api.minimaxi.com/anthropic
AI_API_KEY=your_api_key
AI_MODEL=MiniMax-M2.7
AI_TIMEOUT_SECONDS=60
AI_MAX_TOKENS=1200
AI_ANTHROPIC_VERSION=2023-06-01

如果你要本地直接起模型适配层，项目里已经补了模板:

• aiprovider/.env.example
• docker-compose.local-model.yml

运行与调用补充:

• ./planet.sh start 默认会启动 aiprovider
• 其他服务优先调用主后端 POST /api/v1/ai/situational-awareness/analyze
• backend -> aiprovider 会透传 X-Request-ID
• backend -> aiprovider 与 aiprovider -> 模型供应商 都带轻量重试

详细文档:

• docs/technical/zh/agents-aiprovider.md
• docs/technical/en/agents-aiprovider.md
• aiprovider/README.md
• docs/technical/frontend-layout-guidelines.md
• docs/plans/frontend-ai-playground-development-plan.md
• docs/plans/agents-situational-awareness-foundation-plan.md
• docs/plans/agents-earth-command-runtime-plan.md

前端页面布局规范

管理后台页面默认遵循“单屏工作区”原则：

• 页头、摘要区、主工作区应在一屏内形成稳定结构
• 主表格 / 主图表 / 主分析区应占据页面主要可视空间
• 模块内容超出时优先在卡片、表格、标签页内部滚动
• 不依赖整页纵向撑开来容纳主要工作区

当前推荐参考实现：

• frontend/src/pages/BGP/BGP.tsx
• docs/technical/frontend-layout-guidelines.md

License

待定