项目的 README,来自 github.com/vercel-labs/fx0。合并为一个 markdown 文件:README.md。
fx0 is an open-source, lightweight design agent built with libfx. You describe a page and an agent writes it as one HTML file.
fx0 is also a working example of an app built on libfx. One createFxAgent() call gives it the agent loop, streaming, tool calls, retries and durable sessions, and createFxEngine() runs each subagent.
Try it at fx0.vercel.dev, or clone it and make it your own.
FX0_MODEL when it's set.screenshot_design returns images of the published preview to the model, either the visible viewport or the full page in tiles. An optional width captures at that viewport width (320-1920 CSS px), so a design can be compared with a reference at the reference's own width rather than the preview's.design.md styles, or upload your own. The ten styles, and the one-line descriptions in the picker, come from VoltAgent's awesome-design-md, which you can browse at getdesign.md. Thanks to VoltAgent for publishing them.fx0 is the app. libfx is the agent inside it. Vercel keeps the agent's work safe while it runs.
createFxAgent() and passes each chat's messages to it./api/libfx, and libfx continues from the last saved step.fx0 runs one durable libfx agent per server. libfx keeps each chat's conversation as a session and backs every turn with Vercel Queues, so a turn finishes even when the function running it dies. fx0 has no code of its own to recover a turn. Durability takes three pieces.
The agent. fx0 passes no durability option, so createFxAgent() uses libfx's default: on Vercel, libfx keeps its sessions in Vercel's World, the store behind Vercel Workflow, and uses Vercel Queues. libfx bundles both clients, so fx0 neither writes workflows nor calls Vercel Queues itself. A prompt runs its turn in the request that sent it, so the reply starts without a queue hop, and Vercel Queues keeps the prompt as a backstop until just after that request's 800-second limit. fx0 sends a message as a prompt when the chat is idle. One sent while a turn runs or waits to start is a steer instead, which libfx delivers through Vercel Queues to the running turn.
// lib/libfx-agent.ts, simplified
const agent = createFxAgent({
// No durability option: Vercel's World and Queues on Vercel, local files elsewhere.
apiKey: 'session-authenticated',
fetch: chatFetch,
tools,
})
// lib/agent.ts, simplified: a chat gets a libfx session on its first message,
// and each message is one turn of it
const libfxSessionId = await agent.newSessionId()
const session = agent.session(libfxSessionId, { model, instructions, context: { chatId, turnId } })
session.prompt(`[${author}] ${text}`, { messageId: `m${turnId}` })
The route. Vercel Queues delivers the turns no request runs itself to app/api/libfx: the rest of a turn that outlasted its prompt request, and a prompt's backstop when that request died. libfx's handler runs them:
// app/api/libfx/route.ts
export const maxDuration = 800
export const POST = agent().wakeHandler()
The trigger. One entry in vercel.json subscribes that route to libfx's queue topic:
{
"functions": {
"app/api/libfx/route.ts": {
"experimentalTriggers": [{ "type": "queue/v2beta", "topic": "__libfx_wkf_workflow_session", "retryAfterSeconds": 5 }]
}
}
}
fx0 keeps the transcript, designs and settings in Redis. Here is one message from send to reply. The numbers match the steps below:
1. Save the message before answering. POST /api/prompt adds the message to the transcript in one Redis script, then hands it to libfx with its message id. libfx stores it before acknowledging, so a message that shows as sent can't be lost, and a retried request reaches the same turn.
2. Keep the turn's funding. A queue delivery has no browser cookie, so the prompt route seals its funding in Redis. Every message records the funding of the turn it starts: either the admitted sponsorship or its paid sender's OAuth grant and team. Fresh SDK diagnostics and the journal's restore hook identify the executing turn after a crash. Refresh tokens stay in the cookie, and the server trial key stays out of every stored credential. Missing or expired trial funding never falls back to a customer's paid grant.
3. libfx runs the turn. One worker holds a session at a time, and libfx fences out any other. The prompt request runs the turn first; it and each delivery to /api/libfx can run for 800 seconds, their maxDuration. libfx stops a turn 30 seconds before that limit, keeping what it has done so far, and a delivery to /api/libfx continues it, so a long turn spans several invocations.
4. Copy the stream into the transcript. Any route following the chat, the prompt's own response or an open tab, copies libfx's stream into the transcript. A cursor check makes each line land once, however many follow. The same Redis script marks a turn running when its start lands, and when its end lands it leaves the turn's history to write, with the design the turn left. The copy then writes that history and design version to Neon, and a write that fails waits in Redis for the next copy to retry.
5. Pick up where it stopped. On Vercel, libfx can't tell a crashed function from a slow one, so the request running a turn holds its session until its time limit. The prompt's backstop comes due 5 seconds after that limit: if the request died, the backstop takes the session over and the turn continues where its records end. In a delivery to /api/libfx, a process that exits has its delivery run again about a second later, and a function that stops without exiting holds its message until the queue's hold runs out, up to five minutes. The model is told the turn was interrupted, so it can check what happened before going on. A function that only stalled and wakes after that stops at its next write, so two never write at once.
A tool call the crash cut off runs again only if it's safe to repeat. libfx refuses a tool that doesn't say which it is, and fx0 marks its tools in lib/libfx-agent.ts: reading the design, publishing it, fetching a page, paging through a tool result and searching the tools run again. Edits, questions and subagents don't, so the model is told those calls may have run and decides what to do. The reads start as soon as the model asks for them, while libfx saves the call.
A subagent is an in-memory createFxEngine() inside its tool call, billed to the same chat. It has the same design tools, except that it can't start a subagent of its own. Its model requests count toward the parent turn's 64 steps, in a count kept in Redis (lib/turn-budget.ts), so subagents can't multiply what one turn spends. A retried or recovered request counts once.
TL;DR:
You can watch this happen. Open session diagnostics from the header to see the chat's libfx session, its running turn and how far the transcript has copied libfx's stream.
/api/libfx.| Path | What's there |
|---|---|
lib/agent.ts |
Each chat's prompts, questions, cancel, deletion and sign-out |
lib/libfx-agent.ts |
The durable agent, its per-chat fetch and its tools |
lib/projector.ts |
Copies a chat's libfx stream into its transcript |
lib/turn-credential.ts |
The sealed credential each chat's turns bill |
lib/trial.ts |
Guest identities and the atomic per-IP trial allowance |
lib/journal.ts |
The Redis journal. Every write is a single Lua script, so it's atomic. |
app/api/libfx/ |
Where Vercel Queues delivers libfx's turns |
lib/tools.ts |
The agent's tools: read, publish and edit the design, fetch a URL, ask a question, page through a long tool result, search the available tools and start a subagent. AI Gateway's web search runs beside them. |
lib/design-artifact.ts |
Checks that a design is one HTML file of at most 512 KB, with no external assets |
app/api/ |
Route handlers. Chat routes check sign-in and ownership before anything else. |
components/ |
The chat, composer, preview and diagnostics panel |
Neon Postgres holds accounts, who owns each chat, finished turns and every design version (migrations/).
The agent can use a Google Fonts stylesheet in <head>, for example:
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap">
<style>body { font-family: 'Inter', sans-serif; }</style>
fx0 resolves at most four stylesheet URLs and embeds their Latin WOFF2 faces before the design runs, including when copying or downloading a live or historical design. The model-written HTML stays small and editable. @import is supported too. The existing FX0_REMOTE_IMAGES=0 switch also disables font downloads.
Each stylesheet has a five-second total download deadline, at most 16 font files with four in flight, a 256 KiB per-file cap and a 512 KiB embedded-byte budget. The combined font CSS is capped at 768 KiB per rendered design. Font requests use HTTPS, stay on the expected Google origin at every redirect, and retain the public-IP and pinned-DNS checks. The preview's CSP remains font-src data: and connect-src 'none'.
The shared Runtime Cache avoids repeated downloads; unavailable or over-budget faces fall back to the CSS font stack. Font-bearing preview HTML uses no-store rather than a revision-only ETag, so a reload can recover fonts without editing the design. Embedded faces use an unconditional CSS style, adding one when necessary; that insertion can require a full preview reload instead of a hot update. History preserves the design's HTML, not a snapshot of its external resources: after cache revalidation, Google's stylesheet may resolve to a different font version, just as a remote image can change. Successful exported fonts are embedded in the downloaded file; failed ones are removed rather than left as external links. Other writing systems and fully frozen resource history are outside this feature's scope.
You'll need Node.js 24 and three services:
openid profile email offline_access and the permissions AI Gateway: Use and Team: Read Only. Add http://localhost:3000/api/auth/callback as a callback URL. Don't leave out offline_access: without it, Vercel sends no refresh token and sign-in fails.Copy .env.example to .env.local and fill it in. SESSION_SECRET has to be a random string of at least 32 characters. If your local app shares Redis with a deployment, set FX0_REDIS_PREFIX (for example fx0:local) to keep the chats apart. FX0_MODEL changes the model new chats start on.
npm ci
npm run db:migrate
npm run dev
db:migrate applies the files in migrations/ in order. Each one is idempotent, so running it twice is fine. The app never migrates on its own.
Set the same variables on Vercel. The Neon and Upstash integrations in the Vercel Marketplace fill in DATABASE_URL, KV_REST_API_URL and KV_REST_API_TOKEN for you. Set APP_URL to your production URL and add <APP_URL>/api/auth/callback to your Sign in with Vercel app.
OAuth redirects never trust the request's Host header. They go to APP_URL, or, on a preview deployment without one, to that deployment's own Vercel URLs.
To enable the free trial, apply the migrations, set FX0_FREE_PROMPTS=1 and a server-only AI_GATEWAY_API_KEY, then rebuild and deploy. BotID's client protection and server verification are included. Production uses Vercel's trusted client IP; local development shares one local allowance. Keep local Redis prefixes separate from production.
npm run typecheck # generates the route types, then runs tsc
npm run test:core
npm run test:auth
npm run build
npm run test:smoke # runs the production build with fake sessions
npm run test:journal:integration # needs KV_REST_API_URL/TOKEN, writes under its own prefix
npm run test:trial:integration # needs local redis-server/redis-cli; no remote services
npm run test:artifact:browser # needs local Chrome (or CHROME_PATH); checks design CSP enforcement
npm run test:budget:integration # needs local redis-server/redis-cli; no remote services
npm run test:turns:integration # needs local redis-server/redis-cli; no remote services
The auth and route tests mock Vercel, AI Gateway and both databases, so check a real sign-in and real billing on a deployment.
Authentication diagnostics use auth:request:* and auth:credential:* events in runtime logs. Each API request gets a server-generated request ID. The UI also sends a document-local ID, prerender state and visibility; these are diagnostic hints, not proof of authentication or a shared browser profile.
Fingerprints are 24 hexadecimal characters of HMAC-SHA-256, with a separate logging subkey derived from SESSION_SECRET and separate domains for users, logins, refresh tokens, cookies and pages. Missing or invalid key material produces null, never an unkeyed hash or the original value. Rotating SESSION_SECRET changes the fingerprints; older unkeyed tags cannot be compared directly with these tags. Logs remain pseudonymous operational data: restrict access, keep retention limited to operational needs, and do not publish production logs in public issues or PRs.
auth:request:received records keyed login, grant-cookie and refresh-token fingerprints on every wrapped request, including requests that do not renew.auth:credential:read, selected and publish show whether Redis supplied a newer credential, a publication lost a race, or logout fenced it. read_failed, invalid and publish_failed identify recovery failures without exception contents.auth:request:response records the selected token, status, whether the handler ran, and the final prepared grant-cookie header: grantCookieAction, preparedGrantCookie and preparedRt.Compare a response's preparedRt with later requests' rt. A matching preparedGrantCookie / grantCookie also confirms that exact sealed cookie returned. If a new generation returns and an old one later reappears, the logs establish a rollback or a different request context. If the new generation never returns, server logs alone cannot distinguish a lost response from browser cookie rejection or no further requests. Header preparation is not delivery or browser acceptance.
purpose and secPurpose contain only recognized directives; prerender: null means unknown. Native navigation and iframe requests may have no UI page context. No plaintext tokens, cookies, authorization headers, query strings or exception details are logged.
Pending publication binds both the prior sealed state and the token consumed by the exchange, so a differently sealed predecessor can be repaired without replaying it. The token commitment stays inside the encrypted pending cookie and is not logged. Older pending cookies lack that commitment: exact-state repair and an already-published successor still work, but ambiguous state changes return 503 with the pending credential preserved. Such older ambiguous grants may require signing in again; a different seal alone does not prove a newer token.
Generated pages run in a sandboxed iframe on an opaque origin. They can't read the app's cookies, storage or credentials, and their Content Security Policy blocks network requests (connect-src 'none'). It's still the browser enforcing all of this, though, not a sealed VM.
Paid model requests carry the sender's OAuth token only to AI Gateway. Between requests it stays sealed in Redis and expires with the token. Sponsored requests require a recorded trial admission; the server key is never sent to a browser, cookie, journal or model prompt. Signing out deletes that login's stored credentials and revokes its token. A running turn it funded stops at its next model request; another login's turns keep running. Treat the session cookie and SESSION_SECRET as credentials.
Apache-2.0. The design.md styles in lib/design-md/ come from VoltAgent/awesome-design-md, under the MIT license.