570 lines
52 KiB
Markdown
570 lines
52 KiB
Markdown
# LPT 实现优化清单
|
||
|
||
> 面向接手实现的代理。每条都是**功能性问题**(数据正确性、能力缺失、性能、安全),不含外观类改进。
|
||
> §3 列出已确认的**设计决策**:它们是有意为之的行为,不要当作缺陷修改。
|
||
|
||
## 0. 基线信息
|
||
|
||
| 项目 | 核对基线 |
|
||
|------|---------|
|
||
| 生成时间 | 2026-09-14 |
|
||
| 代码基线 | `lpt-be` c961157 / `lpt-fe` e66bdb7 / `lpt-ai` 200f088 / `lpt-infra` 0a23075 / `lpt-docs` 9cb9c75 |
|
||
| 核对方式 | 通读上述仓库源码 + 对线上 prod/dev 做只读探测(见附录 A) |
|
||
| 复核时间 | 2026-10-08 |
|
||
| 复核基线 | `lpt-be` 04d1f40 / `lpt-fe` 99a1b16 / `lpt-ai` bf56c2b / `lpt-infra` 34f2380 / `lpt-docs` a16cb4c |
|
||
| 复核结论 | 会话-01/02/03 已修(`lpt-be` `d8c8b76`);会话-04 仍无 `@Scheduled`;AI-03 已修(见条目)。基础设施变更:时区固定、LLM 切换为 DeepSeek(不影响本清单条目) |
|
||
|
||
若某仓库 HEAD 已明显晚于上表,先确认问题是否已被修复,再动手。
|
||
|
||
## 1. 协作约定
|
||
|
||
- 完成一项后:勾选对应条目并追加一行「完成于 <仓库> <commit>」;若条目语义已被改动,直接重写条目,不要追加开发日志。
|
||
- 涉及概念/设计语义的改动(如会话生命周期、有效时间定义):必须同步更新 `lpt-docs` 的概念或设计文档;`lpt-docs` 只写概念与设计,不写实现过程。
|
||
- 本文档不记载开发过程,只保留「待办 + 依据 + 验收标准」。禁止写入任何密钥、密码、Token 明文。
|
||
- 条目粒度按「一个代理能独立完成并自测」切分,跨仓库条目已标注涉及仓库。
|
||
- §3「设计决策」不是待办:改动前必须先与维护者确认,禁止当成缺陷直接「修复」。若某项决策需要调整,先在 §3 改写该条,再开对应实现条目。
|
||
- 编号规则:条目编号以中文领域前缀开头,形如 `复习-02`,前缀必须让人一眼看出改动落在哪块(会话、复习、报告、归属、导出、AI、数据、安全、运维、清理);设计决策用 `会话-决策01` 这种形式。编号不复用,旧编号作为别名保留在条目首次出现处(如 `复习-02(原 LPT-09)`)。
|
||
|
||
## 2. 改动计划总览(按模块)
|
||
|
||
按模块给设计和决策。`状态` 含义:**可直接实施**(方案已定,不需维护者再拍板)/**待决策**(结论落地前不要开工)/**依赖其他条目**。
|
||
|
||
| 模块 | 条目 | 优先级 | 状态 | 需要先定什么 |
|
||
|------|------|--------|------|--------------|
|
||
| 学习会话生命周期 | 会话-01 遗忘检测路径不统一 | P0 | 已完成 | — |
|
||
| | 会话-02 `isOverTime()` 误报超时 | P0 | 已完成 | — |
|
||
| | 会话-03 结束会话不幂等 | P0 | 已完成 | — |
|
||
| | 会话-04 悬挂会话无收敛 | P0 | 已完成 | — |
|
||
| | 会话-05 活跃会话拦截无出路 | P1 | 已完成 | — |
|
||
| 内容归属与报告 | 归属-01 内容归属与待归类 | 待实施 | 设计已确认 | 实现级取舍:碎片表如何承载归属、报告字段拆分、归类交互落点 |
|
||
| | 报告-01 报告与碎片不可修订 | P1 | 待设计 | 与归属-01 同批改报告结构;修订与删除的边界(软删除、历史报告标记) |
|
||
| 标记与元信息 | 标记-01 统一标记存储 | P1 | 待决策 | 可挂对象;标记名受控方式;标记值类型;按标记检索;标记名治理与可见性 |
|
||
| 复习 | 复习-01 复习回路补全 | 待确认 | 待决策(6 项) | Feed 是否含报告;反馈动作形态;覆盖率口径;待归类呈现;遗漏项语义;排序可配置性 |
|
||
| | 复习-02 Feed 只读无反馈动作 | P1 | 依赖复习-01 | 反馈动作形态(复习-01 第 2 项) |
|
||
| | 复习-03 Feed 随机取样 | P3 | 待决策 | id 区间随机 / 候选池 / 时间窗口随机 |
|
||
| | 复习-04 覆盖率查询拉全量 | P3 | 依赖复习-01 | 覆盖率口径(复习-01 第 3 项) |
|
||
| | 复习-05 Feed 返回全文 | P3 | 依赖复习-01 | 条目单位与摘要口径(复习-01 第 1 项) |
|
||
| | 复习-06 学习引导 | P1 | 已确认待实施 | 依赖 AI-02 / AI-03,以及标记-01 的存储设计 |
|
||
| | 复习-07 复习耗时统计 | P2 | 已完成 | — |
|
||
| AI 链路 | AI-01 事务内同步等 AI | P2 | 已完成 | — |
|
||
| | AI-02 全链路同步阻塞 | P2 | 已完成 | — |
|
||
| | AI-03 单 worker 串行无重试 | P2 | 已完成 | — |
|
||
| | AI-04 防并发锁是 JVM 内存锁 | P2 | 已完成 | — |
|
||
| 数据与检索 | 数据-01 业务主表缺索引 | P3 | 已完成 | — |
|
||
| | 数据-02 统计聚合在内存 | P3 | 已完成 | — |
|
||
| | 数据-03 编号撞号风险 | P3 | 已完成 | — |
|
||
| 导出 | 导出-01 无数据导出 | P1 | 已完成 | — |
|
||
| 安全 | 安全-01 数据库凭证明文 | P4 | 待决策 + 需你执行 | 是否轮换凭证;历史值清理还是视为已泄露 |
|
||
| | 安全-02 Actuator 鉴权边界 | P4 | 待决策 | 白名单 / 独立端口 + 网络策略(涉 `lpt-infra`) |
|
||
| | 安全-03 AI 入站无防护 | P4 | 可直接实施 | 内部鉴权方式(共享 token / 仅网络策略) |
|
||
| | 安全-04 生产打印全部 SQL | P4 | 已完成 | — |
|
||
| 运维与清理 | 运维-01 备份只在同一 PVC | P4 | 待决策 | 异地 / 对象存储目标选型,需你提供目标 |
|
||
| | 清理-01 死代码与死表 | P4 | 待决策 | 删除 / 保留并在 `lpt-docs` 说明定位 |
|
||
| 学习录音 | 录音-01 采集后端接口与 OBS 后端 | P1 | 已实现·已暂停 | 先定采集方案:OBS / 自研原生 |
|
||
| | 录音-02 控制通道与会话绑定 | P1 | 已暂停 | 轮询 lpt-be / 直连本机端口(建议轮询) |
|
||
| | 录音-03 音频落盘与对象存储 | P1 | 已暂停 | 对象存储选型(MinIO / 云对象存储) |
|
||
| | 录音-04 转写链路(provider 可配置) | P2 | 已暂停 | AI-02 / AI-03 |
|
||
| | 录音-05 录制可见性与隐私边界 | P1 | 已暂停 | 指示形态、他人语音口径 |
|
||
| | 录音-06 浏览器侧接入 | P1 | 已暂停 | 油猴脚本 / 直接进 lpt-fe |
|
||
|
||
> **学习录音模块已整体暂停**(2026‑10‑08):录音-01 的实现已完成并实测通过,但采到系统音频的两条路线(依赖 OBS / 自研原生)还没定,其余条目全部挂起。详见 §12。
|
||
|
||
已确认的设计决策(不是待办):会话-决策01 少于 10 分钟不计入总时长;会话-决策02 遗忘判定阈值 50 分钟;录音-决策01 录音由本机伴随程序负责;录音-决策02 只采系统输出不采麦克风。
|
||
|
||
---
|
||
|
||
## 3. 已确认的设计决策(不是待办,不要当缺陷改)
|
||
|
||
### 会话-决策01(原 D-01)少于 10 分钟的有效学习时间不计入总学习时间
|
||
|
||
- **依据**:`StudySessionsEntity.endedStudySession()`:`effectiveTime < 10 * 60 → setEffectiveTime(0); setEffectivenessRatio(0)`;常量 `MIN_EFFECTIVE_TIME_SECONDS`。
|
||
- **决策**:25 分钟的番茄钟已经足够碎片化,更短的碎片视为噪声,刻意不记录。
|
||
- **注意**:这与 `lpt-docs/design/principles.md` 中「量化,但不评判」存在张力,但已由维护者确认为有意取舍。除非维护者主动改变口径,否则不要改成「保留真实值 + 打标记」。
|
||
- **来源**:原 LPT-02 条目,2026-09-14 由维护者澄清后重新归类。
|
||
|
||
### 会话-决策02(原 D-02)遗忘判定阈值为 50 分钟(2 × `WORK_DURATION`)
|
||
|
||
- **依据**:`StudySessionsEntity.isOverTime()`:`minutes >= WORK_DURATION * 2`;触发时按 `lastStartTime + 25 分钟` 截断有效时间。
|
||
- **决策**:25~50 分钟区间默认用户仍在屏幕前(番茄钟已提醒但可能正在收尾),不做截断;超过 50 分钟才判定为「忘了点暂停/结束」。
|
||
- **注意**:不要把这个阈值改成等于番茄钟长度(25 分钟);阈值存在的意义是区分「在学」与「忘了关」。真正要修的是执行路径不统一,见 会话-01。
|
||
|
||
### 录音-决策01 录音由运行在本机的伴随程序负责,浏览器不采集也不传输音频
|
||
|
||
- **依据**:浏览器无法在 Linux/macOS 采集系统音频(Chrome/Edge 仅在 Windows/ChromeOS 共享整个屏幕时可采系统声,Linux/macOS 只能采标签页音频,Firefox/Safari 不支持音频捕获);Chromium `media/audio/pulse/audio_manager_pulse.cc` 明确排除 monitor(loopback)设备。此外公网页面直连本机端口在 Chrome 142+ 受 Local Network Access 权限约束(Chrome 152 实测:公网页面向 `127.0.0.1` 的 fetch 被拒,`navigator.permissions.query({name:'local-network-access'})` 返回 `prompt`)。
|
||
- **决策**:采集、编码、上传全部由运行在用户本机的伴随程序完成;网页只负责发起、结束与展示。网页关闭或崩溃不影响录音。
|
||
- **注意**:不要把「浏览器直接采系统声」当作可用的退化路径,也不要默认用「本地端口直连」做控制通道(取舍见 录音-02)。
|
||
|
||
### 录音-决策02 只采系统输出,不采麦克风
|
||
|
||
- **依据**:录音要回答的是「用户听到了什么」,而不是「房间里发生了什么」。
|
||
- **决策**:只采系统混音,不采麦克风,也不用麦克风作为兜底来源。
|
||
- **注意**:这条同时收敛隐私范围与转写噪音,不要为提高「完整性」而混入麦克风。
|
||
|
||
### 录音-决策03 采集层只用 OBS,不自研原生采集(**已暂停,待重评**)
|
||
|
||
> 2026‑10‑08:本决策已回退为「待重评」。录音-01 实现完成后暴露了两个与决策依据相冲的事实:① OBS 无法直接录出纯音频(详见 §12),必须再引入 ffmpeg 抽音轨;② OBS 安装体积与跨平台配置差异成本高于先前估计。重启本模块前重新拍板,参见 §12「路线分叉」。
|
||
|
||
- **依据(当时)**:OBS 三平台都原生支持系统音频采集(Windows WASAPI loopback、Linux PulseAudio/PipeWire monitor、macOS 13+ ScreenCaptureKit),官方发布覆盖 Windows x64/arm64、macOS Apple/Intel、Ubuntu `.deb`;自研需分别实现三套原生采集(尤其 macOS SCK),成本远高于引入 OBS。
|
||
- **决策(暂停)**:采集层只做 OBS 后端,不保留原生后端的分支;OBS 的发布与升级由用户自行负责。
|
||
- **注意**:不要因为「不想让用户装 OBS」而临时增加虚拟声卡方案(Linux `module-remap-source` + 常驻 watcher),该路线已实测可行但被本决策取代。
|
||
|
||
---
|
||
|
||
## 4. P0 数据正确性
|
||
|
||
### 会话-01(原 LPT-01)遗忘检测只在「重新进入学习页面」这一条路径上执行
|
||
|
||
- [x] 已完成
|
||
- **完成于** `lpt-be` `d8c8b76`
|
||
- **涉及仓库**:`lpt-be`(可选 `lpt-fe` 心跳)
|
||
- **前提**:系统已具备遗忘检测(见 会话-决策02),问题不在于缺少机制,而在于它只挂在一条路径上。
|
||
- **依据**:`pausedStudySession(lastStartTime.plusMinutes(WORK_DURATION))` 只在 `StudySessionsServiceImpl.startOrContinueStudySession()` 中出现(全仓唯一)。而 `pauseStudySession()` 与 `StudySessionsEntity.endedStudySession()`(内部 `pausedStudySession(now)`)都是直接 `effective += now - lastStartTime`,没有遗忘检测。
|
||
- **影响**:页面不刷新、停留在前台时,pause / ended 两条路径依然可达。典型场景:番茄钟响起后用户离开,3 小时后回到同一个页面点「休息」(`StartTask.vue` 的 `restTimer()` → `stopTimer()` → pause 接口),这 3 小时被全额计入有效学习时间。是否被截断取决于用户有没有刷新过页面。
|
||
- **理由**:这恰好落在 会话-决策02 想覆盖的「忘了点暂停/结束」场景里,属于检测点遗漏,会让同一行为产生两种统计结果,直接损害时间数据的可信度。
|
||
- **建议**:抽出统一的结算时间函数(如 `resolveSettlementTime(session)`:`now - lastStartTime > 50min` 时返回 `lastStartTime + 25min`,否则返回 `now`),在 pause / ended / 定时收敛三条路径共用;番茄钟长度与两类阈值统一配置化。
|
||
- **验收**:构造「ONGOING 且 `last_start_time` 为 3 小时前」的会话,分别调用 pause 与 ended 接口,断言 `effective_time` 被截断到 25 分钟;`StudySessionsEntityTest` 同步补用例。
|
||
|
||
### 会话-02(原 LPT-03)`isOverTime()` 误报「超时 25 分钟」
|
||
|
||
- [x] 已完成
|
||
- **完成于** `lpt-be` `d8c8b76`
|
||
- **涉及仓库**:`lpt-be`
|
||
- **依据**:`StudySessionsEntity.isOverTime()` 只比较 `last_start_time` 与当前时间,不看 `end_time` 与 `session_state`。`startOrContinueStudySession()` 用同一判定既驱动截断又驱动 `systemMessage`。
|
||
- **影响**:已暂停很久的会话(时间早已在暂停时正确入账),每次回到页面都会弹「上段学习任务已经超时 25 分钟,将仅计算为 25 分钟的有效学习时间」。
|
||
- **建议**:拆分「是否需要截断」与「是否需要提示」两个判定,并纳入 `end_time` / `state`。
|
||
- **验收**:对 `state=PAUSED` 且 `end_time` 已存在的会话,接口不返回 `systemMessage`。
|
||
|
||
### 会话-03(原 LPT-04)结束会话不幂等,会产生重复学习报告
|
||
|
||
- [x] 已完成
|
||
- **完成于** `lpt-be` `d8c8b76`
|
||
- **涉及仓库**:`lpt-be`
|
||
- **依据**:`StudySessionsEntity.endedStudySession()` 在 `state = ENDED` 时只 `log.warn` 并原样返回;`StudySessionsServiceImpl.endedStudySession()` 随后无条件 `studyReportsMapper.insert(...)`。
|
||
- **影响**:重复点击、网络重试即可写入多条报告 → 复习 Feed 重复项、标准导图重复节点、统计重复计数。
|
||
- **建议**:`state != ENDED` 才允许写报告,否则幂等返回;接口层可加幂等键。
|
||
- **验收**:对同一 `sessionNum` 连续调用两次结束接口,第二次不新增报告(断言报告条数)。
|
||
|
||
### 会话-04(原 LPT-05)缺少服务端兜底:悬挂会话与超长会话无人收敛
|
||
|
||
- [x] 已完成
|
||
- **完成于** `lpt-be` `db55218`
|
||
- **涉及仓库**:`lpt-be`
|
||
- **已实施**:
|
||
1. 硬兜底阈值 2 小时:进行中且最后一段超过该时长时强制收敛为暂停,按遗忘规则(会话-决策02)截断到 `last_start_time + 25 分钟`,并落 `auto_converged` 标记供前端提示「疑似忘记结束」。
|
||
2. 收敛方式采用**并用**:惰性收敛挂在「活跃会话」与「任务未结束会话」两个读取入口;定时扫描(默认 10 分钟)兜底,保证用户不回来时统计也会收敛、悬挂会话不再阻塞新任务。
|
||
3. 四类阈值(25 分钟番茄钟、50 分钟遗忘判定、2 小时硬兜底、10 分钟有效时间下限)统一收到 `lpt.study-time.*` 配置,实体入口由统一的时间口径对象承载;非法组合(兜底阈值小于遗忘阈值等)在启动时直接失败。
|
||
- **实现约束**:收敛写入一律使用「状态仍为 ONGOING」的条件更新,惰性收敛与定时扫描并发时只结算一次;定时扫描跨租户扫描(系统级后台任务,无登录态),但不影响读取路径的租户隔离。
|
||
- **测试环境**:定时任务用 `lpt.study-time.scan-enabled: false` 在测试配置里关闭,避免调度任务与用例自造的悬挂会话互相干扰(落库集成测试直接调用扫描方法)。
|
||
- **验收**:制造一个 3 小时前的 ONGOING 会话,在不访问该任务页面的前提下,惰性/定时收敛后状态为 PAUSED 且有效时间已按 会话-决策02 截断;正常进行中的会话不受影响。✅ 已用落库集成测试覆盖(惰性、定时、不会误伤正常会话、不跨租户、重复扫描不重复结算)
|
||
|
||
---
|
||
|
||
## 5. P1 会挡路的功能缺口与待补能力
|
||
|
||
### 会话-05(原 LPT-07)活跃会话拦截没有出路,会永久堵住新任务
|
||
|
||
- [x] 已完成
|
||
- **完成于** `lpt-fe` `25fbc67`(+ `lpt-docs` `804d53a`)
|
||
- **涉及仓库**:`lpt-fe`(+ `lpt-be` 需提供结束/放弃能力)
|
||
- **已实施**:拦截入口补两个新出口:「结束它并开始新任务」(复用 `ended` 接口,旧会话会生成一份未填写总结的报告)与「放弃该会话」(复用 `abort`,仅限未产生学习残片的会话,后端拒绝时原样转达原因);两者成功后继续开始当前任务,一次交互内解除阻塞。另对 会话-04 自动收敛过的会话在弹窗与任务页给出「疑似乎忘记结束」提示。
|
||
- **依据(修正)**:守卫实际位于 `StartTask.vue` 的 `loadTaskSession()`(清单原文写的是 `Study.vue` 的 `startTask()`,与实际代码不符,已按实际位置改);原行为只有「前往继续 / 取消」,取消后只弹一条提示,用户无处可去。
|
||
- **影响**:一个搁置数月的暂停会话会阻止开始任何新任务(所有任务入口都撞同一个守卫),用户必须先找回那个任务手动结束。
|
||
- **验收**:存在陈旧活跃会话时,用户可在一次交互内开始新任务。✅ 已用交互式集成测试覆盖五个出口分支(前往继续 / 结束并开始 / 放弃 / 放弃失败 / 取消)
|
||
|
||
### 报告-01(原 LPT-08)学习报告与知识碎片不可修订
|
||
|
||
- [ ] 未完成
|
||
- **涉及仓库**:`lpt-be`(+ `lpt-fe`)
|
||
- **依据**:端点清单——`StudyReportFragments` 只有 `POST` / `PUT /{id}` / `GET`;`StudyReports` 只有创建与查询,**没有 PUT、没有 DELETE**;碎片也没有 DELETE。
|
||
- **影响**:写错不能改,也不能删除,只能改数据库。
|
||
- **理由**:知识碎片是学习报告、复习 Feed、标准导图的共同原料,记录成本上升会直接降低记录率,连锁削弱整个复习闭环。
|
||
- **建议**:报告支持编辑与删除;碎片支持删除;删除需考虑对标准导图、回忆记录、统计的影响(软删除 + 标记重建导图)。
|
||
- **验收**:报告/碎片可编辑与删除;删除后 Feed 与统计不再包含该条。
|
||
|
||
### 复习-02(原 LPT-09)复习 Feed 只读,没有反馈动作
|
||
|
||
- [ ] 未完成
|
||
- **涉及仓库**:`lpt-be`(+ `lpt-fe`)
|
||
- **依据**:Feed 仅提供列表/详情/回忆对比;`ReviewServiceImpl.reviewNeedWeight()` 的智能权重只有两个信号——时间衰减(`createdTime`)与任务最近一次回忆覆盖率。
|
||
- **影响**:无法表达「这条其实很熟」与「这条完全没印象」;权重长期只有两个偏置,也没有「已复习」状态,同一批内容会反复出现。
|
||
- **建议**:加轻量动作(稍后再看 / 已掌握),把「上次复习时间」变成第三个权重信号;保持既有「无压力、偶遇式」设计,不引入强制清单。
|
||
- **依赖**:动作形态需先确认 复习-01(§11)中的反馈动作取舍。
|
||
- **验收**:用户反馈动作可落库并在下一次 Feed 排序中生效。
|
||
|
||
### 导出-01(原 LPT-10)无数据导出
|
||
|
||
- [x] 已完成
|
||
- **完成于** `lpt-be` `faaaa13`、`lpt-fe` `87e4cea`
|
||
- **涉及仓库**:`lpt-be`(+ `lpt-fe`)
|
||
- **已实施**:两个只读接口 `GET /export/task/{taskNum}` 与 `GET /export/range?startDate&endDate`,均支持 `format=markdown|json`(默认 markdown);内容随统一响应体返回(`ExportResult{fileName, contentType, content}`),前端落成文件下载,不引入新的响应约定。两种格式共用同一个导出模型,保证内容一致。
|
||
- **范围口径**:按时间范围导出时,报告与碎片先按时间倒序合并再按内容归属分组,保证同一任务下两种内容交错时顺序仍然正确;起止日期均为闭区间,省略即不限制(默认方案)。
|
||
- **附带效果**:导出内容包含任务维度的统计,顺带覆盖了 复习-07 新增的复习耗时。
|
||
- **理由**:`lpt-docs` 明确系统定位是「辅助学习的工具」,工具型系统应保证数据可携带;同时可缓解备份粒度过粗的问题(见 运维-01)。
|
||
- **验收**:导出内容可独立阅读,包含报告/碎片原文与时间信息。✅ 单测覆盖两种格式、范围分组顺序、空范围、非法格式/起止日期倒置;前端集成测试覆盖导出弹窗主流程与未选时间段的拦截
|
||
|
||
### 复习-06 学习引导
|
||
|
||
- [ ] 未完成
|
||
- **涉及仓库**:`lpt-be` + `lpt-fe` + `lpt-ai`(概念文档已写入 `lpt-docs`)
|
||
- **依据**:复习只有接触(Feed)与结构提取(回忆对比),概念边界上的误解(例如把“参数量”当成能决定磁盘占用)不会被覆盖率捕捉。
|
||
- **已定**:开放式问题引导(例:“1B 参数量的 LLM 模型,会占用多少磁盘空间?”),无标准答案、不判分;AI 在对话中纠正回答里隐含的边界问题;对话不设轮数上限;产出是知识碎片,由用户确认后记录;复用碎片全链路(归属、待归类、导图取材、Feed 回收);碎片默认归属“被引导概念所属的学习任务”,并带「来自学习引导」标记(仅标记,不做特殊处理);记录上下文为复习行为;耗时计入复习-07;不进入学习报告;入口为 Feed 卡片与导图节点;不提供降级形态,AI 不可用时该功能整体不可用。
|
||
- **前置条件**:依赖 AI-02 / AI-03(多轮对话不能建在当前同步阻塞的链路上);「来自学习引导」标记的存储依赖标记-01。
|
||
- **验收**:一次学习引导结束后,用户确认可生成一条归属正确、带来源标记的碎片,并随导图增量更新出现;不确认则不产生任何数据;AI 不可用时入口不可用,且不影响复习其他部分。
|
||
|
||
### 复习-07 复习耗时统计
|
||
|
||
- [x] 已完成
|
||
- **完成于** `lpt-be` `3b33cd8`、`67c8711`,`lpt-fe` `21af81f`
|
||
- **涉及仓库**:`lpt-be` + `lpt-fe`
|
||
- **已实施**:回忆记录落 `review_duration_seconds`,`recall` 接口接收前端计时并由服务端统一结算,复习总览按任务聚合后与学习时长并列。
|
||
- **遗留**:学习引导尚未实现(复习-06),其耗时复用同一个 `review_duration_seconds` 字段,不需要再改表结构。
|
||
- **依据**:复习总览目前只展示来自会话的“累计有效学习时长”(`ReviewTaskStats.effectiveTime`),复习行为本身没有任何计时,投入不可见。
|
||
- **已定口径**:只对回忆对比与学习引导计时,滚动浏览不计时;超过 5 分钟无交互则截断到上一次交互时间(复习没有暂停动作);命名“复习耗时”,不叫有效复习时间、不套用 10 分钟最小阈值;复习总览按任务与学习时长并列展示;不做跨任务汇总大数字、不设目标、不参与复习排序。
|
||
- **建议**:把复习行为作为时间记录的主体(回忆对比已有记录实体,学习引导新增),耗时写在该行为上;前端补空闲检测并上报交互时间。
|
||
- **验收**:完成一次回忆对比后,复习总览该任务行出现复习耗时且与学习时长分列;页面挂机超过 5 分钟不再继续累计。
|
||
|
||
---
|
||
|
||
## 6. P2 AI 链路(收益成本比最高)
|
||
|
||
### AI-01(原 LPT-11)`recallCompare` 在事务中同步等待 AI,长事务占用数据库连接
|
||
|
||
- [ ] 未完成
|
||
- **涉及仓库**:`lpt-be`
|
||
- **依据**:`StandardMindMapServiceImpl.recallCompare()` 标注 `@Transactional`,内部同步调用 `AiServiceClient.compareRecall()`(轮询上限 `lpt.ai-service.timeout-seconds: 600`)。Hikari 连接池未显式配置,为默认 10。
|
||
- **影响**:并发几个回忆对比即可耗尽连接池,导致全站请求阻塞。**这是建议最先修的一条:把 AI 调用移出事务即可,改动小、风险低。**
|
||
- **建议**:先做纯读的对比计算(事务外),再开短事务写入回忆记录;或引入任务表 + 异步回写(与 AI-02 一起做)。
|
||
- **验收**:AI 调用期间不持有数据库连接(可通过连接池监控或长事务日志证明)。
|
||
|
||
### AI-02(原 LPT-12)AI 全链路同步阻塞,用户需干等最长 10 分钟
|
||
|
||
- [x] 已完成
|
||
- **完成于** `lpt-be` `cf380c5`、`lpt-fe` `e52682c`(+ `lpt-docs` `39efbb6`)
|
||
- **涉及仓库**:`lpt-be` + `lpt-fe` + `lpt-ai`
|
||
- **已实施**:新增 `ai_tasks` 表与统一 AI 任务接口(`POST /ai/tasks`、`GET /ai/tasks/{taskNum}`、`GET /ai/tasks/latest`):
|
||
- 提交秒级返回任务标识,结果写在 `result_payload`,按标识可重复获取;
|
||
- 三类能力(回忆对比、标准导图生成、报告草稿)全部改为任务;
|
||
- 读取接口不再产生副作用:`GET /review/standard-mind-map/{taskNum}` 不再自动生成(缺失时返回 null),`GET /study-sessions/{sessionNum}/report-draft` 已删除;
|
||
- 执行器在 `ai-task-*` 线程池里执行,提交后立即投递,`@Scheduled` 兜底扫描接手投递失败与进程重启;卡在 RUNNING 超过阈值的任务会被回收重试。
|
||
- **顺带修掉的一个真实缺陷**:后台执行线程没有 Web 上下文,而租户拦截器与公共字段自动填充都取 `StpUtil`,会直接抛 `NotWebContextException`。已引入 `TenantContext` 让后台线程显式声明执行身份(以任务所属用户执行),请求线程行为不变。
|
||
- **遗留**:`lpt-ai` 侧无需改动(AI-03 已提供任务队列);`lpt-be` 的 `AiServiceClient` 仍是「提交到 lpt-ai 后轮询」的同步封装,但已被调用在执行线程内,不再阻塞请求。
|
||
- **依据**:`lpt-fe/src/utils/request.ts` 的 `timeout: 600000`;`lpt-be` 的 `AiServiceClient.submitAndWait()` 内部轮询最长 600s;`GET /study-sessions/{sessionNum}/report-draft` 这类 GET 也会触发 10 分钟阻塞并计费。
|
||
- **验收**:提交 AI 任务后接口在秒级返回任务标识;任务结果可重复获取,无需重试即可拿到。✅ 落库集成测试覆盖:提交不在请求线程里调 AI、按标识重复查询结果一致、失败任务可查到原因、任务受租户隔离
|
||
|
||
### AI-03(原 LPT-13)`lpt-ai` 单 worker 串行且无重试
|
||
|
||
- [x] 已完成
|
||
- **涉及仓库**:`lpt-ai`(+ `lpt-be` 超时策略)
|
||
- **完成于** `lpt-ai` `bf56c2b`
|
||
- **依据**:`task-queue.ts` 只有一个 `processing` 标志顺序处理;失败直接置 `failed`,无退避重试;任务记录 `TTL_MS = 1 小时`。
|
||
- **影响**:N 个并发请求时第 N 个需等待 N × LLM 耗时,超过 `lpt-be` 的 600s 超时后表现为「AI 实际成功、客户端已超时」,结果既不落库也不告知,用户重复点击导致重复计费。LLM 的 429/5xx 抖动被当成永久失败。
|
||
- **已实施**:
|
||
- **Worker 池**:并发度 `LPT_AI_CONCURRENCY`(默认 2),队列改为基于 id 的 FIFO。
|
||
- **退避重试**:新增 `llm/retry.ts`,仅重试 408/429/5xx 与超时;4xx 客户端错误与「API Key 未配置」不重试;服务端 `Retry-After` 优先于自算退避。为此让 `LlmError` 保留上游真实状态码(原先一律记为 502,无法区分 429 与 400)。
|
||
- **幂等与结果复用**:以 `type + params` 的稳定哈希为幂等键(支持显式 `idempotencyKey`);进行中的相同请求合并为同一任务,已完成结果在 `LPT_AI_RESULT_CACHE_MS` 窗口内复用;**失败任务不复用**,保留用户重试机会;请求体 `force: true` 可强制重新生成。
|
||
- 队列改为可注入依赖的 `TaskQueue` 类,测试覆盖并发、重试、复用与清理。
|
||
- **不得改动的契约**:`/ai/tasks` 必须固定返回 201(Java 端 `AiServiceClient` 把非 201 视为提交失败),复用信息放在响应体的 `reused` / `status` 字段。
|
||
- **验收**:并发 N 个任务时耗时不再线性增长;可重试错误不产生失败结论。✅ 已用假 LLM 服务端到端验证:4 个任务× 300 ms 共用 431 ms(串行需 1200 ms+);前两次 429 后仍为 `done`;相同请求只调用 LLM 1 次。
|
||
- **遗留**:`lpt-ai` 的部署(`lpt-infra` configmap)未设队列相关环境变量,目前走默认值;需要调优时再补。
|
||
|
||
### AI-04(原 LPT-14)防并发锁是 JVM 内存锁
|
||
|
||
- [x] 已完成
|
||
- **完成于** `lpt-be` `cf380c5`
|
||
- **涉及仓库**:`lpt-be`
|
||
- **已实施**:删除 `StandardMindMapServiceImpl` 里的 `ConcurrentHashMap<String, AtomicBoolean> generatingTasks`,改为基于 `ai_tasks` 的进行中判定:同一用户 + 同一类型 + 同一目标已有 `PENDING`/`RUNNING` 任务时复用该任务,因此不存在「多副本锁失效」。执行侧再用「状态仍为 PENDING」的条件更新抢占,多副本并发也不会重复执行。
|
||
- **对外语义已明确**:提交接口返回的是**任务状态**(`AiTaskResponse`),不再是可能为 null 的实体;前端据此展示「正在生成」。
|
||
- **验收**:多副本场景下同一任务不会并发生成;生成中重复请求返回明确的进行中状态。✅ 单测覆盖「同一目标重复提交返回同一任务标识」,集成测试覆盖重复提交复用
|
||
|
||
---
|
||
|
||
## 7. P3 检索与数据增长
|
||
|
||
### 数据-01(原 LPT-15)业务主表缺索引,而每条查询都被追加租户条件
|
||
|
||
- [x] 已完成
|
||
- **完成于** `lpt-be` `e506c4d`(补了 created_by 打头的复合索引;EXPLAIN 需在 MySQL 上核对)
|
||
- **涉及仓库**:`lpt-be`
|
||
- **依据**:`V20250629_1__LPT_dataBase_init.sql` 中 `study_sessions` / `study_reports` / `study_report_fragments` / `tasks` 均只有主键;`MybatisPlusConfig` 的租户拦截器给每条 SELECT/UPDATE/DELETE 追加 `created_by = ?`;全仓仅少数 review 表有索引。
|
||
- **影响**:所有高频查询(Feed、统计、按会话取碎片/报告)都是全表扫描 + 过滤,随使用量线性劣化。
|
||
- **建议**:按实际查询补复合索引,例如 `(created_by, task_num, session_state)`、`(created_by, session_num, created_time)`、`(created_by, created_time)`、`(created_by, task_num, calculated_priority)`。
|
||
- **验收**:`EXPLAIN` 显示关键查询走索引而非全表扫描。
|
||
|
||
### 复习-03(原 LPT-16)Feed 使用 `ORDER BY RAND()`
|
||
|
||
- [ ] 未完成
|
||
- **涉及仓库**:`lpt-be`
|
||
- **依据**:`ReviewServiceImpl.getReviewFeed()` 与 `getSmartFeed()` 对报告表和碎片表分别使用 `ORDER BY RAND() LIMIT ...`,smart 模式抽样量为 `limit × 5`(上限 500)。
|
||
- **影响**:MySQL 上属全表随机排序,单次请求两次全表随机。
|
||
- **建议**:改为 id 区间随机、预生成候选池或「按时间窗口随机 + 按需补充」。
|
||
- **验收**:Feed 接口不产生全表随机排序(`EXPLAIN` 可验证)。
|
||
|
||
### 复习-04(原 LPT-17)取「每任务最近一次回忆覆盖率」时拉取全部回忆记录
|
||
|
||
- [ ] 未完成
|
||
- **涉及仓库**:`lpt-be`
|
||
- **依据**:`ReviewServiceImpl.latestRecallRatioByTask()` 按 `taskNum in (...)` 查询全部记录(含体积较大的 `compare_result` JSON)后只在内存里取每条任务的第一条。
|
||
- **影响**:数据传输量与内存占用随复习次数线性增长。
|
||
- **建议**:改为分组取最新(子查询/`MAX(created_time)`),或把最近覆盖率冗余到任务表/导图表。
|
||
- **验收**:该查询返回行数等于任务数而非回忆记录数。
|
||
|
||
### 数据-02(原 LPT-18)统计聚合在内存中完成且无时间范围
|
||
|
||
- [ ] 未完成
|
||
- **涉及仓库**:`lpt-be`
|
||
- **依据**:`ReviewServiceImpl.fillReviewTaskStats()` 加载**所有任务的全部会话**到内存再聚合,无时间窗、无分页。
|
||
- **影响**:使用越久越慢,且会随会话数增长而内存膨胀。
|
||
- **建议**:下推为 SQL 聚合(含今日/本周条件),必要时物化统计表。
|
||
- **验收**:统计接口加载的会话行数与任务数同阶,不随历史会话数线性增长。
|
||
|
||
### 复习-05(原 LPT-19)Feed 返回全文
|
||
|
||
- [ ] 未完成
|
||
- **涉及仓库**:`lpt-be` + `lpt-fe`
|
||
- **依据**:`ReviewFeedItem.content` 直接返回报告/碎片全文,`getReviewFeed(100, "smart")` 一次最多 100 条;前端只展示前几十个字(详情页才需要全文)。
|
||
- **建议**:Feed 返回摘要字段(含长度标记),详情接口按需拉全文。
|
||
- **验收**:Feed 响应体积显著下降且展示行为不变。
|
||
|
||
### 数据-03(原 LPT-20)编号生成有撞号风险且无唯一约束
|
||
|
||
- [x] 已完成
|
||
- **完成于** `lpt-be` `3cc3be1`
|
||
- **涉及仓库**:`lpt-be`
|
||
- **已实施**:编码后缀由「6 位毫秒片段」改为「6 位毫秒片段 + 6 位随机数」(`SecureRandom`),保留 `PREFIX-yyyyMMdd-<12位>` 的可读形态,不破坏已有编号与前端引用;同时补上唯一约束 `(created_by, task_num)` 与 `(created_by, session_num)`(迁移 `V20261009_3`),作为最终防线。
|
||
- **证据**:此风险不是推测——为 复习-07 写落库集成测试时,同毫秒两次 `generateNum` 真的产出了完全相同的 `task_num`,导致两个任务的数据被并到同一条聚合。
|
||
- **注意**:唯一约束迁移在历史数据已有重复编号时会直接失败——这是有意为之,需要人工确认后再处理,而不是静默跳过约束。
|
||
- **验收**:并发创建 N 个任务/会话无重复编号,数据库层有唯一约束保护。✅ 单测覆盖 300 次连续生成无重复
|
||
|
||
---
|
||
|
||
## 8. P4 安全与运维
|
||
|
||
### 安全-01(原 LPT-21)数据库凭证明文入库
|
||
|
||
- [ ] 未完成
|
||
- **涉及仓库**:`lpt-be` + `lpt-infra`
|
||
- **依据**:`application-prod.yml`、`application-dev.yml`、`application-local.yml` 均包含明文数据库账号密码(三个环境同一份)。`lpt-infra` 已通过 `lpt-secrets` 注入 `SPRING_DATASOURCE_PASSWORD` 覆盖,但配置文件仍在 Git 历史中。
|
||
- **建议**:轮换凭证 → 配置文件只保留占位符/环境变量引用 → 清理历史(或至少视为已泄露处理)。
|
||
- **验收**:仓库中不再出现明文凭证;本地开发通过环境变量或本地未跟踪配置提供。
|
||
- **注意**:**不要把任何密码值复制进本文档。**
|
||
|
||
### 安全-02(原 LPT-22)Actuator 端点鉴权边界未固定
|
||
|
||
- [ ] 未完成
|
||
- **涉及仓库**:`lpt-be`
|
||
- **依据**:线上只读探测确认 `/api/actuator/health`、`/api/actuator/info` 未登录返回 200,而 `/api/actuator/env` 与业务接口返回 401(已注册的 actuator 端点不受 `SaInterceptor` 约束)。
|
||
- **影响**:当前探针正常,但一旦放开 metrics/prometheus 等端点,会连带公开。
|
||
- **建议**:显式固定暴露白名单,或把管理端点放到独立端口并加网络策略。
|
||
- **验收**:未鉴权可访问的端点清单与预期完全一致。
|
||
|
||
### 安全-03(原 LPT-23)`lpt-ai` 缺少入站防护(SSRF 与滥用)
|
||
|
||
- [ ] 未完成
|
||
- **涉及仓库**:`lpt-ai`
|
||
- **依据**:`POST /fetch-title` 由服务端抓取用户可控 URL(可探测内网/云元数据地址);`/ai/tasks` 与 `/admin` 无鉴权、无速率限制、无请求体上限;`admin/store.ts` 把完整 prompt 与学习内容明文写入 `data/logs.json`。
|
||
- **建议**:抓取改为白名单/内网地址黑名单 + 协议与重定向校验;入站加鉴权与限流;`/admin` 加访问控制;日志中学习内容按需脱敏或缩短保留期。
|
||
- **验收**:`/fetch-title` 无法访问内网与元数据地址;未授权请求无法提交 AI 任务。
|
||
|
||
### 安全-04(原 LPT-24)生产环境打印全部 SQL
|
||
|
||
- [x] 已完成
|
||
- **完成于** `lpt-be` `af13bd5`
|
||
- **涉及仓库**:`lpt-be`
|
||
- **依据**:`application.yml` 中 `mybatis-plus.configuration.log-impl: org.apache.ibatis.logging.stdout.StdOutImpl`(注释里保留了 `Slf4jImpl` 备选)。
|
||
- **影响**:生产日志包含全部 SQL 与参数(含学习内容),噪音大且不利于排查。
|
||
- **建议**:改为 `Slf4jImpl` 并按环境分级,生产默认不打印参数。
|
||
- **验收**:生产环境不再输出逐条 SQL。
|
||
|
||
### 运维-01(原 LPT-25)备份只在集群内同一 PVC
|
||
|
||
- [ ] 未完成
|
||
- **涉及仓库**:`lpt-infra`
|
||
- **依据**:`mysql-backup-cronjob.yaml` 每日 `mysqldump --all-databases` 写入同一集群的 `mysql-backup` PVC,保留 14 天,且 dev 与 prod 混在同一 dump。
|
||
- **影响**:集群级故障即全丢;无法按环境恢复。
|
||
- **建议**:增加异地/对象存储副本,按库分文件,并定期做恢复演练。
|
||
- **验收**:可在集群外取得可恢复的备份,并完成一次演练记录。
|
||
|
||
### 清理-01(原 LPT-26)死代码与死表清理
|
||
|
||
- [ ] 未完成
|
||
- **涉及仓库**:`lpt-be` + `lpt-fe`
|
||
- **依据**:`TestController`(`/test/{id}`)与 `test_table` 仍在生产代码中;`review_mind_maps` 表自 `V20260620_1` 创建后无任何代码引用也未 drop;`lpt-fe/src/api/review.ts` 仍导出 `/review/mind-map/*`(含 xmind 上传解析)相关调用,而后端已无对应端点。
|
||
- **建议**:确认无外部调用后删除端点/表/前端死代码;若保留,需在 `lpt-docs` 说明定位。
|
||
- **验收**:前后端不再存在无实现的接口调用;数据库无孤儿表。
|
||
|
||
---
|
||
|
||
## 9. 建议推进顺序(按模块)
|
||
|
||
同一模块内的条目触碰同一批表结构、口径或配置,建议一个模块一次性改完,避免出现双口径并存的中间态。
|
||
|
||
1. **学习会话生命周期**:会话-01/02/03 已完成;会话-04 + 会话-05 已完成(收敛方式取「惰性 + 定时并用」,出口取「结束并开始新任务 + 放弃」)。本模块已收口。
|
||
2. **内容归属与报告**:归属-01 与报告-01 合并一次改完碎片表与报告结构(碎片归属、报告四段结构、导图待更新标记、检索口径);标记-01(统一标记存储)随同定下,学习引导的来源标记依赖它。
|
||
3. **复习**:先落复习-01 的六项结论(口径与内容边界),复习-07(复习耗时)已独立完成;再做复习-02 / 复习-03 / 复习-04 / 复习-05;复习-06(学习引导)依赖 AI-02 / AI-03 与标记-01,排在 AI 链路之后。
|
||
4. **AI 链路**:AI-01 / AI-02 / AI-03 / AI-04 均已完成。本模块已收口。
|
||
5. **数据与检索 + 导出**:数据-01 / 数据-02 / 数据-03 / 导出-01 均已完成。本模块已收口。
|
||
6. **安全与运维清理**:安全-01 ~ 安全-04、运维-01、清理-01,彼此独立,可并行推进。
|
||
7. **学习录音(已暂停)**:模块整体挂起,重启前先定 §12「路线分叉」(依赖 OBS / 自研原生)。
|
||
|
||
---
|
||
|
||
## 10. 已确认的设计变更(待实施)
|
||
|
||
### 归属-01(原 DC-01)内容归属与待归类
|
||
|
||
- **文档**:`lpt-docs/docs/concepts/knowledge-ownership.md`(设计已确认,见文末结论)、`lpt-docs/docs/concepts/learning-report.md`(结构化报告形态)、`lpt-docs/docs/design/system-structure.md`(设计总纲)
|
||
- **背景**:学习 A 内容时顺手记下的旁支知识(例:学 AI 时记下“1B = one billion”)目前会被算作 A 的知识,进 A 的导图与回忆对比基准。根因是把「记录地点」当成了「内容归属」。
|
||
- **变更内容**:拆分记录上下文(不可变、不可为空;取值是学习会话或复习行为)与内容归属(可变、单一、可为空);时间按行为统计(学习会话→学习时间,复习行为→复习耗时)、内容按归属聚合;新增待归类视图;归类动作挂在复习 Feed 里;AI 只给归属建议;待归类内容可升格为学习任务;学习报告改为结构化(会话摘要、预期达成判断、按归属分组的碎片、自由总结,旁支碎片留在本次报告单独标注)。
|
||
- **影响范围**:碎片表结构、学习报告结构(字段、AI 草稿生成与降级拼接、前端展示、历史自由文本报告兼容)、标准导图取材、按任务的复习与检索(`StandardMindMapServiceImpl.doGenerate()`、`ReviewServiceImpl.getTaskReview()`、`getTaskFragments()` / `getTaskReports()`)。学习会话的时间与状态机不受影响。
|
||
- **前置条件**:已满足—— 2026-09-19 维护者确认:碎片不可脱离学习会话;报告改为结构化并保留自由总结;归属保持单一,跨领域关联由标签承担。结论原文见 `knowledge-ownership.md`「已确认的结论」。
|
||
- **实施要求**:一次替换干净,禁止出现“导图按归属、检索仍按会话”的双口径并存;归属变更后需标记导图待更新。
|
||
|
||
---
|
||
|
||
## 11. 待确认的设计缺口(确认前不要实施)
|
||
|
||
### 复习-01(原 DC-02)复习回路补全
|
||
|
||
- **文档**:`lpt-docs/docs/design/review-loop.md`(立场、内容来源、两个层级、排序、归类、反馈、AI 边界)、`lpt-docs/docs/concepts/review-overview.md`(新增)、`recall-review.md`(回忆记录、覆盖率、复习起点、遗漏项)、`review-feed.md`、`lpt-docs/docs/design/principles.md`、`module-boundaries.md`。
|
||
- **背景**:复习此前只有零散描述(Feed、导图、回忆对比各自成文),缺少系统级口径:复习内容的完整来源、任务级与条目级两层入口、覆盖率与掌握度的定义、遗漏项的语义、反馈动作、归类动作落点、AI 边界都未定;文档写的是“Feed 展示碎片和学习报告”,实现只返回碎片。
|
||
- **本次补全(已按以下取向写入文档)**:复习只做“低阻力反复出现 + 主动提取”,不做到期调度、打卡、评分;Feed 条目单位是碎片,报告从任务记录进入;覆盖率按任务聚合成掌握度,作为排序信号之一;遗漏项是每次对比的快照,不做跨次累计待办;归类动作落在复习里;AI 只做语义匹配与归属建议。
|
||
- **待确认**:
|
||
1. Feed 是否包含学习报告(文档取向:不含)。
|
||
2. 反馈动作形态:只读 /“已掌握 + 稍后再看”/ 仅“稍后再看”(关联 复习-02)。
|
||
3. 覆盖率口径:最近一次 / 最近若干次加权。
|
||
4. 待归类内容的呈现:总览独立分类 / Feed 混排打标;归类是否需在卡片上一键完成。
|
||
5. 遗漏项语义:快照 + 回看原文 / 跨次累计集合。
|
||
6. 排序信号是否对用户可配置(掌握度与时间效应的强度)。
|
||
- **关联实现**:复习-02(反馈动作)、复习-03(Feed 随机取样)、复习-04(覆盖率查询)、复习-05(Feed 摘要)。
|
||
|
||
### 标记-01 统一标记存储
|
||
|
||
- **文档**:`lpt-docs/docs/concepts/marker.md`(新增,含 5 个待决问题)
|
||
- **背景**:来源标记、用户标签等弱信息分散在各功能里考虑,缺少统一存放位置;每新增一种标记就要改一次功能表结构。
|
||
- **已定**:标记统一存放,至少包含对象类型与标识、标记名与值、种类(系统标记 / 用户标签)、建立者与时间;标记不是状态——会话状态、报告可否修订、导图是否待更新这类流程判断留在主体上;学习引导产出的碎片带「来自学习引导」系统标记。
|
||
- **待确认**:
|
||
1. 标记可挂在哪些对象上(碎片 / 报告 / 任务 / 会话)。
|
||
2. 标记名的受控方式(系统标记固定词表、用户标签自由输入;是否允许在系统标记上叠加)。
|
||
3. 标记值的类型(布尔开关 / 枚举 / 自由文本)。
|
||
4. 是否需要按标记检索的入口,以及需要哪些索引。
|
||
5. 标记名的治理(重命名、废弃)与对用户的可见性。
|
||
- **关联实现**:复习-06(来源标记)、归属-01(用户标签)。
|
||
|
||
---
|
||
|
||
## 12. 新增能力:学习录音(已暂停)
|
||
|
||
> **模块状态:已暂停(2026‑10‑08)**。录音-01 的实现已完成并实测通过,但「依赖 OBS」与「自研原生采集」两条路线的取舍未定,其余条目已挂起。重启前先读完本节末尾的「路线分叉」。
|
||
|
||
> 目标:学习会话期间采集设备上全部播放声音(含蓝牙耳机等全部输出设备),转写为文本,作为学习报告与知识碎片的上下文原料。概念与边界见 `lpt-docs` 的 `docs/concepts/study-recording.md`。
|
||
|
||
**采集架构(已确认)**:采集由运行在用户本机的伴随程序负责,音频直传后端;浏览器不采集音频、不传输音频,只发起与展示。
|
||
|
||
**采集后端(待重评)**:当前实现走 OBS,但 录音-决策03 已回退为待重评,见下方「路线分叉」。
|
||
|
||
**代码位置**:`lpt-companion`(本地独立仓库,已加入 meta 的 `.gitignore`,远端待建)。
|
||
|
||
| 分支 | 内容 |
|
||
|------|------|
|
||
| `main` | 仓库脚手架 + `AGENTS.md`(含待定方案、约束与实测坑位总结) |
|
||
| `feature/study-recording` | 第一版实现(OBS 后端 + 抽音轨),HEAD `8d0969d` |
|
||
|
||
已实现并实测的部分:obs-websocket 协议客户端与认证、独立 profile / 场景集合 / 场景 / 系统音频源的幂等准备、平台音频源映射、录制控制、用 ffmpeg 抽音轨并删中间视频,共 85 个单测。
|
||
|
||
**平台能力核对**(2026-10-07 本机实测 + 源码核对):
|
||
|
||
| 平台 | 系统音频来源 | 证据 |
|
||
|------|-------------|------|
|
||
| Windows | WASAPI loopback | OBS 桌面音频标准能力(本机无法验证) |
|
||
| Linux | 默认 sink 的 monitor | 本机实测:`pw-record --target=<sink>.monitor` 采集成功(峰值 32768 / RMS 27959);浏览器经 `module-remap-source` 走 `getUserMedia` 亦成功,且能录到非浏览器客户端的播放声 |
|
||
| macOS 13+ | ScreenCaptureKit | OBS 源码 `plugins/mac-capture/mac-sck-audio-capture.m`;`plugin-main.c` 中 `coreaudio_output_capture_info` 已标 `OBS_SOURCE_DEPRECATED`,改用 `sck_audio_capture_info`(本机无法验证) |
|
||
|
||
**已排除的路线**:
|
||
|
||
- 浏览器直接采集系统声:仅 Windows/ChromeOS 在共享整个屏幕时支持;Chromium 明确排除 monitor 设备。
|
||
- 把 monitor 包装成普通输入源再由浏览器采集:本机验证可行(`module-remap-source`),但需要常驻 watcher 跟随默认输出设备,且网页关闭即中断,已被伴随程序方案取代。
|
||
- 公网页面直连本机端口做控制:Chrome 142+ 起受 Local Network Access 权限约束(实测见 录音-决策01)。
|
||
- 用配置让 OBS 只录音频:`RecFormat2=ogg` 会让容器变成 ogg,但 OBS 仍用 `libfdk_aac` 写入,容器与编码器不匹配 → 产出 0 字节文件;`RecAudioEncoder` 设成 `aac` / `opus` / `ffmpeg_opus` 均未改变实际编码器。
|
||
|
||
### 路线分叉(重启本模块前必须先定)
|
||
|
||
| | 依赖 OBS(当前实现) | 自研原生采集 |
|
||
|---|---|---|
|
||
| 原理 | 经 obs-websocket 驱动 OBS 录出「视频+音频」,再用 ffmpeg 抽出音轨并丢弃视频 | 直接读操作系统混音端点,写出纯音频 |
|
||
| 实测状态 | Linux ✅ 已验证;Win / macOS 未验证 | Linux ✅ 已验证(`pw-record`,20 行);Win / macOS 未实现 |
|
||
| 额外依赖 | OBS + ffmpeg | 无 |
|
||
| 体积 | 35 MB(发行版包)~2.5 GB(flatpak) | 几 MB |
|
||
| 中间产物 | 会写出较大的视频文件再删(已压到 112 MB/小时) | 无 |
|
||
| 主要成本 | 三平台配置差异与 OBS 版本漂移 | 需自写三套原生采集(macOS SCK 最难) |
|
||
|
||
伴随程序必须运行在**声音实际播放的那台机器**上,所以「多端」的含义是:每台用于学习的设备都要装一份并各自配对;换了播放设备(例如改用手机听)该设备就必须有自己的采集能力。
|
||
|
||
### 录音-01 采集后端接口与 OBS 后端
|
||
|
||
- [x] 已实现并实测通过(模块已暂停,代码在分支)
|
||
- **涉及仓库**:`lpt-companion`,分支 `feature/study-recording`,HEAD `8d0969d`
|
||
- **完成于** `feature/study-recording` `8d0969d`;`main` 仅保留脚手架与说明
|
||
- **依据**:OBS 32.2.2 提供 Windows x64/arm64、macOS Apple/Intel、Ubuntu 24.04/26.04 发布;obs-websocket 5.x 自 OBS 28 内置。
|
||
- **已实测验证**(Linux / PipeWire / OBS 32.2.2 / obs-websocket 5.7.4):
|
||
1. 端到端可采到系统混音:OBS 日志 `pulse-input: Started recording from 'alsa_output...analog-stereo.monitor' (default)`,与非默认输出设备无关。
|
||
2. 采到的是**其他应用**的声音:用 `pw-cat`(非浏览器)播放 440 Hz,录出的音轨 FFT 主频精确为 440 Hz,峰值 9873。
|
||
3. 配置隔离成功:独立 `CreateProfile` / `CreateSceneCollection` / `CreateScene` / `CreateInput`,不影响用户已有配置。
|
||
4. 采集路径:OBS 录 Simple+mkv(320×240@5fps、200 kbps),抽出 Opus/Ogg 后删视频。中间文件约 112 MB/小时,最终音频约 18 MB/小时。
|
||
- **实现要点(踩坑记录均已写入 `lpt-companion/AGENTS.md`)**:`--profile`/`--collection` 首次运行会被忽略,改用 obs-websocket 的 `CreateProfile`;空场景集合必须先 `CreateScene`;输出模式/容器/画布变更必须重启 OBS(`prepare()` 用 `restartRequired` 告知);以 kill 结束 OBS 会留下 sentinel 导致卡在安全模式对话框;flatpak 版配置路径与启动方式不同。
|
||
- **OBS 侧的已知限制**:无法通过配置让 OBS 只录音频(`RecFormat2=ogg` 会因编码器不匹配产出 0 字节文件),故改走「录标准容器 + 用 ffmpeg 抽音轨」。
|
||
- **新增外部依赖**:抽音轨需要 `ffmpeg`(配置项 `media.ffmpegPath`);分发时需考虑自带或引导安装。
|
||
- **验收**:在未手动操作 OBS 界面的前提下,能从零建立独立配置并录出可播放的音频文件;用户已有的 OBS 配置不被改动。✅ 已验证
|
||
|
||
### 录音-02 控制通道与会话绑定
|
||
|
||
- [ ] 未完成
|
||
- **涉及仓库**:`lpt-be` + 伴随程序
|
||
- **依据**:Chrome 142+ 的 Local Network Access 权限使「网页直连本机端口」需要用户授权一次,且网页关闭会中断控制(实测见 录音-决策01)。
|
||
- **建议**(待确认):轮询式控制通道——网页只写 `lpt-be` 标记开始/结束,伴随程序带设备 token 轮询 `lpt-be` 取任务,音频由伴随程序直传 `lpt-be`。备选:直连 `127.0.0.1` 换取即时起停,代价是 LNA 授权与网页生命周期耦合。
|
||
- **验收**:网页发起后伴随程序在轮询周期内开始录音;关闭网页不影响录音继续与上传;未配对的设备无法拉取任务。
|
||
|
||
### 录音-03 音频落盘与对象存储
|
||
|
||
- [ ] 未完成
|
||
- **涉及仓库**:`lpt-be` + `lpt-infra`
|
||
- **依据**:`lpt-be` 现有 45 个端点全为 JSON,无任何文件上传能力(`MultipartFile` 零命中);`lpt-infra` 仅有 mysql 10Gi 与 lpt-logs 5Gi PVC,无对象存储。实测码率:Opus 32 kbps ≈ 14.8 MB/小时(未限码率时 58 MB/小时)。
|
||
- **建议**:录音元数据入业务库(会话、起止、时长、对象键、状态),音频本体入 S3/MinIO 兼容对象存储;分片上传并支持断点续传;长期保留。与 运维-01(备份异地)同源,建议一并规划。
|
||
- **验收**:一段会话录音可通过元数据定位并取回;上传中断后可续传;容量按 15 MB/小时可控增长。
|
||
|
||
### 录音-04 转写链路(provider 可配置)
|
||
|
||
- [ ] 未完成
|
||
- **涉及仓库**:`lpt-ai` + `lpt-be`
|
||
- **依据**:`lpt-ai` 目前只有 SiliconFlow OpenAI 兼容 chat(`Qwen/Qwen2.5-32B-Instruct`),无任何 ASR 能力;`AiServiceClient` 为同步轮询(见 AI-01 / AI-02)。
|
||
- **建议**:provider 在配置中切换 `online`(SiliconFlow 转写接口)/ `local`(whisper.cpp)/ `off`(只存音频),默认 `off`。
|
||
- **依赖**:AI-02 / AI-03。长音频转写若走同步链路,等于复制 AI-01 / AI-02 的问题。
|
||
- **验收**:切换配置即可改变转写来源;`off` 时全链路不因缺少转写而失败。
|
||
|
||
### 录音-05 录制可见性与隐私边界
|
||
|
||
- [ ] 未完成
|
||
- **涉及仓库**:`lpt-companion` + `lpt-fe`(或油猴脚本) + `lpt-docs`
|
||
- **依据**:录音采集的是系统混音,可能包含他人语音(线上会议、通话);采集范围由系统决定,用户无法逐条挑选;OBS 自身窗口可能被最小化到托盘,不足以充当「正在录音」的指示。
|
||
- **建议**:除了网页侧展示状态,伴随程序还要有常驻的本地可见指示,并提供一键停止;开始前明确说明采集范围与长期保留策略;未配对或未授权时不得开始录音。
|
||
- **待确认**:本地指示形态(托盘图标变化 / 常驻悬浮提示);他人语音的产品口径;会话暂停期间是否继续录音。
|
||
- **验收**:录制中存在不易忽略的可见指示;任意时刻可一键停止;停止后不再产生新分片。
|
||
|
||
### 录音-06 浏览器侧接入
|
||
|
||
- [ ] 未完成
|
||
- **涉及仓库**:`lpt-fe`(或独立油猴脚本)
|
||
- **依据**:浏览器侧只需发起、结束与展示状态,不接触音频。
|
||
- **建议**:优先直接接入 `lpt-fe`(类型安全、随应用版本发布);若仍使用油猴脚本,脚本只调用 `lpt-be` 接口,不持有音频。
|
||
- **待确认**:油猴脚本还是直接进 `lpt-fe`。
|
||
- **验收**:学习会话中可一键开始/结束录音,并看到状态与转写结果。
|
||
|
||
## 附录 A 核对方式(可复现)
|
||
|
||
- 代码核对:阅读 `lpt-be` 的 `service/impl/*`、`entity/*`、`controller/*`、`config/*`、`resources/application*.yml`、`resources/db/migration/*`;`lpt-fe/src` 的 `utils/request.ts`、`components/*`、`api/*`;`lpt-ai/src` 全部;`lpt-infra` 的 `dev/`、`prod/`、`traefik/`。
|
||
- 线上只读探测(仅 GET,未做任何写操作):
|
||
- `GET https://lpt.cat-shark.xyz/api/actuator/health` → 200
|
||
- `GET https://lpt.cat-shark.xyz/api/actuator/info` → 200
|
||
- `GET https://lpt.cat-shark.xyz/api/actuator/env` → 401
|
||
- `GET https://lpt.cat-shark.xyz/api/review/feed`(未登录)→ 401
|
||
- 结构性核对命令示例:`rg -n "@Scheduled" lpt-be/src`、`rg -n "ORDER BY RAND" lpt-be/src`、`rg -n "unique" lpt-be/src/main/resources/db/migration`。
|