OptiVibe

optivibe-mcp

optivibe-mcp 是一款实验性 MCP 服务，为编码 Agent（例如 Claude Code）提供工具，以便与 Zemax OpticStudio 交互。

一次无人值守的运行：将一款 60× 物镜改造为 10× / NA 0.45 消色差复消色差物镜，每个视场点的多色 Strehl 比均 ≥ 0.935。了解实现和测量方法。

它通过 ZOS-API 将 OpticStudio 操作封装为类型化 MCP 工具：加载设计、编辑镜头数据、运行分析、优化和公差分析，无需 Agent 编写原始 API 代码。除工具外，还提供可供 Agent 查询的参考层，包括操作数和玻璃查询，以及对 OpticStudio 手册的全文搜索。

可通过 pip install optivibe-mcp 安装（发布于 PyPI）；该服务也已列入官方 MCP Registry，名称为 io.github.chuang44-tiff/optivibe-mcp。请参阅安装。

包含内容

• 工具（optivibe-mcp，位于 packages/optivibe-harness/）——80 多种类型化工具，通过 ZOS-API 驱动 OpticStudio。每种工具都会返回统一的结果封装，而不是抛出异常，因此 Agent 会检查回读值，而不是假定调用成功。除球面外，它还能创建非球面、坐标断点、折叠反射镜、衍射光栅和梯度折射率介质。对于已定型的镜头，它还可以指出哪些元件影响色差和场曲项，并针对对照组试验更换玻璃（请参阅玻璃工具）。
• 参考层（optivibe-reference）——提供操作数和玻璃查询以及手册搜索，帮助 Agent 做出有依据的选择。无需引擎或许可证；其数据在本地构建（请参阅构建参考数据）。

本项目仅提供代码。其中不包含任何供应商数据（玻璃目录、手册文本、操作数说明）——这些数据需通过你自己的 OpticStudio 授权安装生成。

演示

每个演示都附带任务简述、Agent 的阶段日志、起始镜头和结果镜头，以及用于重新测量它们的脚本：参见 demos/。

Agent 无人值守地将 60× 物镜改造成 10× / NA 0.45 消色差复消色差镜头 一次运行中没有人工介入，最终得到一枚 10× / NA 0.45 物镜，在所有四个视场点的多色 Strehl 比均达到或超过 0.935；之后由独立脚本进行了测量。

本地模型借助 OptiVibe 的技能和 MCP 服务完成相同任务 在本地服务上运行的 Qwen3.8-Flash-Next，收到针对该任务调整的任务简述后，在所有四个视场点的多色 Strehl 比均达到或超过 0.834。页面说明了它在哪些方面不如 Opus。

Agent 改进 20× 变焦镜头，但晋级门槛阻止了它 一次运行将变焦镜头最差位置的模糊程度降低了一半以上，但未达到畸变目标；服务还拒绝让结果通过，因为存在两片较薄的滤光片。重新读取保存的文件后，复现了摘要中的数据。

Agent 能否在看到图纸时设计出更好的镜头？ 相同的镜头任务，在每个组都完成三枚镜头前均无人为介入：每次采用布局审查的运行所得到的镜头，都比仅依据数字进行设计的运行更短（70–100 mm，相比 140–221 mm）；而且每枚视觉组镜头在所有四个波长下的轴上 Strehl 比均达到或超过 0.93。

Agent 的玻璃选择步骤对比 OpticStudio 的 Hammer：两个显微镜物镜 对于 10× / NA 0.45 消色差复消色差镜头，两次 Agent 运行的评价函数值都低于 Hammer（分别低 13 % 和 8 %），同时将 14 种玻璃中的 3 种替换为 Hammer 选择的 10 种玻璃；每枚镜头在所有视场下都通过了验证。对于 20× / NA 0.70 物镜，Hammer 的镜头评价函数值最低，但轴上不合格；两次 Agent 运行都保留了轴上目标。页面列出了相关限制。

前置条件

• Windows。 OpticStudio 和 ZOS-API .NET 接口仅支持 Windows。
• Zemax OpticStudio，需获得 ZOS-API 授权。开发时使用的是 2025 R1 (25.1.0, Premium)；其他版本未经测试。首次打开引擎时会通过 IsValidLicenseForAPI 检查授权。
• Python 3.11+。
• .NET Framework —— 自动使用。引导程序会设置 PYTHONNET_RUNTIME=netfx，并定位安装目录（通过环境变量覆盖、注册表或扫描 Program Files）。无需手动设置。

