live2d-halfbody git:20261024.3fd24b4A

Immutable. This exact content never changes and is served at /api/v1/blob/d0e861f1be02f180.

---
name: live2d-halfbody
description: 从一张立绘或一段角色描述，做出能在 VTube Studio 里直播用的半身 Live2D 皮套，不用手动建模、不开 Cubism Editor：图像模型出图、See-through 拆层、代码补细节和绑定、自查后装进 VTS。默认带小角度转头、歪头、身体跟随、呼吸、眨眼和单眼眨眼、口型、四个表情、头发分段摆动（短发、过肩长发或双马尾，刘海可有可无，侧发可别在耳后）、挂件和耳坠摆动、眼镜、招手/摊手/指向三个手势和脸红。用于用户想新做一个皮套（有立绘、只有描述、或已有分层文件）、检查皮套素材、或调整已有角色的动作幅度时。Builds a half-body Live2D avatar for VTube Studio from one character illustration or a text description.
---

# 半身皮套：从一张立绘到 VTube Studio

给不想手动建模、不想调网格的人。一张立绘或一段角色描述进去，Agent 一步步做出能在 VTS 里直播用的半身 Live2D 皮套。用户只做三件事：

1. **确认立绘**（第 1 步）；
2. **同意把立绘传到 See-through**（第 3 步，Hugging Face，备用魔搭）；
3. **在 VTS 里看效果**，回复 `通过` 或 `不通过：<现象>`（第 5 步）。

其余由 Agent 完成，并在交给用户前自查。

## 跑一次就有的功能

| 功能 | 驱动 |
|---|---|
| 转头左右、上下（±30），歪头时身体跟着倾斜 | 摄像头 |
| 身体跟随：左右转、前后、呼吸起伏 | 摄像头、VTS 自动呼吸 |
| 眨眼、单眼眨眼（快闭上时换成画好的闭眼）；半闭眼时双眼皮淡出 | 摄像头（左右眼分开） |
| 眼珠跟随、眉毛上下 | 摄像头 |
| 张嘴说话、嘴角笑 | 摄像头 |
| 头发分段摆动：刘海（可选）、两侧（发根和发梢两段；可别在耳后）、后发或发髻；低头抬头时跟随。双马尾每条从发绳往下单独摆，发梢再分一段。过肩长发在肩膀以下跟身体走 | 物理 |
| 挂件（项链吊坠、耳坠）摆动 | 物理 |
| 眼镜跟着脸转 | 摄像头 |
| 表情：笑眼 N1、O 型嘴 N2、急眼 N3、困扰 N4，清除 N0 | 快捷键 |
| 手势：招手 N5、摊手 N6、指向 N7 | 快捷键（也配了摄像头手势，见“已知问题”） |
| 脸红 N8 | 快捷键 |

做不到：大角度转头（要侧脸素材）、全身、手臂跟着摄像头连续动（要分段手臂素材）。产出是 VTS 直接用的 `.moc3`，不是 Cubism Editor 的工程文件（`.cmo3`），Editor 打不开。精修级的效果（更细的物理、更多表情、商业级网格）要把 `layers-st/` 的图层导进 Cubism Editor 重新绑定。

## 文件夹

```
素材/角色名/                 立绘、提示词、变体、See-through 结果、图层
  A0-base.png                定稿立绘
  prompts/                   从 references/提示词/标准/ 复制，填好 [[…]]
  check/                     每张变体的对位检查图
  seethrough.psd             See-through 的原始结果
  seethrough/                拆成每层一张 PNG
  layers/                    自拆的图层：只作 See-through 合成的底，不单独交付
  layers-st/                 最终图层（See-through 合成，含手势和脸红）
  R0-rest.png                最终图层的静止合成，手势和脸红变体的底图
角色/角色名/
  character.json             位置、幅度、图层对照
  标注.png                    character.json 里的位置画在立绘上
  素材检查/  prepared/  build/runtime/  自查/  vts/
```

## 步骤

命令都在用户的工作目录（放 `素材/`、`角色/` 的地方）里跑，命令前加 `PYTHONPATH=<skill 目录>`（如 `~/.claude/skills/live2d-halfbody`），Python 才找得到 `rigkit`。

