架构总览 · 构建时从 cargo metadata 生成

一份 MIR,10 层,3 个编译目标

内容以 MIR 存在, 由 Agent 生成,由编译链按目标平台的预算编译。这里只放图:谁在哪一层、 边界用什么语言、现在建成了多少。文字论证在 架构文档 §1。

crate
28个
分层
10层 · 9 层站着 crate
编译目标
3host / wasm32 / ios
编译链
7段,ai-pass 是唯一非确定性
契约
17份 · 1 份冻结
P0 任务
74/170人日 275/672 · 41%

这是一张会自己更新的图。每个 crate 站在哪一层,读的是它自己 Cargo.toml 里的 [package.metadata.me];与 docs/01 §6.1 的表逐项比对, 对不上就构建失败。所以下面这些方块不会比代码旧。

00

先说清楚哪一半是建成的

同一张图里「已建成」和「计划中」长得一模一样,读图的人无法区分—— 要么以为进度比实际快,要么以为文档在吹牛。所以先把这条线画出来。

已经在跑

  • 28 个 crate,在 host / wasm32 / iOS 上按声明构建
  • 4 个 RHI 后端(d3d12 · metal · null · WebGL2)。null 不是占位,是让结构在没有 GPU 的机器上也能验
  • 2 个平台:host(测试与工具)· 微信小游戏(wasm32 上屏)
  • .mir ↔ .mirb 往返:1000 节点的场景,mir → mirb → mir 字节级等义,由测试钉住
  • 着色器生成器:src/ 里零手写 GLSL,这条也由测试守着
  • 编辑器的一端:me-studio 服务端(19446 行)+ 原生 JS 视图层(3619 行),能逐格改 MIR 并回写文本

还只是图上的虚线框

  • 4 个 crate:me-net · me-sim · me-arena · me-model,P1 才建
  • 4 个 RHI 后端:WebGPU · Metal · Vulkan · D3D12
  • 5 个平台:抖音 · iOS · Android · 桌面 · 主机
01

分层:依赖只能向下

10 层里,L1–L8 是主干,L0 与 L9 是两端:L0 被所有层引用,L9 依赖所有层。 每张卡片是一个真实存在的 crate,名字下面是它自己的职责、owner 与构建目标。

L9

命令行外壳依赖所有层

Agent 闭环的唯一反馈通道。进程短命、依赖一切、只被人与 CI 调用

me-cli

命令行外壳。Agent 闭环的唯一反馈通道

A3host
L8

Magic Studio

编辑器与工具层:场景编辑 · 材质图 · 动画图 · AI 工作台 · 性能工作台 · 资产库

me-studio

编辑器后端(前端在 apps/studio/)

A3host
me-studio-wasm

视口那一侧的 wasm(ADR-0015 §2.3 的 B 路):把一份 cooked 字节验一遍,再把条目区零拷贝指回调用方的缓冲区。不渲染 —— 渲染在 me-pal 的 JS 侧;同一个画面有两套实现的话,分叉之后「看着不对」分不清是解码错了还是画法错了。单独出这一份而不是塞进玩家包:玩家不需要解码器,实测 MESC 在 me_runtime.wasm 里出现 0 次

A3host/wasm32
L7

Agent Runtime

AI 内核:Intent → Planner → Generator → Validator → Optimizer

me-agent

AI 内核(内容生产)。不直接改文件,只产出 MIR diff

A1host
me-atlas-io

.mir 同层 .atlas 的装载:AtlasSet 从哪来。CLI 与 Studio 共用一份策略(扫整个目录 / 显式排序 / 读不开目录不算「图集坏了」)——两份实现的分叉不会报错,只表现为「Studio 说编得过、CLI 说编不过」

A3host
L6

MIR

全局枢纽:四类图 + 预算注解 + provenance,引擎唯一的真相源

me-compare

对账图的共用部分:21 组场景(geom)、CPU 参考渲染(cpu)、逐像素比较(compare)、判据(judge)。三条腿(D3D12 / WebGL2 / swrast)吃同一份场景与同一套判据,而 judge 只吃"比出来的数"、读不到任何后端内部状态——判据一旦能读后端状态,"三个后端用同一套判据"就是空话。它进 workspace 而 apps/gpu-demo 不进,正是因为产品真正跑的那条腿(WebGL2 / 小游戏)要把它编进 wasm32:放在演示工程里时,最该被验的那条路是唯一没有画面对账的

