Holo Card Studio Skill 使用指南：用一句话生成可编辑的 3D 全息闪卡

工具教程2026-09-07约 16 分钟Holo Card StudioCodex SkillClaude SkillBlenderThree.js3D全息卡视差

如果你想把一段描述、一张参考图或一个角色设定，变成一张可以拖动、翻面、调节镭射效果的 3D 全息闪卡，holo-card-studio 是一个很有意思的 Skill。

它的重点不是生成一张静态海报，而是同时交付三类结果：

一组可以替换和重跑的分层图像资产；
一个可以继续编辑的 Blender 卡片工程；
一个使用 Three.js 在浏览器中交互的本地网页。

用户可以拖拽卡片观察视差，翻到背面，调节效果滑块，并在 Blender 中继续修改材质、灯光和渲染。Skill 本身只包含代码和文字，具体生成的画作、.blend、模型和输出项目属于用户自己的项目目录。

本文基于 EverettFish/holo-card-studio 的 README、SKILL.md、配置示例和验收清单整理而成，重点解释它的能力边界和最短成功路径，而不是复制仓库原文。

一句话理解 Holo Card Studio

文字描述或参考图
  → 主体 / 背景 / 线稿 / 文字四层资产
  → Blender 可编辑场景
  → 真实卡片几何和材质角色
  → Three.js 交互网页
  → 浏览器验收与最终交付

它更接近一个“从创意到可交互展示物”的内容生产 Skill，而不是单独的图像生成器。

适合谁使用

这个 Skill 适合以下用户：

想快速制作纪念卡、角色卡、收藏卡或产品卡的人；
希望把宠物、人物或角色做成立体闪卡的人；
独立游戏开发者和视觉设计师；
想研究 Blender 材质、视差和 Three.js 重建效果的人；
需要为活动、发布会、社交媒体或线上展览制作互动物料的人；
想通过 AI coding agent 生成一个可编辑项目，而不只是得到一张 PNG 的开发者。

如果你的目标只是输出一张平面海报、头像或普通插画，这个 Skill 可能过重。它的价值在于“分层、可编辑、可交互和可复用”。

完成标准：什么时候才算真的做好

不要把“脚本执行完成”或“本地端口已经启动”当作最终结果。一个完整交付至少应该满足：

四层图片存在，并且画布尺寸一致；
主体和线稿对齐，没有明显漂移；
主体、文字层使用了真实透明通道，而不是画出来的棋盘格；
Blender 场景可以打开，素材路径和参数有效；
导出的 GLB 包含真实网格和网页约定的材质角色；
Three.js 页面可以加载模型和纹理；
桌面端支持拖拽、翻面、重置和参数调节；
移动端没有横向溢出，触摸布局可用；
WebGL 没有 Shader 编译错误；
视差方向、镭射相位和线稿发光效果经过肉眼验证；
输出项目和 Skill 源码分离，生成素材没有被错误打包进 Skill。

核心概念：一张卡片由四层图叠出来

Holo Card Studio 的关键设计是把一张全息卡拆成四个同尺寸图层：

        你的视线
           │
   ┌───────┴────────┐
   │   text.png     │ 文字层：标题、编号、属性
   ├────────────────┤
   │   lineart.png  │ 线稿层：稀疏发光轮廓
   ├────────────────┤
   │   subject.png  │ 主体层：角色、宠物、产品或人物
   ├────────────────┤
   │ background.png │ 背景层：环境、色彩和气氛
   └────────────────┘

浏览器通过不同的深度和缩放，把这些图层“撑开”成有前后关系的画面：

文字通常贴近卡片表面；
线稿作为稀疏的高亮轮廓；
主体向前凸出；
背景向后退；
镭射彩虹和星光根据视角变化；
卡片边缘使用独立材质表现厚度和金属效果。

这也是为什么不能只生成一张完整图片再期待它自动变成 3D 卡片：视差需要知道哪些像素属于主体、背景、文字和线稿。

目录结构与每个文件的职责

仓库大致分成三类内容：Skill 说明、生产脚本和网页模板。

holo-card-studio/
├── SKILL.md
├── references/
│   ├── art-direction.md
│   ├── config.example.json
│   └── verification.md
├── scripts/
│   ├── ensure_blender.py
│   ├── build_card.py
│   ├── export_web.py
│   ├── generate_typography.py
│   ├── validate_assets.py
│   ├── run_pipeline.py
│   └── package_skill.py
└── assets/
    └── web-template/

各部分的职责如下：

