Imported from xiaweizi/StudyWord (
AGENTS.md). Install upstream withnpx skills add xiaweizi/StudyWord. Copyright stays with the author.
Repository Guidelines
项目结构与模块组织
本仓库为单模块 Android 项目，核心代码位于 app 模块。Kotlin 源码放在 app/src/main/java/com/studyword/literacy，按 ui、data、model、util 等功能包划分。静态资源（含主字库 character_sets.json）位于 app/src/main/assets，调整字库时保持难度分组顺序。XML 资源集中在 app/src/main/res，布局文件遵循 activity_*.xml、item_*.xml 命名，Drawable 依据类型拆分子目录。根目录保留 build.gradle、settings.gradle 与 gradle/ wrapper，勿随意删除以免破坏持续集成脚本。
构建、测试与开发命令
使用 ./gradlew assembleDebug 生成可调试 APK 并验证依赖。执行 ./gradlew installDebug 将构建结果安装到已连接设备或模拟器。提交前运行 ./gradlew lint 捕获 Android Lint 警告；需要释放包时，可调用 ./gradlew assembleRelease 并确保签名配置完整。./gradlew test 负责 JVM 单元测试，配合 ./gradlew connectedAndroidTest 校验仪器化测试。若遭遇缓存异常，可通过 ./gradlew clean 清理构建产物，必要时在 Android Studio 内同步 Gradle 以刷新 IDE 配置。
代码风格与命名约定
项目采用 Kotlin 官方代码风格（kotlin.code.style=official）。保持四空格缩进，优先使用 val，函数逻辑尽量集中且控制在 60 行左右。类、Activity 使用 UpperCamelCase，状态存储或 ViewModel 追加语义化后缀（如 ProgressStore）。资源 ID 与布局文件延续 snake_case；新增文案统一放入 res/values/strings.xml，颜色优先复用 res/values/colors.xml 中的定义。提交前使用 Android Studio 的 Code > Reformat Code 与 Optimize Imports，保持团队风格一致。
测试规范
单元测试位于 app/src/test/java，使用 JUnit4（@Test 标注），包名与被测类保持一致，文件名后缀 Test，如 ProgressStoreTest。UI 与集成测试放在 app/src/androidTest/java，在 API 26+ 模拟器上执行 ./gradlew connectedAndroidTest。为关键边界条件编写 KDoc 注释，便于后续维护。修改仓储或持久化逻辑时至少补齐回归用例，并在 PR 描述中说明测试覆盖的业务场景。
提交与 Pull Request 指南
遵循现有提交历史：提交标题使用简洁中文，空一行后在 “详细说明：” 下用列表描述关键变更。协作时保留 Co-Authored-By: weizi <1012126908@qq.com>。发起 Pull Request 时说明改动范围、关联 Issue、列出手动测试记录（设备、构建类型、命令），UI 相关改动附关键截图。确保 lint 与单元测试通过再请求评审，并在 PR 中勾选适用的检查清单以便快速复查。
数据与配置提示
更新 character_sets.json 时保留简单/中等/困难分组，并按笔画数排序以维持学习节奏。新增持久化字段需在 ProgressStore 中提供向后兼容的默认值。除非与维护者协商，请保持 minSdk 26 与 targetSdk 34 配置不变。local.properties 存放本地 SDK 路径，不要提交到版本库；环境变量变化时在 README 中同步说明。
