agentty-gpui

Agentty 专用的 UI 框架:用 GPU 绘制的 Rust UI,支持 macOS、Windows 和 Linux,以 20 个 crate 发布在 crates.io 上。

agentty-gpui 是 Agentty 专用的 UI 框架,基于 Zed 的 gpui 打造。

它包含 Agentty 用 GPU 绘制界面所需的一切:元素与布局、窗口与菜单、键盘和鼠标输入、文字排版与字体、图片与 SVG,以及 macOS、Windows、Linux 的后端和渲染器。Agentty 需要的修复和功能直接加入这里,并以 20 个 crate 发布在 crates.io 上,任何 Rust 应用都能以同样的方式使用。

快速开始#

加入两个 crate:框架本体 agentty-gpui,以及为当前操作系统启动后端的 agentty-gpui-platform。它们的库名是 gpui 和 gpui_platform,所以代码里写 use gpui::...。

sh
cargo add agentty-gpui --rename gpui
cargo add agentty-gpui-platform --rename gpui_platform
rust
fn main() {
    gpui_platform::application().run(|cx: &mut gpui::App| {
        // 打开窗口、绑定按键……
    });
}

各平台需要开启的内容:

平台设置
macOS开启 agentty-gpui-platform 的 runtime_shaders 后,Metal 着色器在启动时编译,构建不需要 Xcode 的 Metal 工具链。关闭时在构建时编译,需要该工具链(xcodebuild -downloadComponent MetalToolchain)。
Windows无需额外设置。默认的 windows-manifest 功能会把应用清单嵌入可执行文件。
Linux为两个 crate 开启 wayland 和/或 x11。

功能开关#

agentty-gpui 的功能。默认开启 font-kit、wayland、x11、windows-manifest。

功能作用
font-kit查找并加载系统字体(默认)
wayland、x11Linux 显示服务器支持(默认)
windows-manifest把 Windows 应用清单嵌入可执行文件(默认)
screen-capture屏幕捕获
inspector查看运行中界面元素的检查器
test-support测试用平台和辅助工具
leak-detection跟踪实体句柄,在测试中发现泄漏;构建时设置 GPUI_LEAK_DETECTION 也会开启
bench-support基准测试和性能分析器(bench 是它的旧名称)
profiler帧时间直方图
stacker深度递归时扩展栈
hot-reload开发时的代码热重载

agentty-gpui-platform 会把同名功能传给各个后端(font-kit、inspector、screen-capture、test-support、bench-support、wayland、x11、runtime_shaders),默认开启 multithreaded。

Crate 一览#

所有 crate 版本一致,构建时只会编译目标平台需要的 crate。链接指向各 crate 的 crates.io 页面。

框架#

Crate库名作用依赖
agentty-gpuigpui框架本体:元素、flexbox 布局(Taffy)、窗口、输入、动作与快捷键绑定、文字、图片与 SVG、异步执行器collections、http-client、macros、refineable、scheduler、shared-string、sum-tree、util、bench-metrics(可选)
agentty-gpui-platformgpui_platform为当前操作系统选择后端并启动应用(gpui_platform::application())agentty-gpui、macos、windows、linux、wgpu(可选)
agentty-gpui-macrosgpui_macros框架的 derive 和属性宏—

平台后端与渲染器#

Crate库名作用依赖
agentty-gpui-macosgpui_macosmacOS 后端:AppKit 窗口和菜单、输入、通知、屏幕捕获(可选)agentty-gpui、apple、collections、scheduler、util
agentty-gpui-applegpui_appleApple 平台共用的 Metal 渲染器和 Core Text 文字agentty-gpui、collections、util
agentty-gpui-windowsgpui_windowsWindows 后端:Direct3D 11 渲染器、DirectWrite 文字、DirectCompositionagentty-gpui、collections、scheduler、util
agentty-gpui-linuxgpui_linuxLinux 后端:Wayland 和 X11、键盘布局(xkbcommon)、桌面门户agentty-gpui、collections、http-client、util、wgpu(可选)
agentty-gpui-wgpugpui_wgpuLinux 上使用的 wgpu 渲染器agentty-gpui、collections、util