路径	作用
`SKILL.md`	给 coding agent 读取的工作规则、顺序和不变量
`references/art-direction.md`	分层画图提示词与参考图处理方法
`references/config.example.json`	卡片元数据与参数配置示例
`references/verification.md`	Blender、GLB、浏览器和移动端验收清单
`scripts/ensure_blender.py`	查找或安装项目本地的官方便携版 Blender，并校验 SHA-256
`scripts/build_card.py`	生成可编辑 Blender 场景
`scripts/export_web.py`	从 Blender 场景导出网页所需几何
`scripts/generate_typography.py`	生成精确的透明文字层
`scripts/validate_assets.py`	检查素材尺寸、透明度和基础完整性
`scripts/run_pipeline.py`	串联 Blender、导出和 Three.js 网页生成
`scripts/package_skill.py`	只打包 Skill 源码和文字资源
`assets/web-template/`	不包含个人画作的响应式 Three.js 查看器

环境要求

官方说明的基础环境包括：

Python 3；
Pillow；
Node.js；
npm；
一个可用的图像生成工具；
Blender。

Blender 不要求用户提前手动安装。流水线可以在项目的 <project>/tools 目录中准备官方便携版，并进行哈希校验。这样每个输出项目可以拥有自己的 Blender 运行时，避免覆盖系统已有版本。

但这不代表所有环境都一定能够自动完成安装。网络、平台架构、权限或官方下载地址变化，都可能导致 Blender 获取失败。遇到这类问题时，应先保留明确的错误信息，不要重复运行同一个失败命令。

最短成功路径：从一句话到可交互卡片

下面是最短、最适合第一次使用的路径。

第一步：准备输出项目和卡片规格

先确定一个独立的输出目录，例如：

my-holo-card/
├── assets/
├── tools/
├── web/
└── card-config.json

然后写一段清晰的卡片需求，至少说明：

主体是谁；
视觉风格是什么；
背景氛围是什么；
卡片文字、编号和稀有度是什么；
是否有参考图；
是否需要背面设计；
交付目标是浏览器分享、Blender 编辑还是图片导出。

例如：

用水墨与金色箔片风格制作一张锦鲤全息卡。主体是一条跃出水面的红白锦鲤，背景是深蓝池水和淡金色涟漪，文字为“锦鲤 · No.001”，保留主体轮廓，网页端需要支持拖拽视差、翻面和手机布局。

如果使用参考图，应明确哪些内容必须保留，哪些内容允许改变。比如“保留人物身份和构图，背景改成星空，文字重新排版”，比“照这张图做”更容易得到稳定结果。

第二步：生成四层素材

生成或准备以下文件：

<project>/assets/subject.png
<project>/assets/background.png
<project>/assets/lineart.png
<project>/assets/text.png

要求：

四层使用同一画布尺寸；
subject.png 和 text.png 使用真实 Alpha 透明；
lineart.png 与主体坐标严格对齐；
背景填满画布；
文字层不要依赖图像模型直接生成，优先用脚本生成精确文字；
不要把绘制出来的棋盘格当成透明背景。

主体和线稿最容易出现对齐问题。新生成的线稿可能看起来风格一致，但眼睛、轮廓或武器边缘已经偏离主体。在线稿发光之前，必须把它与主体叠加检查。

第三步：写入卡片配置

仓库提供了 references/config.example.json。一个简化版本如下：

{
  "title": "你的角色",
  "subtitle": "角色称号",
  "technique": "招式名称",
  "tagline": "招式说明",
  "edition": "001 / 001",
  "collection": "个人全息典藏",
  "description": "关于这张卡的一句话。",
  "assets": {
    "model": "./assets/card.glb",
    "subject": "./assets/subject.png",
    "background": "./assets/background.png",
    "text": "./assets/text.png",
    "lineart": "./assets/lineart.png"
  },
  "parameters": {
    "subjectScale": 1.25,
    "subjectDepth": 0.4,
    "backgroundDepth": -0.25,
    "foil": 0.65
  },
  "safeArea": {
    "scale": 1.12,
    "offset": [-0.06, -0.085]
  }
}

配置中的 safeArea 用于保护文字和重要信息的布局空间，不能和用户调节的视差参数混在一起。否则调节主体深度时，文字位置也可能被意外推走。

第四步：先检查素材，再运行流水线

在完整生成前先执行：

python scripts/validate_assets.py <project>

它负责做基础资产体检，但不能替代肉眼检查。建议同时确认：

图片是否为空；
四张图片尺寸是否一致；
主体和文字是否真透明；
线稿是否和主体重合；
文字有没有被主体遮挡；
主体是否被裁切；
重要内容是否落在安全区域内。

第五步：运行一键流水线

