build-gpui-apps

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Build GPUI Apps

构建GPUI应用

Build native GPUI software that is correct before it is glossy, genuinely platform-aware before it is Apple-styled, and verified in the running app before it is called complete.

This is a routed umbrella skill. Read only the reference layers needed for the task, but always follow the core contract and workflow below.

构建原生GPUI软件，遵循先确保正确性再追求美观、先实现真正的平台适配再打造Apple风格、先在运行应用中验证再宣告完成的原则。

这是一个路由式的综合技能。只需阅读完成任务所需的参考内容，但请始终遵循以下核心约定与工作流程。

Core contract

核心约定

Inspect the target checkout before changing it: branch, dirty state, manifests, lockfile, pinned GPUI source, app entrypoint, root view, theme, components, assets, tests, and platform code.
Treat the target checkout as the API authority. GPUI is pre-1.0; examples from
```
gpui.rs
```
, Zed main, crates.io, or this skill can differ from the pinned revision.
Preserve working state ownership, commands, shortcuts, persistence, window behavior, and platform integration. A visual request is not permission to replace the app architecture.
Keep render work deterministic and cheap. Move blocking I/O and CPU-heavy work off the application thread, then update a live entity through the appropriate async context.
Give interactive elements stable IDs, semantic roles, keyboard access, visible focus, disabled behavior, and immediate input feedback.
Use glass as a functional navigation or control layer, not as decoration on every surface. Never describe a flat translucent rectangle as native Liquid Glass.
Respect reduced motion, reduced transparency, increased contrast, and differentiate-without-color. Provide an opaque fallback.
Validate compilation, behavior, launch, and visuals.
```
cargo check
```
alone does not prove focus, fonts, window chrome, scale factor, clipping, motion, or material behavior.
Do not rasterize text, controls, panels, or whole screens to fake fidelity.
Preserve unrelated changes and report every unverified platform or runtime path plainly.
Treat text input, clipboard, menus, drag/drop, and window lifecycle as OS contracts. Preserve Unicode range units, composition, focus, command state, and stable ownership.
For a new application, establish product identity, a pinned toolchain and GPUI revision, observable startup, storage policy, CI, and packaging gates before calling the starter production-ready.

在修改前检查目标代码库：分支状态、未提交更改、清单文件、锁文件、固定的GPUI源码、应用入口、根视图、主题、组件、资源、测试及平台相关代码。
将目标代码库视为API权威。GPUI尚未发布1.0版本；
```
gpui.rs
```
、Zed主分支、crates.io或本技能中的示例可能与固定的修订版存在差异。
保留现有工作状态的所有权、命令、快捷键、持久化机制、窗口行为及平台集成。视觉需求不代表可以替换应用架构。
确保渲染工作可预测且轻量化。将阻塞式I/O及CPU密集型工作移至应用线程之外，再通过合适的异步上下文更新实时Entity。
为交互元素提供稳定ID、语义角色、键盘访问方式、可见焦点、禁用状态及即时输入反馈。
将玻璃效果用作功能性导航或控制层，而非所有界面的装饰。切勿将扁平半透明矩形描述为原生Liquid Glass。
尊重减少动效、减少透明度、高对比度及无色彩区分的需求。提供不透明的 fallback 方案。
验证编译结果、行为表现、启动流程及视觉效果。仅通过
```
cargo check
```
无法证明焦点、字体、窗口边框、缩放比例、裁剪、动效或材质行为的正确性。
切勿通过栅格化文本、控件、面板或整个屏幕来伪造保真度。
保留无关更改，并清晰报告所有未验证的平台或运行时路径。
将文本输入、剪贴板、菜单、拖拽及窗口生命周期视为系统约定。保留Unicode范围单元、输入法候选、焦点、命令状态及稳定所有权。
对于新应用，在宣告初始版本可投入生产前，需确立产品标识、固定的工具链与GPUI修订版、可观测的启动流程、存储策略、CI及打包校验规则。

Route the task

任务路由

