Files
endorphin-tessera-gui/docs/architecture/01-modules.md
T
2026-10-25 21:25:43 +08:00

4.3 KiB
Raw Blame History

01 · 模块、依赖与部署

项目目录

Tessera/
├── Cargo.toml / Cargo.lock      Rust 依赖和固定解析结果
├── src/
│   ├── main.rs                 组合入口、事件循环和共享发布状态
│   ├── shell/                  原生窗口、标签、开发工具、管理控件
│   ├── runtime/                本机 API、VM worker、执行、事件与异步任务
│   ├── model/                  托管对象、挂载、绑定、依赖和发布数据
│   ├── render/                 布局、绘制、命中、字体与软件光栅化
│   └── bridge/                 Endor 与宿主 UI 类型及行为的连接
├── examples/                   Endor 示例程序,保留原文件名与入口
├── docs/
│   ├── architecture/           本套架构说明和 UML 源文件
│   └── media/                  已有建模视频与字幕
├── scripts/                    原生打包及已有远程检查入口
└── vendor/aster/               独立 Git 子模块:语言、编译器、VM

target/ 是忽略的构建产物,不是源码目录。示例与媒体保留原位置,避免破坏已有引用。完整源码职责见 逐文件清单。

组件关系

箭头表示主要运行时调用/数据流,不宣称是无环的 Rust import 图。

flowchart LR
    Agent[本机客户端 / Console] --> API[runtime: HTTP API]
    API --> Worker[runtime: 串行 VM worker]
    Worker --> Aster[Aster frontend / compiler / core]
    Worker --> Bridge[bridge: UI 类型和行为]
    Bridge <--> Model[model: 对象与展示状态]
    Bridge --> Render[render: 布局与画面提取]
    Worker --> Published[NamespaceState / RenderDocument]
    Published --> Shell[shell: 原生工作区]
    Shell --> Scene[render: 场景合成与光栅化]
    Scene --> OS[winit / softbuffer / 操作系统]
    Shell -->|序列化输入| API
    Worker --> IO[runtime: 有界 I/O provider]
    IO -->|纯数据完成消息| Worker

标准 UML 组件表示见 components.puml。System UI 只依赖低层几何、文本和画图,不导入 Endor VM 或 guest bridge;开发工具的执行逻辑由外层提供。

线程与进程

执行位置 核心所有物 交互方式
GUI / winit 主线程 TesseraApp、原生 Window、Surface、标签动画、工具交互 读已发布快照;发 viewport、输入和窗口命令
tessera-agent-api tiny_http 接收循环、请求观察 对写入做校验并进入最多 8 条的构建队列;读取当前发布状态
tessera-endor-worker 活跃 ReplSession、候选 VM、托管对象图 串行执行程序、回调、布局/绘制协议及任务完成交付
输入发送线程 有界输入客户端 把原生输入转为本机 HTTP 请求;不执行 VM
按需 I/O 池 文件/HTTP 工作及取消控制 不持有托管根;通过 mailbox 回传文本/错误
系统 curl 子进程 fetchText 的实际 HTTP 传输 有超时、大小和协议限制;不是业务服务
flowchart TB
    subgraph Desktop[Tessera 单个桌面进程]
        GUI[GUI 主线程]
        HTTP[本机 API 接收线程]
        VM[唯一执行 worker]
        IO[I/O 池]
        State[(Arc / RwLock NamespaceState)]
        HTTP -->|有界队列| VM
        VM -->|原子发布| State
        State -->|只读快照| GUI
        GUI -->|输入客户端| HTTP
        VM <--> IO
    end
    External[本机 agent] -->|127.0.0.1:4737| HTTP
    IO --> Curl[系统 curl 子进程]
    GUI --> Native[原生窗口 / 软件像素缓冲]

可编辑部署图:deployment.puml。Aster 作为 Cargo path dependency 编译到同一应用,不是额外 VM 服务;Lyra 和 Hestia 不在应用依赖链中。

入口定位

  • 启动:src/main.rs → runtime/api::start → shell/app::TesseraApp。
  • 请求路由和有界队列:runtime/api.rs;VM 所有权与发布:runtime/api/worker.rs。
  • 启动 Endor 主程序/Console:runtime/endor_host.rs。
  • 类型安装:bridge/ui_bridge/bootstrap.rs;原生 Block 方法:calls.rs。
  • 组合最终画面:render/scene.rs;写入像素:render/software_renderer.rs。