diff --git a/OPTIMIZATION_BACKLOG.md b/OPTIMIZATION_BACKLOG.md index 025e32c..928d703 100644 --- a/OPTIMIZATION_BACKLOG.md +++ b/OPTIMIZATION_BACKLOG.md @@ -57,8 +57,16 @@ | | 安全-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 | -已确认的设计决策(不是待办):会话-决策01 少于 10 分钟不计入总时长;会话-决策02 遗忘判定阈值 50 分钟。 +> **学习录音模块已整体暂停**(2026‑10‑08):录音-01 的实现已完成并实测通过,但采到系统音频的两条路线(依赖 OBS / 自研原生)还没定,其余条目全部挂起。详见 §12。 + +已确认的设计决策(不是待办):会话-决策01 少于 10 分钟不计入总时长;会话-决策02 遗忘判定阈值 50 分钟;录音-决策01 录音由本机伴随程序负责;录音-决策02 只采系统输出不采麦克风。 --- @@ -77,6 +85,26 @@ - **决策**: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 数据正确性 @@ -349,6 +377,7 @@ 4. **AI 链路**:AI-01(先把 AI 移出事务)→ AI-02 + AI-03(异步任务与队列可靠性)→ AI-04(并发锁与生成中语义)。 5. **数据与检索 + 导出**:数据-01(补索引)→ 数据-02 / 数据-03,导出-01 可并行。 6. **安全与运维清理**:安全-01 ~ 安全-04、运维-01、清理-01,彼此独立,可并行推进。 +7. **学习录音(已暂停)**:模块整体挂起,重启前先定 §12「路线分叉」(依赖 OBS / 自研原生)。 --- @@ -396,6 +425,112 @@ --- +## 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=.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/`。