探测本机 MIKE Zero 环境：安装位置、bin/x64、无界面入口、引擎数量、mikeio 可用性。

Args: year: 可选，指定 MIKE Zero 年份（如 "2023"）；不传则取最新安装。

列出 MIKE Zero 的 扩展名 -> 引擎 映射（来自 MzEngines.cfg）。

Args: extension: 可选，只看某个扩展名，如 ".m21fm"。 year: 可选，指定 MIKE Zero 年份。

扫描一个工程目录，按类型归类 MIKE Zero 的 setup 文件与结果文件。

Args: root: 要扫描的目录（绝对路径）。 max_files: 最多扫描多少个文件，默认 5000。 year: 可选，指定 MIKE Zero 年份以确定 setup 扩展名。

解析一个 MIKE Zero setup 文件（PFS 格式），返回引擎、段、文件引用、关键参数。

Args: setup: setup 文件绝对路径，例如 .m21fm / .sim11 / .she / .couple / .mzt。 year: 可选，指定 MIKE Zero 年份。

无界面启动一次 MIKE Zero 模拟，返回作业 id。

默认后台运行，用 mz_progress / mz_job_status / mz_job_log 跟踪进度。

两种入口（实测 MIKE Zero 2023）：

• direct=False（默认）走 MzLaunch.exe：支持 -e/-mpi/-gpu/-y/-z， 但模拟结束后会删掉 ._spi_ 进度文件（本服务会先归档）。

• direct=True 直接调引擎 exe（如 MIKE11.exe / FemEngineHD.exe）：开关按引擎 自己的语法拼装，._spi_ 跑完仍保留。不支持 -mpi/-gpu/-z。

Args: setup: setup 文件绝对路径。 engine: 可选，显式指定引擎 exe（如 MIKE11.exe）；不传则由 MzEngines.cfg 按扩展名自动选择。 direct: True 时绕过 MzLaunch，直接调用引擎。 engine_flag: 走 MzLaunch 时指定引擎的参数名，默认 "-e"。 silent: 走 MzLaunch 时传未文档化的 -run（实测可省，非必要不要开）。 exit_when_done: 走 MzLaunch 时传 -x，模拟结束后退出启动器。 mpi: 子域数，传 -mpi N（需该引擎支持 MPI）。 gpu: GPU 卡数，传 -gpu N。 priority: CPU 优先级，传 -y 1..4（1 低，4 高于正常）。 extra_args: 追加的原始命令行参数。 result_dir: 走 MzLaunch 时传 -z 指定结果目录。 year: 可选，指定 MIKE Zero 年份。 wait: 是否同步等待结束（长时间模拟建议保持 False）。 timeout: wait=True 时的等待上限（秒）。

读某个作业的实时进度：百分比、当前模拟时刻、步数、计算速度、剩余时间。

数据来自引擎写的 <setup名>._spi_（例如 PROGRE 1000 表示完成）。 若原文件已被 MzLaunch 删除，则读本服务归档的副本。

Args: job_id: mz_run 返回的作业 id。

批量顺序执行多个 setup：生成 .bat（DHI 官方做法）并后台运行。

生成的 .bat 会保留在 workdir 里，可自行查看或手工重跑。

Args: setups: setup 文件绝对路径列表，按顺序执行。 workdir: 工作目录，默认取第一个 setup 所在目录。 engine / engine_flag / mpi / gpu / priority / extra_args: 同 mz_run。 year: 可选，指定 MIKE Zero 年份。 wait: 是否同步等待整批结束。 timeout: wait=True 时的等待上限（秒）。

用 ToolboxShell.exe 无界面运行一个 Toolbox setup（.mzt / .21t / .3t / .lpkt / .mst）。

Args: setup: toolbox setup 文件绝对路径。 extra_args: 追加参数。 year: 可选，指定 MIKE Zero 年份。 wait: 是否同步等待。 timeout: wait=True 时的等待上限（秒）。

列出最近的作业（模拟 / 批量 / 工具箱）。

Args: limit: 最多返回多少条，默认 20。

查询作业状态：进程是否存活、耗时、日志文件、报错行、新增结果文件。

Args: job_id: mz_run / mz_run_batch / mz_toolbox 返回的作业 id。

读取作业日志末尾若干行（MIKE Zero 把进度写在结果目录的 .log 里）。

Args: job_id: 作业 id。 lines: 读取末尾行数，默认 200。

终止一个作业（连同其子进程，用 taskkill /T）。

Args: job_id: 作业 id。 force: 是否强制结束，默认 True。

读取结果文件元信息：类型、条目名称/单位、时间轴、网格规模。

支持 dfs 系列（.dfs0/.dfs1/.dfs2/.dfs3/.dfsu，走 mikeio） 以及 MIKE 11 / 1D 结果（.res1d/.res11，走 mikeio1d）。

Args: path: 结果文件绝对路径。

读取结果数据：统计量（最大/最小/均值）与抽样后的序列。

数据量大时自动抽样到 max_points 个点，避免撑爆上下文。 对 1D 结果（.res1d/.res11），item 可传量名（如 "Water Level"，返回该量的前几列） 或具体列名（如 "Water Level:CALI:0"，即 量:河段:里程）。

Args: path: 结果文件绝对路径。 item: dfs：条目名或序号。1D：量名 / 列名 / 序号。不传则取第一项。 start: 起始时间，如 "1989-07-27 00:00"。 end: 结束时间。 max_points: 序列抽样点数上限，默认 500。

把结果序列画成 PNG 图片，返回图片路径。支持 dfs 系列与 1D 结果。

Args: path: 结果文件绝对路径。 item: 条目名 / 量名 / 序号；不传则取第一项。 out_png: 输出 PNG 路径；不传则与结果文件同目录同名。