虚拟实验平台开发方案
虚拟实验平台围绕“操作装置、取得读数、分析数据、解释结果”组织学习过程。每个实验具有独立页面、物理模型、参数说明、文献依据和验证记录，共用站点导航与资源发布流程。
单摆虚拟实验是首个案例。其运动、计时、拟合和摆角扫描由浏览器执行，原报告数据作为独立的观测对照。对应的模型依据说明方程、参数身份、适用范围及引用；维护指南提供文件入口与复现命令。
单摆示例：从测量问题组织页面
用户首先选择有效摆长、初始摆角、重力加速度和计数周期数，释放摆球后观察运动。自动记录保存理想模型的完整周期计时，手动计时记录用户选择的仿真时间间隔；随后改变摆长，收集多组数据并拟合周期平方与摆长的关系。
表 1 单摆案例的交互与学习目标
| 环节 | 页面行为 | 需要理解的物理问题 |
|---|---|---|
| 设置参数 | 改变摆长、初始角度、重力和计数周期数 | 量纲、周期尺度及参数作用 |
| 观察运动 | 播放、暂停、复位，比较非线性轨迹与小角度解 | 有限摆角造成的周期和相位差 |
| 记录计时 | 自动记录完整周期时间，或按同向过点手动开始与停止 | 完整周期的计数与计时方法 |
| 拟合数据 | 按数据来源和相同条件筛选，拟合 $T^2=aL+b$ | 斜率、截距、残差与重力估计 |
| 扫描摆角 | 观察周期增量和小角度公式的偏差 | 近似的适用条件 |
| 观测对照 | 读取原报告的规范数据及派生量 | 模型情景与实际观测的联系 |
| 保存结果 | 在本浏览器保留记录，导出 CSV 与 JSON | 复查参数、单位、数据身份与完整数值 |
手动计时与动画使用同一仿真时钟；暂停时计时同步冻结，页面进入后台时暂停运动。自动计时由精确周期关系生成 $NT$，其确定性结果用于研究模型关系。手动计时保留交互操作带来的起止选择。两类记录分别拟合，原报告观测另列。
拟合使用至少三条记录和两个不同的摆长。对虚拟记录保持重力参数、初始摆角及数据来源一致，再比较摆长与周期。页面给出的标准误来自回归残差，解释范围限于当前回归模型；仪器与系统效应需要相应的测量依据和不确定度预算。
单摆示例：模型与应用界面分层
平台使用原生 ES modules。各实验的物理函数独立于页面，绘图接收明确的数据序列，控制器负责用户操作与状态。simulations/registry.json关联45项实验的资源、文献和验收入口；页面通过同一GitHub Pages构建发布。下表以单摆说明分层。
表 2 首个案例的代码与数据分工
| 文件 | 职责 |
|---|---|
simulations/pendulum/model.mjs |
参数校验、非线性周期、数值积分、能量、自动计时与拟合 |
simulations/pendulum/chart.mjs |
SVG 坐标轴、曲线、观测点、标注及自适应布局 |
simulations/pendulum/app.mjs |
控件联动、仿真时钟、记录筛选、本地保存与导出 |
simulations/pendulum/lab.css |
页面布局、中文宋体、西文与数字 Times New Roman、图表样式 |
simulations/pendulum/index.html |
实验操作、数据分析、模型说明与可访问语义 |
simulations/pendulum/observations.json |
原报告观测、派生量、来源及源文件哈希 |
docs/simulation/pendulum-reference.json |
SciPy 参考计算、参数组、容差及浏览器模型对照记录 |
非线性周期由算术几何平均法计算第一类完全椭圆积分；运动轨迹用四阶 Runge–Kutta 方法积分。两条计算路径分别服务于周期读数和连续运动展示，验证时相互联系，并与独立计算对照。具体数学定义和参数范围见模型依据。
观测 JSON 由 scripts/validate_pendulum_simulation.py 从实验 CSV、配置、来源记录和已有结果生成。人工维护的观测源仍位于 experiments/course-01/pendulum/data/；源哈希用于定位网页所用的具体输入。
文献证据先于模型扩展
每个实验维护一张可追溯的证据矩阵。方程和参数分别记录依据，模型适用域与软件控件范围分别说明；计算方法另有数值验证。
表 3 实验模型的证据矩阵
| 内容 | 记录要点 | 对应验证 |
|---|---|---|
| 模型方程 | 文献条目、章节或页码、公式定位、符号定义 | 解析关系、物理极限、独立推导 |
| 实验参数 | 来源文档、单位、有效数字、实测或情景身份 | 单位换算、源表复核、输入哈希 |
| 适用范围 | 模型假设、初始与边界条件、参数域 | 边界条件、极限状态及参数域测试 |
| 数值算法 | 离散方法、步长或误差容限、特殊函数约定 | 收敛性、守恒量、独立求解器比较 |
| 测量解释 | 读数形成过程、拟合模型、误差定义 | 已知算例、合成数据与观测对照 |
基础理论可复用公共教材与方法文献，具体装置、修正项和参数需要逐实验核对。文献条目使用稳定 DOI 或出版机构入口，证据定位到实际阅读的正文。后续增加阻尼、仪器分辨率或其他效应时，先补充参数来源和验证方案，再开放相应控件。
可复现与发布流程
在仓库根目录准备 Python 项目依赖与 Node.js 后，运行：
python scripts/validate_simulations.py --experiment course-01/pendulum
python scripts/validate_simulations.py --all
python -m pytest
python scripts/agent_catalog.py build
python scripts/agent_catalog.py build --check
python scripts/check_agent_docs.py
python scripts/build_pages.py
python scripts/check_pages.py --report .build/pages/verification.json
验证脚本用 SciPy 的椭圆积分与 DOP853 求解器构造独立基准，再检验浏览器模型的周期、轨迹、能量和步长收敛性。模型单元测试同时检查输入范围、标度关系、计时与拟合条件。验证结果中的状态、容差、环境和源哈希共同描述该次检查。
站点构建将页面和运行资源发布到 simulations/pendulum/，并添加公共导航、MathJax、规范 URL 和站点地图。本地预览遵循网页构建指南，使用 HTTP 并保留 GitHub 项目子路径。前端验收覆盖默认状态、参数变化、计时暂停、记录筛选、导出、数学排版和窄屏布局。
正式报告、Jupyter 与 Wolfram Notebook 保留各自的复现流程。平台更新以原成稿的文件哈希为回归依据，新增网页入口、模型和验证记录单独核对。
系列实验与公共接口
表 4 系列实验的模型与操作分工
| 实验组 | 重点 | 验证方式 |
|---|---|---|
| 跨领域先导 | RLC幅相扫频、牛顿环测微、弦驻波 | 独立电路方程、光程与曲率、波动本征关系 |
| 基础测量 | 称量、运动探针、周期定标、成像与光强 | 守恒、运动学、几何及投影关系 |
| 电路与仪表 | 滑片、换接、调零、量程、游标与参数反演 | 节点/回路方程、加载、复阻抗和平衡 |
| 测角与光学读数 | 双游标、反射折射、标尺、旋光与条纹计数 | 矢量光线、圆周角差及独立成像计算 |
| 动力学与场 | 振动相位、刚体质量、探针与四极性换向 | ODE、质量积分、场边界、线积分和奇偶投影 |
| 力热与材料 | 加载、力定标、落球、温升与热传导 | 几何、低Re条件、能量分项与空间收敛 |
| 器件与计算成像 | 器件工作点、复场空间滤波与全息传播 | 厂商条件、KCL、独立FFT、采样与传播收敛 |
各实验保留独立的物理求解、测量步骤和拟合条件。统一构建负责字体与数学资源、站点导航、资源白名单、项目子路径、验收哈希与Agent目录；通用执行器负责语法检查、模型测试和独立参考计算。记录和导出共同保存实验标识、模型版本、参数与单位、来源类别、原始读数及派生结果，具体列由测量方式决定。
每项沿“资料与全文 → 模型规格 → 实现 → 数值验证 → 前端验收 → 上线”推进。检查点保存源与代码哈希、结果、失败原因和下一步；只重跑变更影响的阶段。科学与前端通过后，页面加入正式目录，共享变更触发已上线实验回归。
使用系列科学入口阅读公共理论与逐项证据，使用检索和复现指南接手代码与构建。原有报告、Jupyter和Wolfram沿已批准基线保持，并以文件哈希核对。