从 1.x 升级到 2.0¶

先保留旧数据¶

正常退出旧版后，备份旧安装目录中的 data/ 和自行配置的 .env。不要把包含凭据的备份提交到 GitHub 或发到公开 issue。2.0 使用新的用户数据目录，不在旧安装目录中覆盖文件。

分别导入¶

1. 在「设置 → 导入旧版本」填写旧 data 目录的完整路径，执行数据导入。
2. 检查导入课堂、资料和笔记。相同路径、相同内容的文件再次导入不会重复创建记录。
3. 如需迁移配置，填写旧 .env 的完整路径，执行「导入旧设置与凭据」。已有新配置和已设置凭据优先保留；旧 .env 不改写。
4. 如需迁移外观，在同一设备上执行外观导入。旧颜色、字号、透明度和圆角映射到新版偏好，原存储保留。

数据导入识别 class_transcript.txt、cite/*.txt 和 summaries/*.md，跳过符号链接、越界、超限或不可读文件，并报告跳过项。旧历史摘要作为笔记保留。旧版本已经压缩删除或覆盖的逐字原文无法恢复。

兼容变化¶

原来的 local 是 Google 在线识别，新版将其标记为兼容模式；真正离线识别使用 SenseVoice。旧 WebSpeech、Seed 和 DashScope 能力分别保留，服务商新旧凭据形式不能混填。

2.0 不内置共享试用 Key，也不通过 API 返回完整配置凭据。HTTP、WebSocket 和手机配对使用不同访问边界，旧无鉴权业务接口不再提供。第三方调用方需要按 2.0 接口 迁移。

备份与回退¶

正式桌面数据目录：macOS 为 ~/Library/Application Support/ClassFox，Windows 为 %LOCALAPPDATA%\ClassFox。正常退出后复制整个目录；运行中 SQLite 可能同时使用 classfox.sqlite3-wal 和 classfox.sqlite3-shm，只复制主文件可能漏掉新记录。

系统凭据存储中的 Key 不随目录备份导出，换机需重新填写。回退旧版时使用保留的旧安装与旧数据；旧版不能读取 2.0 SQLite，新版原文可先导出为文本或 Markdown。