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

# 谊安学助手实施开发方案

日期：2026-10-18。依据 [需求.md](需求.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 全部在本地拦截，未操作真实学习或考试记录，真实账号流程仍需实站验收。

## 9. 2.1.3 调整：租约等待与持久日志

- 将同类租约冲突与人工确认等待区分。临时冲突保留自动调度资格，在旧占用失效后重新领取；有效占用不强制抢占。领取成功时清除旧租约等待文案并按实际视频、考试状态更新面板。
- 完整导航及受控恢复仍须核对同一会话、任务、账号、目标页面和有效的一次性标记；手动刷新或新开普通页面继续默认暂停。所有实际动作仍受租约、全局暂停和当前页面证据约束。
- 运行日志继续显示最近 500 条，“清空显示”只清运行日志显示。新增“持续记录诊断日志”开关并默认开启，独立持久保存最近 2000 条诊断记录，刷新后保留；“导出诊断 JSON”“导出诊断 TXT”导出已存记录，“清空已保存诊断”只删除诊断。关闭开关只停止新增，已有记录仍可导出；清空不删除任务检查点、原始考试计时或题库。诊断不含完整题干、选项、答案和 URL 查询参数，多页写入需避免旧页面把新记录覆盖。
- 归档 `01/70-es2015` 的学习地图入口调用 `onSelect` 后通过基类 `navigate` 调用 Angular Router；课程及考试入口均无直接 `window.open`。这排除了该归档入口必然保留旧地图标签的假设，但不推断用户的其他入口行为。
- 本地已复现同类租约领取失败后不再重试、成功恢复后仍显示旧等待提示两项缺陷；这不代表已确认用户必然有多个标签。验证重点为：同类领取失败后租约过期能重试、恢复后提示与动作一致、有效执行器保持互斥、暂停及人工等待仍有效，以及诊断默认值/关闭后可导出/刷新保留/两种清空/2000 条上限和敏感内容过滤。结果以本次实际回归记录为准，不将静态样本及模拟通过等同于真实账号验收。
- 最终验证：`npm test` 的 18 套回归通过；执行权恢复 12 项检查、原学习引擎 52 项检查通过。已实际下载诊断 JSON/TXT 并核对执行权事件、刷新恢复、关闭及清空效果，验证 URL 参数和题目正文不进入导出；桌面和 390px 窄屏检查通过，业务 URL 全部本地拦截。