@agentskillmania/build-micro-python-wasi

用于构建 WASI Preview2 版本 MicroPython 的 CLI 工具。

English | 功能与限制

这是什么？

本 CLI 工具将 MicroPython (v1.27.0) 构建为 WASI Preview2 版本，使其可在 WASM 沙箱环境中运行。

WASI 与官方 WebAssembly 移植版的区别

| 特性 | WASI 版本 (本工具) | WebAssembly 版本 (官方) | | ---------- | ------------------------- | ------------------------------- | | 目标运行时 | wasmtime、wasmer (服务端) | 浏览器、Node.js | | 编译器 | wasi-sdk | Emscripten | | 网络支持 | 原生 TCP 套接字 | 无套接字 (仅 JS FFI) | | 使用场景 | 服务端 WASM、CLI 工具 | 浏览器集成 | | 平台标识 | sys.platform == "wasi" | sys.platform == "webassembly" |

何时使用本 WASI 版本：

• 需要 TCP 套接字网络
• 构建服务端 WASM 应用
• 在沙箱 CLI 环境中运行 Python

何时使用官方版本：

• 在浏览器中运行 Python
• 需要 JavaScript 互操作

环境要求

| 组件 | 测试版本 | 说明 | | -------- | --------- | ---------------- | | Node.js | >= 16.0.0 | 运行 CLI 工具 | | WASI SDK | 22.0 | 将 C 编译为 WASM | | wasmtime | 43.0.0 | 运行 WASM | | Git | 任意 | 下载 MicroPython | | Python | 3.x | 构建系统 |

安装 WASI SDK：

curl -LO https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-22/wasi-sdk-22.0-linux.tar.gz
tar xzf wasi-sdk-22.0-linux.tar.gz
sudo mv wasi-sdk-22.0 /opt/wasi-sdk
export WASI_SDK_PATH=/opt/wasi-sdk

安装 wasmtime：

curl https://wasmtime.dev/install.sh -sSf | bash

安装

npm install -g @agentskillmania/build-micro-python-wasi

或不安装直接使用：

npx @agentskillmania/build-micro-python-wasi <命令>

CLI 命令

validate-env

检查所有依赖是否正确安装。

npx @agentskillmania/build-micro-python-wasi validate-env

检查项：

• Node.js 版本
• WASI SDK 安装
• wasmtime 安装
• Git 和 Python 可用性

download <tag>

下载 MicroPython 源码。

npx @agentskillmania/build-micro-python-wasi download v1.27.0

# 使用镜像（下载更快）
npx @agentskillmania/build-micro-python-wasi download v1.27.0 --mirror https://gh.llkk.cc/

inject-port

将 WASI 移植文件复制到 MicroPython 源码目录。

cd micropython
npx @agentskillmania/build-micro-python-wasi inject-port --target=wasi

此命令创建 ports/wasi/ 目录，包含构建配置。

remove-inject-port

移除已注入的移植文件。

npx @agentskillmania/build-micro-python-wasi remove-inject-port

build

编译 MicroPython 为 WASM。

npx @agentskillmania/build-micro-python-wasi build --target=wasi

# 使用更多并行任务
npx @agentskillmania/build-micro-python-wasi build --target=wasi --jobs=8

输出：ports/wasi/build/micropython.wasm (~954KB)

快速开始

# 1. 检查环境
npx @agentskillmania/build-micro-python-wasi validate-env

# 2. 下载源码
mkdir my-project && cd my-project
npx @agentskillmania/build-micro-python-wasi download v1.27.0

# 3. 注入移植文件
cd micropython
npx @agentskillmania/build-micro-python-wasi inject-port --target=wasi

# 4. 构建
npx @agentskillmania/build-micro-python-wasi build --target=wasi

# 5. 运行
wasmtime run -W exceptions=y -S tcp=y \
  ports/wasi/build/micropython.wasm 'print("Hello, WASM!")'

常见问题

子模块更新卡住： 按 Ctrl+C 跳过（构建不需要）。

版本不匹配： 仅测试过 WASI SDK 32.0 和 wasmtime 43.0.0，其他版本可能不工作。

许可证

MIT - 详见 LICENSE 文件