Architecture

架构概览

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

先看整体结构

NeurolingsCE/
├── src/app/                     # Qt 应用层
│   ├── core/                    # 基础能力：资源、命令、Codex、本地控制、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（独立 CLI 入口为 src/app/cli_main.cc），启动流程可以概括成这样：

main() / cli_main.cc
  -> 初始化日志与平台能力
  -> 判断是否是 CLI 调用
  -> CLI 调用：进入 QCoreApplication + shijimaRunCli()
  -> GUI 开机启动：识别 --neurolingsce-startup
  -> GUI 调用：Platform::initialize()
  -> 创建 QApplication
  -> 检查本地运行时是否已存在
  -> 创建 ShijimaManager
  -> 显示管理器窗口、进入 CLI runtime 模式，或静默恢复启动组合

关键点：

• shijimaShouldRunCli() 会把 CLI 和 GUI 分流开。
• GUI 侧的单实例检查已经优先走本地控制接口 ping。
• 当 CLI 需要控制运行时但当前没有现成实例时，运行时可以被自动拉起。
• --neurolingsce-startup 是系统登录启动专用参数。若设置了静默启动，管理器会保持在托盘中，并恢复上次或指定桌宠组合。
• HTTP API 默认关闭，只有 http/enabled 设置为 true 时才会启动，且只绑定 127.0.0.1:32456。

src/app 的真实分层

src/app/core/

放基础能力和跨界面共用能力，是 CLI、IPC、HTTP 与 GUI 共用的服务层。

常见内容：

• assets/：模板资源、图片、缓存装载与 .mascot 包处理
• audio/：SoundEffectManager
• codex/：Codex notify 配置块的托管、备份与恢复
• commands/：统一 JSON 命令协议（MascotApi / Dispatcher / Service / CodexActivity）
• http/：ShijimaHttpApi（默认关闭）
• localipc/：本地 JSONL IPC（默认控制通道）
• shijima-engine/：集成的引擎源码
• update/：GitHubUpdateManager 更新检查、下载与安装准备

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

src/app/runtime/

放 ShijimaManager 的运行时职责切片。

常见文件：

• ManagerLifecycle.cc
• ManagerMascotRuntime.cc
• ManagerEnvironmentSync.cc
• ManagerEnvironmentController.cc
• ManagerImportWorkflow.cc
• MascotTemplateStore.cc / MascotSessionStore.cc
• ManagerRuntimeState.hpp / ManagerRuntimeHelpers.hpp

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

src/app/ui/

放界面和交互实现。

常见部分：

• ManagerWindowSetup.cc / ManagerUiActions.cc / ManagerTrayController.cc
• ui/interface/：Home、Create（制作/转换）、Combinations（组合）、Settings、About 页面
• ui/mascot/：桌宠窗口绘制与交互
• ui/menus/：右键菜单
• ui/dialogs/：检查器、许可证、进度框
• ui/widgets/：SpeechBubbleWidget、CodexBubbleFormatter（受限 Markdown 渲染与安全清洗）

核心对象

ShijimaManager

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

主要职责：

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

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

命令与控制面

• MascotApi：JSON 请求/响应结构。
• MascotCommandDispatcher / MascotCommandService：通用校验、路由与 Manager 业务适配。
• ShijimaLocalApi：本地 JSONL IPC 服务端与客户端，单行一个 JSON object，带 1 MiB 上限。
• ShijimaHttpApi：可选的本地 HTTP 服务，把请求转换为同一套命令协议。
• CodexActivity / CodexConfigManager：Codex 事件识别与 notify 配置托管。

CLI、localipc、HTTP 共用 core/commands 定义的消息结构，不要在三个传输层各自发明字段。

ShijimaWidget

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

典型职责拆分：

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

shijima-engine

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

• 解析 actions.xml 与 behaviors.xml
• 维护动作与行为状态
• 按完整 tick 推进模拟，每个完整 tick 拆成固定 subtick 做物理与插值细分
• 执行脚本与物理行为

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

mascot 生命周期和 tick 机制

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

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

当前节奏是每秒 25 个完整 tick（40 ms 一个完整周期），每个完整 tick 内部再拆成 4 个 subtick（约 10 ms 一个 subtick）用于物理与位移插值；Duration 等时长字段按完整 tick 计算。

平台抽象层做什么

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

目录包含：

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

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

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

公共头文件主要有：

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

本地控制接口、HTTP API、CLI 三者关系

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

• HTTP API：给外部程序提供 REST 接口，但默认关闭，需要 http/enabled=true 显式开启。
• 本地控制接口：运行时与 CLI 的本机控制通道，是默认主通道。
• NeurolingsCE-cli：给脚本、agent 和终端用户用的命令行前端，走本地 IPC，不经过 HTTP。

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

Codex 通知链路

Codex 命令或通知脚本
  -> CodexActivity（事件识别、摘要与截断）
  -> MascotCommandService
  -> ManagerMascotRuntime
  -> ShijimaWidget / SpeechBubbleWidget

消息长度、事件识别、模板选择和气泡排版分别在 core/commands、runtime、ui/widgets 中完成。投递是 best-effort：只有运行时已启动时才显示。

更新检查链路

GitHubUpdateManager 读取 GitHub Pages 上的静态清单，比较版本、下载更新文件并转交平台/安装逻辑；下载产物会经过 SHA-256 校验。更新逻辑不阻塞 GUI tick。

https://blog.qingchenyou.asia/NeurolingsCE/update/latest.json

发布 Release 后，publish-update-manifest workflow 会用 tools/generate_sha256sums.py 从官方 asset digest 生成确定性的 SHA256SUMS.txt 并补传到 Release，刷新并校验 Release 元数据后，再用 tools/generate_update_manifest.py 生成 public/update/latest.json 并部署到 GitHub Pages。

想改什么，先看哪里

需求	建议先看
启动与单实例	src/app/main.cc、src/app/core/localipc/
开机自启与静默恢复	src/app/main.cc、src/app/ui/interface/ManagerSettingsPage.cc、ManagerCombinationsPage.cc
CLI 参数与输出	src/app/cli_main.cc、src/app/cli.cc、src/app/cli/
命令协议与业务	src/app/core/commands/
HTTP 接口	src/app/core/http/ShijimaHttpApi.cc、src/docs/HTTP-API.md
本地 IPC	src/app/core/localipc/
Codex 集成	src/app/core/codex/、src/app/core/commands/CodexActivity.cc、src/app/ui/widgets/
桌宠组合	src/app/ui/interface/ManagerCombinationsPage.cc
更新检查	src/app/core/update/、.github/workflows/publish-update-manifest.yml、tools/generate_sha256sums.py、tools/generate_update_manifest.py
模板导入	src/app/runtime/ManagerImportWorkflow.cc
.mascot 包验证、安装、迁移	src/app/core/assets/MascotPackage.cc
桌宠渲染与交互	src/app/ui/mascot/
右键菜单	src/app/ui/menus/
主窗口页面	src/app/ui/interface/
平台相关行为	src/platform/Platform/
构建与打包	CMakeLists.txt、Makefile、cmake/、src/tools/、installer/wix/

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

代码组织约定

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

下一步阅读

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