yianxue-assistant/实施开发方案.md

谊安学助手实施开发方案

日期：2026-10-18。依据 需求.md，在现有用户脚本上增量开发，完成后构建、验证、提交并推送当前仓库。

1. 开发顺序与交付

阶段	实施内容	验收重点
统一题库	三岗位来源统一存储、检索与精确匹配；旧数据迁移；生成统一 CSV	5520 条来源记录不丢失；无岗位文件可用；重复导入不增生；冲突不覆盖
六栏面板	总览、视频、考试、题库、控制台、其他设置；保留拖拽与折叠	窄屏可操作；全局暂停常驻；切栏不启动任务或导出
学习调度	从实际页面发现任务，按稳定标识排队；四种模式，顺序与并行	不猜业务接口；已完成不重做；受前置条件约束；独立视频与考试任务不重复领取
视频与恢复	真实播放器倍速、平台记录、课中题检测、受限恢复及检查点	播放结束不误判完成；主动暂停/弹题不刷新；重试有上限；人工重开默认暂停
考试流程	主题关联预检、整卷预检、逐题间隔、分值读取、选中全文核验、交卷	严格大于 80 分；至少 6 分钟；80 分等待人工；真实提交结果确认
集成发布	既有复制/搜索/导出/范围/拖拽回归，更新文档与用户脚本	本地模拟业务页面完成交互测试；无外网业务请求；提交并推送远程

2. 模块边界

• bank-store.js、answer-matcher.js：统一题库与证据匹配，岗位仅作来源信息。
• assistant-panel.js：六个功能栏及状态展示，仅通过回调发出用户操作。
• learning-engine.js：任务、视频、恢复、检查点、日志及多页面协调。
• exam-controller.js：当前考试的主题依据、原始进入时间、分值核算及交卷状态机。
• answer-runner.js：按配置间隔点击真实选项，保持每步上下文及全文核验。
• practice-exporter.js：统一协调页面识别、用户设置、模块生命周期及站点范围。
• build-userscript.mjs：发布单文件用户脚本，名称继续为“谊安学助手 2.0”。

3. 状态与操作约束

• 用户启动任务才调度。切栏、搜索、读取日志不改变运行状态。
• 课中题归视频任务；考试交卷规则不应用到课中题或练习。
• 考试先核对主题关联；仅相似词不能授权自动答题。完整题干预检发生在试卷加载后，不能将已进入试卷的场次称为未开考。
• 预计得分仅计入答案唯一、当前选中全文一致的题目实际分值。未知、冲突及分值不明不算正分。
• 用户手动作答、关停自动选择、暂停、题库/主题变更均取消旧交卷计划；继续前重新核验。
• 提交过程保存状态；结果不明先等待检查，不重复点击。网站倒计时独立于脚本暂停。
• 同一任务只由一个有效执行页持有；并行受阻时显示原因，不显示虚假的运行成功。

4. 样本与验证策略

• 保存网页按静态 DOM 解析，不运行其中原站脚本，也不向业务服务器发送请求。
• 使用真实考试样本验证分值标记、40 题全文匹配及选项换序，使用独立本地模型验证网站选中状态回读。
• 使用可控制时钟与本地提交模型覆盖 80/大于 80、6 分钟前后、人工暂停、未知分值、重复提交及恢复。
• 使用课程/视频模拟页面覆盖倍率、平台完成条件、课中弹题阻塞、卡顿恢复和多页协调。
• 用桌面与窄屏浏览器验证六栏、拖拽、切换状态及控制台；截图保存在系统临时目录。

5. 真实环境验收边界

当前包未包含实际课中弹题内容，也没有完整登录后的课程解锁、平台后台播放及正式交卷结果流程。实现采用保守 DOM 识别：结构或结果无法确认时进入等待人工，不猜答案、不伪造学习进度、不绕过网站验证。发布记录须分别说明本地已验证能力和需要在真实环境核实的流程。

验收完成后将需求、实施方案、源代码、测试、统一题库和构建后的脚本一并提交，推送至 ssh://git@192.168.10.31:2222/qishizhe/yianxue-shauti.git。

6. 本次实现与验证记录

• 发布版本 2.1.0，脚本名称保持“谊安学助手 2.0”。以上模块已接入构建后的单文件脚本，六栏共享全局控制及状态。
• 统一题库保留 5520 条来源记录，2458 道唯一题、2459 个答案组合、1 道冲突题；合并脚本核对原 28 个 CSV 的字段和真实导入结果。
• 增加统一题库、课程状态机、课中题、考试交卷、六栏及完整考试/视频流程回归，连同既有用例共 13 个测试套件。
• 浏览器验证使用本地 Chrome / Playwright，覆盖桌面、390px 窄屏及 320×480 小窗口；Browser 插件在当前环境不可用。截图位于系统临时目录，不提交至仓库。
• 实际保存题目用于验证全文、类型、分值与选项乱序。课程任务、平台完成、并行心跳、课中题判分和提交结果通过独立本地模型验证，没有参加真实考试或调用业务提交接口。
• 补充回归保护异步保存期间的暂停/题库/页面/分值变化、重考计时隔离、未知提交防重复、课中题选中后立即暂停、视频先结束后的并行汇总及平台完成状态展示。

代码交付并不替代第 5 节的真实账号环境验收；未识别的页面结构、身份验证、结果或后台限制会停止受影响任务并提示人工处理。