Version: 1.2.1
把原图和若干张 AI 修复候选图放在一起，用一套可解释的轻量指标算出两张榜： 保守修复榜（谁最接近「修旧如旧」）与展示复原榜（谁最适合上墙展陈）。
本工具是 大云壁画工具箱的一员：相柳网格 · 精卫 · 白泽评审 · 重明 DiffEye · 工具箱启动台。 （系列仓库并排克隆时，这些名字是相对链接：相柳网格 · 精卫 · 重明 DiffEye · 工具箱启动台。）
AI 修复壁画，一次能给你五张候选。五张各有各的好：一张线条最忠实但偏灰，一张颜色最漂亮 但凭空多了几笔花纹，一张最干净但把残色也一起抹了。靠肉眼比对很难排出稳定顺序， 换个人、换一天，结论又变了。
白泽评审做的事只有一件：把「像不像原来的」和「好不好看」拆成两组可解释的指标， 分别算分、分别排名，再把每个分数的来源逐条念给你听。
- 同一批候选，每次评分得到同一套结果，可以留档、可以复核；
- 每一项分数都能追溯到具体指标（原线条位置召回率、损伤区无锚定新增线条比例……）， 不是黑箱打一个总分；
- 两张榜分开，是因为**「保守修复」和「展示复原」本来就不是一回事**， 用一张总分把它们混起来，等于让两个立场互相稀释。
这个工具是在大云禅院壁画修复与重现工作中长出来的。整面墙的扫描图切开、逐块交给不同的 AI 修复，回来一堆候选，谁上墙、谁存档、谁重做——最初靠人围在屏幕前投票， 标准飘、结论散、事后无法复盘。
于是把「像不像原来」这件事尽量量化：先用原图自己的证据（线条、残色、缺失、遮挡） 生成一组 mask，再拿候选图去这些 mask 上对照。评分口径写在明面上，谁有意见， 冲着某一条指标谈，而不是冲着某个人的眼力谈。
「白泽」出自《山海经》。它是知万物之情、能辨万物之名、能言人语的神兽； 传说黄帝东巡至海，遇白泽，问天下鬼神之事，白泽言之，凡一万一千五百二十种。
白泽的职责是辨识——知道什么东西是什么、什么好什么差。 这正好是这个工具的全部工作：在一堆看起来都还行的候选里，说出谁更好、好在哪里、差在哪里。
- 自动 mask 生成：只用 Pillow + numpy，从原图算出证据区 / 线条证据 / 残色证据 / 缺失区 / 损伤区 / 泥层遮挡 / 空白灰泥 / 不确定区八层 mask，不依赖任何分割大模型。
- 双榜评分：
保守修复榜与展示复原榜各自独立算分、独立排名。 - 可解释：14 个分项 + 23 个原始量化指标，每一项都带中文说明，能直接说给评审听。
- 风险提示：自动标出「原始线条位置保留不足」「低证据区存在较多无锚定新增线条」等具体风险。
- 人工修正 mask：画笔 / 矩形两种工具，证据 / 损伤 / 不确定三种笔 + 擦除， 自动 mask 不满意的地方可以手改，改完立即重算最终 mask。
- 灵敏度可调：edge / pigment / missing 三个滑杆，同一个项目可以试不同口径。
- 校准留档：每次评分独立归档一份 JSON + Markdown，便于后续做盲选校准。
- 一键到底：不想分步走，就用「自动评审」——对齐尺寸、生成 mask、评分、导出冠军，一趟跑完。
- 全本地运行：图片只在本机磁盘上处理，服务只监听
127.0.0.1，不访问任何网络服务。
需要 Python 3.9 或更高版本：https://www.python.org/downloads/
安装时请勾选 Add python.exe to PATH。
双击：
run.bat
第一次启动会询问是否自动安装依赖（Pillow / numpy），选 Y 即可。
也可以直接在 PowerShell 里运行：
.\run.ps1浏览器会自动打开：
http://127.0.0.1:8766
使用期间请不要关闭那个命令行窗口，关掉工具就停了。
Pillow
numpy
手动安装：
python -m pip install -r requirements.txt本工具不需要 OpenCV。旧版
README里出现的 OpenCV/SSIM/LPIPS 都只是历史讨论， 实际评分链路只用到 Pillow 与 numpy 的数组运算。
- 导入：填项目名称，选原图（拖入 / 点击 / 从历史原图里挑），再选若干张候选图。
- 点 进入手动流程。所有图会等比对齐到长边 2048 并建项目，页面自动跳到 Mask 页。
- Mask：
- 先看自动 mask 预览（绿=证据，橙=损伤/低证据，蓝紫=不确定）；
- 不满意就调
edge / pigment / missing三个灵敏度滑杆，再点 生成 mask； - 还有局部不对，用画笔或矩形直接涂：证据 / 损伤 / 不确定 / 擦除，涂完点 保存修正；
- 想推翻重来，点 回到自动。
- 评分：点 开始评分，得到双榜、候选对比墙、逐项分数、原始指标与风险标签。
- 点 导出项目 zip 把整个项目（原图、候选、mask、报告、归档）打包带走。
在导入页点 自动评审（一键到底）：对齐尺寸 → 生成 mask → 评分 → 导出两张榜的冠军， 一趟跑完，直接落到评分页看结果。适合先快速看一眼这批候选的整体成色。
| 参数 | 默认 | 说明 |
|---|---|---|
| 线条边缘 edge | 1.0 | 调高 = 保留更多微弱线条证据；调低 = 只认强边缘。范围 0.2–2.0。 |
| 残色 pigment | 1.0 | 调高 = 保留更多微弱残色证据。范围 0.2–2.0。 |
| 缺失 missing | 1.0 | 调高 = 把更多苍白低证据区判为缺失。范围 0.2–2.0。 |
| 项目 | 上限 | 超限行为 |
|---|---|---|
| 候选图张数 | 64 张 / 项目 | 400 + 中文提示 |
| 单个上传文件 | 1 GB | 413 + 中文提示 |
| JSON 请求体 | 1 MB（人工修正笔迹单独放宽到 8 MB） | 413 |
| 修正笔迹 | 20000 条 / 400000 点 | 400 + 中文提示 |
| 笔刷尺寸 | 2–4096 px | 自动夹取到区间内 |
每次评分在 runs\<项目ID>\ 下建一个项目目录：
| 文件 | 含义 |
|---|---|
original\original.png |
对齐到长边 2048 的原图（评分的基准） |
candidates\01_名字.png |
对齐后的候选图，序号即导入顺序 |
project.json |
项目元数据：原始尺寸、对齐后尺寸、是否缩放 |
masks\evidence_mask.png |
证据区（原图仍有可参考的线条/纹样/颜料） |
masks\line_evidence_mask.png |
线条证据（可见线条、边缘、轮廓） |
masks\pigment_evidence_mask.png |
残色证据（仍有残色或颜料方向） |
masks\missing_mask.png |
缺失区（信息不足或缺失明显） |
masks\damage_mask.png |
损伤区（缺失 + 遮挡 + 空白灰泥合成） |
masks\mud_or_occlusion_mask.png |
泥层 / 污渍 / 遮挡物 |
masks\blank_plaster_mask.png |
大面积空白灰泥 |
masks\uncertain_mask.png |
不确定区（评分时降信任） |
masks\final_*_mask.png |
人工修正后参与评分的最终三张 mask |
masks\mask_preview.png |
自动 mask 叠加预览 |
masks\final_mask_preview.png |
修正后的最终叠加预览 |
masks\mask_metrics.json |
各层占比、mask 置信度、灵敏度、阈值 |
masks\override_strokes.json |
人工修正笔迹（可复现） |
score_result.json |
本次评分完整结果（分项、指标、双榜、理由） |
score_report.md |
人可读的评分报告 |
calibration_rounds\<时间戳>_<评分版本>.json |
本轮归档（机器可读） |
calibration_rounds\<时间戳>_<评分版本>.md |
本轮归档（报告） |
exports\conservative_winner\ |
保守修复榜冠军图 + winner_summary.json |
exports\display_winner\ |
展示复原榜冠军图 + winner_summary.json |
exports\<项目ID>_archive.zip |
整个项目打包 |
上传的原始文件放在 uploads\<上传ID>\。runs\ 与 uploads\ 下超过 7 天的目录会在
下次启动时自动清理（_ 开头的目录除外，缓存预览就在里面）。
保守修复榜 = 线条忠实度 39% + 结构保持 12% + 残色方向 8% + 损伤区克制 25% + 异常风险 16% − 鲜艳 caution。偏向修旧如旧：允许原线条适度加固，严惩低证据区乱加内容。
展示复原榜 = 完整度 4% + 展示可读性 16% + 色彩表现 10% + 展陈清晰度 38% + 表面统一 12% + 风格统一 4% + 构图 6% + 证据兼容 6% + 推测风险 4%。偏向展陈清晰度。
颜色逻辑：残色方向在 pigment mask 内比较色相方向，不按 RGB 亮暗差扣分。 允许红更红、蓝更蓝；主要扣红变蓝、冷暖跑偏。
这两套权重是
SCORING_VERSION = v2.1-lightweight-calibration的口径， 与旧版白泽逐字一致，本次系列化改造没有动过任何一个数字。
Q：评分要等多久？
取决于图的大小和候选数量。图会先对齐到长边 2048，单张候选在普通笔记本上通常几秒。 候选多的时候请耐心等状态栏走完。
Q：mask 不准怎么办？
先调灵敏度（edge / pigment / missing）重新生成；仍不满意就用画笔手工修正——
涂「证据」和涂「损伤」的效果完全不同，前者代表"这里还有原始信息可参考"，
后者代表"这里是缺损，别在这里凭空加东西"。改完一定要点 保存修正。
Q：为什么候选图都要缩到长边 2048？
因为所有指标都是逐像素对照（原图 vs 候选），两边必须像素级同尺寸才能比。
2048 是在精度和速度之间取的折中，缩放比例会记在 project.json 里。
Q：为什么不用 SSIM / LPIPS / 分割大模型？
这是一条刻意的取舍：壁画修复的评审要能说清理由。LPIPS 给你的是一串距离， 而白泽给你的是"原线条位置召回率 0.31，说明原线条没保住"。前者更准，后者更能开会。
Q：上传了一张几百 MB 的图，报错了。
单个文件上限 1 GB。超限会返回明确的中文提示，请先把图压到合理尺寸再传。
Q：候选图最多几张？
64 张 / 项目。这个上限是防误操作，正常评审一批 3–10 张。
Q：端口 8766 被占用了。
python server.py 8899然后用 http://127.0.0.1:8899 打开。
Q：双击 run.bat 没反应 / 窗口一闪而过。
先看窗口里有没有中文乱码报错。这类问题的根因通常是脚本文件编码
（run.ps1 必须 UTF-8 带 BOM，run.bat 必须纯 ASCII）。
可以直接跑一遍自查：
D:\vibecodingtool\_series\tools\fix-ps1-encoding.ps1 -Path .\run.ps1,.\run.bat -Check见 CHANGELOG.md。
源代码使用 MIT License 发布。
The names 白泽评审 / Baize Review, as well as the project logo and visual identity, are reserved by the project author and are not granted as branding or trademark rights under the MIT License.
白泽评审 / Baize Review 的名称、项目 logo 和视觉识别保留为项目作者的品牌资产， 不随 MIT 协议授予商标或品牌使用权。