save

docs/三维度评分与话术生成需求文档_V2.0.md

@@ -0,0 +1,336 @@
+# 三维度评分与话术生成需求文档_V2.0
+
+巨子测肤·三维度评分与话术生成需求文档
+
+__版本 V2\.0 ｜ 2026\-09\-26 ｜ 数据来源：旷视FaceStyle智能测肤专业版 V1\.6\.3（skinanalyze\_pro，正式key）__
+
+变更说明（V1\.2→V2\.0）：①评分体系由"六维度"重构为"三维度×6分类"（紧塑力/活力感/稳定力），原衰老维度拆解归位，痘痘升级为正式评分分类；②产品分组改为按实际年龄分段（用户拍板，偏离V1\.2的skin\_age口径，已在第四章显著标注）；③精华推荐由"均分单判据"升级为"三重判据取最强档"，修复均分稀释短板缺陷；④新增三视图（正脸\+双侧脸）调用规范与下颌线评分规则；⑤全文自包含——6分类话术库、护理建议库、日常肤质映射库全部完整文本内嵌。
+
+# 一、接口调用规范
+
+每次调用必须带全可选参数（实测不带会导致 sensitivity 对象缺失、检测图不返回）：
+
+POST https://api\-cn\.faceplusplus\.com/facepp/v1/skinanalyze\_pro
+
+\- image\_file：正脸图（必传，JPG/PNG，人脸框≥400px、yaw≤±30°、清晰度合格）
+
+\- 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
+
+\- return\_marks=wrinkle\_mark,melanin\_mark,dark\_circle\_outline
+
+三视图调用（本章新增）：
+
+\- left\_side\_image\_file / right\_side\_image\_file：左右侧脸图（可选，接口不校验左右是否传反，建议两侧都传）
+
+\- return\_side\_results=jawline\_info：返回下颌线信息（在响应顶层 left\_side\_result / right\_side\_result，不在 result 内）
+
+__返回块__
+
+__字段__
+
+__说明__
+
+left\_side\_result\.left\_jawline\_info
+
+left\_jawline\_angle
+
+左下颌线角度，标准区间116–120°
+
+同上
+
+left\_jawline\_angle\_level
+
+0=标准 / 1=不标准
+
+同上
+
+left\_jawline\_quality
+
+侧脸质量：1=有效（20°~120°）/2=角度<20°/3=>120°/4=无人脸/5=无效人脸/6=其它；仅=1时角度才有校验意义
+
+right\_side\_result\.right\_jawline\_info
+
+right\_jawline\_angle 等
+
+同上，右侧
+
+实测注意事项：① roi\_outline\_color 参数实测报 BAD\_ARGUMENTS，弃用；② left/right\_roi\_outline\_map 请求后不返回；③ jawline 仅在有侧脸输入且 return\_side\_results=jawline\_info 时返回；④ 不带 return\_maps 时 sensitivity 对象随机缺失；⑤ 正式key也有并发窗口，串行调用\+间隔4秒，偶发 CONCURRENCY\_LIMIT\_EXCEEDED 自动重试1次；⑥ 返回图 face\_maps 为 base64（red\_area为JPEG头，其余PNG），需解码后嵌入报告。
+
+计费：按次消耗次数包。调用前必须走图片预校验，不合规直接拦截重拍。正脸/侧脸判定依据 image\_quality\.face\_orientation\.yaw：|yaw|<10°为正脸，±40–50°为侧脸。
+
+# 二、三维度×6分类 P 分计算规则（0–100）
+
+__维度__
+
+__分类__
+
+__公式__
+
+__修正规则（上限锁）__
+
+__字段来源__
+
+紧塑力 firming
+
+轮廓 firmness\_contour
+
+P = min\(眼袋severity映射分, 下颌线角度分\)。眼袋映射：0→100/1→90/2→79/3→74；下颌线角度分=100−|偏离标准区间116–120°|×2，下限60，左右取较差侧
+
+无（映射自带）
+
+eye\_pouch\_severity\.value；left/right\_side\_result\.\*\_jawline\_info\.\*\_jawline\_angle
+
+紧塑力 firming
+
+皱纹 wrinkles
+
+P = 100 − max\(12分区 wrinkle\_score\)
+
+分区 severity≥2→上限79；≥3→上限74
+
+12个 \*\_wrinkle\_info\.wrinkle\_score / wrinkle\_severity\_level
+
+活力感 vitality
+
+光滑 smoothness
+
+P = 0\.4×min\(4分区 pores\_type\_score\) \+ 0\.3×blackhead\_score \+ 0\.3×rough\_score\(纹理分\)
+
+任一分区毛孔 severity≥2→上限79
+
+score\_info\.pores\_type\_score\.\*、blackhead\_score、rough\_score
+
+活力感 vitality
+
+肤色水润 tone\_hydration
+
+P = 0\.5×\(melanin\_score−melasma×10−freckle×5\) \+ 0\.5×water\_score
+
+water\_severity≥60 且 water\_score≥80→水分项按 severity 换算
+
+score\_info\.melanin\_score、melasma\.value、freckle\.value、water\_score、water\.water\_severity
+
+稳定力 stability
+
+敏感 sensitivity
+
+P = min\(sensitivity\_score, 100−敏感面积%×1\.5\)
+
+面积≥15%→上限79；≥30%→上限74（面积用百分比口径）
+
+score\_info\.sensitivity\_score、red\_spot\.red\_spot\_area（小数×100=%）
+
+稳定力 stability
+
+痘痘 acne
+
+P = min\(acne\_score分级映射, 100−计数扣分\)。分级映射：≥95→100/85–94→85/75–84→70/<75→55；扣分=闭口×1\+丘疹×2\+脓包×4\+结节×6\+痘印×1\.5，封顶50
+
+无
+
+score\_info\.acne\_score、closed\_comedones\.count、acne\.count\(丘疹\)、acne\_pustule\.count、acne\_nodule\.count、acne\_mark\.count
+
+__维度级汇总（木桶口径）：紧塑力P = min\(轮廓P, 皱纹P\)；活力感P = min\(光滑P, 肤色水润P\)；稳定力P = min\(敏感P, 痘痘P\)。__
+
+待客户确认项：①痘痘P公式为本版自设计（接口无"痤疮分级severity"字段，以acne\_score分档替代），无文档背书；②下颌线角度映射系数（每偏离1°扣2分、下限60）为自设计；③光滑第三因子由V1\.2的skin\_type\_score改为rough\_score（接口表"光滑"清单无肤质分）。
+
+兼容性提醒：不同批次返回的毛孔/皱纹分区字段命名存在变体（pores\_type\_score 嵌套在 score\_info 内、分区键 left\_nasolabial\_wrinkle\_info 与 left\_nasolabial\_fold\_info 并存），适配层必须做字段归一映射。
+
+# 三、S 分与档位
+
+S = 7 \+ 3×P/100（保留两位小数）。档位判定一律以 P 为准（含上限锁后）：P<80 预警档（S 7\.0–7\.9）；80≤P<90 改善档（S 8\.0–8\.9）；P≥90 良好档（S 9\.0–10\.0）。判档必须使用未四舍五入的 P 原值（历史缺陷：先四舍五入到9\.0再判档，曾把8\.9967错挂25\+束紧）。
+
+# 四、产品分组算法与精华推荐（重点）
+
+__4\.1 分组口径（用户拍板，偏离V1\.2）__
+
+按实际年龄 real\_age 分段：<32岁→25\+组；32–45岁→35\+组；>45岁→50\+组。
+
+⚠️ 显著偏离说明：V1\.2 第四章规定"分组按 skin\_age 定且 skin\_age 不得改写，边界±3岁模糊带才允许R1–R4跨组修正"。V2\.0 改按实际年龄分段（业务方拍板）。skin\_age 数值本身仍不被改写，仅作为参考读数展示。上线前需与客户书面确认此口径变更。
+
+__4\.2 肌肤年龄钳制__
+
+为满足"肌肤年龄与真实年龄差不超过±3岁"的展示约束：肌肤年龄\(展示值\) = min\(max\(skin\_age, 实际年龄−3\), 实际年龄\+3\)；超出即截断到边界，并输出钳制标记"触发\(原X→Y\)"。skin\_age 原始值在任何逻辑下不被改写。
+
+__4\.3 精华推荐·三重判据取最强档（V2\.0修正，核心）__
+
+__判据__
+
+__规则__
+
+__说明__
+
+① 均分档
+
+六分类S均分（未四舍五入原值）≥9→25\+束紧 / 8–9→35\+支撑 / <8→50\+重塑
+
+V1\.2 原口径
+
+② 最差项约束
+
+最差分类 S<7→50\+重塑 / 7≤S<8→至少35\+支撑 / S≥8→不约束
+
+防均分稀释短板：皱纹P=50的人均分仍可达9\.5，单看均分会错推最年轻产品线
+
+③ 年龄组档
+
+产品组别 25\+/35\+/50\+组 → 对应档
+
+按实际年龄分段（4\.1）
+
+__最终推荐 = max\(①②③\)，推荐强度只升不降。报告页须展示命中的判据（如"触发：年龄组档"）。__
+
+历史缺陷记录：V1\.2 均分单判据下，实测 50 岁肌龄、皱纹P=50、最差S=8\.5 的案例因均分9\.54 被推"25\+束紧精华"——业务不可接受，此为本章修正的直接原因。
+
+# 五、6分类话术库（全量文本，按档位 if\-else 拼接）
+
+生成规则：按分类 P 档位选中话术主体，替换 \{\} 变量为当次实测值，输出100–150字。变量缺失时省略对应分句，禁止输出"None/—"占位（历史缺陷：enlarged\_pore\_count 为dict被当int取，输出"粗大毛孔None颗"）。
+
+变量表：\{skin\_age\}肤龄、\{la\}/\{ra\}左右下颌线角度、\{eye\_pouch\}眼袋级、\{dark\_circle\_sev\}黑眼圈级、\{wr\_cnt\}全脸皱纹条数、\{fl\_cnt\}细纹条数、\{worst\_wr\_region\}最差皱纹分区、\{wr\_max\}该区分区分、\{max\_sev\}最高严重度、\{worst\_pore\_region\}最差毛孔区、\{pore4\_min\}该区毛孔分、\{pore\_cnt\}粗大毛孔总数\(4分区求和\)、\{blackhead\_cnt\}黑头数、\{tex\}纹理分、\{ita\}ITA数值、\{st\}肤色分类、\{ha\}HA值、\{melanin\}色素分、\{spot\_flag\}色斑标记句、\{bs\_cnt\}褐色斑数、\{mole\_cnt\}痣数、\{water\_score\}水分分、\{water\_area\}缺水面积%、\{water\_sev\}缺水严重度、\{sens\_area\}泛红面积%、\{sens\_score\}红区分、\{acne\_cnt\}皮损合计、\{acne\_detail\}皮损明细句、\{skin\_type\_cn\}肤质类型、\{oil\_desc\}出油概览句。
+
+## 5\.1 轮廓（紧塑力）
+
+【预警】"面部轮廓出现可见松弛，下颌线角度左\{la\}°/右\{ra\}°（标准区间116–120°，双侧均偏离标准，提示下颌缘支撑力下降）；眼袋\{eye\_pouch\}级、黑眼圈\{dark\_circle\_sev\}级；中面部支撑与轮廓清晰度处于预警水平。建议加强轮廓紧致护理：重点针对下颌线与下颌缘区域使用紧致类精华，配合由下向上的提拉按摩手法，同时加强眼周支撑护理，将紧致防线前置。"
+
+【改善】"下颌线角度左\{la\}°/右\{ra\}°（标准区间116–120°），眼袋\{eye\_pouch\}级，眼下区域出现轻度松弛信号。建议增加紧致类精华步骤，配合由下向上的提拉按摩手法，重点关照眼周与中面部。"
+
+【良好】"面部轮廓紧致立体，下颌线角度左\{la\}°/右\{ra\}°（处于标准区间），眼袋\{eye\_pouch\}级、黑眼圈\{dark\_circle\_sev\}级，中面部容积饱满，未见明显软组织下垂。轮廓支撑力良好，建议维持日常紧致护理与防晒，保持规律作息，守护现有轮廓。"
+
+## 5\.2 皱纹（紧塑力）
+
+【预警】"全脸皱纹\{wr\_cnt\}条、细纹\{fl\_cnt\}条，最差区域为\{worst\_wr\_region\}（分区分\{wr\_max\}，最高严重度\{max\_sev\}级），部分区域已现静态纹趋势。建议针对眼周、法令纹等高发区使用视黄醇/胜肽类淡纹精华，遏制静态纹转化。"
+
+【改善】"全脸皱纹\{wr\_cnt\}条、细纹\{fl\_cnt\}条，最差区域为\{worst\_wr\_region\}（分区分\{wr\_max\}，严重度\{max\_sev\}级）。建议加强日常淡纹与弹润护理，保持肌肤滋润度。"
+
+【良好】"全脸12分区纹路平整（最差区域\{worst\_wr\_region\}，分区分\{wr\_max\}），细纹合计\{fl\_cnt\}条，未见明显静态纹。建议维持日常保湿与防晒，保持现有淡纹护理节奏。"
+
+## 5\.3 光滑（活力感）
+
+【预警】"皮肤表面平整度较低，最差毛孔区位于\{worst\_pore\_region\}（分区毛孔分\{pore4\_min\}），粗大毛孔\{pore\_cnt\}颗、黑头\{blackhead\_cnt\}颗，\{oil\_desc\}纹理分仅\{tex\}，整体细腻度不足。建议避免过度清洁，重点关注\{worst\_pore\_region\}，配合低浓度酸类周期护理与柔润精华。"
+
+【改善】"皮肤表面整体较为平滑，毛孔最差区为\{worst\_pore\_region\}（分区毛孔分\{pore4\_min\}），粗大毛孔\{pore\_cnt\}颗、黑头\{blackhead\_cnt\}颗，\{oil\_desc\}纹理分\{tex\}，局部存在轻微角质粗糙感。建议加强基础清洁与低浓度酸类周期护理。"
+
+【良好】"皮肤表面细腻平滑，最差毛孔区\{worst\_pore\_region\}控制良好（分区毛孔分\{pore4\_min\}，粗大毛孔\{pore\_cnt\}颗、黑头\{blackhead\_cnt\}颗），纹理分\{tex\}，角质层排列整齐。建议维持温和清洁与保湿节奏。"
+
+## 5\.4 肤色水润（活力感）
+
+【预警】"肤色ITA \{ita\}（\{st\}，HA \{ha\}），色素分\{melanin\}，整体偏暗沉（\{spot\_flag\}）；水分分\{water\_score\}，缺水面积\{water\_area\}%、严重度\{water\_sev\}，水润度不足。建议加强透亮与补水护理，做好防晒，减少色素刺激。"
+
+【改善】"肤色ITA \{ita\}（\{st\}，HA \{ha\}），色素分\{melanin\}，整体稳定但存在局部暗沉倾向（\{spot\_flag\}）；水分分\{water\_score\}，缺水面积\{water\_area\}%、严重度\{water\_sev\}。建议加强抗氧化与光泽管理，做好基础防晒与补水。"
+
+【良好】"肤色ITA \{ita\}（\{st\}，HA \{ha\}），色素分\{melanin\}，肤色均匀透亮（\{spot\_flag\}）；水分分\{water\_score\}，缺水面积\{water\_area\}%、严重度\{water\_sev\}。色素与水润状态均衡，建议持续做好防晒与基础保湿。"
+
+## 5\.5 敏感（稳定力）
+
+【预警】"泛红面积达\{sens\_area\}%，红区分\{sens\_score\}，屏障受损信号明显、敏感区域较大。建议立即转为舒缓修护路线，停用酸类与强清洁，必要时寻求专业建议。"
+
+【改善】"泛红面积\{sens\_area\}%，红区分\{sens\_score\}，存在局部轻微泛红与屏障波动。建议使用舒缓修护类产品，减少刺激源，注意温差与清洁力度。"
+
+【良好】"泛红面积\{sens\_area\}%，红区分\{sens\_score\}，屏障状态稳定，未见明显敏感信号。建议维持现有温和护理，避免过度去角质。"
+
+## 5\.6 痘痘（稳定力）
+
+【预警】"检出\{acne\_cnt\}处皮损（\{acne\_detail\}）\{heavy\_note\}。建议尽快进行针对性抗痘护理，避免挤压与刺激，必要时寻求皮肤科专业处理。注：\{heavy\_note\}仅在真实检出脓包/结节时输出"含脓包、结节等中重度皮损，炎症反应明显"，禁止模板硬套。"
+
+【改善】"检出\{acne\_cnt\}处皮损（\{acne\_detail\}），以闭口粉刺、丘疹为主，局部存在炎症倾向。建议加强温和清洁与控油，避免挤压，配合抗炎舒缓护理。"
+
+【良好】"未检出痤疮与皮损。建议维持清洁与控油节奏，注意作息与饮食。"
+
+变量拼接规则：\{spot\_flag\}＝检出黄褐斑和/或雀斑时输出"黄褐斑、雀斑"（只检出一种只写那一种），均未检出输出"未见明显色斑标记"；计数为0的分句整体省略（如痣0处不出现）；\{acne\_detail\}按实际计数列明细"闭口粉刺N处、丘疹N处、脓包N处、结节N处、痘印N处"，为0的类型不列。
+
+# 六、综合文案、生活方式与护理建议
+
+__6\.1 综合文案模板__
+
+【综合】实际年龄\{real\_age\}岁（接口测得肌肤年龄\{skin\_age\}岁，差\{age\_diff\}岁），产品组别\{group\}；六分类S均分\{avg\}、最差分类\{worst\_name\} S=\{worst\_s\}。按三重判据（触发：\{triggers\}）推荐\{essence\}：优先改善\{w1\}（P=\{w1\_p\}）与\{w2\}（P=\{w2\_p\}），其余维度维持现有护理节奏。整体肤质\{skin\_type\_cn\}，\{oil\_desc\}。
+
+精华产品推荐文本（三档全文）：
+
+【25\+束紧精华】"建议搭配使用25\+束紧精华：针对年轻肌肤活力减弱问题，激活肌肤动力、改善暗沉，提升弹润紧致表现，守护年轻光泽并延缓初始衰老迹象。"
+
+【35\+支撑精华】"建议搭配使用35\+支撑精华：专为轻熟肌打造，提升弹韧表现、维持面部轮廓清晰度，改善疲态并延缓衰老速度。"
+
+【50\+重塑精华】"建议搭配使用50\+重塑精华：针对成熟肌肤恢复能力下降，提升紧致表现、改善松弛与轮廓模糊，修复强韧屏障，重塑年轻质感。"
+
+__6\.2 生活方式建议（按最差分类取，并列时按 轮廓>皱纹>光滑>肤色水润>敏感>痘痘 取前者）__
+
+__最差分类__
+
+__生活方式全文__
+
+轮廓
+
+戒除揉眼、托腮等表情性挤压习惯，保证睡眠减少纹路加深
+
+皱纹
+
+保持侧卧改仰卧的睡姿习惯，减少枕巾摩擦；控制屏幕时间，缓解眼周疲劳
+
+光滑
+
+规律去角质但不过度（每1–2周一次），运动后及时清洁，减少油炸与高糖饮食
+
+肤色水润
+
+每日防晒足量补涂，增加维C与抗氧化食物摄入，保证饮水节奏
+
+敏感
+
+避免过热的水洗脸与桑拿，选择无香精配方，换季时精简护肤步骤
+
+痘痘
+
+不挤压痘痘，枕巾高频更换，减少乳制品与高升糖饮食摄入
+
+6\.3 护理建议结构与日常肤质映射：插入顺序【肤质定制】→【6分类按档位】→【综合】→【生活方式】。日常肤质 daily\_skin\_type 为用户自选项（混合偏干/干性/中性/油性/混合偏油五类），【肤质定制】段全文沿用 V1\.2 补充章节A映射库（五类全量文本与联动修正规则不变，此处不再重复）；肤质不参与任何分数计算，仅影响措辞。
+
+# 七、异常与边界
+
+__场景__
+
+__处理__
+
+NO\_FACE\_FOUND/人脸过小
+
+预校验拦截，引导正脸重拍，不消耗次数包
+
+侧脸质量 jawline\_quality≠1
+
+该侧下颌线角度不参与轮廓评分，报告标注"侧脸角度需20°–120°"引导重拍
+
+仅正脸无侧脸
+
+下颌线角度分不参与，轮廓P=眼袋映射分单独决定；报告标注"建议补拍侧脸视图"
+
+图片质量borderline
+
+正常返回但标记可信度降级，报告页提示重拍
+
+sensitivity缺失
+
+敏感维度文案输出数据缺失提示，禁止输出降级假分数
+
+接口超时/5xx/CONCURRENCY
+
+重试1次（间隔4秒）→失败展示"检测繁忙"
+
+同图多次调用数值漂移
+
+数值型字段应完全一致；不一致记录并反馈旷视
+
+字段命名变体
+
+毛孔/皱纹分区字段做归一映射后再计算
+
+Excel存储
+
+原始JSON禁止直接塞单元格（32767字符截断，历史AQ列事故）；表格内用扁平化路径=值清单，完整JSON独立落盘文件
+
+# 八、验收标准
+
+1\) 三维度×6分类 P/S/档位与第二章公式逐项可复算，参数与JSON字段路径一一对应；2\) 维度P=旗下分类min\(\) 木桶口径可复算；3\) 分组按实际年龄分段、精华按三重判据取最强档，且报告页展示触发依据；4\) skin\_age 原值不被改写，钳制仅作用于展示值并留痕；5\) 6分类话术与第五章文本库逐字一致（变量除外），无None/占位残留；6\) 判档一律用未四舍五入原值；7\) 三视图调用下颌线数据完整落表（角度/质量/标准度），无侧脸时按第七章降级；8\) 全部可选参数固定入参；9\) 同一图片重复调用结果逐字一致。
+
+
+<!-- conversion notes
+- Message(type='warning', message='Unrecognised paragraph style: Title (Style ID: Title)')
+-->

