本项目把走廊里「白大褂加水龙头」的共现事件自动算出来，落到一份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 定义走廊与ROI |
synthetic | 视频合成器 | generator.py 负责生成脱敏且可重现的走廊mp4 |
detection | 视觉检测主路径 | 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_id | string | 事件唯一标识 |
t0_s | float | 白大褂进入ROI的起始时间（秒） |
t1_s | float | 事件结束时间（秒） |
corridor_id | string | 所属走廊或区域标识 |
washed | boolean | 是否判定为洗手 |
washed_label | string | 洗手状态文本标签，如「洗手 ≥ 8s」 |
落地场景与不可逾越的边界
这套工具在设计之初，我们就明确了它的适用场景和绝对不碰的边界。
在适用场景方面，它非常适合飞检材料准备，感控办可以直接拿出事件级台账和走廊排名。在护士长例会上，走廊与时段交叉的热力图能直观暴露哪个班次需要加强培训。对于新院区上线，信息科可以先在脱敏合成视频上跑通整条链路，再切换到真实走廊。此外，它还能用于培训演练，故意生成低依从率的视频给新人练手。
但是，我们必须划清边界。首先，它不做任何临床决策或医学建议。其次，它绝不用于个人追责。工具只统计到走廊和时段粒度，不做脸部识别和身份绑定。PDF清单末尾也明确标注了「依 WS/T 313-2019 口径，仅作整改参考，不与个人考核挂钩」。
感控的目的是改进，而不是惩罚。如果我们把工具变成了监控员工的探头，不仅会引发医护人员的抵触情绪，也会让数据失去真实性。我们不想让技术越界，而是让它成为感控管理的辅助尺子。最后，当前版本是离线视频分析，不支持RTSP实时流告警，这也是为了避免实时监控带来的伦理风险。
信息科与感控办常见的踩坑排查
在实际部署和运行中，信息科同事和感控干事会遇到一些典型问题。我们总结了常见的故障排查指南，帮大家少走弯路。
问题现象 | 排查方向 | 解决建议 |
|---|---|---|
白大褂漏检或误检 | HSV阈值不匹配当前走廊光线 | 用OpenCV提取真实画面像素HSV，微调配置文件中的V_low和S_high |
PDF生成出现方块字 | reportlab缺少中文字体支持 | 下载Noto Sans CJK SC字体，修改defaults.yaml中的font_path指向 |
真实视频检测事件数为0 | ROI区域设置错误或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
