菜单
How an AI agent converts mockup HTML into ato-desktop's GPUI Rust components. Use the external `gpui-html` CLI to lower HTML to a Rust builder skeleton; integrate it into production components by hand — do NOT add an HTML parser to ato-desktop.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Deploy and release ato-cli using gh and sleep across dev, main, and tagged GitHub Releases. Use when pushing release-related changes, creating dev-to-main PRs, monitoring required GitHub checks, merging after green, dispatching the Release PR or release-tag workflow via workflow_dispatch, handling release-plz PRs, creating patch bump PRs after version collisions, and verifying the published GitHub Release assets.
Release ato-cli or nacelle end-to-end using gh and sleep until the final GitHub Release is published. Use when pushing release-related changes, creating and monitoring PRs, handling ato-cli release-plz PRs, tagging ato-cli or nacelle, watching release workflows, verifying GitHub Release assets, and recovering from version or tag collisions.
Open a GitHub issue on ato-run/ato distilled from the current session. Use when the user says "issueを作成", "issue化", "open an issue", "file a bug", or otherwise asks to capture a problem/idea uncovered in conversation. Writes the issue in English, attaches the right area:/topic:/platform: labels, and uses the standard ato body template.
Cut a new ato-run/ato release. Merges dev into main, bumps the four dist-tracked crates in lockstep, tags from main, monitors desktop-release.yml + cargo-dist release.yml, and recovers from known failure modes (frontend dist, 403 on host, draft/published race, same-version retry). Use whenever the user says "リリースする", "devの変更をmainに入れてリリース", "cut a release", or `curl install.sh` is broken because of missing assets.
Drive the running ato-desktop (GPUI/Focus mode) end-to-end through the ato-desktop-mcp bridge to exercise real user flows: open a capsule, satisfy config/consent/secret gates, reopen an installed app via ato://app/<ipk>, stop/restart sessions, and inspect both guest WebViews and the GPUI host surface. Use for AODD-style operation, not unit tests.
Agent Operation Driven Development (AODD). Drive product development from agent operation reports instead of pre-written specs or assertions — the operation itself is the development input, the way a failing test is in TDD. Have an autonomous agent operate the real user-facing surface of an application, observe where it gets stuck, and turn those frictions into a Usecase Receipt that becomes the next development input. USE FOR: agent-driven UX evaluation, end-to-end feasibility checks for real users, finding usability and onboarding frictions an agent (or first-time user) actually hits, prioritizing fixes by what blocks autonomous completion. DO NOT USE FOR: unit-test authoring, pure regression coverage of known flows (use E2E tests instead), or one-shot bug fixes with a known repro.
| name | ato-desktop-gpui-html-workflow |
| description | How an AI agent converts mockup HTML into ato-desktop's GPUI Rust components. Use the external `gpui-html` CLI to lower HTML to a Rust builder skeleton; integrate it into production components by hand — do NOT add an HTML parser to ato-desktop. |
| audience | agents working on ato-desktop UI |
When the user hands you HTML/CSS for a desktop UI element (sidebar tab,
modal, chrome bar, …) and asks you to ship it as a GPUI component
inside crates/ato-desktop, do not parse the HTML yourself, and do
not add a parser dependency to this crate. Use the external
gpui-html compiler to lower
the HTML to a GPUI builder Rust skeleton, then integrate that skeleton
into a hand-written production component.
gpui-html-core owns "HTML → GPUI builder Rust". ato-desktop owns
"GPUI builder Rust → production component wired to live AppState,
theme, assets, and input handlers". The two surfaces evolve at
different rates:
AppState, Workspace, Pane, action enum, BridgeProxy, …).If ato-desktop took a gpui-html-core dependency directly, every
spec edit on the parser side would bounce the desktop crate's build,
and agents would be tempted to call the lowering pipeline at runtime
("compile mockup at startup") — which is the wrong architecture.
gpui-html is a build-time / design-time tool, not a runtime
dependency.
gpui-html is responsible for<html>, <head>, <body>,
<script>, <style> are accepted and the boilerplate is stripped).<style> rules to GPUI builder method calls.flex, gap-2, bg-accent, …).gpui::div().flex().child(…)
style builder chains.The generated output is the truth source for visual structure.
ato-desktop is responsible forsrc/ui/.Theme adapter
(src/ui/theme.rs) — generated code references theme.<token>,
which must resolve against the real Theme struct fields.img(src=…) references are placeholders.crate::app::CloseTask,
SelectTask, MoveTask, ShowSettings, …).Stateful/InteractiveElement where needed, replacing
generated div().child(…) chains with real Image/Icon/Stateful
primitives where mockup placeholders don't translate 1:1.ato-desktop MUST NOT dogpui-html-core as a dependency in Cargo.toml.src/. If you see yourself reaching for regex/scraper/a
hand-rolled tokenizer to consume HTML, stop and run the gpui-html
CLI instead..rs files to the crate. The
workflow uses .tmp/ (gitignored) for intermediate artifacts; only
the hand-integrated component code lands in src/.gpui-html lives in a separate repository. Install it once per dev
machine:
cargo install --git https://github.com/ato-run/gpui-html gpui-html
After install, gpui-html --version should print a 0.x version.
If the CLI isn't installed and the user expects you to install it for
them, ask first — cargo install writes to ~/.cargo/bin/ and is a
durable side effect.
Use a gitignored scratch area so intermediate artifacts don't pollute
the crate. The crate's .gitignore already excludes .tmp/; if it
doesn't, add the entry.
mkdir -p .tmp/gpui-html
cat > .tmp/gpui-html/mockup.html <<'EOF'
<!-- paste the mockup HTML here -->
EOF
If the user pasted HTML directly in chat, write it to the file with
the Write tool rather than cat-piping a heredoc — heredocs choke
on backtick-fenced content inside the HTML.
gpui-html needs to know the host's color tokens to validate
bg-<token> / text-<token> / border-<token> references and to
lower bg-<token>/<alpha> to packed RGBA literals. The manifest is
TOML and lives next to the mockup:
cat > .tmp/gpui-html/theme.toml <<'EOF'
[colors]
# Mirror the fields in src/ui/theme.rs that the mockup references.
# Hex values must match the live Theme so the generated literals match
# the runtime colors.
base = "#09090b"
surface = "#18181b"
accent = "#6366f1"
"accent-foreground" = "#ffffff"
[max-width]
# Custom Tailwind scale entries (e.g. max-w-128) — mirror the mockup's
# Tailwind config.
"128" = "32rem"
EOF
src/ui/theme.rs is the authoritative list of theme fields. If the
mockup references a token that isn't in Theme, decide explicitly:
add it to Theme (production change) or rewrite the mockup to use an
existing token (mockup change). Do not silently invent fields in the
manifest just to make the compile succeed.
gpui-html compile .tmp/gpui-html/mockup.html \
--manifest .tmp/gpui-html/theme.toml \
-o .tmp/gpui-html/mockup.rs
Use check if you only need diagnostics (no output file):
gpui-html check .tmp/gpui-html/mockup.html \
--manifest .tmp/gpui-html/theme.toml
JSON diagnostics (one per stderr line) for editor / CI parsing:
gpui-html check .tmp/gpui-html/mockup.html \
--manifest .tmp/gpui-html/theme.toml \
--format json
Exit codes: 0 success, 1 compile error (parse / class / CSS),
2 usage error (missing file, bad manifest).
If lowering fails with UnknownThemeToken or UnknownClass:
UnknownThemeToken → the token isn't in the manifest or the live
Theme. Add it to both, or change the mockup to use an existing
token.UnknownClass with a "palette" hint → the mockup is using a raw
Tailwind palette (e.g. bg-red-500). Replace with a semantic theme
token (bg-rose, bg-status-error) added to Theme.UnknownClass with a "needs manifest" hint → custom-scale sizing
(e.g. max-w-128) without a manifest entry. Add it.UnsupportedCssDeclaration / UnsupportedCssValue → the <style>
block uses something gpui-html doesn't lower yet. Either rewrite
the rule as utility classes (preferred) or accept that the rule
will need a hand translation during integration.Resist the urge to "fix" lowering errors by editing
crates/ato-desktop/. The fixes belong in the mockup, the manifest,
or upstream in gpui-html's spec — never in this crate.
Open .tmp/gpui-html/mockup.rs and the target file under
src/ui/<area>/. The generated source is a single expression chain
like:
div()
.flex()
.flex_col()
.gap_2()
.bg(theme.surface)
.child(div().text_color(theme.body).child("Hello"))
Port this into a Render impl by hand. Tasks at this step:
theme.<token> reads with the live Theme struct in scope
(super::theme::Theme is the canonical import path).task.title, task.favicon, …).InteractiveElement wrappers (on_click, on_mouse_down) for
any element the mockup represents as interactive. Hover/group
behavior, drag-and-drop, keyboard focus all live here — gpui-html
doesn't emit them.IntoElement impls
if the production component is large enough to warrant it.<img> placeholder where production uses gpui_component:: Icon), prefer the production primitive over forcing the generated
shape.Delete .tmp/gpui-html/mockup.rs once the production component is
in place — it's not a source of truth, only an intermediate artifact.
Run the standard checks for the touched module:
cargo check
cargo clippy
cargo test
If the component renders, smoke-test it via cargo run and confirm
visual parity with the mockup. The mockup HTML can be opened in any
browser side-by-side — that's why mockup.html and desktop-mock.html
live in this crate's root.
gpui-htmlIf you find yourself repeatedly hand-translating the same construct
out of the generated code (e.g. a particular shadow utility, an
event handler attribute, a layout primitive), that's signal for an
upstream feature request in ato-run/gpui-html. Open an issue there
with a minimal repro before working around it locally.
If the mockup uses a feature gpui-html silently passes through (e.g. a CSS rule in lenient mode), the production component must translate it by hand — don't claim "the compiler handled it".
| Action | Command |
|---|---|
| Install CLI | cargo install --git https://github.com/ato-run/gpui-html gpui-html |
| Compile HTML | gpui-html compile <html> --manifest <toml> -o <out.rs> |
| Check (no output) | gpui-html check <html> --manifest <toml> |
| JSON diagnostics | gpui-html check <html> --manifest <toml> --format json |
| Scratch dir | .tmp/gpui-html/ (gitignored) |
| Theme fields | src/ui/theme.rs |
| Production UI root | src/ui/ |