Kiln 跨平台 spawn 沙箱发布检查清单:macOS / Windows / Linux 与 PyInstaller 冻结构建验证指南

原创2026-10-14 13:06:201,618 阅读
文章标签:人工智能AI 应用大模型模型评测提示工程微调RAGAI Agent数据标注数据增强LLMOps本地部署桌面应用

Kiln 跨平台 spawn 沙箱发布检查清单:macOS / Windows / Linux 与 PyInstaller 冻结构建验证指南

导读

本文围绕 Kiln 仓库中 code_tools 项目的跨平台 spawn 检查清单,系统讲解 Kiln 代码工具(code tools)与代码评测(code evals)共享的多进程 spawn 基础设施:进程级 _spawn_lock、__main__ 轻量桩替换、同步/异步入口点统一调用,以及 macOS 已验证、Windows 与 Linux 待验证的三平台发布流程。读完本文,你将掌握 Kiln 沙箱执行的底层原理,并能照章完成 PyInstaller 冻结构建在各平台的发布前验证,规避 PyInstaller bug #7410 等已知陷阱。

一、背景:为什么 code tools 与 code evals 必须共享同一套 spawn 基础设施

在 Kiln 中,代码工具(code tools) 和 代码评测(code evals) 是两类核心能力:

  • code tools:用户编写 Python 代码作为工具(实现一个 def run()),供 Agent 在任务中调用,由 PythonCodeTool 负责在沙箱子进程中执行;
  • code evals:用户编写打分器(实现 def score()),对模型输出进行评估,由 v2_eval_code_eval 适配器 负责执行。

两者虽然职责不同,但共享同一套多进程 spawn 基础设施,即 spawn.py。这正是该检查清单存在的根本原因:任何一个发布版本只要包含 code tools 或 code evals,就必须在目标平台上验证这套共享设施。

从源码结构看,这种共享是刻意设计的:kiln_ai.sandbox 模块被设计为 stdlib-only(只依赖 Python 标准库,不引入 Pydantic、数据库、UI 等重依赖),因此子进程可以轻量启动。检查清单在发布前需要逐平台确认的,正是这套共享设施在 macOS、Windows、Linux 以及 PyInstaller 冻结构建下的正确性。

二、共享基础设施四要素(源码级解析)

检查清单开篇列举了四项共享基础设施,全部位于 libs/core/kiln_ai/sandbox/ 目录。下面结合源码逐一深入。

2.1 _spawn_lock:进程级全局锁,对抗 PyInstaller bug #7410

spawn.py 中定义:

_spawn_lock = threading.Lock()

这是一把进程级全局锁,由 code-evals(run_scorer)和 code tools(PythonCodeTool)共同持有。两个功能路径最终都通过 run_bridged_child 发起 spawn,并在其中调用 start_process_with_light_main,从而串行化 p.start() 前后的 __main__ 桩替换窗口。

为什么必须共用同一把锁?PyInstaller bug #7410 是并发 spawn 导致的崩溃:在冻结构建中,多个进程同时启动时可能出现竞态。锁的共享性由测试 test_sandbox_shared.py 中的 TestSpawnLockIdentity 显式断言:

def test_spawn_lock_shared_with_eval(self):
    """Code evals and code tools share the same _spawn_lock (PyInstaller #7410)."""
    assert spawn_mod._spawn_lock is _spawn_lock

def test_bridge_delegates_to_shared_spawn_helper(self):
    """The shared bridge spawns via start_process_with_light_main from sandbox.spawn."""
    assert sandbox_bridge.start_process_with_light_main is start_process_with_light_main

test_code_eval_bridge.py 中也有同样的同源性断言(code_tool.run_bridged_child is sandbox_bridge.run_bridged_child、v2_eval_code_eval.run_bridged_child is sandbox_bridge.run_bridged_child),确保两条调用链解析到同一个共享实现。

2.2 start_process_with_light_main:__main__ 轻量桩替换

spawn.py 中的 start_process_with_light_main(p) 是这套基础设施的技术核心。其原理是:

  1. Python 的 multiprocessing.spawn.get_preparation_data 会读取 sys.modules["__main__"],决定子进程需要重新执行什么;
  2. 若不处理,子进程会重新导入父进程沉重的 __main__ 模块——例如 desktop.py 会传递引入 litellm、google-cloud 等重依赖,导致子进程启动缓慢甚至失败;
  3. 该函数在 p.start() 之前,将 sys.modules["__main__"] 替换为一个轻量桩模块(types.ModuleType("__main__"),不带 __file__、不带 __spec__),于是 init_main_from_name 与 init_main_from_path 都不会被触发,子进程完全跳过重型重新导入;p.start() 结束后在 finally 中恢复真实主模块。

实现中有三个值得注意的细节:

  • 桩模块命名为 "__main__" 而非 "__mp_main__"——后者会与 multiprocessing 内部主模块名冲突;
  • 桩替换发生在 multiprocessing.spawn 现有的 bootstrap 流程之内,因此 freeze_support() 与 PyInstaller 冻结构建继续正常工作;
  • 线程安全上,替换窗口是进程级的,但只有亚毫秒级(仅覆盖 p.start()),且被 _spawn_lock 串行化,而请求处理代码不读取 __main__,因此跨线程可见性是无害的。