A3host/wasm32
me-compiler

编译链。离线运行,因此不进 iOS 包

A1host/wasm32
me-mir

schema、解析、规范化序列化、mirb、校验

A1host/wasm32/ios
me-swrast

CPU 软件光栅:把 me-render 的绘制列表画成 RGBA8 像素,不碰 GPU。它是 Studio 自绘的底座(有它才能在"没有 GPU、没有浏览器"的地方对一张界面做逐像素判据),也不是 me-rhi 的后端——rhi 的后端要假装自己有管线状态,而这一层只要"给我一批四边形、给我一张像素图"。层定在 L6 是留给"将来 runtime 拿它做离屏截图",否则同层依赖会被 check_workspace.py 挡住

A3host
L5

Runtime Subsystems

World(ECS) · Anim · Physics · Audio · Script · UI · Streaming

me-atlas

图集规划(构建期):排序、定高、分页、uv。只吃宽高不吃像素;算法本身仍是 me_render::atlas 那一份

A3host
me-fx2d

2D 特效系统:粒子池 + 发射器 + 关键帧曲线 + 特效时间轴,以及粒子与刚体的弹射/溅射(相对速度反射 + 接触点推出去 + 按撞速喷一簇)。它不守任何守恒律——粒子的「对」由观感定义,所以它不在 L4 物理层里,而是消费 L4 的一个上层。粒子不推动刚体:反作用力是一次的活(World::explode),不是每帧几千个粒子的活

A3host/wasm32/ios
me-record

内录:帧序列 → mp4(ffmpeg 管道)/ PNG 序列。零依赖,只认 RGBA 字节。只上 host 是如实的缺口:内录要 fork 编码器进程与写文件系统,wasm32 与 iOS 上都没有对应能力

A2host
me-runtime

ECS、调度、资源流式(可编 wasm,crate-type 含 cdylib)

A2host/wasm32/ios
me-ui

自绘 UI 系统:布局 / 控件 / 文字 / 输入 / 裁剪。只依赖 me-render,不依赖任何业务 crate。三张贴图全在加载期生成,没有一个美术资源。消费者是 apps/studio-native(整屏编辑器),与浏览器那套 apps/studio/ 并行存在

A1host
L4

Renderer

Render Graph 驱动:虚拟几何 · GI · 材质 · 角色 · 后效 · 裁剪

me-anim

2D 骨骼动画:骨骼层级、局部/世界变换、五种继承标志(Spine 语义)。语义照 Spine、实现不照它:数学全走 me-math(x86 与 wasm 逐位相同,tools/golden.mjs 守),平台分支放在 wasm-host/ 而不是库里的 cfg。不含蒙皮与 IK(S14-3/5)

A2host/wasm32/ios
me-audio

混音器:bus 图、定点增益、语音池、单声道定位

A2host/wasm32/ios
me-fluid2d

2D 粒子流体:双密度松弛(Clavet)、计数排序空间哈希(不用 HashMap,迭代顺序会漂)、圆形与有向盒障碍。不是 Navier-Stokes 求解器——要的是「看起来像水」(会流、会漫平、会被推着走),静止密度由参考间距积出来而不是拍的常数

A3host/wasm32/ios
me-physics

2D 物理最小集:分轴 AABB、单向平台、落地判定

A2host/wasm32/ios
me-render

Render Graph、裁剪、材质、后处理

A2host/wasm32/ios
me-rigid2d

2D 刚体:圆、有向盒与凸多边形(≤8 顶点,2026-10-29 加,为破碎铺路)、顺序冲量 + 暖启动 + 摩擦锥、NGS 位置修正、子步 CCD、距离/弹簧/铰链、休眠与传感器、层掩码、射线与区域查询、力场(磁铁/风/漩涡)。与 me-physics 不共用类型、不互相依赖——那份被 ADR-0013 冻结,共用一个 Aabb 就会成为「只改一个共享类型」的后门

