PPysolate SpineREAD THE CODE · UNDERSTAND THE SYSTEM
章节目录
LEARNING NOTES / 08

仓库说明

命令、实现范围与文件导航。

供 MSRA 面试学习和协作 coding 的独立小实现:Go/wazero 启动真实 CPython Wasm,Python 调用 Host 工具并交付结果。已实现普通执行、小型 whole-program PLM、prefix 和可选 prepared full-copy。Full-copy 用于说明基线与隔离,不是真 COW;本版不再计划实现 Linux 页共享。不做性能测量。

学习手册 开始,再读 PLM 章节prefix 章节 阅读顺序、背景、逐函数讲解、所有权/错误路径和练习随代码同步更新。文档站采用 Astro:https://pysolate-spine.pages.dev/,整站 noindex;这不是访问鉴权。

三个入口

make demo
make explain
make check

准备讲解时看 演示与协作练习;按问题选择 五个边界例子。练习题尚未实现,不需要先读全部底层代码。

运行

需要 Go 1.25 或更新版本,以及实际构建的 dist/spine.wasm。当前本机已有阶段 3 Guest;artifact 不进 Git,新 clone 的要求见 构建与来源

go run ./cmd/demo
# {"item": "book", "total": 42}

# 同一个查价例子加运费,普通 / PLM 结果一致。
go run ./cmd/demo -source examples/order.py
# {"item": "book", "total": 47}
go run ./cmd/demo -source examples/order.py -plm -show-transformed
# stderr 展示实际 Guest AST 转换或明确的无转换状态;stdout 仍是结果。

go run ./cmd/demo -source examples/order.py -prefix -show-transformed
# 文件按行片段回放,不是 LLM provider 接入。

go run ./cmd/demo -source examples/order.py -prepared-copy -prefix
# 同一条 prefix 路径,私有内存全量复制;不是 COW。

go test ./... -count=1
go test -race -run TestPLMGuest -count=1
go test -race -run TestPrefixGuest -count=1
go test -race -run TestPreparedGuest -count=1
PYTHONPATH=guest python3 -m unittest guest/test_plm.py guest/test_prefix.py
go vet ./...

-source 换用户程序,-inputs 传 JSON,-wasm 指定 artifact。改用户程序无需重建解释器;改 Guest C/bootstrap/pass 必须重建。当前远程构建入口:python3 tools/rebuild-guest.py,复用已存在的 Linux CPython/WASI 输入。

可选背景见 prepared-copy 短说明,学习重点仍是 PLM。

实现边界

  • Run 普通执行;RunPLM 只提前 Host 显式 opt-in 的稳定快照读取。
  • 小 AST pass 只在支持的程序里重排相邻工具赋值;保留依赖、分支和原调用处结果/错误交付。不支持的程序正常执行。
  • RunPrefix 接收 append-only 源码片段,在同一 Guest / Future owner 中先准备、后执行。
  • Future 归本轮 Run,退出时取消/等待任务;工具必须配合 context。
  • 无旧 Broker、Verified、certificate、receipts 或默认 hash 管线。没有失败后自动重试。

文件导航

examples/lookup.py       两行普通例子
examples/order.py        同例加一个独立读取
cmd/demo/main.go         工具注册、CLI 与模式选择
runner.go                普通 / PLM / prefix 共用执行生命周期
bridge.go                Host 调用、prepare / resolve 入口
future.go                本轮 Future、匹配、取消与回收
prefix.go                源码 channel 接收与共用字节 ABI
prepared.go              可选干净基线全量复制(不是 COW)
guest/bootstrap.py       执行约定与错误交付
guest/plm.py             小型 AST pass
guest/prefix.py          保守前缀解析与已准备 handle 领取
guest/runtime.c          CPython / Wasm ABI 胶水
build-guest.sh           Linux 链接与打包
tools/rebuild-guest.py   同步源码、构建并取回 artifact

不需要旧 runtime 源码来运行新仓库。Go 直接依赖只有 wazero,另有其传递依赖。普通路径 16 个、PLM 13 个、prefix 10 个、prepared-copy 7 个真实 Guest 子测试;另有 6 个 PLM 与 5 个 prefix 本机语法单测,以及 5 个文档例子同时验证普通/PLM 结果。

源码 Git 仓库仍无 GitHub remote;文档及选定源码视图由独立 Cloudflare Pages 站点提供。原 worktree 保留为备份。Wasm、凭据、机器配置和运行日志不随站点发布。