Ghidra PyGhidra 深度解析：在原生 CPython 3 中驱动 Ghidra API 的插件、库与启动机制

Ghidra 的 PyGhidra 模块（位于 Ghidra/Features/PyGhidra）把原生 CPython 3 解释器深度集成进 Ghidra：它既提供可独立安装的 pyghidra Python 库（通过 JPype 直接访问 Ghidra 的 Java API），又提供 GUI 内的交互式解释器插件和 CPython 3 版 GhidraScript 提供者，还内置了自动处理虚拟环境与 externally-managed 环境的启动脚本。读完本文，你将理解 PyGhidra 四大组成（Python 库、解释器插件、脚本提供者、启动脚本）各自的职责与源码实现，掌握 pyghidra.start() / program_context() / analyze() 等核心 API 的用法，并能在 Ghidra GUI 和 headless 命令行两种模式下实际使用它。

模块概览：README 中声明的四项能力

模块入口文档 README.md 声明了 PyGhidra 提供的四类能力，它们分别对应模块内的四块代码：

1. PyGhidra Python 库及其依赖 —— 对应 src/main/py/README.md 中记录的 pyghidra 包，源码位于 src/main/py/src/pyghidra/；
2. 提供 CPython 解释器的 Plugin —— 对应 PyGhidraPlugin.java，在 Ghidra GUI 中注册交互式 Python 解释器面板；
3. 可运行原生 CPython 3 GhidraScript 的 ScriptProvider —— 对应 PyGhidraScriptProvider.java，使 .py 脚本能以原生 CPython（而非 Jython）执行；
4. Ghidra 用于安装并启动 PyGhidra 的交互式 Python 脚本 —— 对应 support/pyghidra_launcher.py，负责处理 虚拟环境 与 externally managed environments。

此外，模块还附带示例脚本 ghidra_scripts/PyGhidraBasics.py、GUI 主题配置 data/python.theme.properties 以及在线帮助文档 src/main/help/help/topics/PyGhidra/interpreter.html。

运行前提：Python 版本、JPype 依赖与 Ghidra 最低版本

从源码和打包配置可以确认 PyGhidra 的硬性前提：

• Python 版本：pyproject.toml 声明 requires-python = ">= 3.9"，classifiers 覆盖 3.9 到 3.14。GUI 侧支持的版本则由 Ghidra/application.properties 中的 application.python.supported=3.14, 3.13, 3.12, 3.11, 3.10, 3.9 指定，pyghidra_launcher.py 启动时正是读取该属性来筛选系统里可用的 Python 解释器（见下文“启动脚本”一节）。
• 依赖关系：dependencies = ["Jpype1 >=1.5.2, !=1.6.0, !=1.7.0", "typing_extensions ~=4.16", "packaging"]，其中 JPype 是连接 CPython 与 JVM 的核心桥接库；排除 1.6.0 是为了规避 JPype 1.6.0 在 Windows 上的崩溃问题（库 README 的 Change History 中明确提到）。
• Ghidra 最低版本：src/main/py/src/pyghidra/version.py 中 MINIMUM_GHIDRA_VERSION = "12.0"，PyGhidraLauncher.check_ghidra_version() 会在启动时比对 application.properties 里的版本并拒绝过低版本。
• 当前库版本：src/main/py/src/pyghidra/init.py 中 __version__ = "3.2.0"，与库 README 的 Change History（3.2.0）一致。

安装：在线 pip 与离线 wheel 两种方式

Ghidra 发行版内置了 PyGhidra，因此 GUI / headless 都能直接跑原生 CPython 3 脚本和内置 REPL；作为独立 Python 库使用时（pyghidra 只是诸多逆向组件之一），按 库 README 的步骤安装：

1. 下载并安装 Ghidra 12.0 或更高版本到目标位置；
2. 安装 PyGhidra：
   • 在线：pip install pyghidra
   • 离线：python3 -m pip install --no-index -f <GhidraInstallDir>/Ghidra/Features/PyGhidra/pypkg/dist pyghidra
3. 可选：安装 Ghidra 类型存根（针对特定 Ghidra 版本），改善编辑器补全体验：
   • 在线：pip install ghidra-stubs==<version>
   • 离线：python3 -m pip install --no-index -f <GhidraInstallDir>/docs/ghidra_stubs ghidra-stubs
