Recipe Executor(配方执行器)

Recipe Executor - User Manual

Dragonfly Prototype Apps · Recipe Executor...

版本 Version 1.0 · 2026-07-14

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

Recipe Executor(配方执行器) 是一个轻量的、原生窗口式的"执行 recipe"工具,用于在 Dragonfly 内运行 Prototype Labs 的 script recipe。它不再依赖 Prototype Labs 的网页客户端,而是提供一个可停靠的 PyQt6 面板——像其它插件一样的窗口——让你选择一个 recipe、按需填写输入/输出,并在 Dragonfly 的 UI 线程中执行它。

它不导入 ORSModel。与网页客户端一样,它通过环回套接字(默认 127.0.0.1:54321)连接到进程内的 Prototype Labs TCP 服务器,请求服务器在 Dragonfly 的 UI 线程中 run_script(即 GUI Sync)。它原样复用了网页客户端的后端:TCP 协议(send_df_request)、recipe 加载(.py、通过 script_builder + script_blocks 组装的 JSON workflow、以及 sidecar .py 回退)、输入/输出运行时变量分析,以及运行时变量前缀注入。

输入: 一个 recipe 文件(.py / .json / .md);若该 recipe 使用运行时变量,还需一个输入文件/文件夹和/或输出文件夹。输出: 由 recipe 本身创建的任何 Dragonfly 对象(Channel、ROI、MultiROI、网格、保存的文件等)——Recipe Executor 只是启动器,不是算法本身。

它不是完整的 Prototype Labs GUI:这里没有备份、宏录制、自动执行器或菜单/宏管理——它只做一件事,执行 recipe。它不封装任何开源引擎,是一个纯 socket + PyQt 的进程内工具,只用到标准库。

2. 适用场景

• 不想打开完整的 Prototype Labs GUI,只需要"选一个 recipe 并在 Dragonfly 里跑一下"。
• 快速对当前会话重新运行库里某个已保存的 recipe。
• 运行别人发给你的 .py 或 .json recipe,而不必永久添加进库。
• 对选定的文件或文件夹运行需要输入/输出的 recipe(例如读取 input_file/input_dir 并写到 output_dir 的加载-处理流水线)。
• 维护一个小型个人 recipe 库,在 Dragonfly 内从下拉框直接调用常用脚本。

3. 安装与启用

Recipe Executor 随 Prototype Apps Full Package(完整包) 一起发布,并非独立下载——请通过完整包安装器安装。

1. 把完整包解压到一个较短的目录路径(如 C:\PLApps),以避免 Windows 长路径问题。

2. 运行 Install_FullPackage.bat。

3. 在安装对话框中勾选 "Recipe Executor"(默认所有插件都未勾选),然后点击 Install。

4. 完全重启 Dragonfly——菜单只在启动时扫描,正在运行的实例不会显示新项。

5. 从 Prototype Apps > Recipe Executor... 打开,它位于 "Generators & Utilities(生成器与工具)" 分组下。

之后可通过 Developer > Prototype Labs... > Menu Item Manager 启用或禁用。所有内容安装在 %LOCALAPPDATA% 下,无需管理员权限。每次切换后都需重启 Dragonfly 才能生效。

开发者也可直接安装:E:\Dragonfly2027.1\Python_env\python.exe install_recipe_executor_plugin.py(卸载加 --uninstall),随后完全重启。

4. 运行环境与首次配置

无需任何环境配置。 Recipe Executor 以进程内方式运行在 Dragonfly 自带的 Python 中,只使用标准库(socket、struct、json、tokenize)加 PyQt6。没有 venv、无需下载、不需要 GPU、不联网——因为没有第三方依赖需要安装,所以也没有"Setup Environment"按钮。

唯一的硬性依赖是 Prototype Labs TCP 服务器必须在运行。请从 Prototype Apps > Server Management 启动它。Recipe Executor 通过环回套接字连接该服务器,并在面板打开时显示连接状态;若服务器未运行,Run Recipe 与 Check connection 都会失败。

服务器目标默认为 127.0.0.1:54321,可通过环境变量 DF_PROTOTYPE_LABS_TCP_HOST / DF_PROTOTYPE_LABS_TCP_PORT(也兼容 DF_SERVER_HOST/PORT、AED_DF_GUI_HOST/PORT)覆盖。组装 JSON workflow 类型的 recipe 还需要 script_builder.py + script_blocks 文件夹;插件会依次从已安装的 GenericMenuItems、开发仓库、以及自身代码目录中解析这些资源,找不到时回退到同名 sidecar .py(或给出明确提示)。纯 .py recipe 无此依赖。

