juzi/reference/facepp-skinanalyze/SKILL.md

name, description, version, author

name	description	version	author
facepp-skinanalyze	旷视Face++皮肤分析专业版(skinanalyze_pro)标准调用与报告技能。触发词：跑测肤/皮肤检测/巨子测肤/肤质分析/skinanalyze。覆盖凭据管理、API调用模板、参数坑、三维度×6分类评分公式（2026-09-26版）、AR列真值源、Excel报告生成铁律。适用于任何Agent调用旷视测肤接口或生成肤质报告。	1.1.0	lynaimining

facepp-skinanalyze（旷视皮肤分析专业版调用技能）

巨子测肤项目实测验证（2026-09）。禁止现场手写列号脚本——那是「肌肤年龄空列/错位3格」事故根因。

1. 凭据（统一管理）

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. 标准调用模板（全可选参数，每次都带）

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 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 打开文件