Task	Read first	Also read when relevant
Set up or harden a production-ready starter app	production-starter.md	project-versioning.md, testing-qa.md
Orient a GPUI checkout or choose dependency features	project-versioning.md	testing-qa.md
Design state, events, actions, or component boundaries	architecture-state.md	async-performance.md
Build views, controls, layout, themes, overlays, or lists	components-layout.md	worked-patterns.md
Add Apple-like glass, translucency, depth, or macOS material	apple-glass.md	accessibility-platform.md
Add animation, drag, momentum, springs, or gesture behavior	motion-input.md	accessibility-platform.md
Add focus, keyboard, screen-reader, typography, or platform behavior	accessibility-platform.md	components-layout.md
Add editable text, IME, clipboard, drag/drop, menus, multi-window behavior, or restoration	input-windows.md	accessibility-platform.md, testing-qa.md
Add async loading, background work, virtualization, or performance fixes	async-performance.md	architecture-state.md
Add or review tests, launch checks, screenshots, or release gates	testing-qa.md	visual-validation.md
Translate a Paper.design selection into GPUI	paper-to-gpui.md	paper-mcp.md, visual-validation.md
Need complete, copyable patterns	worked-patterns.md	The domain reference for the pattern
Verify why a rule exists or refresh time-sensitive claims	sources.md	Current target source and official docs

任务	优先阅读	相关场景下补充阅读
搭建或加固可投入生产的初始应用	production-starter.md	project-versioning.md, testing-qa.md
熟悉GPUI代码库或选择依赖特性	project-versioning.md	testing-qa.md
设计状态、事件、动作或组件边界	architecture-state.md	async-performance.md
构建视图、控件、布局、主题、浮层或列表	components-layout.md	worked-patterns.md
添加类Apple玻璃效果、半透明、层次感或macOS材质	apple-glass.md	accessibility-platform.md
添加动画、拖拽、动量、弹簧效果或手势行为	motion-input.md	accessibility-platform.md
添加焦点、键盘、屏幕阅读器、排版或平台行为	accessibility-platform.md	components-layout.md
添加可编辑文本、IME、剪贴板、拖拽、菜单、多窗口行为及恢复功能	input-windows.md	accessibility-platform.md, testing-qa.md
添加异步加载、后台任务、虚拟化或性能优化	async-performance.md	architecture-state.md
添加或评审测试、启动检查、截图或发布校验规则	testing-qa.md	visual-validation.md
将Paper.design设计转换为GPUI代码	paper-to-gpui.md	paper-mcp.md, visual-validation.md
需要完整可复用的代码模式	worked-patterns.md	对应模式的领域参考文档
验证规则存在的原因或更新时效性声明	sources.md	当前目标源码及官方文档

Workflow

工作流程

1. Establish scope and current truth

1. 确定范围与当前基准

Run the read-only inspector:

scripts/inspect_gpui_project.sh /path/to/project

Then inspect directly:

Read repository instructions and determine whether the request authorizes edits or only diagnosis/review.
Confirm the owning crate and the smallest surface that can satisfy the task.
Record the GPUI declaration and exact lockfile version or Git revision.
Find a similar component that compiles in this checkout.
Identify current theme access, asset loading, focus conventions, actions, overlay system, async patterns, and test support.
Note the platform and minimum OS versions. Do not silently make a cross-platform component macOS-only.

Read project-versioning.md before creating a new app, changing startup, changing GPUI versions, or copying an upstream API.

For a greenfield or starter-hardening request, read production-starter.md before choosing the crate layout. It uses lassejlv/gpui-starter as a concrete minimal example, then adds the missing production contracts without pretending every app needs every subsystem.

运行只读检查脚本：

scripts/inspect_gpui_project.sh /path/to/project

然后直接检查以下内容：

阅读仓库说明，确定请求是否允许编辑，还是仅需诊断/评审。
确认所属 crate 及满足任务需求的最小修改范围。
记录GPUI声明及锁文件中的精确版本或Git修订版。
找到代码库中可编译的同类组件。
识别当前的主题访问方式、资源加载逻辑、焦点约定、动作、浮层系统、异步模式及测试支持。
记录目标平台及最低系统版本。请勿将跨平台组件默认为仅支持macOS。

