面向跑酷画面分析的 Android 本地辅助工具。
使用 Kotlin 与 Android 原生技术开发，优先追求清晰、稳定、可维护的本地工具体验。
项目简介 · 当前进度 · 功能边界 · 开发路线图 · 开发与构建 · 文档 · 交流与反馈
Important
HZZS 仍处于早期开发阶段。README 中标注为“计划中”“后续”或“待接入”的能力，不代表当前版本已经实现、可用或已发布。
火崽崽助手（HZZS）是一个独立开发的 Android 工具项目，目标是为跑酷类游戏提供更清晰的本地状态查看、画面分析、数据记录、参数校准和异常诊断体验。
后续版本计划在用户主动授权的前提下，对屏幕画面进行本地采样与分析，并逐步提供：
- 跑酷状态、分数、生命和关键事件提示
- 地面障碍、顶部障碍、糖果等画面元素识别
- 悬浮窗 HUD 信息展示
- 本局事件记录、战报和历史趋势分析
- 参数校准、设备适配和异常诊断能力
HZZS 不隶属于、不代表、也未获得任何第三方平台、品牌、游戏或服务的官方授权。
当前版本：
0.1.0
当前版本的重点是建立稳定的 Android 工程基础、统一的界面体验，以及后续分析能力所需的交互入口。
| 模块 | 当前状态 | 说明 |
|---|---|---|
| Android 原生工程基础 | 已完成 | Kotlin、Gradle、Android Views 与 Material Components 基础已建立。 |
| 浅色首页界面 | 已完成 | 已具备状态卡片、功能入口、开发信息与社区入口。 |
| 悬浮窗权限与预览 | 已完成 | 支持显示、拖动、关闭和重新打开。 |
| 悬浮窗执行状态 | 已完成 | 支持“开始执行”与“结束执行”的交互状态切换。 |
| QQ 群与 Telegram 入口 | 已完成 | 首页和悬浮窗都可打开对应社区链接。 |
| 屏幕采集授权 | 计划中 | 后续将通过系统授权流程接入。 |
| 实时帧分析 | 计划中 | 尚未接入玩家、障碍、糖果、分数或生命识别。 |
| HUD 实时提示 | 计划中 | 当前悬浮窗仅承担界面与交互预览。 |
| 本局战报与历史记录 | 计划中 | 尚未建立正式数据模型与本地数据库。 |
| 参数校准与异常诊断 | 计划中 | 后续将作为独立能力逐步实现。 |
当前“开始执行”只表示分析流程的交互入口已经建立，不代表已经开始采集屏幕、识别障碍、读取分数或操作游戏。
当前首页采用浅色 Material 风格（暖白背景 #FFF8F6），作为后续功能、状态和反馈信息的统一入口。
目前包含：
- 应用状态概览
- 开发计划入口
- 悬浮窗入口
- 开发者与版本信息
- HZZS QQ 交流群与 Azek431 主频道入口
当前悬浮窗已经具备基础交互能力：
- 用户授权后显示悬浮窗
- 拖动到合适位置
- 点击右上角
×关闭 - 点击“开始执行”进入执行中状态
- 点击“结束执行”回到初始状态，悬浮窗继续保留
- 打开 HZZS QQ 交流群和 Azek431 主频道
- 打开外部链接后保持悬浮窗显示
- 关闭后可从首页再次打开
HZZS 的设计方向是只读分析与信息提示。
| 范围 | 说明 |
|---|---|
| 允许方向 | 本地屏幕画面分析、状态识别、数据记录、HUD 提示、战报统计、校准与诊断。 |
| 不做自动操作 | 不自动点击、不自动跳跃、不自动滑动、不自动复活，也不代替用户控制游戏。 |
| 不静默采集 | 未来涉及屏幕采集时，会要求用户明确授权。 |
| 不默认上传 | 不主动上传截图、日志、运行记录、设备信息或本地分析数据。 |
| 不伪装官方 | 不宣称为任何游戏、平台、品牌或服务的官方工具。 |
后续核心能力会围绕以下本地处理流程展开：
用户主动授权屏幕采集
↓
画面帧采样与预处理
↓
玩家、障碍、糖果、分数等信息识别
↓
跑酷状态机与事件判断
↓
悬浮窗 HUD 提示 / 本局事件记录
↓
本局战报、历史统计、校准与异常诊断
为提高稳定性，后续不会只依赖单帧结果做判断，而会逐步引入：
- 多帧确认与置信度判断
- 逻辑坐标与不同屏幕比例适配
- 不同皮肤和画面风格的视觉配置
- 低置信度降级与可解释提示
- 本地事件摘要记录，而非无意义地保存全部原始帧
以下页面属于开发规划，不代表当前版本已经全部实现。
火崽崽助手
│
├─ 首页
│ ├─ 当前状态概览
│ ├─ 权限与设备状态
│ ├─ 快速操作入口
│ ├─ 最近提示
│ └─ 社区与开发动态
│
├─ 运行
│ ├─ 执行状态
│ ├─ 屏幕采集授权
│ ├─ HUD 设置
│ ├─ 实时事件提示
│ └─ 最近运行结果
│
├─ 分析
│ ├─ 本局战报
│ ├─ 历史记录
│ ├─ 事件时间线
│ ├─ 数据趋势
│ └─ 本地导出与清理
│
└─ 我的
├─ 权限管理
├─ 校准中心
├─ 异常诊断
├─ 本地数据管理
├─ 关于应用
└─ 更新与反馈
路线图表示当前优先级，会根据真实设备表现、稳定性和用户反馈持续调整。
目标：建立可长期维护的 Android 工程基础。
- 创建 Android 原生项目
- 确定项目名称、包名、主题与基础资源
- 配置 Kotlin、Gradle 与 Android SDK 基础环境
- 建立本地 Release 签名流程
- 添加 README 与 MIT License
- 完善签名文件与本地配置保护规则
- 建立 GitHub Issue 模板与协作规范
目标：建立统一、稳定、可扩展的应用壳层。
- 建立浅色首页基础界面
- 建立悬浮窗权限入口
- 实现悬浮窗显示、拖动、关闭和重新打开
- 建立开始执行与结束执行的状态切换
- 接入 QQ 群与 Telegram 社区入口
- 建立完整底部导航与页面切换
- 完善空状态、加载状态、错误状态与无障碍标签
- 完善应用图标、启动页与关于页面
目标：在明确授权的前提下，建立稳定的本地帧分析能力。
- 接入 MediaProjection 屏幕采集授权流程
- 建立帧采样与图像预处理模块
- 建立逻辑坐标与游戏画面区域适配
- 识别玩家区域与基础姿态
- 识别地面障碍与顶部障碍
- 识别糖果、分数和生命状态
- 建立多帧确认与置信度模型
- 在异常或低置信度时提供明确提示
目标：把识别结果转化为可理解、可回看的本地数据。
- 建立实时 HUD 提示模型
- 建立跑酷事件时间线
- 记录本局关键事件
- 建立本局战报页面
- 增加历史记录与数据趋势
- 支持本地数据导出、清理与恢复
- 默认关闭任何未明确说明的数据上传行为
目标：让不同设备和画面环境下的问题更容易被定位和解决。
- 建立校准中心
- 保存、恢复和重置视觉参数
- 建立设备环境检查
- 增加异常原因分类
- 增加本地日志与诊断快照导出
- 提供问题定位与恢复建议
- 优化不同 Android 版本和设备的适配体验
目标：形成可重复的测试、发布和反馈闭环。
- 完善 Debug 与 Release 构建检查清单
- 建立 GitHub Releases 发布流程
- 编写版本更新日志与升级说明
- 编写用户使用说明与常见问题
- 建立基础兼容性测试流程
- 发布首个可测试版本
- 根据反馈持续优化稳定性、性能与界面体验
| 项目 | 内容 |
|---|---|
| 应用名称 | 火崽崽助手 |
| 项目代号 | HZZS |
| 当前版本 | 0.1.0 |
| Package / Namespace | top.azek431.hzzs |
| 开发语言 | Kotlin |
| 当前 UI 基础 | Android Views + Material Components |
| UI 方向 | 浅色 Material Design 3 风格（暖白背景 #FFF8F6） |
| 最低 Android 版本 | API 24（Android 7.0） |
| 编译 SDK | API 37 |
| 目标 SDK | API 37 |
| 构建工具 | Gradle Wrapper |
| 推荐 JDK | JDK 17 |
| Release 签名 | PKCS12，本地私有保存，不提交到仓库 |
当前目录会随功能增加继续拆分。以下是目前较核心的文件与后续方向：
hzzs/
├─ app/
│ ├─ src/
│ │ ├─ main/
│ │ │ ├─ java/top/azek431/hzzs/
│ │ │ │ ├─ MainActivity.kt
│ │ │ │ ├─ OverlayPreviewManager.kt
│ │ │ │ ├─ CommunityLinks.kt
│ │ │ │ └─ NativeAnalysisBridge.kt
│ │ │ ├─ cpp/
│ │ │ │ ├─ include/hzzs/analysis/
│ │ │ │ ├─ src/analysis/
│ │ │ │ ├─ src/jni/
│ │ │ │ └─ CMakeLists.txt
│ │ │ ├─ res/
│ │ │ │ ├─ layout/
│ │ │ │ │ ├─ activity_main.xml
│ │ │ │ │ └─ view_overlay_preview.xml
│ │ │ │ ├─ drawable/
│ │ │ │ └─ values/
│ │ │ └─ AndroidManifest.xml
│ │ ├─ build.gradle.kts
│ │ └─ proguard-rules.pro
├─ docs/
│ ├─ architecture.md
│ ├─ analysis-algorithm.md
│ ├─ testing.md
│ └─ privacy-and-boundaries.md
├─ gradle/
├─ .vscode/
├─ build.gradle.kts
├─ gradle.properties
├─ settings.gradle.kts
├─ gradlew
├─ gradlew.bat
├─ LICENSE
├─ README.md
├─ CONTRIBUTING.md
└─ CHANGELOG.md
后续预计会逐步形成更清晰的模块边界：
app/src/main/java/top/azek431/hzzs/
├─ ui/
│ ├─ home/
│ ├─ run/
│ ├─ analysis/
│ ├─ profile/
│ ├─ calibration/
│ └─ diagnostics/
├─ capture/
├─ vision/
├─ model/
├─ data/
├─ service/
└─ util/
推荐开发环境：
操作系统：Windows 10 / Windows 11
编辑器：Visual Studio Code
Java：JDK 17
Android SDK Platform：API 37
Android SDK Build-Tools：37.0.0
构建工具：Gradle Wrapper
项目使用 Gradle Wrapper，通常不需要额外全局安装 Gradle。
在项目根目录打开 PowerShell 后，构建 Debug APK：
.\gradlew.bat :app:assembleDebug注意：上述命令在 PowerShell 中也可写作
.\gradlew.bat :app:assembleDebug。 如果你使用的是 CMD，可以直接运行gradlew.bat :app:assembleDebug（无需.\前缀）。
Debug APK 默认输出位置：
app/build/outputs/apk/debug/app-debug.apk
Debug APK 使用 Android 自动生成的调试签名，仅适合本地开发与测试。
正式 Release APK 使用开发者本机保存的私有签名。
以下信息必须保留在本地安全环境中，不应提交到 Git 仓库：
发布签名文件
签名密码
私钥密码
本地密钥库路径
个人环境变量
本地签名配置
请勿将以下类型文件提交到 GitHub：
*.jks
*.keystore
*.p12
*.pfx
keystore.properties
signing.properties
包含密码的 local.properties
HZZS 后续会优先采用本地数据管理策略。
项目计划遵循以下原则：
- 默认优先在设备本地保存记录、配置和诊断信息。
- 不主动上传运行记录、截图、日志或设备信息。
- 涉及屏幕采集或系统权限时，明确说明用途并要求用户主动授权。
- 用户应能够查看、导出或清理本地数据。
- 不在未说明的情况下收集个人信息。
- 不在仓库中保存用户隐私数据、签名文件或敏感配置。
本项目是独立开发的本地工具应用。
请在遵守当地法律法规、设备系统规则、服务条款与平台规则的前提下使用。
请勿将本项目用于：
- 违反法律法规的行为
- 违反平台规则或服务条款的行为
- 自动化操控、代打、绕过限制或破坏公平性的行为
- 损害他人权益的行为
- 传播恶意软件、隐私数据或未经授权的内容
HZZS 目前处于持续开发阶段，欢迎通过以下入口参与测试、反馈和交流。
- HZZS 项目 QQ 交流群（测试、反馈与问题讨论）：130330601
- Azek431 主频道（同步 HZZS 与更多项目动态）：@AzekMain
- GitHub Issues：适合提交可复现的问题、构建错误、设备兼容问题和功能建议。
反馈问题时，建议尽量附上：
设备型号
Android 版本
应用版本
问题描述
复现步骤
相关截图
错误日志
请不要在 Issue、Discussion、Pull Request、日志或截图中上传：
签名文件
密钥库密码
私钥密码
个人账号密码
手机号
身份证明
真实住址
其他隐私信息
提交代码前，请确保：
- 不包含密码、私钥、签名文件或个人配置。
- 不复制来源不明或许可证不兼容的代码与资源。
- 不把规划中的功能描述成已经实现。
- 提交说明能够准确描述改动目的。
- 新增能力应保留清晰的边界，避免把页面、分析、存储和系统服务逻辑堆进单一文件。
本项目采用 MIT License 开源。
MIT 协议允许他人使用、复制、修改、合并、发布、分发、再授权和销售本项目的软件副本；使用或分发时需保留原始版权声明与许可证文本。第三方依赖、素材或资源仍可能适用其各自的许可证，使用前应自行核对。
Built with ❤️ by Azek431