留在学习现场
Hook 轻量记录必要事件；共享核心处理暂存、传输和回执；浮标呈现当前建议与导师提示。
01 · ARCHITECTURE
目标架构：把“采集、判断、回应”拆到正确的位置
可把它理解为三端协作：学员端收集和接收，中心服务保存事实并做编排，导师端观察整体并发出精准提示。关键不是技术名词，而是每件事只能在该做的位置做。
形成统一事实
接收上报、验证身份、解析内容、组织学习分析，并把更新分发给恰当的对象。
把注意力放在关键处
在浏览器中看全局过程、定位需要帮助的节点，并向某位学员定向发送提示。
唯一事实源服务端只认
copilot.db，不读取学员电脑文件。双角色身份学员和导师各用自己的 token，权限不能混用。
先保存再推送导师消息不因离线丢失，实时通道只负责加速。
单进程实时视图当前 EventBus 与连接表在一个应用进程里保持一致。
展开：哪些边界绝不能跨
- 服务端不能读学员机：本地 WorkBuddy 数据库、JSONL 与任意本地路径都只允许学员端显式读取；服务器只消费上报内容。
- Controller 不直连数据库：路由做鉴权和编解码，业务编排交给 Service，持久化交给 Store。
- 导师消息必须按学员定向：导师能看全体，但写入只发送给目标
student_id的浮标。
展开：最重要的一条双向链路
正向：学习事件上报 → 服务端解析/分析 → 导师端全量可见、本人浮标定向可见。
反向：导师发提示 → 服务端先落库 → 在线实时推送或离线补拉 → 学员端实际处理后回执。所谓“送达”以后一步为准。
02 · REUSE MAP
复用地图：保留价值，不继承错误假设
项目不是推倒重来。已有成熟的浮标绘制、对话解析、导师端界面和事件分发逻辑；需要被替换的，是“服务器读学员机本地数据”这类单机时期的假设。
7直接复用
22改造后复用
3逻辑参考后重写
10归档，不带入新架构
直接保留
- 配置加载与单 worker 启动
- 进程内 EventBus
- 导师端三栏视觉骨架
高价值资产，改造后继续用
- 原生浮标：跨 Space、绘制、重连与交互
- 对话解析：把路径入参改成已上报的字节内容
- Store / Service：保留编排价值，改掉单机读写和层间泄漏
明确退出
- 服务器读本地 WorkBuddy 数据库
- PyQt6 历史浮标与旧菜单栏
- 投机的 ports 抽象与死代码
!
判断复用与否的第一问：它是否假设服务端能接触学员电脑？如果答案是“是”，不要把这条能力搬进新服务端；只能把显式读取留在学员端，再用上报内容完成同样的目标。
展开：最值得优先理解的四项资产
- floating_native.py：原生浮标的跨 Space、绘制、拖拽、点击、重连都已有成熟经验，优先改造而不是重写。
- transcript.py：逐行解析和文本提取逻辑价值很高，只需把输入换成服务端收到的原始内容。
- eventbus.py：单向 pub/sub 结构可直接保留；定向路由应由连接注册表完成。
- 导师端静态界面：已有三栏信息结构，重点补消息编写、状态与补拉体验。
展开：开始改一个旧文件前的三步
- 先在复用地图里确认它的分类：直接用、改造、重写还是归档。
- 定位它依赖的假设：是否读本地路径、是否依赖全局单例、是否跨层写数据。
- 为保留的行为写真实判据，再移除不符合目标架构的部分。
03 · TEST PLAN
测试判据：不是“没有报错”，而是系统真的守住承诺
测试方案将每个关键需求写成明确的通过标准。开发时可以改命令适配环境，但不能把标准改松；每次改动先证明测试在功能被打断时会失败，再证明修复后恢复通过。
每次迭代都要过的底线
可导入、应用能构建、全量测试、单 worker 拒绝、多机红线、公共网络 token 与部署参数都必须有明确结果。
用真实链路验证核心功能
覆盖解析、落库、学习分析、导师 API、hook 上报、双向消息、鉴权、离线同步和学员端会话跟随。
端到端与真机发布门
验证多学员隔离、导师消息仅到目标浮标、公网身份隔离；再用真实设备补跨 Space、HTTPS/WSS 与灰度上报证据。
先见过红功能彻底坏掉时，用例必须真的会失败。
不 mock 被测对象Service 集成使用真临时 Store + 固定假 LLM。
断言内容输入确定性内容，断言正确输出，不能只看非空。
不放宽判据修复只改业务实现，不能靠改标准换取“绿”。
展开：P0 为什么要先跑
P0 是最短路径的“系统还活着吗”检查。除了全量测试，它还专门抓三类高风险退化：多 worker 破坏实时视图、服务器重新读取学员本地文件、public 环境允许空 token 启动。这些不等业务功能做完才检查。
展开：一次功能开发的推荐顺序
先写能断言真实行为的用例并确认它会失败；只做最小实现使其通过；跑对应 P0/P1；每完成若干条路径再回归。涉及导师 → 学员消息时，还要验证目标隔离、断线补拉和最终回执。
01定位边界先回到架构页与复用地图，确认这条能力应该放在哪一端。
02写判据从测试方案选对应 P0/P1/P2，补真实、可失败的用例。
03最小改动不顺手扩张，不迁移无关结构，不改变锁定判据。
04跑回归逐项验证功能路径，定期重跑基础门和已通过路径。
05记录证据把实际命令、结果与失败修复写入开发日志，方便后续协作。