higgsfield-websites

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent guide — Higgsfield website (full-stack, server-rendered)

Agent指南 — Higgsfield网站（全栈、服务器渲染）

You are editing ONE per-website Cloudflare Worker: a React 19 + TanStack Start app that is server-rendered (SSR) and deploys as a single Worker served at the website's own subdomain. The look of the site is composed from the wow-maker toolkit (see rule 0). The rules below are hard constraints — breaking them ships a broken or insecure website.

Scope: build the real, full app — and make it WOW. This stack ships complete, production-grade applications: real frontend AND backend, database (D1), file storage (R2), auth, third-party API integrations, and background work. When the user describes an app, tool, site, or web product, BUILD IT directly with the website builder — it is the default for any web app, site, or tool. Never ask the user to confirm the platform or build target (e.g. "is this a Higgsfield website-builder site, or something else?"), never ask whether they "really" want an app, never downgrade to a "demo" or mockup as the safe option, and don't stall on scope questions. Take the fullest reasonable interpretation of the request, fill gaps with sensible defaults, and ship a working preview. Ask at most ONE short clarifying question — and only when the ambiguity genuinely changes what you'd build and no sensible default exists; otherwise build first and iterate with the user on the live result.

"Build it" INCLUDES "make it wow" — wow is part of DONE, not optional polish. A real, working app that is a flat page of default components is NOT done; by this skill's standard it is a failure. Do the wow pass as a first-class part of every build, not something you add later or skip under time pressure (and never silently judge it "optional" because the brief feels restrained — see rule 0). Read

references/wow-maker.md

and hit its minimum wow bar before you consider the site finished.

Repo layout. The website project lives in app/
— its own

package.json

src/

packages/

migrations/

, build config, and the deploy inputs (

app.manifest.json

wrangler.jsonc

). Run every

bun

/build command from there. There are no per-template setup files to hunt for — everything you need to build is in this skill (

website-builder-flow

) and its

references/

Higgsfield infrastructure (what these names mean). The website you build integrates with Higgsfield's platform through three pieces — all are Higgsfield's own infra, not third-party libraries:

