电脑截屏、手机截屏 → AI 读题作答 → 答案同时出现在电脑和手机上
单机就能用（桌面悬浮窗把答案贴在屏幕边上） · 连上手机就是双端同步（手机当第二块屏）
局域网内两台设备直连，不经过任何第三方中转服务器，也不需要注册账号。
一个在局域网里跨设备搜题的小工具。它把「截屏 → 多模态 AI 读题 → 显示答案」这条链路做成两端协同：
电脑截屏（热键 / 悬浮球 / 悬浮窗 / 剪贴板）
│
▼
多模态 AI 读题（题目 / 选项 / 材料 / 主观题结构化）
│
├──────────────► 电脑端：当场显示答案与解析（主窗口 或 桌面悬浮窗）
│
└──── 局域网 ──► 手机端：自动刷新出同一条结果，可离线回看
手机截屏（悬浮球 / 相册选图）
│
▼
上传到电脑 → 电脑端 AI 分析 → 结果回传手机（电脑端同步留档）
典型场景：电脑上做网课作业 / 题库练习，想快速看答案与解析；或者用手机对着题目截一张屏（或从相册选一张已经拍好的图）上传给电脑上的 AI —— 两边看到的永远是同一份结果。
答案由 AI 生成，仅供参考；请遵守所在学校 / 机构关于作业与考试的规定。
同一个软件，两种用法 —— 单独一台电脑就能用，也可以电脑 + 手机连起来用，随时切换。
什么都不用配：填个 AI Key，按 F8 截屏就有答案。局域网服务默认是关的，不配对手机时它连端口都不监听。
这个用法的最佳搭配是桌面悬浮窗（见后面〈桌面悬浮窗〉一节）：把答案贴在屏幕边上的小窗里 —— 字大、清晰、不挡题，做题时不用切窗口、也不用回头找主界面：
- 大小随你调：整体 50%–300%、窗内字号 60%–200%、透明度最低 20%；
- 默认模式只列题目与答案，能直接拖选复制；要看解析与阅读材料就一键切「详细解析模式」；
- 窗里就能「识别一张」「多页识别」，还能翻上一条 / 下一条 —— 等于把主界面最常用的部分挂在桌面上。
- 电脑端「设置 → 连接设备」打开开启连接设备开关（第一次会弹一次防火墙授权，选允许）；
- 手机端扫码配对（两台设备连同一个 Wi‑Fi）；
- 之后两边看的就是同一份结果：
- 电脑截屏，手机看：手机当第二块屏 —— 电脑上按
F8、点悬浮球或点悬浮窗识别，结果 1 秒内出现在手机上，还能自动跳到本次结果页； - 手机截屏，电脑算：手机悬浮球单击截屏（或「相册选图搜题」）→ 上传到电脑用 AI 识别 → 结果同时回到手机与电脑；
- 断线不丢：手机不在线时任务自动排队，重新连上自动补跑；历史记录本来就在手机本地，离线也能翻；
- 同一时间只支持一台安卓设备：换手机请先在电脑端「连接设备 → 已配对设备」里吊销旧设备，再用新手机扫码配对。
两种用法可以混着来：平时单机用，要给手机看结果时再打开「连接设备」，不用重装、也不用改配置。
| 能力 | 说明 |
|---|---|
| 全局热键截屏搜题 | 两个可自定义的全局热键：截屏识别（默认 F8）与多页模式（默认 F9）；被别的软件占用会自动回退并给出提示 |
| 桌面悬浮球 | 常驻桌面最上层的小圆球：单击截一张图直接识别（正在攒页时 = 收尾识别）；按住 0.5 秒或右键追加一页进入多页模式。可拖动、松手自动吸附屏幕左右边缘；大小、透明度、描边都可调，三种状态三种颜色（待识别 / 识别中 / 多页模式） |
| 桌面悬浮窗 | 贴在桌面上的结果小窗（见下一节）：不切回主窗口就能看答案、接着识别、翻上一条 / 下一条；可切「默认模式 / 详细解析模式」、可调大小与配色，点按钮不抢焦点 |
| 多页识别 | 一道大题分好几屏（题干 + 材料 + 图）时，逐页「追加」，最后「结束」一次性提交，AI 按页序整体读题；题目顺序由模型自行纠正 |
| 剪贴板监听 | 复制一张图（截图工具、浏览器、看图软件都行）就自动识别，不用切窗口 |
| 拖入 / 粘贴 | 图片文件直接拖进主界面，或 Ctrl+V 粘贴 |
| 结果页 | 一次识别的所有题目在同一页纵向显示；命中选项标绿、不确定的标黄；阅读材料默认折叠、可展开；可展开「原始返回」排查解析问题 |
| 历史记录 | 按「任务合集」分组，可二次确认后删除；支持关键词搜索历史题目（题干 / 解析，FTS5）；支持 Markdown / JSON 导出、合集导出、一键备份与恢复 |
| 托盘常驻 | 关闭窗口 = 隐藏到托盘，不退出；托盘菜单可直接截屏、多页识别、切换合集、显示 / 隐藏悬浮球与悬浮窗、打开设置 |
| 内置服务端 | 电脑端自带局域网服务（HTTP + WebSocket），手机端通过配对码 / 二维码连上来，无需另装服务。默认关闭：在「连接设备」里打开开关才会启动并申请网络权限 |
| 示例1 | 示例2 | 示例3 |
|---|---|---|
 |
 |
 |