A3host/wasm32/ios
me-shader

着色器生成:一张材质图、多个出口(GLSL / MSL,S18 加 HLSL)+ 顶点属性声明。2026-10-31 从 me-render::shader 搬出来(S17-3 第一步,五份产物逐字节相同)——搬的理由不是分文件,是出口会变成三个:留在渲染 crate 里时"两个出口读同一张图"只能靠人记得,搬出来之后由依赖方向保证(渲染层只能回来用,不能往里塞一张自己的属性表)。不含顶点布局(stride 由渲染层的顶点结构体决定),也不含编译与管线 —— 编译失败要与"生成错了"分开归因

A2host/wasm32/ios
me-soft2d

2D 软体:Verlet 质点 + 距离约束 + 形状匹配。旗帜/头发(网格与一维链)、果冻(形状记忆)共用一套代码。它不改速度、只改位置——软体守的是「边长与形状」,不是动量;果冻的「软」来自"约束解不唯一",所以用只有横竖边的 block 而不是带对角的 grid

A3host/wasm32/ios
L3

RHI

渲染硬件抽象。与上层的边界是 C ABI,不是 C++ 虚表

me-rhi

C ABI 边界(abi.rs 归 A1)+ 各后端(backends/ 归 A2;现有 null、WebGL2(wasm32)、D3D12(Windows,2026-10-28 加,只覆盖 P0 的 2D 路径))

A1host/wasm32/ios平台适配层
L2

PAL

平台抽象:FS · Thread · Time · Input · Net · Pay · Ads · Account · Storage

me-pal

平台抽象 trait 与各平台实现

A3host/wasm32/ios平台适配层
me-pal-wx

微信 wasm 导出壳:把像素缓冲暴露给 JS/WebGL

A3wasm32平台适配层
L1

Platforms设计上为空

平台是目标,不是模块

这一层没有 crate:平台本身(微信 / iOS / Android / 桌面 / 主机)是目标,不是模块——差异由 L2 的 PAL 实现吸收。

L0

Core被所有层引用

句柄、错误码、能力位、预算、溯源。不分配、不浮点

me-cooked

cooked 场景的字节形态(magic MESC):编译器写、运行时读,一份实现两边共用

A1host/wasm32/ios
me-core

句柄、错误码、能力位、预算、溯源。不分配、不浮点

A1host/wasm32/ios
me-math

确定性浮点数学:初等函数(sqrt / exp / ln / pow / 三角函数)、2D 向量、贝塞尔、二次求根、级数、积分、最小二乘。与 me-core 并列的另一个 L0,两者互不依赖——me-core 的许可是「不分配、不浮点」,而数学是行为、全是浮点;塞进去等于改写那条许可,且没有任何判据会红(改的是 description)。2026-10-28 起它是物理侧唯一的数学来源:三个物理 crate 全部依赖它,me-rigid2d/src/math.rs 只剩一层 pub use 门面。原设计里「两份实现互校」(me-rigid2d/tests/cross_math.rs)已撤——互校能发现「算错了」,发现不了「两边差着用」,而两份精度不同的 sin 存在同一个引擎里,就是等着某天有人查一整天「为什么回放对不上」

A3host/wasm32/ios

P1 计划中 · 只存在于文档

docs/01 §6.2 列了四个还没建的 crate。图上不画它们的格子—— 「计划中」的方块一旦和真实的方块长一样,就会有人去 crates/ 里找。

me-net

会话 / 传输 / 时钟 / 兴趣 / 回放。只抽象会话与传输,不抽象同步范式(ADR-007)

P1 Q1
me-sim

权威 tick / 快照 / lockstep / desync 检测。仅服务端

P1(Q1–Q2)
me-arena

agent 宿主:预算计量 / 留痕 / 匹配 / 评级。仅服务端

P1 Q3
me-model

Provider / Pricing 与计量累加器。不含模型实现与价格表

P1 Q3
02

六条宪法

架构不是那张图,是这六条。图可以改,这六条改一次要一次裁决。

只允许向下依赖

L5 不许 import L7,L4 不许知道 L8 存在。

违反三条以内还能救;三年后 3000 个例外就救不回来了。