5. 界面说明

面板以可停靠/浮动窗口打开,标题为 Recipe Executor,顶部有一行提示,说明它以 GUI Sync 方式运行且需要 Prototype Labs 服务器。

Dragonfly server(服务器)

• Server: <host:port> — 只读标签,显示解析后的 TCP 目标。
• Status: … — 连接状态(成功/已连接显示绿色,失败显示红色)。
• Check connection — ping 服务器,报告 Success(在 GUI 中)/ Connected 及服务器 pid,或报错信息。
• Interrupt — 发送 interrupt_ui_thread,用于中断 Dragonfly UI 线程上正在运行的脚本或阻塞对话框。

Recipe(配方)

• Library: — recipe 库中已保存 recipe 的下拉框(按最新排序);其 tooltip 显示库文件夹路径。
• Refresh — 重新读取库文件夹并刷新下拉框。
• Load — 加载当前选中的库 recipe。
• Browse file… (.py / .json / .md) — 从任意位置选择并加载一个 recipe 文件,不加入库。
• Add file to library… — 选择一个 recipe 文件,复制进库并加载。
• Loaded: — 显示已加载 recipe 的名称、来源,以及 IO 徽标:*needs input*(需输入)、*needs output*(需输出),或 *no runtime input/output*(无运行时输入输出)。

Input / Output(输入/输出,仅用于使用运行时变量的 recipe)

• Input file/folder: — 文本框加 File… 与 Folder… 按钮。仅当加载的 recipe 引用了输入运行时变量时可用。
• Output folder: — 文本框加一个 Folder… 按钮。仅当加载的 recipe 引用了输出运行时变量时可用。

运行与日志

• Run Recipe — 主按钮(蓝色);在 Dragonfly 的 UI 线程中执行已加载的 recipe。
• 状态行 — 一行结果(成功绿色,失败红色)。
• 日志 — 只读、带时间戳的日志面板,流式显示客户端消息以及运行的远端 stdout/stderr。

6. 使用步骤

1. 从 Prototype Apps > Server Management 启动 Prototype Labs 服务器,再打开 Prototype Apps > Recipe Executor...。

2. 点击 Check connection,确认状态变为绿色(Success/Connected)。

3. 选择一个 recipe:从 Library 下拉框选择并点 Load,或用 Browse file… 加载外部 .py/.json/.md,或用 Add file to library… 保存并加载。

4. 查看 Loaded: 徽标。若显示 *needs input* / *needs output*,填写 Input file/folder 和/或 Output folder(用 File…/Folder… 选择)。若显示 *no runtime input/output* 则跳过此步。

5. 点击 Run Recipe。在日志中查看远端 stdout/stderr;状态行报告成功或错误。

6. 若脚本卡住或留下阻塞对话框,点击 Interrupt 中断 UI 线程。

你填写的输入/输出路径会记录在插件代码旁的 recipe_exec_config.json 中,下次自动预填。

7. 参数说明

Recipe Executor 本身没有算法数值参数——计算完全在你加载的 recipe 里。影响运行的选项/控件如下:

识别的输入运行时变量:input_file、input_files、input_dir、input_folder、input_name;输出:output_dir、output_folder。Recipe Executor 通过对 recipe 源码做 tokenize 检测使用了哪些变量,并在运行前注入定义它们的运行时前缀。recipe 中的特殊注释 # AED_AUTO_CLOSE_DIALOG: <标题>|<延迟毫秒> 可在延迟后(默认 2000 毫秒)自动关闭匹配的 Windows 对话框。

8. 输出结果

Recipe Executor 本身不创建任何 Dragonfly 对象——它是启动器。输出是被执行 recipe 所产生的一切:例如 Channel、ROI、MultiROI、网格、测量值,或写入输出文件夹的文件。由于走的是相同的 run_script GUI-Sync 路径,这些对象在 Dragonfly 中的呈现与在 Prototype Labs GUI 里运行该 recipe 完全一致。

当提供了输出文件夹时,若不存在会自动创建,output_dir/output_folder 被设为其解析后的绝对路径。对于文件输入,input_file 为该文件,input_dir/input_folder 为其父目录;对于文件夹输入,input_files 为其中文件的有序列表,input_file 为第一个。运行的远端 stdout/stderr 会流式显示到日志面板;成功时状态行显示 *Script finished.*。

