ui-ux-pro-max-skill Logo 设计管线详解：BM25 设计简报检索与 Gemini/Atlas Cloud 双通道生成实战

本文围绕 ui-ux-pro-max-skill 仓库中的 Logo 设计参考文档 logo-design.md 展开，完整讲清该技能"先检索、后生成"的 Logo 设计工作流：如何用 search.py 的 BM25 引擎从 55 种风格、55 组色板、55 个行业数据中生成设计简报，再用 generate.py 通过 Gemini（Nano Banana）或 Atlas Cloud 双通道产出 Logo 图片。读完本文，你可以直接复制文中的命令完成一次完整的 AI Logo 设计流程，并理解每个参数在底层代码中的实际行为。

Logo 子技能在 Design 技能中的位置

ui-ux-pro-max-skill 的 design 技能是一个统一的设计入口，其 SKILL.md 将 Logo 设计描述为"55 styles, Gemini or Atlas Cloud AI"的生成能力之一，与 brand、tokens、UI、CIP、slides、banners、social photos、icons 并列。Logo 子技能的全部资产集中在 .claude/skills/design/ 下，按职责分为三层：

层	路径	职责
参考文档	references/logo-design.md	本主题的入口文档，定义脚本、命令、风格与配色规范
数据层	data/logo/styles.csv、data/logo/colors.csv、data/logo/industries.csv	三张 CSV 数据表，供 BM25 检索
执行层	scripts/logo/search.py、scripts/logo/generate.py、scripts/logo/core.py	检索 CLI、生成 CLI、BM25 检索引擎

文档原文对三个脚本的定位如下：

Script	Purpose
scripts/logo/search.py	Search styles, colors, industries; generate design briefs
scripts/logo/generate.py	Generate logos with Gemini Nano Banana or Atlas Cloud
scripts/logo/core.py	BM25 search engine for logo data

需要说明的是，文档中命令示例使用 ~/.claude/skills/design/scripts/logo/ 前缀，这是技能安装到用户主目录后的运行时路径；在仓库内，这些文件对应 .claude/skills/design/scripts/logo/ 目录，内容完全一致。

检索内核 core.py：BM25 引擎如何工作

core.py 是整个子技能的检索基础，文档称其为"BM25 search engine for logo data"。从源码结构看，它包含四个关键设计点：

1. 数据目录与三域配置。 数据目录由 DATA_DIR = Path(__file__).parent.parent.parent / "data" / "logo" 定位（core.py 第 14 行），默认最多返回 3 条结果（MAX_RESULTS = 3）。CSV_CONFIG 为每个域（style / color / industry）分别指定：

• 数据文件（styles.csv / colors.csv / industries.csv）；
• 参与检索的列（search_cols），即 BM25 文档由哪些列拼接而成。例如 style 域用 Style Name、Category、Keywords、Best For 四列拼成"文档"，color 域用 Palette Name、Category、Keywords、Psychology、Best For；
• 输出列（output_cols），决定最终展示哪些字段。例如 color 域会输出完整的五色 Hex 值（Primary/Secondary/Accent/Background/Text Hex）。

2. 标准 BM25 实现。 BM25 类（core.py 第 37-96 行）采用经典参数 k1=1.5, b=0.75，词元化规则是"小写化、去标点、过滤长度 ≤ 2 的词"（第 50-53 行），IDF 公式为 log((N - f + 0.5) / (f + 0.5) + 1)。检索时只对得分大于 0 的文档返回结果（第 123-124 行），因此不相关的查询不会硬凑结果。

3. 域自动检测。 当你不传 --domain 时，detect_domain() 会基于关键词计数在三个域之间做判定：style 域关键词包含 minimalist、vintage、emblem、wordmark 等；color 域包含 palette、hex、颜色词；industry 域包含 tech、healthcare、finance、food 等。若所有域都没有命中，默认回退到 style 域（第 143 行）。

4. 全域检索。 search_all() 对三个域各取最多 2 条结果合并返回，这正是设计简报（design brief）的数据来源。

第一步：生成设计简报（Design Brief）

文档明确把设计简报标记为工作流起点（"Design Brief (Start Here)"）。推荐命令：

python3 ~/.claude/skills/design/scripts/logo/search.py "tech startup modern" --design-brief -p "BrandName"

在仓库实际路径下等价于 python3 .claude/skills/design/scripts/logo/search.py ...。--design-brief（可缩写 -db）会调用 search_all() 跨三个域检索，-p 指定品牌名；generate_design_brief()（search.py 第 37-91 行）会把结果组织成带四个板块的简报：

