optlens

optlens

一个与求解器无关的 LP 和 MILP 模型调试与解释工具。将一个不可行的模型，或求解结果令你不放心的模型交给它。optlens 会找出相互冲突的约束、修复这些约束所需的最小改动，以及每项改动的代价。所有结果都是 Agent 或用户可以阅读的文本。你可以在自己的 Python 代码中使用它，也可以通过插件从 Claude Code 使用，或通过任意 MCP 客户端使用。

optlens 适用于已经构建好的模型，不会编写模型。

网站：optlens.dev

安装

Python 3.12 或更高版本：

pip install "optlens[scip,mcp]"   # core: numpy, scipy, HiGHS

要运行下面的快速入门示例或测试，请克隆代码仓库，并从克隆目录安装 （git clone https://github.com/jjd-lab/optlens && cd optlens && pip install ".[scip,mcp]"）。

某些网络无法访问 GitHub，例如使用代理或 VPN 的网络。在这种情况下，请通过其他方式复制源代码，例如下载代码仓库的 zip 文件。使用 pip install "<folder>[scip,mcp]" 安装，并使用 claude plugin marketplace add <folder> 添加 Claude Code 插件。

extra	添加内容
scip	SCIP (pyscipopt)：第二个开源求解器，支持原生 MIP IIS
gurobi	gurobipy：Gurobi，需自备许可证。其版本必须与 Gurobi 版本匹配。Compute Server 或令牌服务器会拒绝较新的客户端（“No compatible runtime available”），因此请安装对应的主版本，例如 pip install "gurobipy==12.*"。open_model 会显示已安装的 gurobipy 版本。
pyomo、pulp	加载 Pyomo 和 PuLP 模型
mcp	MCP 服务 optlens-mcp 和 Claude Code 插件

快速入门

import optlens as od
from optlens.session import Session, Version

if __name__ == "__main__":  # solves run in worker processes, which start by re-importing this script
    md = od.load("tests/fixtures/ex_milp_tutorial__rhs_tighten__0.mps")  # LP or MPS
    s = Session({"v0": Version(md, None, "original model")})
    print(s.get_model_overview())   # size, status (here INFEASIBLE), constraint families
    print(s.compute_iis())          # the conflicting constraints, grouped by family
    print(s.fix_menu())             # the smallest change per family that restores feasibility
    print(s.modify_and_resolve(changes=[{"action": "set_rhs", "name": "resource[Monika]", "upper": 1}]))

将其保存为文件，并从代码仓库根目录运行。任何执行求解的脚本都要保留 if __name__ == "__main__": 保护语句。求解会在工作进程中运行。Windows 会通过 spawn 启动这些进程，每个进程都会重新导入脚本。没有这条保护语句，脚本就会在每个求解器进程中再次运行。

每个 Session 方法都会返回文本，而 optlens.session.TOOLS 则包含与之对应的 JSON 架构，供 Agent 使用。会话还支持可行性松弛、以版本形式进行假设性修改、原因追问、灵敏度和边际值、可疑数据值，以及版本或模型之间的比较。

在 Pyomo、gurobipy 或 PuLP 中构建的模型，可以直接从模型对象加载，也可以从构建模型的文件加载。optlens 会运行该文件，但不执行其中的 if __name__ == "__main__": 代码块，并在遇到第一个求解调用（optimize()、solve()）时停止。它会读取该调用对应的模型。整个过程不会执行求解，因此大型 gurobipy 模型也可以在 Gurobi 有大小限制的许可证下加载。

md = od.from_object(model)                      # a Pyomo ConcreteModel, gurobipy Model or PuLP LpProblem
md = od.load("my_model.py")                     # the model it solves, else its one model or build_model()
md = od.load("my_model.py:make_scenario")       # a named model, or a function with no arguments that returns one

由 Gurobi 写入的 LP 文件（其中包含 HiGHS 无法处理的带方括号名称）无需 gurobipy 即可加载。

optlens 支持二次目标函数（QP、MIQP）。凸 QP 使用 HiGHS 求解。optlens 会自动将混合整数或非凸模型交给 SCIP。除灵敏度范围外，线性模型可以回答的问题都适用。如果目标函数非凸，影子价格也不可用。模型加载时，optlens 会拒绝二次约束、指示约束及其他通用约束，以及 SOS。optlens.dev/ask 列出了所有问题、格式和求解器。

求解器