9. 常见问题与故障排除

• 状态红色 / "No response from Dragonfly server" — Prototype Labs 服务器未运行或端口不同。从 Prototype Apps > Server Management 启动它,再点 Check connection。
• "Load a recipe first." — 尚未加载 recipe;选择一个并点 Load(或 Browse/Add)。
• "This recipe needs runtime variable(s)…" — 该 recipe 使用了 input_*/output_*;运行前先填写已启用的 Input/Output 字段。
• "script_builder.py was not found" / "script_blocks folder was not found" — 你选择的是 JSON workflow recipe 但组装资源不可达。改选生成好的 .py recipe,或把共享资源安装到 GenericMenuItems。
• "Recipe JSON has no workflow, code, script path, or matching sidecar .py" — 该 .json 没有可运行主体也没有同名 .py;请提供 .py。
• Markdown recipe 失败 — .md 需要同名的 .json 或 .py;请改加载该文件。
• Interrupt 提示 "Unknown cmd" — 运行中的服务器版本尚不支持 interrupt_ui_thread;重启 Prototype Labs 服务器到较新版本。
• 日志中出现 recipe 错误 — traceback 来自在 Dragonfly 内运行的 recipe;请调试该 recipe 本身(本工具只是启动它)。

10. 注意事项与已知限制

• 仅执行 recipe — 没有备份、宏录制、自动执行器或菜单/宏管理;这些保留在网页客户端 / 完整 Prototype Labs GUI 中。
• 需要 Prototype Labs TCP 服务器 在运行;没有直接的对象模型访问(从不导入 ORSModel)。
• 以 GUI Sync 方式在 Dragonfly UI 线程运行——recipe 运行期间 Dragonfly 界面处于忙碌状态;卡住的脚本可能需要用 Interrupt 中断。
• JSON workflow 组装 依赖 script_builder.py + script_blocks 可达;没有它们时只能运行 .py recipe(或内嵌/带 sidecar 脚本的 JSON)。
• 自动关闭对话框 辅助功能仅限 Windows(FindWindowW/PostMessage)。
• 实机验证待完成: TCP 运行路径原样复制自可用的网页客户端,但尚未在此插件形态下实机重跑。

11. 参考资料

• 插件文档:DragonflyPlugins/RecipeExecutor-Plugin/README.md 与 DESIGN.md。
• 核心后端(TCP 协议、recipe 加载、IO 分析、运行):recipe_exec_code/recipe_exec_core.py;PyQt 面板:recipe_exec_code/recipe_exec_panel.py。
• 未封装任何第三方开源引擎——仅使用 Python 标准库(socket、struct、json、tokenize)与 PyQt6,基于 Prototype Labs dragonfly_server 的 TCP 协议。
• 相关:Prototype Apps > Server Management(启动所需 TCP 服务器)与 Prototype Labs 的 Script Builder / recipe 库。

Part II English Manual

Contents

1. Introduction

2. Use cases

3. Installation & enabling

4. Runtime environment & first-run setup

5. Interface

6. How to use

7. Parameters

8. Output

9. FAQ & troubleshooting

10. Notes & known limitations

11. References

1. Introduction

Recipe Executor is a lightweight, native windowed "execute recipe" tool that runs a Prototype Labs script recipe inside Dragonfly. Instead of the Prototype Labs browser/web client, it gives you a dockable PyQt6 panel — a window like every other Prototype Apps plugin — that lets you pick a recipe, optionally supply an input/output, and run it in Dragonfly's UI thread.

It does not import ORSModel. Like the web client, it connects to the in-process Prototype Labs TCP server over a loopback socket (default 127.0.0.1:54321) and asks the server to run_script in Dragonfly's UI thread (GUI Sync). It reuses the web client's exact backend verbatim: the TCP protocol (send_df_request), recipe loading (.py, JSON workflow assembled via script_builder + script_blocks, sidecar .py fallback), input/output runtime-variable analysis, and runtime-prefix injection.

Input: a recipe file (.py / .json / .md) plus, if the recipe uses runtime variables, an input file/folder and/or an output folder. Output: whatever Dragonfly objects the recipe itself creates (Channels, ROIs, MultiROIs, meshes, saved files, etc.) — Recipe Executor is only the launcher, not the algorithm.

