| name | metasweeper-dev |
| description | 元扫雷核心开发助手。当需要修改核心游戏逻辑、导入导出、录像回放、stats.dat 格式、 窗口行为、游戏状态机、计分板/计数器、UI 菜单、游戏模式时使用此 skill。 涵盖架构详解、模块文档、常见修改场景、调试指南。 |
元扫雷核心开发助手
何时使用
- 修改核心游戏逻辑（游戏状态、雷区交互、胜利/失败判定）
- 修改导入导出（stats.dat、CSV、meta.dat）
- 修改录像回放功能
- 修改计分板/计数器
- 修改 UI 菜单栏、对话框
- 添加新的游戏模式或约束
- 调试窗口行为、事件响应
- 修改打包/构建流程
架构详解
继承链
ui.ui_main_board.Ui_MainWindow # 自动生成的 UI 表单
└─ superGUI.Ui_MainWindow # 基类：路径、配置、设置读写
└─ MineSweeperGUIEvent # 鼠标/键盘/滚轮事件
└─ MineSweeperVideoPlayer # 录像回放控制器
└─ MainWindowGUIImportExport # 导入/导出
└─ MineSweeperGUI # ★ 主游戏控制器
MainWindow（mainWindowGUI.py）是独立的 QMainWindow 实例，不作为继承的一部分，而是作为 self.mainWindow 属性传入。
游戏状态机
状态定义在 src/config/constants.py：
READY → PLAYING → WIN / FAIL
↘ JOKING → JOWIN / JOFAIL
DISPLAY / SHOW_DISPLAY（录像回放）
SHOW（概率显示）
STUDY（分析模式）
状态变更入口：mineSweeperGUI.py 中 game_state 的 setter（line ~240-300）。
数据流
用户操作（鼠标/键盘）
→ MineSweeperGUIEvent（事件转换）
→ ms_toollib（实际游戏逻辑，.pyd）
→ board_renderer / mineLabel（界面绘制）
→ gameScoreBoard（计数器刷新）
→ （游戏结束时）→ stats.dat 加密写入
stats.dat 读写
| 操作 | 位置 | 方法 |
|---|
| 写入单条记录 | mineSweeperGUI.py:415-432 | gameFinished() 中调用 |
| 读取所有 short_md5 | mineSweeperGUI.py:1486-1514 | _read_stats_dat_short_md5s() |
| 导入 3.2.2 evf | mainWindowGUIImportExport.py:44-233 | 旧 exe 验证 → dedup → 写入 |
| 导入旧版 stats.dat | mainWindowGUIImportExport.py:241-277 | 直接解密 → dedup → 写入 |
| 导出 CSV | mainWindowGUIImportExport.py:349-435 | 解密 → 过滤 → csv.writer |
| 导出 meta.dat | mainWindowGUIImportExport.py:437-509 | 解密 → 过滤 → 重新加密写入 |
AES-128-GCM 密钥在 superGUI.STATS_DAT_KEY。
常见修改场景
1. 新增导出菜单项
步骤：
1. uiFiles/main_board.ui → 添加 action（设 text、font）
2. uiFiles/ → 执行 ui转py.bat → 自动编译到 src/ui/
3. MainWindowGUIImportExport.__init__ → trigger 连线
4. 实现导出方法
严禁直接修改 src/ui/ 下的生成文件，所有界面改动必须先改 uiFiles/ 下的 .ui 源文件，再执行 ui转py.bat。
2. 修改去重逻辑
去重 key 目前是 short_md5（md5[:8]）。如需加入 mine_num/row/column：
- 改
_read_stats_dat_short_md5s() 返回 set[tuple]
- 改两处 import（evf 和 dat）的对比逻辑
3. 新增游戏模式
步骤：
1. src/config/constants.py → 加 MODE_xxx 常量
2. src/utils/helpers.py → trans_game_mode 翻译
3. src/superGUI.py → predefinedBoardPara 配置
4. src/mineSweeperGUI.py → 约束逻辑
4. 修改计数器 namespace
变量通过 score_board_manager.with_namespace({...}) 注入。
name 到公式别名的映射在 utils/helpers.py:trans_expression()。
如需刷新 UI 记得调 score_board_manager.show(ms_board, index_type)。
调试指南
- 窗口行为问题：检查
mainWindowGUI.py:closeEvent + superGUI.py:read_or_create_game_setting + 配置 key 大小写
- stats.dat 解密失败：确认
STATS_DAT_KEY 一致、nonce/tag/ciphertext 长度正确
- 菜单不显示：运行
uiFiles/ui转py.bat 重新生成 .py，检查 action 连线
- 插件不加载：
plugin_manager\_run.py 入口，plugin_loader.py 扫描路径
构建
构建由 GitHub Actions CI 完成（.github/workflows/python-app.yml），不在本地构建。
触发方式：推送到 main/master 自动构建；也可在 Actions 页面手动 workflow_dispatch。
CI 流程：
- 安装 Qt + Python 3.12
pyinstaller 打包 metasweeper.exe（含 --runtime-hook hook-debugpy-pyinstaller.py）pyinstaller 打包 plugin_manager.exe- 合并资源到
dist/metasweeper/
- 上传 Artifact（zip 包）
