纯前端 Demo：选择目标 → 眼部定位 → 实时参考路径 → 分段指导 → 用户点击检查 → 原始关键帧分析 → 方向反馈。
v0.3 已合入 main；部署改动须通过 PR 验收后上线。眼线方向检查仍是实验能力，真人样本、实体手机五轮运行及三位新手试用尚未执行。
- 工作台只开放眼线；底妆、眉妆、眼影、唇妆明确标记为尚未开放。
- 练习时突出眼部放大画面、当前一步和检查按钮，整体画面可切换；参数和显示设置按需展开。
- “跟着画”只显示当前分段，“看效果”显示整体示意；高对比与透明度只改变显示。
- 用户确认后进行可取消的三秒倒计时，在至多一秒内尝试至多五个不同视频帧，按现有几何与清晰度规则择优；全部无效则要求重拍。
- 结果显示本次原始照片，可切换画前对照。虚线表示参考方向，实线仅表示从可靠候选像素拟合得到的方向。无法判断时不画检测线。
- 离开会确认清除进度；结束或离开释放摄像头并清除会话照片。没有后端或云端图片存储。
环境：Node.js 22.12+（本次使用 24.19）、npm。
npm ci
npm run dev打开终端显示的本机地址，允许摄像头。初次安装会下载官方 Face Landmarker 模型并复制 WASM / OpenCV.js 到 public/assets/（约 51 MB）。如果下载失败，重试 npm run assets。运行时从本站加载资源，不依赖公共 CDN，也没有图片上传接口。
手机摄像头需要受信任的 HTTPS。局域网的普通 HTTP IP 地址通常只能查看页面；要用手机摄像头，请将 npm run build 生成的 dist/ 放到 HTTPS 静态站点，或使用受信任的本地开发证书。电脑本机 localhost 可直接调试。部署工作流合入 main 后，main 更新会自动发布到 GitHub Pages；只有 Deploy mobile demo 的 build、deploy、verify 全部成功后，才进入手机验收。
仓库：https://github.com/linz12306/beauty-without-barriers。私有仓库需要先由仓库所有者添加协作者。
git clone https://github.com/linz12306/beauty-without-barriers.git
cd beauty-without-barriers
npm ci
npm run dev统一使用现有 React + TypeScript + Vite 技术栈和 package-lock.json 锁定的依赖。摄像头与 MediaPipe 由 src/vision/ 共用，路径与展示放在 src/guidance/，结果检查放在 src/analysis/；模块数据类型以 src/types.ts 为准。修改公共接口前先与相关模块负责人同步。
每个功能从最新 main 创建自己的分支（例如 feat/eye-guidance），通过 Pull Request 合并回 main。提交前运行本文的单元测试、页面测试与构建。不要提交环境密钥、真实人像样本、授权截图或测试录屏；模型和运行资源通过安装脚本生成。
- 从工作台进入眼线，可先在“跟着画”和“看效果”之间切换了解形状，再在光线均匀、镜头稳定的环境开启摄像头，选择自己的左眼或右眼。
- 调整长度和上扬角度，画前采集基准图。已经画过时需先卸除，否则无法把现有眼线当成“新增区域”。
- 看放大画面的“起”“收”和箭头，完成高亮的一段眼尾；点击检查，确认移开手与工具，然后拍摄。
- 查看方向反馈或无法判断原因。可以重拍，也可以自行确认后继续连接眼睑外段。
- 第二次检查依旧只检查眼尾方向，由用户确认完成。
如果只想跟随参考线练习，或画前照片反复无法通过检查，可在准备页选择 “仅跟随指引练习”。该模式需要眼部定位，但不拍照、不分析；两步均由你自行确认完成，完成页明确说明没有自动检查。重新开始恢复默认检查流程。
镜像只改变显示。分析始终读取原始视频，不读取叠加参考线的 Canvas。图片仅在内存中保存，关闭页面、关闭摄像头或重新选择目标会清除基准图与结果。
- 已实现：MediaPipe 单人脸 VIDEO 模式与内置平滑、按眼宽适配的参考路径、左右眼/镜像/缩放转换、暂停/重看/重拍、取消与过期结果隔离。
- 实验算法：OpenCV 对齐眼部裁切 → 补偿小范围位移和亮度 → 新增深色区域 → 外眼角附近连通区域 → 拟合方向。结果为接近参考、偏高、偏低、无法判断。
- 实验参数：相差超过 10° 为明显偏离；比较的是图像内眼部局部坐标中的方向，不是真实三维角度或美妆标准。
- 保守拒判：模糊、闭眼、过远、大姿态变化、明显未对齐/大区域变化、候选不可靠时拒判。关键点不证明无遮挡，用户需要主动确认；这套规则不能保证识别所有手、工具和阴影。
- 没有实现：自动手部事件、连续笔尖追踪、眼线粗细/连续性评价、双眼对称、完整妆容推荐、后端/账号/持久化。
- 性能现状：面部推理最多约每 65 ms 尝试一次，不积压视频帧。MediaPipe 和单次 OpenCV 分析均在主线程，设备上可能出现卡顿；尚未证明手机帧率。先通过手机实测，再决定是否需要 Worker。
若分析组件加载失败，仍可使用定位和分步指导，并明确显示“分析暂不可用”。没有模拟结果、随机评分或隐藏演示答案。
官方 E2E 验收命令只有 npm run test:e2e；Worker 数量由
playwright.config.ts 统一限制，不要在本机或 CI 另加 --workers 参数。
npm run test
npx playwright install chromium
npm run test:e2e
npm run build如果已安装 Google Chrome，可以用 PW_CHANNEL=chrome npm run test:e2e。浏览器测试使用隔离的合成视频和测试用关键点，OpenCV 实际运行；另有本地 MediaPipe 模型加载/非人脸推理测试。测试替身不被应用入口引用，也不进入生产构建。
真实样本的执行入口：
npm run test:vision -- samples/private/manifest.json没有提供真实样本时，该命令明确返回 NOT RUN 和退出码 2，不伪造通过结果。数据格式、验收门槛与手机/用户测试表见 测试说明。
| 文件 | 职责 |
|---|---|
src/vision/ |
摄像头、模型、当前帧关键点与原始图采集 |
src/guidance/ |
统一眼部坐标、渐细轮廓、共用绘制器、实时放大与明确标注的示意图 |
src/analysis/ |
OpenCV 加载、对齐、候选提取和方向评价 |
src/session.ts |
步骤状态、基准图/目标版本、检查请求隔离 |
src/App.tsx |
工作台、眼线入口和离开确认 |
src/EyelinerPractice.tsx |
同一摄像头会话中的准备、练习、结果与完成交互 |
tests/ |
Playwright 页面流程与异常测试 |
scripts/validate-dataset.mjs |
实际样本批处理与验收报告 |
现有调研资料保留在 research/。第三方组件来源见 第三方说明。