安装

从 PyPI 安装

在 Python 3.11+ 虚拟环境中：

pip install optivibe-mcp "optivibe-reference[manual]"
optivibe-build-data --probe
optivibe-doctor

两个软件包均已发布到 PyPI：optivibe-mcp 和 optivibe-reference，并以匹配的版本同步发布。optivibe-mcp 是服务；它会一并安装参考层（optivibe-reference）。[manual] 扩展（PyMuPDF）为可选项，用于读取你的 OpticStudio 手册 PDF（参见 手册安装）。optivibe-build-data 会根据你自己的 OpticStudio 安装构建参考数据；--probe 还会运行两个操作数探测程序，这些程序会打开 OpticStudio，并需要 ZOS-API 许可证。optivibe-doctor 用于检查安装。然后 将服务注册到 Claude Code。

optivibe-build-data 会将数据写入已安装软件包的 data/ 和 data/captures/ 目录，因此请将 optivibe-mcp 安装到虚拟环境中（或使用 pip install --user），不要安装到其 site-packages 目录不可写的系统 Python 中。

从克隆仓库开始

克隆仓库，然后在仓库根目录运行一条命令：

powershell -ExecutionPolicy Bypass -File install.ps1

该命令会在 .venv 中创建虚拟环境、安装两个软件包、从你的 OpticStudio 安装中构建参考 数据、运行 doctor，并打印用于向 Claude Code 注册服务的命令。它不会打开 OpticStudio 会话。选项：

• -Python <path>：用于构建环境的 Python 3.11+，当 PATH 中的 python 版本较旧时使用；
• -Probe：还会运行两个操作数探测程序，这会打开 OpticStudio，并需要 ZOS-API 许可证（请参阅构建参考数据）；
• -Register：代你运行 claude mcp add 命令。

该脚本只会运行以下步骤，你也可以手动执行。

手动安装

在 packages/optivibe-harness/ 中：

pip install -e ../optivibe-reference   # reference layer first
pip install -e .                        # then the harness

请先安装参考软件包——harness 会在进程内加载它；如果没有安装，参考和查找工具将无法使用。

[manual] 扩展（PyMuPDF）会读取你的 OpticStudio 手册 PDF。它不仅用于手册搜索，还用于操作数/公差描述增强（构建过程会从 PDF 中提取原文描述）。如果没有它，操作数和公差目录将以仅同义词的形式构建（grounding 仍然有效——每个条目都可通过其同义词搜索——但不包含手册描述）。要获得完整的增强版构建，请安装它：

pip install -e "../optivibe-reference[manual]"

如果你更喜欢使用 conda，每个软件包都提供了一个 environment.yml（Python 3.11）。

然后检查安装：

python -m optivibe_doctor

该命令会检查解释器、两个软件包、它们的依赖项、参考数据和你的 OpticStudio 安装目录，并为每项检查打印一行结果；如果有问题，还会给出解决方法。除非你主动要求，否则它不会打开 OpticStudio 会话：--engine 也会打开一个会话并验证 ZOS-API 许可证，--boot 则会启动一次真实服务。在全新安装中，参考数据检查会显示 WARN，直到你构建参考数据；只要有任何检查显示警告，退出代码就是 1。

向 Claude Code 注册

claude mcp add optivibe -- /path/to/python -m optivibe_harness

/path/to/python 是你安装软件包的环境所使用的解释器——指向其他 Python 是导致无提示失败的常见原因。你可以通过以下命令找到它：

python -c "import sys; print(sys.executable)"

对应的 JSON 配置：

{ "command": "/path/to/python", "args": ["-m", "optivibe_harness"] }

通过 PyPI 安装后，你也可以改为注册 optivibe-mcp 命令。请提供它的完整路径（环境处于激活状态时，where optivibe-mcp 会打印该路径）：

claude mcp add optivibe -- C:/path/to/venv/Scripts/optivibe-mcp.exe

玻璃工具

优化器稳定镜头后，有两个工具可以协助处理玻璃步骤。explain_glass_swaps 为只读工具：它会列出哪些玻璃元件承载色差项和 Petzval 项。trial_glass_swaps 最多会尝试四组替换，每组替换都会与未改动的对照组并行重新优化，并依据实测图像质量进行评估；运行时会编辑打开的镜头，并在结束时还原。substitute_glass 会执行一次替换并保留结果。design-glass-matching 技能会运行此步骤。