| 能力 | 说明 |
|---|---|
| 当前任务 | 手机默认就是「电脑识别结果的显示器」：显示与电脑的连接状态（「已连接 · 合集名」）与正在识别的图片张数，出结果后自动跳到本次结果页 |
| 悬浮球 | 常驻在别的应用之上：单击截屏上传分析；长按进入多页模式（一次长按加一页，最后短按收尾提交） |
| 相册选图搜题 | 从相册挑一张图上传到电脑分析 |
| 结果页 | 与电脑端同一套题目卡片；「上一次 / 下一次识别」在多次识别之间切换、字号可调、可请求电脑「重新生成」 |
| 历史记录 | 按合集分组、可离线查看（数据本来就在手机上），支持删除 |
| 静默采集 | 手机自己发起的识别全程不打扰：不跳页、不切标签、不把界面拉到前台，进度只反映在「当前任务」页与通知里 |
- 电脑发起识别：手机 1 秒内看到「N 张图片识别中…」，出结果后自动跳到本次结果页；如果手机正停在某次结果页上，页顶会浮出一条「电脑正在识别中…／识别完成，正在打开新结果…」。
- 手机发起识别：结果落回手机并同步到电脑端，全程静默。
- 电脑上新建 / 改名合集、新增识别结果：手机在前台时 1 秒内跟着变；电脑上删掉的合集在手机端会保留（手机端自己删的合集会同步给电脑）。
- 断线也没关系：手机有离线队列，重新连上会自动补跑并补齐。
电脑端可以开一个贴在桌面上的结果小窗：在别的应用里做题时，不用切回主窗口就能看答案、接着识别、翻上一条 / 下一条。
小窗和悬浮球是同一套实现（原生窗口，不为它再起一个界面引擎）：贴在其他窗口之上，点它上面的按钮不会抢走你当前窗口的焦点，识别时还会自动把自己藏起来，不会拍进发给 AI 的图里。
| 项 | 说明 |
|---|---|
| 开关 | 「设置 → 悬浮窗设置 → 显示悬浮窗」，默认关闭，打开后记住状态；托盘右键菜单里也能随时开关（菜单文字会跟着变成「隐藏悬浮窗」） |
| 置顶显示 | 默认置顶；关掉后会被别的窗口盖住 |
| 位置 | 默认落在屏幕右侧、不贴边；未锁定时按住顶部第一栏即可拖动，设置里有「恢复默认位置」 |
| 锁定位置 | 锁定后拖不动（顶部第一栏也有锁定按钮），但按钮点击始终有效 |
| 三种外观 | 标准竖屏 9:20（342 × 760，默认）· 加长竖屏 9:30（270 × 900）· 横向 20:9（560 × 252）；不支持自由拉伸 |
| 显示比例 | 50%–300% 无极调节，窗口宽度 = 该外观的基准宽度 × 比例 |
| 窗内字符大小 | 60%–200%，在设置页里调（窗内不放字号按钮） |
| 透明度 | 默认 90%，最低 20% |
| 配色与明暗 | 配色 6 套：纯净白（默认）/ 薄荷绿 / 天空蓝 / 丁香紫 / 暖沙 / 樱粉；明暗可选跟随软件设置 / 明亮 / 深色 |
| 两种内容模式 | 默认模式：只看题目与答案，纯文本、可拖选复制，底部多一个「复制识别内容」；详细解析模式：与主界面同一套题目卡片（选项全列 + 解析 + 阅读材料）。顶部第一栏一键切换 |
| 窗内操作 | 顶部第一栏：左侧是「第 N/M 次识别」与识别时间，右侧一排图标按钮——下一条 / 上一条 / 重新识别 / 切换模式 / 锁定位置（鼠标悬停有说明）；底部：「识别一张」「多页识别」（多页中变成「结束并上传」「继续添加页（n/上限）」「取消多页」） |
| 滚动与跟随 | 内容区滚轮滚动；电脑上每识别完一次，小窗自动切到最新那一次 |
⚠️ 悬浮窗不排版公式：数学 / 物理公式会按 LaTeX 源码原样显示（例如$x^2-1$会照原样画出来）。需要看排版好的公式，请回到主窗口 —— 同一份结果在主界面是正常渲染的。
| 项 | 要求 |
|---|---|
| 电脑 | Windows 10 / 11（64 位）。电脑与手机需要在同一个局域网（同一个路由器 / 同一个 Wi‑Fi）。VC++ 运行库已随包提供，无需另外安装 |
| 手机 | Android 8.0 及以上（minSdk 26），arm64 / armeabi-v7a / x86_64 三种架构都有对应安装包 |
| AI 服务 | 需要自备一个支持图片输入的多模态模型 API Key（默认已按 DeepSeek 官方接口填好模型名与地址，通常只要粘一个 Key） |
| 权限 | 手机端需要相机（扫码配对）、通知、悬浮窗、截屏授权（首次使用时按引导授权即可） |
两种包任选其一，功能相同：
- 便携版：解压
quizsync-windows-portable-*.zip到任意目录，双击quizsync_desktop.exe。数据（数据库、截图、日志）就放在软件目录下的userdata\，拷走整个目录即搬走全部数据。 - 安装版：运行
quizsync-windows-setup-*.exe，会创建开始菜单与桌面快捷方式，卸载不会删除你的数据目录。
首次启动如果 Windows 防火墙询问是否允许访问网络，请选择允许（只在局域网内使用）。
安装 quizsync-android-<架构>-*.apk：
| 文件 | 适用机型 |
|---|---|
arm64-v8a |
近几年绝大多数手机（首选） |
armeabi-v7a |
较老的 32 位机型 |
x86_64 |
模拟器 / x86 平板 |
⚠️ 装过早期版本的手机，请先卸载旧版再装：包名已从com.example.quizsync_android改为com.quizsync.android。系统把两者当作两个不同的应用，无法覆盖安装，也不会提示升级。 卸载旧版会一并删掉它的历史记录与配对信息，装好新包后需要重新配对一次。
Android 会提示「未知来源应用」，按系统引导允许一次即可。
- 打开软件 → 左侧 API 配置；
- Provider / 模型名 / Base URL 默认已经按 DeepSeek 官方接口填好（
deepseek-flash+https://api.deepseek.com），通常只要把 API Key 粘进去、点保存； - Key 申请入口就在该输入框下面（
https://platform.deepseek.com/api_keys）。
用别家的多模态模型也可以：把 Provider 切到 OpenAI 兼容 / Anthropic / Gemini，填上对应的模型名、地址与 Key 即可。
识别结果都归属于某个「任务合集」（例如「期末复习」「第三章作业」），方便以后查找与导出。 第一次打开会要求新建一个；每次启动都要重新选一次，避免新记录不小心落进上次的合集。
- 电脑端 连接设备 → 打开时会自动刷新一个二维码和 6 位配对码；
- 手机端首次进入点「开始使用」→ 扫码（或手动输入 6 位码）；
- 配对成功后手机自动回到「当前任务」页，并显示「已连接 · 合集名」。
同一时间只支持连接一台安卓设备。换手机时请先在电脑端「设置 → 连接设备 → 已配对设备」里 吊销旧设备，再用新手机扫码配对；直接配对新手机，旧手机会立刻掉线并需要重新扫码。
- 通知权限：常驻截屏服务需要（Android 13+ 会弹窗）；
- 悬浮窗权限：悬浮球需要；
- 截屏授权：第一次点悬浮球时，系统会弹出「开始录制或投射」之类的确认框，点允许（这是 Android 对截屏的硬性要求，无法跳过）；
- 部分机型还需要把应用加入电池优化白名单 / 允许后台弹出界面，否则悬浮球可能被系统清理（设置 → 识别模块设置 → 权限引导里有直达入口）。
想一边看别的窗口一边看答案，就把小窗打开：「设置 → 悬浮窗设置 → 显示悬浮窗」打开即可， 默认落在屏幕右侧（竖屏 9:20）；觉得挡视线就调小「显示比例」，或把「透明度」拉低。
- 按截屏热键（默认
F8；被别的软件占用时会自动回退并给出提示，以「热键设置」页显示的为准）→ 截取鼠标所在的那块屏幕 → 答案，全程后台静默：不会抢焦点、不会把窗口弹到前台。 - 点桌面悬浮球：在别的应用里也能截，不用切回本程序。
- 多页：按「多页模式」热键（默认
F9）逐页攒 —— 第一下进入多页并抓第一张，继续按就往下加；抓满页数上限会自动上传；没满就按F8（截屏识别）结束多页，把已抓的图一次提交。用悬浮球也行：长按 / 右键追加、单击收尾。 - 桌面悬浮窗：打开后小窗常驻，识别完直接在窗里看答案；窗里可以翻上一条 / 下一条、切换「默认模式 / 详细解析模式」、点「识别一张」再截一张、点「复制识别内容」把这一屏答案拿走。
- 剪贴板：在设置里打开「剪贴板监听」后，复制一张图就会自动识别。
- 结果：成功时界面保持静默，结果写进当前会话，回到主界面就能看到题目与解析；失败（没配 Key、没找到题目、网络不通）会把窗口带到前台并写明原因。
- 把手机当第二块屏：电脑识别时看着手机就行，结果会自动出现（停在结果页上时也会有浮层提示）。
- 手机自己发题：点悬浮球截屏（或「相册选图搜题」）→ 上传到电脑分析 → 结果回传；
- 多页：长按悬浮球加页（球变色表示已进入多页模式），最后短按一次结束并提交 —— 短按只提交已经截好的页，不会再多截一张；抓满上限会自动提交。
左侧一共十个分类，第一项是「使用说明」（可识别的方式与各项设置怎么用）：
| 分类 | 内容 |
|---|---|
| 使用说明 | 五种可识别方式、多页识别怎么用、十个分类逐项说明、常见问题 |
| 显示设置 | 主题模式（跟随系统 / 浅色 / 深色）、界面缩放 50%–300%、题目字号与字重 |
| API 配置 | AI 服务供应商、API Key、模型名、Base URL、超时、每日调用上限、今日用量 |
| 连接设备 | 连接状态、监听端口与局域网地址、配对二维码 / 配对码、已配对设备（可吊销）。同一时间只支持一台安卓设备（换手机先吊销旧设备） |
| 识别设置 | 剪贴板监听、是否保存图片文件、多页识别页数上限、本地图片缓存上限 |
| 悬浮球设置 | 显示开关、大小、整体透明度、描边（开关 / 宽度 / 不透明度，颜色跟随状态） |
| 悬浮窗设置 | 显示开关、置顶、锁定位置与归位、三种外观、显示比例、窗内字符大小、配色与明暗、默认 / 详细解析模式、透明度 |
| 热键设置 | 两个用途各自一行（截屏识别 / 多页模式）：自定义 / 恢复默认；停在本页（且窗口在前台）时按键不会触发截屏，离开或切到别的程序立刻恢复 |
| 数据管理 | 任务合集（切换 / 新建 / 删除 / 按合集导出）、一键备份、恢复备份、导出全部历史、导出日志、打开数据目录 |
| 关于 | 应用名与版本、项目地址、技术栈、字体与开源许可 |
手机端设置项集中在「设置」标签：外观（主题 / 字号）、识别模块总开关与二级页（截屏方式含备选的无障碍截屏、悬浮球开关与外观、一题多页、权限引导）、配对与解除配对、关于。安卓端本地原图固定只留最近 20 张（没有缓存上限设置项；文本结果与元数据永久保留）。
- 只在你自己的设备之间传输：电脑与手机在同一个局域网内直连（HTTP + WebSocket），没有云端中转、没有账号体系，代码里也不包含任何遥测 / 统计。
- 什么会离开你的设备：只有你主动截取或选中的那张图片会发给你自己配置的 AI 服务商（例如 DeepSeek 官方接口）用于识题。除此之外的数据都留在本机。
- API Key 的存放：Key 只存在电脑端，用 Windows DPAPI 加密后落盘，数据库里不存明文；界面上只回显尾 4 位，输入框保存后立刻清空；手机端不保存 Key，只持有一份配对 token（放 Android Keystore），可在电脑端「吊销设备」或手机端「解除配对」立即作废。
- 数据落在哪：电脑端在软件目录的
userdata\（数据库、images\截图、logs\日志、备份与导出）；手机端在应用私有目录（对外不可见）。两端都可以一键导出 / 备份。 - 删除与卸载：删除识别记录是软删除（可随备份恢复）；电脑端卸载不会删除数据目录（
userdata\要手动删），手机端卸载会连同应用私有数据一起清掉（换机请先在电脑端备份）。 - 局域网访问：服务只监听局域网地址，并用配对 token 鉴权；手机端「解除配对」或电脑端「吊销设备」可立即让旧 token 失效。
| 现象 | 处理 |
|---|---|
| 手机连不上电脑 | 确认两台设备在同一个 Wi‑Fi、电脑端服务已启动（连接设备页有状态与端口）；Windows 防火墙放行该端口；若网络开启了「AP 隔离」（公司 / 学校网络常见）会互相不可见，换成手机热点试试 |
| 识别结果一直是「识别中」 | 看电脑端是否弹过错误提示（Key 未填 / 额度超限 / 网络不通）；API 配置页的「今日用量」能看到调用情况 |
| 截出来是黑图 | 该应用禁止截屏（视频类、银行类应用常见），换用手机截屏或相册选图上传 |
| 悬浮球不见了 | 手机端：设置 → 识别模块设置 → 权限引导，补授予悬浮窗权限并加入电池白名单；电脑端：设置 → 悬浮球设置 → 打开「显示悬浮球」 |
| 悬浮窗不见了 / 拖不动 | 电脑端「设置 → 悬浮窗设置 → 显示悬浮窗」重新打开（托盘右键菜单里也有这一项）；被别的窗口盖住就把「置顶显示」打开；拖不动是「锁定位置」开着 —— 解锁后按住顶部第一栏才能拖 |
| 悬浮窗里的公式是一串代码 | 悬浮窗不排版公式（按 LaTeX 源码显示）；要看排版好的公式请回主窗口，同一份结果是正常渲染的 |
| 手机端不自动刷新 | 确认手机停在「当前任务」页且电脑端已选合集；手机在前台时每秒会主动问一次电脑状态 |
| 手机上的合集 / 记录和电脑不一致 | 电脑端新建 / 改名 / 新增记录后，手机在前台时 1 秒内会跟上；电脑端删掉的合集在手机端会保留（手机端自己删的合集会同步给电脑）；手机刚才在后台的话，回到前台也会自动补齐 |
| 换了电脑 / 重装 | 把旧的 userdata\ 目录拷到新软件目录旁边即可（也可用「数据管理」里的一键备份 / 恢复） |
| 换手机了 | 先在电脑端「连接设备 → 已配对设备」里吊销旧手机，再用新手机扫码配对；电脑端同一时间只支持一台安卓设备 |
| 想用别家模型 | API 配置里换 Provider（OpenAI 兼容 / Anthropic / Gemini）并填模型名与地址；必须是支持图片输入的模型 |
- 只支持 Windows + Android 两端（没有 iOS / macOS / Linux 版本）。
- 依赖局域网直连，不支持公网远程使用。
- 电脑端同一时间只支持连接一台安卓设备：换手机请先在「设置 → 连接设备 → 已配对设备」里吊销旧设备，再用新手机扫码配对。
- 系统级禁止截屏的应用只能得到黑图（本工具不做任何绕过）。
- 桌面悬浮窗不排版公式：公式按 LaTeX 源码显示，需要排版后的效果请看主窗口。
- AI 会出错：答案与解析仅供参考，重要场合请自行核对；题目不清、缺页时结果可能不完整（界面会标出「题目不全」与「AI 猜测」）。
- 图片与结果保存在本机，跨设备迁移请用备份 / 导出功能。
- 手机端没有内置拍照入口：想用照片搜题，请先用系统相机拍好，再从「相册选图搜题」导入（或直接点悬浮球截屏）。
apps/desktop Flutter（Windows 桌面端，内置局域网服务端）
apps/android Flutter（Android 端，含极薄的 Kotlin 平台通道）
packages/quizsync_core 纯 Dart 共享核心：协议模型 / drift(SQLite) / 同步引擎 / AI 客户端 / 解析
packages/quizsync_ui 两端共享的 Flutter 组件（题目卡片 / 配色 / 会话导航）
server/ 独立的 Windows 命令行服务端（纯 Dart CLI：热键截屏 → AI → 手机）
docs/ 协议、数据模型、AI 契约、功能规格等设计文档
tools/ 一键构建与打包脚本
| 层 | 选型 |
|---|---|
| 界面 / 业务 | Flutter 3 · Dart 3 · Riverpod |
| 本地数据 | drift（SQLite，含 FTS5） |
| 端到端同步 | 自研：Lamport 时钟 + 逐字段 LWW + 软删除墓碑 + 离线队列，两端共用同一份实现 |
| 电脑端服务 | shelf（HTTP + WebSocket），配对码 / token 鉴权 |
| 截屏 | Windows：GDI（含剪贴板 DIB 解析）；Android：MediaProjection（备选无障碍截屏） |
| 悬浮球 / 悬浮窗 | Windows：原生分层窗口（UpdateLayeredWindow，Dart 侧离屏出像素、原生侧只负责贴图与命中判定）；Android：原生 View + WindowManager（不在浮层里跑第二个 Flutter 引擎） |
为什么不把逻辑分散写：两端最容易出问题的地方是「同一份数据在两边长得不一样」。协议、模型、序列化与同步算法全部放在共享包里，两端跑同一份代码，从结构上消灭这类不一致。
需要 Flutter 3.4x（stable）与对应平台的工具链（Windows 桌面：Visual Studio 生成工具；Android：Android SDK + JDK 17）。
# 依赖（在 packages/quizsync_core、packages/quizsync_ui、apps/desktop、apps/android 下分别执行）
flutter pub get
# 静态检查
flutter analyze
# 构建
cd apps/desktop && flutter build windows --release
cd apps/android && flutter build apk --split-per-abi --release仓库内的设计文档见 docs/：功能规格（SPEC.md）、局域网协议（protocol.md）、数据模型与同步算法（data-model.md）、AI 契约与输出格式（ai-contract.md）。
本源码包不含测试目录（发布版已裁剪）：
flutter test/dart test没有用例可跑 ——tools/build_all.ps1检测到没有test目录会自动跳过测试步骤，静态检查与两端构建照常进行。
- 界面字体 MiSans（小米）：依官方 FAQ，允许个人与商业免费使用、可随软件嵌入分发，但不得单独售卖 / 再分发字体文件本身，也不得改名后再发布。
- 图标字体 Material Icons：Apache License 2.0。
- 其余第三方依赖的许可证全文可在应用「设置 → 关于 → 第三方组件许可全文」中查看。
- 本项目的代码以 MIT 许可证 开源，可自由使用、修改与再分发（保留版权与许可声明即可）。
- 上表中随包分发的第三方资源（MiSans 字体、Material Icons、KaTeX 字体等）不因本项目开源而改变许可，仍按各自的条款使用。
AI 双端搜题 · QuizSync AI — 局域网内的跨端 AI 搜题工具