本地运行，视频不上网。把整段分类、旧分类复核、长视频区间精选合并为一个项目、一套标签、一张工作台；无需切换不同审核程序。
从 GitHub Releases 下载与电脑匹配的免安装包，完整解压后双击 VideoReviewer.exe（Windows）、VideoReviewer.app（macOS）或 VideoReviewer（Linux）。包内含 Python、FFmpeg 和网页资源，无需手工配置。Windows 默认启动一个已安装的现代浏览器窗口，不依赖 WebView2；关闭审核页后自动释放服务。未签名应用可能触发系统安全提示：确认来源后按系统提供的“仍要运行”/Control 点按“打开”操作。
在项目中心选择一个视频目录，选择新项目模板，然后开始：
| 模板 | 默认行为 |
|---|---|
| 跌倒分类 | 跌倒 / 不跌倒 / 护工 Fall，标签键提交后下一条，整理时移动原视频 |
| 区间精选 | 默认选取 8 秒、多段可选，显示时间轴，整理时无重编码截取；无跌倒整段默认复制 |
| 通用标注 | 自定义类别，默认只保存标签，不操作原视频 |
模板只是初始设置，不是三个互不兼容的程序。已有项目始终恢复自身保存的规则。默认输出为项目目录内的 output/，可在项目设置修改，或绑定已有外部分类目录。目录浏览器看到的是运行程序那台电脑上的目录。所有输入仅扫描第一层，子目录不会被当成待审视频；已绑定输出分类目录也会作为复核输入。
修改输出位置不会隐藏已经整理的视频：项目会保留已知视频的位置与进度，可再次整理到新位置。移除额外输入目录只停止发现新文件，不清除已有项目记录；挂载暂时不可用会提示重新绑定，不阻止打开其他可用视频。
- 左侧是可伸缩、可收起的视频队列，长列表按可见区域渲染。当前视频始终可见，即使它因刚打标签而不再符合筛选。
- 搜索同时匹配文件名、设备 ID、CSV 对照字段和备注；支持状态 / 标签筛选、设备排序与保存筛选视图。
- 中间视频默认 1.5×、静音、自动播放、循环。下一条预加载首帧；切换继承播放或暂停、倍速、循环、静音状态。不会播完自动跳过未审内容。
- 右侧是主分类、辅助标签、备注、待复核状态；开启区间功能后出现区间列表与时间轴标记。一个项目可同时有整段标签和多个带标签的区间。
- 默认 960×620 以上窗口按稳定桌面布局呈现；较小窗口或大缩放使用紧凑布局与面板内滚动，避免把操作裁掉。视频大小随空间调整，不拉伸内容。
主分类是单选，辅助标签可多选且不影响文件去向。区间标签描述某一段，整段标签描述完整视频。未审核 / 已完成 / 待复核 是审核状态，不是类别。原目录分类和原始 CSV 只是对照信息，不自动算作本轮完成。没有选择区间时，回车不会擅自判断为无跌倒。
| 按键 | 操作 |
|---|---|
| J / K / L | 跌倒 / 不跌倒 / 护工 Fall（跌倒模板直接保存并下一条） |
| S / W | 播放暂停 / 切换循环 |
| A / D | 前后跳转，默认 1 秒；长按跨过片尾时按循环设置回到片头 |
| ← / → | 前后 1 秒，到达画面作为区间起点 |
| [ / ] | 上一条 / 下一条，不打标签 |
| Space | 添加当前区间，仅区间功能开启时生效 |
| Enter | 完成并下一条；必须有标签或区间 |
| U | 待复核并下一条，无法播放的视频也可使用 |
| Backspace | 撤销上一步标注，可连续撤销 |
“项目设置 → 快捷键”可为所有工作台操作配置按键；选中键位框后按键，Delete 清空。标签键使用单个字符；其他动作支持方向键、回车、空格等，不允许重复占用或系统组合键。输入文字时不会触发审核快捷键。项目默认随规则模板保存；“仅保存为个人快捷键”只影响当前浏览器，不把个人习惯写给同事。
倍速用原生播放，20× 档有跳段补足，会提示可能漏掉动作；精细判断建议 0.75–1.5×，不确定时回看。预加载提升常见短片切换速度，不能保证网络盘、解码异常或首次兼容转码时绝对零等待。
项目设置支持添加、改名、停用标签，配置颜色、判定说明、键位、输出子目录；已引用标签不能删除，改显示名称不会破坏旧标注。可配置辅助标签、默认区间长度、自由长度、关键帧对齐、直接提交、复制 / 移动 / 仅标注以及额外输入目录。规则可以导出 JSON 模板，再导入其他项目；模板不携带视频、进度或 CSV 路径。
CSV 自动在项目附近查找，优先匹配实际视频；也可手选文件、匹配视频列、设备列和最多 3 个展示字段。重复且不一致的 CSV 行不猜测覆盖；失联的已配置 CSV 保留映射并提示重新绑定。CSV 始终只读，整理不会新建导出 CSV。CSV 设备 ID 优先；缺失时可配置文件名正则，第一组括号作为设备 ID，默认不猜命名规则。
大目录启动按目录清单核对文件，避免 Windows / NAS 对每个视频重复真实路径查询；未变化的索引不重复写入。进度分为目录检索、CSV 查找与匹配、索引建立、旧标签恢复、磁盘保存，并显示距上次进展的时间。CSV 自动检测每个候选最多采样 10000 行，在检查点使用约 8 秒总体预算；已选择的 CSV 最终仍完整读取以检查重复冲突，已保存映射重新打开时不重新遍历其他候选。系统阻塞的网络读请求不保证在预算内返回。
CSV 很大时，可在启动页点“本次跳过 CSV，先审核视频”。只跳过本次对照，不改原 CSV、不清空已有配置和审核标签；之后可在项目设置手动载入，手选 CSV 不限制行数。超过 20 秒无进展会显示提示；“复制诊断信息”提供当前阶段、文件、计数与等待时间，便于排查网络盘等待。
“开启新一轮复核”保留原标签和区间，把状态重置为本轮未审核，可用于纠正旧结果，不删除原记录。
如果网页模式能正常使用、独立窗口纯黑，故障在独立窗口初始化/渲染这一层，不能仅凭截图断定具体是 GPU、缓存还是组件错误。新版 Windows 双击默认使用现代浏览器模式，绕开该依赖；有 WebView2 且需要独立窗口的用户可显式运行 VideoReviewer.exe --desktop。可选独立窗口 25 秒内既未完成页面加载、也未建立页面连接时，会退出黑屏窗口并改用浏览器；慢目录检索和已建立连接的页面不被误关闭。未初始化窗口可以正常关闭，不再等待不存在的 JS 桥接。
旧 IE/MSHTML 内核不支持当前界面的 CSS 变量、布局和 JavaScript。窗口组件即使指定 Edge，也可能在 WebView2 / .NET 不可用时静默降级。新版在创建窗口前检查实际内核，禁止 IE 降级；独立窗口无法使用时，只启动已安装的 Edge / Chrome / Firefox，不走可能指向 IE 的默认浏览器关联。不自动下载安装组件。
如需独立窗口，可由用户安装微软官方 WebView2 Runtime。没有可启动的现代浏览器时明确提示并关闭服务；不让失效页面长期占用端口。网页也会检测必要浏览器能力和样式是否完整加载，显示可读的修复说明，而不是黑字深底、错位弹窗。更新请完整解压应用包，不要混用新旧文件；保留原项目的 output 和 .video-reviewer，无需重新标注。
点击开始立即显示载入面板，目录验证在后台运行；目录、快照读取、日志恢复、CSV、索引各阶段分别显示进度及耗时，诊断信息保留各阶段时间。Windows 项目中心只查询可用盘符列表，不逐个访问映射盘。目录选择器读取期间明确显示等待状态，不会误选上一次浏览的目录。
已有视频按目录清单批量核对，清单中的缺失文件不再逐个查询。旧输出目录每个只枚举一次，仅恢复已登记视频，不递归扫描、不收录其中其他视频；缺失和不可访问文件的原标签保留，整理时仍明确报错，不会当成已导出。
未变化的 CSV 匹配结果保存在本机预览缓存目录，一个项目一份可替换缓存；CSV 的路径、大小、修改/变更时间、文件身份、字段设置或视频清单变化就重新匹配，缓存损坏或不能写入时自动回退。缓存不会修改 CSV，也不是人工标签的存放位置；人工标签仍在原项目 .video-reviewer 中。首次匹配或换电脑仍需要读取 CSV，较慢时可选择“本次跳过 CSV，先审核视频”。网络盘本身的首次连接和实际读盘耗时不能消除。
工作台顶部的“整理历史”直接读取当前项目的批次记录：时间、输出根目录、新整理/已核验/失败数量及失败原因。旧版已有逐文件记录会显示为“旧版记录”，不会伪造过去的完整批次统计。最近 100 批汇总保存在原隐藏项目进度中，不写 CSV，不另外生成版本备份。
更新时先等待旧任务结束并退出旧程序，解压新版应用，选择原来同一个项目目录。不要删除或移走 .video-reviewer，无需重新打标签。通过“整理历史 → 检查并继续整理 → 确认整理”恢复未完成项；它按当前标签和输出规则重新检查，不盲目回放旧计划。已归位的移动视频跳过，成功复制/片段会检查原成品，失败或未处理项继续。外部文件冲突和源文件变化不会覆盖；源文件不可访问会列为失败，不会静默当作全部完成。
整理窗口立即显示，预览计划只读内存，不逐文件访问磁盘；确认后才在后台校验。进度展示当前文件、校验/复制/发布阶段、本阶段读取或复制的字节数、已用时间和磁盘等待提示。“已处理”包括成功和失败，结束后分开统计；单个失败不阻塞后续，完整失败清单可下载为 JSON 诊断文件。整理期间暂不能修改标签、规则或刷新清单，避免文件被归到过时标签下；关闭整理对话框不停止任务，退出整个应用需等待批次结束。
Windows 本地盘及 UNC 网络盘统一使用原生扩展路径访问视频；临时文件使用短随机名称，避免在原长文件名后追加 UUID 导致超出路径或文件名限制。成品名称和整段字节内容不变；移动前保留 SHA-256 内容校验与同名不覆盖保护。不会要求同事改注册表。操作系统阻塞的磁盘/网络请求仍可能等待较久；新版让阶段可见，不承诺网络盘瞬时完成，也不以取消校验换速度。
失败处理：先等待本批结束、保留原视频及已有 output，查看“整理历史”的原因后重试；不要为了重试删除已成功成品或隐藏进度。新旧程序不要同时编辑一个项目。批次中断可在重开项目后继续；项目恢复仍会核验已发布但记录未完成的成品。界面“标注已保存”不等于全部视频已整理；最终应确认失败为 0，并核对归档结果与人工标签一致。
项目目录/
├── .video-reviewer/
│ ├── project.json # 规则、目录绑定、CSV 映射
│ ├── state.json # 视频稳定 ID、标注、审核轮次、整理记录快照
│ ├── events.jsonl # 确认保存前落盘的操作日志
│ └── writer.lock # 单写入程序锁；退出或崩溃后由系统释放
└── output/
├── fall/ # 默认整段分类
├── no_fall/
├── caregiver_fall/
└── clips/ # 默认区间成品，全部在同一个目录
每次标注先写日志并刷新到磁盘，成功后才显示“已保存”。日志在启动时重放，定期收敛为快照，不为每次版本升级建立备份目录。未确认的浏览器队列保留本地，断网或保存失败会醒目提示、支持重试和下载；版本冲突必须明确选择服务器记录，不静默覆盖。退出前应等待顶栏显示“已保存”。
新版本首次打开会迁入项目或绑定输出中找到的 .fall_label_state*.json / .clip_reviewer_state.json，保留旧文件，不删除旧进度；重复文件名按原目录身份迁移，模糊情况提示，不乱配。若旧输出在项目外，请先用旧命令参数绑定，或将对应项目进度与视频一起移到项目目录，再升级。嵌套路径的旧片段视频不会递归扫描，请显式添加对应输入目录。
隐藏项目目录与视频目录内的相对路径可以整体搬迁；外部 CSV / 输入 / 输出绝对路径需在新电脑重新绑定。只替换应用不丢进度；备份或搬迁数据时要连同 .video-reviewer 一起保留。 同一项目仅允许一个程序写入，多个页面用记录版本检查避免覆盖；这不是多人实时协作平台。网络盘不支持文件锁时会拒绝危险写入，可完整复制项目到本机继续。
“提交标签”只保存进度，点击顶栏“整理文件”并确认才处理视频。计划只包含本轮已完成内容；未审、待复核不整理，困难样本不会被自动判断成负类。
- 整段保持原文件名。复制逐字节校验；移动先核对目标内容再删除原文件。不同内容同名绝不覆盖；失败单项列出并允许重试，不阻断后续视频。
- 区间单段保持原名，多段加
_0001、_0002；默认都放output/clips，也可按区间标签分子目录。不会因截取区间而删除长视频。 - 区间始终使用
-c copy，不重新编码、无新增压缩损失。无重编码与任意帧精确截取不能同时保证：关键帧与音视频包边界会造成实际起止 / 时长偏差，整理记录保存实际时长；不将它宣称为严格逐帧 8.000 秒。 - 输出冲突会预警；已完成项有持久整理凭据，重复整理跳过成功项。中断恢复核实文件内容，不重新覆盖成品。输出文件由其他工具修改时提示冲突。
- 自动兼容预览仅改变本机缓存，最终整理读取原视频，不用预览缓存作输出。普通浏览器使用 H.264；Linux 独立应用使用 VP9 兼容预览。支持当前优先、后台兼容全部与生成进度。
Windows 免安装版默认打开一个现代浏览器窗口；macOS / Linux 默认独立窗口。独立窗口关闭后结束服务，未保存记录或整理任务会阻止误退出；浏览器模式 / 远程版关闭最后一页后约 8–12 秒退出，刷新不算结束。临时休眠 / 断网不会立即杀掉审核；异常页面消失且没送达关闭通知时最迟 24 小时退出。顶栏“退出工具”可明确停止。只有 --keep-running 长期运行；--no-browser 不会让服务常驻。
更新：退出旧工具，完整解压新版，重新选择原数据项目即可。不要混用新旧包内的文件。Windows 默认浏览器模式无需 WebView2；可选 --desktop 独立窗口需要系统可用的 WebView2，也可用 --browser 显式绕开独立窗口。Linux 原生包面向现代 x64 桌面环境（glibc 2.34+），无图形桌面的服务器用远程模式。源代码不依赖桌面组件。
源码需 Python 3.10+ 和 FFmpeg（无需独立 FFprobe）：
python3 start.py
python3 start.py --source "/视频目录" --preset fall
python3 start.py --source "/视频目录" --preset clips --output-root "/成品目录"Windows 可双击 start_windows.bat，macOS / Linux 用 ./start_mac_linux.sh。旧 --mode clip/label 及分类输出参数兼容。
远程 VS Code：运行 ./start_remote.sh，在 Ports 面板手动打开转发地址，项目配置不主动弹浏览器。普通 SSH：
# 服务器
./start_remote.sh 18765
# Mac / Windows 本机终端，保持隧道运行
ssh -N -L 18765:127.0.0.1:18765 用户名@服务器地址访问 http://127.0.0.1:18765。本机端口占用时只更换 -L 左边端口。可信局域网可用 python3 start.py --host 0.0.0.0，其他电脑访问服务器 IP 和端口；没有登录系统且可浏览运行账号能读的目录，不得暴露公网，每人使用自己的数据项目。端口默认从 8765 自动选择空闲值，不会杀其他用户的服务。
唯一源码目录：/home/duanqw/Kami/video_clip_reviewer。唯一 NAS 副本：/mnt/27_1-B2B-data/2026/duanqingwu/qwen3vl_vllm/datasets/video_clip_reviewer。每次更新新增文件先入 Git，再运行 ./sync_to_nas.sh 并核对校验；不同步用户视频、缓存、Git 历史、个人数据，不删除 NAS 的额外数据。
四平台独立包由 GitHub Actions 构建并自检，固定存于两边的 packages/（不进入 Git），VERSION.txt 记录版本，只维护一套最新包。源码修改不会自动更新旧应用包。
python3 -m unittest discover -s tests -v
node --test tests/playback.test.cjs tests/app-lifetime.test.cjs
# 安装 Playwright + Chromium 后，隔离真实浏览器流程
node tests/workbench.test.cjs
# 安装 requirements-build.txt 并有图形环境后
python3 tests/test_native_integration.py
python3 -m PyInstaller --noconfirm --clean VideoReviewer.spec旧 reviewer.py / quick_labeler.py 保留为媒体工具与迁移适配层；start.py 只启动统一 ProjectApp。核心分为 schema / store / project service / bounded media deck / workbench，不再为每种任务维护独立活跃页面。发布依赖的许可证与来源见 THIRD_PARTY_NOTICES.md。