reference/facepp-skinanalyze/SKILL.md

@@ -0,0 +1,115 @@
+---
+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 打开文件

reference/facepp-skinanalyze/credentials.env

@@ -0,0 +1,16 @@
+# ~/.openclaw/credentials.env — 统一凭据存放（勿提交 git、勿发到聊天）
+# 用法: set -a; source ~/.openclaw/credentials.env; set +a
+
+# ---- 旷视 Face++（巨子测肤 skinanalyze_pro 测试接口）----
+# 试用key(cAa5...)已弃用: 旷视规则试用key不能调专业版。当前为正式key(EcZ...)
+FACEPP_API_KEY=EcZiqYhA8eQSiRgXVem8mijgzPfSC2qp
+FACEPP_API_SECRET=p62QRWv9tQitZ1tvXmEBV8AgmaS00lO8
+
+# ---- FaceStyle 专业版调用参数 ----
+FACEPP_SKINANALYZE_URL=https://api-cn.faceplusplus.com/facepp/v1/skinanalyze_pro
+
+# ---- 飞书 / OCR（合同盖章核验项目）----
+# 实际值在 ~/Desktop/合同盖章核验项目/service/.env（未入库）
+
+# ---- 智谱 / 火山引擎 ----
+# 已存于 ~/.zshrc 及 openclaw.json providers 配置