This is not the full Prototype Labs GUI: there is no backup, macro recording, auto-executor, or menu/macro management here — it does exactly one thing, execute a recipe. There is no bundled open-source engine; it is a pure socket + PyQt in-process tool wrapping the standard library.

2. Use cases

• You don't want to open the full Prototype Labs GUI and only need to "pick a recipe and run it in Dragonfly".
• Quickly re-run a saved library recipe on the current session.
• Run a .py or .json recipe that someone sent you, without adding it permanently.
• Run an input/output recipe against a chosen file or folder (e.g. load-a-volume-then-process pipelines that read input_file/input_dir and write to output_dir).
• Keep a small personal recipe library of frequently used scripts, accessible from a dropdown inside Dragonfly.

3. Installation & enabling

Recipe Executor ships in the Prototype Apps Full Package. It is not a standalone download — install it through the Full Package installer.

1. Unzip the Full Package to a short directory path (e.g. C:\PLApps) to avoid Windows long-path issues.

2. Run Install_FullPackage.bat.

3. In the installer dialog, check "Recipe Executor" (all plugins are unchecked by default), then click Install.

4. Fully restart Dragonfly — the menu is scanned only at startup, so a running instance will not show the new item.

5. Open it from Prototype Apps > Recipe Executor..., listed in the "Generators & Utilities(生成器与工具)" section.

You can later enable or disable it via Developer > Prototype Labs... > Menu Item Manager. Everything installs under %LOCALAPPDATA% and needs no administrator rights. Restart Dragonfly after each toggle for the change to take effect.

For developers, the plugin can be installed directly with E:\Dragonfly2027.1\Python_env\python.exe install_recipe_executor_plugin.py (uninstall with --uninstall), followed by a full restart.

4. Runtime environment & first-run setup

No environment setup is required. Recipe Executor runs in-process in Dragonfly's own Python and uses only the standard library (socket, struct, json, tokenize) plus PyQt6. There is no venv, no download, no GPU, and no internet needed — there is no "Setup Environment" button because there are no third-party dependencies to install.

The one hard dependency is that the Prototype Labs TCP server must be running. Start it from Prototype Apps > Server Management. Recipe Executor connects to it over a loopback socket and shows the connection status when the panel opens; without it, Run Recipe and Check connection will fail.

The server target defaults to 127.0.0.1:54321 and can be overridden via the environment variables DF_PROTOTYPE_LABS_TCP_HOST / DF_PROTOTYPE_LABS_TCP_PORT (also honored: DF_SERVER_HOST/PORT, AED_DF_GUI_HOST/PORT). Assembling JSON-workflow recipes additionally needs script_builder.py + the script_blocks folder; the plugin resolves these from the installed GenericMenuItems folder, then the dev repo, then its own code directory, and falls back to a sidecar .py (or a clear message) when they cannot be found. Plain .py recipes run with no such dependency.

5. Interface

The panel opens as a dockable/floating window titled Recipe Executor, with a one-line header reminding you it runs in GUI Sync and needs the Prototype Labs Server.

Dragonfly server

• Server: <host:port> — read-only label showing the resolved TCP target.
• Status: … — connection status (green on success/connected, red on failure), updated by the check.
• Check connection — pings the server and reports Success (in GUI) / Connected plus the server pid, or the error.
• Interrupt — sends interrupt_ui_thread to stop a running script or a blocking dialog on the Dragonfly UI thread.

Recipe

• Library: — dropdown of saved recipes from the recipe library (sorted newest first); its tooltip shows the library folder path.
• Refresh — re-reads the library folder into the dropdown.
• Load — loads the currently selected library recipe.
• Browse file… (.py / .json / .md) — pick and load a recipe file from anywhere without adding it to the library.
• Add file to library… — pick a recipe file, copy it into the library, and load it.
• Loaded: — shows the loaded recipe name, its source, and an IO badge: *needs input*, *needs output*, or *no runtime input/output*.

Input / Output (only for recipes that use runtime variables)

• Input file/folder: — line edit plus File… and Folder… buttons. Enabled only when the loaded recipe references an input runtime variable.
• Output folder: — line edit plus a Folder… button. Enabled only when the loaded recipe references an output runtime variable.

Run and log

• Run Recipe — the primary (blue) button; executes the loaded recipe in Dragonfly's UI thread.
• Status line — one-line result (green on success, red on failure).
• Log — read-only, time-stamped log pane streaming client messages and the remote stdout/stderr from the run.

6. How to use

1. Start the Prototype Labs Server from Prototype Apps > Server Management, then open Prototype Apps > Recipe Executor....

