# v0.77 RAG + ASR 集成 Checklist

> 这次 commit 只放**纯新增文件**(scaffold),**没动任何 v0.76.4 代码**。
> 当前状态: **代码 100% 兼容 v0.76.4**,即使 merge 进 main 也无任何用户感知。

## ✅ 这个 commit 已完成

- [x] 所有 RAG / ASR 客户端代码 (server/clients/*)
- [x] memory 路由 + sqlite-vec migration (server/{routes,migrations}/)
- [x] feature flag config (server/config/v0.77-flags.js)
- [x] React 组件 PressToTalkButton + MemoryUsedBadge (desktop/src/components/)
- [x] dev mock service worker (desktop/src/dev-mock-sw.ts)
- [x] 部署脚本 (scripts/lynn-deploy-native.sh)
- [x] OpenAPI 契约 (docs/api/openapi-v0.77.yaml)
- [x] release notes (docs/RELEASE-NOTES-v0.77.md)

## 🔲 还没集成 (后续 commit 完成)

### Server 端集成 · 仅在 flag ON 时生效

- [ ] `server/index.js` 启动时挂载 memory router
  ```js
  import { memoryRoutes } from "./routes/memory.js";
  import { v077Flags } from "./config/v0.77-flags.js";
  if (v077Flags.RAG_ENABLED) {
    app.route("/v1/memory", memoryRoutes);
  }
  ```

- [ ] `server/routes/chat.js` (或 WS handler) 加 memory 召回
  - 在用户消息进 LLM 前调 `buildMemoryContext()`
  - 召回失败必须 try/catch 静默 fallback
  - 把 `memory_used` 事件作为首帧推给前端
  - **必须有 `Promise.race(... timeout(500))` 超时保护**

- [ ] WS 协议加新 frame type
  - `{type:"memory_used", items:[...], recall_ms:N}`
  - 旧 client 自动忽略 unknown type → 兼容

### Client 端集成 · 仅 dev 用

- [ ] `desktop/src/main.tsx` 启动时(仅 DEV) 加载 mock SW:
  ```ts
  if (import.meta.env.DEV && import.meta.env.VITE_USE_MSW === "true") {
    const { worker } = await import("./dev-mock-sw");
    await worker.start({ onUnhandledRequest: "bypass" });
  }
  ```
- [ ] 主输入框区域插入 `<PressToTalkButton />`
- [ ] chat 消息组件上方插入 `<MemoryUsedBadge />`
- [ ] 设置面板加 RAG/ASR 开关 toggle

### 数据 · 隔离测试用

- [ ] 测试 brain 启动时设 `LYNN_HOME=~/.lynn-test` 完全隔离
- [ ] 生产 brain 不设 `LYNN_RAG_ENABLED`,自然 OFF

## 测试流程

### 1. 服务端部署 (GPU 服务器,0 用户影响)
```bash
scp scripts/lynn-deploy-native.sh root@js1.blockelite.cn:/root/ -P 30112
ssh root@js1.blockelite.cn -p 30112
sudo bash /root/lynn-deploy-native.sh --check  # 预检
sudo bash /root/lynn-deploy-native.sh          # 正式部署
```

### 2. 本地启测试 brain
```bash
LYNN_RAG_ENABLED=true \
LYNN_HOME=~/.lynn-test \
LYNN_EMBED_URL=http://js1.blockelite.cn:8002 \
LYNN_RERANK_URL=http://js1.blockelite.cn:8003 \
LYNN_ASR_URL=http://js1.blockelite.cn:8004 \
  npm run server
```

### 3. 启 dev client (mock 模式,不需要后端)
```bash
VITE_USE_MSW=true npm run dev:renderer
```

### 4. 启 dev client (连真实测试 brain)
```bash
LYNN_BRAIN_URL=http://localhost:18001 npm run start:dev
```

## 回滚

| 场景 | 操作 |
|---|---|
| 整个分支不要了 | `git checkout main && git branch -D feat/v0.77-rag-asr` |
| GPU 服务挂了 | `bash lynn-deploy-native.sh --down` (10 秒) |
| 测试数据库脏 | `rm -rf ~/.lynn-test/memory.db` |
| flag 开错了 | 去掉环境变量,重启 brain |

## 安全保证

- ✅ 没有 v0.76.4 代码被修改
- ✅ flag 默认 OFF,merge 进 main 不影响生产
- ✅ 新文件全部走独立路径(/v1/memory/*),不冲突现有 endpoint
- ✅ sqlite-vec migration 独立 db 文件,不动现有 SQLite
- ✅ 所有客户端组件零外部依赖,可零成本删除