2.3 call_entrypoint:同步 / 异步入口点统一处理

entrypoint.py 中的 call_entrypoint(fn, kwargs) 同时处理同步与异步入口点:

def call_entrypoint(fn: Callable, kwargs: dict) -> Any:
    result = fn(**kwargs)
    if inspect.iscoroutine(result):
        result = asyncio.run(result)
    return result

如果 fn 是普通函数,返回值原样返回;如果 fn 是 async def(或任何原因返回协程),则用 asyncio.run() 在子进程主线程中驱动协程完成。该函数被 code-eval 打分器和 code-tool 的 run() 入口点共用。

test_sandbox_shared.py 的 TestCallEntrypoint 对同步、异步、asyncio.gather、异常传播等路径做了完整覆盖——包括 asyncio.run() 嵌套调用会报错的约束测试。

2.4 spawn 上下文:显式 get_context("spawn"),绝不用 fork

子进程使用 multiprocessing.get_context("spawn") 显式创建(绝不用 fork),并设置 daemon=True。这一要求在实际代码中有两处体现:

  • sandbox_bridge.py 在 run_bridged_child 中用 spawn 上下文创建两条 IPC 队列;
  • sandbox_bridge.py 在 _pump 中用 ctx.Process(target=..., daemon=True) 创建子进程,并通过 loop.run_in_executor(executor, start_process_with_light_main, p) 在专用线程池中启动。

为什么必须在 Linux 上显式指定 spawn?fork 在存在多线程的应用中不安全(可能死锁),而 spawn 在三个平台上行为一致。从代码结构看,daemon=True 保证了子进程随应用退出而结束,避免僵尸进程泄漏。

三、macOS:已验证(2026-07-05)

检查清单明确标注:macOS 已在本机验证(2026-07-05)。验证方式是在该平台上完整运行测试套件,包括 test_code_tool_execution.py、test_sandbox_shared.py 以及 code-eval 套件,确认了以下能力:

验证项 对应源码/测试
同步与异步 run() 入口点 TestChildSyncRun / TestChildAsyncRun(test_code_tool_execution.py)
嵌套工具调用(IPC 队列) ToolCallBridge(tools_api.py)
超时与崩溃处理 _pump 中的 deadline、p.kill()、BridgeResult(timed_out/crashed)
_spawn_lock 下的并发 spawn TestSpawnLockIdentity
stdout/stderr 捕获 worker.py 的 io.StringIO 重定向
返回值序列化 _serialize_result(str 直传,JSON 类型 json.dumps,其余报错)

关于返回值序列化,worker.py 的规则是:str 原样传递;dict/list/int/float/bool/None 通过 json.dumps(ensure_ascii=False)序列化;其他类型抛出明确的 TypeError。

四、Windows:发布前必须验证

Windows 目前是待验证状态([ ] Must verify before release),核心关注点有三:

1. freeze_support() 必须先于任何 spawn 进程创建执行

multiprocessing.freeze_support() 在应用入口点中被调用。检查清单中给出的位置是 desktop.py(原记 line 186)与 dev_server.py(原记 line 25);以当前仓库源码为准,实际位置分别是:

  • desktop.py:__main__ 中先调用 multiprocessing.freeze_support(),紧接着 multiprocessing.set_start_method("spawn", force=True);
  • dev_server.py:同样的两行调用。

关键约束:code tools 自身不调用 freeze_support(),它们依赖应用入口点已经调用过。没有 freeze_support(),Windows 上 PyInstaller 冻结的可执行文件使用 multiprocessing 会陷入无限循环。此外 set_start_method("spawn", force=True) 强制所有平台使用 spawn(Windows/macOS 本就默认 spawn,Linux 上 fork 是默认且不安全)。

2. start_process_with_light_main 保持在 spawn bootstrap 内

由于 __main__ 桩替换发生在 multiprocessing.spawn 现有的 bootstrap 流程内部,freeze_support() 的兼容性不受影响。这一点在 spawn.py 的 docstring 中明确说明,并在 test_sandbox_bridge.py 的桥接池测试中通过录制 run_in_executor 提交来断言("start_process_with_light_main" in submitted)。

3. PyInstaller 冻结构建验证

需要在 Windows 构建机上验证 PyInstaller 冻结构建能否为 code tools spawn 子进程(与 code-evals 相同的验证标准),并确认 _spawn_lock 能防止 Windows 下 PyInstaller 的并发 spawn 问题。

五、Linux:发布前必须验证

Linux 同样是待验证状态([ ] Must verify before release),核心关注点:

  • 与 Windows 相同的 freeze_support() 与 _spawn_lock 要求;
  • PyInstaller bug #7410(并发 spawn 崩溃)最初就是在 Linux 上报告的——因此 Linux 是 _spawn_lock 最关键的平台;
  • 验证 __main__ 桩替换在 Linux 冻结构建中工作正常。

