Universal SWV Analysis Skill

一个面向 WorkBuddy / Agent（如 Claude Code） 的 Skill，对方波伏安法（SWV）实验数据文件夹执行一键完整分析：数据质量检查 → 峰检测与原始信号三指标 → 空白/基线处理 → 电极重复性 → 校准与 LOD/LOQ → 可追溯报告。

数值计算全部由内置 Python harness 确定性完成，不靠肉眼估峰、不手工改数据。

核心能力

• 批量读取：工作站导出的双列 TXT（E-average(V) 电位 + DeltaI(A) 差分电流）；同时监控 .dat 文件，有 DAT 无 TXT 时提示回原软件导出，不解析未知二进制。

• 数据质量检查：文件结构、扫描方向、4 mV 步长、单位换算、浓度×电极×扫描完整性、同电极重复扫描、PBS 空白 QC——全部输出 PASS/WARN/FAIL 及原因，异常数据保留不删除。

• 峰分析（每条曲线）：

  指标	含义
  峰电位	校正信号上检测的峰位
  峰电流值（peak_current_raw_A）	原始 ΔI 在峰位的取值，含背景
  电流差（peak_height_net_raw_A）	原始峰顶电流 − 峰电位处两锚点线性基线值（对应电化学工作站软件的峰高定义）
  峰面积（peak_area_raw_A_V）	峰窗内原始信号对同一基线的积分（mV·µA）
  校正峰高	空白扣除 + 基线校正后的定量峰高，用于校准

  若空白扣除使校正峰倒置（空白响应高于样品，曲线"画反"），自动回退到原始信号定位峰位，并在结果中明确标注 corrected_peak_inverted_after_blank_correction。

• 校准与限值：多模型比较（OLS/WLS/Huber/RANSAC/对数）、Bootstrap 不确定度、LOD/LOQ。

• 输出：Excel/CSV/JSON/HTML 报告、PNG/SVG 图、audit_log.json 审计记录。

快速开始

安装

WorkBuddy：Skills 管理界面导入 Skill ZIP（不要直接压缩源码仓库），启用 universal-swv-analysis，将实验数据目录设为工作区。

Claude Code：将 Skill 目录放到 ~/.claude/skills/universal-swv-analysis/。

从源码构建 ZIP（发布者）：

python scripts/build_skill_zip.py

上传 dist/universal-swv-analysis-v0.2.0.zip（只含运行时文件，单一顶层目录）。

使用

把实验数据文件夹设为工作区，对 Agent 说：

使用 Universal SWV Analysis Skill，以 Expert 模式完整分析当前文件夹中的实验数据。

或直接执行：

python "<skill_root>/scripts/swv.py" expert \
  --input "<实验数据文件夹>" \
  --output "<输出文件夹>"

一条命令依次完成：

DAT/TXT 检查 → TXT 校验 → 文件名/元数据解析 → 实验完整性检查
→ MB/Fc 分组 → 空白扣除/基线/寻峰/拟合 → 重复扫描与 PBS 质控
→ 校准/LOD/LOQ → 报告与结果验证

首次使用前安装依赖并自检：

python -m pip install -r requirements.txt
python scripts/self_test.py

要求 Python 3.10+；CI 在 3.10–3.13 上执行测试。

用示例数据试跑

python scripts/swv.py expert \
  --input "examples/raw_data" \
  --output "tmp/demo_output"

输入约定

文件格式：双列 TXT，表头 E-average(V) 与 DeltaI(A)（详见 references/TXT_FORMAT_SPEC.md）。

推荐命名：

{浓度}{单位}-{电极编号}-{扫描次数}.txt    例如：100fM-2-1.txt、PBS-3-2.txt

• 浓度：100fM / 100 fm / 100FM 均可；uM/μM/µM 兼容；
• 电极编号：独立平行实验单位；
• 扫描次数：该电极的重复测量，不是独立平行。

原文件名永远保留，不会自动重命名。

输出

<output>/
├─ 01_inspection/          数据质量检查（校验表、完整性矩阵、检查报告 HTML）
├─ 02_resolved_configs/   每个电位体系实际生效的配置
├─ 03_results/             正式结果
│  ├─ all_curve_results.xlsx/csv   逐曲线结果（含原始三指标）
│  ├─ replicate_statistics.csv     按电极分组的均值/SD/CV（含三指标）
│  ├─ within_electrode_scan_qc.csv 同电极重复扫描 QC
│  ├─ pbs_quality_control.csv      PBS 空白 QC
│  ├─ calibration_models.csv       校准模型比较
│  ├─ uncertainty_lod_loq.csv      不确定度与 LOD/LOQ
│  ├─ processed_curves.csv         原始/空白/基线/校正/检测信号
│  ├─ report.html                  可浏览报告
│  ├─ audit_log.json               可追溯处理记录
│  └─ plots/                       全套图形
└─ expert_run_summary.json

同一目录同时存在 MB（−0.5→−0.1 V）与 Fc（0.3→0.7 V）时，自动分组分析，不混用峰窗口或校准曲线；03_results/ 下按 MB/、Fc/、unknown/ 分目录。

其他命令

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 "<结果文件夹>"                      # 结果完整性验证

详细文档

主题	文档
输入格式与命名	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

元数据限制

文件名只能表达浓度/电极/扫描，不能说明样品是 IGF-1、BSA 还是阴性对照。推荐通过元数据文件补充 target_analyte、sample_type、sample_name、batch、experiment_date、redox_reporter、probe_or_construct、electrode_type。缺少时 Skill 继续分析，但明确标记元数据为推断。

安全原则

• 不覆盖、重命名或删除原始 TXT/DAT；
• 不自动删除异常数据（WARN/FAIL 保留并报告）；
• 电极是独立重复；同电极多次扫描不当作额外 n；
• 定量使用未平滑校正信号；平滑信号只用于检测；
• MB 与 Fc 不混用峰窗口或校准；
• 模型选择不只凭最高 R²；
• 数学多峰组分不自动等同于独立化学物种。

开发者

python -m pip install -r requirements.txt
python -m pytest tests/          # 测试（30 个）
python scripts/self_test.py      # 自检

源码仓库用于维护与版本控制，不等同于导入包；发布请使用 scripts/build_skill_zip.py。