g4f-go：gpt4free 的自包含 Go 启动器，首运行时按需下载 CPython 运行时

本文基于 gpt4free 仓库中的 g4f-go/README.md 及其配套源码展开：g4f-go 是一个只有几 MB 的 Go 启动器，它不把 CPython 解释器嵌入二进制，而是在首次运行时根据 runtime.json 清单为当前操作系统/架构下载对应版本的 CPython、校验 sha256 并解压到用户目录，再把 g4f[slim] 安装进该解释器中运行——全程无需系统 Python。读完本文，你将理解它的清单设计、下载/校验/解压的完整链路、各平台（含 Android/Termux 的 dlopen C runner）差异、命令行用法以及构建发布方式。

一、设计定位：小二进制 + 首运行时下载

传统做法是把整个 CPython 运行时打进可执行文件，导致二进制动辄数百 MB。g4f-go 反其道而行：

• 二进制本身只嵌入一个很小的清单文件（runtime.json），其中固定（pin）了各平台 CPython 归档的 URL、字节大小和 sha256；
• 首次运行时，为宿主机 OS/arch 选中清单条目，下载归档到 ~/.g4f/python-embed/（Android 为应用私有目录），并打印基于 \r 的实时进度（百分比、字节数、吞吐、ETA）；
• 校验 sha256 后解压，引导 pip（ensurepip），向解释器安装 g4f[slim]，写入 .installed 戳文件，然后才执行你的命令；
• 之后的运行直接跳到第 3 步——运行时会缓存，直到固定版本变化。

这一设计的前提与收益在 g4f-go/main.go 中可以印证：runMain() 在任何用户命令（含 client、api 等透传命令）之前先调用 ensureRuntime()，保证解释器就绪后才进入命令分发。入口命令示例来自 README：

g4f-go client "What is gpt4free?"
g4f-go api --port 8080

二、运行时清单 runtime.json：按平台固定下载源

清单 g4f-go/runtime.json 是当前仓库中该功能的唯一事实来源，结构为：

{
  "version": 1,
  "python": "3.14.7",
  "pbs_tag": "20260805",
  "platforms": {
    "android":        { "kind": "android", "url": "https://www.python.org/ftp/python/3.14.7/python-3.14.7-aarch64-linux-android.tar.gz", "size": 22477276, "sha256": "" },
    "linux-x64":      { "kind": "pbs", "url": ".../cpython-3.14.7+20260805-x86_64-unknown-linux-gnu-install_only.tar.gz" },
    "linux-arm64":    { "kind": "pbs", "url": ".../cpython-3.14.7+20260805-aarch64-unknown-linux-gnu-install_only.tar.gz" },
    "windows-amd64":{ "kind": "pbs", "url": ".../cpython-3.14.7+20260805-x86_64-pc-windows-msvc-install_only.tar.gz" },
    "darwin-x64":   { "kind": "pbs", "url": ".../cpython-3.14.7+20260805-x86_64-apple-darwin-install_only.tar.gz" },
    "darwin-arm64": { "kind": "pbs", "url": ".../cpython-3.14.7+20260805-aarch64-apple-darwin-install_only.tar.gz" }
  }
}

（上表 URL 为示意截断，完整地址见仓库文件。）各字段的语义由 g4f-go/download.go 中的结构体定义确认：

字段	含义
kind	"pbs" 表示 python-build-standalone 的 install-only tarball；"android" 表示 python.org 官方 Android 包
arch	目标架构（amd64 / arm64 / any）
url	归档下载地址
size	固定字节大小，用于快速完整性判断（0 表示未 pin）
sha256	固定哈希，用于强校验（空串表示未 pin）

清单与二进制的绑定方式是 go:embed：g4f-go/manifest_embedded.go 通过 //go:embed runtime.json 把清单打进二进制，并在 init() 中立即解析校验，畸形清单会在启动时 panic 而不是延迟到首次下载才暴露。这也意味着构建二进制时完全不需要网络。

