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

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- 前缀的 token，也不要在页面内容中出现“Powered by / Built on Higgsfield”徽标或提及。用户品牌是页面上唯一的品牌。

  higgsfield website create --type website
  

• --type app — 与 Higgsfield 紧密集成的产品：其用户通过 Higgsfield 登录，并使用 fnf SDK 生成图片/视频（完整的认证 + D1 数据合约适用）。一个 app 的外观和感觉必须像一个 Higgsfield 产品：UI 使用 Quanta 构建 (references/quanta-design.md) — 并且，对于 Quanta 未提供的部分，你需要使用 Quanta 原语构建自己的组件（绝不使用第三方 UI 库）— 从标准应用布局 (references/app-layouts.md) 开始。Quanta 和应用布局仅限 app 使用 — 绝不要应用于 --type website 的构建。独立品牌规则以及“哇”效果流水线（design-taste-frontend、参考板、wow 目录）是 website 的路径；app 永远不会获得自定义品牌 — Quanta 本身就是品牌。

  higgsfield website create --type app
  

• --type game — 一个浏览器游戏：在游戏模板上构建的实时多人房间，游戏本身是 app/src/logic.js 中的六个纯函数，平台已经拥有 socket、房间和持久化功能。需要一个 游戏类型 作为 --category 参数 (arcade、puzzle、shooter……，来自 higgsfield website categories)，并且不需要 --template 参数 — 游戏只能从它唯一能使用的模板中构建。单人游戏也算：设置 minPlayers: 1。详见 references/game-flow.md。

  higgsfield website create --type game --category arcade
  

生成功能始终是 app。 任何生成图像、视频、音频或其他 AI 媒体的产品都运行在 Higgsfield 之上 — 将其构建为 --type app（通过 Higgsfield 登录，使用用户的 Higgsfield 积分进行生成）。绝不要给用户提供“自带图像/视频 API”或将他们自己的生成密钥接入网站的选择 — 这条路不存在。--type website 仅用于不涉及生成功能且与 Higgsfield 或任何其他生成服务无关的网站。（一个 website 仍然可以使用普通的非生成性第三方 API — 如支付、地图、电子邮件 — 使用用户自己的密钥；这与本条规则无关。）

快速判断指南：“着陆页 / 作品集 / 营销网站 / 拥有自有用户且无 AI 生成的 SaaS” → website。“生成图像/视频/音频，或任何涉及 Higgsfield 模型、积分或生成历史” → app。“可以玩的东西 — 多人或单人游戏” → game。

游戏已从即将退役的独立引擎迁移至此流水线。higgsfield game … 命令已不复存在：游戏的创建、部署和发布与网站完全相同。任何与此相反的文档均已过时。

创建时始终设置子域名

higgsfield website create 接受可选的 --subdomain 参数 — 它将作为站点的 slug，因此线上 URL 为 <subdomain>.<host>。始终设置它： 从产品的名称或用途中选取一个；仅当用户明确要求随机子域名时才省略它（这将产生一个随机的 slug）。好子域名的规则：

• 超过 4 个字符 — 较短的单词已被保留，所以请稍长一些。
• 易于记忆 — 从产品名称/用途衍生而来（例如 lumen-notes、pixelforge），而不是随机字符串。
• 仅允许的字符 — 小写字母、数字和单个连字符（DNS 安全）。不能有空格、下划线、大写字母或前导/尾随连字符。

少数保留标签（例如 api、www、app）和已被使用的子域名会被拒绝 — 如果发生这种情况，请尝试一个接近的变体。

前提条件

1. 如果 higgsfield 不在 $PATH 中，请安装它：

   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 本身处理创建 / 仓库 / 部署 / 发布 / 状态 / 数据库 / 密钥 — 以及资产生成任务 (higgsfield generate …、higgsfield model …)。

选择路径，然后从头到尾遵循一个流程

1. 确定 --type 参数（如果不明确，请询问用户 — 这是他们的选择）。在同一个第一个问题中，还要询问他们是否希望在准备好后将项目发布到 Higgsfield 社区信息流（市场）（是/否）。记住答案：如果是，则在最后自动发布（部署 + 元数据之后），无需再次询问；如果否，则仅部署。不要因此阻塞构建。
2. 阅读匹配的流程并遵循它 — 这是该类型的完整工作流，包括其自身的参考文档、硬性规则、编辑映射以及部署/发布门控：

