词间 Wordnote

本机运行的英语词汇学习助手：导入文字型 PDF 选择题，使用 DeepSeek 补全词汇笔记，在网页中阅读、点读、纠错并导出 Markdown。

启动

Windows 下双击 start.cmd。首次运行安装依赖并构建网页，随后自动在浏览器打开本机地址；保留启动窗口，关闭该窗口即可结束服务。

需要 Node.js 20.19+（建议 22 或 24）和 Python 3.12+。当前机器已准备好 .venv、前端依赖和构建结果。启动脚本会优先使用已有的 Python 环境；新机器需要可以访问软件包源。

首次启动自动导入项目目录中的两份示例 PDF 及对应的现有 Markdown，并补齐全部 240 个选项的简要解释，全部标记为待核对。原句来自 PDF，旧 Markdown 中的填空句不用于改写原文。已有安装升级时会补齐未修改的示例笔记；人工修改过的内容保留，补齐内容作为候选版本。项目目录中的原 Markdown 文件不改写。

配置 DeepSeek

在网页右上角“朗读与模型设置”中填写 DeepSeek API Key 并保存。密钥只保存在本机 .env，不会由接口返回给前端。也可根据 .env.example 在本机配置 DEEPSEEK_API_KEY。模型默认为 deepseek-flash，可以修改。

导入 PDF 后点击“生成笔记”，题目文本将发送给 DeepSeek，并产生相应接口费用。没有密钥仍可阅读、点读、编辑和导出已导入的笔记。设置界面的“已配置”只表示存在密钥，不代表账户权限或余额已通过真实调用验证。

朗读

点击句子读整句；点击加粗目标词、选项词或单条搭配分别朗读。再次点击正在播放的内容可停止，切换内容会取消上一段。选择文字进行复制不触发朗读。

网页设置可选择英语音色及语速。音色来自浏览器或 Windows。当浏览器未暴露本机已安装的英语语音时，后端使用 Windows System.Speech 生成本机 WAV 音频并缓存，网页直接播放，无需云端 TTS。当前机器已验证 Microsoft Zira Desktop 可用。没有音色时，在 Windows 的时间和语言设置中添加英语语音，或换用 Edge/Chrome；浏览器提供的部分音色需要联网。

划词词典和选项解释

在应用页面选中英文单词、词组、搭配或整句，会出现“查词 / 翻译”菜单，也可朗读或复制所选内容。支持原句中的普通词、选项和跨越加粗词的整句选区。这里的全局指应用页面内；PDF 原页图片和正在编辑的输入框不参与划词。

内置 ECDICT 英汉词典，包含 768,739 条带中文释义的词条，并提供词形索引和常用搭配补充词库。命中的词条直接在本机查询，无需 API Key。词库、来源和许可在 backend/assets/。

未收录的表达、整句翻译，以及主动点击“语境释义”，使用已配置的 DeepSeek；会发送选中文字及所在题目的句子，并产生接口费用。返回结果按文本、语境和模型缓存在本机，查词不修改笔记。词典内容与模型释义会标明来源。

每个 A-D 选项都包含词性、释义、搭配和针对本题的简要解释：正确项说明成立依据，其他三项分别说明词义或搭配为何不适合。生成结果和手动保存均校验四项解释，不允许留空或过短；校验不能替代对解释准确性的人工核对。旧版本中尚未补齐的题目会进入“待完成”，可重新生成。

数据和恢复

• data/wordnote.sqlite3：题目、笔记、历史版本、任务、阅读位置、查词缓存。
• data/pdfs/：PDF 原件；data/previews/：原页预览。
• data/audio/：本机英语语音缓存。
• .env：本机模型密钥。
• Markdown 由当前结构化内容导出；外部编辑的 Markdown 不自动反向同步。
• 重复导入时可打开已有文档，或创建独立副本。
• 资料标题旁的垃圾桶可删除当前资料，确认后移除应用里的 PDF 副本、预览、题目、笔记、历史和生成记录。电脑上的原文件及已导出的 Markdown 不受影响；删除无法撤销。生成中的资料须先停止并等待任务结束。删除后可重新导入，删空资料库后仍保留导入入口。
• 任务按题保存，失败最多自动重试两次，中断后可继续生成未完成题目。
• 人工编辑后的题目重新生成会产生候选版本，用户决定是否采用。所有已保存版本可在历史中查看；原题改变后，不允许直接恢复对应其他原题的解释。
• 修改答案会标记待核对；修改原文会清空当前笔记以便重新生成，历史仍保留。

备份时先关闭服务，再复制整个 data 目录；需要迁移密钥时另行备份 .env。应用默认只监听 127.0.0.1。

开发与验证

.\.venv\Scripts\python.exe -m uvicorn backend.app:app --host 127.0.0.1 --port 8765
npm.cmd run dev

开发网页由 Vite 提供，/api 代理到 8765。正式本机运行时，后端同时提供 dist 网页，只需要一个服务。

.\.venv\Scripts\python.exe -m pytest tests -q
npm.cmd run build
npm.cmd run test:e2e

后端测试覆盖原文解析、数据校验、导入去重、删除及关联数据清理、编辑历史、生成任务、异常恢复、离线查词、语境缓存及选项解释迁移。模型请求使用模拟响应。浏览器测试使用已安装的 Edge，启动独立临时数据库和空密钥配置，不读取项目 .env，验证桌面和手机布局、搜索、点读、划词、编辑、删除、导出，以及本机真实英语音频播放。真实模型内容质量需要配置密钥后单独检查。

详细范围与验收标准见 设计方案.md。