需求分析
基于您的描述，您希望开发一个Tampermonkey用户脚本（Userscript），针对USMLE Step 1的Free 120在线测评网站（主要指NBME提供的互动测试界面，URL为https://orientation.nbme.org/Launch/USMLE/STPF1）。这个网站提供免费的120道样题，分成3个blocks（每个block 40题），模拟真实考试环境。脚本的核心功能是记录用户在测试中的正确/错误题，并为每道题显示解析（rationale）。以下是对需求的详细分析：
核心功能需求
-
记录正确/错误题：
- 跟踪用户在每个block中回答的题目。
- 在测试结束时，比较用户答案与正确答案，标记正确/错误。
- 存储记录（如本地存储），允许用户后续查看历史（如哪些题错了、错误率）。
- 需求假设：网站在测试结束时会显示正确答案列表（例如“1-B”格式），但不直接提供解析。脚本需要捕获这个信息或预定义正确答案。
-
显示每道题的解析：
- 为每道题显示详细解释，包括正确答案理由、错误选项分析。
- 需求假设：官方网站在线界面不直接显示解析（基于公开信息，在线版本主要用于模拟测试，解析通常在PDF样题文件中提供）。脚本可能需要从外部来源注入解析，如硬编码、从API加载或从用户提供的PDF提取。
- 显示方式：可在题目旁注入按钮/面板，点击显示解析；或在测试结束总结中显示。
非功能需求
- 兼容性：脚本需在Tampermonkey扩展中运行，支持Chrome/Firefox等浏览器。针对动态网页（JavaScript驱动的测试界面），需处理DOM变化。
- 用户体验：不干扰原网站功能；界面友好，如添加浮动面板或侧边栏显示记录和解析。支持“show answer mode”（如果网站有）或自定义模式。
- 数据存储与隐私：使用浏览器localStorage或GM_storage存储记录（避免服务器依赖）。不收集用户数据，确保合规（USMLE内容受版权保护，避免非法分发）。
- 性能：脚本轻量，不影响测试加载速度。处理120题规模，避免内存溢出。
- 安全性：不修改网站数据，仅观察和注入UI。遵守NBME条款，避免被检测为作弊工具。
假设与约束
- 网站结构假设：基于公开描述，界面类似于UWorld或NBME考试软件：题目显示在主区域，有选项（A-E）、提交按钮、定时器。结束时显示分数和正确答案列表。动态元素可能使用Angular/React等框架，需通过MutationObserver监控。
- 解析来源约束：官方在线界面无内置解析。需从PDF（https://www.usmle.org/sites/default/files/2021-10/Step_1_Sample_Items.pdf）或第三方解释（如Reddit/Bootcamp）获取。但版权限制：脚本不能自动下载/分发内容，建议用户手动提供或硬编码摘要。
- 技术约束：Tampermonkey脚本用JavaScript编写，不能访问外部API除非通过GM_xmlhttpRequest。Free 120偶尔更新（e.g., 2024版新增biostats/ethics题），脚本需易维护。
- 风险：如果网站检测到脚本，可能阻塞；解析准确性依赖来源；用户需了解这仅为学习工具，非官方。
利益相关者与优先级
- 用户：医学生准备USMLE，需要快速回顾错误题和解析。高优先：准确记录、易用显示。
- 开发者：您或他人，实现简单架构。中优先：可扩展性（如支持新版Free 120）。
- 优先级排序：先实现记录功能（核心），再添加解析显示（增强）。
规划
开发分为几个阶段，使用敏捷方法：先原型，后迭代。总时间估计：初学者1-2周（研究+编码+测试）。工具：浏览器开发者工具（检查DOM）、VS Code（编写JS）、Tampermonkey（测试）。
总体架构
- 脚本类型：Greasy Fork风格的Userscript，使用
@match针对特定URL。 - 组件：
- 观察器：使用MutationObserver监控页面变化，捕获题目、用户选择、提交事件。
- 存储层：localStorage保存用户答案、正确/错误标记（JSON格式，如
{block1: {q1: {userAnswer: 'B', correct: 'A', wrong: true}}}）。 - UI注入：用document.createElement添加按钮/模态框显示记录和解析。
- 解析数据：硬编码JSON数组（题号→解析文本），或从用户上传文件加载（避免版权问题）。
- 流程：
- 用户启动测试。
- 脚本监控每个题目的显示和提交，记录用户答案。
- 测试结束，捕获官方正确答案列表，计算正确/错误。
- 注入UI：显示总结表格、点击题号查看解析。
开发步骤
以下是详细规划，使用表格呈现：
| 阶段 | 任务 | 细节 | 预计时间 | 依赖/工具 |
|---|---|---|---|---|
| 1. 研究与准备 | 分析网站结构 | 访问https://orientation.nbme.org/Launch/USMLE/STPF1，选择“All Blocks”运行测试。使用浏览器DevTools检查DOM元素（如题目ID、答案选项class、结束页面表格）。识别关键selector（e.g., ‘.question-text’, ‘.answer-options’）。测试动态变化。 | 1-2天 | 浏览器DevTools |
| 收集解析数据 | 下载官方PDF样题，提取120题的正确答案和rationale（手动转JSON）。或使用第三方如Bootcamp解释（https://bootcamp.com/blog/new-free-120-nbme-step-1-explanations）。注意：仅用于个人，勿分发。 | 1天 | PDF阅读器，JSON编辑器 | |
| 定义脚本元数据 | 编写@name, @version, @match (e.g., // @match https://orientation.nbme.org/* )，@grant (GM_xmlhttpRequest if需外部加载)。 | 0.5天 | Tampermonkey | |
| 2. 核心开发 | 实现记录功能 | - 添加事件监听：on question load，捕获题号/文本。 - on answer select/submit，存储用户选择。 - on test end，解析官方答案表，比较并标记错误。 - 保存到localStorage。 | 3-4天 | JavaScript, MutationObserver |
| 实现解析显示 | - 创建解析数据库（JSON: {qId: {answer: ‘A’, rationale: ‘解释文本’}}）。 - 注入按钮到每个题或总结页，点击显示模态框。 - 如果PDF更新，支持用户导入功能（FileReader API）。 | 2-3天 | JavaScript, CSS for UI | |
| 添加UI增强 | - 总结面板：显示错误题列表、百分比。 - 导出功能：JSON下载历史记录。 - 错误处理：如果网站更新，fallback模式。 | 2天 | HTML/CSS/JS | |
| 3. 测试与迭代 | 单元测试 | 测试单个功能：模拟DOM变化，验证记录准确。 | 1天 | Jest (可选) 或手动 |
| 端到端测试 | 在真实网站运行完整测试，检查兼容性、性能。模拟不同浏览器。 | 2天 | Tampermonkey | |
| 反馈迭代 | 测试边缘 case（如中途刷新、blocks中断）。优化UI基于用户反馈。 | 1-2天 | - | |
| 4. 部署与维护 | 发布脚本 | 上传到Greasy Fork (可选)，或本地安装。添加更新日志。 | 0.5天 | Greasy Fork |
| 维护计划 | 监控Free 120更新（每年可能），调整selector/解析数据。添加配置选项（如切换解析来源）。 | 持续 | GitHub repo |
潜在挑战与缓解
- 动态网站：如果界面用Shadow DOM，需pierce查询。缓解：用querySelectorAll深搜。
- 版权与合法性：勿包含官方内容；建议用户自行添加解析。缓解：脚本仅提供框架。
- 更新兼容：Free 120不时更新（如2024版加新题）。缓解：版本检测，允许用户编辑数据。
- 资源：参考Tampermonkey文档、Stack Overflow上的Userscript示例。示例代码起点：一个简单DOM观察器脚本。
这个规划提供了一个可执行的蓝图。如果您提供更多细节（如具体网站行为或解析来源），我可以进一步细化或帮助草拟代码大纲。