Neoo-Blue/colab-flux

colab-flux 是做什么的？

在租用的 Colab GPU 上运行 FLUX 3 Image Klein，由 fluxx 驱动。一次 fluxx gen 会启动一台 A100 -> 安装 diffusers -> 下载并加载 FLUX 3 和评判模型 -> 渲染每张照片（从多次生成中选出最佳，经过评判）-> 下载图片 -> 保持 GPU 预热数分钟以便后续任务，然后停止它。将所有可能需要的照片批次处理到一个调用中。

产生图片一致性的关键是品牌档案，而非运气：

• 产品参考：产品的真实照片，每次生成时作为参考图像传递给 FLUX 3，以使产品保持其形状、标签和颜色（最多 10 张参考）
• 风格：一段具体的摄影语言描述，附加到每个场景中
• 避免：永远不应出现的内容
• 随机种子：每个品牌固定，因此相同场景会以相同方式渲染
• 反馈：每张照片都记录；fluxx rate 记录用户喜欢的内容及其原因，然后你可以将模式反馈到风格中

所有内容都存放在 ~/colab-flux/brands/<name>/ 中：brand.json、refs/、history.jsonl、shots/<time>/。

1. 首次使用：检查设置

运行 fluxx doctor（如果找不到 fluxx，首先运行 sh <此技能文件夹>/install.sh）。它会打印出 ok / TODO 行。逐一引导用户完成每个 TODO，用通俗语言解释：

TODO	用户操作	备注
Colab CLI 未安装	无需操作：你运行此技能文件夹中的 sh install.sh	安装 uv 和官方 Colab CLI
未登录 Google	在用户自己的终端中运行 fluxx login	浏览器会打开以进行 Google 登录。你不能替他们完成此操作
计算单元	在 https://colab.research.google.com/signup 购买 Colab Pro 或计算单元	A100 不在免费套餐中
Hugging Face（可选）	默认无需操作：没有令牌时，fluxx 会在检查每个权重文件的 sha256 与官方仓库一致后，从公共镜像下载。对于官方仓库：fluxx login 会打开 FLUX 3 页面，用户点击同意，创建一个读取令牌并粘贴到隐藏提示框中	免费。切勿要求他们将令牌粘贴到聊天中
没有品牌	无需操作：你执行下面的品牌访谈

fluxx login 通过隐藏提示框请求令牌，因此需要一个真正的终端：在 Claude Code 中，告诉用户打开一个终端标签页并在那里运行它（Codex 同理）。当用户表示已完成时，再次运行 fluxx doctor。

2. 品牌访谈（每个品牌一次）

用一条消息提问以下问题，保持简短并附上示例，以便用户在一分钟内回答：

1. 该业务是什么，以及哪些产品应该出现？（例如“手灌大豆蜡蜡烛，琥珀色玻璃罐”）
2. 谁会购买它，图片将用于何处？（Shopify、Amazon、Etsy、Instagram、广告、印刷品）
3. 风格，用几个词或一个他们欣赏的品牌来描述。（例如“宁静、温暖、斯堪的纳维亚风格，像 Aesop”）
4. 有哪些内容绝对不能出现？（人物、文字、竞品物品、杂乱、某些颜色）
5. 产品的照片：文件路径或拖入。每个产品的简单、光线良好的照片效果最佳。

然后将答案转化为档案。将形容词翻译成摄影师会使用的词语，因为这是 FLUX 遵循的语言。“宁静而温暖”变为“左侧柔和的漫射窗光，温暖的中性调色板（燕麦色、沙色和陶土色），哑光亚麻和浅橡木表面，浅景深，充裕的留白，编辑风格的产品摄影”。

fluxx brand new acme-candles --business "Acme, 手灌大豆蜡蜡烛，琥珀色玻璃罐" \
  --style "左侧柔和的漫射窗光，温暖的中性调色板……" \
  --avoid "人物、手部、除罐标签外的书面文字、杂乱" --aspect 4:5
fluxx brand ref acme-candles /path/to/jar-front.jpg            # role: product（默认）
fluxx brand ref acme-candles /path/to/moodboard.jpg --role style

根据目标调整宽高比：Amazon/Shopify 产品网格 1:1，Instagram 信息流 4:5，故事/Reels 9:16，网页主图 16:9，Etsy 4:3 或 1:1。品牌的宽高比是默认值；--aspect 可在每次运行时覆盖。向用户展示你编写的档案（fluxx brand show NAME），并询问是否符合他们的想法。

3. 制作图片

