| name | universal-swv-analysis |
| description | 对方波伏安法（SWV）TXT/DAT 文件夹执行确定性质量监控、元数据解析、PBS/空白审查、基线校正、寻峰拟合、电极重复性、校准、LOD/LOQ 和可追溯报告。Use when the user provides SWV data or mentions E-average(V), DeltaI(A), PBS/blank QC, peak analysis, calibration, LOD/LOQ, or filenames such as 100fM-2-1.txt. |
通用 SWV 分析 Skill
本 Skill 面向 WorkBuddy/Agent；内置 Python harness 仅是确定性执行后端。所有数值工作必须由 harness 完成，不得凭肉眼估峰或手工改数据。
执行定位
- 将包含本文件的目录解析为绝对路径
<skill_root>。
- 将用户数据目录和输出目录解析为绝对路径。
- 不得假定当前工作目录是 Skill 根目录；始终用
<skill_root> 调用脚本和资源。
默认工作流
用户要求完整分析时，在同一任务内执行：
python "<skill_root>/scripts/swv.py" expert \
--input "<原始数据绝对路径>" \
--output "<输出绝对路径>"
expert 自动完成 DAT/TXT 检查、TXT 校验、文件名和元数据解析、MB/Fc 分组、正式分析、重复扫描与 PBS QC、校准、LOD/LOQ、报告和结果验证。
Agent 决策规则
- 有可读 TXT：继续分析；缺少非关键元数据时保留推断标记，不中断。
- 仅有 DAT：报告
EXPORT_REQUIRED，要求用户从仪器软件导出 TXT，不尝试解码二进制。
- 没有可读 TXT，或关键浓度/重复身份完全无法确定：说明阻塞原因并请求最少必要信息。
- 出现
WARN/FAIL：保留并报告，不询问是否删除，也不自动排除。
- 同时存在 MB、Fc 或未知档案：自动分组，绝不混用峰窗口或校准。
- 未经项目验证，不自动把高级方法结果宣布为科学上最优。
- 汇报分析结果时，同时呈现原始数据三指标（峰电流值、电流差、峰面积）与校正峰高，不省略任一组；峰面积以 mV·µA 展示。
强制科学规则
- 绝不覆盖、重命名、移动或删除源 TXT/DAT。
- 文件名优先按
{concentration}{unit}-{electrode_id}-{scan_index}.txt 解析，并保留原名。
- 电极是独立重复；同一电极的扫描不是额外的
n。
- 排序前检查原始方向，并以
4.0 ± 0.5 mV 验证预期步长。
- 区分数学基线、实验空白扣除与去噪；默认只用去噪信号定位峰。若空白扣除使校正峰倒置（空白响应高于样品，曲线"画反"），回退到原始信号定位峰，并明确记录
peak_position_from_raw_signal 与 corrected_peak_inverted_after_blank_correction，不得静默失败。
- 定量使用未平滑校正信号；每条曲线保留
PASS/WARN/FAIL 及原因。
- 不仅凭最高 R² 选模型；报告残差、预测误差、重复变异和限制。
- 数学多峰组分不自动等同于独立化学物种。
可选工作流
python "<skill_root>/scripts/swv.py" inspect --input "<输入绝对路径>" --output "<检查输出绝对路径>"
python "<skill_root>/scripts/swv.py" analyze --input "<输入绝对路径>" --config "<配置绝对路径>" --metadata "<元数据绝对路径>" --output "<结果绝对路径>"
python "<skill_root>/scripts/swv.py" compare --input "<输入绝对路径>" --config "<skill_root>/assets/compare_config.yaml" --output "<对比输出绝对路径>"
python "<skill_root>/scripts/swv.py" validate --results "<结果绝对路径>"
若运行时报告缺少 Python 依赖，执行：
python "<skill_root>/scripts/install_dependencies.py"
python "<skill_root>/scripts/self_test.py"
按需读取参考资料
- 输入与命名：
references/TXT_FORMAT_SPEC.md
- 完整处理顺序：
references/WORKFLOW.md
- QC 阈值与解释：
references/QC_RULES.md
- 方法选择：
references/METHOD_REGISTRY.md
- 输出清单：
references/OUTPUT_SPEC.md
- 科学限制：
references/SCIENTIFIC_LIMITATIONS.md
- 故障排查：
references/TROUBLESHOOTING.md
若缺少 PyWavelets，小波去噪会降级为内置 Haar 实现，并在结果中记录警告。
