MetaOpenFOAM Runner ReAct
使用这个 skill 时，把 Runner 当作多轮 ReAct 控制器，而不是固定代码的一次性调用。基本方式是：先启动 MCP 服务，让模型/agent 连接 MCP 并获取工具列表；之后模型每轮选择一个工具，读取工具 observation，再决定下一步，直到成功结束或失败并输出整理后的错误日志。
安全规则
- 这个 skill 只面向真实上传/提交/监控流程；如果用户只是想做模拟成功率评测，应使用项目评测脚本，不要启动本 skill 的 MCP 服务。
- 除非用户明确要求真实运行并提供必要信息，否则不要上传、提交、下载或启动可视化。
- 不要打印 SSH 私钥、API key 或任何凭据；只引用密钥路径或环境变量名。
- 如果用户说“不要上传”“模拟”“只测试工具选择”，不要使用本 skill 的 MCP 工具；改用外部模拟评测脚本。
信息收集门槛
如果用户一开始没有提供必要信息，agent 必须先询问，不要假设。至少确认：
- 用户是否明确要求真实上传/提交；未明确时必须先问。
- 本地 case 路径：例如
run/1D_flame。真实上传前必须确认该目录存在。 - MCP 服务来源：使用 skill 自带
scripts/mcp_server.py，还是项目已有src/mcp_server.py。 - Python 环境：能运行 MCP 服务的 Python 路径，或确认当前环境已安装
mcp。 - 真实运行时的 HPC 连接信息：
user@host、端口、远端目录、SSH 私钥路径或让用户提供密钥内容。 - 轮询策略：默认每 20 分钟轮询一次；如果用户希望更短/更长，要明确。
- 结束范围：是否只提交并监控，还是完成后下载并可视化。
推荐一次性提问模板：
要执行 Runner/HPC ReAct 流程，我还需要确认：
1. 是否确认要真实上传并提交到 HPC？
2. 本地 case 目录是哪一个？
3. 使用 skill 自带 MCP 服务还是项目内 MCP 服务？
4. 如果真实运行，请给出 user@host、端口、远端目录、SSH key 路径/内容。
5. 作业完成后是否需要下载和可视化？
如果用户已经在上下文中提供了某项信息，不要重复询问；只问缺失项。不要要求用户重复粘贴私钥，除非本机没有可用密钥文件。
会话默认配置
第一次真实运行成功收集并验证配置后，将这些值视为当前会话默认值：
- MCP 服务来源和 Python 环境
key_pathuser_hostportremote_base_dir- 轮询间隔，默认 1200 秒
- 作业完成后是否下载
- 下载后是否可视化
用户之后提交第二个或更多算例时，除非用户显式修改，不要重复询问这些默认配置；只需要确认新的 case_path 是否存在。用户说“不需要下载”“这次不要可视化”“改成 10 分钟轮询”等，才覆盖对应默认值。
如果上下文跨会话丢失，或者无法确认默认配置仍然有效，应重新询问缺失项。
启动 MCP 服务
在 Runner 调工具之前，先启动 MetaOpenFOAM 的 MCP 服务。这个 skill 自带一个真实 HPC MCP 服务脚本：
METAOPENFOAM_HPC_KEY=/path/to/private_key \
METAOPENFOAM_HPC_USER_HOST=user@host \
METAOPENFOAM_HPC_PORT=65141 \
METAOPENFOAM_HPC_REMOTE_BASE=/remote/work/dir \
python /path/to/metaopenfoam-runner-react/scripts/mcp_server.py
该服务不提供 mock 模式；启动后工具会执行真实 SSH/SCP/sbatch/下载/可视化操作。缺少 HPC 环境变量时应先询问用户，不要自行猜测。
如果当前项目已经实现了自己的 MCP 服务，也可以启动项目入口，例如：
CONFIG_FILE_PATH=/path/to/inputs/2D_detonation.yaml \
PYTHONPATH=/path/to/MetaOpenFOAM/MetaGPT:/path/to/MetaOpenFOAM/src \
/path/to/MetaOpenFOAM/metaopenfoam_env/bin/python \
/path/to/MetaOpenFOAM/src/mcp_server.py
启动后，agent 必须通过 MCP client 与该服务建立连接，并用 MCP 的工具发现能力读取可用工具。不要凭空假设工具已经可用；至少应确认拿到这些工具名：
upload_and_submit_openfoam_case_on_hpccubeupload_and_submit_openfoam_cases_on_hpccubemonitor_openfoam_case_on_hpccubemonitor_openfoam_cases_on_hpccubeupload_and_monitor_openfoam_case_on_hpccubedownload_openfoam_case_from_hpccubevisualize_openfoam_case
finish_runner 是 Runner 控制器内部的结束动作，不一定由 MCP 服务提供；如果 MCP 没有这个工具，agent 仍应在自身流程里用同名动作表示“结束 Runner 并返回结果”。
ReAct 状态机
真实长作业推荐使用“提交”和“监控”分开的工具。每个本地 case 的第一步应选择：
upload_and_submit_openfoam_case_on_hpccube
得到 observation 后：
- 如果
status是submitted，记录remote_case_dir和job_id，等待 observation 中的next_poll_seconds；如果没有该字段，默认等待 1200 秒，也就是 20 分钟。之后调用monitor_openfoam_case_on_hpccube。 - 如果
monitor_openfoam_case_on_hpccube返回status="queued"或status="running"，不要下载；把队列/运行日志返回给用户，然后等待 20 分钟再次调用同一个 monitor 工具。 - 如果 monitor 返回
status="finished"，下一步选择download_openfoam_case_from_hpccube，参数使用 observation 返回的remote_case_dir。 - 如果
status是failed、error，或 observation 里包含error_log，不要下载、不要可视化；直接选择finish_runner，并在error_summary中整理错误日志。
兼容旧项目时也可以使用 upload_and_monitor_openfoam_case_on_hpccube，它会在工具内部阻塞监控直到 finished/failed。但对可能排队很久的真实超算作业，优先使用 split 模式，避免一次 MCP 调用挂太久。
批量提交与监控
如果用户给出多个 case 路径，优先使用批量工具：
- 调用
upload_and_submit_openfoam_cases_on_hpccube，参数是case_paths列表。 - 保存返回的
jobs列表，每个 job 至少包含case_path、remote_case_dir、job_id。 - 等待
next_poll_seconds，默认 1200 秒。 - 调用
monitor_openfoam_cases_on_hpccube，参数是上一步保存的jobs。 - 对返回的
grouped结果分别处理：
-queued/running：继续等待并批量轮询。
-finished：按用户默认设置下载；如果启用可视化，下载后逐个可视化。
-failed：逐个整理error_log并结束对应 case。
批量任务里不要因为一个 case 失败就停止全部任务；除非用户明确要求全局失败即停止。每次向用户汇报时，给出简短表格：case_path、job_id、status、queue_state/错误摘要。
下载后：
- 如果 observation 包含
local_path或local_case_dir，并且状态表示下载成功，下一步选择visualize_openfoam_case。 - 如果下载失败，选择
finish_runner，status="failed"，并总结下载错误。
可视化后：
- 如果 observation 返回
status="launched"，选择finish_runner，status="success"。 - 如果可视化失败，选择
finish_runner，status="failed"，并总结可视化错误。
工具选择输出格式
模型选择工具时只返回 JSON：
{
"tool": "tool_name",
"args": {},
"reason": "one short sentence"
}
可用工具/动作名：
upload_and_monitor_openfoam_case_on_hpccubeupload_and_submit_openfoam_case_on_hpccubeupload_and_submit_openfoam_cases_on_hpccubemonitor_openfoam_case_on_hpccubemonitor_openfoam_cases_on_hpccubedownload_openfoam_case_from_hpccubevisualize_openfoam_casefinish_runner
Runner 提示词应包含的信息
Runner 给模型的 prompt 至少包含：
- 当前本地
case_path - 当前脚本路径，通常是
Allrun或Allrun_postprocessing - 当前 phase
- case 文件摘要
- MCP 工具发现得到的工具名和参数摘要，尤其是 submit/monitor 分离工具
- 之前每轮工具调用与 observation，建议 JSON 化
- 上面的 ReAct 状态机规则
必须明确告诉模型：不要编造路径。上传用当前 case_path；监控用 observation 中的 remote_case_dir 和 job_id；下载用 observation 中的 remote_case_dir；可视化用 observation 中的 local_path 或 local_case_dir。
失败日志整理
如果远端运行失败，停止下载和可视化，整理错误日志并结束。错误摘要应包含：
- 队列状态，如果有
- job id，如果有
- OpenFOAM fatal/error 关键行
- 可能失败位置：mesh、边界条件、solver 发散、化学机理文件、缺失文件、调度脚本等
- 1 到 2 条下一步排查建议
摘要要短，适合写入 Runner 输出或交给 Reviewer agent。
成功率评测
评测时必须评测完整 trace，而不是只看第一步是否选择上传。
推荐 split 模式的正确成功路径：
upload_and_submit -> monitor(queued/running)* -> monitor(finished) -> download -> visualize -> finish_runner
推荐批量模式的正确成功路径：
upload_and_submit_cases -> monitor_cases(queued/running)* -> monitor_cases(finished/failed grouped) -> 对 finished 下载/可视化 -> 对 failed 整理错误 -> finish_runner
兼容长阻塞工具时的正确成功路径：
upload_and_monitor -> download -> visualize -> finish_runner
推荐 split 模式的正确失败路径：
upload_and_submit -> monitor(queued/running)* -> monitor(failed) -> finish_runner(error_summary)
兼容长阻塞工具时的正确失败路径：
upload_and_monitor -> finish_runner(error_summary)
在本仓库中，如果已有评测脚本，可使用模拟模式分批跑：
CONFIG_FILE_PATH=/mnt/d/Ubantu_run/MetaOpenFOAM/inputs/2D_detonation.yaml \
PYTHONPATH=/mnt/d/Ubantu_run/MetaOpenFOAM/MetaGPT \
metaopenfoam_env/bin/python -B scripts/evaluate_runner_tool_selection.py \
--mode react --trials 3 --limit 10 --resume --retry-failures \
--thinking none --temperature 0.7 \
--output evaluation_results/runner_react_high_temp_current.json
模拟评测使用项目脚本内部的 mock observation，不应启动本 skill 的 MCP 服务，也不应上传文件。
更多细节
实现 MCP 工具、适配其他 agent 框架、或判定 trace 时，读取 references/tool-contracts.md。
Skill 自带资源
scripts/mcp_server.py：可直接启动的真实 HPC MCP 服务，需要配置 HPC 环境变量。scripts/hpc_runner.py：MCP 服务依赖的上传、提交、单次轮询监控、下载和可视化实现。references/tool-contracts.md：工具参数、observation 契约和 trace 判定规则。