1. fluxx brand show NAME：在编写任何内容之前，先阅读档案和最近的反馈。
2. 编写场景。每行一个简短具体的描述，仅关于场景。品牌风格、避免列表和参考角色会自动添加，FLUX 3 自己的提示增强器（GPU 上的一个 9B 模型）会将每行扩展为完整描述，因此无需花费令牌编写冗长提示。好的示例：罐子放在阳光照耀的橡木窗台上，早晨，旁边有一枝干桉树。
3. 将所有用户可能想要的照片收集到一次调用中（启动是最昂贵的部分）：

   fluxx gen -b acme-candles -n 2 "场景一" "场景二" "场景三"
   fluxx gen -b acme-candles --from shots.txt          # 每行一个场景，# 为注释
   

   一个场景可以通过前缀设置其自身形状，因此一次运行可以混合多种格式： 16:9 | 罐子放在阳光照耀的窗台上，左侧留白用于标题。 冷启动大约需要 4 分钟，然后每张 4 MP 渲染大约 45 秒。在 Claude Code 中使用 run_in_background 运行；在 Codex 中让它运行。它会在标准输出上每行打印一张图片路径；进度、每张照片的评判分数和缺陷以及计算单元成本会输出到标准错误。 当用户在使用产品的场景中时，说明如何操作：“将手机听筒举到耳边，其线缆延伸出画面；电话底座不可见”。FLUX 会按照参考显示产品的方式绘制产品，因此被提起的部分往往会出现两次（在测试中，即使提示说支架是空的，一个被举起的听筒加上电话底座上仍有一个）。将产品的其余部分框出画面解决了这个问题。
4. 最佳 N 选一，在 GPU 上评判。 每张照片最多渲染 --candidates 个图像（默认 3）。一个视觉语言评判模型（Qwen3.5-9B，在同一 GPU 上）根据简报、产品参考和避免列表（解剖结构、重复对象、产品保真度、多余文本、吸引力）检查每个图像，保留最佳的一个，并在一个图像得分 9+ 且无缺陷时提前停止。其他图像以较小尺寸返回在 alts/ 中，以便用户仍然可以选择。
5. 你自己也要查看 _md.jpg 文件（它们很小），特别是那些标准错误中列出了缺陷或分数低于 7 的照片。指出问题所在，而不是直接呈现为已完成。然后向用户提供文件夹和路径。
6. GPU 之后保持预热（--keep，默认 5 分钟），并且模型保持加载，因此后续相同设置的 fluxx gen 会立即开始渲染，而不是等待约 4 分钟。呈现图片后立即询问：“GPU 仍将预热 N 分钟（空闲时大约 X 个计算单元）。需要更多或修改吗？否则我将关闭它。”如果用户完成，运行 fluxx stop。如果用户无回应，它会自动停止。如果用户要求更长时间，在下次运行时传递 --keep 15，或使用 fluxx config keep_minutes 15 保存新默认值。--keep 0 会在运行结束时停止 GPU。

标志：-n N 每个场景的变体数量（种子 seed..seed+N-1）· --candidates K 每张照片的渲染次数，保留最佳（1-8）· --keep MIN 预热分钟数 · --draft 仅 1 MP 中等尺寸，一个候选，速度更快，用于探索新方向 · --aspect W:H · --ref PATH 一次性的额外产品照片 · --no-refs · --seed S · --no-upsample 当场景已经是完整描述时（跳过 19 GB 下载）· --out DIR。

每个场景的输出：<id>_hd.png（约 4 MP，例如 2048x2048，用于打印、缩放和主图）和 <id>_md.jpg（长边 1024 像素，用于列表、网页和社交媒体）。

4. 平台列表（Amazon、Etsy、eBay、Shopify）

当图片用于在线销售产品时，使用 fluxx listing 代替 gen。一次运行可以生成标准的六张正方形 4 MP 照片集，导出到每个平台对应的文件夹，包含该平台要求的顺序、名称和尺寸，并在 GPU 上草拟列表文案（评判模型编写，因此不消耗 Claude 令牌）：

fluxx listing -b acme-candles --product "琥珀色玻璃罐中的手灌大豆蜡蜡烛，带木盖" \
  --notes "8 盎司，50 小时燃烧时间，棉质灯芯，香味：雪松和烟熏，俄勒冈制造" --for amazon,etsy

照片（角色）	内容	品牌风格
main	产品单独放在纯白背景上，居中	无：然后 fluxx 将背景准确设为 RGB 255，并将产品缩放到填充画面的 85%（亚马逊主图规则）
angle	白色背景上的四分之三视角	无
detail	材质和工艺特写	无
lifestyle	在使用中，在适合买家的环境中	是
scale	与日常物品并置，以清晰显示尺寸	是
gift	拿在手中或作为礼物，不露脸	是

输出在运行文件夹下的 markets/<site>/ 中：

平台	图片	文案（listing.md + copy.json），由 fluxx 执行限制
amazon	MAIN.jpg、PT01.jpg……2048 像素	标题 75 字符（2026 年 7 月起限制），商品要点 125，5 个要点各 200，描述 2000，搜索词 250 字节
etsy	01.jpg……2048 像素，首先是一张风格化照片（它是搜索缩略图）	标题 140，13 个标签各 20 字符，描述
ebay	01.jpg……1600 像素	标题 80，商品规格，描述
shopify	01.jpg……2048 像素	标题 70，SEO 标题 60，SEO 描述 160，描述，标签