### 0. 检查环境

```
python -m rigkit.doctor
```

有 ✗ 的先处理完再出图，否则会在出完二十来张图之后才卡住。! 只影响一部分：没有 See-through 令牌时匿名额度不一定够，没有 ffmpeg 时出不了自查短片，没有 Codex 时用其他图像工具出图（见第 2 步）。

### 1. 立绘 —— 用户确认

把 `references/提示词/标准/` 整个复制到 `素材/角色名/prompts/`，先填好 `A0-base.txt` 里的 `[[…]]`（外貌、刘海、两侧头发、头发长短、眼镜、耳坠）。

- 只有描述：照描述填，生成立绘。
- 有立绘：存为 `素材/角色名/参考.png`，生成时作为参考图附上，得到一张按绑定要求画的版本（脖子露出；有刘海时停在眉毛以上；两侧头发盖住耳朵到下巴为止，或别在耳后；平光、白底、手臂和身体之间留缝）。原图不满足这些要求时，直接拆会在动起来时出问题。

```
python -m rigkit.variants 素材/角色名 A0-base
```

没有 Codex 时按第 2 步的“用其他图像工具出图”出 A0。给用户看，用户确认后才往下做。

已有按 [图层清单](references/图层清单.md) 分好层的文件时，跳到第 4 步。

### 2. 出图

把 `prompts/` 里其余的 `[[…]]` 换成这个角色的描述；角色没有的部件删掉对应的提示词：帽子或发饰 V1，耳前的侧发 V2 和 V7，刘海 V3，挂件 V9（S1 里同时删掉那一行，见 [出图](references/出图.md)）。然后：

```
python -m rigkit.variants 素材/角色名
```

依次生成 14～19 张“整张图改一处”的变体，每张出对位检查图。偏移 4 px 以内、改动只在该改的地方算合格；不合格删掉重出，同一张最多三次。细节见 [出图](references/出图.md)。

**用其他图像工具出图**（没有 Codex，或 Agent 自己能出图）：`variants` 遇到已经有的图只做检查，不重出，所以可以先用别的工具把图出好放进去。

```
python -m rigkit.variants 素材/角色名 --list
```

每行一张图：要附的图、提示词文件、出了没有。按顺序一次出一张，附的图标着“还没有”时等它出好：

- 提示词用 `prompts/<名>.txt` 的全文，不改写；只附列出的那一张图，让工具在它上面改。A0 附参考图，没有参考图时直接生成。
- 工具要能改图：给一张图和提示词，返回改过的同一张图。只能凭文字出新图的工具只能出 A0。
- 存为 `素材/角色名/<名>.png`，和附的图长宽比相同。不裁、不加边、不抠图、不修补。
- A0 出成正方形；不是 1254×1254 时缩放到这个尺寸（做过的角色都是这个尺寸）。

出完一批，跑一次 `python -m rigkit.variants 素材/角色名` 出检查图，合格标准同上。第 3 步的手势和脸红同样：`--list F1-blush P1-wave P2-explain P3-point`。还没用 Codex 以外的工具完整做过一个角色。

### 3. 拆层 —— 用户同意上传

先用变体自拆，作为合成的底：

```
python -m rigkit.split 素材/角色名 素材/角色名/layers --pad-top 90
```

再问用户是否同意把立绘传到 See-through，同意后：

```
python -m rigkit.seethrough fetch 素材/角色名/A0-base.png 素材/角色名/seethrough
python -m rigkit.seethrough split 素材/角色名 素材/角色名/layers 素材/角色名/layers-st --pad-top 90
```

`fetch` 先试 Hugging Face，没跑成再换魔搭（`--site hf` 或 `--site modelscope` 指定一个），各用能给的最高分辨率。也可以把网页版、ComfyUI 或自己显卡跑出的 PSD 交给它：`fetch 那个.psd 素材/角色名/seethrough`。

最终图层必须走 See-through：自拆的图层动起来边缘有碎点、被挡住的头发补不全，不单独交付。当天没有额度时，换另一个网站、等第二天，或者用 PSD。