reference/facepp-skinanalyze/examples/call_skinanalyze.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Face++ skinanalyze_pro 标准调用
+# 用法: call_skinanalyze.sh <图片路径> [输出json路径]
+set -euo pipefail
+set -a; source "${CREDENTIALS_ENV:-$HOME/.openclaw/credentials.env}"; set +a
+IMG=${1:?用法: call_skinanalyze.sh <图片路径> [输出json]}
+OUT=${2:-/tmp/skinanalyze_result.json}
+curl -s "${FACEPP_SKINANALYZE_URL:-https://api-cn.faceplusplus.com/facepp/v1/skinanalyze_pro}" \
+  -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" | tee "$OUT"
+python3 - "$OUT" <<'PY'
+import json,sys
+d=json.load(open(sys.argv[1]))
+assert 'error_message' not in d, d.get('error_message')
+print('OK, top keys:', ', '.join(sorted(d.keys())[:10]))
+PY

reference/facepp-skinanalyze/examples/call_skinanalyze_3view.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# Face++ skinanalyze_pro 三视图调用（正脸 + 左右侧脸 → 下颌线）
+# 用法: call_skinanalyze_3view.sh <正脸图> <左侧脸图> <右侧脸图> [输出json]
+set -euo pipefail
+set -a; source "${CREDENTIALS_ENV:-$HOME/.openclaw/credentials.env}"; set +a
+
+FRONT=${1:?用法: call_skinanalyze_3view.sh <正脸图> <左侧脸图> <右侧脸图> [输出json]}
+LEFT=${2:?缺左侧脸图}
+RIGHT=${3:?缺右侧脸图}
+OUT=${4:-/tmp/skinanalyze_3view_result.json}
+
+retry() {
+  local n=0
+  until [ "$n" -ge 3 ]; do
+    RESP=$(curl -s "${FACEPP_SKINANALYZE_URL:-https://api-cn.faceplusplus.com/facepp/v1/skinanalyze_pro}" \
+      -F api_key=$FACEPP_API_KEY -F api_secret=$FACEPP_API_SECRET \
+      -F image_file=@"$FRONT" \
+      -F left_side_image_file=@"$LEFT" \
+      -F right_side_image_file=@"$RIGHT" \
+      -F "return_side_results=jawline_info" \
+      -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")
+    if ! echo "$RESP" | grep -q 'error_message'; then
+      echo "$RESP" > "$OUT"
+      return 0
+    fi
+    n=$((n+1))
+    echo "第${n}次失败: $(echo "$RESP" | head -c 120)，${n}0秒后重试..." >&2
+    sleep $((n*10))
+  done
+  echo "$RESP" > "$OUT"
+  return 1
+}
+
+retry || { echo "三次重试均失败" >&2; exit 1; }
+
+python3 - "$OUT" <<'PY'
+import json, sys
+d = json.load(open(sys.argv[1]))
+assert 'error_message' not in d, d.get('error_message')
+r = d['result']; si = r['score_info']
+ls = d.get('left_side_result', {}).get('left_jawline_info', {})
+rs = d.get('right_side_result', {}).get('right_jawline_info', {})
+print('OK skin_age:', r['skin_age']['value'],
+      '| total:', si['total_score'],
+      '| 左下颌线:', ls.get('left_jawline_angle'), '°(q%s)' % ls.get('left_jawline_quality'),
+      '| 右下颌线:', rs.get('right_jawline_angle'), '°(q%s)' % rs.get('right_jawline_quality'),
+      '| 标准区间 116-120°')
+print('完整结果已存', sys.argv[1])
+PY