中医面舌辨证（tcm-face-tongue）

何时使用

• 用户上传正脸照 → 走 face 模式（望面，输出体质 + 五脏分析 + 食谱）
• 用户上传伸舌照 → 走 tongue 模式（望舌，输出舌象分类 + 体质 + 症状）
• 用户同时给出人脸 + 舌头两张图 → 走 combined 模式（面舌辨证，输出主/次体质与综合解读）

如不确定哪种模式，按以下优先级：

1. 如果手上同时有"face + tongue"两图 → combined（信息最完整）
2. 只有人脸 → face
3. 只有舌头 → tongue

接口元数据

• 网关：https://facepro.ragehealth.cn/openapi-test（测试环境，正式环境为 https://gateway.ragehealth.cn/openapi-prod）
• 请求方式：POST + multipart/form-data
• 认证头：AccessKey、Signature（每次调用前重新生成）
• 三个接口：

> 关于 combined 的本地图片：官方接口只接 URL。当任一输入是本地文件时，call_tcm.py combined 会自动 客户端 fallback：分别调用 face + tongue 接口并把结果合并为 { faceTcm, tongueTcm, comprehensiveInterpretation: null, _clientFallback: true }。此时缺失服务端的 comprehensiveInterpretation.summary，需要由调用方根据 faceTcm + tongueTcm 自行综合解读。

公共可选参数（face 与 combined）

> tongue 模式只接受 imageUrl / imageFile，不支持上述地理 / 人口学参数。

调用方式

# 望面（URL 或本地文件二选一）
python scripts/call_tcm.py face \
  --image-url https://example.com/face.jpg \
  [--province 广东省 --city 深圳市] [--age 30 --gender 0] [--skin-info 油性] \
  [--output face.json] [--full-stdout]

# 望舌
python scripts/call_tcm.py tongue \
  --image-file C:/path/to/tongue.jpg \
  [--output tongue.json]

# 面舌辨证：双 URL 走官方接口；任一为本地文件则自动 client-side fallback
python scripts/call_tcm.py combined \
  --face-image-url https://example.com/face.jpg \
  --tongue-image-url https://example.com/tongue.jpg \
  [--age 30 --gender 0] [--province 广东省 --city 深圳市] \
  [--output combined.json]

# 面舌辨证（fallback：本地图）
python scripts/call_tcm.py combined \
  --face-image-file C:/path/to/face.jpg \
  --tongue-image-file C:/path/to/tongue.jpg \
  --output combined.json

凭证由脚本自动从环境变量 TCM_AK / TCM_SK 读取，不要作为参数传入。首次使用前需前往 注册申请 AK/SK，写入 scripts/.env（可与 skin-pro 共用同一对凭证）。脚本内部会生成 Signature 并以 multipart/form-data 提交。

执行步骤

1. 判定模式：按上文"何时使用"的优先级选 face / tongue / combined。
2. 校验输入：图片 jpg/png；伸舌图需正面伸出、光线充足、无明显反光。
3. 调脚本：拿到 JSON；success=false 时提示用户重拍或检查图片质量。
4. 解读关键指标（按模式取）：
• face（data 直接挂）：
• 基础：age / gender / display_img / face_color_region_show_url / occlusion.glasses
• 大字段（默认会被脚本从 stdout 剥离，仅 --output 文件保留）：landmarks / raw_landmarks（478 个 [x,y] 关键点）
• 五脏分析：report_items[]（每项 type ∈ {体质,心,肝,脾,肺,肾}），含 regions / syndromes / diseases / yin_score / yang_score / yin_yang_status / face_color / body_type / out_reason / emotion / analysis / suggests / disease_analysis / disease_suggests
• 食谱：recipes[]（按 type 关联到对应 report_items），含 food_name / effect / ingredients / way / notice / food_image_url
• tongue（data 直接挂）：
• 综合：score（0~100，越高越健康）、overview
• 体质：tiZhi.tizhiType + tiZhi.tiZhiReason
• 症状：symptomArray[].{symptom, symptomReason}
• 舌象分类：classify[].{className, classNameCn, category, score, resolution, deductionScore}，按 category 分组：舌形 / 舌神 / 舌色 / 苔色 / 苔质
• 局部检测：detection.{boxes, polygon, scores, labels, classnames, classNamesCn, resolutions, deductionScores}（裂痕/齿痕/点刺；可能为空 dict 表示舌形正常）
• combined（data 直接挂）：
• faceTcm / tongueTcm：分别是 face / tongue 接口的完整响应（结构同上）
• comprehensiveInterpretation：核心结论（client-side fallback 时为 null）
• tizhi：综合体质（如 "湿热质"）
• tizhi1 / prop1：主要体质 + 置信度
• tizhi2 / prop2：次要体质 + 置信度
• summary：综合解读
• mainSymptom：主导体质的主要表现
• auxiliarySymptom：兼夹体质 / 次要病理特征
• _clientFallback：仅在 client-side fallback 时为 true，提示需要调用方自行综合 faceTcm + tongueTcm 给出解读

字段枚举字典（face / combined 的 report_items）

部分字符串字段是固定枚举，直译可能让用户困惑，建议解读时映射成自然语言：

> 提示：当多个 report_items 的 yin_score / yang_score / body_type / out_reason / emotion 完全相同时，多半是接口用「整体体质」结论填充各脏腑默认值，单脏腑无需重复强调，可只在「综合体质」段引用一次。

1. 生成报告（建议骨架）：
• 综合体质 + 置信度（combined 用 tizhi1/prop1+tizhi2/prop2；单 face 用 report_items[type=体质]；单 tongue 用 tiZhi.tizhiType）
• 五脏失衡 Top（face/combined 才有）：按 report_items 中阴阳得分偏离平衡显著的脏器
• 舌象要点（tongue/combined 才有）：列出 classify 中 classNameCn != '正常' 的项 + 对应 resolution
• 推荐食谱 / 调理建议：face 直接取 recipes；tongue 提取 symptomArray 配合体质给通用建议
• 综合解读：combined 直接用 comprehensiveInterpretation.summary

安全 & 合规

⚠️ 必须提醒：

• 中医辨证结果仅供参考，不能替代执业中医师面诊
• 严重或持续症状应建议线下就诊
• 食谱仅为日常调理建议，特殊体质 / 孕产妇 / 慢病患者 / 服药人群应遵医嘱
• 不在响应中泄露 AccessKey / SecretKey
• face_id / userGroup 涉及人脸特征数据，仅在用户明确授权时启用 faceIdDetect，避免无差别记录

示例

用户：帮我看下这两张照片（人脸 + 伸舌），分析下我现在的体质。

操作：

python scripts/call_tcm.py combined \
  --face-image-url https://example.com/face.jpg \
  --tongue-image-url https://example.com/tongue.jpg \
  --province 广东省 --city 深圳市 \
  --output combined.json

回复（节选）：

• 综合体质：湿热质（主，置信度 0.62）+ 气郁质（次，置信度 0.21）
• 主要表现：面色偏黄、舌红苔黄腻、口苦
• 五脏：肝阳偏盛，脾偏湿
• 调理：清热祛湿 + 疏肝解郁；推荐食谱：薏苡仁赤小豆汤
• 建议：清淡饮食、忌辛辣油腻、规律作息；持续不适请线下面诊