在创建新应用、修改启动流程、变更GPUI版本或复制上游API前，请阅读project-versioning.md。

对于从零开始或加固初始应用的请求，请在选择 crate 结构前阅读production-starter.md。文档以lassejlv/gpui-starter为具体的最小示例，然后补充缺失的生产级约定，同时不假设所有应用都需要所有子系统。

2. Write the behavioral contract

2. 编写行为约定

Before implementation, state:

source of truth for state;
user actions and resulting events/state transitions;
loading, empty, disabled, error, and cancellation states;
focus owner, tab order, shortcuts, pointer and touch behavior;
text index units, composition, clipboard, menu, and window ownership when in scope;
resize and scrolling behavior;
material tier and fallbacks;
reduced-motion, opaque, and high-contrast behavior;
target platforms and what must be verified on each.

For a visual translation, add the exact source frame, viewport, theme, fonts, assets, and screenshot evidence.

在实现前，明确：

状态的权威来源；
用户动作及对应的事件/状态转换；
加载、空状态、禁用、错误及取消状态；
焦点所有者、Tab顺序、快捷键、指针及触摸行为；
文本索引单元、输入法候选、剪贴板、菜单及窗口所有权（若涉及）；
缩放及滚动行为；
材质层级及 fallback 方案；
减少动效、不透明及高对比度模式下的行为；
目标平台及每个平台上需要验证的内容。

对于视觉转换任务，需补充精确的源框架、视口、主题、字体、资源及截图证据。

3. Choose the smallest correct GPUI register

3. 选择最小且正确的GPUI注册方式

Use:

an ordinary element tree for normal layout and styling;
```
RenderOnce
```
for stateless, value-like reusable components;
an
```
Entity<T>
```
implementing
```
Render
```
for independently changing state;
a project model entity for shared domain state;
```
canvas
```
or a custom
```
Element
```
only when ordinary layout or painting cannot meet the requirement;
a narrow platform bridge only for behavior GPUI cannot supply.

Do not create an entity for every wrapper. Do not keep meaningful state in ephemeral render-local values. Read architecture-state.md and components-layout.md.

可选择：

普通元素树：用于常规布局与样式；
```
RenderOnce
```
：用于无状态、值类型的可复用组件；
实现
```
Render
```
的
```
Entity<T>
```
：用于独立变更的状态；
项目模型Entity：用于共享领域状态；
```
canvas
```
或自定义
```
Element
```
：仅当常规布局或绘制无法满足需求时使用；
精简的平台桥接：仅用于GPUI无法提供的行为。

切勿为每个包装器创建Entity。切勿将重要状态存储在临时的渲染本地值中。请阅读architecture-state.md及components-layout.md。

4. Implement one vertical slice

4. 实现垂直切片功能

Build one end-to-end path before broad extraction:

Domain state or model operation
Typed action or event
Entity update
```
cx.notify()
```
or emitted event
Rendered default state
Pointer, keyboard, focus, and accessibility behavior
Error/cancellation state
Targeted test

Only extract a reusable component or token after a repeated semantic or visual pattern is proven. Keep public APIs narrow and predictable.

在进行广泛抽象前，先构建一条端到端的路径：

领域状态或模型操作
类型化动作或事件
Entity更新
```
cx.notify()
```
或触发事件
渲染默认状态
指针、键盘、焦点及无障碍行为
错误/取消状态
针对性测试

仅当重复的语义或视觉模式被验证后，再提取可复用组件或标记。保持公共API精简且可预测。

5. Apply Apple design without lying about capability

5. 应用Apple设计风格但不夸大能力

Select the material tier in this order:

Existing system or project component
Native macOS 26+
```
NSGlassEffectView
```
behind an availability boundary
```
NSVisualEffectView
```
or GPUI whole-window blur when that is the actual need
Cross-platform GPUI approximation using semantic tint, border, highlight, shadow, and opacity
Opaque/high-contrast fallback

Do not stack glass on glass. Keep content surfaces mostly solid. Use concentric geometry, restrained tint, adaptive light/dark tokens, and clear elevation. Read apple-glass.md.

