本文介绍新版的自动 JSON 生成、多角色切换和按群画质档位。手工网站操作（微调）另见网站制作说明。
使用自己的图片编辑 API，模型选择 gpt-image-2-5，大小 1024x1024。先制作正常图，再将这张正常图作为其他差分的参考图片，避免独立生成导致人物位置、比例、服饰变化。
| 文件命名 | 内容 | 必需 |
|---|---|---|
| normal.png | 睁眼、闭嘴 | 是 |
| close.png | 闭眼、闭嘴 | 是 |
| open.png | 睁眼、小幅张嘴 | 是 |
| happy.png | 开心的完整立绘 | 否 |
| confused.png | 困惑的完整立绘 | 否 |
| angry.png | 生气的完整立绘 | 否 |
| shy.png | 害羞的完整立绘 | 否 |
| crying.png | 哭泣的完整立绘 | 否 |
呆毛注： 推荐自己把图片ps改为透明背景 png
把图片命名好，放在同一个文件夹内备用
生成png透明通道的图，将背景设为透明。 将参考图片制作成用于群聊角色动图的基准立绘，输出 1254×1254 的单张图片。保留参考角色的身份、Q 版比例、脸型、发色、发型、帽子、发夹、服饰、配色和画风。角色睁开双眼，嘴巴自然闭合，表情亲切。使用透明背景，人物居中，头部和帽子完整可见，边缘留出空白，下方可保留半身裁切。确定人物位置、大小、姿势与头部倾角，后续差分都将沿用这张图。画面只包含一个角色，不添加文字、标志、边框或额外装饰。
生成png透明通道的图，将背景设为透明。 这张参考图是已经确定的角色基准图。请制作同画布的闭眼差分，输出 1254×1254 单张图片。只把双眼改成自然闭合的眨眼状态，保持闭嘴。严格保持人物位置、比例、姿势、头部倾角、帽子、发夹、头发轮廓、服饰、光照、线条、配色和透明背景不变。不得重新构图、放大、缩小或移动角色，不改动其他部位，不添加文字。目标是与基准图切换时，除了眼睛之外其他像素区域尽可能一致。
生成png透明通道的图，将背景设为透明。 这张参考图是已经确定的角色基准图。请制作说话差分，输出 1254×1254 单张图片。只将嘴巴改成自然说话时的小幅张嘴，画出合理的小口腔，双眼保持睁开。严格保持人物位置、比例、姿势、头部倾角、帽子、发夹、头发轮廓、服饰、光照、线条、配色和透明背景不变。不得重新构图、放大、缩小或移动角色，不改变脸型，不添加文字。目标是与基准图切换时，除了嘴巴之外其他像素区域尽可能一致。
生成png透明通道的图，将背景设为透明。 以这张角色基准图制作开心表情的完整立绘，输出 1254×1254 单张图片。只修改面部表情，让眼睛和嘴巴呈现自然、可爱的开心笑容。严格保持人物位置、比例、姿势、头部倾角、脸型、帽子、发夹、头发轮廓、服饰、光照、线条、配色和透明背景不变。不得重新构图、移动角色或添加文字。此图会作为一张完整特色表情播放，而不是眼睛或嘴巴部件。
生成png透明通道的图，将背景设为透明。 以这张角色基准图制作轻微困惑表情的完整立绘，输出 1254×1254 单张图片。只修改眉眼和嘴巴，表现温和的疑惑感，不改变脸型和人物姿势。严格保持人物位置、比例、头部倾角、帽子、发夹、头发轮廓、服饰、光照、线条、配色和透明背景不变。不得重新构图、移动角色、添加问号或文字。此图会作为一张完整特色表情播放。
生成png透明通道的图，将背景设为透明。 这张参考图是已经确定的角色基准图。请制作可爱、轻微生气的完整立绘差分，输出 1254×1254 单张图片。只修改面部：眉毛略向内收拢，眼神稍微不满，嘴巴自然抿起或呈小小的嘟嘴，保留角色原来的亲和感，不做夸张狰狞表情。严格保持人物位置、比例、姿势、头部倾角、脸型、帽子、发夹、头发轮廓、服饰、光照、线条、配色和透明背景不变。不得握拳、改变身体动作、重新构图、放大、缩小或移动角色；不添加怒气符号、火焰、烟雾、文字或额外道具。此图作为完整特色表情播放，不是五官部件。除指定面部区域外，其他区域应尽可能与基准图一致。
生成png透明通道的图，将背景设为透明。 这张参考图是已经确定的角色基准图。请制作温柔、可爱的害羞完整立绘差分，输出 1254×1254 单张图片。只修改面部：眉眼稍微柔和，目光略显羞涩，嘴巴为自然的小幅闭嘴微笑，脸颊增加轻柔的粉红晕染。保持原来双眼的颜色和结构，不改变脸型。严格保持人物位置、比例、姿势、头部倾角、帽子、发夹、头发轮廓、服饰、光照、线条、整体配色和透明背景不变。不得转头、低头、抬手遮脸、重新构图、放大、缩小或移动角色；不添加爱心、汗滴、文字或额外道具。此图作为完整特色表情播放，不是五官部件。除指定面部区域外，其他区域应尽可能与基准图一致。
生成png透明通道的图，将背景设为透明。 这张参考图是已经确定的角色基准图。请制作委屈、轻声哭泣的完整立绘差分，输出 1254×1254 单张图片。只修改面部：眉毛略显委屈，双眼含泪，在眼角与脸颊添加少量自然的小泪珠，嘴巴微微下弯，保留可爱、柔和的角色气质。泪珠局限在面部区域，不画夸张的喷泉式眼泪，不改变眼睛颜色和脸型。严格保持人物位置、比例、姿势、头部倾角、帽子、发夹、头发轮廓、服饰、光照、线条、整体配色和透明背景不变。不得抬手擦泪、改变身体动作、重新构图、放大、缩小或移动角色；不添加雨滴背景、乌云、文字或额外道具。此图作为完整特色表情播放，不是五官部件。除指定面部区域外，其他区域应尽可能与基准图一致。
更新插件后，在插件目录执行 pnpm install 安装依赖。资源根目录是 Yunzai 根目录下的 data/chatgpt/avatars，不是插件目录。
每个角色一个文件夹，文件夹名就是锅巴下拉中显示的角色名，可使用中文：
data/chatgpt/avatars/
呆毛/
normal.png
close.png
open.png
happy.png
confused.png
angry.png
shy.png
crying.png
另一个角色/
normal.webp
close.webp
open.webp
normal、close、open 三个基础文件名固定，分别表示正常、闭眼、张嘴；扩展名接受 png、jpg、jpeg、webp，大小写不敏感。其余非隐藏图片作为特色表情，最多 32 张。不要把预览截图、对齐对比图等无关图片留在此目录。同名的不同格式文件（例如 normal.png 和 normal.webp）会报冲突。
Bot 主人执行 #chatgpt刷新角色文件夹。插件扫描所有直接子目录，为各角色生成或更新 peraravatar-plus-config.json；不需要先去网站制作 JSON。
默认命名：happy／开心→开心并搭配 bounce；confused／困惑→困惑并搭配 wobble；angry／生气→生气并搭配 shake；shy／害羞→害羞并搭配 wobble；crying／哭泣→哭泣并搭配 none。其他文件以文件名为表情名称，默认 none。新表情 ID 根据源文件名生成，模型仍然只使用已加载的 ID，不直接访问文件。
若已有手工 JSON，刷新优先按 sourceFile 记录匹配原表情；首次处理网站文件时按表情名称的“开心”等前缀匹配。唯一匹配后保留原 ID、名称、动作、图片位移，以及整体呼吸／眨眼设置。新表情使用默认值，删除图片会从生成列表中移除该表情。无法唯一匹配时该角色刷新失败，不猜测覆盖；若首次手工名称完全改成其他词，建议先改回标准名称完成一次匹配，再修改名称。
发生变化时先备份原文件为 peraravatar-plus-config.json.<时间>-<编号>.bak，再原子替换 JSON；没有变化时不重新写入或增加备份。缺少基础图、图片损坏、命名冲突或超限，保留旧 JSON 并显示错误。其他有效角色继续刷新。备份由主人自行保管／清理。
只有 JSON、没有图片的文件夹按手工资源处理，不重建。完整图片模式下网站遗留的 buildMode:parts 字段不会阻止使用完整立绘，真正的顶层分层模式仍不支持。路径穿越和越界目录／图片链接被拒绝。
执行刷新命令后，重新加载锅巴配置页面。在“角色动图群”表格中分别设置：
| 字段 | 用途／可选档位 |
|---|---|
| Bot QQ、群号 | 对应机器人与目标群 |
| 自动附带角色动图 | 只在该 Bot＋对应渠道开启；8888 行为私聊开关 |
| 角色文件夹 | 从已存在资源 JSON 的角色目录下拉选择 |
| GIF 分辨率 | 512×512、768×768、1024×1024（全部为正方形） |
| GIF 时长 | 2、3、5 秒 |
| GIF 帧率 | 10、15、20 FPS |
「角色动图回复」分组里还有一个全局开关「特色表情渐变过渡」（默认开启，与「角色动图群」表格的按群字段相互独立）：开启后，辅助模型选中特色表情时按下面「特色表情的播放时间线」播放；关闭后整段播放特色立绘（旧行为）。
同一个 Bot 在不同群可以使用不同角色和画质；多个 Bot 也可以共享同一角色。未设置时默认 512×512、3 秒、10 FPS；已保存的旧 512×640 档会自动按 512×512 使用。私聊需要预览、状态或自动附图时，手动添加一行：Bot QQ 填实际值、群号填 8888（保留值），该行决定私聊使用的角色与档位；打开该行开关后，私聊回复会自动附图（所有与该 Bot 私聊的用户）。没有 8888 行或未选角色时，私聊预览/状态会提示先到锅巴配置。
也可以将以下字段合并到插件现有 config/config.json，保留其他配置；手动修改群配置后重启 Yunzai，锅巴保存立即生效：
{
"avatarReply": {
"provider": "current",
"groups": [
{
"botId": "123456789",
"groupId": "987654321",
"switchOn": true,
"avatarId": "呆毛",
"size": "1024x1024",
"duration": 3,
"fps": 10
}
]
}
}默认没有授权群；私聊默认不附图，8888 行开关打开后所有私聊用户都会自动附图。开关不改变聊天黑白名单、冷却或模型权限。
| 主人指令 | 用途 |
|---|---|
| #chatgpt刷新角色文件夹 | 按图片生成／更新 JSON，显示各角色的成功或失败结果 |
| #chatgpt角色预览 | 群内使用本群选中的角色和档位；私聊不带名称时使用 8888 行 |
| #chatgpt角色预览 呆毛 | 仅私聊可指定角色目录；档位取 8888 行，没有该行时用默认 512×512／3秒／10 FPS |
| #chatgpt角色状态 | 显示当前渠道（群或私聊 8888 行）的资源路径、档位、图片数量、特色表情、开关和读取错误 |
| #chatgpt角色开启 | 在当前群/私聊开启（私聊操作 8888 行）；仅 Bot 主人可用；要求对应渠道已在锅巴选择角色文件夹 |
| #chatgpt角色关闭 | 在当前群/私聊关闭，取消尚未发送的旧任务；仅 Bot 主人可用 |
资源文件在使用时检查更新，无需为了替换图片重启。更新失败继续使用本进程中该角色上一次成功加载的资源；状态会显示错误。重启无法恢复只存在于内存中的旧版本，必须保留文件备份。切换角色或档位会取消旧的待发任务。
所有角色动图（自动附图、群聊／私聊、主人预览）统一采用画面内的单行电影字幕：白字、黑色描边和轻微阴影，直接覆盖在适当放大的角色立绘下部；不再使用旧气泡、箭头、底框或另留字幕区域。模型优先从完整回复中提炼最多两段自然短句，按顺序硬切换而非逐字出现；本地按标点断句和字符数兜底，切掉每段首尾的标点，长字串自动缩小字号或截短，不能自动折为两行。
字幕切换与特色表情渐变时间线互不干扰。角色输出三个档位均为正方形；旧 512×640 的历史设置读取时改为 512×512。若选择 768×768、3 秒、10 FPS，应在实际 QQ 客户端确认 GIF 仍能自动下载：改动字幕或角色大小会影响字节体积，插件自身的 8 MiB 上限不等于 QQ 的自动下载阈值。
开启「特色表情渐变过渡」（默认开启）且辅助模型选中特色表情时，动图按三段播放：
| 阶段 | 行为 |
|---|---|
| 正常段（约前一半时长） | 普通立绘，眨眼与说话动嘴照常；反应动作（抖动、跳动等）此时不出现 |
| 交叉溶解（约 0.35 秒） | 从普通立绘逐渐混合到特色立绘，仍只播基础运动 |
| 特色段（不短于 1 秒，直至结束） | 保持特色立绘，反应动作在过渡完成后以约 0.2 秒缓入开始；按原眨眼节奏短暂闪回普通「闭眼」帧；不再张嘴 |
2 秒档约为 0.65／0.35／1 秒，3 秒档约为 1.5／0.35／1.15 秒，5 秒档约为 2.5／0.35／2.15 秒。模型未选中特色表情时仍按普通三帧循环播放；关闭全局开关时整段播放特色立绘（旧行为）。
- 放好图片后执行刷新命令，确认目标文件夹显示“已生成”“已更新并备份”或“未变化”。只复制散图不会立即生效，必须刷新。
- 在锅巴选定角色后发 #chatgpt角色状态，确认路径、特色表情名称和档位正确。
- 发 #chatgpt角色预览 检查基本眨眼、嘴型、布局与画质。透明背景是预期效果；预览不调用辅助模型，也不会选中特色表情，看不到渐变过渡；时长短于眨眼间隔时可能看不到眨眼（特色段的闭眼闪回同理）。
- 在启用的群或私聊中进行庆祝、疑问、抱怨、接受夸奖、安慰等对话。辅助模型按最终回复选择特色图，也可以不选，不保证每句话都触发指定表情。
- 生成的图片是否对齐、是否满足资源限制，以及真实提供商的选择效果，仍需用实际素材和群聊检查。
输出为透明背景（GIF 只支持 1 位透明度，半透明边缘会被二值化）；分辨率、时长、帧率按渠道配置，默认 512×512、3 秒、10 FPS。图片素材若是纯白背景，GIF 里也会是白色底，想要真正透明请使用透明背景 PNG。每轮最多一张 GIF。角色字幕最多 2 段，每段不超过 12 个可见字符（合计不超过 24），始终单行、按字数分配时间并保证每段至少 0.7 秒。辅助模型只能选择已存在的表情 ID 和支持的动作；调用失败时用正文首句本地断句、清除首尾标点并采用默认动作。GIF 生成或上传失败不撤销完整文字。
本地渲染不需要 GPU、浏览器、麦克风、摄像头或 FFmpeg。工作线程串行编码，最多三项等待任务，队列满时跳过附图，生成超时为 30 秒。文件超过 8 MiB 或生成超时会跳过附图，不自动降低选定档位，完整正文保留；高分辨率、长时长和高 FPS 会增加耗时与体积。发出前再次检查群授权及资源版本，发送后清理系统临时文件。GIF 编码使用 gifenc（全局透明调色板 + rgb565 最近色匹配，并按上一帧索引做滞回以抑制逐帧色斑闪烁）；渐变仍可能有轻微色阶，QQ 客户端也可能压缩动图。
| 现象 | 处理 |
|---|---|
| 无法确定 Bot／找不到文件 | 用状态命令检查路径；私聊使用群号 8888 行（角色、档位与自动附图开关），其中 Bot QQ 必须等于 Bot 自身 QQ |
| 提示“未选择角色文件夹” | 群内先在锅巴为该 Bot＋群选择角色文件夹；私聊先添加群号 8888 的行并选择角色 |
| 不支持模式／口型档过多 | 选择完整图片模式，只留一个口型档及一张开口图，移除部件特色表情 |
| 图片不是内嵌数据 | 替换网站样例为自己的图片，重新下载配置 JSON |
| 特色表情超限 | 特色表情最多 32 种，同时检查 JSON 32 MiB、单图 6 MiB、累计 32 MiPixels 的资源限制 |
| 切换时角色抖动 | 检查差分对齐，在网站修正位置和大小，或重新编辑差分 |
| 首句电影字幕／没有动图 | 查看 [ChatGPT] 角色字幕／渲染／发送日志和状态命令，检查模型连接、队列及上传 |
| 特色表情没有渐变过渡 | 检查锅巴「特色表情渐变过渡」开关是否开启；辅助模型未选中特色表情时本就不进入特色段（正常现象）；关闭开关时整段播放特色立绘 |
| 中文显示方块 | 安装系统中文字体；Debian/Ubuntu 可安装 fonts-noto-cjk，安装后重启 Yunzai |
| 替换 JSON 后仍是旧角色 | 查看状态中的读取提示；修正文件后重新预览，首次失败不会创建假资源 |
人工构造的栅格测试素材仅验证状态切换、解析、权限、任务取消和 GIF 编码，不代表 GPT Image 2 差分质量。
需要生成真实验证素材时，使用 misaka-gpt-image-agent 的 gpt-image-2 技能接口：调用注册的 generate_image／edit_image，按技能传入绝对 outputDir；差分使用 imagePaths 引用正常图，不传透明背景或 input_fidelity，不提交测试素材。若该接口未在验证会话中暴露，记录素材生成尚未验证，不能改用 Codex 内置生图或另写 API 客户端替代。
上线验收还需由 Bot 主人在实际适配器及 QQ 群中验证动图上传、显示和字体。Windows 本地测试不代表 Linux 服务器的中文字体与显示效果。