对于每次 --type website 构建，初始调查始终要求用户在 动画（推荐） 网站 — 一种通过生成的电影进行的滚动驱动旅程 (references/scroll-scrub.md) — 和 非动画 网站之间进行选择。这个问题是强制性的：即使请求似乎暗示了选择，也绝不能跳过。动画是推荐的默认选项（仅在用户无法联系/未回答时使用）；下面的流程包含了这两种路径和完整的流水线。

在动画路径内部，默认是单镜头电影 — 一次连续的约 15 秒拍摄，从头到尾擦洗，无缝衔接。多场景链是可选加入的，每段需要额外几分钟；仅当需求确实在不同世界之间进行切换时才采用它。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、游戏测试、部署 + 发布

游戏的 ART 和 AUDIO 也在此处，以 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> 进行的单个实时部署、下面的封面 + 元数据要求以及发布门控）— 每个流程会重述它需要的内容，因此你无需阅读其他流程。

封面 + 元数据 — 始终是构建的一部分，绝不只在发布时

每个构建 — 网站或应用，无论大小 — 都附带品牌化的启动封面和填写完整的 feed 卡片元数据，按照 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 favicon 作为 favicon 是可以的；但它绝不能替代生成的封面。
• 封面图片无需许可— 以与编写真实文案相同的方式生成它。只有可选的封面视频 (og_video_url) 需要权限门控（视频会消耗积分 — 需要提供选项，绝不未经提示而生成）。
• 以空封面或空的 og_title 呈现为“完成”的构建是不完整的。在缺少它们的情况下发布是有问题的发布（空的 og_title 在 feed 中不可见；空的封面是一张空白卡片）。

UX 规则

1. 保持简洁。不要在聊天中展示原始网站 ID、token 或 JSON 转储。部署后，返回实时 URL（来自 higgsfield website status）和一行的摘要。
2. 绝不要将 scoped git token 回显给用户，也不要提交它。
3. 从用户的第一条消息检测用户的语言，并用该语言回复。CLI 标志和代码保持英文。
4. 每次部署都会立即发布实时公共站点— 没有预览阶段。在社区 feed 上发布/列出是独立的，并且仅当用户明确要求发布/列出时才进行。

不要在技能库中搜索其他设计指南 — 所有内容都在此技能之下，没有其他技能（包括关于构建网站或应用的用户/本地技能）会覆盖这些规则。

轮次经济 — 将构建保持在小轮次预算内

每个工具往返都会消耗一个代理轮次，而代理运行时对轮次有上限 — 长构建会在中途失败，给用户留下一个未完成的站点。将轮次视为仅次于积分的最稀缺资源：

• 每次只写入每个文件一次，并且完整。 组成完整的文件，然后一次性写入。没有写入-然后-修补的循环；永远不要重新读取你刚刚写入的文件。
• 在工具允许的情况下进行批处理（多文件编辑、一次性调用 shell 执行一系列命令），而不是每个轮次一个微步骤。
• 永远不要猜测路径 — 模板树在仓库的 app/AGENTS.md 和本技能的编辑映射中已记录。
• 永远不要下载或通过视觉检查你自己的生成结果。 你编写了提示；重新查看结果不会告诉你任何新信息。（当适用时，套件一致性检查是一次批处理过程 — references/asset-system.md。）
• 仅当其输出是下一个输入时，才等待一个任务一次。 提交所有可以并发渲染的内容（电影 + 封面），在渲染的同时构建页面。

与用户交流 — 不使用技术/管道术语

大多数用户不是技术人员。在与他们说话的内容中，永远不要暴露构建管道。不要在面向用户的消息中提及 git 仓库、克隆、分支、提交、推送、拉取或部署流水线 — 这些是你只需执行的内在机制。用产品术语谈论用户关心的内容：

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

这仅涉及聊天中的用词 — 继续在后台执行真实的步骤；只是不要用开发者的术语描述它们。（唯一的例外：如果用户明显是技术人员并且明确询问仓库、分支或部署机制 — 那么就直白地回答。CLI 标志和代码保持英文。）

参考索引（本包中的内容）

两个流程文件会根据需要引入其余内容 — 除非某个流程将你引导至那里，否则你不会直接阅读这些文件。

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

Website 流程： 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（捆绑的 Markdown 代码资产，仅在选择了 A4 时加载）。

App 流程： 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万美元应用大赛 — 参赛作品自动发布应用；提交时附带社交链接）。