Documentation

mph-agent 文档

Multiphysics Modeling Agent 是一款基于 ReAct 架构的 AI 智能体，将自然语言描述的 COMSOL 建模需求自动转换为完整的 .mph 模型文件。

声明：本项目仅基于 COMSOL 官方开放的 Java API 进行二次开发，与 COMSOL 官方无关联，仅供学习与交流使用，使用前请确保已拥有合法正版许可。

简介#

mph-agent 通过 Reasoning & Acting 循环理解需求、规划步骤、调用 COMSOL Java API、观察执行结果并迭代改进，最终生成可直接在 COMSOL Multiphysics 中打开的 .mph 文件。提供 Tauri + React 桌面应用 与 源码运行 两种使用方式。

ReAct 闭环

Thought → Action → Observation → Iterate

技能库 + 案例库

SKILL.md 索引到 skills.db，自动检索注入

讨论模式 + 分阶段规划

复杂需求先讨论、分阶段执行

多 LLM 后端

DeepSeek / Kimi / Ollama / OpenAI 兼容

COMSOL 6.3

Java API 直调，自动重启桥接

EventBus 流式

推理与执行事件实时推送到桌面端

架构#

三层架构：桌面交互层（Tauri + React）/ ReAct Agent 层（Python）/ COMSOL 执行层（Java API）。通过 EventBus 串联推理与执行事件。

桌面交互层

•对话 / 技能库 / 案例库
•设置 + COMSOL Ops
•上下文用量仪表

ReAct Agent 层

•Planner / Executor / ReAct
•讨论模式 + 分阶段规划
•技能检索 + 摘要记忆

COMSOL 执行层

•Java API 直调（6.3）
•几何 / 物理场 / 网格 / 研究
•结构化 .mph 解析

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

环境要求#

组件	要求	说明
`Python`	3.8+	推荐 3.11 / 3.12
COMSOL Multiphysics	6.1+	6.3+ 推荐，需已安装并拥有正版许可
Java JDK	8+	与 COMSOL 兼容；项目可使用内置 JDK 11

安装#

方式一：桌面版（推荐）

仅 Windows。安装包内含 Java 11，无需额外安装 Python/JDK。

下载 Releases

方式二：从源码运行

适合开发者；需 Node.js + Rust 进行桌面端构建。

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

环境配置#

在项目根目录创建 .env，或在桌面应用的设置页中填写。

必需变量

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

可选变量

变量	说明
`JAVA_HOME`	未配置时使用系统 Java 或项目内置 JDK 11
`JAVA_DOWNLOAD_MIRROR`	国内可设 tsinghua 使用清华镜像
`MODEL_OUTPUT_DIR`	模型输出目录，默认 ./models

.env 示例

LLM_BACKEND=ollama
OLLAMA_URL=http://localhost:11434
OLLAMA_MODEL=llama3
COMSOL_JAR_PATH=C:\Program Files\COMSOL\COMSOL63\Multiphysics\plugins

使用方法#

启动桌面应用后，在底部输入框输入自然语言建模需求，Agent 将自动规划并执行。

uv run python cli.py

默认模式

直接生成 COMSOL 模型，例如「创建一个宽 1 米、高 0.5 米的矩形」。

计划模式

输入 /plan 切换为仅解析 JSON；/run 切回默认。

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）在桌面端提供同步能力，结合结构化的本地 .mph解析作为参考上下文，帮助新任务快速成功。

Skills

目录：skills/；入口：skills/README.md；按领域（几何 / 物理场 / 网格 / 研究 / 后处理）编写 SKILL.md 即可自动生效。

Cases

桌面端 Cases 页面支持同步案例库与本地 .mph 结构化解析，可作为新建模任务的示例与参考上下文。

事件流（EventBus）#

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

典型事件：

thought：模型思考过程
action：即将执行的工具调用
observation：Java 侧返回结果 / 错误
plan.stage：分阶段规划的阶段切换
context.usage：Prompt 用量变化

斜杠命令#

命令	说明
`/demo`	演示建模流程
`/doctor`	环境诊断（COMSOL / Java / LLM 检查）
`/context`	查看会话摘要与历史
`/backend`	选择 LLM 后端
`/output`	设置输出文件名
`/plan`	切换到计划模式（仅解析 JSON）
`/run`	切回默认执行模式
`/help`	查看帮助
`/quit`	退出应用

常见问题#

COMSOL JAR 找不到？+

COMSOL 6.3+ 请将 COMSOL_JAR_PATH 配置为 plugins 目录；6.1 及更早则配置为单个 jar 路径。在桌面应用内运行 /doctor 可自动诊断。

Java 环境报错？+

可依赖项目内置 JDK 11（自动下载到 runtime/java，国内可设 JAVA_DOWNLOAD_MIRROR=tsinghua 使用清华镜像）；若使用系统 Java，请确保 JAVA_HOME 与 COMSOL 兼容。

API 调用失败？+

检查当前 LLM 后端对应的 API Key（如 DEEPSEEK_API_KEY、KIMI_API_KEY）是否已在 .env 或环境变量中配置。

Windows 上构建桌面应用报 linker / link.exe not found？+

需安装 Build Tools for Visual Studio 并勾选「使用 C++ 的桌面开发」；或使用 GNU 工具链：rustup default stable-x86_64-pc-windows-gnu（需 MSYS2/MinGW）。

从 comsol-agent 迁移？+

将命令与配置中的 comsol-agent 改为 mph-agent，桌面端需重新安装以更新产品名与 identifier。

← 返回首页更新日志 →