按以下优先级选择材质层级：

现有系统或项目组件
受版本限制的原生macOS 26+
```
NSGlassEffectView
```
```
NSVisualEffectView
```
或GPUI全窗口模糊（仅当确实需要时）
使用语义色调、边框、高亮、阴影及透明度的跨平台GPUI近似方案
不透明/高对比度 fallback 方案

切勿叠加多层玻璃效果。保持内容界面基本为实体。使用同心几何布局、克制的色调、自适应明暗标记及清晰的层级。请阅读apple-glass.md。

6. Make interaction physical and interruptible

6. 让交互更具物理感且可中断

Respond on press/down, then commit on release/click.
Keep direct manipulation 1:1 and preserve the grab offset.
Carry velocity from gesture to settling motion.
Retarget from current presentation state and velocity.
Keep input active while motion runs.
Use symmetric enter/exit paths and anchor presentations to their source.
Prefer
```
AnimationExt::with_animation
```
for decorative finite motion when the pinned version supports it; it integrates with GPUI reduced-motion state.
Use explicit state plus frame requests for interactive springs. The bundled spring.rs is a pure-Rust starting point, not a substitute for target-version integration.

Read motion-input.md before implementing custom animation or gestures.

For editable text, native command surfaces, drag/drop, or more than one window, read input-windows.md. Prefer a maintained editor component over implementing the platform input contract from scratch.

在按下时响应，在释放/点击时提交操作。
保持直接操作1:1对应，并保留抓取偏移量。
将手势速度延续到收尾动效中。
根据当前展示状态及速度重新定位。
动效运行时保持输入激活。
使用对称的进入/退出路径，并将展示内容锚定到其来源。
若固定版本支持，优先使用
```
AnimationExt::with_animation
```
实现装饰性有限动效；它会与GPUI的减少动效状态集成。
对于交互式弹簧效果，使用显式状态加帧请求。附带的spring.rs是纯Rust的起点，不能替代目标版本的集成。

在实现自定义动画或手势前，请阅读motion-input.md。

对于可编辑文本、原生命令界面、拖拽或多窗口功能，请阅读input-windows.md。优先使用维护中的编辑器组件，而非从头实现平台输入约定。

7. Protect lifecycle and performance

7. 保护生命周期与性能

Hold a returned
```
Task
```
when dropping it should cancel work; detach only when app-lifetime completion is deliberate and errors are observed.
Hold a
```
Subscription
```
when the observer has an owner; detach only when entity lifetime semantics are correct.
Capture
```
WeakEntity
```
in long-running work.
Use
```
background_spawn
```
for blocking/CPU work and
```
cx.spawn
```
or
```
cx.spawn_in
```
for application-thread orchestration.
Virtualize large collections with
```
list
```
or
```
uniform_list
```
.
Avoid filesystem, network, sleep, parsing, and unbounded allocation in
```
render
```
.
Request animation frames only while something is changing.

Read async-performance.md.

当丢弃任务应取消工作时，保留返回的
```
Task
```
；仅当需要应用生命周期内完成且需监控错误时，才分离任务。
当观察者有所有者时，保留
```
Subscription
```
；仅当Entity生命周期语义正确时，才分离订阅。
在长时间运行的任务中使用
```
WeakEntity
```
。
使用
```
background_spawn
```
处理阻塞/CPU密集型工作，使用
```
cx.spawn
```
或
```
cx.spawn_in
```
处理应用线程编排。
使用
```
list
```
或
```
uniform_list
```
虚拟化大型集合。
避免在
```
render
```
中执行文件系统操作、网络请求、休眠、解析及无限制分配。
仅在内容变化时请求动画帧。

请阅读async-performance.md。

8. Validate in widening rings

8. 逐步扩大验证范围

Run repository-native checks first, then adapt this baseline:

cargo fmt --check
cargo check -p <owning-crate>
cargo test -p <owning-crate>
cargo clippy -p <owning-crate> --all-targets -- -D warnings

Also:

