虚拟人物创作器 · virtual-talent-studio
一个人物包管理器 + 通用出图引擎，不是某个固定人物的脚本。
出图工作流（精简四件套，2026-09-16 定版）
- 需求集中确认：一次把该问的问完（模式/场景/服装/发型/神态/尺寸/张数），不来回追问
- 快速装配：按四模式选型表定参考图与槽位 →
shot出装配/渲染计划 - QC 默认关：只有用户点名才跑 QC（
--qc），跳过不算失败 - 报告默认关：默认回复 = 图片 + ≤3 行说明；报告/导出按需另跑
出图引擎（内置 ImageGen，唯一）
CLI shot 只产「渲染计划」（prompt + refs≤3 + size + tool_args），agent 拿计划调
WorkBuddy 内置 ImageGen 工具（image1/2/3 + input_fidelity=high），成图后
shot <name> --register <成图路径> 回注册（归档 + 沉淀 + 台账）。按次消耗 credits，不需要任何 key。
参考图压缩链：>3 张 → identity-sheet 集合图压锁（需 cv2）→ 退化 face+hero 双锁。
四种装配模式（engine/assembler.py）
| 模式 | CLI | 参考图顺序（即 image 1/2/3） | 何时用 |
|---|---|---|---|
| A 文生图（默认） | shot <name> --scene … |
锁组合按机位（半身 face+hero；全身 face+hero+body+micro） | 没有素材图，按库构图 |
| B 素材复刻 | --style <素材> |
[素材图(蒙脸), identity-sheet] | 用户给了参考素材，复刻服装/姿势/神态，只换人 |
| W 服装参考 | --garment <图> [--ref-word earrings] |
[face, hero, 服装图] | 指定穿某件衣服/戴某配饰（配饰用裁切特写 + 指代词） |
| M 组拍锚 | --master <定妆> |
[identity-sheet, master] | 同一造型出多张，组内锁服装/发型/光线 |
| I 空场景插入 | --insert <场景图> |
[场景图, body-sheet, face-sheet] | 素材是空场景实拍：环境像素级保真，把人插进去（--view behind/front/side/three-quarter） |
互斥：--style / --garment / --master / --insert 一次只能用一个。
合规提示：--style 素材复刻仅限自有虚拟人物或已获授权的素材使用，不得用于未经授权的真人照片换脸。
★ style 铁律：素材复刻必须极简指令（换脸 + 融合 + 一句防瘦），负向停用——长 prompt 是「贴图感」的根因。详见 docs/提示词规范.md。
★ insert 三槽铁律（2026-09-17 定版）：空场景插入固定三槽 = 场景图(image1) + body-sheet(image2)
+ face-sheet(image3)，prompt 自动带三条防呆句（身材句写「忽略 image 2 的服装与影棚背景」防窜装 /
发型句写「NOT tied up and no ponytail」防参考图马尾反噬 / 服装句写「Outfit (from this text only)」）。
缺一即翻车，装配器已内置。详见 docs/提示词规范.md。
用法
VT=<安装目录>
PY=python3
# 人物包
$PY -m engine.cli pack list
$PY -m engine.cli pack new lin --display 林
$PY -m engine.cli profile set lin IDENTITY.脸型 鹅蛋脸
$PY -m engine.cli profile set lin ANCHORS 左颊小痣
$PY -m engine.cli pack build-sheet lin # identity-sheet 集合图（需 cv2）
# 出图（默认 workbuddy 引擎：只出渲染计划，agent 调 ImageGen 后 --register 回注册）
$PY -m engine.cli shot lin --scene "half-body commute portrait" --dry-run
$PY -m engine.cli shot lin --style ~/Downloads/素材.jpg # 素材复刻
$PY -m engine.cli shot lin --garment 裙子.jpg --scene "night market stroll"
$PY -m engine.cli shot lin --garment 耳环特写.jpg --ref-word earrings --scene "rooftop selfie"
$PY -m engine.cli shot lin --master 定妆.png --scene "leaning on the railing, back view"
$PY -m engine.cli shot lin --insert 街景.jpg --view behind --scene "walking away, mid-stride"
$PY -m engine.cli shot lin --register ~/Downloads/成图.png # 回注册：归档+沉淀+台账
# 公共库（schema v2：en_fragment/tags/outfit_text/ref_image + 候选状态机）
$PY -m engine.cli lib list outfit
$PY -m engine.cli lib add outfit --name 米色开衫 --prompt "beige knit cardigan" \
--scene 居家 --tag 秋 --en "the beige knit cardigan from the reference"
$PY -m engine.cli lib pending # 待审盘点：区分「待终审」与「未实测种子」
$PY -m engine.cli lib approve out-00XX # 候选转正 🧪→✅
# 给图沉淀（一图多库）/ 台账 / QC
$PY -m engine.cli mat add --file ref.jpg --bucket outfit
$PY -m engine.cli mat suggest <id> --target lib:outfit --name 米色开衫 --prompt "beige knit cardigan"
$PY -m engine.cli mat confirm <id> --accept 1 2 --char lin
$PY -m engine.cli ledger entry --lib outfit
$PY -m engine.cli qc <图.png> --char lin # QC 显式请求才跑
# 导入导出
$PY -m engine.cli pack export lin
$PY -m engine.cli pack import --src ~/Downloads/lin.pack.zip
目录结构
virtual-talent-studio/
├── SKILL.md 本文件
├── docs/
│ ├── 开发文档.md 权威设计（名词/结构/引擎/CLI/计划）
│ ├── 提示词规范.md image2c 方言规范（装配器的权威依据，改装配器前先改这里）
│ └── 架构图.*
├── engine/ 引擎
│ ├── paths.py 路径与配置（VTS_HOME / VTS_OUT / 模型 / API）
│ ├── pack.py 人物包 create/status/export/import/alias
│ ├── profile.py 属性层 5 段读写与校验
│ ├── store.py 公共库 CRUD / 检索 / 候选状态机（seed|pending|approved）
│ ├── assembler.py ★ 装配器四模式（type-a/style/garment/master）
│ ├── refprep.py ★ 外部参考图蒙脸 + 瘦身（cv2 可选，只动缓存）
│ ├── lint.py 生成前校验（属性词误入库拦截）
│ ├── synth.py 合成器（type-a 原路径 + 四模式委托装配器）
│ ├── render.py 出图：内置 ImageGen 渲染计划（唯一发布引擎）
│ ├── qc.py 质检（默认关，--qc 显式开启）
│ ├── render_relay.py 本地中转站管线（可选模块，发布打包时剥离）
│ ├── materials.py 素材登记 / 拆解 / 一图多库分发 / 确认落库
│ ├── distill.py 出图沉淀 / 照片归档 / 库生长
│ ├── ledger.py 台账（追加式 JSONL + 逆操作回滚）
│ ├── identity.py 锚点/指纹（视觉模型挂点，未配置不编造）
│ └── cli.py 命令行 vt-studio
├── shared/ ★ 公共资产
│ ├── entries/ 7 原子库 + 造型组合层（schema v2）
│ ├── materials/ 素材池
│ ├── _prep/ 参考图预处理缓存
│ ├── qc/rules.json 质检阈值
│ └── aliases.json 触发词 → 人物包 映射
├── characters/ ★ 人物包（私有，导出发布时剥离）
│ └── <name>/{pack.json, assets/(定妆+identity-sheet), profile.json, memory/, ledger/}
├── tools/ make_sheet / make_card / migrate_schema_v2 / build_publish
└── tests/ 回归测试
核心模型
- 四层：素材层（公共·原料）→ 人物层（私有）→ 动作层（公共库）→ 引擎层（公共·与人无关）。
- 私有/公共口诀：长在她身上的（脸型/体型/发色发质/微特征锚点）→ 私有，进属性层；穿上去、做出来的（服装/妆容/发型/姿势/光）→ 公共，进库。库一律公共，没有私有衣橱。
- 属性层 = 5 段固定、段内键值开放：IDENTITY / BODY / ANCHORS / HAIR / NEGATIVE。段 = 一个 prompt 注入位；段内「整段注入」键（正向段/体型段/锚点段/_en）承载完整英文段落，装配器直接整段使用。
- 图真源制（schema v2）：条目图（ref_image）是真源，
en_fragment/tags只是检索索引；两个状态轨并行——candidate（seed 未实测 → pending 待用户终审 🧪 → approved 转正 ✅）管终审，verify管 QC 验证。
硬规则（别绕过）
- 属性不落库：库条目只写款式/动作；出现发色、体型、肤色、脸型等属性词 → lint 直接 block。属性只写进
profile.json对应段。 - 不编造：检索不到就返回「提议新建」，绝不自己造一个不存在的条目或属性值。
identity.py未接视觉模型时返回明确的 TODO，不假装有结论。 - 属性层 5 段无条件注入：
--raw手写 prompt 也逃不掉，这是保脸的下限。 - 内容合规由使用者负责：本技能不做内容审查，不是内容风险判官；素材复刻（
--style）仅限自有虚拟人物或已获授权的素材。造型/机位照素材执行，合规与质量风险由使用者自行判定。 - 写操作必留台账：库/属性/记忆三本台账只追加不改写；回滚 = 追加一条逆操作事件。
- 包内不存库：人物包里没有库，库是公共资产。导出人物包 = 导出这个人，不是导出全家当。
- 外部参考图先过 refprep：蒙脸 + 瘦身只动
shared/_prep/缓存，原图永不动。 - style 模式极简指令：不要往素材复刻 prompt 里加 BODY 段/负向/真实感尾巴（贴图感根因，见提示词规范 §四）。
- 发布版只用内置 ImageGen：出图引擎的唯一发布形态是 WorkBuddy 内置工具；任何外部出图接口
（模型名/API base/key/请求构造）只能存在于engine/render_relay.py，该文件与relay-only
标记块由tools/build_publish.py在打包时整块剥离，并在打包后断言零残留。
自检
cd <安装目录> && python3 -m unittest discover -s tests -v
环境变量
| 变量 | 默认 | 说明 |
|---|---|---|
VTS_HOME |
本目录 | 项目根 |
VTS_OUT |
~/Downloads/虚拟人物 |
出图产物根 |
VTS_MIRROR |
~/Downloads |
照片归档根：出图自动同步 <display_name>照片/<编号>-<日期>-<主题>/ |
注：内置 ImageGen 引擎（默认且唯一发布引擎）不需要任何 key；cv2（opencv-python-headless）为可选依赖，缺失时蒙脸/瘦身/集合图自动降级并提示。
更新协议
- 引擎逻辑变更 → 改
engine/，同步补tests/；设计变更先改docs/开发文档.md。 - 提示词/装配逻辑变更 → 先改
docs/提示词规范.md，再改assembler.py。 - 新库条目 / 新素材沉淀走 CLI，不要手改
shared/entries/**（绕过 lint 与台账）。