• INDUSTRY ANALYSIS：行业分析，输出推荐风格、主色、字体、常用符号、情绪、最佳实践与规避项；
• STYLE RECOMMENDATIONS：风格推荐，每个风格给出色彩、字体、效果、适用场景与复杂度；
• COLOR PALETTE OPTIONS：色板选项，含 Primary/Secondary/Accent/Background 的 Hex 值与心理暗示；
• 末尾以品牌名大写作为简报标题（LOGO DESIGN BRIEF: BRANDNAME）。

这个板块结构在 search.py 第 52-88 行中逐项拼出，Agent 拿到简报后即可直接进入下一步生成。

第二步：按域检索风格、色板与行业规范

文档给出的三个域检索命令可直接使用：

# Styles
python3 ~/.claude/skills/design/scripts/logo/search.py "minimalist clean" --domain style

# Color palettes
python3 ~/.claude/skills/design/scripts/logo/search.py "tech professional" --domain color

# Industry guidelines
python3 ~/.claude/skills/design/scripts/logo/search.py "healthcare medical" --domain industry

以第一条命令为例，实际执行输出如下（已按 token 优化格式，单字段超过 300 字符会被截断，见 search.py 第 29-30 行）：

## Logo Design Search Results
**Domain:** style | **Query:** minimalist clean
**Source:** styles.csv | **Found:** 3 results

### Result 1
- **Style Name:** Minimalist
- **Category:** General
- **Keywords:** clean, simple, essential, whitespace, geometric, modern
- **Primary Colors:** #000000 #FFFFFF #F5F5F5
- **Secondary Colors:** Single accent only
- **Typography:** Sans-serif thin weight
- **Effects:** None, sharp edges, high contrast
- **Best For:** Tech startups SaaS apps professional services
- **Avoid For:** Playful brands children entertainment
- **Complexity:** Low
- **Era:** 2010s-Present

### Result 2
- **Style Name:** Swiss/International
- **Category:** Design
- **Keywords:** grid-based, rational, clean, functional
...

除文档列出的用法外，CLI（search.py 第 94-103 行）还支持两个文档未提及的选项：--max-results / -n 调整返回条数（默认 3，对应 MAX_RESULTS），以及 --json 输出原始 JSON 结果，便于程序化处理。--domain 的合法取值即 CSV_CONFIG 的键：style、color、industry。

数据层：55 种风格、55 组色板与 55 个行业

文档标题摘要写"55+ styles, 30 color palettes, 25 industry guides"；而从当前仓库数据文件实际内容看，三张表都已扩充到 55 行：styles.csv 覆盖 55 种风格，colors.csv 与 industries.csv 各含 55 组数据。这意味着文档正文中的风格分类表与配色表是数据的一个精选子集，完整取值以 CSV 为准。

文档归纳的风格分类表如下（"Available Styles"小节）：

Category	Styles
General	Minimalist, Wordmark, Lettermark, Pictorial Mark, Abstract Mark, Mascot, Emblem, Combination Mark
Aesthetic	Vintage/Retro, Art Deco, Luxury, Playful, Corporate, Organic, Neon, Grunge, Watercolor
Modern	Gradient, Flat Design, 3D/Isometric, Geometric, Line Art, Duotone, Motion-Ready
Clever	Negative Space, Monoline, Split/Fragmented, Responsive/Adaptive

CSV 中每个风格记录还带有文档未展示的字段：Complexity（复杂度）、Era（时代）、Avoid For（不适用于什么品牌），例如 styles.csv 中 "3D/Isometric" 标记为 High 复杂度、2018-Present 时代，"Neon/Glow" 明确 Avoid 于 "Corporate healthcare traditional" 场景——这些字段会直接出现在设计简报的 STYLE RECOMMENDATIONS 板块中。

色彩心理学方面，文档给出核心速查表：

Color	Psychology	Best For
Blue	Trust, stability	Finance, tech, healthcare
Green	Growth, natural	Eco, wellness, organic
Red	Energy, passion	Food, sports, entertainment
Gold	Luxury, premium	Fashion, jewelry, hotels
Purple	Creative, innovative	Beauty, creative, tech

而 colors.csv 提供了可直接落地的完整色板。每条色板包含五个 Hex 通道与心理学描述，例如：

Palette	Primary	Secondary	Accent	心理暗示	Best For
Tech Gradient	#6366F1	#8B5CF6	#06B6D4	Innovation technology forward-thinking	Tech startups SaaS AI companies
Classic Blue Trust	#003366	#0055A4	#FFD700	Trust reliability professionalism	Finance legal healthcare corporate
Luxury Gold	#1C1917	#44403C	#D4AF37	Luxury prestige exclusivity wealth	Luxury fashion jewelry hotels
Eco Green	#228B22	#2E8B57	#8FBC8F	Growth sustainability health nature	Organic eco wellness environmental
Vintage Sepia	#704214	#A0522D	#D2B48C	Nostalgia heritage authenticity	Craft heritage artisan vintage