代理规则：

• 信息来自卖家。 在运行前询问尺寸、材料、包含物品和保养信息，并通过 --notes 传递。文案模型被告知不得编造信息，但在用户发布前，应阅读 listing.md 并删除任何不在笔记中或图片中可见的声明。
• 图片展示的是 FLUX 绘制的内容，而非真实物品。 对于 main、angle 和 detail，产品必须与用户的真实产品匹配：对照他们的照片进行检查，并告知他们市场要求图片展示实际商品。生活方式场景是生成场景最有帮助的地方。
• 完成的白色 main 图片会成为后续照片的产品参考，因此用户自己照片中的道具（桌布、装饰品）不会泄露到生活方式场景中。仍然要求提供一张简洁、光线良好的产品照片：这是 main 图片的绘制来源。
• --only main,lifestyle 可生成子集；--no-refs --ref other.jpg 可列出同一品牌的不同产品；--for etsy 可限制平台。

5. 学习用户的喜好

只有当你关闭反馈循环时，档案才会变得更好。每次用户对图片做出反应时：

fluxx rate 02-jar-on-oak-windowsill-v1 good "喜欢低角度晨光"
fluxx rate 03-jar-in-bathroom-v2 bad "太杂乱，毛巾抢走了焦点"

当两个或更多评分指向同一方向时，编辑 brand.json（它是纯 JSON；使用你的文件工具编辑）：优化 style，扩展 avoid，在 notes 中添加一条带日期的行，说明更改内容和原因。当相同的缺陷再次出现时（重复部分、错误颜色、缺失标签），在 checks 中添加一条一行规则，例如 "整个图片中恰好只有一部电话听筒"。然后评判模型从现在开始会在每个候选项上计数并验证该规则；在测试中，仅靠总分恰好错过了这类缺陷。用一行话告诉用户（“我已将‘低角度晨光’加入你的风格，并移除了罐子附近的道具”）。用户喜欢的照片可以成为风格参考： fluxx brand ref NAME <path>_hd.png --role style（参考总数上限为 10；FLUX 3 将风格参考仅视为外观，而非内容）。

根据请求更改风格（“让它更暗、更阴沉”，“我们正在重新品牌化到柔和色”）：重写 brand.json 中的 style，将旧的风格保留在 notes 中并附上日期，以便用户可以恢复；移除不再合适的风格参考；并提供一次快速的 --draft 运行，使用 3-4 个已知场景，以便用户在全批次之前看到新外观。对于第二个独立的风格（例如节日活动），创建另一个具有相同产品参考的品牌，而不是覆盖现有品牌。

规则

• 一次调用，多张照片。 切勿逐张图片循环 fluxx gen。冷启动（GPU，约 60 GB 模型，加载）大约需要 4 分钟。预热窗口内的后续任务会跳过此步骤。
• GPU 始终会停止。 失败时，fluxx 会立即停止它。成功时，它会保持预热 --keep 分钟，然后一个独立的看门狗进程会停止它，即使 fluxx 或代理已退出。在运行期间，看门狗将其上限设为 --max-minutes（默认 60）。如果运行以 NOT CONFIRMED STOPPED 结束，则立即运行 fluxx stop 然后运行 fluxx status。
• 聊天中不泄露密钥。 Hugging Face 令牌仅输入到 fluxx login 的隐藏提示框中。它被传送到用户自己的 Colab VM，该 VM 在读取后立即从磁盘删除它，并且 VM 在停止时被清除。
• 用户的图片归用户所有。 产品照片仅上传到用户自己的 Colab VM。
• 许可证。 FLUX 3 Image Klein 采用 FLUX Kommunity 许可证：免费，包括图片的商业使用，适用于个人和年收入低于 500 万美元的企业；规模较大的企业需要从 Black Forest Labs (https://bfl.ai) 获得许可证。如果潜在企业规模较大，在入职期间提一次。

命令

fluxx doctor                       # 检查哪些已设置，哪些缺失
fluxx login                        # Google 登录 + Hugging Face 令牌（用户运行，需要终端）
fluxx brand new|show|list|ref ...  # 品牌档案
fluxx gen -b NAME [...] scenes...  # 渲染（重用预热 GPU）
fluxx listing -b NAME --product .. --notes .. [--for amazon,etsy,ebay,shopify]  # 市场列表包
fluxx rate SHOT good|bad "原因"     # 反馈
fluxx config [keep_minutes|candidates N]   # 默认值：5 分钟预热，3 个候选项
fluxx status                       # Colab 会话和计算单元余额
fluxx stop                         # 停止遗留 GPU 会话（始终安全）
fluxx selftest                     # 离线检查，不调用 Colab

环境变量：COLAB_FLUX_HOME（默认 ~/colab-flux），`F