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

谊安学助手实施开发方案

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

1. 开发顺序与交付

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

2. 模块边界

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

3. 状态与操作约束

• 用户启动任务才调度。切栏、搜索、读取日志不改变运行状态。
• 课中题归视频任务；考试交卷规则不应用到课中题或练习。
• 考试先核对主题关联；仅相似词不能授权自动答题。完整题干预检发生在试卷加载后，不能将已进入试卷的场次称为未开考。
• 预计得分仅计入答案唯一、当前选中全文一致的题目实际分值。未知、冲突及分值不明不算正分。
• “题目不全时手动确认交卷”开关默认开启：任意题目未匹配、冲突、未核验或不支持，以及正常未答完提醒均等待人工在网站确认。关闭时允许网页整卷完整、全部可匹配题处理并全文核验、预计得分严格大于 80 分且满 6 分钟的部分题库试卷自动交卷及确认正常未答完提醒；未知题不猜答、不计正分。
• 网页整卷和答题卡完整、主题关联明确、分值与分制可核对、可匹配题均已全文核验、预计得分严格大于 80 分和达到最早交卷时长等通用门槛，在任何开关状态下均生效。
• 用户手动作答、关停自动选择、暂停、题库/主题变更均取消旧交卷计划；继续前重新核验。
• 提交过程保存状态；结果不明先等待检查，不重复点击。网站倒计时独立于脚本暂停。
• 同一任务只由一个有效执行页持有；并行受阻时显示原因，不显示虚假的运行成功。

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 节的真实账号环境验收；未识别的页面结构、身份验证、结果或后台限制会停止受影响任务并提示人工处理。

7. 2.1.1 调整：缺题人工确认开关

• “考试答题”栏新增“题目不全时手动确认交卷”开关（manualConfirmIncomplete），默认开启，设置跨页面及刷新保存。
• 开启时要求整卷每题唯一精确匹配且当前选中全文核验通过，题库缺题、冲突、未核验、无法唯一映射或不支持时等待人工；网站正常未答完提醒也由用户确认。关闭时恢复部分题库自动交卷，保留题库主题预检、全部可匹配题已处理并全文核验、预计得分严格大于 80 分及默认 6 分钟等条件，允许自动确认本场正常未答完提醒。
• 网页题目或答题卡加载不全、分值或分制不明、主题关联不明确、可匹配题未处理或核验失败、80 分及以下、计时未到、暂停、身份验证及结果不明等条件始终阻止自动交卷。开关不能覆盖这些通用门槛。
• 在入口、提交前复查及确认阶段统一核对开关和通用门槛。切换开关立即暂停当前答题与交卷计划，须用户明确继续后重验，不能关闭时立即提交。未知题不猜答，人工补选的未知答案不自动计正分。
• 本次验收重点：网页整卷完整、已核验 84 分但有 4 题未匹配时，开关开启则满 6 分钟仍不点击提交/确认，关闭并明确继续重验后可按原规则交卷及确认正常未答完提醒；完整 100 分且每题核验通过，达到时长并满足其他条件后可正常自动交卷。另覆盖任何开关状态下的加载不全、分值不明、80 分、主题不明，以及开关默认值、持久化和切换中止。
• 本节记录本次实施与验收范围，测试结果以本次实际执行记录为准。

8. 2.1.2 调整：续播、单次机会保护与视频后续考试

1. 在视频栏提供三个独立、默认开启并保存的开关：autoContinuePlayback（自动继续上次播放）、skipSingleAttemptQuiz（仅 1 次答题机会时交给我处理）、resumePlaybackOnReturn（切回页面时自动恢复播放）。设置由协调器传给任务、课中题及考试模块，跨页恢复时保留当前策略。
2. 续播只处理唯一可见、正文匹配“是否继续上次播放的位置？”且同时含“重新开始”“继续播放”两个按钮的网站弹窗，正常点击“继续播放”。关闭开关、已暂停任务、弹窗不明或存在待处理题目时，不擅自播放或选择其他弹窗。
3. 用户确认的单次规则为“只剩 1 次或总共仅允许 1 次答题机会时，交给我手动答题”。公共机会数模块只读取当前弹题/考试范围内可见的允许、总、剩余次数和实际补考文案，1 次或 0 次阻止受影响的自动操作；明确大于 1 次保留证据，未显示时不推断。题干、选项、参考答案、隐藏节点、已答次数、已答题数和交卷人数都不作为机会数证据。
4. 在课中题选项/提交、考试入口及自动答题/交卷前复核该规则，避免只在首次读页检查。详情页机会数证据只用于同一受控考试流，不能把其他课程的次数借给当前试卷。关闭保护仍须通过原有题库全文匹配、分值、计时和交卷条件。
5. 旧站静态代码显示 visibilitychange 的后台分支主动暂停视频，没有返回恢复逻辑。本版在切页前保存真实播放状态，后台暂停显示“后台暂停，等待返回”，返回后按开关及实际任务状态续播。手动暂停播放器、全局或局部暂停、弹题和待人工状态优先；后台暂停不触发故障刷新，不伪造播放时长，不承诺后台一直播放。
6. 新安装默认 all，即“视频＋考试（含课中答题）”；已有保存的模式继续使用，不覆盖用户显式的仅视频选择。顺序模式在平台确认视频完成、关联考试开放后才进入考试，仍受单次机会及题库预检约束；video、videoQuiz 不进入独立或关联考试。视频栏根据当前模式及保护设置说明后续流程，不增设重复按钮。

本次补充包 08.zip 只有 Angular 初始外壳，没有播放器、弹窗、次数提示 DOM 或业务 JS 资源。适配参考旧完整归档的静态模板及脚本片段，不执行下载页面中的原站代码。旧源码已提供续播正文和两个按钮、后台主动暂停、不及格，还可补考 N 次 及 还可重考 N 次 的静态证据；真实账号的播放器和考试状态仍需实站确认。

最终本地验证：npm test 的 15 套回归全部通过，学习引擎另完成 52 项检查。已覆盖三个开关默认值、保存、回读及切栏不触发动作，精确续播与未知弹窗，后台暂停与返回恢复、关闭恢复及用户手动暂停优先，明确 0/1/多次和缺失机会数、补考按钮、隐藏及题干干扰，课中题与考试共同保护，新安装默认与旧模式保留，以及平台确认完成后串联考试。额外验证共享设置不同键并发不丢失、旧读取及旧设置快照不覆盖新值、暂停写入期间不重新启动弹题、不同考试的次数证据隔离、关联考试完整导航及完成后不重复加入任务。桌面及 390px 窄屏检查通过；业务 URL 全部在本地拦截，未操作真实学习或考试记录，真实账号流程仍需实站验收。