4. 可选：安装 Java 类型存根：在线 pip install java-stubs-converted-strings（离线不可用）；
5. 可选：通过环境变量 GHIDRA_INSTALL_DIR 指向 Ghidra 安装目录。若未设置，PyGhidra 会回退到读取 Ghidra 用户设置目录下的 lastrun 文件（Ghidra 11.4 起创建）。也可以直接 pyghidra.start(install_dir=<GhidraInstallDir>)。

安装目录的解析优先级在 launcher.py 中得到印证：install_dir = install_dir or os.getenv("GHIDRA_INSTALL_DIR") or _lastrun()，随后 _validate_install_dir() 会校验目录存在、Ghidra/application.properties 存在，以及 Ghidra/Features/PyGhidra/lib/PyGhidra.jar 存在（三者缺一即抛出带明确提示的 ValueError）。_lastrun() 则按平台在 %APPDATA%（Windows）、~/Library（macOS）、~/.config（Linux，且优先尊重 XDG_CONFIG_HOME）下查找 ghidra/lastrun。

核心 API：从 start() 到 walk_programs()

3.0 版 API 的目标是让“打开项目、获取程序、运行脚本”这类高频操作尽量简洁，完整签名记录在 库 README 的 API 一节，实现集中在 src/main/py/src/pyghidra/api.py。逐个说明关键函数：

• pyghidra.start(verbose=False, *, install_dir=None)：以 Headless 模式启动 JVM 并完整初始化 Ghidra。实现上它创建 HeadlessPyGhidraLauncher 并调用 launcher.start()，返回该 launcher（可用于后续 add_classpaths / add_vmargs 等操作）。
• pyghidra.started()：查询 launcher 是否已启动（JVM 已起且 Application.isInitialized() 为真）。
• pyghidra.open_project(path, name, create=False)：打开指定位置的项目，create=True 时自动创建；项目不存在且不允许创建时抛 FileNotFoundError。实现使用 Java 侧的 ProjectLocator 与 PyGhidraProjectManager.java。注意返回的 Project 支持 with 语法（上下文管理器自动关闭项目）。
• pyghidra.open_filesystem(path)：把任意 Ghidra 可识别的“文件系统”（zip 文件、目录等）挂入 Ghidra，返回 GFileSystem；不支持的容器抛 ValueError。
• pyghidra.consume_program(project, path, consumer=None)：按项目内路径（以 / 开头）取出 Program，返回 (program, consumer) 二元组，程序用完后必须调用 program.release(consumer) 手动释放。consumer 机制确保底层 DomainObject 在所有消费方都释放后才真正关闭；路径不是 Program 时抛 pyghidra.ProgramTypeError。
• pyghidra.program_context(project, path)：consume_program 的上下文管理器封装，退出 with 块自动 release，是日常脚本中最推荐使用的方式。
• pyghidra.analyze(program, monitor=None)：在事务内通过 AutoAnalysisManager 执行全量分析并返回分析日志；日志收集方式是向分析管理器注册一个监听器，累积 getMessageLog()。
• pyghidra.ghidra_script(path, project, program=None, echo_stdout=True, echo_stderr=True)：运行任意类型（Java、PyGhidra、Jython 等）的 GhidraScript，返回 (stdout, stderr) 二元组。源码实现中它通过 GhidraScriptUtil.getProvider(source_file) 找到对应 provider，用 StringWriter 包住标准输出/错误，支持把脚本的 print 捕获回 Python 字符串。
• pyghidra.transaction(program, description="Unnamed Transaction")：事务上下文管理器，进入时 startTransaction、退出时按是否异常决定 endTransaction(id, success)，异常时自动回滚语义由 Ghidra 保证。
• pyghidra.analysis_properties(program) / program_info(program)：便捷获取 Program.ANALYSIS_PROPERTIES 与 Program.PROGRAM_INFO 选项；前者会先调用 AutoAnalysisManager.initializeOptions() 以确保分析属性表完整（3.0.2 修复过这里拿不全属性的问题）。
• pyghidra.program_loader()：返回 ProgramLoader.Builder，支持链式 .project(...) / .source(...) / .language(...) / .loaders(...) 等配置。
• pyghidra.task_monitor(timeout=None)：不带 timeout 时返回 TaskMonitor.DUMMY（不阻塞、不可取消）；带秒数时返回 PyGhidraTaskMonitor.java 实现的超时自动取消监视器。
• pyghidra.walk_project(project, callback, start="/", file_filter=...)：遍历项目内每个 domain file 并回调，基于 ProjectDataUtils.descendantFiles 递归。
• pyghidra.walk_programs(project, callback, start="/", program_filter=...)：在 walk_project 基础上只处理程序、自动跳过非 Program 文件，回调签名为 (DomainFile, Program)。

