FAQ

常见问题

本页只保留使用和开发中最容易遇到、且值得单独回答的问题。

使用相关

NeurolingsCE 和 Shijima-Qt 是什么关系？

NeurolingsCE 是基于 Shijima-Qt 深度修改而来的项目。当前仓库中还集成了桌宠模拟引擎源码，所以很多引擎级修复可以直接在本仓库内完成。

支持哪些模板格式？

推荐格式是 .mascot 单文件包。它本质上是 zip 兼容压缩包，根目录必须包含 info.json，并包含 actions.xml、behaviors.xml、img/ 等模板资源。

导入器仍兼容常见 Shimeji-ee 风格 ZIP 资源包，并会在导入时转换成 .mascot 包；但不是所有历史资源包都能无改动导入。

可以同时运行多个桌宠吗？

可以。你可以同时召唤多个实例，甚至来自不同模板。

可以同时运行多个 NeurolingsCE 运行时吗？

不可以。程序是单实例设计，但单实例里可以管理多个桌宠实例。

桌宠帧率是多少？

当前设计基于 25 FPS。

平台相关

Windows 启动时提示缺少 Qt6Guid.dll 或其他 Qt DLL

这通常说明运行时 DLL 没有部署到程序目录。

优先处理方式：

1. 确认 CMake 构建时找到了 windeployqt
2. 或把 Qt bin 路径加入 PATH
3. 或手动部署 Qt 运行时

Linux 下为什么前台窗口联动不工作？

先确认你所处的桌面环境：

• KDE Plasma 6：通常开箱即用
• GNOME 46：首次运行后一般需要重新登录一次
• 其他桌面环境：这项能力可能不可用

Wayland 下为什么表现奇怪？

项目的桌宠定位能力与传统桌面窗口模型强相关。在 Linux 上通常会退回到更可行的兼容路径，而不是按原生 Wayland 桌宠模型工作。

macOS 上为什么拿不到前台窗口信息？

通常是 Accessibility 权限没有授予。

处理方式：

1. 打开“系统设置 → 隐私与安全 → 辅助功能”
2. 给 NeurolingsCE.app 或启动它的终端授予权限
3. 重新启动应用

模板与导入

导入成功了，但模板没有出现在列表里

优先怀疑：

• XML 语法有问题
• .mascot 包结构不规范，或 info.json.name 为空
• 导入后的目录结构仍不符合运行时加载要求

请先看 导入桌宠模板。

.mascot 是目录还是文件？

从 0.3.2 开始，推荐的 .mascot 是一个单文件包，不再是普通目录。它可以理解成改了扩展名的 zip 包。

旧版本留下的 xxx.mascot/ 目录会在启动时尽量迁移为 xxx.mascot 文件。运行时加载时会把包解压到缓存目录读取 XML、图片和气泡文本；删除模板时删除的是安装目录中的 .mascot 文件。

CLI 与 API

CLI 是不是通过 HTTP 控制程序？

现在不是。CLI 默认通过本地控制接口与运行时通信，HTTP API 仍然独立存在，但不是 CLI 的主通道。

label 和桌宠实例 id 有什么区别？

• id 是运行时实例 ID
• label 是 CLI 面向用户的标签

label 会在运行时重启后失效。

API 没响应怎么办？

按这个顺序排查：

1. 确认运行时确实在运行
2. 访问 http://127.0.0.1:32456/shijima/api/v1/ping
3. 检查端口 32456 是否被其他程序占用

构建相关

CMake 找不到 Qt6

显式传入 Qt6_DIR、CMAKE_PREFIX_PATH 或 QTDIR。

MSVC 报 32 位工具链错误

请切换到 x64 工具链。项目当前不支持 32 位 MSVC。

Qt6::Multimedia 或 Qt LinguistTools 缺失会怎样？

• 缺少 Qt6::Multimedia：通常退化为无音效构建
• 缺少 LinguistTools：翻译不会被编译进产物

子模块初始化不完整

请重新执行：

git submodule update --init --recursive

下一步阅读

• 快速开始
• 导入桌宠模板
• HTTP API 与 CLI
• 构建指南