The ClawCap 龙虾脑控帽：一个用 Gemini 做头像配饰的 MCP Skill 源码解析

> 来源: https://x.com/xueqiu88/status/2032271374430191796

> GitHub: https://github.com/ls569333469/The-ClawCap

> 作者: 雪球（@xueqiu88）

> 背景: Solana x Trends Agent Talent Show 黑客松参赛作品（$30K USDC 奖池）

> 协议: MIT

> 日期: 2026-03-13

📌 一句话总结

一个用纯 Gemini API 实现的"头像配饰合成引擎"——AI 自动分析画风、定位头部、生成遮罩、融合配饰。虽然包装成了 meme 项目（龙虾帽），但底层的三阶段 Pipeline 设计和 Prompt 工程值得学习。

🦞 它做什么

上传任意头像 → AI 分析画风 → 自动在头顶加一顶龙虾帽 → 保持原画风一致

支持所有画风：真人照片、二次元、3D 渲染、NFT 像素风、水彩、油画、素描……

🏗️ 三阶段 Pipeline（源码深度解析）

阶段一：VLM 视觉指纹提取

文件: core/vision_fingerprint.py

模型: gemini-3.1-pro-preview

作用: 分析原图的画风、角度、光照，并精确定位头顶坐标

# VLM Prompt 设计亮点：
# 1. 强制只返回 JSON（"Return ONLY valid JSON, no markdown"）
# 2. 坐标归一化到 0.0-1.0（适配任意尺寸图片）
# 3. 无法检测头部时返回 -1（优雅降级）
# 4. temperature=0.1（极低随机性，保证稳定输出）

返回结构：
{
  "art_style": "cartoon",           # 13 种画风分类
  "face_angle": "front-facing",     # 7 种角度
  "lighting_environment": "flat shading",
  "head_top_x": 0.5,               # 头顶 X（归一化）
  "head_top_y": 0.15,              # 头顶 Y（归一化）
  "head_width": 0.3                 # 头部宽度（归一化）
}

精妙之处：

• 用 VLM 做结构化信息提取而非对话——prompt 设计严格，只要 JSON
• 13 种画风分类覆盖常见头像类型（photorealistic/anime/pixel art/nft collectible 等）
• 坐标归一化让下游处理尺寸无关

阶段二：智能遮罩生成

文件: core/mask_generator.py

工具: Pillow + NumPy（纯算法，不用 AI）

作用: 生成黑白 Mask——白色=允许重绘，黑色=绝对保护

# 核心算法：
# 1. 从 VLM 获取头顶坐标（归一化）→ 转换为像素坐标
# 2. 以头顶为锚点，向上延展椭圆形区域（"帽子穿戴空间"）
# 3. 帽子宽度 = 头部宽度 × 1.2（稍微超出头部边缘）
# 4. 帽子高度 = 头部高度 × MASK_EXPAND_RATIO（0.35）
# 5. 用椭圆距离公式填充白色区域
# 6. 高斯模糊羽化边缘（12px）→ 自然过渡

# 椭圆距离计算：
dist = ((x - cx) / rx)² + ((y - cy) / ry)²
mask[dist <= 1.0] = 255  # 椭圆内部为白色

设计考量：

• 椭圆比矩形更自然——帽子不会有硬边界
• 高斯羽化让重绘区域和保护区域平滑过渡
• 帽子区域向上延展、略微覆盖头顶——模拟"戴"的感觉
• 不用 AI 做 Mask——纯算法更快更稳定

阶段三：动态重绘融合

文件: core/inpainter.py

模型: gemini-3.1-flash-image-preview（Nano Banana 2）

作用: 在 Mask 区域内用 Inpainting 渲染配饰

# Prompt 工程原则（开发者在注释里写的非常清楚）：
# 1. 空间定位交给 Mask 图像，不在文本里写坐标数字
# 2. 只用肯定句陈述，不用 if/else 条件逻辑
# 3. 加入画风同化指令，防止材质与画风撕裂
# 4. 负面提示词不混入正向 Prompt

# 生成的 Prompt 示例：
"Equip the subject with a red beanie hat with two curved red lobster pincers. 
 Completely cover and replace any prior headwear. 
 The new headwear fits perfectly within the highlighted area shown in the mask image.
 Render the headwear STRICTLY in the cartoon style. 
 Translate all real-world materials into their cartoon artistic equivalents. 
 Preserve the original face, expression, body, and background exactly as-is."

最精妙的设计："Render the headwear STRICTLY in the {art_style} style. Translate all real-world materials into their {art_style} artistic equivalents."

