Files
lpt-android/AGENTS.md
T

2.3 KiB
Raw Blame History

lpt-android 代理协作规范

LPT 的 Android 客户端:学习会话 + 系统级悬浮窗,不含复习。

规则与技能位置

  • 通用规则(跨仓库):meta 仓库 .agents/roles/(提交规范见其中的 commit-convention.md)。
  • 本仓库暂无专属 roles/ 与 skills/;出现 Android 专属约定时再建。

技术栈

  • Kotlin 2.3.21 + Jetpack Compose(Material 3)
  • AGP 8.13.2 / Gradle 8.14.6 / JDK 17 / compileSdk 36 / minSdk 26
  • Retrofit + OkHttp + kotlinx.serialization;DataStore Preferences
  • 悬浮窗用经典 View + WindowManager,不用 Compose-in-overlay

Compose BOM 锁 2026.03.01。升到 ≥ 2026.04 会要求 AGP 9.1+ / compileSdk 37,见 README。

目录职责

目录 职责
data/ 网络与本地存储;LptApi 是唯一接口定义处,LptRepository 负责 code != 200 → ApiException
session/ SessionController 是会话状态机唯一入口;UI 与服务都只读它的 StateFlow
service/ 前台服务与悬浮窗;不承载业务逻辑,只渲染状态并转发动作
ui/ Compose 页面;不直接调 Retrofit,只调 SessionController / AppContainer

必须遵守的约定

  • 会话状态只在 SessionController 里改。UI 和 Service 都不得自行维护会话副本,否则会与服务端口径分叉。
  • 计时不得用 tick 累加。显示值一律走 State.effectiveSeconds(nowMs),基准取服务端 effectiveTime,锚点取 SystemClock.elapsedRealtime()。
  • 悬浮窗窗口标志不要随手改:FLAG_NOT_FOCUSABLE | FLAG_NOT_TOUCH_MODAL | FLAG_LAYOUT_NO_LIMITS 三者缺一都会出问题(抢焦点 / 挡住下层 / 半隐藏被夹回屏幕内)。
  • 不要在浮窗里做文本输入。App 不在前台时系统不允许后台窗口弹键盘;需要输入时拉起 Activity。
  • 对接后端先看部署环境的 OpenAPI(GET {baseUrl}/v3/api-docs),不要假设源码与部署一致——两者已经分叉过一次。

后端

  • dev:https://lpt-dev.cat-shark.xyz/api
  • 认证:Sa-Token,token 放请求头 satoken(不用 Cookie)
  • 只使用学习会话相关端点,不碰 review/*

提交规范

同 meta 仓库:简短中文,格式 类型: 简述,例如 feat: 新增悬浮窗碎片录入。