需要注意一个适用前提：当前仓库的 runtime.json 中，只有 android 条目 pin 了 size，各桌面平台的 size/sha256 仍为空（文件内注释明确要求发布前用 curl ... | sha256sum 重新 pin）。从源码看，verifyRuntime() 在 SHA256 为空时会直接放行（unpinned; trust size/transport），即未 pin 的条目只依赖文件大小与传输层保证——这是理解其完整性校验边界的关键。

清单的版本常量在 g4f-go/version.go 中维护：Version = "0.1.0"、PythonVer = "3.14.7"，注释要求升级 CPython 时保持两处同步。

三、首运行时做了什么：下载、校验、解压、打戳

3.1 平台识别与缓存

runtimeManifestKey()（g4f-go/download.go#L39-L59）把 runtime.GOOS/runtime.GOARCH 映射为清单键（linux-x64、linux-arm64、windows-amd64、darwin-x64/darwin-arm64、android）；找不到对应条目时直接报错 no runtime in manifest for platform。

下载前的缓存判断逻辑在 downloadRuntime()（g4f-go/download.go#L83-L151）：

• 若缓存文件已存在且大小 > 0：当清单 pin 了 size 时要求完全相等，否则视为不完整并重新下载；
• 下载期间先写入临时文件 .g4f-runtime/runtime.download，完成后原子 rename 为正式缓存名（runtime-<归档文件名>），避免半成品被当成缓存；
• 总字节数优先取 HTTP Content-Length，取不到再退回清单 size。

3.2 实时进度反馈

copyWithProgress()（g4f-go/download.go#L176-L216）以 256 KiB 缓冲区流式写入，并把进度输出节流到约每 200 ms 一次；progressLine() 用 \r 覆盖同一行打印 百分比 | 已下/总量 | 速率/s | eta。注释明确说明 http.Client 不设默认超时——“进度提示是让用户知情，而不是硬超时”。

3.3 解压与路径安全

extractRuntime()（g4f-go/download.go#L239-L362）负责把归档解到 binDir/python-home/：

1. 第一遍扫描确定归档的唯一顶层目录（如 python/、prefix/），第二遍解压时剥掉该前缀，使内容直接落在 python-home/（bin/...、lib/...），与启动器布局一致；
2. 对每个条目做 zip-slip 防护：.. 前缀路径或解析后跳出目标目录的条目直接拒绝（unsafe path in archive）；
3. 对 tar 中的符号链接按原样重建（如 libpython3.so -> libpython3.14.so）；若文件系统不支持符号链接，则回退为复制目标文件（best effort，见 copySymlinkTarget()）。

解压成功后写入戳文件 .g4f-runtime/.runtime-ok，下次运行即跳过解压（见 ensureRuntime()，g4f-go/download.go#L387-L444）。

3.4 首运行后的目录布局

按 README 与 installDir()（g4f-go/runtime.go#L29-L38），桌面平台布局如下：

~/.g4f/python-embed/
├── python-home/bin/python        # 解释器（pbs 布局）
├── python-home/lib/python3.14   # stdlib + site-packages（g4f 装在这里）
├── python                         # shell 包装器，设置 PYTHONHOME/PYTHONPATH
└── .g4f-runtime/
    ├── .runtime-ok                # 戳：下载+解压完成
    ├── .installed                 # 戳：g4f 已通过 pip 安装
    └── runtime-<归档名>           # 下载的归档缓存

固定安装到用户主目录有两个目的（源码注释原话）：保持可执行文件完全可重定位，并让同一台机器上的所有 g4f-go 版本共享一份运行时。

四、把 g4f 装进解释器：ensurepip + pip + 环境隔离

installG4F()（g4f-go/runtime.go#L115-L136）在每次执行 g4f 命令前检查并安装：

1. ensurePip()：先尝试 python -c "import pip"；失败则 python -m ensurepip --upgrade 引导（pbs install-only 包自带 ensurepip 但没有独立 pip）；
2. python -m pip install --no-input "g4f[slim]"；
3. 成功后写入 .g4f-runtime/.installed 戳。