官方完整示例

库 README 中的示例几乎覆盖了上述全部 API：

import os, jpype, pyghidra
pyghidra.start()

# 打开/创建一个项目
with pyghidra.open_project(os.environ["GHIDRA_PROJECT_DIR"], "ExampleProject", create=True) as project:

    # 遍历一个 Ghidra 发行版 zip 文件，加载所有 decompiler 二进制并保存进项目
    with pyghidra.open_filesystem(f"{os.environ['DOWNLOADS_DIR']}/ghidra_11.4_PUBLIC_20250620.zip") as fs:
        loader = pyghidra.program_loader().project(project)
        for f in fs.files(lambda f: "os/" in f.path and f.name.startswith("decompile")):
            loader = loader.source(f.getFSRL()).projectFolderPath("/" + f.parentFile.name)
            with loader.load() as load_results:
                load_results.save(pyghidra.task_monitor())

    # 最多 10 秒分析 windows 反编译器程序
    with pyghidra.program_context(project, "/win_x86_64/decompile.exe") as program:
        analysis_props = pyghidra.analysis_properties(program)
        with pyghidra.transaction(program):
            analysis_props.setBoolean("Non-Returning Functions - Discovered", False)
        analysis_log = pyghidra.analyze(program, pyghidra.task_monitor(10))
        program.save("Analyzed", pyghidra.task_monitor())

    # 遍历项目，给每个 decompiler 程序设置属性
    def set_property(domain_file, program):
        with pyghidra.transaction(program):
            program_info = pyghidra.program_info(program)
            program_info.setString("PyGhidra Property", "Set by PyGhidra!")
        program.save("Setting property", pyghidra.task_monitor())
    pyghidra.walk_programs(project, set_property, program_filter=lambda f, p: p.name.startswith("decompile"))

    # 把一段字节作为新程序加载
    ByteArrayCls = jpype.JArray(jpype.JByte)
    my_bytes = ByteArrayCls(b"\xaa\xbb\xcc\xdd\xee\xff")
    loader = pyghidra.program_loader().project(project).source(my_bytes).name("my_bytes")
    loader = loader.loaders("BinaryLoader").language("DATA:LE:64:default")
    with loader.load() as load_results:
        load_results.save(pyghidra.task_monitor())

    # 运行一个 GhidraScript
    pyghidra.ghidra_script(f"{os.environ['GHIDRA_SCRIPTS_DIR']}/HelloWorldScript.java", project)

遗留 API（已弃用）

pyghidra.open_program() 与 pyghidra.run_script() 仍可用但已被 typing_extensions.deprecated 标记弃用（见 core.py 中 from typing_extensions import deprecated）：

• open_program(binary_path, ...)：一步完成“建项目 + 导入二进制 + （默认）分析”，返回 FlatProgramAPI 上下文管理器；可指定 language / compiler / loader / project_name / project_location / analyze=False 等；nested_project_location=True 是保持旧版布局兼容的默认值（Ghidra GUI 创建的项目是平铺布局，可用 False 打开）。
• run_script(binary_path, script_path, ...)：直接在原生 CPython 中对二进制跑一个已有的 Ghidra 脚本；由于 Jython 2 与 CPython 3/JPype 的差异，个别脚本可能需要少量修改。命令行等价形式：pyghidra C:\input.exe C:\some_ghidra_script.py <传给脚本的 CLI 参数>。

JVM 启动机制：PyGhidraLauncher 家族

pyghidra.start() 背后是 launcher.py 中的 PyGhidraLauncher 基类及其三个子类，README 中记录的 add_classpaths() / add_vmargs() / add_class_files() / start() 接口都定义于此：

