形象护照 · Aesthetic Passport — V2
上传一张正脸，30 秒内看到第一个发现：面部特点、个人色彩、八型风格方向，以及能在自己身上看见的发型、唇色、披布和穿搭建议；
带走一张 3:4 档案卡，随时一键删除。V2 的定稿 PRD 在 docs/v2/，任务与接口在 docs/v2/V2_TASKS.md。
无需任何密钥即可完整体验（假模型 / 假图像编辑 / 假支付）：
make install && make models && (cd web && npm ci)
ANALYSIS_PROVIDER=fake IMAGE_EDIT_PROVIDER=fake PAYMENT_PROVIDER=fake QC_MODE=stub make dev # API :8000 + web :3000
# 或者完全不启动 API：
cd web && NEXT_PUBLIC_USE_FIXTURE=1 npm run dev
打开 /（落地页）、/t/style（话题入口）、/start（上传）或 /p/ap_sample_0001（示例档案，任何模式下都用样例数据）。
关键路径脚本：node web/e2e/critical-path.mjs（话题入口 → 同意 → 质检 → 揭晓 → 档案 → 反馈重排 → 免费试看 → 解锁 → 导出档案卡 → 删除）。
| 层 | V2 新增 |
|---|
| CV | 只需正脸（D20）；三庭五眼、虹膜比例尺；美颜检测；面部多边形（浏览器试色用，随照片 24 小时删除） |
| 模型 | 两段式：快速初见（analyzer-quick-0.1）+ 完整分析（analyzer-0.3），各自校验并修复一次（D21） |
| 规则 | 八型四层（D25）、反馈即时重排（D26）、三方向发型校验、镜框 mm、行动计划、穿搭一致性 |
| 图像 | 多目标试看、核心区像素不变 + 边缘软保护 + 颜色迁移、质量门与降级、“AI 试看”显式标识与隐式元数据（D22） |
| 商业 | 免费 vs 一次性完整护照；付费内容在服务端裁剪（D27） |
V1 说明（历史）
EN — Upload 2–4 photos and answer three questions → get a structured, evidence-backed personal styling report,
ranked into a top-5 action list → see the #1 change applied to your own photo. An AI-product portfolio piece:
multimodal pipeline → schema-constrained output → deterministic rules layer → image editing with a hard identity
guarantee → a UI that shows where every number came from. UI in Simplified Chinese; code and comments in English.
上传 2–4 张照片、回答三个问题，得到一份结构化、有依据、可执行的个人形象报告：五条按优先级排好的建议，每一条都能指回照片里的具体观察；再看到第一条用在你自己照片上的样子。
不打颜值分 · 不给医美建议 · 不推断年龄、民族、性别认同或健康 · 照片 24 小时内删除。
| 推荐造型（改造前后，脸部始终是原图像素） | 优先改进 Top 5（含「为什么排第一」） |
|---|
| |
| 视觉档案：测量 / 模型 / 规则 并排 | 手机端（375 px） |
| |
示例报告使用一位虚构用户的数据和示意插画（/sample），不含任何真人照片。
它证明了什么
不是「我会调视觉 API」，而是一条可追溯的产品管线：
flowchart LR
U["2–4 张照片<br/>+ 三个问题"] --> QC
subgraph CV["测量 · CV 层（MediaPipe + OpenCV）"]
QC["质检门禁<br/>人脸 · 清晰度 · 曝光 · 姿态 · 角色"] --> AN["锚点<br/>长宽比 · 额颧颌宽度"]
AN --> FS["脸型启发式"]
QC --> CS["颜色取样<br/>脸颊 · 眉 · 虹膜 · 唇 · 头发 Lab"]
end
QC -- 不合格 --> RT["重拍提示<br/>（不调用模型）"]
subgraph M["模型 · 单一生产模型（DeepSeek，JSON 模式）"]
LLM["一次视觉调用<br/>观察 → 推断 → 建议"] --> V{"Schema + 契约校验"}
V -- 失败（最多重试 1 次） --> LLM
end
AN --> LLM
FS --> LLM
CS --> LLM
subgraph R["规则 · rules.py + config/*.yaml"]
RU["约束复核 C5 · 依据完整 C4<br/>测量 vs 模型 C1–C3 · C11 · C12<br/>置信度封顶 · 季型门控<br/>排序（分数拆解）· 款式库匹配"]
end
V -- 通过 --> RU
AN --> RU
CS --> RU
RU --> P[("Passport JSON<br/>Schema v0.2")]
P --> WEB["报告页<br/>每个数值带来源标记"]
P --> PV["推荐造型<br/>头部裁切 → Qwen 图像编辑<br/>→ 蒙版回贴，脸部像素不变"]
PV --> WEB
| 来源 | 产生什么 | 代码 |
|---|
| 测量（CV） | input_quality、anchors（含脸型启发式）、color_measurements | qc.py · anchors.py · face_shape.py · color_sample.py |
| 模型 | analysis：观察、判断、四个方向块、6–8 条候选建议——只此一处 | analyzer.py · prompts/production_analyzer.md · schema/analysis.schema.json |
| 规则 | derived：排序与分数拆解、标签、一致性标记、封顶后的置信度、季型门控、参考款式 | rules.py · config/rules.yaml · config/hairstyles.json |
报告界面上每个值旁边都有 测量 / 模型 / 规则 标记；「视觉档案」一节把模型的脸型判断和 CV 启发式并排放，矛盾时由规则层标出（C11）。
- 单一生产模型 + 完整本地校验（D1、D10、D12）：JSON 模式只保证可解析，所以本地跑完整 Schema 和输出契约检查，失败带错误清单在同一对话里重试一次，再失败就明确报错。规则层结果（剔除、改判、封顶）从不触发重试。
- 连续维度是数据，风格标签只是界面语言（D2）：标签是（量感，曲直）平面上离哪个原型最近。
- 硬约束不靠模型自觉（D8）：「不染发」时，任何提到染发的建议都会被规则层改判剔除。
- 色彩只给方向（D3、D15）：CV 取样只用来交叉检查模型；冷暖置信度封顶；季型倾向只在通过门控时显示，措辞永远是「偏向某季型」。
- 像本人由回贴保证，不靠模型（D4、D17）：图像模型没有蒙版参数，所以最后一步是确定性的合成——眉线以下的脸、眼、鼻、口的 alpha 强制为 0。测试中即使假模型改动了每一个像素，这些区域与原图逐像素相同。
本地运行
需要：Python ≥ 3.11、Node 22；Linux 上 MediaPipe 还需要 libegl1 libgles2（sudo apt-get install libegl1 libgles2）。
make setup # .venv + Python 依赖 + MediaPipe 模型（models/，不入库）+ web 依赖 + .env
make dev # API http://localhost:8000 + 网页 http://localhost:3000
打开 http://localhost:3000 。不需要任何密钥也能走完整个流程：
| 没有密钥时 | 效果 |
|---|
ANALYSIS_PROVIDER=auto → fake | 分析内容来自示例数据，报告顶部显示「演示模式」 |
IMAGE_EDIT_PROVIDER=auto → fake | 效果图用简单调色演示「编辑区域 + 原脸回贴」，并注明是演示 |
| 质检、锚点、颜色取样 | 始终真实运行（MediaPipe） |
接入真实模型：在 .env 里填 DEEPSEEK_API_KEY（分析）和 DASHSCOPE_API_KEY（阿里云百炼中国站·北京地域，效果图），重启即可。
其他命令：
make test # pytest（无需密钥；人脸相关测试需要 data/test_faces/ 下有正脸照）
make lint # ruff
make passport PHOTOS=data/p01 # 命令行：照片目录（front.jpg、profile45.jpg，可选 smile、hair）→ runs/<id>/passport.json
make sample # 重建示例护照（examples/ 与 web/lib/fixtures/）
make types # 从 schema 生成 web/lib/passport.ts
python scripts/summarize_runs.py runs/ap_* # 首次通过率、p50/p90、成本、安全词检查、稳定性
python scripts/ab_thinking.py --sets data/p01 data/p02 data/p03 # DeepSeek 思考模式开 / 关对比（D16）
python scripts/debug_landmarks.py <照片> # 关键点叠图，核对编号
配置
| 变量 | 默认 | 作用 |
|---|
DEEPSEEK_API_KEY / DASHSCOPE_API_KEY | — | 分析模型 / 图像编辑模型 |
DASHSCOPE_BASE_URL | 空 | 可选；覆盖 config/models.yaml 里的百炼地址，如北京业务空间专属地址 https://<WorkspaceId>.cn-beijing.maas.aliyuncs.com/api/v1；为空则用配置里的地址 |
ANALYSIS_PROVIDER / IMAGE_EDIT_PROVIDER | auto | auto：有密钥用真模型，否则用示例；也可设 fake、none（关闭效果图） |
QC_MODE | real | stub 只用于没有模型文件的开发 / CI |
INVITE_CODES | 空 | 逗号分隔；为空时不需要邀请码 |
DAILY_PASSPORT_LIMIT · IP_PASSPORTS_PER_HOUR | 30 · 5 | 控制 API 花费 |
MEDIA_TTL_HOURS · PREVIEW_CAP · MAX_UPLOAD_MB | 24 · 3 · 15 | 照片保留时长、每份护照效果图上限、单张上限 |
WEB_ORIGINS | http://localhost:3000 | CORS |
NEXT_PUBLIC_API_BASE（web） | http://localhost:8000 | 前端调用的 API 地址 |
阈值与规则全部在 config/*.yaml，不在代码里。
隐私
- 侧脸、微笑、发型照在分析结束时立即删除。
- 正脸照只用于生成效果图：它、缩略图和效果图在 24 小时后由清理任务删除（启动时与每小时运行）。质检不通过或生成失败时，所有照片立即删除。
- 保存下来的只有护照 JSON（不含照片）。日志与
runs/<id>/calls.jsonl 只记录指标，不记录照片或模型原文。
- 客户端 IP 只以加盐哈希形式用于限流。
- 照片、
runs/、data/、模型文件永不入库（.gitignore）。
部署
- API：
Dockerfile（构建时下载 MediaPipe 模型）+ render.yaml（Render，挂载持久磁盘到 /data 存 SQLite 与 24 小时媒体）。在 Render 上设置两把密钥、WEB_ORIGINS（网页域名）和 INVITE_CODES。
- 上线保护：生产环境设
APP_ENV=production。此时假分析 / 假图像编辑 / 假支付 / 质检 stub 全部拒绝启动，缺密钥会直接报错而不是悄悄改用样例；
假支付关闭后解锁页只显示"支付暂未开放"和邀请码。若要公开演示，额外设 ALLOW_MOCK_PROVIDERS=1，每份档案顶部会显示"演示模式"横幅。
照片过期（24 小时）后，所有读照片、几何与试看的接口一律按已删除处理，不依赖清理任务是否已运行。
- 网页：Vercel，Root Directory 设为
web/，环境变量 NEXT_PUBLIC_API_BASE 指向 API。
- CI：
.github/workflows/ci.yml（ruff、pytest、示例与类型是否最新、TypeScript、next build）。
项目结构
schema/ analysis.schema.json（模型输出契约）· passport.schema.json（产品对象，v0.2）
prompts/ production_analyzer.md（analyzer-0.2）· image_edit.md（preview-0.2）· evaluator_rubric.md（离线，未启用）
config/ rules.yaml · qc.yaml · models.yaml · hairstyles.json（改编自 MIT 项目）
src/aesthetic_passport/
qc · anchors · face_shape · color_sample · cv ← 测量
analyzer · providers/（deepseek · fake · image/qwen · image/fake） ← 模型
rules · assemble · schema_io ← 规则与校验
pipeline · masks · preview · api/（FastAPI、SQLite、保留、限流）
web/ Next.js（App Router）· Tailwind · Radix；一个 <Report> 组件同时服务 /passport/[id] 与 /sample
tests/ 130 个测试（无需密钥、无需网络）
docs/ MVP_BRIEF · DECISIONS · SCHEMA · ITERATION_LOG · screenshots/
状态
已完成 MVP 简报的 S0–S6（见 docs/MVP_BRIEF.md 与 docs/ITERATION_LOG.md）。
| 已验证 | 待真实数据 / 密钥 |
|---|
| 全流程（上传 → 实时质检 → 进度 → 报告 → 效果图）在 375 px 与桌面端可用 | 真实分析的首次通过率、p50 延迟、单份成本（需 DEEPSEEK_API_KEY 与 data/ 照片集） |
| 质检对 7 类合成坏图按正确原因拒绝；关键点、颜色取样、蒙版均经叠图核对 | 思考模式开 / 关对比（scripts/ab_thinking.py） |
| 受保护脸部区域逐像素不变；图像接口失败时报告照常显示并降级为文字 | 真实效果图的「像本人」人工检查（需 DASHSCOPE_API_KEY） |
MVP 之后（按顺序）：评测脚本与 /eval 页面（docs/EVAL.md）· 离线评审模型 · 自动像本人检查 · 分享卡 · 第二个图像模型对比 · 英文界面。
致谢与许可
改编与参考的第三方代码、数据和模型见 THIRD_PARTY.md。