2. Click Check connection and confirm the status turns green (Success/Connected).

3. Pick a recipe: choose one from the Library dropdown and click Load, or use Browse file… to load an external .py/.json/.md, or Add file to library… to save-and-load it.

4. Read the Loaded: badge. If it says *needs input* / *needs output*, fill Input file/folder and/or Output folder (use the File…/Folder… pickers). If it says *no runtime input/output*, skip this step.

5. Click Run Recipe. Watch the log for remote stdout/stderr; the status line reports success or the error.

6. If a script hangs or leaves a blocking dialog open, click Interrupt to stop the UI thread.

Input/output paths you enter are remembered in recipe_exec_config.json next to the plugin code, so they pre-fill next time.

7. Parameters

Recipe Executor has no numeric algorithm parameters of its own — the computation lives entirely in the recipe you load. The controls/options that affect a run are:

Recognized input runtime variables: input_file, input_files, input_dir, input_folder, input_name. Output: output_dir, output_folder. Recipe Executor detects which are used by tokenizing the recipe source and injects a runtime prefix defining them before running. A special comment # AED_AUTO_CLOSE_DIALOG: <title>|<delay_ms> in a recipe will auto-close a matching Windows dialog after the delay (default 2000 ms).

8. Output

Recipe Executor itself creates no Dragonfly objects — it is a launcher. The outputs are whatever the executed recipe produces: for example Channels, ROIs, MultiROIs, meshes, measurements, or files written to the output folder. These appear in Dragonfly exactly as they would if the recipe were run from the Prototype Labs GUI, since it is the same run_script GUI-Sync path.

When an output folder is supplied it is created if missing, and output_dir/output_folder are set to its resolved absolute path. For a file input, input_file is that file and input_dir/input_folder its parent; for a folder input, input_files is the sorted list of files in it and input_file is the first. The remote stdout/stderr of the run is streamed into the log pane; the status line shows *Script finished.* on success.

9. FAQ & troubleshooting

• Status is red / "No response from Dragonfly server" — the Prototype Labs Server isn't running or is on a different port. Start it from Prototype Apps > Server Management and click Check connection.
• "Load a recipe first." — no recipe is loaded; select one and click Load (or Browse/Add).
• "This recipe needs runtime variable(s)…" — the recipe uses input_*/output_*; fill the enabled Input/Output fields before running.
• "script_builder.py was not found" / "script_blocks folder was not found" — you selected a JSON workflow recipe but the assembler assets aren't reachable. Select the generated .py recipe instead, or install the shared assets under GenericMenuItems.
• "Recipe JSON has no workflow, code, script path, or matching sidecar .py" — the .json has no runnable body and no sibling .py; provide the .py.
• Markdown recipe fails — a .md needs a sibling .json or .py of the same name; load that file instead.
• Interrupt says "Unknown cmd" — the running server build predates interrupt_ui_thread; restart the Prototype Labs Server to a current build.
• A recipe error appears in the log — the traceback comes from the recipe running inside Dragonfly; debug the recipe itself (this tool only launched it).

10. Notes & known limitations

• Execute-recipe only — no backup, macro recording, auto-executor, or menu/macro management; those stay in the web client / full Prototype Labs GUI.
• Requires the Prototype Labs TCP server running; there is no direct object-model access (ORSModel is never imported).
• Runs in GUI Sync on Dragonfly's UI thread — while a recipe runs, Dragonfly's UI is busy; a stuck script may require Interrupt.
• JSON-workflow assembly depends on script_builder.py + script_blocks being reachable; without them only .py recipes (or JSON with an embedded/sidecar script) run.
• The auto-close-dialog helper is Windows-only (FindWindowW/PostMessage).
• Live-verify pending: the TCP run path is copied verbatim from the working web client but has not been re-run live in this plugin form.

11. References

• Plugin docs: DragonflyPlugins/RecipeExecutor-Plugin/README.md and DESIGN.md.
• Core backend (TCP protocol, recipe loading, IO analysis, run): recipe_exec_code/recipe_exec_core.py; PyQt panel: recipe_exec_code/recipe_exec_panel.py.
• No third-party open-source engine is wrapped — it uses only the Python standard library (socket, struct, json, tokenize) and PyQt6, over the Prototype Labs dragonfly_server TCP protocol.
• Related: Prototype Apps > Server Management (starts the required TCP server) and the Prototype Labs Script Builder / recipe library.