[开源] 护士长查手卫生只能靠月底盯Excel，基于纯视觉规则与边缘检测的共现事件清单

本项目把走廊里「白大褂加水龙头」的共现事件自动算出来落到一份A4打印清单与依从率台账上。在院感管理的日常里手卫生依从率一直是个让人头疼的软指标。现场巡查靠眼睛月底报表靠Excel缺乏可回放的事件级证据。这套工具走的是纯规则与视觉检测的路线不碰大模型不联网上传主打一个可重现、可审计、可打印直接给感控办和护士长提供飞检材料。为什么感控办需要一份带时间戳的台账医院手卫生管理是感控办日常最大的痛点之一。我们去医院看现场护士长和感控干事最怕的就是两件事一是上级飞检时拿不出一份包含「谁、何时、哪条走廊、洗没洗」的明细台账二是科室主任每个月只能看到一个干瘪的依从率百分比根本不知道具体哪几个班次、哪几个时段掉得最厉害。传统的院感巡查往往是护士长拿着夹板去走廊数人头或者信息科从HIS系统里导出一堆毫无关联的排班表。月底汇总时各科室的数据经常打架感控办只能靠人工去核对费时费力还容易出错。至于那些排名靠后的走廊感控办往往只能反复贴标语因为拿不出具体的「问题清单」来指导改进。我们做这套工具就是为了解决这个端到端的链路断裂。从走廊视频输入到HSV白大褂检测、ROI命中、帧间差分提取洗手动作再到按走廊和班次聚合出依从率最后生成PDF打印清单和CSV事件台账。整条链路不联网、不上传视频和事件数据全留在本地。我们不需要那些花哨的提示词叙事只需要给感控办一份经得起推敲的白纸黑字。零大模型主路径纯规则与视觉检测的克制现在医疗信息化圈子言必称大模型但在手卫生检测这个场景我们坚决选择了零大模型主路径。原因很简单感控数据涉及医护人员的行为轨迹用大模型去搞「AI判你有罪」的叙事在合规和伦理上都走不通。大模型的黑盒特性也无法满足院感评审对数据可解释性的严苛要求。我们的主路径全靠纯规则和传统视觉。首先是HSV颜色空间检测白大褂配合轮廓和宽高比过滤干扰其次是ROI区域命中判断人是否靠近水龙头最后是帧间差分计算洗手动作的能量。状态机负责把「白大褂进入ROI」和「8秒内是否出现洗手动作」聚合成一个共现事件。这种设计的好处是绝对可控。每一个判定阈值都能在配置文件里看到每一次检测都能复现。对于信息科来说这意味着你可以向院长和感控办解释清楚每一个数字是怎么算出来的而不是黑盒里吐出来的玄学结果。当感控办拿着这份台账去跟科室主任沟通时他们看到的是基于物理规则和视觉算法的客观事实而不是某个AI模型的的主观臆断。从走廊视频到A4打印清单的实操演练我们设计了一条极简的三步走链路让感控办和护士长能迅速拿到结果。第一步是合成一段脱敏的走廊视频用于测试。通过 generate 子命令我们可以注入特定的依从率生成一段30秒的模拟视频和对应的元数据。这一步对于新院区上线非常关键信息科可以在没有真实视频的情况下先验证整条链路的逻辑。第二步是批量跑检测。通过 detect 子命令系统逐帧处理视频输出事件台账和聚合数据。终端会直接用 Rich 库打印出各走廊的依从率和 TOP 问题走廊。这种终端摘要让信息科在跑批时就能对数据质量有个底。第三步是生成打印材料。通过 report 子命令系统把 CSV 数据转化为 A4 纵向的 PDF 清单。这份清单包含封面、排名、问题清单、热力图和免责说明。同时输出热力图和柱状图方便护士长直接贴在白板上。这里展示一下核心的命令执行过程。hhe-board generate \ --corridor 内一 \ --duration 30 \ --compliance 0.5 \ --output data/synthetic/clip_0_5.mp4hhe-board detect \ --input-dir data/synthetic/ \ --corridors-config configs/corridors.example.yaml \ --thresholds configs/thresholds.example.yamlhhe-board report \ --events-csv output/events.csv \ --corridors-config configs/corridors.example.yaml \ --output-pdf output/checklist.pdf \ --output-heatmap output/heatmap.png \ --output-bar output/bar.png核心模块与数据流转设计为了让信息科的同事能看懂并接手二次开发我们把代码结构做了严格的分层。从配置加载、数据模型到合成器、视觉检测、统计计算再到可视化和报告输出每个模块各司其职。下表梳理了核心目录的职责划分方便大家快速定位代码。模块目录核心职责关键文件说明models数据模型定义event.py 定义共现事件corridor.py 定义走廊与ROIsynthetic视频合成器generator.py 负责生成脱敏且可重现的走廊mp4detection视觉检测主路径whitecoat.py 负责HSV检测event_builder.py 负责状态机聚合compliance统计与聚合calculator.py 计算分子分母ranking.py 输出TOP问题走廊report报告与输出pdf_checklist.py 生成A4打印清单csv_exporter.py 导出台账在数据流转上我们定义了清晰的共现事件结构。状态机在检测到白大褂进入 ROI 后会开启一个 8 秒的计时窗口。在这个窗口内系统持续计算帧间差分的能量值。如果能量值超过设定的 motion 阈值且持续时间满足要求则判定为洗手。每一个事件都包含了时间戳、持续时间、走廊ID以及是否洗手的标签。字段名类型业务含义event_idstring事件唯一标识t0_sfloat白大褂进入ROI的起始时间秒t1_sfloat事件结束时间秒corridor_idstring所属走廊或区域标识washedboolean是否判定为洗手washed_labelstring洗手状态文本标签如「洗手 ≥ 8s」落地场景与不可逾越的边界这套工具在设计之初我们就明确了它的适用场景和绝对不碰的边界。在适用场景方面它非常适合飞检材料准备感控办可以直接拿出事件级台账和走廊排名。在护士长例会上走廊与时段交叉的热力图能直观暴露哪个班次需要加强培训。对于新院区上线信息科可以先在脱敏合成视频上跑通整条链路再切换到真实走廊。此外它还能用于培训演练故意生成低依从率的视频给新人练手。但是我们必须划清边界。首先它不做任何临床决策或医学建议。其次它绝不用于个人追责。工具只统计到走廊和时段粒度不做脸部识别和身份绑定。PDF清单末尾也明确标注了「依 WS/T 313-2019 口径仅作整改参考不与个人考核挂钩」。感控的目的是改进而不是惩罚。如果我们把工具变成了监控员工的探头不仅会引发医护人员的抵触情绪也会让数据失去真实性。我们不想让技术越界而是让它成为感控管理的辅助尺子。最后当前版本是离线视频分析不支持RTSP实时流告警这也是为了避免实时监控带来的伦理风险。信息科与感控办常见的踩坑排查在实际部署和运行中信息科同事和感控干事会遇到一些典型问题。我们总结了常见的故障排查指南帮大家少走弯路。问题现象排查方向解决建议白大褂漏检或误检HSV阈值不匹配当前走廊光线用OpenCV提取真实画面像素HSV微调配置文件中的V_low和S_highPDF生成出现方块字reportlab缺少中文字体支持下载Noto Sans CJK SC字体修改defaults.yaml中的font_path指向真实视频检测事件数为0ROI区域设置错误或motion阈值过高检查sink_roi截图是否覆盖水龙头适当调低handwash_motion_threshold洗手时长口径需要调整默认阈值不符合医院特定要求修改thresholds.yaml中的handwash_min_seconds并在event_builder.py中增加判定关于环境依赖我们锁定了 opencv-python-headless 以避免 GUI 依赖导致的服务器报错。如果是 Apple Silicon 环境建议走源码编译或使用 conda 安装。对于 Windows 环境下的中文路径报错建议将视频文件统一放在纯英文或 ASCII 字符的目录下以规避 cv2.VideoCapture 的兼容性问题。数据合规方面大家完全可以放心。所有视频、事件、CSV和PDF全部留在本机运行主路径零网络调用。我们严格参考 WS/T 313-2019 医务人员手卫生规范确保工具在院感管理中的专业性与合规性。项目地址 https://github.com/nexorin9/handhygiene-edge-board