若要让 Claude Code 在运行任何一个会编辑镜头的工具之前先征求你的同意，请在设置中添加一条 ask 规则（例如 .claude/settings.json）：

{
  "permissions": {
    "ask": ["mcp__optivibe__trial_glass_swaps", "mcp__optivibe__substitute_glass"]
  }
}

ask 规则优先于 allow 规则；即使处于 bypassPermissions 模式，也仍会征求同意。在无头运行（claude -p）或 dontAsk 模式下，没有人可以征求同意，因此匹配的调用会被拒绝。

构建参考数据

参考层的数据由你本地已授权的安装生成；不会提交任何源自供应商的数据。通过 PyPI 安装后，运行 optivibe-build-data（可添加 --probe，先运行下面的两个探测）；无需克隆仓库。从克隆的仓库运行时，请在仓库根目录执行：

python packages/optivibe-reference/scripts/build_vendor_data.py

此命令会从你的 .agf 文件（ZEMAX_GLASSCAT）中读取玻璃目录；如果你指定了手册 PDF（OPTIVIBE_MANUAL_PDF），还会为其建立搜索索引。

操作数和公差目录由对你安装环境中 ZOS-API 枚举接口的实时探测生成。请先运行下面的两个探测一次（每个探测都会启动一个无头 OpticStudio 会话，读取操作数／公差接口，然后关闭会话）：

python packages/optivibe-reference/scripts/probe_operands.py
python packages/optivibe-reference/scripts/probe_tolerances.py

如果缺少某项输入，相应步骤将跳过：对应工具（玻璃或手册搜索，或操作数／公差查询）会返回带类型的“不可用”结果，服务器的其他部分仍可正常工作。详情和数据来源记录见 PROVENANCE.md。

运行

启动时不会打开 OpticStudio——首次调用涉及设计的工具时才会启动引擎，且一次只处理一个设计。参考和查询工具无需引擎运行——因此，无论许可证等级如何，安装、注册、构建参考数据以及所有查询都能成功；只有引擎启动时才会检查 ZOS-API 许可证。

关于可信度的说明：工具会返回结果封装，不会在失败时抛出异常，因此调用完成并不能证明它执行了你的预期。请检查返回值或优化器的判定结果，而不要仅凭没有报错就判断成功。

技能

仓库包含若干适用于常见任务的 Claude Code 技能：

技能	用途
design-review	根据规格评估设计
design-compare	并排比较设计
design-vision-review	观察渲染后的布局，并报告镜头数据未能体现的内容（仅供参考）
design-aberration-review	读取光线扇形图和场曲／畸变图，并报告像差的平衡情况（仅供参考）
optimize-loop	监控优化过程
design-glass-matching	为已定型的镜头选择玻璃：找出影响色彩或场曲项的元件，针对基准测试替换方案，并且仅在整体图像质量提升时保留替换
bench-catalog	根据目标规格或相互对比，对一组镜头设计进行基准测试和排序
zos-api-debug	排查 OpticStudio 连接／许可证错误

状态

本项目处于实验性早期阶段，按现状提供；请预期存在一些不足。目前仅针对 Windows 上的单一 OpticStudio 版本（2025 R1）开发和测试；其他版本上的行为尚未验证。接口和工具覆盖范围可能会变化。

运行的是其他 OpticStudio 版本或许可证等级？ 请通过 提交问题，并附上 python -m optivibe_doctor --engine 的输出，无论是否正常运行都欢迎反馈。报告它在你的版本上正常运行，与报告缺陷同样有帮助。

贡献与联系

欢迎通过 GitHub Issues 和 pull request 提交错误报告、问题和代码；详情请参阅 CONTRIBUTING.md。 请勿在问题或 PR 中包含任何源自供应商的数据（玻璃目录、手册文本、操作数说明）——请参阅 PROVENANCE.md。

许可与来源

optivibe-mcp 采用 Apache License 2.0 许可——请参阅 LICENSE 和 NOTICE。

本项目仅包含代码，运行时会驱动你自己已授权的 OpticStudio 安装；不会再分发供应商数据或 SDK 文件。你在本地构建的参考数据会保留在本地（已加入 gitignore）。optivibe-mcp 是独立项目，与 Ansys/Zemax 无关联，也未获其认可。数据来源和许可证记录请参阅 PROVENANCE.md。