基础库#

Crate库名作用依赖
agentty-gpui-utilgpui_util小型通用辅助工具—
agentty-gpui-shared-stringgpui_shared_string无需复制即可共享的字符串 SharedString—
agentty-gpui-collectionscollections哈希映射和哈希集合类型util
agentty-gpui-sum-treesum_tree列表和文字底层的 B 树,适合并发ztracing
agentty-gpui-schedulerscheduler异步任务调度器—
agentty-gpui-refineablerefineable让样式可以部分覆盖的 Refineable traitderive-refineable
agentty-gpui-derive-refineablederive_refineable它的 derive 宏—
agentty-gpui-http-clienthttp_clientHTTP 客户端接口,用于从 URL 加载图片—
agentty-gpui-zlogzlog日志collections
agentty-gpui-ztracingztracing追踪,可选接入 Tracy 性能分析器ztracing-macro、zlog(可选)
agentty-gpui-ztracing-macroztracing_macro它的属性宏—
agentty-gpui-bench-metricsbench_metrics性能计数器—

没有包含 iOS 和 Web 后端,因为 Agentty 面向 macOS、Windows 和 Linux。需要原始 HTTP 客户端的 image 和 image_gallery 示例也没有包含。

crates.io 依赖#

crates.io 上的 crate 只能依赖 crates.io 上的 crate。原始代码从 Git 或分叉获取的依赖,这里换成了 crates.io 的发布版本:

Crate原始版本多出的内容
async-task任务 waker vtable 标识的修复
calloop(Linux)每轮循环的 idle 回调限制在约 10ms
khronos-egl(Linux)失败的 EGL 调用报告成功时不再 panic
wgpu、naga(Linux)更新的 API(QueueDescriptor、has_srgb_suffix)
zed-font-kit、zed-scap、zed-xim之后的小修复
oo7(Linux)提示流结束时的错误处理
windows-capture(Windows,screen-capture)无;在 Cargo.lock 中固定为能与 zed-scap 一起构建的最后一个版本,开启 screen-capture 的一方也必须同样固定

更新方式#

有两个分支:

  • main:发布的代码,为 Agentty 做的改动都在这里。
  • upstream:作为基础的原始代码,未经修改,每个原始版本一个提交,对应的版本写在 zed/SNAPSHOT.md 中。

引入新的原始版本:

sh
scripts/sync-upstream.sh <标签>   # 在 upstream 上生成新快照
git merge upstream                 # 合并到 main,只有这里改过的文件可能冲突
python3 -I scripts/apply_agentty.py

合并时如果 crate 清单冲突,采用原始一侧(git checkout --theirs <文件>),再重新运行脚本。

测试#

sh
cargo nextest run --workspace --features agentty-gpui-apple/runtime_shaders
cargo test --workspace --doc --features agentty-gpui-apple/runtime_shaders
  • 使用 nextest:有几个测试读取进程级状态,用 cargo test 并行运行时会失败。
  • CI 使用 --profile ci(.config/nextest.toml),失败的测试最多重试两次,因为有几个基准测试会计时 80ms 的轮询,在繁忙的运行器上可能超时。
  • Linux CI 在 wgpu 渲染器测试中使用 Mesa 的软件 Vulkan 驱动。

发布流程#

  1. 提高 scripts/apply_agentty.py 中的 VERSION,重新运行脚本并推送。CI 必须通过,包括 cargo publish --workspace --dry-run。
  2. 在 GitHub Actions 中运行 Agentty 工作流,用这个检出在 macOS、Windows 和 Linux 上构建并测试 Agentty。
  3. 用 cargo publish --workspace 按依赖顺序发布。
  4. 打上发布标签(git tag v<版本> && git push origin v<版本>)。

反馈问题#

agentty-gpui 的问题或希望的改动,请提交到 agentty-gpui 的 Issues;Agentty 的问题请提交到 Agentty 的 Issues。各操作系统上 Agentty 的差异见 平台。