这句画风同化指令解决了一个经典问题：用 AI 在二次元头像上加真实材质的帽子会导致"画风撕裂"。通过强制要求"将所有材质翻译为对应画风的等价物"，实现了风格一致性。

🔌 MCP Skill 集成

文件: mcp_server.py

框架: FastMCP（mcp.server.fastmcp）

@mcp.tool()
async def equip_avatar_accessory(
    image_base64: str,         # 头像 Base64
    accessory_prompt: str,     # 配饰描述（英文）
    negative_prompt: str = "distorted face, low quality, blurry",
) -> Image:

安全设计：

• 内容过滤：正则匹配 nude|naked|nsfw|porn|weapon|blood|gore|drug|kill|terror
• API Key 校验
• 图像尺寸限制（256-2048px）

Claude 集成：在 claude_desktop_config.json 里加一个 MCP Server 配置，然后对 Claude 说"给这个头像戴龙虾帽"就行。

🔍 关键概念详解

extract_fingerprint：让 AI 先"看懂"图再动手

Pipeline 第一步——把头像丢给 Gemini VLM，让它"看"图并返回结构化信息：

输入：一张头像图片（任何画风）

输出：6 字段 JSON

{
  "art_style": "cartoon",                      // 画风（13 种分类）
  "face_angle": "3/4 profile looking left",    // 人脸朝向（7 种）
  "lighting_environment": "warm sunset backlight",  // 光照环境
  "head_top_x": 0.48,                         // 头顶 X（归一化 0-1）
  "head_top_y": 0.12,                         // 头顶 Y（归一化 0-1）
  "head_width": 0.35                           // 头部宽度比例
}

后面两步都依赖它：

1. Mask 生成需要 head_top_x/y + head_width → 帽子放哪、放多大

2. Inpainting 需要 art_style → 帽子匹配原图画风

高斯羽化：让帽子边缘自然融入

如果 Mask 边缘非黑即白（硬切），合成结果会出现明显接缝。高斯羽化用高斯模糊处理边缘，让黑白之间产生灰色渐变：

没有羽化：         有羽化（12px）：
■■■■□□□□         ■■■▓░░□□
■■■■□□□□         ■■■▓░░□□
（硬边界→接缝）    （柔和过渡→自然融合）

■ = 白（可以画）  □ = 黑（不能动）  ▓░ = 灰色渐变（部分融合）

灰色区域 = 新图和原图按比例混合，产生自然过渡。

数学本质：用正态分布（钟形曲线）做卷积。中心权重最大，越远越小。12px 半径意味着边缘向两侧各扩散 12 像素。

MASK_FEATHER_PX = 12  # 羽化半径——经验值
# 太小（2-3px）效果不明显
# 太大（30px+）帽子边缘模糊发虚

mask_img = mask_img.filter(
    ImageFilter.GaussianBlur(radius=12)
)

本质上就是 Photoshop "羽化选区" 的代码版——自动完成，不需要手动调。

📊 技术栈

一个 API Key 搞定：全流程只依赖 Gemini，不需要 Stable Diffusion、DALL-E 或其他模型。

💡 分析

技术亮点

1. 三阶段解耦设计优秀：VLM 分析（AI）→ Mask 生成（算法）→ Inpainting（AI）。AI 和传统算法各司其职，比端到端更可控

2. Prompt 工程教科书：注释里详细解释了每个 prompt 设计决策——"不用条件逻辑""空间定位交给 Mask""画风同化指令"——这些原则适用于所有图像编辑 prompt

3. 画风同化思路可泛化：把"龙虾帽"换成任何配饰/装饰/滤镜效果，Pipeline 完全通用

4. 代码质量高：中英双语注释、完整错误处理、logging、类型标注——不像典型的黑客松赶工代码

可泛化的方向

局限

1. 依赖 Gemini 图像编辑能力：目前用的是 Preview 版本，稳定性未知

2. Mask 太简单：椭圆形 Mask 对复杂发型/姿势可能不够精确——用 SAM 等分割模型会更好

3. 没有真正的 Inpainting Mask 传递：代码注释说 Mask 是"预留"的——实际没有传给 Gemini API，只靠 Prompt 引导空间定位

4. Demo 跑在裸 IP 上：没有域名、没有 HTTPS，说明是快速部署

📊 评分

报告由深度研究助手自动生成 | 2026-03-13

来源: https://x.com/xueqiu88/status/2032271374430191796 | https://github.com/ls569333469/The-ClawCap