# ICL-Bench

**评估 Agent 能否把 ICL 术后的眼睛构建成可验证的光学环境，并解释、预测、反推视觉现象。**

ICL 在这里指用于屈光矫正的有晶状体眼人工晶体，不是机器学习的 in-context learning。题目要求保留天然晶状体，在虹膜后、天然晶状体前加入人工晶体；考核眼球解剖、几何光学、波动光学、数值计算及证据边界的联合推理。

版本：`0.1.0-draft`，2026-10-26。当前交付是**专业评测规范 + 36 张任务卡 + 可运行的 24 例合成数值核心**。尚未建立经过专家审核的全眼光学真值、真实临床数据集或正式排行榜。数值核心只检验一个明确限定的等效薄相位模型，不能单独证明模型可以模拟真实 ICL 手术。

新增 `0.2.0-halo-draft` 光圈专项：[14 个成对可运行病例 / 28 个条件 + 6 个专业研究病例](spec/halo-cases.md)，直接评估光圈中心、相对灯芯偏移、半径/宽度、二维形态、方位亮度与裁切弧段。解析校准环、合成光晕和待建立真实 ICL 真值的病例明确分级。

新增 `0.3.0-synthetic-thick-eye`：[合成厚眼与夜间光圈模型](spec/thick-eye-model.md)。已实现角膜、瞳孔、有限厚 ICL/透明孔/内外侧壁、天然晶状体和视网膜的逐面折射，可渲染六种夜间对照，并按光路分解大环来源。生成的交互实验位于 `examples/eye-model/index.html`。

新增 `0.4.0-patient-draft`：[患者感知层](spec/patient-layer.md)。包含[原创采集问卷](patient-study/questionnaire.md)、[离线形态/位置交互标注](patient-study/index.html)及[重复报告评分协议](patient-study/protocol.md)。可记录多光源、多层圆环/椭圆/弧段/自由轮廓并导出JSON；主观一致性分与物理机制分分开。当前仅有虚构软件夹具，问卷尚未验证，无真实患者数据。

阅读入口：[研究总览：从光学模型到患者看到的光圈](articles/overview.md)。网页发布版将总览与15份原始规范、任务说明和阶段验证记录整合为研究文章索引，并保留各文档的版本与证据边界。

## 为什么有区分度

- **先建眼，再算光，再显示。** 提交可运行的眼球结构、线性 PSF（点光源在视网膜上形成的光强分布）、原始能量账本和场景渲染，不能只交好看的图片。
- **同一模型接受隐藏干预。** 更换瞳孔、光源波长、屈光度、光学区、偏心和中央孔后重新运行，不允许逐题手画光圈。
- **现象与机制拆开。** 衍射、像差、离焦、反射鬼像、散射及光学区边缘不能混为一个 bloom 特效；中央孔是液体通道，不能直接当作黑色遮挡。
- **有无法唯一回答的题。** 相似光晕可能来自不同结构。必须给出参数可辨识性、反例和最有价值的追加测量。
- **有否决项。** 解剖位置错误、能量凭空增加、用显示色调映射掩盖数值错误、把合成参数冒充厂家设计或患者测量，不能取得完整评测的合格认证。

## 文件入口

