本页帮助你快速建立对代码库的正确心智模型,尤其是启动链路、运行时分层和"改什么去哪里"。

NeurolingsCE/
├── src/app/ # Qt 应用层
│ ├── core/ # 基础能力:资源、命令、本地控制、HTTP、音效、引擎
│ ├── runtime/ # 运行时:生命周期、环境同步、导入流程
│ └── ui/ # 管理器界面、桌宠窗口、菜单、对话框、部件
├── src/platform/Platform/ # 平台抽象层
├── include/shijima-qt/ # 公共头文件
├── src/app/core/shijima-engine/ # 集成的桌宠模拟引擎
├── libshimejifinder/ # 导入与解压
├── cpp-httplib/ # HTTP 库
├── ElaWidgetTools/ # GUI 组件库
├── translations/ # 当前翻译资源
└── src/docs/HTTP-API.md # 接口真源文档

当前仓库的主入口在 src/app/main.cc,启动流程可以概括成这样:

main()
 -> 判断是否是 CLI 调用
 -> CLI 调用:进入 QCoreApplication + shijimaRunCli()
 -> GUI 调用:Platform::initialize()
 -> 创建 QApplication
 -> 检查本地运行时是否已存在
 -> 创建 ShijimaManager
 -> 显示管理器窗口或进入 CLI runtime 模式

关键点:

• shijimaShouldRunCli() 会把 CLI 和 GUI 分流开。
• GUI 侧的单实例检查已经优先走本地控制接口 ping,而不是旧文档里那种"CLI 依赖 HTTP"叙述。
• 当 CLI 需要控制运行时但当前没有现成实例时,运行时可以被自动拉起。

放基础能力和跨界面共用能力。

常见内容:

• assets/:模板资源、图片与缓存装载
• audio/:SoundEffectManager
• commands/:桌宠命令服务
• http/:ShijimaHttpApi
• localipc/:本地控制接口
• shijima-engine/:集成的引擎源码

assets/ 里还包含 .mascot 包处理逻辑。新格式下,安装目录保存的是单文件 Name.mascot,运行时会验证 info.json,再解压到应用缓存目录读取 XML、图片、音效和可选的 bubble_context.txt。

放 ShijimaManager 的运行时职责切片。

常见文件:

• ManagerLifecycle.cc
• ManagerMascotRuntime.cc
• ManagerEnvironmentSync.cc
• ManagerImportWorkflow.cc

这些文件负责桌宠生成与销毁、环境同步、模板导入、运行时调度等。

放界面和交互实现。

常见部分:

• ManagerWindowSetup.cc
• ManagerUiActions.cc
• ManagerTrayIcon.cc
• ui/mascot/:桌宠窗口绘制与交互
• ui/menus/:右键菜单
• ui/dialogs/:检查器、许可证、进度框
• ui/widgets/:如气泡组件

它是整个应用的中心管理器,也是大多数"全局行为"的落点。

主要职责:

• 维护模板列表与已生成桌宠
• 驱动运行时 tick
• 响应导入流程
• 协调 GUI、HTTP、本地控制接口与平台层

如果你要改"应用级行为",通常先从 ShijimaManager 相关文件看起。

每个桌宠实例对应一个窗口部件。

典型职责拆分:

• MascotWidgetRendering.cc:绘制与命中区域
• MascotWidgetInteraction.cc:拖拽、点击、菜单
• MascotWidgetLifecycle.cc:生命周期相关逻辑

位于 src/app/core/shijima-engine/,负责:

• 解析 actions.xml 与 behaviors.xml
• 维护动作与行为状态
• 进行 25 FPS 节奏下的模拟推进
• 执行脚本与物理行为

这个引擎已经集成进仓库,因此本项目允许直接在这里做本地修复。

可以把桌宠运行理解成一条持续循环:

加载模板
 -> 生成桌宠实例
 -> 每 tick 同步环境
 -> 推进引擎状态
 -> 重绘窗口
 -> 响应交互 / HTTP / CLI / 本地控制命令

仓库说明和代码都把 tick 频率固定在 25 FPS,这是当前设计基础。

平台相关代码统一放在 src/platform/Platform/。

目录包含:

• Windows/
• Linux/
• macOS/
• Stub/

平台层负责的不是业务逻辑,而是这些底层差异:

• 应用初始化前后的平台特定设置
• 窗口在桌面上的展示方式
• 前台窗口观测
• Linux KDE / GNOME 的专用集成
• macOS 的 Accessibility 相关接入

公共头文件主要有:

• Platform.hpp
• ActiveWindow.hpp
• ActiveWindowObserver.hpp

当前项目里这三者分工已经比较清晰:

• HTTP API:给外部程序提供 REST 接口。
• 本地控制接口:运行时与 CLI 的本机控制通道。
• NeurolingsCE-cli:给脚本、agent 和终端用户用的命令行前端。

理解这一点很重要,因为旧文档容易让人误以为 CLI 只是 HTTP 的一层包装;现在不是这样。

更细的代码定位建议请看 仓库导览。

• 源文件扩展名统一使用 .cc。
• 头文件以 #pragma once 为主。
• 项目头文件使用 #include "shijima-qt/..."。
• 引擎头文件使用 #include <shijima/...>。
• 平台层头文件使用 #include "Platform/..."。
• 大类通常按"主体 + 职责"拆分,例如 ManagerImportWorkflow.cc、MascotWidgetRendering.cc。

• 仓库导览
• 构建指南
• HTTP API 与 CLI
• 贡献指南