`split` 会逐条打印它对 See-through 图层做的修正（裁掉画到别处的、挪回归错的配饰、补漏画的部件），规则见 [规则](references/规则.md) 的“See-through 合成”。看 `layers-st/拆层总览.png`：每层只有自己的东西，静止合成和立绘只差在画风。

然后做手势和脸红：

```
python -m rigkit.extras 素材/角色名 素材/角色名/layers-st        # 写出 R0-rest.png
python -m rigkit.variants 素材/角色名 F1-blush P1-wave P2-explain P3-point
python -m rigkit.extras 素材/角色名 素材/角色名/layers-st        # 加进图层
```

看 `layers-st/手势和脸红.png`：每行是静止、变体、模型里打开后的样子，手臂和身体接得上、手的边缘干净才往下做。

### 4. 生成并自查

```
python -m rigkit.estimate 素材/角色名/layers-st 角色/角色名 --name 名字
python -m rigkit.check_art 角色/角色名/character.json
python -m rigkit.prepare 角色/角色名/character.json
python -m rigkit.build 角色/角色名/character.json             # 几分钟
```

- `estimate` 不覆盖已有的 `character.json`，写成 `character.draft.json`；图层改过要重估时，比对后换上。
- `标注.png`：脸的椭圆、眼眉鼻嘴、歪头转轴、颈根、肩、腰、发根线不在对的位置时，改 `character.json` 里对应的数字，重新 prepare 和 build。
- `素材检查/`：`露底` 有品红、`原画对照` 有成线的红色时，回到第 3 步。

自查：

```
python -m rigkit.preview flips 角色/角色名/build/runtime
python -m rigkit.preview sheet 角色/角色名/character.json 角色/角色名/自查 新版=角色/角色名/build/runtime
python -m rigkit.preview clip 角色/角色名/character.json 角色/角色名/自查/动作.mp4 新版=角色/角色名/build/runtime
```

翻折三角形应为 0。看放大图和短片里的固定检查区（眉毛和刘海、脸边、下巴和脖子、太阳穴和耳朵、眼角和睫毛、嘴角），有问题先修，再交给用户。有上一版时把上一版放在前面并排比。

再在 VTS 的背景色上，把闭眼、半闭、笑眼、张大嘴、半张嘴、三个手势、左右甩头各渲一张，眼睛、嘴、头发交界放大三到四倍看：用户在 VTS 里最先看到的就是这些画面。

### 5. 装进 VTS —— 用户验收

```
python -m rigkit.vts 角色/角色名/character.json --install
```

新模型可以在 VTS 开着时装；覆盖已装的模型要先退出 VTS，这时保留用户在 VTS 里调过的设置，只补缺的快捷键和映射。VTS 开着又要换新版时，改 `vts.name` 和 `vts.folder` 装成新文件夹。

给用户并排图、短片和下面这张清单，回复 `通过` 或 `不通过：<现象>`：

| 看什么 | 怎么做 |
|---|---|
| 转头、歪头 | 左右上下转头、歪头：脸、头发、帽子、耳朵跟着转，没有裂缝、碎点、留在原地的东西 |
| 眼睛 | 眨眼、单眼眨眼、半闭眼；转头时睫毛不穿过头发 |
| 嘴 | 说话、笑；闭着嘴转头时不歪嘴 |
| 头发 | 甩头：刘海、侧发、后发分段摆，发梢比发根慢；长发在肩膀以下跟身体 |
| 挂件 | 身体动时吊坠摆动，底下的衣服完整 |
| 身体 | 身体跟随左右转、前后，呼吸起伏 |
| 表情 | N1～N4 切换，N0 清除 |
| 手势 | N5～N7：身体画风不跳，手的边缘干净；手势打开时转头，手臂跟着身体走 |
| 脸红 | N8：边缘柔和；甩头时头发下面不露边 |

## 调幅度

动作幅度都在 `character.json`：