行业默认值表（文档"Industry Defaults"小节）：

Industry	Style	Colors	Typography
Tech	Minimalist, Abstract	Blues, purples, gradients	Geometric sans
Healthcare	Professional, Line Art	Blues, greens, teals	Clean sans
Finance	Corporate, Emblem	Navy, gold	Serif or clean sans
Food	Vintage Badge, Mascot	Warm reds, oranges	Friendly, script
Fashion	Wordmark, Luxury	Black, gold, white	Elegant serif

industries.csv 在此基础上进一步扩充到 55 个行业，每个行业除推荐风格与配色外，还给出 Common Symbols（常用符号）、Mood、Best Practices 与 Avoid 四列。例如 Technology 行业推荐 "Minimalist Abstract Mark Gradient Geometric"，常用符号是 "Circuit nodes data infinity loop"，明确避免 "Overly complex clip art dated fonts"；Healthcare 行业则建议避免使用红色（血液联想）与过于冷硬的风格。设计简报的 INDUSTRY ANALYSIS 板块正是逐列输出这些字段。

第三步：generate.py 生成 Logo

文档给出三条代表性命令，并强调 ALWAYS use white background for output logos（生成的 Logo 一律要求白色/透明背景——这一约束实际写在生成脚本的提示词模板中，后文详述）：

python3 ~/.claude/skills/design/scripts/logo/generate.py --brand "TechFlow" --style minimalist --industry tech
python3 ~/.claude/skills/design/scripts/logo/generate.py --prompt "coffee shop vintage badge" --style vintage
python3 ~/.claude/skills/design/scripts/logo/generate.py --brand "TechFlow" --provider atlas

文档摘要的选项为 --style、--industry、--prompt、--provider、--atlas-model；结合 generate.py 的 main()（第 488-558 行），完整参数面如下：

参数	说明	备注
--prompt / -p	Logo 描述提示词	与 --brand 至少提供一个，否则报错
--brand / -b	品牌名	会插入提示词头部 Logo for 'Brand': 并用于默认文件名
--style / -s	风格修饰符	取值限定于 STYLE_MODIFIERS 的 18 个键
--industry / -i	行业	取值限定于 INDUSTRY_PROMPTS 的 10 个键
--output / -o	输出文件路径	缺省为 {brand}_{时间戳}.png
--output-dir	批量模式的输出目录	缺省为 ./{brand}_logos
--batch	批量生成变体数	批量模式专用
--brand-context	附加品牌上下文	前置到批量模式提示词
--pro	使用 Nano Banana Pro 模型	仅 --provider gemini 有效，与 --provider atlas 互斥（第 542-543 行）
--provider	gemini（默认）或 atlas	选择图像生成通道
--atlas-model	Atlas Cloud 模型	默认 google/nano-banana-2-lite/text-to-image
--aspect-ratio / -r	画面比例	可选 1:1、16:9、9:16、4:3、3:4，默认 1:1（Logo 用方形最理想）
--list-styles	列出 18 种风格修饰符	只打印不生成
--list-industries	列出 10 个行业	只打印不生成

双通道模型。 generate.py 顶部定义了模型常量：Gemini 通道默认使用 gemini-2.5-flash-image（Nano Banana，定位是"fast, high-volume, low-latency"），加 --pro 切换 gemini-3-pro-image-preview（Nano Banana Pro，定位"professional quality, advanced reasoning"）；Atlas 通道默认模型为 google/nano-banana-2-lite/text-to-image，API 基址为 https://api.atlascloud.ai/api/v1。

提示词增强机制。 enhance_prompt()（第 126-140 行）把品牌名、风格修饰符、行业提示依次拼接到基础提示词上，最后套入 LOGO_PROMPT_TEMPLATE 模板。该模板正是"白底 Logo"规则的代码落点，其硬性要求包括：干净的矢量风格、任何尺寸下都可缩放、清晰剪影、居中构图于纯白或透明背景、除非特别要求否则不加文字、高对比清晰边缘、方形完美居中。STYLE_MODIFIERS 收录 18 种风格（minimalist、vintage、modern、luxury、playful、corporate、organic、geometric、hand-drawn、3d、abstract、lettermark、wordmark、emblem、mascot、gradient、lineart、negative-space），INDUSTRY_PROMPTS 收录 10 个行业（tech、healthcare、finance、food、fashion、fitness、eco、education、real-estate、creative）；不在此表中的取值会被静默忽略，风格/行业参数因此是"受控词表"而非自由文本。

批量模式。 --batch N 会调用 generate_batch()（第 400-485 行），从固定的 9 种风格序列（minimalist、modern、geometric、gradient、abstract、lettermark、negative-space、lineart、3d）中依次取用，输出文件命名为 {brand}_{style}_{序号}.png，并在每次请求之间 sleep(2) 做速率控制。文档头注释中的批量示例：