pipEnv()（g4f-go/runtime.go#L156-L169）通过环境变量把 pip 严格限制在下载运行时内部，绝不触碰宿主 Python：

PYTHONHOME=<python-home 目录>
PYTHONNOUSERSITE=1        # 禁用用户级 site-packages
PYTHONDONTWRITEBYTECODE=1 # 不写 .pyc
PYTHONUTF8=1              # 强制 UTF-8
PYTHONPATH=<python-home>/lib/python3.14/site-packages   # Windows 为 Lib/site-packages

同样的隔离变量也固化在 shell 启动器中：writeLauncher()（g4f-go/process.go#L19-L28）生成的 python 包装脚本导出 PYTHONHOME、PYTHONNOUSERSITE 等后 exec "$DIR/python-home/bin/python" "$@"。注意源码注释特别指出：binDir/python 是 shell 包装器而不是解释器本体，真正的解释器永远在 python-home/bin/python（Windows 为 python-home/python.exe，见 pythonExecutable()，g4f-go/process.go#L135-L152）。

进程转发由 runPython()（g4f-go/process.go#L32-L49）完成：透传 stdin/stdout/stderr，Ctrl-C 时经 signal.NotifyContext 返回 130，子进程退出码原样冒泡。内部子进程（pip）则使用 noSignalCtx() 以免被 Ctrl-C 连带杀掉。最终，非内建命令一律转发为 python -m g4f <args...>（g4f-go/main.go#L116-L121）。

五、命令行用法

README 与 printHelp()（g4f-go/main.go#L15-L31）共同给出的完整命令集：

命令	作用
g4f-go <g4f args...>	运行 gpt4free（如 g4f-go client "hello"），参数透传给 python -m g4f
g4f-go api --port 8080	启动 OpenAI 兼容 API 服务
g4f-go gui	启动 Web GUI
g4f-go status	显示运行时下载/安装状态
g4f-go install g4f	（重新）安装 g4f 包（需网络），等价于在运行时里执行 pip install/uninstall ...
g4f-go bootstrap	刷新 g4f 包安装（升级 g4f-go 后重新 pip install g4f[slim]）
g4f-go --version	打印 g4f-go 0.1.0 (CPython 3.14.7)
g4f-go help	显示帮助

status 的实现（g4f-go/main.go#L64-L82）值得参考：它分别探测 python 可执行文件与 .installed 戳是否存在，输出 runtime: downloaded & extracted / not downloaded yet 与 g4f: installed / not installed，最后真正执行一次 python --version 验证解释器可用。

另一个实用开关是 G4F_PYTHON_ONLY=1：设置后启动器只打印下载好的解释器路径并退出（g4f-go/main.go#L101-L104），方便其他工具把这个 CPython 运行时作为独立组件包装使用。

六、支持的平台与 Android 特例

OS	Arch	运行时来源
Linux	amd64, arm64	python-build-standalone install-only tarball
Windows	amd64	python-build-standalone install-only tarball
macOS	amd64, arm64	python-build-standalone install-only tarball
Android	arm64（Termux）	官方 python.org *-linux-android 包

下载位置对照表：

平台	位置
Linux / macOS / Windows	~/.g4f/python-embed/
Android（Termux）	应用私有目录（G4F_ANDROID_FILES_DIR，默认 $HOME/g4f-go-runtime）

Android 是最复杂的分支，全部逻辑在 g4f-go/runtime_android.go（//go:build android）中，非 Android 构建使用 g4f-go/runtime_stubs.go 的空实现保证可编译：

