ChessVisionTrainer ♟️

离线端侧国际象棋棋盘视觉识别与 Stockfish 18 走法训练辅助工具 (Android)

Built with Google AI Studio: https://ai.studio/apps/f2b75c4e-2e55-440f-b8b9-dc88ba5e6ce0

---

✨ 核心特性

• 100% 离线端侧运行：显式移除 INTERNET 与 ACCESS_NETWORK_STATE 权限，所有视觉推理与引擎计算均在手机本地完成。
• 双阶段高精度棋盘与棋子识别 (YOLOv8m + LiteRT)：
  • 使用 NAKSTStudio/yolov8m-chess-piece-detection (best_f16.tflite, [1, 640, 640, 3] -> [1, 17, 8400])。
  • 支持 全局检测 -> 棋盘区域裁剪二次高分辨率推理 (Focused Crop Inference)，结合像素级 8×8 棋盘格自动定位 (detectCheckerboardRectFromPixels) 与手动框选校准，解决竖屏手游棋盘占比小、边缘坐标或聊天框干扰的问题。
  • 启动时通过 TfliteModelInspector 直接解析 FlatBuffer 张量结构与校验 SHA-256，拒绝错误网页或 Git LFS 指针文件。
• 严谨的 FEN 重建与规则合法性校验 (ChessPositionAndRules.kt)：
  • 支持白方在下 (WHITE_BOTTOM) / 黑方在下 (BLACK_BOTTOM) 自动判定与手动切换。
  • GameStateTracker 自动追踪从初始局面演进的易位权 (KQkq)、吃过路兵目标格 (en passant) 与回合数；中途加入对局时自动提示用户确认易位权等未明历史状态。
  • 完备检验双王数量、双王相邻、底线兵、非走子方被将军等非法局面，并准确识别王车易位、吃过路兵、升变、将死 (Checkmate) 与逼和 (Stalemate)。
• 本地 Stockfish 18 UCI 引擎 (StockfishEngineController.kt)：
  • 集成官方 Stockfish 18 (arm64-v8a 内置双 NNUE 网络 nn-c288c895ea92.nnue / nn-37f18f62d772.nnue)。
  • 支持低 / 中 / 高三档性能模式（动态适配分辨率、CPU 线程数、Hash 大小与思考时间），具备过期请求自动中断 (stop) 与丢弃机制。
• 游戏内战术悬浮窗与触摸穿透走法箭头 (FloatingOverlayViews.kt)：
  • ♟ 悬浮胶囊一键触发单帧分析、长按清除箭头、⊞ 校准 直接在当前游戏画面上全屏框选/自动吸附对齐棋盘。
  • 推荐走法箭头 (FLAG_NOT_TOUCHABLE) 完全触摸穿透，不影响正常下棋操作。

---

📂 项目结构

app/src/main/
├── AndroidManifest.xml                  # 离线权限声明、MediaProjection 前台服务与悬浮窗权限
├── assets/
│   ├── model_metadata.json              # 模型与 Stockfish 18 资产溯源、张量规格与 SHA-256 校验值
│   └── licenses/                        # AGPLv3 / GPLv3 / Apache-2.0 开源许可文本
└── java/com/example/
    ├── MainActivity.kt                  # Jetpack Compose 主界面（状态监控、档位/方向设置、手动校准与测试）
    ├── capture/
    │   ├── ImageFrameConverter.kt       # RGBA_8888 ImageReader 帧安全转换（严格处理 pixelStride/rowPadding）
    │   ├── ScreenCaptureOverlayService.kt # MediaProjection 虚拟屏幕采集与悬浮窗生命周期管理
    │   └── TrainerSessionOrchestrator.kt # 采集 -> 视觉 -> 规则校验 -> Stockfish -> 悬浮窗 编排器
    ├── chess/
    │   └── ChessPositionAndRules.kt     # 8x8 棋盘状态、FEN 解析、合法走法生成与对局状态追踪器
    ├── engine/
    │   └── StockfishEngineController.kt # Stockfish 18 本地进程管理与 UCI 协议通信
    ├── model/
    │   └── TrainerModels.kt             # 性能档位、棋子类别映射、校准框与分析报告数据模型
    ├── overlay/
    │   └── FloatingOverlayViews.kt      # 悬浮胶囊按钮、触摸穿透走法箭头、游戏内棋盘校准视图
    └── vision/
        ├── CoordinateTransformer.kt     # 模型空间 <-> 截图空间 <-> 8x8 网格 <-> 屏幕悬浮窗 坐标变换链
        ├── TfliteModelInspector.kt      # TFLite FlatBuffer 结构与 SHA-256 校验器
        └── YoloChessDetector.kt         # LiteRT (TFLite) 推理、NMS 后处理与二次裁剪重推理

---

🚀 本地构建与运行

1. 下载模型与引擎二进制文件

由于 best_f16.tflite (~51.9 MB) 与 libstockfish.so (~114.1 MB) 体积较大（超过 GitHub 单文件 100 MB 限制且不包含在 AI Studio 源码导出压缩包中），在编译 APK 前请运行项目自带的一键下载与 SHA-256 校验脚本：

Windows (PowerShell):

.\scripts\download_assets.ps1

macOS / Linux (Bash):

chmod +x scripts/download_assets.sh
./scripts/download_assets.sh

脚本会自动下载并校验以下两个文件（与 app/src/main/assets/model_metadata.json 完全一致）：

1. app/src/main/assets/best_f16.tflite
   • 来源：NAKSTStudio/yolov8m-chess-piece-detection
   • SHA-256：2bfabe22f91266a2308a7df29c2a22afbbdb537fb2040ef8c93f6ed4fc144033
2. app/src/main/jniLibs/arm64-v8a/libstockfish.so
   • 来源：official-stockfish/Stockfish (sf_18 stockfish-android-armv8.tar)
   • SHA-256：cc3b3b74466b6d85cdc0f8cfdad4111c6a44bd0698f4eab96fea7b359a54d3d4

2. 使用 Android Studio 打开并运行

1. 打开 Android Studio，选择 Open 并打开本项目目录。
2. 等待 Gradle 同步完成。
3. 连接 arm64-v8a 安卓真机或模拟器，点击 Run 即可安装运行。

---

📜 开源许可声明

• 视觉模型 (best_f16.tflite)：NAKSTStudio/yolov8m-chess-piece-detection — AGPL-3.0
• 国际象棋引擎 (libstockfish.so)：Stockfish 18 — GPL-3.0-or-later
• 推理运行时 (Google AI Edge LiteRT)：Apache-2.0

详见 app/src/main/assets/licenses/ 目录下的完整许可证文本。