Repository Map

仓库导览

本页回答一个非常实际的问题：如果你已经知道自己想改什么，第一眼该去哪个目录、哪个文件。

最常见的入口

你想改什么	先看哪里
程序启动、CLI 分流、单实例	src/app/main.cc
CLI 参数解析与输出	src/app/cli.cc、src/app/cli/
HTTP 接口	src/app/core/http/ShijimaHttpApi.cc
本地控制接口	src/app/core/localipc/
桌宠生成、销毁、调度	src/app/runtime/ManagerLifecycle.cc、ManagerMascotRuntime.cc
环境同步、多屏幕、前台窗口联动	src/app/runtime/ManagerEnvironmentSync.cc
模板导入	src/app/runtime/ManagerImportWorkflow.cc
.mascot 包验证、安装、迁移	src/app/core/assets/MascotPackage.cc
桌宠渲染与交互	src/app/ui/mascot/
管理器窗口与界面动作	src/app/ui/Manager*.cc、src/app/ui/interface/
右键菜单	src/app/ui/menus/
检查器、许可证、进度框等对话框	src/app/ui/dialogs/
平台差异	src/platform/Platform/
构建和打包	CMakeLists.txt、Makefile、cmake/、src/packaging/

顶层目录怎么读

src/app/

主应用层，按照职责拆成了 core、runtime、ui。

这是你改业务逻辑时最常进入的目录。

src/platform/Platform/

平台抽象层，按 Windows、Linux、macOS、Stub 分目录。

如果一个问题只在某个平台复现，通常应先来这里定位。

include/shijima-qt/

公共头文件入口。想看类的公开接口，通常从这里进。

src/app/core/shijima-engine/

集成的桌宠模拟引擎源码。

如果问题已经深入到 XML 行为解析、动作执行、物理或脚本层，最终大多会落到这里。

translations/

当前翻译资源。现在仓库里至少有简体中文翻译文件。

src/docs/HTTP-API.md

接口真源文档。你改了 API 或 CLI 语义时，这里通常比 wiki 更应该优先同步。

GUI、CLI、控制接口之间的文件关系

如果你在改控制链路，可以按这条线看：

src/app/main.cc
  -> src/app/cli.cc
  -> src/app/cli/CommandLineParser.cc
  -> src/app/cli/CommandExecutor.cc
  -> src/app/core/commands/
  -> src/app/core/localipc/
  -> src/app/core/http/

这条链路能帮你判断一个问题到底属于：

• 参数解析问题
• 命令执行问题
• 本地控制接口问题
• HTTP 接口问题

桌宠本体相关的文件关系

如果你在改“桌宠为什么这样动、这样画、这样响应”，可以从这里切入：

src/app/runtime/ManagerMascotRuntime.cc
  -> src/app/ui/mascot/
  -> src/app/core/shijima-engine/

常见分工：

• 运行时层决定何时生成、如何调度
• UI 层决定如何绘制、如何交互
• 引擎层决定行为逻辑和状态推进

平台问题排查路径

Windows

先看：

• src/platform/Platform/Windows/

适合排查：

• 前台窗口获取
• 窗口样式
• 与任务栏 / Alt-Tab 相关的问题

Linux

先看：

• src/platform/Platform/Linux/

适合排查：

• KDE / GNOME 前台窗口追踪
• DBus 交互
• Shell 扩展或脚本联动

macOS

先看：

• src/platform/Platform/macOS/

适合排查：

• Accessibility
• AppKit 相关行为

构建与产物相关文件

CMakeLists.txt

适合看：

• Windows / MSVC 构建
• target 定义
• Qt 组件发现
• windeployqt
• 翻译资源编译

Makefile 与 common.mk

适合看：

• Linux / macOS / MinGW 构建
• 发布目录结构
• AppImage / macOS .app
• GUI 与 CLI 实际产物名

改动前的建议动作

如果你不确定应该从哪里下手，推荐按这个顺序：

1. 先在 架构概览 里确认该能力属于哪一层。
2. 再来本页查最可能的目录和文件。
3. 最后再打开对应头文件，确认接口边界。

下一步阅读

• 架构概览
• 构建指南
• 贡献指南