python generate.py --brand "Unikorn" --batch 9 --output-dir ./logos --pro

Atlas Cloud 通道的底层细节

Atlas 通道是显式选择加入的（--provider atlas），其异步 API 的调用链在 generate.py 第 237-281 行：先 POST /model/generateImage（payload 为 model、prompt、aspect_ratio），拿到 prediction id 后以 ATLAS_POLL_INTERVAL = 2 秒为间隔轮询 /model/prediction/{id}，最多轮询 ATLAS_MAX_POLLS = 90 次，状态到达 completed 后从 outputs[0] 下载图片，遇到 failed/timeout/canceled/cancelled 立即抛错。该通道还有两处安全性设计值得注意：

• SSRF 防护：_validate_public_https_url()（第 151-173 行）强制媒体 URL 必须为 HTTPS、拒绝 localhost/.local/.internal 类主机名，并要求 IP 型主机必须是全局公网地址；重定向由 _SafeRedirectHandler 拦截并复用同一校验；
• 密钥隔离：下载图片时只携带 Accept: image/* 与 User-Agent，绝不转发 Authorization 头。

这两点都有测试佐证：tests/test_generate.py 中 test_atlas_submits_once_and_polls_until_completed 验证"提交一次、轮询至完成"的时序，test_media_download_never_forwards_api_key 验证下载请求头中不含 authorization 字段，另有测试断言 Atlas 提交失败时不会重试 POST。Gemini 通道则走 google.genai SDK（_generate_with_gemini，第 284-334 行），配置 response_modalities=["IMAGE", "TEXT"] 与四项 BLOCK_LOW_AND_ABOVE 安全阈值，从返回的 inline_data 中提取 image/* 数据落盘；未安装 SDK 时会给出明确指引："run: pip install google-genai"。

环境配置（Setup）

文档给出的 Setup 章节完整继承如下，适用于仓库中脚本的实际读取逻辑：

export GEMINI_API_KEY="your-key"
pip install google-genai

# Optional Atlas Cloud provider (no extra Python package required)
export ATLASCLOUD_API_KEY="your-key"

两个前提需要说明：

1. Gemini 是默认通道，需要 GEMINI_API_KEY 且必须安装 google-genai Python 包；Atlas 通道只需 ATLASCLOUD_API_KEY 环境变量，不需要额外 Python 依赖（generate.py 使用标准库 urllib 直接请求）。
2. .env 文件支持：load_env()（generate.py 第 35-54 行）按优先级依次读取三处 .env 文件——<design技能目录>/.env、~/.claude/skills/.env、~/.claude/.env，且已存在于进程环境中的变量不会被覆盖。因此 API Key 既可以 export，也可以写入这些 .env 文件之一。

标准工作流（Workflow）

文档定义的 4 步工作流保持不变，这里补充每一步的落点：

1. 生成设计简报 → scripts/logo/search.py --design-brief（跨三域检索，产出行业/风格/色板三板块）；
2. 生成 Logo 变体 → scripts/logo/generate.py --brand --style --industry（按需加 --batch、--pro、--provider atlas）；
3. 询问用户是否需要 HTML 预览 → 使用 AskUserQuestion 工具（面向 Claude 等支持该工具的 Agent 环境）；
4. 若用户同意 → 调用 /ui-ux-pro-max 技能生成 HTML 画廊，便于在浏览器中对比多个 Logo 变体。

深入阅读：三份配套参考文档

文档末尾的 "Detailed References" 列出三份同目录参考文档（已转换为仓库相对路径）：

• logo-style-guide.md — 风格详述（Detailed style descriptions）；
• logo-color-psychology.md — 颜色含义与搭配（Color meanings and combinations）；
• logo-prompt-engineering.md — AI 生成提示词工程（AI generation prompts）。

三者与本文的分工是：本文聚焦"命令 + 数据 + 生成管线"的可执行层面，风格语感、配色理论与提示词技巧的细节可对照上述文档深入。

小结

Logo 子技能的设计哲学是"数据先行、生成殿后"：先用 core.py 的 BM25 引擎（k1=1.5、b=0.75、过滤短词、得分 > 0 才返回）在 55×3 的结构化设计数据中检索出有据可依的风格、色板与行业约束，形成设计简报；再由 generate.py 把受控词表内的风格/行业修饰符与白底矢量化的提示词模板拼装起来，交给 Gemini 或 Atlas Cloud 双通道出图，Atlas 通道附带轮询上限、公网 URL 校验与密钥隔离等工程防护，并有单元测试锁定其行为。这套"检索—简报—生成"管线是本文所有命令可直接复现、且行为可从源码逐行追溯的原因。