| 文件 | 内容 |
|---|---|
| [spec/benchmark.md](spec/benchmark.md) | 目标、分层任务、完整评测协议、计分和发布门槛 |
| [spec/optics.md](spec/optics.md) | 坐标、物理模型、几何/波动混合传播及数值验证 |
| [spec/evidence.md](spec/evidence.md) | 文献核验状态、参数来源、临床数据与专家审查方案 |
| [tasks/catalog.json](tasks/catalog.json) | 36 张任务卡、交付件、可观察验收标准及难度 |
| [tasks/agent_prompt.md](tasks/agent_prompt.md) | 可直接交给被测 Agent 的完整建设任务 |
| [spec/core-protocol.md](spec/core-protocol.md) | 已实现的合成数值轨道及提交契约 |
| [spec/validation.md](spec/validation.md) | 21 项检查、负控成绩、数值修复及验证边界 |
| [spec/halo-cases.md](spec/halo-cases.md) | 光圈形态与位置的 20 个病例设计、精确对照、输出与评分 |
| [spec/halo-validation.md](spec/halo-validation.md) | 光圈专项 37 项检查、错误模型对照与两个方向的加密结果 |
| [tasks/halo_cases.json](tasks/halo_cases.json) | 光圈病例机器可读参数、任务和真值等级 |
| [tasks/halo_prediction_example.json](tasks/halo_prediction_example.json) | 环中心、相对偏移、半径/宽度等结构化预测格式 |
| [spec/thick-eye-model.md](spec/thick-eye-model.md) | 可运行厚眼模型、六种夜景对照、三层射线数检查与53项测试 |
| [iclbench/thick_eye.py](iclbench/thick_eye.py) | 带透明孔/内外侧壁的有限体积ICL及 Snell/Fresnel 传播 |
| [iclbench/eye_render.py](iclbench/eye_render.py) | 从实际光线能量生成夜景、光路图和交互页面 |
| [patient-study/index.html](patient-study/index.html) | 四步患者记录台：条件、问卷、形态位置、复核导出 |
| [patient-study/protocol.md](patient-study/protocol.md) | P01–P07条件、二次成像、盲评、重复/患者宏平均及评分 |
| [iclbench/patient.py](iclbench/patient.py) | 患者报告一致性评分、排除审计和患者簇bootstrap |
| [iclbench/optics.py](iclbench/optics.py) | 有限视场、多波长、透明中央孔的等效薄相位参考模型 |
| [iclbench/evaluate.py](iclbench/evaluate.py) | 从提交的原始 PSF 自动计算数值指标 |
| [tests/test_core.py](tests/test_core.py) | 解析极限、物理不变量、反作弊和数值检查 |

## 运行合成核心

Python 3.10+，唯一必需的第三方依赖是 NumPy。

```sh
cd ICL-Bench
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/python -m unittest discover -s tests -v

# 在评测方目录生成题面和参考答案；给 Agent 的仅为 release/public/
.venv/bin/python -m iclbench generate --output release --seed 20261026

# 用参考实现产生格式样例，仅用于工具自检，不是模型成绩
.venv/bin/python -m iclbench baseline --cases release/public/cases.json --output runs/reference
.venv/bin/python -m iclbench evaluate --release release --submission runs/reference --output runs/reference/score.json

# 展示有限视场的 PSF 和统一显示条件下的夜间点光源场景
.venv/bin/python -m iclbench demo --output examples/demo

# 重现完整开发管道及固定图/手画圈/忽略孔负控
.venv/bin/python -m scripts.check_pipeline

# 生成光圈专项病例及逐例对照图库
.venv/bin/python -m iclbench halo-generate --output halo-release
# 重现光圈专项的负控与加密检查
.venv/bin/python -m scripts.check_halo_pipeline
.venv/bin/python -m scripts.check_halo_convergence

# 构建厚眼光路、夜间多光源场景及可交互机制对照
.venv/bin/pip install -e '.[render]'
.venv/bin/python -m iclbench eye-render --output examples/eye-model
.venv/bin/python -m scripts.check_thick_eye

# 生成48份虚构重复报告、16个条件及四种评分负控
.venv/bin/python -m iclbench patient-demo --output runs/patient-demo
.venv/bin/python -m iclbench patient-evaluate \
  --reference runs/patient-demo/private/records.json \
  --predictions runs/patient-demo/latent-format-check.json \
  --output runs/patient-demo/rechecked-score.json
```

`examples/demo/index.html` 可直接打开。正式测评必须让被测 Agent 自己构建模型，并在独立进程/容器里对隐藏配置运行。随项目公开的生成器与参考实现不构成保密测试集。

光圈专项生成后打开 `halo-release/gallery/index.html`。该图库包含参考答案，不能分发给只应接收 public/ 的参评者。专项开发分与临床分分开，详见协议。

## 两个成绩，不能混用

1. **Core numerical score / 100**：已实现，24 例，衡量等效薄相位合成题上的 PSF、能量和响应。附 6 个机制分项与失败列表。
2. **Professional ICL-Bench score / 100**：规范已定义，须完成 36 张任务、提交可运行全眼模型，并通过独立光学参考、眼科及光学专家复核。目前应记为 `not_evaluated`，不能从核心分数换算。

临床术后视觉还受泪膜、角膜像差、散射、光源、视网膜响应及神经适应影响。这里的渲染是给定假设下的光学预测，不是个人术后视觉承诺。

患者层另外报告 **Patient agreement development score /100**，不换算为以上专业总分。研究记录须保留重复、测量条件和排除原因；匹配主观描述不能单独证明光学因果。直接打开`patient-study/index.html`即可使用离线记录台。