Vitro 快速入门

最后核对：2026-10-07（零分钟上手补统一入口 launcher——scripts/bin/vitro 默认 wasm 臂免构建直跑，源码构建段保留；复核补漏批抓漏〔#49 批一 2026-10-06 落地晚于本册 10-05 重写〕。前一沿革 2026-10-05 S9 工序④删区整篇改单轨——原「Rust 冻结对照 oracle 三出口」主线随 native/ 物理删除整体失效，替换为 MoonBit 现役三路径；历史形态见 tag rust-oracle-freeze）

单轨口径（2026-10-05 起）：仓库唯一实现 = MoonBit（moonbit/）。MoonBit 侧构建与闸门见 moonbit/AGENTS.md，路线与进度见 MoonBit迁移总计划.md。

本指南帮助你在 10 分钟内跑通 Vitro 的三条主路径：命令行调试、JSON-lines 会话、wasm-gc 出口。

需要深度构建配置与防线细节，请参阅构建指南.md；前端（Flutter / Android / Web）已于 2026-09-11 迁出本仓库，见后端定位与白箱计划.md。

零分钟上手：MoonBit 现役引擎（`vitro/engine`）

推荐：统一入口 launcher（#49 批一，2026-10-06 起）——不用先构建，默认 wasm 臂直接跑（node ≥25 消费 gateway/wasm/wasm.wasm；node 缺失/过旧自动降级 native exe，stderr 明示 backend= 行）：

scripts/bin/vitro run corpus/baseline/hello_world.c        # sh（Git Bash/Linux/macOS）；Windows cmd 用 scriptsinitro.cmd
scripts/bin/vitro --backend native run corpus/baseline/hello_world.c   # 显式 native 臂

源码构建与测试（闸门验证 / native 臂产物）：

# 728 测试用例（facts `moonbit_test_passed` 口径）+ 全部闸门绿（闸清单以 ci.yml 为权威，不锚闸数）
cd moonbit && moon check && moon test

# 端到端跑一个 C 程序（`vitro` 总入口：C 源码 → 编译 → VM 执行）
cd moonbit && MOON_CC=clang moon build --release --target native cmd/vitro
./_build/native/release/build/cmd/vitro/vitro.exe run ../corpus/baseline/hello_world.c
# → Hello（返回码 0）
# 更多：vitro compile / step / api（万能单帧，全部协议方法脚本化）——见 [CLI使用手册](CLI使用手册.md)

Windows 提示：moon build --target native 默认走 MSVC cl 链接后端，本仓实测病态慢（moon#2254 自述口径）；一律设 MOON_CC=clang，全量约 17s（moonbitlang/moon#2254）。MoonBit 侧完整构建/闸门/发布流程见 moonbit/AGENTS.md。

环境要求

工具	版本	用途
MoonBit 工具链（moon）	基线见 `scripts/toolchain_baseline.txt`	现役引擎构建与测试（必需）
Go	见根 `go.mod`	测试防线驱动（clang_direct / vm_diff 等，零第三方依赖）
Clang / Clang++	近期版本	Clang 直拍门禁的 Golden（跑防线必需）；Windows 上 native 目标构建须 `MOON_CC=clang`
Node.js	近期版本	wasm-gc 网关冒烟 / demo 冒烟宿主

moon version           # MoonBit 工具链（基线锁定见 scripts/toolchain_baseline.txt）
clang --version        # 跑直拍防线时需要
go version && node --version

一分钟上手：命令行工具

vitro 总入口（MoonBit）可直接编译、运行、单步与脚本化调试 C 代码：

cd moonbit && MOON_CC=clang moon build --release --target native cmd/vitro
# 产物：moonbit/_build/native/release/build/cmd/vitro/vitro.exe

# 直接运行代码片段（`-` = 源码从 stdin 读）
echo '#include <stdio.h>
int main() { printf("hello, vitro\n"); return 0; }' | ./_build/native/release/build/cmd/vitro/vitro.exe run -

# 编译并查看诊断（中文诊断：错误码 + 位置 + 修复建议）
./_build/native/release/build/cmd/vitro/vitro.exe compile ../corpus/baseline/hello_world.c

# 一次性 step 流
./_build/native/release/build/cmd/vitro/vitro.exe step ../corpus/baseline/hello_world.c

完整命令与选项（compile / step / api 万能单帧与批式多帧）见 CLI使用手册.md。