HiGHS 随核心一起提供，SCIP 和 Gurobi 是额外选项。可通过 OPTLENS_SOLVER（highs、scip、gurobi 或默认的 auto）、MCP 服务中 open_model 的 solver，或 Session(..., prefer=...) 选择求解器。在未使用 Gurobi 的 auto 模式下，每个模型都会交给 HiGHS 或 SCIP 求解。对于较大的 MIP，首次求解会让两者同时竞速。

• 每次求解都有严格的时间限制。 求解器并不总会遵守自身的时间限制。SCIP 曾在 30 秒的限制下运行了 862 秒。因此，每次求解都会在工作进程中运行，optlens 会在达到限制时停止该进程。
• Gurobi 会独立完成每个步骤。 Gurobi 会话会在 Gurobi 上求解、计算 IIS、进行松弛、分析范围并检查结果，不会把任何步骤交给其他求解器。如果你选择了 Gurobi，而它无法运行某个模型（因为未安装 Gurobi，或模型超出许可证的规模限制），那么工具会停止并说明原因，而不是切换求解器。在 auto 模式下，如果 Gurobi 能在当前环境中运行，optlens 就会使用它。它会通过一个单变量求解进行一次检查。如果已安装 gurobipy，但没有可用许可证，或许可证服务器拒绝了当前版本，它就会排除该选项，而 open_model 会说明原因。如果 Gurobi 无法运行某个模型，它会退回到 HiGHS 或 SCIP，并说明这一点。
• HiGHS 和 SCIP 会互相替代。 当只有其中一个能完成某个步骤时，就会发生这种情况：HiGHS 不支持 MIP IIS，而 SCIP 支持。如果某个求解器未能在时限内给出结果，也会发生这种情况，此时另一个求解器会再尝试一次。结果会注明执行该步骤的求解器。
• 每个 IIS 都会经过检查。 有时，求解器返回的 IIS 中包含单独来看可行的约束。optlens 会拒绝该 IIS，并在同一求解器上逐个移除约束，重新构建 IIS。这可以防止一个已知的 gurobipy 13.0.3 错误。对于一个二进制变量，如果其分数上限经舍入后变为 0，computeIIS 会漏掉该变量上的单变量行。例如，160 open <= 100 且 open >= 1 时，它只会返回 open >= 1，而这本身是可行的。
• Gurobi 已在小型模型和一个大型模型上经过测试。 这个大型模型是一个包含 279k 行的酒店模型，已针对求解、灵敏度分析、IIS、松弛和修复菜单进行测试。其他大型模型尚未经过测试，欢迎提交相关报告。

对于包含数十万个约束的大型模型，IIS 搜索会从冲突附近开始。它会从 HiGHS 的不可行性证明出发，而不是搜索整个模型。

与你的 Agent 配合使用

按上述方式安装后，optlens-mcp 就会加入你的 PATH。然后连接一次即可。Agent 会获得这 24 个工具及其配套方法：先打开模型，从原因入手，从求解结果中获取所有数值，并在推荐修复方案前重新求解。

Agent	连接方式
Claude Code	先运行 claude plugin marketplace add jjd-lab/optlens，再运行 claude plugin install optlens@optlens（也可以在会话中使用对应的 /plugin 命令）
Codex CLI	codex mcp add optlens -- optlens-mcp
Cursor	在 .cursor/mcp.json（或 ~/.cursor/mcp.json）中配置：{"mcpServers": {"optlens": {"command": "optlens-mcp"}}}
VS Code (Copilot)	在 .vscode/mcp.json 中配置：{"servers": {"optlens": {"type": "stdio", "command": "optlens-mcp"}}}
Claude Desktop	在 claude_desktop_config.json 中配置（Settings > Developer > Edit Config）：{"mcpServers": {"optlens": {"command": "optlens-mcp"}}}
其他任意 MCP 客户端	将 optlens-mcp 作为 stdio 服务运行

该命令必须位于 Agent 可见的 PATH 中。如果不在，请提供 optlens-mcp 的完整路径，例如 .venv/bin/optlens-mcp。OPTLENS_SOLVER（highs、scip、gurobi 或 auto）用于选择求解器。

时间限制。 求解会在 45 秒后停止，因此一次调用会在一分钟内返回结果。OPTLENS_CALL_LIMIT（单位为秒，至少为 30）是单次工具调用允许的最长时间。工具的 time_limit 最多可比此值少 15 秒。只有在求解达到时间限制时仍在改进，Agent 才会请求更多时间；结果会说明是否如此。请将此限制设为客户端等待单次工具调用的时长。open_model 会说明当前生效的限制；如果结果因达到限制而提前结束，也会明确说明。

