SpaceEngine 0.99x详细信息生成器(含AI能力)
基于 C++26 与 Python 混编的 SpaceEngine 详细信息生成器,可向下兼容0.980。
从SpaceEngine导出的行星系统文件(.sc)解析行星系统结构并生成详细信息文档。
目录
产品介绍
DetailedInfoGen(简称 InfoGen)将C++侧的ANTLR解析与天文计算功能(使用pybind11编译成Python模块InfoGen)与Python侧的命令行、国际化及文档渲染能力相结合,用于从SpaceEngine导出的行星系统文件中提取天体数据并输出结构化文档。
当前已完成的功能
- 从SpaceEngine导出的文件生成行星系统基本信息
- 解析行星系统文件(使用ANTLR)
- 重建行星系统层级:自动定位系统根节点(质心),并按广度优先遍历重建父/子系统树
- 汇总系统级信息:恒星/行星/矮行星/卫星/小行星/彗星数量、恒星光谱型
- 输出单天体信息:轨道数据(轨道根数、双星轨道)、物理数据(半径、质量、密度、温度、光度等)、大气、海洋、生物圈
- 生成小行星/彗星列表,支持按半径、质量、自转、逆行、高倾角等条件筛选与排序
- 中文友好的分类命名(恒星光谱型、行星类型分级)
- 输出结果为Markdown或用户自定义Jinja2模板格式
- (可选)把读取的行星系统保存到数据库,支持的数据库详见配置文件
- 根据数据库中保存的物体数据,AI生成各种二创数据(如文明,矿产等)
- 基于LangGraph构建多轮工具调用工作流,模型可自动查询数据库中保存的系统/物体信息后再生成内容
- 支持全局提示词与用户提示词(含变量占位符)、最大工具调用次数限制与流式输出,结果写入Markdown文件
- 通过MCP服务的形式把内部工具暴露给第三方AI客户端
- 可选择性把全局提示词通过MCP的
instructions字段下发给客户端(并非所有客户端都会读取该字段) - 支持stdio与HTTP两种传输方式,HTTP模式下可选择监听IPv6地址
- 可选择性把全局提示词通过MCP的
- 随仓库提供可直接导入的第三方客户端Agent插件(DSH、ZCode、WorkBuddy)
- 把MCP查询工具、全局提示词与只读约束打包成一个开箱即用的专家/Agent,免去逐个客户端手写配置
- 插件默认连接
http://localhost:8000/mcp,服务未启动时自动重试并静默提醒,不影响客户端其他功能
技术栈
| 层次 | 技术 |
|---|---|
| 构建 | CMake 4.0+ |
| 核心 | C++26(<flat_map> / <flat_set> / ranges / concepts / jthread 等) |
| 绑定 | pybind11(C++代码编译为Python模块InfoGen) |
| 解析 | ANTLR4(解析SpaceEngine文件语法) |
| 数值 | Eigen(定长/动态向量与矩阵) |
| 日志 | spdlog(复用外部 fmtlib,避免重复符号) |
| 格式化/转换 | fmtlib、fast-float、google-double-conversion |
| 脚本 | Python 3.12+,argparse / gettext / polib / pandas |
| 数据库 | Apache ADBC + DBUtils + SQLAlchemy |
| AI | Langgraph |
| 服务 | FastMCP |
安装部署
环境要求
| 项目 | 要求 | 说明 |
|---|---|---|
| 操作系统 | Windows / Linux | 仓库仅提供这两个平台的依赖清单 |
| CMake | 4.0以上 | 构建脚本声明 cmake_minimum_required(VERSION 4.0) |
| C++编译器 | 支持 C++26(推荐 GCC-16.1) | 需 <flat_map> / <flat_set> / <ranges> / std::jthread 等特性 |
| Python | 3.12以上 | 需Development.Module组件(Python头文件与库) |
| ANTLR4 C++ Runtime | v4 | 唯一需要手动准备的依赖 |
依赖说明
以下依赖已内置于InfoGen_Data/3rdParty,配置阶段由CMake按目录名排序后自动add_subdirectory引入,无需手动安装,下载源码后记得git submodule update一下:
| 依赖 | 用途 |
|---|---|
| fmtlib | 字符串格式化(fmt::format) |
| spdlog | 日志输出(配置为复用外部 fmtlib,避免fmt::v12符号重复定义) |
| pybind11 | 将C++代码编译为可直接import的Python模块 |
| Eigen | 向量/矩阵类型(SEVec2 / SEVec3 / SEArray等) |
| fast-float | 快速浮点解析 |
| google-double-conversion | 浮点数与字符串互转 |
| antlr | ANTLR接入脚本,本身不含运行时,通过find_package定位系统安装的ANTLR C++ Runtime |
注:唯一无法自动处理的依赖是ANTLR,必须手动下载安装(见第1步)。由于ANTLR生成的词法器/语法器源码已自带,因此无需安装Java或ANTLR工具本身,只需C++运行时库。
安装步骤
注:由于这一版本功能比以前的版本强大的多,因此安装部署的难度也提高了某些白嫖党难以接受的程度
先修课程:C++程序设计,Python程序设计,数据库原理与应用,人工智能基础,天体物理学
1. 编译并安装 ANTLR C++ Runtime
从 https://www.antlr.org/download.html 下载 antlr4-cpp-runtime-4.x.x-source.zip 并解压。
cd antlr4-cpp-runtime-4.x.x-source
cmake -S . -B build \
-DANTLR4_INSTALL=ON \
-DCMAKE_POLICY_VERSION_MINIMUM=3.5 \
-DCMAKE_INSTALL_PREFIX=<ANTLR4安装目录>
cmake --build build --parallel
cmake --install build
两个关键选项:
-DANTLR4_INSTALL=ON:让ANTLR生成并安装antlr4-runtime-config.cmake配置包,供find_package(antlr4-runtime CONFIG)定位。不开启则本项目无法找到ANTLR。-DCMAKE_POLICY_VERSION_MINIMUM=3.5:ANTLR的cmake_minimum_required版本较旧,CMake 4.x已不兼容低于3.5的策略版本,必须显式指定。
安装后确认存在lib/cmake/antlr4-runtime/antlr4-runtime-config.cmake,该目录即为后续ANTLR4_ROOT的取值依据。
2. 配置项目
cmake -S <源码目录> -B <构建目录> \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=<安装前缀> \
-DANTLR4_ROOT=<ANTLR4安装目录> \
-DPython3_EXECUTABLE=/path/to/python
可用的 CMake 变量:
| 变量 | 说明 |
|---|---|
-DANTLR4_ROOT=<dir> |
ANTLR安装根目录(需含 lib/cmake/antlr4-runtime或lib/cmake/antlr4),推荐写法 |
-DANTLR_SEARCH_DIRS=<dir1>;<dir2> |
额外的ANTLR搜索目录,分号分隔,可填多个 |
-DCMAKE_PREFIX_PATH=<dir> |
CMake 标准前缀路径,与前两者等价,三者可任选 |
-DPython3_EXECUTABLE=<python> |
指定Python解释器,用于解析Development.Module组件 |
-DCMAKE_INSTALL_PREFIX=<dir> |
安装前缀,必填 |
如果终端输出[InfoGen/antlr] 已就绪,导入目标: antlr4::runtime,以及发现头文件 N 个,源文件 N 个、收集到可链接依赖目标 N 个说明配置成功。若出现[InfoGen/antlr] 未找到 ANTLR C++ 运行时错误,说明ANTLR路径未正确传入。
3. 编译并安装
cmake --build <构建目录> --parallel
cmake --install <构建目录>
安装后,CMAKE_INSTALL_PREFIX 下会得到与源码一致的目录结构:
<安装前缀>/
├── InfoGen.py # 命令行入口
└── InfoGen_Data/
├── InfoGen.(so|pyd) # C++编译的Python模块
├── Plug-ins/ # 第三方客户端Agent插件(DSH / ZCode / WorkBuddy)
......
└── requirements-linux.txt / requirements-win.txt
4. 复制运行时动态库
C++模块在Linux下使用$ORIGIN作为RPATH(构建脚本设置了INSTALL_RPATH "$ORIGIN"),即只会在模块自身所在目录查找依赖库,因此运行时库必须放到<安装前缀>/InfoGen_Data/下:
- ANTLR:将ANTLR的DLL复制到
<安装前缀>/InfoGen_Data/。 - GCC 运行时(仅当使用 GCC 编译,且其运行时库不在系统搜索路径时):
- Windows:将
libstdc++-6.dll、libgcc_s_seh-1.dll、libwinpthread-1.dll等复制到<安装前缀>/InfoGen_Data/。 - Linux:
export LD_LIBRARY_PATH=/path/to/gcc/lib64:$LD_LIBRARY_PATH
- Windows:将
5. 安装 Python 依赖
python3 -m venv ./venv
source ./venv/bin/activate # Windows: .\venv\Scripts\activate
pip install -r <安装前缀>/InfoGen_Data/requirements-linux.txt # Windows 改用 requirements-win.txt
依赖清单包含argparse之外的中文帮助、国际化(polib)、数据处理(pandas),以及后续AI所需的langchain等组件。
6. 验证安装
cd <安装前缀>
python InfoGen.py --help
若正常输出中文帮助信息(而非报错或乱码),则安装配置完成。
常见问题排查(AI生成,仅供参考!!!)
| 现象 | 原因与处理 |
|---|---|
| 第 1 步配置 ANTLR 时报 CMake 策略/兼容性错误 | 缺少 -DCMAKE_POLICY_VERSION_MINIMUM=3.5 |
第 2 步出现 [InfoGen/antlr] 未找到 ANTLR C++ 运行时 |
未传 -DANTLR4_ROOT / -DANTLR_SEARCH_DIRS / -DCMAKE_PREFIX_PATH,或该路径下没有 lib/cmake/antlr4-runtime |
链接报 relocation R_X86_64_32 ... can not be used when making a shared object |
静态依赖未以 -fPIC 编译;顶层已全局开启 CMAKE_POSITION_INDEPENDENT_CODE,若某依赖自行覆盖该属性需检查其 CMake |
链接报 multiple definition of fmt::v12::... 或 duplicate section |
spdlog 捆绑 fmt 与外部 fmtlib 冲突;构建脚本已强制 SPDLOG_FMT_EXTERNAL_HO=ON,请勿关闭或改为 OFF |
import InfoGen 失败,或提示找不到动态库 |
未执行第 4 步,把 ANTLR / GCC 的运行时库放到 InfoGen_Data/ 下 |
Linux 运行前需每次设置 LD_LIBRARY_PATH |
属于第 4 步 GCC 运行时的正常处理,可写入 shell 配置或启动脚本 |
| 配置时报找不到 Python 开发组件 | 安装 python3-dev(Linux)或在 Windows 安装包中勾选「Python 开发文件」,或用 -DPython3_EXECUTABLE 指定正确的解释器 |
| Windows 控制台中文乱码 | InfoGen_Data/__init__.py 已自动把控制台输出代码页切到 UTF-8(65001),若仍乱码请确认终端字体支持中文 |
| MCP客户端连接成功但查询无结果 | 确认启动时的-n/--namespace与导入数据时使用的命名空间一致,且数据库配置仍有效 |
| MCP客户端读不到全局提示词 | 未加--mcp-global-prompt-instruction(默认不发送instructions),或客户端本身未实现读取instructions;同时确认-C指向的文件存在且为UTF-8编码 |
插件安装后找不到 Agent / 专家 / /infogen |
确认导入的是插件目录本身(DSH 选含package.json、ZCode 选含marketplace.json、WorkBuddy 选含.codebuddy-plugin/的那一层),并已在客户端中启用;旧会话可能需要新建会话后才生效 |
| DSH 的 InfoGen-DSH 预设里没有 MCP 工具 | 确认MCP服务已以HTTP模式启动、-n与导入数据时的命名空间一致;curl http://127.0.0.1:3080/infogen-dsh/status查看探测状态与错误信息 |
使用方法
从SpaceEngine导出的文件生成行星系统基本信息
python InfoGen.py create system -S /SpaceEngine/Export/RS-xxxx.sc [-B /OutputPath]
解析SpaceEngine导出的文件、重建行星系统结构,并将结果写入输出目录下的<系统主天体ID>.md。
create system 参数说明
| 参数 | 说明 | 默认值 |
|---|---|---|
-S, --input |
输入的 SpaceEngine 文件(必填) | — |
-B, --output |
输出目录 | ./Export |
--code-page |
输入文件的编码代码页(用于防止乱码) | 65001 |
--absolute-orbit |
轨道是否为绝对参照系(如黄道、天球);默认相对参照系(如赤道) | 关闭 |
--common-plane-threshold |
10^(-x),当计算的黄道轨道面与上一级物体的黄道轨道面相差小于该值时视为共面(仅 --absolute-orbit=False 生效) |
9 |
--esi-estimator |
地球相似指数算法:SolarSys(半径、密度、逃逸速度、温度)、Extrasolar(恒星辐射通量、行星半径) |
SolarSys |
--sort-system |
对输出内容按半长轴顺序排序 | 关闭 |
--exceptional-asteroids-pred |
小行星列表排序依据(取值见下表) | LargestByDiameter |
--exceptional-asteroids-limit |
小行星列表最大数量 | 50 |
-L, --lcid |
输出文档的语言 ID(如 2052 简体中文、1033 英文)(TODO) |
2052 |
-f, --format |
输出文档格式(当前支持 Markdown) |
Markdown |
-D, --format-args |
输出文档格式的额外参数,可重复传入(key=value,如 -Dprecision=6) |
空 |
--store |
将生成的原始数据保存到数据库 | 关闭 |
--namespace |
保存数据的命名空间 | — |
--exceptional-asteroids-pred 可选值:
| 取值 | 含义 |
|---|---|
LargestByDiameter |
半径降序 |
MostMassive |
质量降序 |
SlowestRotators |
自转周期降序 |
FastestRotators |
自转周期升序 |
Retrograde |
筛选轨道倾角大于90°小于270°的小行星并按倾角升序排序 |
HighlyInclined |
轨道面与黄道面夹角降序 |
命名空间 --namespace 名称限制:
- 字符限制:只能包含小写字母(a-z)、数字(0-9)以及连字符/中划线(-)。
- 首尾限制:必须以字母或数字开头和结尾,不能以连字符(-)开头或结尾。
- 长度限制:最大长度不能超过63个字符。
数据库联动
python InfoGen.py adbc init --driver="/path/to/libadbc_driver_xxxx.dll" --uri="<数据库链接>"
此命令会自动在URL对应的数据库里建立表结构,并在./InfoGen_Data/Config目录下生成一个配置文件,内容就是命令里填的驱动和数据库URL。目标数据库必须是一个空的数据库。
adbc init 参数说明
| 参数 | 说明 | 默认值 |
|---|---|---|
--driver |
ADBC驱动路径(必填) | — |
--uri |
连接目标:文件路径或DSN(必填) | — |
-F, --force |
覆盖已存在的配置 | 关闭 |
获取已经导入的数据
python InfoGen.py get <resource> -A # 获取所有<resource>
python InfoGen.py get <resource> -n<namespace> [<name>] # 获取那个名称或ID对应的<resource>
python InfoGen.py describe <resource> -n<namespace> [<name>] # 输出<resource>的详细信息
get 参数说明
| 参数 | 说明 | 默认值 |
|---|---|---|
-A, --all-namespaces |
获取全部资源 | — |
-n, --namespace |
指定命名空间,没有设置-A的情况下为必填 | — |
-o, --output |
输出格式,目前支持wide,json和yaml | — |
注:get和describe均不支持模糊查询,如果要模糊查询,请使用python InfoGen.py get <resource> [-A | -n<namespace>] | grep ...
AI创作(如生成文明,矿产,宜居度评级等)
python InfoGen.py generate -S <用户提示词> [-B <输出目录>] [-D<Variable>=<Value>...]
generate 参数说明
| 参数 | 说明 | 默认值 |
|---|---|---|
-S, --input |
用户提示词文件 | — |
-B, --output |
输出目录 | ./Export |
-C, --global-prompt |
全局提示词文件 | ./InfoGen_Data/StreamingAssets/Prompts/Global.txt |
-D, --define |
给-S指定的用户提示词里的变量赋值,多个变量重复多次 | — |
-n, --namespace |
命名空间(必填) | — |
--max-tool-calls |
最大调用工具次数 | 10 |
-v, --verbose |
流式输出模型返回的内容 | — |
注:用户提示词中的变量用{}定义,详见模板
服务
service 参数说明
| 参数 | 说明 | 默认值 |
|---|---|---|
service |
服务名称(必填,目前仅支持mcp) |
— |
-n, --namespace |
命名空间(必填) | — |
-D, --define |
服务启动参数,以key=value形式原样透传给FastMCP.run(),可重复传入(如-Dtransport=http、-Dport=8000) |
空 |
-6, --mcp-ipv6 |
使用IPv6链接(仅mcp的HTTP模式生效) |
关闭 |
--mcp-global-prompt-instruction |
把全局提示词文件的内容通过MCP的instructions字段传出 |
关闭 |
-C, --mcp-global-prompt-file |
MCP全局提示词文件(仅--mcp-global-prompt-instruction开启时读取) |
./InfoGen_Data/StreamingAssets/Prompts/Global.txt |
MCP服务
python InfoGen.py service mcp -n<namespace> [-D<key>=<value>...] [-6] [--mcp-global-prompt-instruction [-C<prompt文件>]]
把指定命名空间的数据库查询能力以MCP工具的形式对外提供,供支持MCP的AI客户端(如Claude Desktop等)调用。
部分客户端(如CodeBuddy、Cherry Studio等)会主动读取MCP服务端instructions字段的内容作为全局提示词。由于MCP规范并未强制要求客户端实现该字段,本项目默认不发送,需要时显式加上--mcp-global-prompt-instruction后才会发送全局提示词。
MCP工具清单:
| 工具 | 作用 |
|---|---|
QuerySystem |
查询指定系统的信息 |
QueryAllObjectsInSystem |
查询指定系统内某一类型(质心/恒星/行星/矮行星/卫星/小行星/彗星)的全部物体 |
QueryObject |
查询指定物体的详细信息,可附加系统名与物体类型 |
MCP客户端配置示例:
以stdio传输为例,在客户端配置中把启动命令指向本项目即可:
{
"mcpServers": {
"InfoGen": {
"command": "python",
"args": ["InfoGen.py", "service", "mcp", "-n<namespace>"],
"cwd": "<安装前缀>"
}
}
}
若需要让客户端读取全局提示词,在args中追加--mcp-global-prompt-instruction与-C<提示词文件>:
{
"mcpServers": {
"InfoGen": {
"command": "python",
"args": ["InfoGen.py", "service", "mcp", "-n<namespace>", "--mcp-global-prompt-instruction"],
"cwd": "<安装前缀>"
}
}
}
若改用HTTP传输,可执行python InfoGen.py service mcp -n<namespace> -Dtransport=http,再让客户端以URL方式接入。
接入第三方客户端
除了上一节那种手工填写MCP配置的方式,仓库的InfoGen_Data/Plug-ins下还内置了成品Agent插件,把「MCP服务 + 全局提示词 + 只读工具集 + 数据使用约束」打包成一个开箱即用的Agent:
| 插件 | 目标客户端 | 形态 | 启用方式 | 插件标识 / 版本 |
|---|---|---|---|---|
| InfoGen-DSH | DeepSeek Harness(DSH) | DSH bundle(Host半 + Client半) | 安装后在「Agent预设」中选择InfoGen-DSH |
infogen-dsh / 26.0.0-26H2 |
| InfoGen-ZCode | ZCode | 插件市场包(Agent + 指令) | 安装后在会话中输入/infogen <任务> |
infogen-zcode / 26H2 |
| InfoGen-WorkBuddy | WorkBuddy(CodeBuddy) | 专家包(Agent型) | 安装后显式声明「启用 InfoGen-WorkBuddy」 | infogen-workbuddy / 26H2 |
所有插件都采用手动导入。插件目录会随cmake --install一起安装到<安装前缀>/InfoGen_Data/Plug-ins/,导入时填源码树或安装前缀下的绝对路径均可。
共同前提
已通过
create system --store把行星系统数据导入数据库,并记住导入时使用的命名空间。以HTTP模式启动MCP服务(三个插件默认都连接
http://localhost:8000/mcp):python InfoGen.py service mcp -n<namespace> -Dtransport=http --mcp-global-prompt-instruction- 加上
--mcp-global-prompt-instruction,服务才会把Global.txt放进MCP的instructions字段;不加时客户端只拿得到工具、拿不到全局提示词(WorkBuddy会回退读取包内references/Global.txt副本,ZCode会尝试按路径读取,DSH则不会重复注入,以避免与MCP下发的提示词冲突)。 - 需要换端口时用
-Dport=<端口>,同时要同步修改插件里的MCP地址:DSH需改infogen-dsh.mcpUrl与预设中infogen-mcp.url两处,ZCode在「高级设置」改mcp_url即可。
- 加上
MCP服务暂时不可达不会让客户端崩溃:三个插件都会自动重试,连续失败3次后给出一条静默提醒并正常结束本次请求,服务恢复后工具自动可用。
各客户端要点
- DSH:插件新增独立的
InfoGen-DSHAgent预设,只有选择该预设的会话才会获得 InfoGen 工具、全局提示词与只读工具集,其他会话不受影响;工具在DSH中带服务器前缀(mcp__infogen__QuerySystem等)。该预设从工具层面就是只读的——不注册write/edit/apply_patch/bash。探测状态可通过curl http://127.0.0.1:3080/infogen-dsh/status查看。 - ZCode:
/infogen是该Agent的唯一启用入口,未被该指令派发时不会工作;生成结果直接回到对话。MCP地址可在「插件管理 → InfoGen-ZCode → 高级设置」中修改mcp_url。 - WorkBuddy:必须先显式声明启用(如「启用 InfoGen-WorkBuddy」或「用这个专家帮我查系统」),否则不连接MCP、不查询数据、不生成内容;导入时确认
.codebuddy-plugin/plugin.json位于所选目录根下,不要多选或漏选一层父目录。
各插件的完整配置项、故障排查与更新流程见其目录下的README.md。
查看帮助
python InfoGen.py --help # 查看全部命令
python InfoGen.py create --help # 查看某命令的详细参数
计划添加的功能
- 向量数据库持久化
许可证
本项目基于 GPL-3.0 许可协议开源。
No comments yet. Be the first to write one.