mph-agent 文档

Multiphysics Modeling Agent 是一款基于 ReAct 架构的 AI 智能体， 将自然语言描述的 COMSOL 建模需求自动转换为完整的 .mph 模型文件。 主干已接入 claw-code：单步 COMSOL 操作优先由内嵌调度器执行并返回结构化 JSON，必要时由官方 Java API 兜底。

简介#

mph-agent 通过 Reasoning & Acting 循环理解需求、规划步骤、调用 COMSOL Java API、 观察执行结果并迭代改进，最终生成可直接在 COMSOL Multiphysics 中打开的 .mph 文件。 当前推荐通过 源码安装 使用 CLI；仓库包含 Tauri + React 桌面端源码，可自行构建 GUI，不提供预编译安装包。

架构#

三层架构：交互 / 客户端层（Tauri + React，源码构建）/ ReAct Agent 层（Python）/ COMSOL 执行层（claw-code 内嵌调度 + Java API 兜底）。 通过 EventBus 串联推理与执行事件。

架构详图见仓库 docs/architecture/architecture.md。

claw-code 接入#

主干将 claw-code 作为执行骨架之一：agent/executor/clawcode_dispatcher.py 在进程内嵌入 claw-code， 把每个 COMSOL 步骤与上下文打包执行，必须返回单个 JSON 对象（含 status、message、路径与产物等字段），便于上层与 EventBus 稳定处理。 若 claw-code 未完成，JavaAPIController 仍可按官方 API 兜底。

环境要求#

安装#

git clone https://github.com/iammm0/mph-agent.git
cd mph-agent
uv sync
uv run python cli.py

环境配置#

在项目根目录创建 .env；若自行构建了 GUI，也可在应用设置页填写。

必需变量

• LLM_BACKEND：deepseek / kimi / ollama / openai-compatible 等
• COMSOL_JAR_PATH：
  • 6.3+：指向 plugins 目录，如 C:\Program Files\COMSOL\COMSOL63\Multiphysics\plugins

  • 6.1 及更早：指向单个 jar，如 安装目录/lib/win64/comsol.jar

可选变量

.env 示例

LLM_BACKEND=ollama
OLLAMA_URL=http://localhost:11434
OLLAMA_MODEL=llama3
COMSOL_JAR_PATH=C:\Program Files\COMSOL\COMSOL63\Multiphysics\plugins
CLAW_CODE_ENABLED=1
CLAW_CODE_MAX_TURNS=12
CLAW_CODE_TIMEOUT_SECONDS=120

使用方法#

运行 uv run python cli.py 进入 CLI 后，在终端按提示输入自然语言建模需求，Agent 将自动规划并执行。 若已自行构建桌面 GUI，可在应用底部输入框输入相同需求。

$ uv run python cli.py

Python API#

源码运行环境下可从 Python 直接调用 ReAct Agent：

from agent.react.react_agent import ReActAgent

react_agent = ReActAgent(max_iterations=10)
model_path = react_agent.run("创建一个宽1米、高0.5米的矩形")
print(f"模型已保存: {model_path}")

技能库与案例库#

技能库（Skills）以 SKILL.md 组织领域知识，索引到 data/skills.db； 建模过程中 Agent 会根据任务自动检索相关技能并注入到提示词。案例库（Cases）相关能力在 GUI 源码中实现，需自行构建客户端后使用；CLI 路径以终端交互与脚本能力为主。

事件流（EventBus）#

Agent 内部通过 EventBus 广播推理与执行事件；CLI 或自建 GUI 以流式方式订阅展示， 包括 Thought / Action / Observation、工具调用、Java 侧日志、上下文用量等。

斜杠命令#

常见问题#