NeuraDock 视觉认知负荷代理教程：一个质量门控的开源EEG工作流，用于Alpha动态和实时应用

# NeuraDock 视觉认知负荷智能体教程：面向Alpha动态与实时应用的质量门控开源EEG工作流 来源：https://arxiv.org/html/2606.26518 徐志远，戴月清，李俊林，罗俊文 上海脉冲元智能科技有限公司 (NeuraDock) (教程文稿，为发布版本更新：2026.06.24) ###### 摘要 本教程论文提供了一份逐步可复现的 NeuraDock Agent 操作指南，这是一个专注于 Alpha 动态和视觉认知负荷分析的开源 EEG 智能体。目标是实践性的：读者应能安装该智能体，运行 EEG 预处理和质量控制，生成 Alpha 动态图，执行被试内静息/任务视觉认知负荷比较，运行公开小数据集分析并将其与参考验证摘要进行比较，启动在线仪表盘，从外部应用调用实时 API，以及使用 LLM 解释层来解析质量风险。现有的 EEG 工具箱提供了优秀的离线分析能力，但要搭建一个实时的、质量门控的认知负荷流水线，往往需要手动连接采集、自定义 QC、Alpha 特征提取和 Web API；本教程弥合了离线到在线的这一鸿沟。本教程采用质量门控工作流：下游的 Alpha 和工作负荷指标仅在预处理和质量控制门控后计算，而非直接从原始 EEG 计算。在附带的小数据集验证中，该智能体处理了 18 条记录，生成了 10 个被试内比较，在 10 个对比中有 7 个观察到任务相关的后部 Alpha 抑制，估计了被试内重复性的初步证据，并测定了本地在线 API 延迟。本教程面向那些希望从 EEG 文件到实时视觉认知负荷原型有一条透明路径的研究人员、开发者和应用团队。 关键词：EEG 教程；视觉认知负荷；Alpha 动态；后部 Alpha 抑制；开源；实时 API；质量控制；NeuraDock Agent ## 1 读者目标 本教程作为一篇动手实践的论文编写。通过本教程，读者应能重现以下输出： - •EEG 预处理与信号质量报告。 - •干净/质量门控的 EEG 输出文件。 - •时域、频域和时频域的 Alpha 动态图。 - •被试内离线静息/任务认知负荷比较图。 - •小数据集每条记录及被试内比较的输出。 - •实时本地仪表盘和 API 端点。 - •基于 LLM 的 EEG 计算结果与质量风险解释。 更重要的是，教程结束时读者将拥有一个本地 HTTP 端点，可向应用程序流式传输视觉工作负荷指数和质量标志。从离线的 EEG 脚本到实时 API 的这条路径通常是让一个有前景的认知负荷想法转化为数周基础设施工作的关键部分。教程同时说明该工作流不是什么：它不是临床诊断系统，不是注意力或疲劳诊断，也不是跨被试认知能力排名方法。 ## 2 为何需要一个教程工作流 通用的 EEG 工具，如 MNE-Python、EEGLAB 和 BrainFlow，强大且开源，但它们是广泛的工具包，而非专注的认知负荷工作流[1 (https://arxiv.org/html/2606.26518#bib.bib1),2 (https://arxiv.org/html/2606.26518#bib.bib2),4 (https://arxiv.org/html/2606.26518#bib.bib4),5 (https://arxiv.org/html/2606.26518#bib.bib5),3 (https://arxiv.org/html/2606.26518#bib.bib3)]。商业及设备专用系统如 Emotiv Cortex 和 Neurosity SDK 工作流提供实时数据访问，但它们并非完全开源、可本地审计的认知负荷分析栈[6 (https://arxiv.org/html/2606.26518#bib.bib6),7 (https://arxiv.org/html/2606.26518#bib.bib7)]。现有的认知负荷研究往往停留在离线层面，并未提供从预处理到实时 API 的完整路径。这就造成了实际的“为何现在”鸿沟：构建自适应界面、XR 演示、HMI 实验或内部工作负荷仪表盘的团队可以离线分析 EEG，但仍然难以将同一逻辑部署为一个其他应用每秒可调用一次的质量门控服务。NeuraDock Agent 通过打包一个专注的教程工作流程来填补这一空缺： 安装 -> 检查配置文件 -> 预处理并质量门控 EEG -> 分析 Alpha 动态 -> 比较被试内静息/任务 -> 运行公开小数据集分析 -> 启动在线仪表盘/API -> 使用 LLM 摘要层解释结果 其价值不仅在于特征提取器，而在于一条从 EEG 数据到认知负荷应用原型的可审计、可重复的路径。 ## 3 教程假设 以下命令假设使用 Windows PowerShell，且当前目录为克隆后的 `eeg-workstation-agent` 仓库根目录。所有路径均相对于该仓库；无需特定机器的安装路径。简短示例使用由仓库数据助手下载并经过 SHA256 验证的公共文件： data_examples\alpha\open_closed_eye2.txt data_examples\rest_task\rest_S01_1.txt data_examples\rest_task\task_S01_1.txt 工作流使用七通道 NeuraDock 配置文件和 250 Hz 采样率。后部和顶枕通道用于视觉 Alpha 特征提取。 ## 4 第1步：安装并检查智能体 克隆开源仓库并进入其根目录： git clone https://github.com/Neuradock/eeg-workstation-agent.git cd eeg-workstation-agent 创建虚拟环境并安装智能体： py -m venv .venv .\.venv\Scripts\python.exe -m pip install --upgrade pip .\.venv\Scripts\python.exe -m pip install -e ".[dev]" 下载第2-4步使用的三个公开示例记录： .\.venv\Scripts\python.exe scripts\download_example_data.py 下载器会对照发布时固定的 SHA256 值验证每个文件。人类 EEG 记录保存在单独的数据仓库中；MIT 软件许可不会自动替代数据仓库的使用与再分发条款。 检查版本与硬件配置文件： .\.venv\Scripts\neuradock-agent.exe --version .\.venv\Scripts\neuradock-agent.exe profile 预期版本：本教程运行实际产生的硬件配置文件输出为： { "profile_version":"1.1", "device":"NeuraDockEEGWorkstation", "hardware_revision":"public-profile-v2", "sampling_rate_hz":250, "channels":["CP5","CP6","PO3","PO4","O1","Oz","O2"], "amplitude_unit":"microvolts", "line_frequency_hz":50.0, "tcp_default_ip":"127.0.0.1", "tcp_default_port":9600, "tcp_start_command":"start", "packet_total_channels":8, "packet_used_channels":7, "bluetooth_samples_per_packet":5, "quality":{ "line_noise_power":10.0, "emg_power":20.0, "outlier_count_per_second":2, "outlier_absolute_amplitude":100.0, "bad_channel_segment_ratio":0.4, "minimum_neighbor_correlation":0.15 }, "channel_count":7 } 这确认了本教程使用 7 通道配置文件，采样率 250 Hz，后部通道 PO3、PO4、O1、Oz 和 O2 可用于视觉 Alpha 特征。TCP 默认设置也解释了为何在线模式仅需 IP 地址和端口即可启动。 ### 4.1 硬件调优设计 本教程中的 NeuraDock 导联配置并非随意选择。后部环 PO3/PO4/O1/Oz/O2 靶向枕叶和顶枕叶的 Alpha 动态，这是本教程用于视觉认知负荷估计的主要信号家族。侧方通道 CP5/CP6 提供额外的空间上下文，用于质量检查和后部不对称性解释。该智能体可吸收形状相同的通用 7 通道数据，但其空间 QC 阈值、后部通道分组以及右减左不对称指标是针对此 NeuraDock 几何结构校准的。为获得最佳效果，请使用 NeuraDock 硬件配置文件，而不要将该智能体视为任意 EEG 文件的解析器。 ## 5 第2步：运行 EEG 预处理与质量控制 预处理是第一个科学检查点。运行： .\.venv\Scripts\neuradock-agent.exe analyze 'data_examples\alpha\open_closed_eye2.txt' --workflow quality 典型输出结构： runs/\_quality/ |-- report.md |-- results.json |-- clean_eeg_data.npz '-- figures/ |-- signal_quality.png '-- clean_signal.png 如何解读这一步： - •`report.md` 是人可读的 QC 报告。 - •`results.json` 包含保留率、警告信息、被拒绝的片段信息以及坏道候选。 - •`clean_eeg_data.npz` 存储经过清理/质量门控的 EEG 数据。 - •图形有助于检查保留信号的质量和被拒绝的部分。 本教程对 `open_closed_eye2.txt` 的实际运行结果： 摘要: signal_quality:retained=65.9%, status=warning raw_shape:[7,13210] clean_shape:[7,8710] retention_rate:0.659 rejected_segment_count:18 bad_channel_candidates:[] warnings: - 只有65.9%的样本通过了片段级QC。 - 身体活动启发式: slight_activity_or_mild_muscle_tension. 该结果可用于教程目的，但并非完美干净的记录。智能体明确将运行标记为 `warning`，因为大约三分之一的样本被片段级 QC 拒绝。这正是期望的行为：下游 Alpha 分析应当继承这一警惕性，而非假装信号是干净的。 参考图 1：实际 `open_closed_eye2.txt` 预处理运行的信号质量图。报告保留了 65.9% 的样本，并标记了轻微身体活动或肌肉紧张。 参考图 2：`open_closed_eye2.txt` 经预处理和质量门控后的干净 EEG 信号。后续教程指标基于此质量门控工作流，而非仅基于原始 EEG。 这是一个核心设计原则：后续 Alpha 和工作负荷指标基于预处理/质量门控工作流，而非直接基于原始 EEG。 ## 6 第3步：分析 Alpha 动态 运行 Alpha 动态工作流： .\.venv\Scripts\neuradock-agent.exe analyze 'data_examples\alpha\open_closed_eye2.txt' --workflow alpha_dynamics 典型输出结构： runs/\_alpha_dynamics/ |-- report.md |-- results.json '-- figures/ |-- alpha_time_domain.png |-- alpha_frequency_domain.png '-- alpha_time_frequency.png Alpha 动态工作流自动识别弱 Alpha、基线 Alpha、强 Alpha、相对于基线的 Alpha 抑制、峰值 Alpha 频率以及右减左 Alpha 不对称性。 实际 `open_closed_eye2.txt` 运行结果： 摘要: alpha_dynamics: weak=4, strong=4, max_suppression=+0.731 quality_status:warning retention_rate:0.659 valid_window_count:10 excluded_window_count:39 weak_alpha/baseline_alpha/strong:4/2/4 max_alpha_suppression_from_baseline:0.731 median_alpha_peak_hz:10.25 median_alpha_asymmetry_right_minus_left:0.309 warnings: - 只有65.9%的样本通过了片段级QC。 - 39个Alpha窗口因干净保留率低于80%而被排除。 此输出有意保持保守。只有 10 个 Alpha 窗口通过质量验证，因此 Alpha 动态可用作特征流水线的演示，但应结合 QC 警告进行解读。 参考图 3：实际 `open_closed_eye2.txt` Alpha 动态时频输出。这替代了较早的任务记录示例，并与本教程步骤中的命令匹配。 参考图 4：从同一 `open_closed_eye2.txt` 运行生成的时域与频域 Alpha 动态图。 ## 7 第4步：运行离线静息/任务视觉认知负荷比较 对于离线工作负荷比较，始终将被试与其自身基线进行比较。先使用静息文件，再使用任务文件： .\.venv\Scripts\neuradock-agent.exe analyze 'data_examples\rest_task\rest_S01_1.txt' 'data_examples\rest_task\task_S01_1.txt' --workflow visual_cognition_comparison 使用显式标签： .\.venv\Scripts\neuradock-agent.exe analyze 'data_examples\rest_task\rest_S01_1.txt' 'data_examples\rest_task\task_S01_1.txt' --workflow visual_cognition_comparison --condition-labels Rest Task 典型输出结构： runs/\_visual_cognitive_load_comparison/ |-- report.md |-- results.json '-- figures/ |-- visual_cognitive_load_comparison.png |-- rest_visual_cognitive_load.png '-- task_visual_cognitive_load.png 解释规则： Task 减去 Rest 的后部 log Alpha < 0 -> Task 的后部 Alpha 低于 Rest -> 这与任务相关的 Alpha 抑制一致 此比较是描述性的且在被试内进行。不应将其用于比较不同被试的认知能力。 本教程对 `rest_S01_1.txt` 与 `task_S01_1.txt` 的实际运行结果： 摘要: visual_cognitive_load_comparison: Task-Rest median log Alpha = -0.024 Rest median posterior log Alpha: 1.141 Task median posterior log Alpha: 1.117 Task minus Rest: -0.024 Task/Rest Alpha power ratio: 0.946 Rest median Alpha peak: 11.00 Hz Task median Alpha peak: 11.25 Hz Peak shift: +0.25 Hz Rest retention: 93.3% Task retention: 78.9% Task quality: warning 主要对比的方向与轻度任务相关后部 Alpha 抑制一致：任务 Alpha 低于静息 Alpha。然而，效应较小且任务条件存在质量警告，因此正确的解释应谨慎：这是一个描述性的被试内对比，并非更高认知负荷的证据。 参考图 5：来自 `rest_S01_1.txt` 和 `task_S01_1.txt` 的实际静息/任务比较图。主要对比是任务与静息之间后部 log Alpha 的中位数差值。 参考图 6：静息和任务记录的条件级视觉认知负荷图。空白或断开区域对应 QC 排除的窗口，而非零工作负荷。 ## 8 第5步：运行公开小数据集分析 完整的人类 EEG 小数据集在单独的公开数据仓库中维护版本。在智能体仓库旁边克隆该分支： git clone --branch add-visual-cognitive-load-mini-dataset-20260622 --single-branch https://github.com/Neuradock/eeg-workstation-data.git ..\eeg-workstation-data 从智能体仓库定义相对数据根目录： $dataRoot="..\eeg-workstation-data\visual_cognitive_load\mini_dataset_v20260622" 使用公共 CLI 对所有 18 条记录运行 Alpha 动态： .\.venv\Scripts\neuradock-agent.exe analyze $dataRoot --recursive --workflow alpha_dynamics --output-root runs\mini_dataset_alpha 以下可重用的 PowerShell 函数运行质量门控的被试内比较： function Compare-NeuraDockPair { param($Reference, $Comparison, $ReferenceLabel, $ComparisonLabel) .\.venv\Scripts\neuradock-agent.exe analyze $Reference $Comparison --workflow visual_cognition_comparison --condition-labels $ReferenceLabel $ComparisonLabel --output-root runs\mini_dataset_comparisons } 运行六个静息/任务会话比较： foreach ($subject in "S01","S02","S03") { foreach ($session in 1,2) { $folder="$dataRoot\cohort_3subj_rest_task\$subject" Compare-NeuraDockPair "$folder\rest_${subject}_${session}.txt" "$folder\task_${subject}_${session}.txt" "Rest" "Task" } } 运行四个任务变体比较： $cohort="$dataRoot\cohort_2subj_ljw_xzy" Compare-NeuraDockPair "$cohort\ljw\01_rest.txt" "$cohort\ljw\02_chat.txt" "Rest" "Chat" Compare-NeuraDockPair "$cohort\ljw\01_rest.txt" "$cohort\ljw\03_game.txt" "Rest" "Game" Compare-NeuraDockPair "$cohort\xzy\01_rest_eye_half.txt" "$cohort\xzy\02_music_eye_half.txt" "Rest" "Music" Compare-NeuraDockPair "$cohort\xzy\01_rest_eye_half.txt" "$cohort\xzy\03_game.txt" "Rest" "Game" 每条命令都会写入一个带时间戳的运行文件夹，包含 `report.md`、`