Architecture

架构概览

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

先看整体结构

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 需要控制运行时但当前没有现成实例时，运行时可以被自动拉起。

src/app 的真实分层

src/app/core/

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

常见内容：

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

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

src/app/runtime/

放 ShijimaManager 的运行时职责切片。

常见文件：

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

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

src/app/ui/

放界面和交互实现。

常见部分：

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

核心对象

ShijimaManager

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

主要职责：

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

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

ShijimaWidget

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

典型职责拆分：

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

shijima-engine

位于 src/app/core/shijima-engine/，负责：

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

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

mascot 生命周期和 tick 机制

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

加载模板
  -> 生成桌宠实例
  -> 每 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、CLI 三者关系

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

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

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

想改什么，先看哪里

需求	建议先看
启动与单实例	src/app/main.cc、src/app/core/localipc/
CLI 参数与输出	src/app/cli.cc、src/app/cli/
HTTP 接口	src/app/core/http/ShijimaHttpApi.cc、src/docs/HTTP-API.md
模板导入	src/app/runtime/ManagerImportWorkflow.cc
.mascot 包验证、安装、迁移	src/app/core/assets/MascotPackage.cc
桌宠渲染与交互	src/app/ui/mascot/
右键菜单	src/app/ui/menus/
平台相关行为	src/platform/Platform/
构建与打包	CMakeLists.txt、Makefile、cmake/、src/packaging/

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

代码组织约定

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

下一步阅读

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