launch the real app;
exercise mouse, keyboard, focus, resize, scroll, and relevant touch paths;
verify light, dark, inactive-window, reduced-motion, opaque, and high-contrast states where supported;
capture matching screenshots for visual work;
check at 1x and a high-DPI scale;
inspect logs and task/error states;
run at least one targeted
```
#[gpui::test]
```
when behavior uses GPUI input, focus, actions, timing, or windows.

Read testing-qa.md and visual-validation.md.

This skill includes a compile-checked, exact-revision fixture at

assets/reference-app

. It demonstrates startup, actions, entity events, owned async work, accessibility, menus, multiple windows, virtualization, preference-aware material fallbacks, and spring orchestration. It is a pattern fixture, not a production component framework. Validate it with:

scripts/validate_reference_app.sh

先运行仓库原生检查，再适配以下基线：

cargo fmt --check
cargo check -p <owning-crate>
cargo test -p <owning-crate>
cargo clippy -p <owning-crate> --all-targets -- -D warnings

同时：

启动实际应用；
测试鼠标、键盘、焦点、缩放、滚动及相关触摸路径；
验证亮色、暗色、非活动窗口、减少动效、不透明及高对比度状态（若支持）；
为视觉工作捕获匹配的截图；
在1x及高DPI缩放比例下检查；
查看日志及任务/错误状态；
当行为涉及GPUI输入、焦点、动作、计时或窗口时，至少运行一个针对性的
```
#[gpui::test]
```
。

请阅读testing-qa.md及visual-validation.md。

本技能在

assets/reference-app

中包含一个经过编译检查的精确修订版示例应用。它展示了启动流程、动作、Entity事件、自有异步工作、无障碍功能、菜单、多窗口、虚拟化、感知偏好的材质fallback及弹簧效果编排。这是一个模式示例，而非生产组件框架。可通过以下命令验证：

scripts/validate_reference_app.sh

Production starter path

生产级初始应用路径

For “create a GPUI app,” “set up a starter,” or “make this starter production-ready”:

Gather the product name, package/binary slug, owned application ID, supported platforms, minimum OS versions, distribution route, durable data, and update owner.
Inspect the target and the exact starter/example commit. Never copy over an existing checkout or delete its Git history without authorization.
Keep the minimal
```
desktop
```
/
```
ui
```
split until domain code proves a separate headless crate.
Pin the Rust toolchain and GPUI Git revision, commit
```
Cargo.lock
```
, and make the first clean CI baseline reproducible.
Rename identity across crates, binary, action namespace, app ID, menus, storage, icons, packaging, and update metadata.
Add observable startup, configuration/migrations, secret storage, lifecycle-owned async work, accessible controls, diagnostics, and recovery only where the product requires them.
Replace the demo with one real vertical slice and test it from domain state through action, GPUI update, persistence/error state, restart, and release launch.
Build, sign, install, upgrade, and exercise real artifacts on every claimed platform. Report cross-compilation separately.

Do not call a raw release binary, a green

cargo check

, or the unmodified minimal example production-ready. Use the complete acceptance matrix in production-starter.md.

对于“创建GPUI应用”、“搭建初始应用”或“将初始应用升级为生产级”的请求：

收集产品名称、包/二进制文件名、所属应用ID、支持平台、最低系统版本、分发渠道、持久化数据及更新负责人信息。
检查目标代码库及初始示例的精确提交记录。未经授权，请勿覆盖现有代码库或删除其Git历史。
在领域代码证明需要单独的无头 crate 前，保持最小的
```
desktop
```
/
```
ui
```
拆分。
固定Rust工具链及GPUI Git修订版，提交
```
Cargo.lock
```
，并创建第一个可复现的干净CI基线。
在所有crate、二进制文件、动作命名空间、应用ID、菜单、存储、图标、打包及更新元数据中统一产品标识。
仅在产品需要时添加可观测的启动流程、配置/迁移、密钥存储、生命周期绑定的异步工作、无障碍控件、诊断及恢复功能。
用一条真实的垂直切片功能替换演示内容，并从领域状态、动作、GPUI更新、持久化/错误状态、重启及发布启动全流程进行测试。
在所有声明支持的平台上构建、签名、安装、升级并测试真实产物。单独报告交叉编译情况。