python scripts/run_pipeline.py --project <project>

根据仓库说明，这一步会完成以下工作：

查找可用的 Blender；
缺少时准备官方便携版 Blender；
生成可编辑的 Blender 场景；
从 Blender 场景导出卡片几何；
组装 Three.js 网页；
将素材、模型和配置放入输出项目。

如果这里报缺少 Python、Pillow、Node.js、npm 或 Blender，不要把“脚本启动了”当成成功。先解决依赖，再重新运行。

第六步：启动本地网页

node <project>/web/server.mjs

保持服务进程运行，打开命令返回的 localhost 地址。网页端至少要测试：

页面初始渲染；
纹理加载；
GLB 模型加载；
鼠标拖拽；
移动端触摸拖动；
卡片翻面；
视差参数滑块；
镭射效果调节；
重置和自动动画；
截图下载；
键盘控制；
减少动效设置；
约 390px 宽度和桌面宽度下的布局。

“ready” 标志、HTTP 200 或页面能打开，都不能证明 Shader 编译正确，也不能证明画面好看。要等待模型和纹理真正加载，并在真实浏览器中观察画面变化。

第七步：检查 Blender 工程

如果需要继续编辑，可打开：

<project>/card.blend

重点查看：

三个图片平面的 X 轴旋转仍为 90 度；
旋转没有被错误 Apply；
相对路径和素材是否被正确打包；
卡片边缘是否使用了独立材质槽；
前后倾斜方向是否都能正确渲染；
合成器辉光和镭射节点是否已经连接；
界面语言是否符合需求。

第八步：交付输出

一次完整交付通常包括：

输出	用途
本地网页 URL	浏览器交互、分享和展示
`card.blend`	Blender 中继续编辑、改材质和出图
`assets/`	替换四层图片后重跑流水线
`card-config.json`	修改标题、编号、稀有度和参数
渲染图	社交平台或宣传物料使用
GLB 或导出几何	网页端模型与材质角色

需要注意：Blender 的自定义 Shader 节点图不能通过 glTF 直接传递到网页。网页端会使用 Three.js 和自己的 Shader 逻辑重建效果，因此 Blender 离线渲染与浏览器实时渲染不应默认宣称像素级一致。

安装 Skill：放进 coding agent 的 Skills 目录

仓库 README 给出的安装方式是将目录放到 agent 的 Skills 目录，例如：

~/.codex/skills/holo-card-studio/

常见步骤如下：

git clone https://github.com/EverettFish/holo-card-studio.git \
  ~/.codex/skills/holo-card-studio

如果本地已经存在同名目录，不要直接覆盖未保存的修改。先检查目录状态：

git -C ~/.codex/skills/holo-card-studio status --short

安装完成后，可以在 agent 中用自然语言描述目标：

用 holo-card-studio 给我做一张赛博朋克风的机械猫全息卡，背景是霓虹雨夜，编号 No.007，保留主体轮廓，网页端支持拖拽、翻面和手机布局。

或者：

根据这张参考图制作全息卡，保留人物和构图，背景换成星空，文字改成“探索者 · 001”，输出可编辑 Blender 工程和本地 Three.js 网页。

一个合格的 agent 工作过程应该先复述卡片规格和它推断的设计细节，再生成资产、写配置、跑流水线、启动网页并实际验收，而不是只返回一段“已经完成”的文字。

参数怎么调：先理解四个核心旋钮

主体缩放与深度

仓库给出的默认核心控制是：

主体缩放：1.25；
主体深度：0.4；
背景深度：-0.25；
文字缩放：1；
文字深度：0。

主体深度越大，卡片越有“冲出来”的感觉，但也更容易出现边缘穿帮、遮挡文字或视差夸张。背景深度为负值，可以制造后退感；如果负值过大，可能产生不自然的拉伸。

`safeArea` 安全布局

安全区域负责让文字、编号和重要信息保持在可读位置。它解决的是“内容布局”问题，不是“视差强度”问题。

推荐做法：

先固定安全区域；
再调整主体和背景的视差；
最后用不同尺寸和不同屏幕方向检查文字。

镭射效果

全息效果不能只是把一张彩虹渐变叠在画面上。仓库的设计强调镭射相位应随观察角度变化，而不是只随时间变化。

如果镭射只会随时间滚动，不会随着拖拽方向变化，它看起来更像屏保，而不是全息卡。调节时应分别观察：

左右转动时色带是否变化；
上下倾斜时色谱是否变化；
移动鼠标是否只改变视差而不破坏文字；
移动端触摸是否出现反向或跳跃。

线稿发光

