Repository Map

仓库导览

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

最常见的入口

你想改什么	先看哪里
程序启动、CLI 分流、单实例	src/app/main.cc
独立 CLI 入口	src/app/cli_main.cc
CLI 参数解析与输出	src/app/cli.cc、src/app/cli/
统一命令协议与业务	src/app/core/commands/
HTTP 接口	src/app/core/http/ShijimaHttpApi.cc
本地控制接口	src/app/core/localipc/
Codex 配置托管	src/app/core/codex/
更新检查与下载	src/app/core/update/
桌宠生成、销毁、调度	src/app/runtime/ManagerLifecycle.cc、ManagerMascotRuntime.cc
模板/会话所有权	src/app/runtime/MascotTemplateStore.cc、MascotSessionStore.cc
环境同步、多屏幕、前台窗口联动	src/app/runtime/ManagerEnvironmentSync.cc、ManagerEnvironmentController.cc
模板导入	src/app/runtime/ManagerImportWorkflow.cc
.mascot 包验证、安装、迁移	src/app/core/assets/MascotPackage.cc
桌宠渲染与交互	src/app/ui/mascot/
管理器窗口与页面	src/app/ui/ManagerWindowSetup.cc、src/app/ui/interface/
气泡与 Codex Markdown 渲染	src/app/ui/widgets/
右键菜单	src/app/ui/menus/
检查器、许可证、进度框等对话框	src/app/ui/dialogs/
平台差异	src/platform/Platform/
行为与协议测试	src/app/tests/
构建和打包	CMakeLists.txt、Makefile、cmake/、src/tools/、installer/wix/、src/packaging/

顶层目录怎么读

src/app/

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

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

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 更应该优先同步。

neurolingsce-skill/ 与 neurolingsce-companion/

仓库内置的 agent skill：前者用于 CLI 桌宠控制，后者用于情绪陪伴场景。

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

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

src/app/main.cc / cli_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 接口问题

Codex 通知链路

CodexActivity（core/commands）
  -> MascotCommandService（core/commands）
  -> ManagerMascotRuntime（runtime）
  -> ShijimaWidget / SpeechBubbleWidget（ui）

事件识别、长度限制与截断在 core/commands，模板选择在 runtime，气泡排版与安全 Markdown 渲染在 ui/widgets。

桌宠本体相关的文件关系

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

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 构建
• macOS CMake 构建
• target 定义
• Qt 组件发现
• windeployqt
• 翻译资源编译
• 测试目标与 CTest 注册

Makefile 与 common.mk

适合看：

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

src/tools/ 与 installer/wix/

适合看：

• package-windows-bin.ps1（Windows 便携包）
• build-msi.ps1 / build-bundle.ps1（MSI 与引导安装器）
• bundle-default.sh、generate-metainfo.sh 等辅助脚本

src/packaging/

适合看：

• 桌面入口、图标
• AppStream / metainfo
• macOS .app 模板与 Info.plist

改动前的建议动作

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

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

下一步阅读

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