AMC-WebUI浏览器Python沙箱内幕：Pyodide WASM、Web Worker与按需安装包机制详解

AMC-WebUI浏览器Python沙箱内幕Pyodide WASM、Web Worker与按需安装包机制详解【免费下载链接】AMC-WebUI面向 Gemini 的 Local-First AI 工作流 WebUI集成多模态聊天、Canvas、文件处理、实时搜索、代码执行与高级推理。项目地址: https://gitcode.com/gh_mirrors/al/AMC-WebUIAMC-WebUI 是一款面向 Gemini 的 Local-First AI 工作流 WebUI其中的浏览器 Python 沙箱让你无需任何服务器就能在浏览器内执行 Python 代码它基于 PyodideWASM 版 CPython在 Web Worker 中运行支持数据分析、CSV 处理和 Matplotlib 绘图且代码不离开你的设备。本文深入剖析这套沙箱的三大核心机制——Pyodide WASM 运行时、Web Worker 线程隔离、按需安装包加载并带你读完全部关键源码。为什么要在浏览器里跑 Python大多数 AI 聊天工具的代码执行发生在云端沙箱如 Gemini 的服务端 Code Execution代码会经过服务器。AMC-WebUI 走的是 Local-First 路线Python 代码直接在你的浏览器进程内执行敏感数据CSV、个人信息、私有文件永不离开本机。实现这一点的钥匙是Pyodide——用 WebAssembly 编译的完整 CPython 解释器附带一个浏览器虚拟文件系统Emscripten FS可以直接import pandas。架构总览主线程、Worker 与 WASM 三层结构整套沙箱分布在三个层级源码集中在src/features/local-python/目录层级文件职责请求编排pyodideService.tsWorker 生命周期、请求队列、超时与中止沙箱执行pyodideWorkerTemplate.tsPyodide 初始化、代码执行、输出收集UI 状态usePyodide.tsReact Hook 与结果 LRU 缓存Web Worker 隔离不卡顿的秘诀WASM 执行 Python 是 CPU 密集型的如果在主线程运行整个页面会冻结。AMC-WebUI 的做法动态生成 Worker 脚本。Worker 代码是一段模板字符串运行时把 Pyodide 的 baseURL 替换进__PYODIDE_BASE_URL__占位符见 buildPyodideWorkerScript再打包成 Blob 创建 Worker——不需要在服务器里预置 Worker 文件。消息协议通信。主线程通过postMessage({ type: RUN_PYTHON, code, files })下发任务Worker 回传output / image / files / error二进制数据用 Transferable 的ArrayBuffer零拷贝转移dispatchToWorker。请求串行队列。多个代码块并发到达时排入队列顺序执行避免两个任务争抢同一解释器drain。延迟加载按需创建沙箱服务本身也是懒加载的loadPyodideService.ts 只在第一次真正执行代码时才动态import并创建 Worker。也就是说从未运行过 Python 的用户一个字节 WASM 都不会下载——这正是 Local-First 性能优化的关键。按需安装包机制import 什么装什么Pyodide 的按需安装分两级第一级预加载核心栈。Worker 启动时一次性加载micropip、pandas、numpy、matplotlib四个包loadPyodideAndPackages覆盖 90% 的数据分析场景后续执行零等待。第二级AST 级动态补装。每段代码执行前沙箱调用await pyodide.loadPackagesFromImports(code);它不是简单的字符串匹配而是对代码做AST 解析找出所有 import 语句再对照 Pyodide lockfile 把缺失的包下载进沙箱已预装的包会自动去重。若代码引用了 Pyodide 不支持的包会被翻译成清晰的错误提示A requested dependency is not available in the browser Pyodide environmentinstallDependencies。 简单说import requests会触发 requests 的 WASM 版自动下载import json则什么都不做。执行流程隔离目录 → 代码运行 → 产物回传每次执行都被封装在一个一次性沙盒目录/tmp/local-python-{id}里注入输入文件用户此前上传的附件如 CSV写入目录Python 里用相对路径直接读取collectLocalPythonInputFiles 负责收集上下文文件。重定向标准输出setStdout / setStderr把print输出捕获成字符串。文件差分收集产物执行前后各做一次递归文件列表差集就是代码生成的新文件图表、CSV、HTML 等连同 MIME 类型一起回传。Matplotlib 特殊通道检测plt.get_fignums()有活跃图表就渲染成 PNG 单独回传在消息气泡里内联显示。彻底清理finally中关闭所有图、切回原目录、删除沙盒目录保证每次运行互相隔离Worker 主循环。生命周期管理超时、中止与预热 长驻 Worker 会白白占用几十 MB 内存AMC-WebUI 用一套状态机精细管理空闲回收5 分钟无请求后terminate()WorkerscheduleIdleReclaim执行超时单次运行 60 秒未完成即强制拆除 Worker中止即重建由于 Pyodide 无法干净地打断 C 扩展用户点停止时直接终止 Worker 并立即预热一个替补实例WARMUP消息让下一次执行跳过多 MB 的冷启动resetWorker结果 LRU 缓存usePyodide 最多缓存 24 条执行结果消息列表虚拟滚动滚出视野后图表结果依然秒回。如何启用本地 Python 沙箱在聊天设置中打开本地 Python开关即可。系统会向模型注册一个名为run_local_python的客户端工具clientFunctionTool.ts模型遇到计算、数据分析、画图类任务时会自动调用它执行发生在你的浏览器里。它与 Gemini 服务端代码执行互斥路由到第三方 API 或开启服务端执行时本地沙箱自动让位判断逻辑见 codeExecution.ts。关键源码索引 模块路径Worker 生命周期管理pyodideService.ts沙箱执行模板pyodideWorkerTemplate.ts懒加载入口loadPyodideService.tsUI 状态与缓存usePyodide.ts模型工具声明clientFunctionTool.ts运行模式判定codeExecution.ts一句话总结AMC-WebUI 用Blob 动态 Worker Pyodide WASM AST 按需装包三板斧把一台完整的 Python 数据分析工作站装进了浏览器标签页且性能、内存、隐私全部可控。【免费下载链接】AMC-WebUI面向 Gemini 的 Local-First AI 工作流 WebUI集成多模态聊天、Canvas、文件处理、实时搜索、代码执行与高级推理。项目地址: https://gitcode.com/gh_mirrors/al/AMC-WebUI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考