切勿将原始发布二进制文件、仅通过

cargo check

的代码或未修改的最小示例称为生产级应用。请使用production-starter.md中的完整验收矩阵。

Paper.design path

Paper.design转换路径

For any Paper-to-GPUI request:

Require a live Paper MCP connection and one exact selected frame or node ID.
Verify the open file with
```
get_basic_info
```
and intent with
```
get_selection
```
.
Capture a 2x screenshot, hierarchy, JSX as structural evidence, computed styles, fonts, tokens, and actual exportable assets.
Preserve the GPUI app architecture and translate layout semantics, not DOM wrapper count.
Implement geometry, typography, paint, assets, and interactions in that order.
Compare Paper and native screenshots at matching logical bounds.

If Paper is unavailable, stop the design extraction path and explain how to connect it. Do not recreate the design from memory. Read paper-to-gpui.md and paper-mcp.md.

对于任何Paper转GPUI的请求：

需要有效的Paper MCP连接及精确的选定框架或节点ID。
使用
```
get_basic_info
```
验证打开的文件，使用
```
get_selection
```
确认需求意图。
捕获2x截图、层级结构、JSX结构证据、计算样式、字体、标记及实际可导出资源。
保留GPUI应用架构，转换布局语义而非DOM包装器数量。
按几何布局、排版、绘制、资源、交互的顺序实现。
在匹配的逻辑边界下对比Paper与原生截图。

若无法访问Paper，请终止设计提取流程并说明连接方法。切勿凭记忆重建设计。请阅读paper-to-gpui.md及paper-mcp.md。

Review standard

评审标准

Rank findings by user impact and confidence. Require evidence for claims about:

stale or dropped tasks/subscriptions;
missed
```
cx.notify()
```
calls;
unstable or duplicate element IDs;
focus traps or pointer-only controls;
blocking application-thread work;
unbounded render allocation;
incorrect fixed sizing or clipping;
unsupported blur/material claims;
missing accessibility role, label, state, or action;
animation that ignores reduced motion;
platform API use without availability guards;
green compilation presented as visual or runtime proof.

Do not turn style preferences into correctness findings.

按用户影响及置信度对问题排序。对于以下声明，需提供证据：

任务/订阅过期或丢失；
遗漏
```
cx.notify()
```
调用；
元素ID不稳定或重复；
焦点陷阱或仅支持指针的控件；
阻塞应用线程的工作；
无限制的渲染分配；
不正确的固定尺寸或裁剪；
不支持的模糊/材质声明；
缺失无障碍角色、标签、状态或动作；
忽略减少动效设置的动画；
未加版本限制的平台API使用；
将编译通过视为视觉或运行时正确性的证明。

切勿将风格偏好转化为正确性问题。

Completion report

完成报告

Report:

GPUI version/revision and target platforms;
files and architectural boundaries changed;
material tier and fallback behavior;
interaction, focus, accessibility, async, and performance behavior;
text/IME, command, window lifecycle, and restoration behavior when relevant;
tests, builds, launch, and visual comparisons actually performed;
remaining deltas, unverified platforms, and version-sensitive assumptions.

For the research snapshot behind this skill, read sources.md. Refresh upstream APIs when the target revision differs or the snapshot is no longer current.

After substantial suite changes, run the realistic prompts and reviewer-only rubrics in forward-tests.md with fresh agents. Fix routing or instruction gaps before publishing.

报告内容包括：

GPUI版本/修订版及目标平台；
修改的文件及架构边界；
材质层级及fallback行为；
交互、焦点、无障碍、异步及性能表现；
文本/IME、命令、窗口生命周期及恢复行为（若相关）；
实际执行的测试、构建、启动及视觉对比；
剩余差异、未验证的平台及版本敏感的假设。

如需了解本技能背后的研究快照，请阅读sources.md。当目标修订版与快照不同或快照过时，请更新上游API信息。

在对技能套件进行重大修改后，请使用新代理运行forward-tests.md中的真实提示及评审专用规则。在发布前修复路由或说明中的漏洞。