线稿层适合做稀疏轮廓和局部高光，不适合把整张画面全部描边。

常见问题是：线稿过密、发光强度过高、主体细节被抹掉。即使节点强度可以调得很高，也应该通过稀疏遮罩保留印刷质感。

三类常见使用场景

1. 宠物和个人纪念卡

输入宠物或人物参考图，保留主体的身份和构图，再替换背景、线稿和文字。

适合加入：

名字；
纪念日期；
稀有度；
专属称号；
一句祝福或描述。

2. 游戏角色和收藏卡

可以为战士、法师、Boss 或道具制作统一卡牌系列。将编号、稀有度、属性和技能写入 card-config.json，替换四层素材后批量重跑。

批量制作时建议额外维护：

卡片主题模板；
统一字体和安全区域；
统一材质参数；
一组可复用背景；
角色与编号清单；
每张卡的验收截图。

3. 发布会、活动和品牌互动物料

产品卡、团队卡、周年卡、纪念卡和活动彩蛋都适合用网页链接交付。相比单张图片，用户可以在手机上转动、翻面和查看信息，互动感更强。

但如果用于商业品牌，仍需另外确认：

人物肖像授权；
角色、Logo 和字体授权；
生成图片的使用权；
网页公开访问范围；
第三方模型或工具的条款。

决策指南：什么时候该用它，什么时候不该用

需求	是否适合 Holo Card Studio	原因
只需要一张平面海报	不一定	用普通图像生成或设计工具更快
需要主体前后层次和拖拽视差	适合	四层资产和 Three.js 查看器正好覆盖
需要继续在 Blender 调材质	适合	交付的是可编辑 `.blend`
需要多人协作修改同一张卡	需要额外设计	Skill 不等于在线协作平台
需要大规模商业卡牌生产	可以作为基础	还要补模板、任务队列、资产管理和批量验收
需要像素级统一的离线与网页渲染	需要谨慎	Blender Shader 与网页 GLSL 是两条实现路径
需要直接发布到公网	可以，但需另行部署	仓库默认是本地网页，并不自动替你部署

常见问题与恢复方法

问题一：棋盘格看起来像透明，其实不是透明

原因是生成图里真的画了一张棋盘格。

处理方法：打开图像编辑器查看 Alpha 通道，确认透明区域的 Alpha 值为 0，而不是 RGB 中画了灰白格。重新导出 PNG 后，再运行资产检查。

问题二：线稿和主体漂移

原因通常是线稿重新生成后没有和原主体共享同一坐标关系。

处理方法：

将 lineart.png 放在 subject.png 上方叠加；
对齐眼睛、轮廓、武器和边缘；
对漂移区域重新绘制或调整；
确认无误后再提高线稿发光强度。

问题三：镭射像屏保，不像全息卡

原因是光谱相位只随时间变化，没有和观察方向绑定。

处理方法：检查视角方向是否进入材质计算，确认拖拽时色带真的变化，并分别测试左右和上下两个方向。

问题四：拖拽有拖影，视差方向反了

仓库特别强调了 Blender 与 glTF 的坐标转换问题。Y-up 转换会改变局部坐标关系；网页端应该使用卡片根节点的规范坐标系，而不是导出后前面网格的局部系。V 坐标也只能还原一次。

处理方法：

先确认 uView 使用的是卡片根节点坐标；
确认没有重复转换 V 坐标；
分别测试正向和反向深度；
不要只看默认静止画面，要边拖边观察。

问题五：浏览器页面能打开，但画面是黑的

页面打开只说明服务器响应，不说明 WebGL、Shader、GLB 和纹理都成功。

检查顺序：

浏览器控制台是否有 Shader 编译错误；
模型请求是否返回 200；
四层图片是否成功加载；
GLB 是否包含网格；
材质角色名是否符合网页约定；
是否在模型和纹理加载完成前就截图；
是否存在跨域、路径或大小写问题。

问题六：Blender 能打开，但网页效果不一样

这是预期风险，不一定是流水线错误。自定义 Blender 节点图不会直接通过 glTF 传到 Three.js；网页端需要用自己的材质和 Shader 重建视觉效果。

正确做法是比较关键行为，而不是默认追求像素完全一致：

是否保持四层空间关系；
视差方向是否正确；
镭射是否随视角变化；
线稿是否保持稀疏；
移动端交互是否可用；
卡片翻面是否正确。

问题七：打包 Skill 时把用户素材一起带进去了

Skill 本体和输出项目必须分开。打包前执行：

python scripts/package_skill.py

然后检查 ZIP 中的每个文件，确认没有：