1. Termux 探测与依赖安装：ensureRuntime() 开头检测 Termux 环境（TERMUX_VERSION 环境变量或 /data/data/com.termux/files/usr 存在性），缺少 clang/make 时用 pkg install -y clang make libxml2 libxslt libjpeg-turbo libpng 补齐（g4f-go/download.go#L387-L405）；
2. 目录合并：python.org 的 Android 包只提供 libpython3.14.so + stdlib、没有 python 可执行文件，因此把 tarball 合并进 G4F_ANDROID_FILES_DIR（或默认的 $HOME/g4f-go-runtime）下的 python-home/；
3. 编译 dlopen runner：finalizeAndroidRuntime() 写出内嵌的 pyandroid_runner.c，再用 Termux 的 clang（优先 /data/data/com.termux/files/usr/bin/clang）编译出 pyandroid。链接参数为 -I <home>/include/python3.14 -L <home>/lib -Wl,-rpath,<home>/lib -lpython3.14 -ldl（g4f-go/runtime_android.go#L88-L124）。C runner 的初始化序列是 dlopen("libpython3.14.so") → PyConfig_InitPythonConfig → PyConfig_SetBytesArgv → 从 PYTHONHOME 环境变量设置 cfg.home → Py_InitializeFromConfig → Py_RunMain（g4f-go/runtime_android.go#L129-L175），与 CPython 官方 android 测试床（testbed）采用相同技术。

build/ 目录下另有 build-all.sh 交叉编译脚本（README 中 ./build-all.sh、./build-all.sh android 即指向它）。

七、构建与重新 pin 清单

按 g4f-go/README.md 与 g4f-go/Makefile：

go build -o g4f-go .        # 本机快速迭代（对应 Makefile 的 dev 目标）
./build-all.sh              # 交叉编译并打 zip 发布包，输出到 dist/
./build-all.sh android      # 只构建 android 目标
./fetch-python.sh           # 重新下载各平台归档，回写 runtime.json 的 size + sha256

Makefile 还封装了 fetch（跑 fetch-python.sh）、build（跑 build-all.sh）、vet、test、clean 等目标；模块声明见 g4f-go/go.mod（module g4f-go，go 1.22），零第三方依赖。

fetch-python.sh（g4f-go/fetch-python.sh）的工作方式：用内嵌 python3 从 runtime.json 按前缀筛选平台（支持 linux|windows|darwin|android|all），逐个 curl 下载，计算 sha256sum 与文件大小后回写 manifest——这是发布前把空 sha256 pin 齐的标准流程。

关于 go:embed 的一个细节：g4f-go/runtime.go 与各 runtime_<os>.go 文件通过 build tag 嵌入 embed/<os>/ 目录，其中存放 EMPTY_PYTHON_RUNTIME 占位文件，保证 fetch-python.sh 运行之前 go build 也能成功（真正的归档/清单策略见文件内注释）。

八、限制与适用前提

README 明确列出三条限制，结合源码可进一步理解其成因：

1. 运行时必须落盘：CPython 无法可靠地 100% 在内存中运行，首次下载约 50–800 MB（视平台而定，如当前 manifest 中 Android 包固定为 22,477,276 字节，桌面 pbs 包大小取决于 pbs 发布）；
2. macOS 分发需签名/公证：Gatekeeper 要求由分发者完成签名与 notarization，启动器自身不处理；
3. Android 需要设备上的 Termux：dlopen runner 是在设备上用 Termux 的 clang 现场编译的（见 buildAndroidRunner() 的 Termux 探测与错误提示 Termux is required to build the python runner）。

此外从源码结构看还有两个实践要点：其一，G4F_ANDROID_FILES_DIR 未设置时 Android 运行时落在 $HOME/g4f-go-runtime（g4f-go/runtime_android.go#L33-L42），如需自定义应用私有目录应通过包装器注入该环境变量；其二，升级 g4f-go 后建议执行 g4f-go bootstrap 刷新包安装，而运行时的重新下载由清单固定版本驱动——版本变化前缓存持续有效。

九、小结

g4f-go 展示了一种“清单 + 首运行时下载”的分发模式：几 MB 的 Go 二进制（g4f-go/main.go 负责命令分发，g4f-go/download.go 负责下载/校验/解压，g4f-go/runtime.go 负责 pip 引导与环境隔离，g4f-go/runtime_android.go 处理 Termux 特例），配合 ~/.g4f/python-embed/ 下的戳文件与归档缓存，让 gpt4free 在“无系统 Python”的机器上即开即用，同时保留了 G4F_PYTHON_ONLY=1 这类把 CPython 运行时单独导出的扩展点。