fnf — Higgsfield's backend API. The product's generation, media, profile, workspace, credits, and auth all live behind it. Server code reaches it at
```
https://fnf.internal/*
```
(the platform injects the user's auth on server egress).
```
@higgsfield/fnf
```
is the SDK and
```
@higgsfield/fnf-react
```
its React bindings (both vendored in
```
app/packages/
```
).
Quanta (
```
@higgsfield/quanta
```
) — Higgsfield's app UI design system: tokens and components for product surfaces. Use it only for app surfaces that integrate the Higgsfield fnf SDK — generation consoles and fnf-backed tools (image/video generation, media, profile, workspace, credits). Everything else — marketing/landing pages, portfolios, and general SaaS/dashboards/tools that do NOT use the SDK — are built with custom Tailwind/CSS (per wow-maker), not Quanta. Vendored in
```
app/packages/quanta
```
.
fnf-web — the main Higgsfield web app/repo that owns these packages upstream. You don't edit it; it's the source of truth the vendored
```
app/packages/*
```
snapshots come from.

你正在编辑每个网站对应的单个Cloudflare Worker：这是一个基于React 19 + TanStack Start的服务器渲染（SSR）应用，部署为单个Worker并通过网站自身的子域名提供服务。网站的视觉效果由wow-maker工具包构建（参见规则0）。以下规则为硬性约束——违反规则会导致网站出现故障或安全问题。

范围：构建真实的完整应用，并打造令人惊叹的效果。 该技术栈可交付完整的生产级应用：包含真实的前端和后端、数据库（D1）、文件存储（R2）、认证、第三方API集成以及后台任务。当用户描述一个应用、工具、站点或Web产品时，直接使用网站构建器进行构建——这是任何Web应用、站点或工具的默认选择。绝不要询问用户是否确认平台或构建目标（例如：“这是Higgsfield网站构建器站点，还是其他类型？”），绝不要询问用户是否“真的”想要一个应用，绝不要默认降级为“演示版”或原型，也不要在范围问题上停滞不前。对请求做出最合理的完整解读，用合理的默认值填补空白，并交付可运行的预览版本。最多提出一个简短的澄清问题——且仅当歧义确实会改变你要构建的内容，且不存在合理默认值时才提问；否则先构建，再根据用户反馈在实时结果上迭代。

“构建完成”包括“打造惊艳效果”——惊艳效果是完成标准的一部分，而非可选的润色。 一个仅由默认组件组成的扁平页面的真实可运行应用不算完成；按照本技能的标准，这是失败的。将惊艳效果作为每个构建流程的核心环节，而非事后添加或因时间紧张而跳过的内容（绝不要因为需求看起来克制就默认认为惊艳效果是“可选的”——参见规则0）。阅读

references/wow-maker.md

，在认为网站完成前达到其最低惊艳标准。

仓库布局。网站项目位于**

app/

**目录下——包含独立的

package.json

、

src/

、

packages/

、

migrations/

、构建配置以及部署输入文件（

app.manifest.json

、

wrangler.jsonc

）。所有

bun

/构建命令都从该目录运行。无需查找每个模板的设置文件——构建所需的所有内容都在本技能（

website-builder-flow

）及其

references/

目录中。

Higgsfield基础设施（术语含义）。你构建的网站通过三个部分与Higgsfield平台集成——所有这些都是Higgsfield自身的基础设施，而非第三方库：

fnf —— Higgsfield的后端API。产品的生成、媒体、个人资料、工作区、积分和认证等功能均基于此。服务器代码通过
```
https://fnf.internal/*
```
访问该API（平台会在服务器出站时注入用户的认证信息）。
```
@higgsfield/fnf
```
是对应的SDK，
```
@higgsfield/fnf-react
```
是其React绑定（两者均托管在
```
app/packages/
```
目录下）。
Quanta（
```
@higgsfield/quanta
```
）—— Higgsfield的应用UI设计系统：用于产品界面的令牌和组件。仅在集成Higgsfield fnf SDK的应用界面中使用它——例如生成控制台和基于fnf的工具（图片/视频生成、媒体、个人资料、工作区、积分）。其他所有场景——营销/着陆页、作品集以及不使用SDK的通用SaaS/仪表盘/工具——均使用自定义Tailwind/CSS（遵循wow-maker规范），而非Quanta。托管在
```
app/packages/quanta
```
目录下。
fnf-web —— 上游托管这些包的主Higgsfield Web应用/仓库。你无需编辑它；它是
```
app/packages/*
```
目录下快照的数据源。

Prerequisites

前置条件

You drive the whole lifecycle through the

higgsfield

CLI, then edit code on the local filesystem with

git

bun

higgsfield

is not on

$PATH

, install it:

bash

curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh

higgsfield account status

reports

Session expired

Not authenticated

, ask the user to run

higgsfield auth login

(interactive) and wait for confirmation.

```
git
```
and
```
bun
```
are used locally once you clone the repo (lifecycle step 2). The CLI itself handles create / deploy / status / db / secrets / delete.

你通过

higgsfield

CLI驱动整个生命周期，然后使用

git

bun

在本地文件系统上编辑代码。

如果

higgsfield

不在

$PATH

中，请安装它：

bash

curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh

如果

higgsfield account status

显示

Session expired

Not authenticated

，请让用户运行

higgsfield auth login

（交互式）并等待确认。

克隆仓库后（生命周期步骤2），本地会使用
```
git
```
和
```
bun
```
。CLI本身负责创建/部署/状态/数据库/密钥/删除等操作。

UX Rules

UX规则

Be concise. No raw website IDs, tokens, or JSON dumps in chat. After a deploy, return the preview URL (from
```
higgsfield website status
```
) and a one-line summary.
Never echo the scoped git token back to the user, and never commit it to the repo.
Detect the user's language from the first message and reply in it. CLI flags and code stay English.
Don't stall on scope questions or ask the user to confirm the platform/build target — build the fullest reasonable interpretation and iterate on the live preview. At most ONE clarifying question, only when no sensible default exists.
Preview is the default and the only environment you deploy on your own. Deploy
```
--env production
```
ONLY when the user explicitly asks to publish / go live / ship.
Don't screenshot the deployed site unless the user asks — return the URL.

保持简洁。聊天中不要显示原始网站ID、令牌或JSON转储内容。部署完成后，返回预览URL（来自
```
higgsfield website status
```
）和一行摘要。
绝不要将范围限定的git令牌回显给用户，也不要将其提交到仓库。
根据用户的第一条消息检测其语言，并使用该语言回复。CLI标志和代码保持英文。
不要在范围问题上停滞不前，也不要询问用户是否确认平台/构建目标——构建最合理的完整版本并在实时预览上迭代。最多提出一个澄清问题，仅当不存在合理默认值时才提问。
预览是默认环境，也是你自行部署的唯一环境。 仅当用户明确要求发布/上线/交付时，才使用
```
--env production
```
部署到生产环境。
除非用户要求，否则不要对部署的网站截图——返回URL即可。

Website lifecycle (CLI)

网站生命周期（CLI）

Every hosted website tool maps to a

higgsfield website …

subcommand. The build/edit loop is: create → repo-access → clone → edit → commit + push → deploy preview.

Create the website + its git repo. Prints a
```
website_id
```
(add
```
--json
```
for the raw object). Use that id in every later command.
bash
```
higgsfield website create
```
Get repo access — clone URL, branch, slug, and a scoped git token. Clone into a directory named after the slug so multiple sites can share the workspace. Pass the token via a per-command header so it never lands in
```
.git/config
```
.
bash
```
higgsfield website repo-access <website_id> --json
# with the returned repo_url / branch / slug / token:
git -c http.extraHeader="Authorization: token <token>" clone <repo_url> <slug> && cd <slug>
```
The project lives in
```
app/
```
(see Repo layout below).
Edit the code under
```
app/
```
, following the rules below (Stack, Hard rules, wow-maker design pass, auth, …).

Commit + push. Run push as its own step and confirm it succeeded — the deploy builds from the pushed branch.

bash

git add -A && git commit -m "<what changed>"
git -c http.extraHeader="Authorization: token <token>" push origin <branch>

Deploy the preview (default). The platform CI builds from the pushed branch and returns the build result; a build/type error surfaces here.
bash
```
higgsfield website deploy <website_id> --env preview
```
Deploy production ONLY on an explicit publish/go-live request:
```
--env production
```
.
Status / live URLs any time:
bash
```
higgsfield website status <website_id>
```

Other commands (all take

<website_id>

; add

--json

for machine-readable output):

Database (read-only D1):

higgsfield website db tables <id>

db schema <id> --table <t>

db rows <id> --table <t> [--limit N] [--filter col:op[:value]]

db query <id> --sql "SELECT …"

(single read-only

SELECT

WITH

Secrets (staged until the next deploy):

higgsfield website secrets set <id> --name NAME --value VALUE

secrets list <id>

secrets delete <id> --name NAME

List / delete:
```
higgsfield website list
```
;
```
higgsfield website delete <id>
```
permanently removes the site, database, storage, and repo — only on an explicit delete request.

每个托管网站工具都对应

higgsfield website …

子命令。构建/编辑流程为：创建 → 获取仓库权限 → 克隆 → 编辑 → 提交并推送 → 部署预览。

创建网站及其git仓库。输出
```
website_id
```
（添加
```
--json
```
可获取原始对象）。后续所有命令都使用该ID。
bash
```
higgsfield website create
```
获取仓库权限——克隆URL、分支、slug和范围限定的git令牌。克隆到以slug命名的目录中，以便多个站点共享工作区。通过每个命令的头信息传递令牌，使其不会保存到
```
.git/config
```
中。
bash
```
higgsfield website repo-access <website_id> --json
# 使用返回的repo_url / branch / slug / token：
git -c http.extraHeader="Authorization: token <token>" clone <repo_url> <slug> && cd <slug>
```
项目位于
```
app/
```
目录下（参见下方仓库布局）。
编辑
```
app/
```
目录下的代码，遵循以下规则（技术栈、硬性规则、wow-maker设计规范、认证等）。

提交并推送。单独运行推送步骤并确认成功——部署会基于推送的分支构建。

bash

git add -A && git commit -m "<变更内容>"
git -c http.extraHeader="Authorization: token <token>" push origin <branch>

部署预览（默认）。平台CI会基于推送的分支构建并返回构建结果；构建/类型错误会在此处显示。
bash
```
higgsfield website deploy <website_id> --env preview
```
仅当用户明确要求发布/上线时，才部署到生产环境：
```
--env production
```
。
随时查看状态/实时URL：
bash
```
higgsfield website status <website_id>
```

其他命令（均需传入

<website_id>

；添加

--json

可获取机器可读输出）：

数据库（只读D1）：

higgsfield website db tables <id>

、

db schema <id> --table <t>

、

db rows <id> --table <t> [--limit N] [--filter col:op[:value]]

、

db query <id> --sql "SELECT …"

（仅支持只读

SELECT

WITH

语句）。

密钥（暂存至下次部署）：

higgsfield website secrets set <id> --name NAME --value VALUE

、

secrets list <id>

、

secrets delete <id> --name NAME

。

列出/删除：
```
higgsfield website list
```
；
```
higgsfield website delete <id>
```
会永久删除站点、数据库、存储和仓库——仅在用户明确要求删除时使用。

Stack

技术栈

TanStack Start (file-based routing under
```
app/src/routes/
```
, SSR via
```
app/src/server.ts
```
→ a Worker
```
export default { fetch }
```
). No Next/Remix/Astro conventions, no
```
app/src/pages
```
.
Vite 7 + bun. Build emits
```
dist/server/server.js
```
(the Worker) +
```
dist/client
```
(hashed static assets). Tailwind v4 is wired in
```
app/src/styles.css
```
(it also imports Quanta's Tailwind entry for the template bundle). Legacy shadcn/ui files may exist from the scaffold. Higgsfield-SDK app surfaces (generation consoles, fnf-backed tools) use Quanta components/tokens; every other site (marketing, landing, general SaaS/dashboards/tools, portfolios) uses custom Tailwind/CSS (per wow-maker) — do not import
```
@higgsfield/quanta/*
```
for page chrome, heroes, or marketing sections.
No separate Hono/Express backend. Server logic is TanStack server functions (
```
createServerFn
```
) and server routes. App-local API routes are allowed when a platform contract requires them, for example
```
GET /api/user
```
as the browser-safe proxy to
```
https://fnf.internal/user
```
.

TanStack Start（
```
app/src/routes/
```
目录下的基于文件的路由，通过
```
app/src/server.ts
```
实现SSR → Worker的
```
export default { fetch }
```
）。不遵循Next/Remix/Astro约定，无
```
app/src/pages
```
目录。
Vite 7 + bun。构建输出
```
dist/server/server.js
```
（Worker） +
```
dist/client
```
（带哈希的静态资源）。Tailwind v4已在
```
app/src/styles.css
```
中配置（它还导入了Quanta的Tailwind入口用于模板包）。脚手架中可能存在遗留的shadcn/ui文件。Higgsfield-SDK应用界面（生成控制台、基于fnf的工具）使用Quanta组件/令牌；其他所有站点（营销、着陆页、通用SaaS/仪表盘/工具、作品集）使用自定义Tailwind/CSS（遵循wow-maker规范）——不要为页面框架、首屏或营销部分导入
```
@higgsfield/quanta/*
```
。
无独立的Hono/Express后端。服务器逻辑通过TanStack服务器函数（
```
createServerFn
```
）和服务器路由实现。当平台协议要求时，允许使用应用本地API路由，例如
```
GET /api/user
```
作为浏览器可访问的代理，指向
```
https://fnf.internal/user
```
。

Hard rules

硬性规则

0. Design: build a WOW site from the wow-maker toolkit

0. 设计：基于wow-maker工具包打造令人惊叹的站点

There are no fixed templates. For EVERY build — marketing site, app, dashboard, or the simplest landing — your design source is references/wow-maker.md
: the single directory of everything that makes a site wow (bespoke AI-generated assets, signature animation patterns, motion/3D libraries, and copy-paste component/block registries, all free + permissively licensed). Read it FIRST and compose a distinctive site from it; every site must ship a real wow moment. Do NOT ship generic scaffolding, and do NOT search the skill library for other design guidance (no

popular-web-designs

design-md

, external landing-page skill) — everything is in wow-maker.

Our biggest edge: generate bespoke assets (images, video loops, 3D, OG) with the Higgsfield generation tools — a site with real generated art looks far cooler than stock or CSS-only visuals, and the agent under-uses this. wow-maker §1 has the pipeline; treat asset generation as a default step on every build.

After wow-maker, read exactly ONE craft skill for HOW to execute with taste — which one depends on whether the site integrates the Higgsfield SDK:

Default — any site that does NOT use the Higgsfield SDK (marketing/landing pages, portfolios, general SaaS/dashboards/tools): read references/design-taste-frontend.md
(the anti-"AI-slop" craft playbook) and build custom Tailwind/CSS components. Do NOT import
```
@higgsfield/quanta/*
```
, and do NOT use
```
minimalist-ui
```
.
Higgsfield-SDK app surfaces — apps that integrate the fnf SDK (image/video generation, media upload, profile, workspace, credits, generation feed/history): read references/minimalist-ui.md
for the craft layer and references/quanta-design.md
+ the package guide
```
app/packages/quanta/ai/AGENTS.md
```
to implement. minimalist-ui
is for Higgsfield-SDK app surfaces ONLY — never load it for a non-SDK site.

Apply the craft skill's PRINCIPLES (layout variance, hierarchy, typographic discipline, anti-AI-tell rules, real imagery, motivated motion) in service of the wow you're building. Where a craft skill's assumed stack (Next.js/RSC,

next/font

, shadcn/Fluent/Carbon, raw

bg-zinc-*

palette) conflicts with this template, THIS STACK WINS. Do NOT ship default, generic-looking scaffolding.

Then route to the FUNCTIONAL skill for the task:

Task	Read
Design / wow on any build — bespoke AI assets + signature effects + motion/3D libs + copy-paste components (approved, free)	`references/wow-maker.md` (read FIRST, every build)
fnf SDK: generation jobs, media upload, profile/workspace/credits, adapters	`references/fnf-sdk.md` + `references/auth.md` + `references/runtime-and-infra.md`
React query/cache/controllers for fnf	`references/fnf-react.md` + `references/auth.md`
Higgsfield-SDK app UI (generation console, fnf-backed tool)	`references/minimalist-ui.md` + `references/quanta-design.md` + `app/packages/quanta/ai/AGENTS.md` + `references/fnf-sdk.md` + `references/fnf-react.md` + `references/auth.md`
Auth, current user, login/logout, `/api/user` , `__auth` routes	`references/auth.md` + `references/runtime-and-infra.md`
TanStack Start routes, SSR, server functions, Cloudflare Worker runtime	`references/runtime-and-infra.md`
Heavy / long-running work (ffmpeg, headless browser, background jobs), containers	`references/containers.md`
SEO meta tags, Open Graph, Twitter Cards, canonical URLs, robots directives	`references/seo-meta-tags.md`
JSON-LD structured data, schema.org markup	`references/seo-schema-markup.md`
robots.txt, sitemap.xml, security headers, canonicals, redirects, trailing slashes	`references/seo-technical.md`
Post-build SEO quality audit	`references/seo-audit.md`
GEO optimization for AI search engines (Perplexity, ChatGPT, Gemini)	`references/seo-geo-content.md`
Brand entity, knowledge graph, sameAs, NAP consistency	`references/seo-entity.md`
Cloudflare Workers security: secrets, global state, streaming, headers	`references/security-worker-hardening.md`
Post-build web security audit (OWASP Top 10, XSS, CSRF, insecure defaults)	`references/security-web-audit.md`
Threat modeling for websites with auth, user data, or databases	`references/security-threat-model.md`

Package-local guides are canonical for package APIs (read alongside the relevant skill when a task touches the package):

Package	Guide
`@higgsfield/quanta`	`app/packages/quanta/ai/AGENTS.md`
`@higgsfield/fnf`	`app/packages/fnf/ai/AGENTS.md`
`@higgsfield/fnf-react`	`app/packages/fnf-react/ai/AGENTS.md`

没有固定模板。对于每个构建——营销站点、应用、仪表盘或最简单的着陆页——你的设计来源是**

references/wow-maker.md

**：包含所有能让站点惊艳的内容的单一目录（定制AI生成资源、标志性动画模式、动效/3D库以及可复制粘贴的组件/块注册表，均为免费且许可宽松）。首先阅读该文档，从中构建独特的站点；每个站点必须具备真实的惊艳时刻。 不要交付通用脚手架，也不要在技能库中查找其他设计指导（不要使用

popular-web-designs

、

design-md

或外部着陆页技能）——所有内容都在wow-maker中。

我们最大的优势：使用Higgsfield生成工具生成定制资源（图片、视频循环、3D、OG资源）——带有真实生成艺术的站点比使用素材或纯CSS视觉效果的站点酷得多，但Agent往往未充分利用这一点。wow-maker第1节包含生成流程；将资源生成为每个构建流程的默认步骤。

在阅读wow-maker之后，仅阅读一个技能文档以了解如何有品味地实现——具体阅读哪个取决于站点是否集成Higgsfield SDK：

默认情况——不使用Higgsfield SDK的站点（营销/着陆页、作品集、通用SaaS/仪表盘/工具）：阅读**
```
references/design-taste-frontend.md
```
**（反“AI粗制滥造”的制作指南）并构建自定义Tailwind/CSS组件。不要导入
```
@higgsfield/quanta/*
```
，也不要使用
```
minimalist-ui
```
。
Higgsfield-SDK应用界面——集成fnf SDK的应用（图片/视频生成、媒体上传、个人资料、工作区、积分、生成动态/历史记录）：阅读**
```
references/minimalist-ui.md
```
了解制作规范，阅读
```
references/quanta-design.md
```
以及包指南
app/packages/quanta/ai/AGENTS.md
进行实现。
```
minimalist-ui
```
仅适用于Higgsfield-SDK应用界面**——绝不要在非SDK站点中加载它。

将技能文档中的原则（布局变化、层级结构、排版规范、反AI痕迹规则、真实图像、有目的的动效）服务于你要打造的惊艳效果。如果技能文档假设的技术栈（Next.js/RSC、

next/font

、shadcn/Fluent/Carbon、原始

bg-zinc-*

调色板）与本模板冲突，以本技术栈为准。不要交付默认的、通用外观的脚手架。

然后根据任务选择对应的功能技能文档：

任务	阅读文档
任何构建中的设计/惊艳效果——定制AI资源 + 标志性效果 + 动效/3D库 + 可复制粘贴组件（已批准、免费）	`references/wow-maker.md` （首先阅读，每个构建都需阅读）
fnf SDK：生成任务、媒体上传、个人资料/工作区/积分、适配器	`references/fnf-sdk.md` + `references/auth.md` + `references/runtime-and-infra.md`
用于fnf的React查询/缓存/控制器	`references/fnf-react.md` + `references/auth.md`
Higgsfield-SDK应用UI（生成控制台、基于fnf的工具）	`references/minimalist-ui.md` + `references/quanta-design.md` + `app/packages/quanta/ai/AGENTS.md` + `references/fnf-sdk.md` + `references/fnf-react.md` + `references/auth.md`
认证、当前用户、登录/登出、 `/api/user` 、 `__auth` 路由	`references/auth.md` + `references/runtime-and-infra.md`
TanStack Start路由、SSR、服务器函数、Cloudflare Worker运行时	`references/runtime-and-infra.md`
重型/长时间运行任务（ffmpeg、无头浏览器、后台任务）、容器	`references/containers.md`
SEO元标签、Open Graph、Twitter卡片、规范URL、robots指令	`references/seo-meta-tags.md`
JSON-LD结构化数据、schema.org标记	`references/seo-schema-markup.md`
robots.txt、sitemap.xml、安全头、规范URL、重定向、尾部斜杠	`references/seo-technical.md`
构建后SEO质量审计	`references/seo-audit.md`
AI搜索引擎（Perplexity、ChatGPT、Gemini）的GEO优化	`references/seo-geo-content.md`
品牌实体、知识图谱、sameAs、NAP一致性	`references/seo-entity.md`
Cloudflare Workers安全：密钥、全局状态、流、头信息	`references/security-worker-hardening.md`
构建后Web安全审计（OWASP Top 10、XSS、CSRF、不安全默认值）	`references/security-web-audit.md`
带认证、用户数据或数据库的网站威胁建模	`references/security-threat-model.md`

包本地指南是包API的权威文档（当任务涉及包时，需结合相关技能文档阅读）：

包	指南
`@higgsfield/quanta`	`app/packages/quanta/ai/AGENTS.md`
`@higgsfield/fnf`	`app/packages/fnf/ai/AGENTS.md`
`@higgsfield/fnf-react`	`app/packages/fnf-react/ai/AGENTS.md`

0a. Higgsfield packages and template modules

0a. Higgsfield包和模板模块

The

app/packages/

directory contains managed snapshots from fnf-web:

@higgsfield/fnf

@higgsfield/fnf-react

, and

@higgsfield/quanta

. Do not edit these manually unless the task explicitly asks to patch a package snapshot.

Template-owned infrastructure lives in

app/src/module/**

. The Design mode child bridge lives in

app/src/module/design-inspector

, not in a package and not in fnf-web.

Higgsfield-SDK app UI uses Quanta tokens/components; every other surface uses wow-maker + custom Tailwind/CSS. fnf API calls stay server-side.

app/packages/

目录包含来自fnf-web的托管快照：

@higgsfield/fnf

、

@higgsfield/fnf-react

和

@higgsfield/quanta

。除非任务明确要求修补包快照，否则不要手动编辑这些文件。

模板自有基础设施位于

app/src/module/**

目录下。设计模式子桥位于

app/src/module/design-inspector

，不属于任何包，也不在fnf-web中。

Higgsfield-SDK应用UI使用Quanta令牌/组件；其他所有界面使用wow-maker + 自定义Tailwind/CSS。fnf API调用仅在后端进行。

0b. Deploy targets and Design-mode inspector

0b. 部署目标和设计模式检查器

Deploy with the CLI.

higgsfield website deploy <website_id> --env preview

is the default and the ONLY environment you deploy on your own. Deploy

--env production

ONLY when the user explicitly asks to publish, go live, or ship. The platform CI runs the build on deploy (preview = the editable Design-mode build, production = a clean public build) and returns the build result — you do not run the production/preview build scripts yourself.

Supercomputer's in-browser Design mode adds an editable-preview inspector to preview builds; it is platform-managed. The template owns the child-iframe runtime under

app/src/module/design-inspector

;

fnf-web

owns the parent UI. You never hand-write inspector code, refs, source markers, or

data-hf-*

attributes; never fold the inspector build into the production

build

script; and never ship inspector metadata to production just to make Design mode work.

通过CLI部署。

higgsfield website deploy <website_id> --env preview

是默认选项，也是你自行部署的唯一环境。仅当用户明确要求发布、上线或交付时，才使用

--env production

部署到生产环境。平台CI会在部署时运行构建（预览版 = 可编辑的设计模式构建，生产版 = 干净的公开构建）并返回构建结果——你无需自行运行生产/预览构建脚本。

Supercomputer的浏览器内设计模式会为预览构建添加可编辑预览检查器；它由平台管理。模板负责

app/src/module/design-inspector

下的子iframe运行时；

fnf-web

负责父UI。你无需手动编写检查器代码、引用、源标记或

data-hf-*

属性；不要将检查器构建纳入生产

build

脚本；也不要为了让设计模式生效而将检查器元数据交付到生产环境。

1. SSR-safe rendering

1. SSR安全渲染

Every route renders on the server per request. NEVER touch browser-only globals (

window

document

localStorage

navigator

) at module top level or during render — only inside

useEffect

/event handlers, or guarded with

typeof window !== "undefined"

. A top-level

window

reference crashes SSR.

每个路由都会根据请求在服务器上渲染。绝不要在模块顶层或渲染期间访问仅浏览器可用的全局变量（

window

、

document

、

localStorage

、

navigator

）——仅在

useEffect

/事件处理程序中访问，或使用

typeof window !== "undefined"

进行保护。顶层

window

引用会导致SSR崩溃。

2. Server-only code stays server-only

2. 仅服务器代码保持在服务器端

Put server logic in

createServerFn(...).handler(...)

or a

*.server.ts

module (the

.server.ts

suffix keeps it out of the client bundle). Secrets and bindings are read server-side, per request — never shipped to the browser.

将服务器逻辑放在

createServerFn(...).handler(...)

或

*.server.ts

模块中（

.server.ts

后缀会将其排除在客户端包之外）。密钥和绑定会在服务器端按请求读取——绝不会交付到浏览器。

3. Higgsfield (fnf) calls are BACKEND-ONLY — and your app needs a real backend

3. Higgsfield（fnf）调用仅在后端进行——你的应用需要真实的后端

Build whatever backend the website needs: your own database (D1), server functions (

createServerFn

), app-local API routes, sessions, business logic — that's expected and fully supported, not just Higgsfield glue. For any website that uses the Higgsfield SDK this is mandatory, not a nice-to-have: it MUST be a real end-to-end app — real server functions/routes AND real persistence (D1) — never a front-end mock (see rule 3a). This rule is ONLY about reaching Higgsfield's API (fnf): call Higgsfield internal services exclusively from server code (a server function, server route, or

*.server.ts

). The platform attaches identity on server egress, so tokens never live in website code. NEVER call

https://fnf.internal/*

from client components — route the request through your own server code instead. (Your own backend endpoints can be called from the client as normal; the restriction is specific to Higgsfield's API.)

For current user auth, implement

GET /api/user

as a TanStack server route that calls

https://fnf.internal/user

server-side and returns the upstream status and JSON unchanged. Browser UI calls

/api/user

. Login/logout are browser navigations to

/__auth/login?return=<path>

and

/__auth/logout?return=<path>

. Read

references/auth.md

before touching this.

If the website uses the Higgsfield (fnf) SDK, adding auth is MANDATORY — not optional. Any website that touches the fnf SDK (generation, media upload, job feed/history, profile, workspace, wallet, credits, or any

https://fnf.internal/*

call) is an authenticated surface. Before shipping it you MUST implement the Higgsfield auth contract exactly as written in

references/auth.md

: the

GET /api/user

server proxy, a signed-out state that links to

/__auth/login

/__auth/logout

, and a server-side auth re-check before every SDK operation. Read

references/auth.md

and follow it — do not invent your own login UI, email/password form, or token handling, and do not build anonymous generation flows unless the user EXPLICITLY asks for an offline/mock demo (see rule 3a — a mock is never the default).

Preview sign-in is platform-owned — do NOT improvise a cause if it fails. Sign-in is not implemented in the website you build:

/__auth/login

is a platform-injected route that hands off to Higgsfield's auth service (Clerk), then redirects back to

return

/api/user

succeeds. The generated code's only job is to navigate to

/__auth/login

and read

/api/user

— both per

references/auth.md

. So if a user reports sign-in failing or looping on a PREVIEW, FIRST confirm the website side is correct (it links to

/__auth/login?return=<path>

and proxies

/api/user

unchanged); if it is, the failure is on the platform/auth side (the Higgsfield auth service / Clerk instance config), NOT the generated website. Say so plainly instead of inventing a website-code cause (e.g. "cookies are scoped to the prod domain"). Only change website code if it actually deviates from the

references/auth.md

contract.

Choose the auth mode by what the website is doing:

Higgsfield auth is mandatory for Higgsfield SDK/model features: image/video generation, media upload, profile, workspace, credits, and generation history. Use
```
/api/user
```
,
```
/__auth/login
```
,
```
/__auth/logout
```
, and server-only
```
https://fnf.internal
```
calls.
In-app auth is for the generated product's own users: todo accounts, SaaS team members, dashboards, notes, CRM users, and other app-local identity. Implement it with the website's own routes/storage and do not call
```
https://fnf.internal/user
```
unless the website also uses Higgsfield SDK features.
If a website needs both, keep them separate. Higgsfield auth gates paid generation/profile/workspace operations; in-app auth gates the product's own data. Never replace Higgsfield auth with app-local auth for generation, and never use Higgsfield auth as fake product-user accounts unless the prompt asks for a Higgsfield-authenticated tool.

If the user prompt asks for a model/generation website, even casually, treat auth, profile, credits/workspace display, and a generation feed/history as mandatory acceptance criteria. Example: "create a form app for Nano Banana generation 2" means build the form plus sign-in/logout,

/api/user

, profile/credits/ workspace UI, SDK submit/cost/media upload routes, polling until terminal status, and a feed/history panel that renders real image/video previews for submitted and historical generations. Do not wait for the user to explicitly ask for those.

Generation history cards must render SDK

Generation.results

, not status-only placeholders. Use

app/src/lib/higgsfield-generation-results.ts

and

app/src/components/higgsfield-generation-card.tsx

, or an equivalent component with the same URL precedence: optimized image preview first, video thumbnail as poster when present, raw URL for playback/open/download. Show prompt, model, status, and created time where available. A completed job without a result URL must show an explicit "preview unavailable" state with refresh/get behavior.

When creating SDK clients in generated websites, use only

createWorkflowPlatformAdapter({ baseUrl: 'https://fnf.internal' })

from server-side code. Do not use public/dev fnf URLs, env-selected backend URLs,

createFnfWebAdapter

createDevFnfWebAdapter

, apps-marketplace adapters, bearer tokens, or dev user headers in generated website code.

This is a generated-template policy. The SDK package itself is adapter-based; if the user explicitly asks to build a separate non-Supercomputer integration with another approved backend, use that host's adapter or a custom SDK backend port instead of applying this template-only restriction.

构建网站所需的任何后端：自有数据库（D1）、服务器函数（

createServerFn

）、应用本地API路由、会话、业务逻辑——这是预期且完全支持的，而不仅仅是Higgsfield的粘合代码。对于任何使用Higgsfield SDK的网站，这是强制性要求，而非可选功能：它必须是真实的端到端应用——包含真实的服务器函数/路由和真实的持久化（D1）——绝不能是前端模拟（参见规则3a）。本规则仅针对访问Higgsfield的API（fnf）：仅从服务器代码（服务器函数、服务器路由或

*.server.ts

）调用Higgsfield内部服务。平台会在服务器出站时附加身份信息，因此令牌永远不会出现在网站代码中。绝不要从客户端组件调用

https://fnf.internal/*

——而是通过自有服务器代码路由请求。（自有后端端点可以正常从客户端调用；该限制仅针对Higgsfield的API。）

对于当前用户认证，实现

GET /api/user

作为TanStack服务器路由，在服务器端调用

https://fnf.internal/user

并原样返回上游状态和JSON。浏览器UI调用

/api/user

。登录/登出是浏览器导航到

/__auth/login?return=<path>

和

/__auth/logout?return=<path>

。在处理认证前，请阅读

references/auth.md

。

如果网站使用Higgsfield（fnf）SDK，添加认证是强制性要求——而非可选功能。 任何涉及fnf SDK的网站（生成、媒体上传、任务动态/历史记录、个人资料、工作区、钱包、积分，或任何

https://fnf.internal/*

调用）都是需要认证的界面。在交付前，你必须严格按照

references/auth.md

中的Higgsfield认证契约实现：

GET /api/user

服务器代理、指向

/__auth/login

的未登录状态、

/__auth/logout

，以及每次SDK操作前的服务器端认证重新检查。阅读

references/auth.md

并遵循其要求——不要自行设计登录UI、邮箱/密码表单或令牌处理逻辑，除非用户明确要求离线/模拟演示（参见规则3a——模拟永远不是默认选项），否则不要构建匿名生成流程。

预览版登录由平台负责——不要为失败编造原因。 登录功能并非在你构建的网站中实现：

/__auth/login

是平台注入的路由，会将用户转交给Higgsfield的认证服务（Clerk），然后重定向回

return

路径，使

/api/user

请求成功。生成代码的唯一职责是导航到

/__auth/login

并读取

/api/user

——两者均遵循

references/auth.md

。因此，如果用户报告预览版登录失败或循环，首先确认网站端是否正确（它链接到

/__auth/login?return=<path>

并原样代理

/api/user

）；如果正确，失败原因在于平台/认证端（Higgsfield认证服务/Clerk实例配置），而非生成的网站。直接说明这一点，不要编造网站代码层面的原因（例如：“Cookie作用域为生产域名”）。仅当网站代码确实偏离

references/auth.md

契约时，才修改网站代码。

根据网站的功能选择认证模式：

Higgsfield认证对于Higgsfield SDK/模型功能是强制性的：图片/视频生成、媒体上传、个人资料、工作区、积分和生成历史记录。使用
```
/api/user
```
、
```
/__auth/login
```
、
```
/__auth/logout
```
以及仅服务器端的
```
https://fnf.internal
```
调用。
应用内认证用于生成产品的自有用户：待办账户、SaaS团队成员、仪表盘、笔记、CRM用户以及其他应用本地身份。使用网站自有路由/存储实现，除非网站同时使用Higgsfield SDK功能，否则不要调用
```
https://fnf.internal/user
```
。
如果网站需要两种认证模式，请将它们分开。Higgsfield认证用于付费生成/个人资料/工作区操作；应用内认证用于产品自有数据。绝不要用应用内认证替代Higgsfield认证用于生成功能，也不要将Higgsfield认证用作虚假的产品用户账户，除非提示要求构建Higgsfield认证的工具。

如果用户提示要求构建模型/生成网站，即使是随口提及，也要将认证、个人资料、积分/工作区显示以及生成动态/历史记录视为强制性验收标准。示例：“为Nano Banana generation 2创建一个表单应用”意味着构建表单以及登录/登出、

/api/user

、个人资料/积分/工作区UI、SDK提交/成本/媒体上传路由、轮询直到终端状态，以及显示已提交和历史生成的真实图片/视频预览的动态/历史记录面板。不要等待用户明确要求这些功能。

生成历史记录卡片必须渲染SDK的

Generation.results

，而非仅显示状态的占位符。使用

app/src/lib/higgsfield-generation-results.ts

和

app/src/components/higgsfield-generation-card.tsx

，或具有相同URL优先级的等效组件：优先显示优化后的图片预览，存在视频缩略图时将其作为海报，原始URL用于播放/打开/下载。在可用时显示提示词、模型、状态和创建时间。完成的任务如果没有结果URL，必须显示明确的“预览不可用”状态，并提供刷新/获取功能。

在生成的网站中创建SDK客户端时，仅从服务器端代码使用

createWorkflowPlatformAdapter({ baseUrl: 'https://fnf.internal' })

。不要在生成的网站代码中使用公开/开发环境的fnf URL、按环境选择的后端URL、

createFnfWebAdapter

、

createDevFnfWebAdapter

、应用市场适配器、Bearer令牌或开发用户头信息。

这是生成模板的策略。SDK包本身是基于适配器的；如果用户明确要求构建与另一个已批准后端的独立非Supercomputer集成，请使用该主机的适配器或自定义SDK后端端口，而非应用本模板的限制。

3a. A Higgsfield-SDK app is end-to-end — real backend + real DB, never a mock

3a. Higgsfield-SDK应用是端到端的——真实后端 + 真实数据库，绝不是模拟

Any website that uses the Higgsfield SDK (generation, media, profile, workspace, credits, or any

https://fnf.internal/*

call) MUST ship as a real, end-to-end product — NOT a front-end mock, prototype, or "demo" that fakes the backend. This is a hard requirement, on the same footing as the auth contract above.

An SDK app MUST have all three:

A real backend. Every data operation (submit, poll, save, list, mutate) runs through a TanStack server function or server route — fnf calls server-side, reads/writes server-side. No client-only data layer standing in for a backend.
Real persistence (D1). Opt into D1 (
```
"db": true
```
in
```
app/app.manifest.json
```
, rule 6) and persist the app's OWN product state: saved/favorited generations, collections/galleries, named projects, prompt presets, share/publish records, in-app user data, settings — whatever the product remembers between sessions. Add the schema in
```
app/migrations/000N_*.sql
```
(additive; rule 5).
Real fnf integration. Generations, media, profile, and credits come from the live SDK against
```
https://fnf.internal
```
(rule 3), never hardcoded fixtures.

fnf is the source of truth for the generations themselves — do NOT mirror fnf's tables into D1. D1 is for YOUR product layer on top of fnf (the "saved", "organized", "shared", "annotated" state fnf doesn't own). A generation app with zero app-owned state is almost always under-built: at minimum let users save and organize what they make.

These are NOT a backend and are bugs in an SDK app: in-memory arrays or module-level state as "the database";

localStorage

sessionStorage

as the persistence layer; hardcoded / fixture /

lorem

data standing in for real records; a static JSON file faking a list endpoint;

setTimeout

faking request latency; memory/mock SDK adapters shipped as the product; TODO stubs where a write belongs.

The ONLY exception is when the user explicitly asks for an offline/mock demo (an "offline demo", "no backend", "static prototype", memory-adapter sample) — then say plainly that it is a mock and why. Absent that explicit ask, build the real thing; never downgrade to a mock as the "safe" default.

任何使用Higgsfield SDK的网站（生成、媒体、个人资料、工作区、积分，或任何

https://fnf.internal/*

调用）必须作为真实的端到端产品交付——不能是前端模拟、原型或“演示版”，不能伪造后端。这是硬性要求，与上述认证契约处于同等地位。

SDK应用必须具备以下三点：

真实后端。每个数据操作（提交、轮询、保存、列出、修改）都通过TanStack服务器函数或服务器路由运行——fnf调用在服务器端进行，读写操作在服务器端完成。不能用仅客户端的数据层替代后端。
真实持久化（D1）。启用D1（
```
app/app.manifest.json
```
中设置
```
"db": true
```
，参见规则6）并持久化应用的自有产品状态：已保存/收藏的生成内容、集合/画廊、命名项目、提示词预设、分享/发布记录、应用内用户数据、设置——任何产品在会话之间需要记住的内容。在
```
app/migrations/000N_*.sql
```
中添加模式（增量式；参见规则5）。
真实fnf集成。生成内容、媒体、个人资料和积分来自针对
```
https://fnf.internal
```
的实时SDK（参见规则3），绝不是硬编码的固定数据。

fnf是生成内容本身的数据源——不要将fnf的表镜像到D1中。D1用于存储你在fnf之上的产品层状态（fnf不拥有的“已保存”、“已整理”、“已分享”、“已注释”状态）。一个没有应用自有状态的生成应用几乎总是构建不足：至少要让用户保存和整理他们创建的内容。

以下内容不属于后端，在SDK应用中属于错误： 将内存数组或模块级状态作为“数据库”；将

localStorage

sessionStorage

作为持久化层；将硬编码/固定/

lorem

数据替代真实记录；将静态JSON文件伪造为列表端点；将

setTimeout

伪造为请求延迟；将内存/模拟SDK适配器作为产品交付；在需要写入的地方留下TODO占位符。

唯一的例外是当用户明确要求离线/模拟演示（“离线演示”、“无后端”、“静态原型”、内存适配器示例）——此时要明确说明这是模拟以及原因。如果没有明确要求，请构建真实版本；绝不要默认降级为模拟版本作为“安全”选项。

4. Cloudflare bindings via

cloudflare:workers

4. 通过

cloudflare:workers

访问Cloudflare绑定

Any infra you opt into (D1

DB

, R2

STORAGE

, KV

KV

) is read server-side through

app/src/lib/bindings.server.ts

(

import { env } from "cloudflare:workers"

). Each binding is present ONLY if declared in

app/app.manifest.json

, so the typed accessors are optional — guard before use. Do not thread

env

through React props or read it at module top level.

你启用的任何基础设施（D1

DB

、R2

STORAGE

、KV

KV

）都通过

app/src/lib/bindings.server.ts

（

import { env } from "cloudflare:workers"

）在服务器端读取。每个绑定仅在

app/app.manifest.json

中声明后才会存在，因此类型化访问器是可选的——使用前需进行检查。不要通过React props传递

env

，也不要在模块顶层读取它。

5. Opted-in storage is SHARED — preview data == prod data

5. 启用的存储是共享的——预览版数据 == 生产版数据

If you opt into D1, R2, or KV, each is a SINGLE instance shared by the preview and prod deploys. Only the CODE is split (

vars.HF_ENV

). The DATA is not.

```
env.HF_ENV
```
tells you which env it is; it CANNOT switch the database / bucket / namespace.
A destructive migration or write you run "just to test on preview" hits production data. Prefer additive migrations (
```
CREATE TABLE IF NOT EXISTS
```
,
```
ADD COLUMN
```
); avoid
```
DROP
```
/destructive
```
UPDATE
```
unless you mean prod.

如果你启用了D1、R2或KV，每个服务都是预览版和生产版部署共享的单个实例。只有代码是分离的（

vars.HF_ENV

）。数据是共享的。

```
env.HF_ENV
```
告诉你当前是哪个环境；它不能切换数据库/存储桶/命名空间。
你在“仅在预览版测试”时运行的破坏性迁移或写入操作会影响生产版数据。优先使用增量迁移（
```
CREATE TABLE IF NOT EXISTS
```
、
```
ADD COLUMN
```
）；除非针对生产版，否则避免使用
```
DROP
```
/破坏性
```
UPDATE
```
。

app/app.manifest.json

declares infra — NOTHING is provisioned by default

app/app.manifest.json

声明基础设施——默认不提供任何资源

A new website gets no D1, no R2, no KV, no Durable Object —

app/app.manifest.json

ships every service OFF. Opt in only when the website actually needs it:

```
"db": true
```
→ a D1 database, bound
```
env.DB
```
```
"r2": true
```
→ an R2 bucket, bound
```
env.STORAGE
```
```
"kv": true
```
→ a KV namespace, bound
```
env.KV
```
```
"durableObject": "ClassName"
```
→ a Durable Object, bound
```
env.ROOMS
```

"container": true

(or

{ "instanceType", "port", "sleepAfter" }

) → a Docker container for heavy / long-running work, bound

env.CONTAINER

— see

references/containers.md

Counts are capped (≤1 each) by the platform, which PROVISIONS the resource and binds it in an authoritative config at deploy. The committed

app/wrangler.jsonc

is build/dev input only (used by

wrangler dev

); the platform OVERWRITES its

name

bindings at deploy, so editing a binding there does not change the deploy — declare infra in
```
app/app.manifest.json
```
.

KV is eventually consistent (it is NOT Redis): use it for config, feature flags, and cached reads — NOT for counters, locks, or read-after-write. Reach for a Durable Object when you need strong consistency.

For a Durable Object you must ALSO

export class ClassName extends DurableObject {…}

from

app/src/server.ts

(alongside the default

{ fetch }

export) so the class ships in the Worker.

For a container — heavy or long-running work a Worker can't do (ffmpeg, a headless browser, a 30-minute job): set

"container"

in the manifest and follow references/containers.md
. It has the exact

app/container/Dockerfile

, the platform-fixed

AppContainer

class (a Durable Object you export from

app/src/server.ts

), the keep-alive + 3-hour-deadline pattern that long jobs REQUIRE (or the container is idle-killed mid-job), and how a background container calls fnf via a container token. Containers are off by default.

新网站没有D1、R2、KV、Durable Object——

app/app.manifest.json

中所有服务默认关闭。仅当网站确实需要时才启用：

```
"db": true
```
→ D1数据库，绑定为
```
env.DB
```
```
"r2": true
```
→ R2存储桶，绑定为
```
env.STORAGE
```
```
"kv": true
```
→ KV命名空间，绑定为
```
env.KV
```
```
"durableObject": "ClassName"
```
→ Durable Object，绑定为
```
env.ROOMS
```

"container": true

（或

{ "instanceType", "port", "sleepAfter" }

）→ 用于重型/长时间运行任务的Docker容器，绑定为

env.CONTAINER

——参见

references/containers.md

资源数量有上限（每个≤1），由平台提供资源并在部署时以权威配置绑定。提交的

app/wrangler.jsonc

仅作为构建/开发输入（供

wrangler dev

使用）；平台会在部署时覆盖其

name

+ 绑定，因此编辑此处的绑定不会改变部署——请在

app/app.manifest.json

中声明基础设施。

KV是最终一致的（它不是Redis）：将其用于配置、功能标志和缓存读取——不要用于计数器、锁或写后读操作。当需要强一致性时，请使用Durable Object。

对于Durable Object，你还必须从

app/src/server.ts

导出

export class ClassName extends Durable Object {…}

（与默认的

{ fetch }

导出一起），以便该类随Worker一起交付。

对于容器——Worker无法处理的重型或长时间运行任务（ffmpeg、无头浏览器、30分钟任务）：在清单中设置

"container"

并遵循**

references/containers.md

。该文档包含精确的
app/container/Dockerfile
、平台固定的
AppContainer
类（你需从
app/src/server.ts
导出的Durable Object）、长时间任务必须**遵循的保活+3小时期限模式（否则容器会在任务中途因闲置被终止），以及后台容器如何通过容器令牌调用fnf。容器默认关闭。

Editing map

编辑指南

Pages / routing →
```
app/src/routes/**
```
(file-based;
```
__root.tsx
```
is the shell).

Server logic →

createServerFn

(see

app/src/lib/api/example.functions.ts

) or

*.server.ts

Bindings access →
```
app/src/lib/bindings.server.ts
```
.
Infra declaration →
```
app/app.manifest.json
```
;
```
app/wrangler.jsonc
```
= build/dev input.
Durable Object class → exported from
```
app/src/server.ts
```
.

Container (heavy/long jobs) →

app/container/Dockerfile

+ the

AppContainer

class in

app/src/server.ts

; recipe in

references/containers.md

Components → Default builds (marketing, landing, general SaaS/tools): custom components built per wow-maker; app-local files in
```
app/src/components/**
```
. Higgsfield-SDK app builds: Quanta imports from
```
@higgsfield/quanta/*
```
, app-local wrappers only when composition is app-specific. Do not start from
```
app/src/components/ui/*
```
unless migrating a legacy shadcn piece (restyle it to the site's tokens, or to Quanta tokens on an SDK app surface).
Generation result UI → use
```
app/src/components/higgsfield-generation-card.tsx
```
and
```
app/src/lib/higgsfield-generation-results.ts
```
for SDK-backed feeds and post-submit polling output. Do not render completed generations as blank boxes with only status/id text.
Styles / theme →
```
app/src/styles.css
```
wires Tailwind v4 (Quanta CSS is imported for the template bundle). Default builds: a custom token layer per wow-maker — no q-prefixed utilities. Higgsfield-SDK app builds: native Tailwind spacing (
```
p-4
```
,
```
gap-2
```
) + Quanta semantic utilities (
```
bg-q-background-primary
```
,
```
text-q-body-md-regular
```
). Keep Quanta package tokens in
```
app/packages/quanta
```
; do not redefine them unless patching the package snapshot.
D1 schema →
```
app/migrations/000N_*.sql
```
(additive; see rule 5).

页面/路由 →
```
app/src/routes/**
```
（基于文件；
```
__root.tsx
```
是外壳）。

服务器逻辑 →

createServerFn

（参见

app/src/lib/api/example.functions.ts

）或

*.server.ts

。

绑定访问 →
```
app/src/lib/bindings.server.ts
```
。
基础设施声明 →
```
app/app.manifest.json
```
；
```
app/wrangler.jsonc
```
= 构建/开发输入。
Durable Object类 → 从
```
app/src/server.ts
```
导出。

容器（重型/长时间任务） →

app/container/Dockerfile

app/src/server.ts

中的

AppContainer

类；参考

references/containers.md

中的流程。

组件 → 默认构建（营销、着陆页、通用SaaS/工具）：基于wow-maker构建的自定义组件；应用本地文件位于
```
app/src/components/**
```
。Higgsfield-SDK应用构建：从
```
@higgsfield/quanta/*
```
导入Quanta组件，仅在组合为应用特定内容时使用应用本地包装器。不要从
```
app/src/components/ui/*
```
开始构建，除非迁移遗留的shadcn组件（根据站点令牌重新设置样式，或在SDK应用界面中使用Quanta令牌）。
生成结果UI → 使用
```
app/src/components/higgsfield-generation-card.tsx
```
和
```
app/src/lib/higgsfield-generation-results.ts
```
用于SDK驱动的动态和提交后轮询输出。不要将已完成的生成为仅显示状态/ID文本的空白框。
样式/主题 →
```
app/src/styles.css
```
配置了Tailwind v4（Quanta CSS已导入用于模板包）。默认构建：基于wow-maker的自定义令牌层——不要使用q前缀的工具类。Higgsfield-SDK应用构建：原生Tailwind间距（
```
p-4
```
、
```
gap-2
```
） + Quanta语义工具类（
```
bg-q-background-primary
```
、
```
text-q-body-md-regular
```
）。Quanta包令牌保留在
```
app/packages/quanta
```
中；除非修补包快照，否则不要重新定义它们。
D1模式 →
```
app/migrations/000N_*.sql
```
（增量式；参见规则5）。

Verify

验证

The trusted platform CI builds the website on every deploy (preview → editable Design-mode build, production → clean public build), so a deploy already gives you the authoritative type + build result. Do NOT reflexively

bun install

bun run build

(or lint, or any other local install/build) just to check your work — that repeats the build the deploy is about to run and makes the user sit through two builds back to back. The platform CI provisions infra and deploys/migrates.

Default: make your edits, push, and deploy the preview (

higgsfield website deploy <website_id> --env preview

) — never production unless the user explicitly asked to publish. Let the deploy build surface any type or build error and report it back — no

node_modules

, no local build needed for a normal content/UI edit.

Do NOT take a screenshot of the deployed website (e.g. via the browser tool) unless the user explicitly asks for one. Return the preview URL and let the user open it — screenshotting is slow, often unnecessary, and not something the user asked for by default.

Run the local checks only when you actually need them — from

app/

bash

cd app
bun install          # only when you changed dependencies / package.json
bun run typecheck    # tsc --noEmit
bun run build        # production-clean build: no inspector runtime or source metadata
bun run build:design # editable Supercomputer preview build with WeakMap source registry
bun run build:prod   # alias for the production-clean build

Run them only when the work genuinely requires it, e.g.:

You added, removed, or upgraded a dependency, or edited
```
package.json
```
.

You changed build/runtime config (

vite.config.ts

tsconfig*.json

wrangler.jsonc

app.manifest.json

You are debugging a build or type error and need the local output to iterate.
A command you must run genuinely needs
```
node_modules
```
present.

For a small, isolated edit (copy, styling, a self-contained component), skip the local install/build and let the deploy verify it.

Before claiming a build done / deploying, no placeholders may remain. Run

bun run qa:fill -- --strict

(add

--url <preview>

to also scan the rendered page). It fails if any template placeholder survives — a

<...>

-style token (e.g.

"<brand name>"

lorem ipsum

, or the scaffold blank-page marker (

REMOVE_THIS

blank-app-v1

). On a freshly scaffolded website it flags the blank-page placeholder by design — that just means nothing has been built yet. It is a completion gate, not a CI build step.

可信平台CI会在每次部署时构建网站（预览版 → 可编辑的设计模式构建，生产版 → 干净的公开构建），因此部署已经提供了权威的类型+构建结果。不要习惯性地运行

bun install

bun run build

（或lint，或任何其他本地安装/构建）来检查你的工作——这会重复部署即将运行的构建，让用户等待两次连续的构建。平台CI会提供基础设施并进行部署/迁移。

默认流程：进行编辑，推送，然后部署预览版（

higgsfield website deploy <website_id> --env preview

）——除非用户明确要求发布，否则不要部署到生产版。让部署构建显示任何类型或构建错误并报告回来——对于普通内容/UI编辑，不需要

node_modules

或本地构建。

除非用户明确要求，否则不要对部署的网站截图（例如通过浏览器工具）。返回预览URL让用户自行打开——截图速度慢，通常不必要，且不是用户默认要求的操作。

仅在确实需要时运行本地检查——从

app/

目录运行：

bash

cd app
bun install          # 仅在更改依赖项 / package.json时运行
bun run typecheck    # tsc --noEmit
bun run build        # 生产版干净构建：无检查器运行时或源元数据
bun run build:design # 带WeakMap源注册表的可编辑Supercomputer预览版构建
bun run build:prod   # 生产版干净构建的别名

仅在工作确实需要时运行这些命令，例如：

添加、移除或升级了依赖项，或编辑了
```
package.json
```
。

更改了构建/运行时配置（

vite.config.ts

、

tsconfig*.json

、

wrangler.jsonc

、

app.manifest.json

）。

调试构建或类型错误，需要本地输出来迭代。
必须运行的命令确实需要
```
node_modules
```
存在。

对于小型、孤立的编辑（文本、样式、独立组件），跳过本地安装/构建，让部署验证即可。

在声称构建完成/部署前，不能留下任何占位符。 运行

bun run qa:fill -- --strict

（添加

--url <preview>

可同时扫描渲染后的页面）。如果任何模板占位符未被替换，该命令会失败——例如

<...>

样式的令牌（如

"<brand name>"

）、

lorem ipsum

或脚手架空白页标记（

REMOVE_THIS

blank-app-v1

）。对于刚搭建的网站，它会默认标记空白页占位符——这仅意味着尚未构建任何内容。这是完成检查，而非CI构建步骤。

higgsfield-websites

Original

Translation

Agent guide — Higgsfield website (full-stack, server-rendered)

Agent指南 — Higgsfield网站（全栈、服务器渲染）

Prerequisites

前置条件

UX Rules

UX规则

Website lifecycle (CLI)

网站生命周期（CLI）

Stack

技术栈

Hard rules

硬性规则

0. Design: build a WOW site from the wow-maker toolkit

0. 设计：基于wow-maker工具包打造令人惊叹的站点

0a. Higgsfield packages and template modules

0a. Higgsfield包和模板模块

0b. Deploy targets and Design-mode inspector

0b. 部署目标和设计模式检查器

1. SSR-safe rendering

1. SSR安全渲染

2. Server-only code stays server-only

2. 仅服务器代码保持在服务器端

3. Higgsfield (fnf) calls are BACKEND-ONLY — and your app needs a real backend

3. Higgsfield（fnf）调用仅在后端进行——你的应用需要真实的后端

3a. A Higgsfield-SDK app is end-to-end — real backend + real DB, never a mock

3a. Higgsfield-SDK应用是端到端的——真实后端 + 真实数据库，绝不是模拟

4. Cloudflare bindings via
`cloudflare:workers`

4. 通过
`cloudflare:workers`
访问Cloudflare绑定

5. Opted-in storage is SHARED — preview data == prod data

5. 启用的存储是共享的——预览版数据 == 生产版数据

6.
`app/app.manifest.json`
declares infra — NOTHING is provisioned by default

6.
`app/app.manifest.json`
声明基础设施——默认不提供任何资源

Editing map

编辑指南

Verify

验证

higgsfield-websites

Original

Translation

Agent guide — Higgsfield website (full-stack, server-rendered)

Agent指南 — Higgsfield网站（全栈、服务器渲染）

Prerequisites

前置条件

UX Rules

UX规则

Website lifecycle (CLI)

网站生命周期（CLI）

Stack

技术栈

Hard rules

硬性规则

0. Design: build a WOW site from the wow-maker toolkit

0. 设计：基于wow-maker工具包打造令人惊叹的站点

0a. Higgsfield packages and template modules

0a. Higgsfield包和模板模块

0b. Deploy targets and Design-mode inspector

0b. 部署目标和设计模式检查器

1. SSR-safe rendering

1. SSR安全渲染

2. Server-only code stays server-only

2. 仅服务器代码保持在服务器端

3. Higgsfield (fnf) calls are BACKEND-ONLY — and your app needs a real backend

3. Higgsfield（fnf）调用仅在后端进行——你的应用需要真实的后端

3a. A Higgsfield-SDK app is end-to-end — real backend + real DB, never a mock

3a. Higgsfield-SDK应用是端到端的——真实后端 + 真实数据库，绝不是模拟

4. Cloudflare bindings via cloudflare:workers

4. 通过cloudflare:workers访问Cloudflare绑定

5. Opted-in storage is SHARED — preview data == prod data

5. 启用的存储是共享的——预览版数据 == 生产版数据

6. app/app.manifest.json declares infra — NOTHING is provisioned by default

6. app/app.manifest.json声明基础设施——默认不提供任何资源

Editing map

编辑指南

Verify

验证

4. Cloudflare bindings via
`cloudflare:workers`

4. 通过
`cloudflare:workers`
访问Cloudflare绑定

6.
`app/app.manifest.json`
declares infra — NOTHING is provisioned by default

6.
`app/app.manifest.json`
声明基础设施——默认不提供任何资源