• add_classpaths(*args)：JVM 启动前追加 classpath 条目；
• add_vmargs(*args)：追加 JVM 参数；
• add_class_files(*args)：在 Ghidra 完全加载后再注入 classpath，保证依赖 Ghidra 类的类能正确加载；
• start(**jpype_kwargs)：幂等启动（jpype.isJVMStarted() 为真直接返回），先 check_ghidra_version() 校验版本，再 _setup_java() → _pre_launch_init() → _launch()。

三个子类对应三种使用场景：

class HeadlessPyGhidraLauncher(PyGhidraLauncher):   # 无头模式：Application.initializeApplication + HeadlessGhidraApplicationConfiguration
class DeferredPyGhidraLauncher(PyGhidraLauncher):  # 延迟初始化：先起 JVM，之后显式调用 initialize_ghidra(headless=True/False)
class GuiPyGhidraLauncher(PyGhidraLauncher):        # GUI 模式：在新 Java 线程里跑 Ghidra.main，并用 shutdown hook 等待退出

从源码看启动过程中的几个关键细节：

1. JVM 参数来源：_jvm_args() 从 support/launch.properties 中解析 VMARGS=（以及平台后缀变体，如 VMARGS_LINUX=），同时注入 -Dpyghidra.sys.prefix / -Dpyghidra.sys.executable 让 Java 侧知道当前 Python 解释器位置。
2. JAVA 定位：java_home 属性会优先尝试 JAVA_HOME_OVERRIDE（环境变量或 launch.properties 中的行），否则实际执行 java -version 探测（因为 macOS 的 PATH 上有桩 java），失败则回退 JAVA_HOME，最后通过 LaunchSupport ... -jdk_home -save 得到 JDK 路径。
3. 字符串转换：_setup_java() 强制 jpype_kwargs['convertStrings'] = True，这是 PyGhidra 把 Java String 自动转为 Python str 的机制（即库 README 推荐的 java-stubs-converted-strings 存根所假设的行为）。
4. 调试开关：设置 PYGHIDRA_DEBUG 环境变量会在 vmargs 头部插入 -agentlib:jdwp=...address=127.0.0.1:18001，可用远程调试器附着到 Ghidra 进程；库还提供了 pyghidra.debug_callback 装饰器，用于给“从 Java 线程调用的函数”挂 pydevd.settrace。
5. 导入钩子：_PyGhidraImportLoader 与 _GhidraBundleFinder 被挂到 sys.meta_path——前者处理 Python/Java 包名冲突（下划线方案），后者让 Ghidra “Bundle Manager”里的 Python 模块可被导入。

README 给出的自定义 JVM 配置示例：

from pyghidra.launcher import HeadlessPyGhidraLauncher

launcher = HeadlessPyGhidraLauncher()
launcher.add_classpaths("log4j-core-2.17.1.jar", "log4j-api-2.17.1.jar")
launcher.add_vmargs("-Dlog4j2.formatMsgNoLookups=true")
launcher.start()

GUI 集成：解释器插件与 CPython 脚本提供者

PyGhidraPlugin：交互式解释器

PyGhidraPlugin.java 是 ProgramPlugin 子类，注解声明它属于 CorePluginPackage、COMMON 分类，短描述为 “PyGhidra Interpreter”，并且依赖 InterpreterPanelService（servicesRequired）。插件持有一个 InterpreterGhidraScript 实例（interpreter/InterpreterGhidraScript.java），并在 programActivated() / locationChanged() / selectionChanged() / highlightChanged() 等回调中把当前程序、地址、选区、高亮同步给脚本上下文——这就是 GUI 解释器里能直接用 currentProgram、currentSelection 等脚本变量与代码视图联动的原理。

PyGhidraPlugin.setInitializer(Consumer) 是留给 Python 侧的内部钩子：Python 初始化完成后通过它把自己注册为初始化器，init() 时用它构造 interpreter/PyGhidraInterpreter.java（负责启动 CPython 子进程/控制台，配套还有 PyGhidraConsole.java、ResetAction.java、CancelAction.java）。

PyGhidraScriptProvider：让 .py 脚本用原生 CPython 3 跑

PyGhidraScriptProvider.java 继承 AbstractPythonScriptProvider，关键点有二：

