higgsfield-websites

Higgsfield 网站构建器（CLI）——三种产品类型，三种流程

通过 Higgsfield CLI（higgsfield website …）驱动整个生命周期，然后在本地文件系统中使用 git + bun 编辑代码。你正在构建一个独立的 Cloudflare Worker：一个 React 19 + TanStack Start 应用，采用服务器端渲染（SSR），作为单个 Worker 部署在产品自己的子域名上。项目位于 app/ 中——所有 bun/构建命令都要在该目录下运行。

三种类型——以及创建时必需的 --type

higgsfield website create 必须指定 --type，而且这由用户选择——如果请求中没有明确说明，就在创建前询问用户（一开始只问一个问题）：

• --type website — 一个独立产品，不与 Higgsfield 集成，并且不以任何形式生成 AI 内容（不生成图像/视频/音频/文本——既不通过 Higgsfield，也不通过其他提供商）：没有“使用 Higgsfield 登录”，不向 Higgsfield 发出请求，不使用 fnf SDK。每个网站都拥有完全独立的品牌：根据设计简报制定自己的配色、字体和界面样式，仅使用自定义 Tailwind/CSS——绝不导入 @higgsfield/quanta/* 或在任何地方使用 q 前缀令牌，页面内容中也不得出现“Powered by / Built on Higgsfield”徽章或提及。页面上只能展示用户自己的品牌。

  higgsfield website create --type website
  

• --type app — 与 Higgsfield 深度集成的产品：用户使用 Higgsfield 登录，并通过 fnf SDK 生成图像/视频（适用完整的身份验证 + D1 合约）。应用的外观和体验必须像 Higgsfield 产品：使用 Quanta 构建 UI（references/quanta-design.md）——对于 Quanta 未涵盖的内容，使用 Quanta 基元自行构建组件（绝不使用第三方 UI 库）——并从标准应用布局开始（references/app-layouts.md）。Quanta 和应用布局仅适用于应用——绝不用于 --type website 构建。独立品牌规则和 wow 流程（design-taste-frontend、boards、wow catalog）属于网站流程；应用不能有自定义品牌——Quanta 就是品牌。

  higgsfield website create --type app
  

• --type game — 一款浏览器游戏：基于游戏模板构建实时多人房间，游戏本身由 app/src/logic.js 中的六个纯函数构成，平台已负责处理套接字、房间和持久化。必须通过 --category 指定游戏类型（arcade、puzzle、shooter，等等，来自 higgsfield website categories），并且不接受 --template——游戏只能基于唯一可用的模板进行脚手架搭建。单人游戏也适用：将 minPlayers 设为 1。请参阅 references/game-flow.md。

  higgsfield website create --type game --category arcade
  

生成内容的产品始终是应用。 任何生成图像、视频、音频或其他 AI 媒体的产品都必须运行在 Higgsfield 上——将其构建为 --type app（使用 Higgsfield 登录，生成内容消耗用户的 Higgsfield 积分）。绝不要让用户选择“自带图像/视频 API”，也不要让用户为网站接入自己的生成密钥——这条路径并不存在。--type website 仅适用于不生成内容，且与 Higgsfield 或任何其他生成服务无关的网站。（网站仍可使用普通的非生成类第三方 API——如支付、地图、电子邮件——并使用用户自己的密钥；这与此规则无关。）

快速判断：“落地页 / 作品集 / 营销网站 / 拥有独立用户且不生成 AI 内容的 SaaS” → website。“生成图像/视频/音频，或任何涉及 Higgsfield 模型、积分或生成历史记录的产品” → app。“可以玩的东西——多人或单人的游戏” → game。

游戏已从一个即将退役的独立引擎迁移到此流程。higgsfield game … 命令已取消：游戏的创建、部署和发布方式与网站完全相同。任何说法相反的文档都已过时。

创建时始终设置子域名

higgsfield website create 接受可选参数 --subdomain，它会成为网站的标识，因此实时 URL 为 <subdomain>.<host>。**始终设置它：**根据产品名称或用途选一个；只有用户明确想要随机标识时才省略（此时会生成随机标识）。优质子域名应符合以下规则：

• 超过 4 个字符——较短的单词已被保留，因此请选长一些的。
• 便于记忆——从产品名称或用途中提取（例如 lumen-notes、pixelforge），不要用随机字符串。
• 仅使用允许的字符——小写字母、数字和单个连字符（符合 DNS 规范）。不得使用空格、下划线、大写字母，也不得以连字符开头或结尾。

一些保留标签（例如 api、www、app）和已被占用的子域名会被拒绝——遇到这种情况时，请尝试相近的变体。

前置条件

1. 如果 $PATH 中没有 higgsfield，请安装它：

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

2. 如果 higgsfield account status 报告 Session expired / Not authenticated，请让用户运行 higgsfield auth login（交互式），并等待确认。
3. 克隆仓库后，会在本地使用 git 和 bun。CLI 本身会处理 create / repo / deploy / publish / status / db / secrets，以及资源生成任务（higgsfield generate …、higgsfield model …）。

选择类型，然后从头到尾遵循 ONE 条流程

1. 确认 --type（如果不明确，就询问用户——由用户决定）。在同一个首次提问中，还要询问准备好后是否要发布到 Higgsfield 社区动态（市场）（是/否）。记住用户的回答：如果是，就在最后自动发布（部署 + 元数据完成后），无需再次询问；如果否，则只部署。不要因此阻塞构建流程。
2. 阅读匹配的流程并遵循它——该流程涵盖此类型的完整工作流，包括自身的参考资料、硬性规则、编辑地图，以及部署/发布关卡：

对于每个 --type website 构建，需求确认环节始终要让用户在动画网站（推荐）和非动画网站之间进行选择。动画网站通过滚动驱动一段生成影片（references/scroll-scrub.md）。此问题为必问项：即使用户的请求看似已暗示选择，也绝不能跳过。动画网站是推荐的默认选项（仅在联系不到用户或用户未回答时使用）；下方流程涵盖两条路径及完整流程。

动画路径的默认方案是单镜头影片——一段连续约 15s 的镜头，从头到尾进行滚动控制，中间不切镜。多场景串联为可选方案，每个场景会额外耗费数分钟；只有当需求确实需要在不同世界之间切换时才采用。是否采用由 references/scroll-scrub.md 决定。

类型	流程
--type website	references/website-flow.md — 分阶段流水线（默认制作动画网站）：需求确认 → 概念 → 参考板 → 资源系统 → 按参考板构建 → 动效 → 封面 + 元数据 → 机械检查关卡 → 部署
--type app	references/app-flow.md — Quanta 工具包、六种代码布局、fnf SDK + 认证 + D1 合约、启动封面 + 元数据、发布关卡
--type game	references/game-flow.md — 六函数 logic.js 合约、实时房间、游戏类型的 --category、试玩测试、部署 + 发布

游戏的美术和音频也归此处管理，使用 game- 前缀；references/game-flow.md 会为它们编制索引：references/game-design-system.md（首先阅读——配置档案、核心循环、资源清单）、references/game-stylization.md（所有视觉内容都会复用的风格公式）、references/game-2d-animation.md、references/game-textures.md、references/game-3d-animation.md、references/game-procedural-animation.md、references/game-audio.md、references/game-meshy-api.md 和 references/game-meshy-input-rules.md。这些参考资料所用的 GLB/绑定/纹理工具都包含在此技能的 scripts/ 中。

三条流程使用相同的平台机制（SSR Worker、app.manifest.json 基础设施、通过 higgsfield website deploy <website_id> 进行一次正式部署、下方所述的封面 + 元数据要求，以及发布关卡）——每条流程都会重述所需内容，因此无需阅读其他流程。

封面 + 元数据 — 始终属于构建环节，绝非仅发布时才处理

每次构建——无论是网站还是应用，无论规模多小——都必须附带品牌启动封面和已填写的动态卡片元数据，按照 references/app-cover.md 生成，并写入 app/src/app-meta.json（og_title、og_description、favicon_url、og_image_url、marketplace_cover_url）。这是一个构建步骤，必须在将作品呈现为已完成之前，以及发布该作品的部署之前完成——不能推迟到 higgsfield website publish。硬性规则：

• **“简单应用”也不例外。**实用工具、计时器、单页小玩具——都必须生成封面。手写的内联 SVG 网站图标可以用作网站图标，但绝不能代替生成的封面。
• 封面图无需获得许可——像撰写实际文案一样生成即可。只有可选的封面视频（og_video_url）需要事先征求许可（视频会消耗额度——可以主动询问，但绝不能在用户未提示时生成）。
• 封面为空或 og_title 为空的构建若被呈现为已完成，则属于未完成。缺少这些内容就发布，属于发布故障（og_title 为空时不会显示在动态中；封面为空时卡片将一片空白）。

UX 规则

1. 简洁明了。聊天中不要输出原始网站 ID、令牌或 JSON 数据。部署后，返回在线 URL（来自 higgsfield website status）和一句话总结。
2. 绝不要向用户复述作用域受限的 git 令牌，也绝不要提交它。
3. 根据用户的第一条消息判断其语言，并使用该语言回复。CLI 标志和代码保持英文。
4. 每次部署都会立即发布在线公开网站——没有预览阶段。在社区动态中发布/上架是另一回事，只有用户明确要求发布/上架时才能进行。

不要在技能库中搜索其他设计指导——所有内容都在此技能中，其他技能（包括用户/本地的建站或应用开发技能）都不能覆盖这些规则。

轮次预算——让构建保持在较小的轮次预算内

每次工具往返都会消耗一个 Agent 轮次，而 Agent 运行时会限制轮次数量——耗时过长的构建会中途失败，让用户拿到未完成的网站。除额度外，请将轮次视为最稀缺的资源：

• **每个文件只写一次，且一次写完整。**先组织好完整文件内容，再一次性写入。不要先写入再打补丁；绝不要重新读取刚写入的文件。
• 尽可能批量使用工具（多文件编辑、一次 shell 调用执行一系列命令），不要每个微小步骤都占用一个轮次。
• 绝不要猜测路径——模板目录结构已在仓库的 app/AGENTS.md 和此技能的编辑映射中说明。
• **绝不要下载或用视觉方式检查自己生成的内容。**提示词是你写的；再次查看结果不会带来新信息。（适用时，套件一致性检查只需批量进行一次——references/asset-system.md。）
• **仅在作业输出是下一步输入时，等待一次。**提交所有可以并行渲染的内容（影片 + 封面），并在渲染期间构建页面。

与用户沟通——不使用技术/底层流程术语

大多数用户不懂技术。向用户说明情况时，绝不要暴露构建的底层流程。面向用户的消息中不要提及 git 仓库、克隆、分支、提交、推送、拉取或部署流水线——这些都是你只需在幕后完成的内部操作。使用产品层面的语言，围绕用户关心的事情表达：

• “正在设置你的网站……”——不要说“正在克隆仓库”/“正在搭建项目框架”。
• “正在保存更改……”/“正在更新网站……”——不要说“正在提交”/“正在推送”。
• “预览已就绪：”——不要说“已部署分支”/“构建已通过”。
• “正在发布你的网站……”——不要说“正在合并到 main”/“正在推送到生产环境”。

这只针对聊天中的措辞——幕后照常执行实际步骤，只是不使用开发者术语来描述。（唯一例外：用户明显懂技术，并明确询问仓库、分支或部署机制时，可以直接说明。CLI 标志和代码保持英文。）

参考索引（此软件包包含的内容）

两个流程文件会按需引入其余文件——除非流程指引你查看，否则无需直接阅读。

两个流程共用： references/app-cover.md（启动封面 + OG 图片）、 references/runtime-and-infra.md（TanStack 路由、SSR、Worker 运行时）、 references/security.md（Worker 加固、OWASP 审计、威胁模型）。

网站流程： references/design-recipe.md、references/wow-catalog.md、 references/wow-maker.md、references/reference-boards.md、 references/asset-system.md、references/image-to-code.md、 references/design-taste-frontend.md、references/review-rubric.md、 references/seo.md、references/scroll-scrub.md（A4 接缝锁定式旅程）、 references/scroll-scrub-asset-react.md、 references/scroll-scrub-asset-css.md 和 references/scroll-scrub-asset-video.md（仅在选择 A4 时加载的捆绑 Markdown 代码资源）。

应用流程： references/app-quickstart.md（从这里开始——可运行的关键路径：身份验证、生成提交/轮询、结果渲染、常见 Quanta 组件）、 references/quanta-design.md、references/app-layouts.md、 references/fnf-sdk.md、references/fnf-react.md、references/auth.md、 references/containers.md、references/cover-animator.md（需要权限的 约 5 秒封面视频 → og_video_url）、references/contest.md（10 万美元应用竞赛——参赛作品会自动发布应用；提交时附上社交链接）。