- 会话冲突出口:开始新任务前查其他任务上的未结束会话,给出「前往继续 / 结束它并开始 / 放弃它」三个出口,避免同时存在两个进行中的会话 - 学习预期必填:未填预期时用不可关闭弹窗挡住,只能保存预期或走误操作结束 - 收敛提示:把服务端 systemMessage / autoConverged 原样告知用户 - 学习报告:结束会话时取 REPORT_DRAFT 草稿(AI 不可用由后端规则降级)作为编辑起点,可直接手写结束;任务页新增报告查看(三段 + 本会话碎片) - 悬浮窗只保留三件事:展示倒计时、记一条碎片、暂停/继续;结束、报告、预期等一律回到 App 页面 - 修复前台服务在进程被系统拉起时把「还不知道」当成「没有会话」而自杀(以 State.resolved 为准)
4.4 KiB
4.4 KiB
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 页面(含 ReportsScreen);不直接调 Retrofit,只调 SessionController / AppContainer |
必须遵守的约定
- 会话状态只在
SessionController里改。UI 和 Service 都不得自行维护会话副本,否则会与服务端口径分叉。 - 悬浮窗只做三件事:展示倒计时、记一条碎片、暂停/继续。结束会话、写报告、改预期、看历史一律在 App 页面内完成;不要往浮窗里加按钮或面板(它常驻在其他 App 之上,每多一个控件都是常态干扰)。
- 开始新任务前必须先处理未结束会话。
startOrContinue先查GET /study-sessions/active?excludeTaskNum=,有冲突就只设置State.conflict,由 UI 给出三个出口;不得绕过这一步直接开始,否则会同时存在两个进行中的会话。 - 学习预期不可为空。
State.expectationRequired为真时用不可关闭的弹窗挡住(只能填预期或误操作结束)。 - 前台服务停之前要确认“确实没有会话”。对账是异步的,
State.resolved为 false 时看到的空状态是“还不知道”,不能据此stopSelf()。 - 计时不得用 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) - 只使用学习会话相关端点(含报告与
POST /ai/tasks的REPORT_DRAFT),不碰复习端点(review前缀)
分支与发布
与 lpt-be / lpt-fe / lpt-ai 同规则:一个分支对一个环境(本仓库没有服务端部署,环境差异落在“默认 API 地址”上)。
| 分支 | 环境 | 默认 API 地址 |
|---|---|---|
dev |
开发 | https://lpt-dev.cat-shark.xyz/api |
master |
生产 | https://lpt.cat-shark.xyz/api |
- 两个分支的代码只允许差
ApiClient.DEFAULT_BASE_URL这一行(其余全部一致)。改这一行时必须确认自己在哪个分支上,改完只提本分支。 - 不要跨分支合并:
dev的功能要上生产时,只把常规代码改动同步过去,并保持 master 的默认地址不变。 - 构建在 Gitea 手动触发
.gitea/workflows/build.yml(dev/prod 二选一),不需要签本地环境:- 校验「分支 ↔ 环境」(从 dev 发 prod 直接被拒);
- 校验代码里的
DEFAULT_BASE_URL是否与本环境一致,不一致直接失败; - 容器内构建 APK(
ci/Dockerfile固定 JDK 17 / cmdline-tools / android-36),产物归档为 Actions artifact 并打印 sha256。
- APK 不入 Git(
.gitignore已忽略*.apk),分发走 Actions artifact。
提交规范
同 meta 仓库:简短中文,格式 类型: 简述,例如 feat: 新增悬浮窗碎片录入。