1. 优先级：@ExtensionPointProperties(priority = 1000) 的注释写明“Enforce high priority so PyGhidra is the default Python provider”——从源码结构看，高优先级意味着原生 CPython 3 提供者默认压过 Jython 提供者成为 .py GhidraScript 的执行器。
2. 脚本实例化：getScriptInstance() 根据 SystemUtilities.isInHeadlessMode() 分别创建 PyGhidraHeadlessScript（继承 HeadlessScript）或 PyGhidraGhidraScript（继承 GhidraScript）；两者的 run() 都只是把 this 交给 Python 侧注册的 scriptRunner 回调真正执行。若 JVM 不是以 PyGhidra 方式启动（scriptRunner == null），会抛出 “Ghidra was not started with PyGhidra. Python is not available”。
3. 字段暴露：两个内部脚本类都通过 @ExposedFields 注解（配合 PythonFieldExposer.java 和 MethodHandles.Lookup）把 currentProgram、currentLocation、currentSelection、currentHighlight、monitor、writer、state 等 protected 字段暴露给 Python，使得 CPython 脚本能像 Java GhidraScript 一样访问这些上下文。异常处理上，PyGhidraGhidraScript.run() 特意不再包装 Java 侧捕获到的 PyExceptionProxy，以避免 Python 丢失原始 BaseException（3.2.0 的修复点）。

properties 子包（property/JavaPropertyFactory.java 等一组 *JavaProperty）则负责把 Java 对象属性以 Python 化属性风格暴露，是“像操作 Python 对象一样操作 Java 对象”体验的一部分。

启动脚本 pyghidra_launcher.py：venv 与 externally-managed 的自动处理

support/pyghidra_launcher.py 是模块 README 声明的第四项能力：Ghidra 用它来安装并启动 PyGhidra。它的命令行接口为：

pyghidra_launcher.py <install dir> [--console] [--dev] [-H | --headless]

其中 --headless 会强制控制台模式；--dev 表示开发模式（使用源码树的 Ghidra/RuntimeScripts/support/launch.properties 和 build/venv 开发虚拟环境，venv 不存在时会提示 Run "gradle prepPyGhidra"）。

从源码看它的完整工作流：

1. 找 Python：find_supported_python_exe() 依次尝试（a）上次保存的解释器（python_command.save，位于用户设置目录）、（b）application.properties 中 application.python.supported 声明的版本（构造 python3.14、py -3.14 等候选命令并执行 sys.version_info 探测）、（c）兜底的 python3 / python / py。当前仓库的配置为 3.14, 3.13, 3.12, 3.11, 3.10, 3.9。
2. 确定执行环境，按优先级：
   • 已在某个虚拟环境中 → 直接用该环境；
   • Ghidra 用户设置目录下的 venv 已存在 → 切换到它；
   • 检测到 externally-managed（stdlib/EXTERNALLY-MANAGED 标记文件，兼容 Python 3.9 的私有 API sysconfig._get_default_scheme 与 3.10+ 的公开 API）→ 自动在用户设置目录创建并使用 Ghidra venv；
   • 其余情况交互式询问：是否安装 PyGhidra、是否新建 Ghidra 虚拟环境（要求 ensurepip 可用）、是否允许装进系统环境。
3. 安装/升级：以 python -m pip install --no-index -f <install_dir>/Ghidra/Features/PyGhidra/pypkg/dist pyghidra 安装（离线，使用发行版内置 wheel）；若已安装且内置 wheel 版本更新，则询问是否升级——但在 externally-managed 环境中拒绝自动升级并提示。
4. 启动 PyGhidra：
   • headless：<python> -m pyghidra.ghidra_launch --install-dir <dir> ghidra.app.util.headless.AnalyzeHeadless；
   • 常规：<python> -m pyghidra -g --install-dir <dir>；
   • --console 时用 subprocess.call（阻塞、输出可见），否则 subprocess.Popen 并 CREATE_NO_WINDOW（Windows 上不弹控制台窗口）。

用户设置目录的推导（get_user_settings_dir()）也值得一读：它从 application.properties 组装 app_name_version_releasename，尊重 launch.properties 中的 VMARGS=-Dapplication.settingsdir= 覆盖，其次 XDG_CONFIG_HOME，最后按平台回退到 %APPDATA% / ~/Library / ~/.config。

命令行入口：pyghidra 命令

