老师还没进班，迟到名单已经出来了
ClassIsland 插件「人脸考勤」 · v1.2.3.0（AI做的）
到设定的早读/自习时间，自动用摄像头连拍几张照片，在本机用开源小模型和花名册逐个比对，把迟到的同学列出来，直接贴在 ClassIsland 主界面上。
全部推理都在本机 CPU 上完成：不联网、不上传任何照片和特征。
运行要求: 需要 ClassIsland 2.1.0 或更高版本。插件用到了 2.1.0 才有的设置页分组菜单和自动化行动扩展点，宿主版本低的话请先升级。
下载
ClassIsland.Plugin.FaceLate v1.2.3.0（.cipx，约 109 MB，已内置模型与 OpenCV 运行时）
| v1.2.3.0
开源仓库 YSA887/ClassIsland.Plugin.FaceLate（MIT 许可）
| main
论坛的绿色下载按钮需要先给本帖点赞才能点击。懒得点赞的话，直接用上面两条链接就行。
已向下游 ClassIsland/PluginIndex 提交上架申请（PR 192），通过之后就能在应用内的插件市场里直接安装了：ClassIsland/PluginIndex192
为什么写这个
早读考勤这件事，人工点名大概两分钟，而且总有漏网之鱼。教室一体机本来就带着摄像头（或者花二三十块插个 USB 摄像头），那为什么不让它自己数人？
于是有了这个插件：到点了自己拍、自己认、自己出名单，老师进班时主界面上已经写着谁没到。
你需要准备的只有两样：一份花名册，和每位同学两张以上的正脸照（手机拍也行，从照片录入）。
功能概览
| 功能 | 说明 |
|---|
| 定时自动考勤 | 周一到周日每天单独开关、单独配时间，一天可配多个时刻，精确到秒 |
| 摄像头连拍 | 张数、间隔、分辨率、预热秒数都可调，默认 4 张 |
| 多帧投票抗误判 | 每位同学要在 ≥ N 张照片里都被认出来才算「到了」，压制偶发串脸 |
| 两种判定方式 | 教室抓拍·缺席判定 / 门口抓拍·出现判定，按摄像头位置选 |
| 人脸录入 | 摄像头连拍录入，或从已有照片批量导入；同一人可反复录入累积样本 |
| 批量导入 | 文件名里带人名（806班张三.jpg）就自动匹配，整批一次导入并给汇总 |
| 智能导入 | 人像库已有样本时，逐张问你「这是 XXX 吗」，确认即入库 |
| 多脸框选 | 一帧里有多张脸时弹出带编号方框的预览图，点一下选要录的那个人 |
| 多款识别模型 | 自带 SFace（128 维）+ 可选 ArcFace（512 维），可自动挑选，阈值跟着模型走 |
| 主界面组件 | 「早读迟到名单」组件，拖到主界面任意位置，可设标题、显示人数、上课自动隐藏 |
| 接自动化 | 提供行动「人脸考勤：执行一次考勤」，晚自习这种非固定时间直接挂规则里 |
| 运行日志 | 分级日志面板默认折叠，出问题再翻开看，标题栏直接显示错误条数 |
| 完全离线 | 模型随插件包发布，装完即用，不需要联网 |
上手四步
装好之后，【应用设置】左侧会出现一个可折叠的 「人脸考勤」 分组，底下五个页面：主设置 / 花名册 / 批量导入 / 识别与模型 / 运行与日志。
1. 录花名册
【应用设置】→【人脸考勤】→【花名册】：填好班级名称，然后在左边输入姓名逐个 添加。
名单长的话，点右上角 花名册操作 ▾：
| 菜单项 | 说明 |
|---|
| 导入花名册文本 / CSV… | 选一个 .txt / .csv，每行一位同学，支持 姓名,班级 两列 |
| 从剪贴板导入 | 先把名单复制好，点这个直接导入 |
| 导出花名册 CSV… | 反向导出，方便备份或复制到别的班 |
| 打开人脸样本目录 | 看看录进去的人脸小图长什么样 |
名单格式就两列，班级可以省略：
张三
李四,高二(3)班
王五,高二(3)班
每位同学旁边还有两个开关：参与考勤 / 今日请假。请假的同学不会被算成迟到。
2. 录人脸（可多次，越录越准）
在左边选中一位同学，把摄像头对准他，点 录入方式 ▾：
| 菜单项 | 说明 |
|---|
| 摄像头录入（连拍若干张） | 按设定张数连拍，每张挑画面中最大的那张脸存成样本 |
| 从图片文件录入…（可多选） | 选一张或多张已有照片批量录入；照片里有多张脸会分别存成样本 |
录错了用 样本操作 ▾ → 删除选中的样本 / 清空该生全部人脸。
建议分 23 次录入：正脸一次、稍微左右侧脸各一次、戴眼镜再录一次。经验上 48 条就很稳了（每人最多保留 12 条，超出自动淘汰最早的）。
录的时候右下角会实时显示摄像头画面，方便确认人在画面里的位置。
3. 配考勤
【应用设置】→【人脸考勤】→【主设置】，顶边栏有四个页签：基本 / 时间计划 / 摄像头 / 存档与日志。
- 基本：抓拍开关、迟到判定方式（教室抓拍 · 缺席判定 / 门口抓拍 · 出现判定）
- 时间计划：周一到周日每天单独开关、单独配时间，一天可配多个时刻（逗号分隔）。懒的话用 批量启用 ▾（周一至周五启用 / 周六周日启用 / 七天都启用）和 套用时间 ▾（把周一的时间套到其余各天）
- 摄像头：序号、分辨率（强烈建议 1280×720）、抓拍张数、间隔、预热秒数；这里有 测试与目录 ▾ → 测试摄像头（抓一帧），先确认能出画面
- 存档与日志：是否保留抓拍照片、保留天数
改完去【人脸考勤】→【运行与日志】页点 立即识别一次 跑一遍完整流程，页面上有进度条和阶段文字，能看清走到哪一步了。
4. 把组件拖到主界面
【应用设置】→【组件】→ 组件库里找到 早读迟到名单，拖上去。可以在组件设置里改标题、没迟到时是否隐藏、上课时是否自动隐藏、名单最多显示几人等。
显示效果大致是：
早读迟到 [3 人]
张三、李四、王五
识别完成，迟到 3 人（6.4 秒）
识别时间 07:20:03 · 抓拍 4 张 · 检测到 38 张脸 · 耗时 6.4 秒
两种判定方式怎么选
- 教室抓拍 · 缺席判定（默认）：摄像头对着教室，早读开始时抓拍。
迟到 = 花名册（应到） − 被识别到的人。最贴近「抓拍看谁还没来」的场景。
- 门口抓拍 · 出现判定：摄像头对着门口/走廊，在早读开始之后的时间点抓拍。
迟到 = 被识别到的人。
两种方式下，已请假和未录入人脸的同学都不会被误判为迟到：请假的直接排除；没录人脸的完全不参与判定，并在结果备注里列出姓名提醒你补录。
性能：8 GB 的老电脑也够用
实测（普通办公 PC、纯 CPU、一张 2048×1150 的 34 人合影缩到 1280×720）：
| 项目 | 实测值 |
|---|
| 模型载入 + 检测器创建 | ≈ 40 ms |
| 1280×720 单帧「检测 + 逐张脸提特征」 | ≈ 71 ms |
| 8 张脸 × 200 条样本的比对 | 1 ms |
| 完整流程（40 人班、抓拍 4 张） | 约 3 秒 |
模型合计不到 40 MB（YuNet 检测模型才 230 KB），常驻内存 100200 MB。抓拍张数拉到 20 张，量级也在 15 秒以内。
640×480 到底够不够？实测答案是「不够」
同一个场景，只改抓拍分辨率：
| 抓拍分辨率 | 合格人脸 | 不同人之间的最大相似度 | 与阈值 0.363 的余量 |
|---|
| 640×480 | 2 张 | 0.3593 | 0.0007（几乎为零） |
| 1280×720 | 5 张 | 0.3186 | 0.0444 |
640×480 下「不同人之间的最大相似度」是 0.3593，而判定阈值是 0.363 —— 只差 0.0007，等于说随便两张脸都有可能被认成同一个人；同时只有 2 张脸够大能被识别，后排同学基本没参与判定。
SUCCESS: 想认准，先把抓拍分辨率提到 1280×720，这比换模型管用得多。
教室一体机上报「未检测到人脸」？v1.2.3 修的就是它
这一条请重点看，踩坑的人不少。
现象很迷惑：同一张照片、同一个版本，在自己电脑上好好的，换到教室一体机上每一张都失败，提示「没有检测到足够大的人脸」，批量导入「新增 0 条」。
根因是模型文件所在路径里有中文字符：
- OpenCV 的 C++ 实现用窄字符（ANSI）路径去开文件，而
FaceDetectorYN 只会把路径原样递进去，也没有「读进内存再加载」的重载 —— 路径一旦含非 ASCII 字符就必然抛 Can't read ONNX file。
- 而 ClassIsland 的插件配置目录在
C:\Users\<用户名>\ 下 —— Windows 用户名是中文（比如 C:\Users\张老师\），或者把 ClassIsland 装在 D:\教学软件\ClassIsland 这类目录里，路径就带中文了。
- 这个异常随后被
catch 吞掉，界面显示成「未检测到人脸」—— 看起来像照片或模型的问题，完全联想不到「装在哪个目录」。
v1.2.3 已修复: 插件会把检测模型复制到一个纯 ASCII 目录再加载（优先 C:\ProgramData\ClassIsland-FaceLate-Models\）；路径本来就是纯 ASCII 时不复制、零开销。
顺带这次还做了两件事：
- 不再吞错 —— 以后遇到类似问题，提示会直接说出病因，而不是笼统的「未检测到人脸」；环境故障还会在「运行日志」里记一条错误。
- 「识别与模型」页加了真实自检 —— 不只检查文件在不在，而是真建一次检测器、真跑一次推理，把「文件都在但就是跑不起来」当场暴露出来。
如果升级后仍然失败，请到【人脸考勤】→【识别与模型】看 自检 那一行，它会把原因直接写出来；「运行日志」里也会有一条对应的错误记录，把它发出来就能定位。
常见问题速查
打不开摄像头 / 一直失败
在【主设置】→【摄像头】页用 测试与目录 ▾ → 测试摄像头（抓一帧），把序号 0、1、2… 试一遍；确认没有其它程序（钉钉、腾讯会议、相机）占用；笔记本内置摄像头和外接 USB 同时存在时序号会变。
总是把某位同学判成迟到
多半是样本太少或角度太单一 → 多录几次；也可能是抓拍时他背对摄像头或被挡住 → 增加抓拍张数。
把别人认成了这位同学（串脸）
阈值太低 → 在推荐值基础上上调（SFace 试 0.40~0.45，ArcFace 试 0.55~0.65）；把「最少命中张数」提到 3，配合 56 张抓拍。
后排同学总是认不出来
- 先把抓拍分辨率提到 1280×720 以上（最有效的一步）；
- 确认摄像头对焦在整个教室，而不是只对着前排；
- 给后排同学额外录几次（拿手机拍正脸照，用「从照片录入」）。
导入花名册后有些人没参与判定
他们还没录入人脸，结果备注里会列出这些同学的名字。
换了识别模型，阈值要不要跟着改？
不用手动改，也不能照搬。余弦相似度的分布是跟着模型走的：SFace 官方推荐 0.363，ArcFace 系是 0.40.6（本插件取 0.50）。v1.2.1 起插件会自动按当前模型取推荐值，并且把你在各款模型下调过的值分开记住，切换模型不会互相污染。
学校网络访问不了 GitHub / HuggingFace，怎么装？
用能上网的电脑把 .cipx 下好，U 盘拷到一体机，【应用设置】→【插件】→【从本地安装】。模型已经打包在里面了，装的过程完全不联网。
安装
- 下载
ClassIsland.Plugin.FaceLate.cipx（约 109 MB，已包含模型和 OpenCV 运行时，不需要装 .NET SDK）
- ClassIsland →【应用设置】→【插件】→【从本地安装】，选择这个文件
- 重启 ClassIsland，在【应用设置】→【插件】里确认「人脸考勤」已启用
- 回到【应用设置】，左侧会出现一个可折叠的 「人脸考勤」 分组，里面有 主设置 / 花名册 / 批量导入 / 识别与模型 / 运行与日志 五个页面
WARNING: 需要 ClassIsland 2.1.0 或更高。安装后请确认插件目录下存在 OpenCvSharpExtern.dll 和 opencv_videoio_ffmpeg4130_64.dll 这两个原生库（构建脚本会自动拷贝）。
装完可以去【人脸考勤】→【识别与模型】点一下 操作 ▾ → 载入 / 重新载入模型，确认模型正常载入；那条自检结果会告诉你检测器到底能不能跑。
关于模型和隐私
| 模型 | 用途 | 大小 | 许可 |
|---|
| YuNet | 人脸检测 | ≈ 230 KB | OpenCV Zoo，Apache-2.0 |
| SFace（默认） | 特征提取（128 维） | ≈ 37 MB | OpenCV Zoo，Apache-2.0 |
| ArcFace MobileFaceNet（可选） | 特征提取（512 维） | ≈ 13 MB | InsightFace，仅供非商业研究用途 |
前两个模型都打包在插件里，装完开箱即用，不需要联网。ArcFace 因为许可限制没有内置（校内教学属于非商业场景，但为便于分发就不打包了），想用可以自行导入。
隐私: 所有照片、特征向量、名单都只落在本机插件配置目录里，推理完全离线。抓拍照片默认保留 14 天后自动清理，也可以在设置里关掉存档。
版本记录
| 版本 | 要点 |
|---|
| v1.2.3 | 修掉「换台电脑就检不到人脸」（模型路径含中文导致 OpenCV 读不出模型）；不再吞错，新增真实自检 |
| v1.2.2 | 设置界面重做：一行一事卡片 + 顶边栏页签，文案精简，修三个观感 bug |
| v1.2.1 | 比对阈值改为跟着模型走（0.363 是 SFace 的，ArcFace 用 0.50） |
| v1.2.0 | 漏检根因修复 + 多脸框选录入 + 多模型清单 |
| v1.1.0 | 设置页分组菜单 + 批量/智能导入 + 自动化行动 |
| v1.0.1 | 重要修复版（线程安全、模型定位、进度条、抓拍分辨率） |
| v1.0.0 | 首个版本 |
完整的变更记录（含每个 bug 的根因和实测数据）在 CHANGELOG.md 里：YSA887/ClassIsland.Plugin.FaceLate/blob/main/CHANGELOG.md
许可与致谢
本插件以 MIT 许可发布。
- 人脸模型：OpenCV Zoo（Apache-2.0）—— YuNet 由 Shiqi Yu 等人提出，SFace 由 Yaoyao Zhong 等人提出
- 推理/采集：OpenCvSharp（Apache-2.0）
- 宿主：ClassIsland
- 使用deepseekv4.1制作