客户端	等待工具调用的时间	OPTLENS_CALL_LIMIT
Claude Code（插件）	10 分钟，由插件设置（调用超过 2 分钟后会转入后台）	110，由插件设置
Claude Code（claude mcp add）	MCP_TOOL_TIMEOUT（除非设置，否则约为 28 小时；某些环境会设为 60 秒）	除非另行设置，否则为 60；如需更长时间，请在服务条目中添加 "timeout": 600000，并将其设为 110
Claude Desktop、MCP TypeScript SDK 客户端	60 秒	60（默认值）
其他客户端	请参阅客户端设置	除非客户端允许更长时间，否则为 60

大型 MIP 可能无法在上述任何限制内完成。此时，结果会报告找到的方案、其界限和差距。

然后提问："为什么 plan.mps 不可行，怎样修复？" Agent 会打开模型，并写入一次上下文。上下文会说明每个约束和变量族的含义。上下文以 JSON 格式存放在 .optlens/context/ 中，你可以查看并提交。随后 Agent 会逐步使用这些工具。对于多个步骤或多次求解，它会使用 run_python。这是一个持久化的 Python 进程，已将引擎预加载为 session，且只加载一次模型。

Claude Code 插件使用的是同一个服务，外加一段简短的技能说明，指向该服务的方法（plugin/README.md）。

安全性。 optlens 会以你的权限在你的机器上运行代码，且没有沙箱。run_python 会执行 Agent 编写的代码。其进程启动时不会携带你的 API 密钥和令牌，但可以读写你用户权限范围内的所有内容。在 Claude Code 中，你需要批准每次调用。打开 .py 模型时，该文件会运行至首次求解调用。只打开你信任的模型和代码。如需报告漏洞，请参阅 SECURITY.md。

试用

如果想试用此插件，同时不影响你自己的 Claude Code 配置，可以在单独的文件夹中创建一个干净的环境。该文件夹会有自己的虚拟环境，其中包含从 GitHub 安装的 optlens，以及只启用 optlens 插件的独立 Claude 配置。文件夹中还会包含一周酒店数据，其数据加载出了问题 (packs/hotel/examples/try_week)， 并附有 5 个可提问的问题：

git clone https://github.com/jjd-lab/optlens && optlens/scripts/sandbox.sh ~/optlens-try
~/optlens-try/start.sh          # log in on the first start; the questions are in ~/optlens-try/HOW-TO.md

需要 bash、Python 3.12+ 和 Claude Code，支持 macOS 或 Linux。在 Windows 上，请使用 WSL，或按照 plugin/README.md 中的 PowerShell 步骤操作。--project PATH 会将你自己的模型放在该路径下。这是一个独立配置，不是安全沙箱（请参阅上文的安全性）。删除文件夹即可将其移除。

以下是在启用了插件的干净 Claude Code 环境中运行同一周数据的演示。动画来自录制的会话，每次工具调用都显示了实际耗时：

酒店包

packs/hotel/ 是一个合成酒店收益管理模型：房型 × 夜晚 × 入住时长 × 预订窗口 × 价格等级。它包含生成器、文档、领域说明和辅助工具。它可以构建包含数千到 837,000 个约束的模型，让你在真实且规模较大的场景中试用 optlens。

测试

python -m unittest discover -s tests -t .                             # the engine, from the repo root
cd packs/hotel && python -m unittest discover -s tests -t .           # the hotel pack

联系方式

如有疑问、想反馈你自己的模型，或申请访问 optchat，请发送邮件至 [email protected]。 optchat 是基于 optlens、面向业务用户构建的聊天 Agent。如需报告 Bug 或提出功能请求，请提交 GitHub Issue。

以下是规划人员使用 optchat 处理酒店包模型的会话，该模型规划 14 个夜晚。数据加载时，有一晚的团队目标被输入为 1,200，而不是 120。每个回答末尾都会列出引擎调用、耗时和费用。录制中，超过 2 秒的等待都缩短为 2 秒：

参与贡献

使用你自己的模型报告问题，是最有价值的贡献。请参阅 CONTRIBUTING.md 和 行为准则。

许可证

Apache-2.0（LICENSE）。第三方鸣谢见 NOTICE。