| 想改 | 字段 |
|---|---|
| 歪头角度 | `head.tilt_deg`（满幅时的度数） |
| 转头时脸走多远 | `head.yaw_px`、`head.pitch_px` |
| 身体倾斜 | `body.tilt_deg`（每单位参数的度数，满幅 ×10） |
| 呼吸起伏 | `body.breath.head`、`body.breath.shoulder`（像素） |
| 身体跟随 | `body.turn`、`body.shift`、`body.lean_y` |
| 头发摆幅 | `hair.locks.<图层>.swing`；发梢 `hair.tips.amount` |
| 物理手感 | `hair.locks.<图层>.physics`：`delay` 越小越拖、`length` 越长越慢 |
| 挂件摆幅 | `dangles.<图层>.deg`（满幅时的度数） |
| 半闭眼 | `eyes.crease_fade`（双眼皮淡出的区间）、`eyes.lower_from`（下眼睑开始合的位置） |
| 嘴从哪里开始张 | `mouth.open_from`：摄像头读数低于它时保持闭嘴 |

幅度按 VTS 半身取景和真人动作判断：正常歪头约 15°，模型只转 3° 就等于没有。改完重新 build。其余字段见 [配置说明](references/配置说明.md)。

## 规则

全部规则和来由见 [规则](references/规则.md)。最常被违反的几条：

- 动手前先查 Live2D 的标准做法，说清楚打算怎么做。
- 切图用 See-through，图像模型只补它给不了的细节（表情、被挡住的部分、手势）。
- 只处理有把握的部分：See-through 的图层整块用，代码只做整块的取舍、挪动和按不相连的块分开，不在它的层里按颜色逐像素再切（切出来都毛躁）。要改一处，先和 See-through 原样并排放大比，没有明显更好就不改。
- 新规则先在所有已有角色上量判断依据、定适用范围，改完新旧代码各跑一遍逐层比，不误伤已通过的角色。
- 每轮给同尺寸并排图和短片，由人判断；翻折数、像素差只用来排查破面。
- 同一个症状修了三轮还在，停止改代码，改用素材解决。
- 图像模型只派“整张图改一处”，不派“只留一部分”；要的部分由代码用差值算。
- 传图到外部服务前先问用户；账号和 token 由用户自己注册、自己填，不在对话里复述 token。
- 安装时不覆盖用户的 vtube.json，覆盖已装模型时 VTS 要先退出。

## 环境

- **Python 3.10+**：`pip install -r <skill 目录>/requirements.txt`（系统 Python 不让装时建一个虚拟环境）。出短片要 ffmpeg。
- **Codex 命令行**（出图）：ChatGPT 桌面版自带，或单独安装的 `codex`（在 PATH 里即可），登录 ChatGPT 账号；都不是时把环境变量 `CODEX` 指向它。没有 Codex 时用其他能改图的图像工具，见第 2 步。
- **See-through**（拆层），两个网站跑的是同一个模型，至少准备一个：
  - **Hugging Face**（首选，几分钟一次，最高 1280）：不登录时每天的免费显卡时间不一定够跑一次；用户注册免费账号、建一个 Read token，放进环境变量 `HF_TOKEN` 或 `~/.cache/huggingface/token`（`hf auth login` 存的位置），每天约 1～2 次。
  - **魔搭 ModelScope**（备用，免费，最高 1536）：用户注册账号、建一个访问令牌，放进环境变量 `MODELSCOPE_API_TOKEN` 或 `~/.cache/modelscope/token`。要排队，一次可能半小时。1536 的头发轮廓和眼睛比 1280 更接近原画。
- **VTube Studio**（Steam 版）。
- **Live2D Cubism Core**（预览、自查、图标要用）：装了 Cubism Editor 时自动找到；否则下载 Cubism SDK for Native，把环境变量 `CUBISM_CORE` 指向其中的 Core 动态库。Core 按 Live2D 的许可使用，不随本 skill 分发。

macOS 上验证过；Windows 未验证。

## 已知问题

- 摄像头手势（张开手掌 = 招手、双手张开 = 摊手、竖食指 = 指向）：第一个角色能触发，第二个角色配置逐字段相同却不触发，原因未查明。快捷键 N5～N7 不受影响。
- 静止时是 See-through 画的样子，比原画软一点，睫毛、发梢描边的细节少一些。
- 戴眼镜、镜框紧挨双眼皮时，See-through 会丢掉双眼皮线，在睫毛上沿画一道浅灰带，按原样保留。