仓库中还保留了一个专门的回归基准 _heavy_main_bench.py:其 docstring 明确指出"这正是该基准要捕获的 bug——打分器现在通过 run_bridged_child spawn……以保留修复"。基准入口同样先调用 multiprocessing.freeze_support()(见该文件第 75 行),可用于在 Linux 上复现/回归 PyInstaller #7410 场景。

六、冻结构建(PyInstaller)逐平台验证流程

检查清单为 macOS、Windows、Linux 三个平台给出了统一的六步验证流程,每一步对应一个已实现的机制:

  1. 用 PyInstaller 构建冻结应用——验证构建产物本身可启动;
  2. 启动应用并创建一个简单的 def run() 返回字符串的 code tool——对应 TestChildSyncRun.test_sync_run_returns_string('def run(x):\n return "hello " + x\n');
  3. 从 UI 测试面板测试该 code tool——验证完整 UI → API → sandbox 链路;
  4. 创建一个调用其他工具(例如演示用数学工具)的 code tool 并测试——这一步专门验证嵌套工具调用 IPC 层(通过两条队列 requests/responses 实现 tool_call/list_tools 消息往返,见 tools_api.py 的 ToolCallBridge);
  5. 验证 code-evals 仍然工作——共享 _spawn_lock 的回归检查(对应 TestSpawnLockIdentity 的同一性断言);
  6. 尽可能并发运行两个测试——验证 spawn 锁正确串行化 p.start()。

其中第 4 步是 code tools 相对 code-evals 的新增核心验证点:code-evals 的冻结构建验证已经覆盖了大部分 spawn 基础设施,code tools 在其上叠加了嵌套工具调用 IPC 层,这是需要重点验证的新东西。

七、附注:stdout/stderr 重定向的"一石二鸟"

检查清单的 Notes 部分提到:stdout/stderr 在子进程中被重定向到 StringIO。这在两个层面发挥作用:

  1. 捕获用户输出:worker.py(code tools)与 sandbox_worker.py(code evals)在进入用户代码前将 sys.stdout/sys.stderr 换成 io.StringIO(),结束后恢复,输出随结果消息一起回传,且超过 64 KB 会被截断(_TRUNCATION_LIMIT = 64 * 1024);
  2. None-stdout 防护:在 PyInstaller --windowed 构建中(macOS .app 和 Windows GUI 构建),sys.stdout 可能是 None,用户代码一旦打印就会崩溃。提前重定向恰好规避了这个问题。

call_entrypoint、child_main/execute_scorer_bridged 所在的三个沙箱模块全部保持 stdlib-only,这是子进程能够轻量、安全启动的前提。

八、完整执行链路速览

综合源码,一次 code tool 调用的完整链路是:

PythonCodeTool.run()
  → _invoke(): 构建 NestedToolServer(allowlist、project、task、recorder)
  → run_bridged_child(): 深度上限检查(>=10 直接报错,不 spawn)
      → 深度 0 时获取共享信号量(CODE_SANDBOX_MAX_CONCURRENCY = 16)
      → get_context("spawn") 创建两条队列
      → _pump(): ctx.Process(daemon=True)
          → start_process_with_light_main(p)(_spawn_lock + __main__ 桩替换)
          → 轮询 requests 队列,tool_call/list_tools 分发给 NestedToolServer
          → 超时 p.kill(),崩溃返回 exit_code
  → 子进程 child_main(): exec(code) → run() → call_entrypoint()
      → ToolCallBridge 通过两条队列完成嵌套工具调用

相关实现位于 code_tool.py、sandbox_bridge.py、spawn.py、worker.py。Code eval 侧则走 v2_eval_code_eval.py → 同样的 run_bridged_child → execute_scorer_bridged,共享同一把锁、同一个桥、同一个并发池。

九、测试与验证资源索引

发布前可重点复用的测试与基准:

  • test_code_tool_execution.py:code tool 执行引擎全量测试(真实 spawn 子进程),覆盖同步/异步、超时、崩溃、嵌套调用、并发;
  • test_sandbox_shared.py:共享基础设施测试——_spawn_lock 同一性、桥委托关系、call_entrypoint 同步/异步路径、打分器走共享桥的回归;
  • test_sandbox_bridge.py:桥接池行为测试,断言 spawn/poll/join 都发生在专用 kiln-sandbox-bridge 线程池而非默认执行器上;
  • test_code_eval_bridge.py:code tool 与 code eval 解析到同一 run_bridged_child 与同一 start_process_with_light_main 的引用同一性测试;
  • _heavy_main_bench.py:针对 PyInstaller #7410 的回归基准(含 freeze_support() 调用)。

在 Windows 与 Linux 构建机上,建议以"完整测试套件 + 上述六步冻结构建验证"双轨并行,待两项全部通过后再发布包含 code tools / code evals 的版本。

登录后查看全文
Kiln