116 lines
10 KiB
Markdown
116 lines
10 KiB
Markdown
---
|
||
name: facepp-skinanalyze
|
||
description: 旷视Face++皮肤分析专业版(skinanalyze_pro)标准调用与报告技能。触发词：跑测肤/皮肤检测/巨子测肤/肤质分析/skinanalyze。覆盖凭据管理、API调用模板、参数坑、三维度×6分类评分公式（2026-09-26版）、AR列真值源、Excel报告生成铁律。适用于任何Agent调用旷视测肤接口或生成肤质报告。
|
||
version: 1.1.0
|
||
author: lynaimining
|
||
---
|
||
|
||
# facepp-skinanalyze（旷视皮肤分析专业版调用技能）
|
||
|
||
巨子测肤项目实测验证（2026-09）。禁止现场手写列号脚本——那是「肌肤年龄空列/错位3格」事故根因。
|
||
|
||
## 1. 凭据（统一管理）
|
||
|
||
```bash
|
||
set -a; source ~/.openclaw/credentials.env; set +a
|
||
# FACEPP_API_KEY / FACEPP_API_SECRET / FACEPP_SKINANALYZE_URL
|
||
# 新凭据一律存 ~/.openclaw/credentials.env（chmod 600），不散落、不明文入库
|
||
# 控制台: https://console.faceplusplus.com.cn —— 必须用「正式」key，试用 key 调不了专业版（见第 2 节坑清单）
|
||
```
|
||
|
||
当前凭据状态（2026-09-26 下午更新）：
|
||
- `FACEPP_API_KEY` = `EcZi…`（32 位，**正式 key**）✅
|
||
- `FACEPP_API_SECRET` = 32 位 ✅（2026-09-26 从微信 ClawBot 2026-09-22 17:51 记录找回）
|
||
- `FACEPP_SKINANALYZE_URL` = `https://api-cn.faceplusplus.com/facepp/v1/skinanalyze_pro` ✅
|
||
- ✅ pro 端点实测可用（含三视图/下颌线）。正式 key 也有并发窗口：串行 + 间隔 4 秒，偶发 CONCURRENCY_LIMIT_EXCEEDED 自动重试即可
|
||
|
||
## 2. 标准调用模板（全可选参数，每次都带）
|
||
|
||
```bash
|
||
curl -s "$FACEPP_SKINANALYZE_URL" \
|
||
-F api_key=$FACEPP_API_KEY -F api_secret=$FACEPP_API_SECRET -F image_file=@$IMG \
|
||
-F "return_maps=water_area,red_area,brown_area,texture_enhanced_pores,texture_enhanced_blackheads,texture_enhanced_oily_area,texture_enhanced_lines,rough_area,roi_outline_map,texture_enhanced_bw" \
|
||
-F "return_marks=wrinkle_mark,melanin_mark,dark_circle_outline"
|
||
```
|
||
|
||
一键脚本见 examples/call_skinanalyze.sh（单正脸版）/ examples/call_skinanalyze_3view.sh（三视图版，含重试，2026-09-26 实测通过）。
|
||
|
||
## 2b. 三视图调用模板（正脸 + 双侧脸 → 下颌线）
|
||
|
||
```bash
|
||
bash examples/call_skinanalyze_3view.sh <正脸图> <左侧脸图> <右侧脸图> [输出json]
|
||
```
|
||
- 参数：`image_file` + `left_side_image_file` + `right_side_image_file` + `return_side_results=jawline_info`
|
||
- 下颌线返回在**顶层** `left_side_result` / `right_side_result`（不在 result 里）
|
||
- `jawline_quality` 必须 =1 角度才有效（2=侧脸<20°/3=>120°/4=无人脸/5=无效/6=其它）
|
||
- 脚本内置 3 次递增退避重试（10s/20s/30s），应对正式 key 的偶发并发限制
|
||
- 示例图片在 examples/images/（1 组三视图：正脸 C3_180.jpg + 左 C3_135.jpg + 右 C3_-135.jpg）
|
||
|
||
实测坑清单：
|
||
- `roi_outline_color` 报 BAD_ARGUMENTS（ff0000/CCOOFF 均拒绝）→ 弃用，用默认色
|
||
- `left/right_roi_outline_map` 请求了也不返回（接口行为）
|
||
- sensitivity 对象缺返回只发生在不带 return_maps 的调用；带全参数后每次都返回
|
||
- jawline_score/cheekbone_mark 需侧脸图（left/right_side_image_file + return_side_results=jawline_info），纯正脸永远拿不到
|
||
- **✅ 三视图调用（2026-09-26 实测通）**：正脸 image_file + `left_side_image_file`/`right_side_image_file` + `return_side_results=jawline_info`。下颌线返回在**顶层** `left_side_result`/`right_side_result`（不在 result 里！）：`jawline_angle`（标准区间 116–120°，angle_level 0=标准）、`jawline_quality`（=1 才有效，2=侧脸角度<20°/3=>120°/4=无人脸/5=无效/6=其它）。接口不判断左右图是否传反，建议两侧都传
|
||
- 正脸/侧脸判定：看 `result.image_quality.face_orientation.yaw`（|yaw|<10° 正脸，±40–50° 侧脸）
|
||
- `face_maps` 返回 base64（red_area 是 jpeg 头、其余 png），解码后 openpyxl add_image 嵌入
|
||
- 返回图 url 需下载保存，原始 JSON 落盘
|
||
- 试用 key 有公用并发限制（CONCURRENCY_LIMIT_EXCEEDED→串行+重试）；专业版必须正式 key
|
||
- **✅ 2026-09-26 已换正式 key（EcZi…）并验证 pro 可用**。正式 key 也有并发窗口：连续快速调用偶发 CONCURRENCY_LIMIT_EXCEEDED，**串行 + 间隔 4 秒**即可
|
||
- **🔴 头号坑：试用 api_key 根本调不了专业版。** 旷视技术顾问 2026-09-22 在「巨子生物肌肤检测专业版技术对接」群明确答复：
|
||
- 「所有用户试用 api_key 是公用并发的」→ 密集调用必报 `CONCURRENCY_LIMIT_EXCEEDED`
|
||
- 「**试用 api_key 不能调用皮肤分析专业版**」「**专业版只能用正式 api_key 来调用**」
|
||
- 2026-09-26 复测：当前 `cAa5…` 调 pro **12/12 次全部 CONCURRENCY_LIMIT_EXCEEDED**（跨 3 分钟、带/不带可选参数、换图均失败）→ **重试无用，不要浪费时间重试**
|
||
- **解法**：到 https://console.faceplusplus.com.cn 控制台**创建正式 API Key**（不是试用）后替换 credentials.env。拿到正式 key 前，pro 重跑这条路是堵的
|
||
- 同 key 调**标准版 `skinanalyze`（非 pro）可以通**，但只返回老版枚举字段（pores_forehead/eye_pouch/nasolabial_fold/dark_circle/skin_type 等 value 0–2），**没有** water_score / sensitivity_score / sensitivity_area / melanin_score / wrinkle_info 分区分 / pores_type_score / skin_age，算不了现行六分类 → **不能替代 pro**，别拿它凑数
|
||
|
||
## 3. 三维度 × 6 分类 P/S 计算（2026-09-26 生效，取代旧六维）
|
||
|
||
> ⚠️ 旧的六维度（衰老/色沉/粗糙/皱纹/水分/敏感）已废弃。现行为 **紧塑力 / 活力感 / 稳定力** 三维度，各辖 2 个分类。用户另有一版拍板：产品分组按**真实年龄**而非 skin_age（见第 4 节）。
|
||
|
||
| 维度 | 分类 | P 公式 |
|
||
|---|---|---|
|
||
| 紧塑力 | 轮廓 | eye_pouch 严重度映射：0→100 / 1→90 / 2→79 / 3→74（下颌线、苹果肌需侧脸图，正脸永远拿不到） |
|
||
| 紧塑力 | 皱纹 | `100 − max(12 分区 wrinkle_score)`；分区 severity≥2→锁 79，≥3→锁 74 |
|
||
| 活力感 | 光滑 | `0.4×min(4 分区 pores_type_score) + 0.3×blackhead_score + 0.3×rough_score（纹理分）`；分区毛孔 severity≥2→锁 79 |
|
||
| 活力感 | 肤色水润 | `0.5×(melanin_score − melasma×10 − freckle×5) + 0.5×water_score`；water_severity≥60 且 water_score≥80→按 severity 换算 |
|
||
| 稳定力 | 敏感 | `min(sensitivity_score, 100 − sensitivity_area×1.5)`；面积≥15%→79，≥30%→74（面积用**百分比**口径） |
|
||
| 稳定力 | 痘痘 | `min(acne_score 分级映射, 100 − 计数扣分)`；分级 ≥95→100 / 85–94→85 / 75–84→70 / <75→55；扣分 = 闭口×1+丘疹×2+脓包×4+结节×6+痘印×1.5，封顶 50。**新增维度，无来源文档背书，待客户确认** |
|
||
|
||
- 维度 P = `min(旗下两个分类 P)`（木桶口径）
|
||
- `S = 7 + 3×P/100`，保留两位；档位 `P<80 预警 / 80–89 改善 / ≥90 良好`
|
||
- **判档一律用未四舍五入的原值**（曾因先四舍五入到 9.0 再判档，把 8.9967 错挂 25+ 束紧）
|
||
|
||
### 3.1 本轮踩过的坑（务必避复）
|
||
|
||
- **AQ 列 JSON 被 Excel 32767 字符截断 → 不要拿它当重算主数据源**。真值在源表的 **AR「六维公式记录」列**：那是当年用完整 JSON 生成的计算记录，63/63 行含 `min(pores_type_score)`、`max(wrinkle_score)`、`severity`、`water_severity`、`blackhead_score`、`skin_type_score`。**缺真值时先查 AR 列，不要急着重跑接口**
|
||
- **不要从旧文案列正则反解字段**，会串字段（实测 water_severity 反解 57/63 取值错误）
|
||
- **不要靠「旧 P 恰为某阈值」反推锁值**。曾据此误判 Excel 行 51/52/53 触发锁值，实为 `0.4×100+0.3×100+0.3×肤质分(30)=79` 的自然结果。严谨做法：比对「记录值 vs 自然计算值」，差值才是锁值痕迹（实测触发 0 次）
|
||
- **旧表只在 severity≥2（触发锁值）时才记录 severity**，故 AR 里 severity 实际 57/63 可得，缺的行意味着 severity<2
|
||
- 毛孔分不可用整脸 `pores_score` 退化（偏高），必须 `min(pores_type_score)`（实测 43 行偏差，最大 7.6 分）
|
||
|
||
## 4. 产品分组公式
|
||
|
||
- **当前口径（用户拍板）**：按**真实年龄** —— <32→25+组；32–45→35+组；>45→50+组；肌肤年龄钳制在真实年龄 ±3 内
|
||
- **文档口径（V1.2 第四章）**：按接口测出的 `skin_age` 定组，skin_age 本身不得改写，只有落在组边界 ±3 岁模糊带才允许 R1–R4 跨组修正。**当前实现偏离 V1.2，须向客户明示**
|
||
- 辅助判据：25+ 看 dark_circle_severity/eye_pouch/fine_line；35+ 看 nasolabial_fold_severity/wrinkle_deep_num；50+ 看 mouth_wrinkle/rough_severity/色素累积
|
||
|
||
## 5. Excel 报告铁律（必须遵守）
|
||
|
||
1. 禁止硬编码列号/col 递增。用「表头名→列号」映射：`hdr_col = {ws.cell(2,j).value.split('\n')[0].strip(): j}`，写入 `ws.cell(row, hdr_col['肌肤年龄 skin_age'], v)`
|
||
2. 跳过 IMG/NAME/RUN 元数据列时单独处理，指标列只走映射
|
||
3. 写完必须自校验：抽查首行逐项断言 `ws.cell(row, hdr_col[表头]).value == 写入值`，不一致立即报错，不许静默保存
|
||
4. 结果图直接嵌入表格单元格（openpyxl add_image），不能只给 URL 列
|
||
5. **删列/插列与图片锚点（2026-09-26 实测坑）**：
|
||
- xlsx 的 `drawing1.xml` 锚点列号是 **0 基**，别当 1 基算（曾因此把 264 张图错位 18 列）
|
||
- 原生文件与 openpyxl 保存过的文件 **rid 编号体系不同**（rId0 起始 vs rId1 起始），跨文件按 rid 对锚点会错位
|
||
- 大改（删 10+ 列）别在成品上叠补丁：**从干净备份整体重建**，一次性按映射改 sheet1.xml + drawing1.xml 再重打包
|
||
- openpyxl 的 insert_cols/delete_cols 在锚点列**之后**操作安全；跨锚点列必错
|
||
- 校验锚点看分布：本表应为 {col0:23, col21:88, col22:88, col23:88}（同格多图靠 colOff 侧排是原表设计，不算重复）
|
||
|
||
## 6. 其他 Agent 调用约定
|
||
|
||
- 接口调用统一走 examples/call_skinanalyze.sh，凭据只从 ~/.openclaw/credentials.env 读取
|
||
- 原始返回 JSON 必须落盘再处理，不要在内存里即调即丢（方便复核）
|
||
- 生成 Excel 后：抽查首行自校验 + afplay Glass.aiff + open 打开文件
|