pyproject.toml 的 [project.scripts] 注册了 pyghidra = "pyghidra.__main__:main"（另有 GUI 变体 pyghidraw = "pyghidra.gui:_gui"）。main.py 中定义的参数如下：

参数	说明
-v, --verbose	初始化 Ghidra 时输出详细 JVM 日志
-d, --debug	日志级别设为 DEBUG
-g, --gui	启动 Ghidra GUI
--install-dir	Ghidra 安装路径（默认 GHIDRA_INSTALL_DIR 环境变量）
--skip-analysis	加载二进制后跳过自动分析
binary_path（位置参数）	可选的二进制文件
script_path（位置参数）	headless 脚本路径，必须 .py 结尾；不给出脚本则进入 REPL
--project-name	项目名称（默认二进制文件名加 _ghidra 后缀）
--project-path	项目存放位置（默认二进制所在目录）
-D <prop> / -X <arg>	原样转发给 JVM
script_args	脚本路径之后的剩余参数，全部传给脚本

运行行为三分支（PyGhidraArgs.func()）：给了 --gui 走 GUI 启动；给了 script_path 则以 HeadlessPyGhidraLauncher 启动后调 run_script()（支持 Ctrl+C 优雅退出）；只给 binary_path 则打开该二进制后进入针对它的交互式 REPL（_interpreter(api)，banner 显示 Ghidra 与 Python 版本）；什么都没给则进入纯 REPL。

Python 与 Java 包名冲突：下划线后缀方案

当 Python 模块与 Java 包 import 路径同名时（经典例子是 Python 标准库 pdb 与 Ghidra 的 pdb 包），Python 模块优先；PyGhidra 的 _PyGhidraImportLoader（sys.meta_path 钩子）自动提供“包名加下划线”的访问方式：

import pdb   # 导入 Python 的 pdb
import pdb_  # 导入 Ghidra 的 pdb

该 loader 仅在 JVM 已启动、且去掉末尾 _ 后是 Java 包时返回模块规范，因此不会干扰正常 Python 导入。

3.2.0 版本的关键改进（对照源码）

对照 库 README 的 Change History 3.2.0 条目与当前源码，可以确认这些行为：

• 未捕获的 JException 会输出完整 Java 堆栈：_pyghidra_excepthook 在标准 excepthook 之外额外写入 exc_value.stacktrace()；
• GhidraScript 抛出的原始异常对象不再被吞掉：PyGhidraGhidraScript.run() 直接 throw e 保留 PyExceptionProxy；
• JPype 依赖放宽为 >=1.5.2, !=1.6.0, !=1.7.0（pyproject.toml 已体现）；
• open_program() / run_script() 通过 typing_extensions.deprecated 正式标记弃用（core.py 已体现）；
• 脚本运行后默认恢复 sys.modules，可用 Java 系统属性 pyghidra.sys.modules.restore.disable=true（写在 support/launch.properties）关闭该默认行为（3.1.0 引入）。

小结：关键文件索引

内容	路径
模块 README（本文主体文档）	Ghidra/Features/PyGhidra/README.md
Python 库完整 API 文档与示例	Ghidra/Features/PyGhidra/src/main/py/README.md
库打包配置（依赖与入口点）	Ghidra/Features/PyGhidra/src/main/py/pyproject.toml
核心 API 实现	Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/api.py
Launcher 家族实现	Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/launcher.py
命令行入口	Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/main.py
遗留 API（open_program/run_script）	Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/core.py
GUI 解释器插件	Ghidra/Features/PyGhidra/src/main/java/ghidra/pyghidra/PyGhidraPlugin.java
CPython 3 脚本提供者	Ghidra/Features/PyGhidra/src/main/java/ghidra/pyghidra/PyGhidraScriptProvider.java
venv/externally-managed 启动脚本	Ghidra/Features/PyGhidra/support/pyghidra_launcher.py
支持 Python 版本声明	Ghidra/application.properties

总体而言，PyGhidra 的价值在于把“Ghidra 逆向分析”从一个 GUI 工作流变成一个可编程的 Python 环境：headless 脚本批处理、独立于 Ghidra 的 Python 工具链、GUI 内交互式调试三者共用同一套 API，而 JVM 生命周期、Python 环境、插件装载这些脏活由 launcher 与启动脚本自动处理。