五分钟上手：JSON-lines 会话（headless 出口）

长寿命会话进程：stdin 每行一个 JSON 请求，stdout 每行一个 JSON 响应（NDJSON）。供 IDE 后端、判分服务、自动化脚本以任意语言消费，无需 ctypes 或 FFI。

cd moonbit && MOON_CC=clang moon build --release --target native cmd/serve
./_build/native/release/build/cmd/serve/serve.exe <<'EOF'
{"id":1,"method":"compile","params":{"source":"#include <stdio.h>\nint main(){ printf(\"%d\", 1+2); return 0; }\n"}}
{"id":2,"method":"run"}
{"id":3,"method":"output.delta","params":{"cursor":0,"stream":"stdout"}}
{"id":4,"method":"shutdown"}
EOF

响应形如：

{"id":1,"ok":true,"result":{"diagnostics":[],"ok":true}}
{"id":2,"ok":true,"result":{"ok":true,"return_value":0,"status":"finished","steps_executed":13,"trap":"","waiting_input":false}}
{"id":3,"ok":true,"result":{"cursor":1,"delta":"3","stream":"stdout","total":1}}
{"id":4,"ok":true,"result":{"shutdown":true}}

三条关键契约：

id 关联：请求可带 id，响应原样回填（异步/乱序对账）；
帧同构：成功帧 {"ok":true,"result":{…}}、错误帧 {"ok":false,"error":{…}}，解析路径统一；
输出分通道：stream 取 display（默认，含引擎附注）/ stdout（纯程序输出，判分与 Clang Golden 比对用）/ stderr / note。

方法一览（编译 / 运行 / 单步 / seek / 断点 / 内存区域 / 配置）见 CLI使用手册.md serve 节； StepPayload 的字段语义见 docs/spec/STEP_PAYLOAD_SCHEMA_V0_1.md。

五分钟上手：wasm-gc 出口

cd moonbit && moon build --release --target wasm-gc gateway/wasm
node scripts/wasm_gateway/host.js     # 16 断言冒烟（gateway 4 导出面 / trap / 体积上限）

gateway 库 + gateway/wasm 薄壳构成 wasm-gc 单出口（S7 批五号落地，总计划 F-5； String 零拷贝直传，NDJSON 帧协议与 serve 同一语义）。浏览器直调形态见仓库附带静态单页 demo（demo/）。

历史注记：原 Rust wasm32 出口（vitro_native.wasm ≈3.75MB）已随删区退役， wasm_smoke 冒烟门禁随之移除；现役 wasm 出口冒烟 = scripts/wasm_gateway/host.js。

验证项目是否健康

cd moonbit && moon check && moon test                     # 现役引擎：728 用例（facts 口径）+ 全部闸门绿（闸清单见 ci.yml）

# Clang 直拍（与 Clang / Clang++ 对照全量语料 stdout）
go run ./scripts/clang_direct

# serve 协议冒烟
go run ./scripts/serve_smoke

# 文档数字对账
go run ./scripts/facts --strict check

常见问题

`moon` 命令未找到

安装 MoonBit 工具链（见 moonbit/AGENTS.md 环境节）；版本基线锁定于 scripts/toolchain_baseline.txt。

直拍防线报 "clang not found"

防线以 Clang 为唯一 Golden 来源，缺失时会故意 fail fast（exit 2），而不是静默跳过。安装 LLVM/Clang 并加入 PATH。

程序等待输入（`waiting_input`）

run 返回 waiting_input: true 时，可通过 -i <file>（CLI）或 run.input / batch_input（serve）提供标准输入。

想看图形界面

本仓库不含任何前端。图形界面由社区前端基于出口协议自行实现；历史 Flutter 前端见标签 before-frontend-split。

下一步

支持的 C 子集：C语言子集规范.md（C++ 子集已裁砍归档：ARCHIVE_C++子集规范.md）
架构设计：架构设计.md
CLI 手册：CLI使用手册.md
构建与防线：构建指南.md
后端定位与路线：后端定位与白箱计划.md
MoonBit 现役引擎（S2–S8 已收官）：MoonBit迁移总计划.md ｜构建与闸门：moonbit/AGENTS.md
协议 schema：STEP_PAYLOAD_SCHEMA_V0_1.md

零分钟上手：MoonBit 现役引擎（vitro/engine）