L6 是唯一真相源

运行时不接受任何绕过 MIR 的资产直读。

凡是不能表达为 MIR 的东西,AI 就碰不到,也就无法优化。

L3 边界必须是 C ABI

内核语言可能换,RHI 后端几乎必然是 C++。

C ABI 是这份清单里唯一不随语言迁徙而碎的契约。

L2 之上禁止 #if PLATFORM

平台差异收敛为 PAL 的实现 + MIR 的 target 注解。

这是最常见的死法:三年后代码里 3000 个 #ifdef,引擎就废了。

L7 不许直接改文件

Agent 只产 MIR diff 或 recipe,落盘由编译链统一执行。

可审计、可回滚,都建立在「只有一处写盘」上。

预测与权威共用同一份 tick

客户端本地预测调用与服务端同一个 tick 函数。

两份实现必然漂移,症状是「偶尔被拉回原位」——最难查的那类 bug。

03

七段编译链

MIR 到可执行包是一条标准的多 pass 流水线。跨端这件事发生在这里,不在运行时—— 运行期判断会让 shader 变体爆炸。

  1. 01parse文本 → AST
  2. 02legalize目标能力合法化

    跨端的核心:virtual_geometry 在 WebGL2 上被合法化成预烘焙 LOD 链,而不是报错

  3. 03budget-pass预算分配与协商

    父子节点之间可以借贷,超限在编译期就报

  4. 04ai-passAgent 优化(可选)

    唯一的非确定性 pass:必须留完整 provenance,且能 --no-ai 关掉以复现 bug

  5. 05lower平台特化 IR

    着色器变体、资产编码、场景烘焙

  6. 06link分包切分

    把 30MB 内容切成 4MB 主包 + N 个 CDN 分包,按场景可达性做图划分

  7. 07pack平台包

    小游戏 zip / APK / IPA / 主机镜像

04

技术栈

左列是决定的结果,右列是原因。没有原因的行不要留在表里—— 那说明它是抄来的默认值,不是选择。

领域选型状态为什么是这个
内核语言Rust 2024(rust-version 1.97)已落地无 GC、零成本抽象、wasm32 一等公民(ADR-001)
后端边界C ABI · #define ME_RHI_ABI_VERSION 8已冻结后端几乎必然是 C++,C ABI 是唯一稳定的契约面(ADR-001 / 0003 / 0005 逐版裁决)
编译目标host / wasm32 / ios三目标进 CIwasm32 是主战场,iOS 证明原生后端,host 跑测试
渲染后端d3d12 · metal · null · WebGL2(已落地)→ WebGPU · Metal · Vulkan · D3D12(计划)4/8 已落地WebGL2 没有 compute,所以「Compute-free 路径」是硬约束(约束 C2)
内容格式.mir 文本(开发期权威)· .mirb 二进制(发布期权威)往返字节等义同一份 schema 生成两态,mir → mirb → mir 必须字节级相同
编辑器Rust 服务端 + 原生 JS 视图层(me-studio / apps/studio/web/)有可跑的一端编辑逻辑全在服务端,前端只画快照、发 act 请求——同一份逻辑在 TS 里再写一遍,症状会是「界面上改得动、文件里没变」
平台微信小游戏(wasm32,已落地)→ 抖音 / iOS / Android / 桌面 / 主机1/7 已落地每个平台一个 PAL 实现,不改上层一行
工具链cargo + Python 守卫(CI 111 步)+ Playwright 视觉验证在跑守卫必须会红:写在文档里的规则只有「被人想起来」一种生效方式

本页由 build_arch.py 在构建时生成:分层、owner、构建目标来自 cargo metadata(每个 crate 的 [package.metadata.me]), 并与 docs/01-architecture.md §6.1 的表逐项对账;契约数来自 interface/MANIFEST.json;任务与人日来自 docs/10 + plan/board.json; CI 步数来自 tools/ci/ci.sh。任一处对不上,构建直接失败—— 不会产出「三周前的图 + 今天的日期」。

要改这一页的内容:改 crate 的 Cargo.toml,或者改 build_arch.py 里的层名与散文。不要直接改 site/arch/index.html, 它是产物,下次构建会被覆盖。