用户生成的 PNG；
带嵌入图片的 .blend、.glb 或 .gltf；
视频和缓存；
凭据和 API Key；
项目依赖目录；
个人输出项目。

一个写在 JavaScript 里的 Base64 PNG 也属于图片内容，不应混入纯文本 Skill 包。

推荐的迭代方法：一次只改一个变量

全息卡很容易进入“同时改五个参数，最后不知道什么起作用”的状态。推荐使用下面的迭代环：

观察问题
  → 只修改一个变量
  → 重新运行或刷新
  → 在同一角度比较
  → 记录变化
  → 保留或回滚

例如：

视差太弱：只增加主体深度；
文字被挡：只调整安全区域或文字深度；
线稿太糊：只减少线稿遮罩密度；
镭射太像屏保：先检查视角绑定，不要直接提高颜色饱和度；
移动端溢出：先修正布局，不要调整材质参数。

建议把成功参数保存成项目模板，后续同类型卡片直接复用，而不是每次从零试错。

批量制作时的工程化建议

如果从单张卡扩展到一套卡牌，可以继续补充以下能力：

用 JSON 或表格维护角色、编号、稀有度和文案；
将字体、边框、背景和安全区域做成模板；
为每张卡生成独立输出目录；
资产生成、验证、Blender 构建和网页导出分阶段执行；
为每张卡保存渲染图和浏览器验收截图；
记录失败原因，区分素材失败、配置失败、Blender 失败和网页失败；
在批量发布前进行依赖、授权和隐私检查；
保留上一版可用输出，方便单张卡回滚。

不要一开始就把所有卡片串成一个大脚本。先保证单张卡可重复成功，再组合成批处理流水线。

可复用的卡片需求模板

请使用 holo-card-studio 创建一张 3D 全息卡。

主体：
风格：
背景：
需要保留的参考图元素：
允许改变的元素：
卡片标题：
副标题：
编号 / 版本：
稀有度或属性：
正面文字：
背面文字：
视差强度：
镭射风格：
线稿发光强度：
目标设备：桌面 / 手机 / 两者
交付物：本地网页 / card.blend / 渲染图 / 全部

完成后请：
1. 先确认卡片规格和你推断的细节；
2. 生成 subject、background、lineart、text 四层素材；
3. 验证真实 Alpha、尺寸和线稿对齐；
4. 运行完整流水线；
5. 在真实浏览器中测试拖拽、翻面、滑块和手机布局；
6. 报告输出文件、访问地址、已验证项目和未解决问题。

验收清单

素材

Blender

场景可以打开
三个图片平面保持 X=90° 对象旋转
旋转没有错误 Apply
素材使用相对路径或已正确打包
卡片边缘材质存在
前后倾斜渲染方向正确
节点和合成器效果已连接

WebGL / Three.js

交付与安全

网页 URL 可访问
card.blend 可编辑
输出项目与 Skill 源码分离
Skill ZIP 不包含用户图片和模型
没有把 API Key、Cookie 或凭据写入项目
肖像、字体、Logo 和生成内容的授权边界已确认

许可证与使用边界

仓库包含 MIT License，可以在遵守许可证通知要求的前提下使用、修改、发布和分发软件与文档。但仓库明确说明，生成的艺术作品和用户上传的参考图不随软件仓库分发，也不自动受到软件许可证覆盖。

这意味着：

Skill 代码和文档的许可证，不等于生成素材的版权许可；
使用他人照片、角色、Logo、字体或商业素材时，需要单独确认授权；
将生成卡片用于商业活动时，应检查相关模型、字体、图片和品牌条款；
发布网页时，还要确认参考图和卡片内容是否适合公开访问。

总结

Holo Card Studio 的价值，在于把“生成一张好看的图”推进成“交付一个可以编辑、可以交互、可以继续生产的卡片项目”。它把图像生成、Blender 场景构建、真实几何导出、Three.js 实时材质和浏览器验收串成了一条流水线。

最重要的使用原则有五条：

先写卡片规格，再生成素材。
四层图必须同画布、真透明、严格对齐。
先跑资产验证，再运行完整流水线。
以真实浏览器交互作为验收，不以端口和 ready 标志代替视觉检查。
把 Skill 源码、用户输出、生成图片、模型和凭据严格分开。

如果只是想做一张静态海报，使用普通图像工具会更快；如果你需要视差、翻面、镭射、Blender 可编辑性和网页交互，Holo Card Studio 才能发挥它的完整价值。

来源

本文对仓库内容进行了中文整理、结构化解释和实践补充；安装路径、脚本名称、默认参数和许可证边界应以仓库当前版本为准。