解密 SillyTavern 角色卡片系统PNG 元数据存储的技术架构与实战指南【免费下载链接】SillyTavernLLM Frontend for Power Users.项目地址: https://gitcode.com/GitHub_Trending/si/SillyTavern从社区下载一张看起来只是普通头像的 PNG 图片拖进 SillyTavern 后一个拥有完整性格、开场白、世界观甚至专属表情包的角色立刻出现在列表中——这就是角色卡片系统的魔法。SillyTavern 的角色卡片系统把一整套结构化角色数据缝进图片的像素之外随图携带、随处可分享。它到底是怎么做到的本文从 PNG 文件格式的最底层数据块讲起逐层拆开这套存储机制再用 3 个由浅入深的实战案例带你亲手创建、编辑、批量管理角色卡片。一个钩子为什么角色必须长在图片里先看一个真实痛点一个 AI 角色通常包含姓名、性格描述、开场白、对话示例、世界书条目、扩展插件配置……这些字段加在一起往往有几 KB 甚至几十 KB 的文本。如果把这些数据单独存成 JSON 文件分享给朋友时就得图片 配置打包传输如果存进数据库换一台机器或换一个前端就全部失效。SillyTavern 的答案是把数据直接写进角色头像图片本身。用户拿到的永远是一个文件一张 PNG。它既是可视化的角色形象又是可被任何 SillyTavern 实例识别的数据载体。这份所见即所得的便携性是角色卡片系统最核心的设计动机。幕后机制一张 PNG 如何容纳一份角色档案PNG 文件并非只有像素数据。它的结构是一串块chunk从固定的 8 字节签名89 50 4E 47开始依次排列 IHDR头部、IDAT图像数据、IEND结束块等。规范允许在 IDAT 与 IEND 之间插入任意数量的辅助块其中tEXt块专门用于存放文本信息——这就是角色卡片数据的藏身之处。写入把 JSON 塞进 tEXt 块核心实现在 src/character-card-parser.jswrite(image, data)函数的流程可以概括为四步用png-chunks-extract把整张图片拆解成 chunk 数组过滤掉已有的chara/ccv3关键字 tEXt 块避免重复写入将角色 JSON 以 UTF-8 编码后做 Base64 转换再用png-chunk-text包装成关键字为chara的 tEXt 块插到 IEND 块之前顺手再生成一份 V3 规范spec: chara_card_v3的副本写入关键字为ccv3的块。关键点在于Base64 编码。PNG 的 tEXt 块只保证 Latin-1 文本的安全传输中文描述、特殊符号直接写入会破坏块结构Base64 把任意 UTF-8 内容都收敛成 ASCII 字符集彻底绕开编码问题——这是整套方案里最容易踩坑、也最值得学习的一笔。读取优先 V3回退 V2read(image)是写入的逆过程提取所有 tEXt 块并解码关键字先找ccv3找不到再找chara命中后把文本做 Base64 解码还原成 JSON。这种新规范优先、旧规范兜底的设计保证了向后兼容老卡片永远能被读取新卡片在旧版本前端里也不会直接崩溃。为什么选 PNG 而不是 JPGJPG 是破坏性压缩重存一次就可能污染内嵌数据PNG 无损且块结构开放、可精确增删 tEXt 块。这也是社区角色卡片几乎清一色 PNG 的根本原因。格式与容量边界tEXt 块的数据长度字段是 4 字节理论上单块上限接近 2GB实际角色卡片多在几 KB 到几十 KB完全够用读取是一次内存内的 chunk 过滤 一次 Base64 解码典型卡片解析耗时在毫秒级写入时同图会同时携带 V2 与 V3 两套数据文件体积只增加少量文本开销。模块地图三层架构与数据流转路径角色卡片系统可以切成三个层次各自职责清晰层次核心文件职责存储层src/character-card-parser.js、src/png/encode.jsPNG chunk 的读写、Base64 编解码、CRC 校验逻辑层src/validator/TavernCardValidator.js、src/byaf.js、src/charx.js卡片格式验证、多格式BYAF/CharX/JSON/YAML互转接口层src/endpoints/characters.js创建、编辑、导入、导出、删除、复制的 REST API数据流转路径也很清晰文件系统上的 PNG → character-card-parser 解码 → 验证器校验 → 前端渲染角色面板反向则是前端编辑表单 → 组装 V2/V3 JSON → parser 编码 → 落盘为 PNG。验证器三道关卡守住格式底线TavernCardValidator.js 的validate()依次尝试 V1、V2、V3 三套规范命中即返回对应的版本号全部落空返回 false。V1 是最早的六字段结构name、description、personality、scenario、first_mes、mes_exampleV2 增加了spec: chara_card_v2标记并大幅扩充字段V3 则要求spec_version落在 3.0~3.9 之间。验证失败时lastValidationError会精确指出是哪个字段缺失这也是导入报错排查的第一入口。V2 卡片的完整字段结构定义在 src/types/spec-v2.d.ts除六项基础字段外还包括creator_notes / system_prompt / post_history_instructions作者说明、系统提示词、历史后置指令alternate_greetings多组可选开场白character_book内嵌世界书含 entries 数组每个条目有 keys、content、enabled、insertion_order、selective、position 等属性tags / creator / character_version / extensions标签、作者、版本号与插件扩展位。动手实验室3 个由浅入深的角色卡片实战案例一入门导入一张现成卡片并原样导出启动 SillyTavern进入角色管理界面点击导入按钮选择一张 PNG 角色卡片比如仓库自带的 default_Seraphina.png后端会调用/api/characters/import按扩展名识别png格式并走importFromPng流程确认角色出现在列表中点进编辑检查描述、开场白、替代问候语是否完整——说明元数据被正确解码回到角色管理选择导出 PNG浏览器会收到一个重新编码后的文件。把它和原文件对比图片像素不变但 tEXt 块已被write()重写。要点导入时后端用parse()读取导出时先read()读出原始 JSON剥离私有字段如聊天历史引用后再write()回写保证分享出去的文件不泄露本地数据。案例二进阶手写一份 V2 JSON 并编码进图片这一例带你绕过界面直接走数据通路按 V2 规范手写 JSON最低要求字段spec、spec_version、data.name、data.description、data.first_mes等建议先用验证器跑一遍确保字段齐全在项目根目录写一段 Node 脚本import { write } from ./src/character-card-parser.js读取任意一张 PNG 作为底图把 JSON 字符串交给write(imageBuffer, jsonString)把输出 buffer 存成新 PNG再拖回 SillyTavern 导入——角色应完整出现用read()读回确认 JSON 与原数据一致。要点手写时最容易漏掉alternate_greetings必须为数组和extensions必须为对象这两项是验证器的高频报错点。写完后务必用 src/validator/TavernCardValidator.js 自检别让错误卡片进入分享环节。案例三专家用 API 批量管理 多格式互通当角色数量上百时手点界面不再现实用/api/characters/all拉取全部角色列表拿到每个角色的文件名遍历调用/api/characters/exportformat 传png或json做批量备份备份脚本里对每条记录先read()再write()统一升级到最新 V2/V3 双写格式针对其他生态的卡片如 Backyard 导出的.byaf、旧版 JSON、YAML用/api/characters/import的file_type参数分别指定byaf、json、yaml后端会经 src/byaf.js 等模块做宏替换#{user}→{{user}}和字段映射后统一转成标准卡片为角色配置场景背景把 default/content/backgrounds 下的图片上传为聊天背景并在地点切换时联动更新角色行为设定。SillyTavern 角色卡片系统搭配的中世纪集市场景背景用于增强角色交互沉浸感要点BYAF 是 zip 容器内部包含 manifest 与角色 JSONByafParser会取 manifest 中的第一个角色并自动转换示例对话与开场白格式多角色 BYAF 只导入第一个导入前先检查 manifest。选择智慧PNG 卡片与替代方案怎么取舍特性PNG 角色卡片本方案独立 JSON 配置数据库存储第三方托管服务便携性极高单文件即角色中需配套管理低依赖环境中依赖服务可用性可视化自带形象图无需额外关联图片视服务而定分享成本发一张图即可需打包多文件需导出迁移需开放访问权限版本兼容V2/V3 双写向后兼容无统一规范结构自定义厂商锁定数据安全本地文件剥离私有字段后导出同左集中但需维护数据出境风险适用场景社区分享、个人收藏、跨端迁移脚本批处理团队协作、多端同步在线画廊结论很直白面向分享与携带选 PNG 卡片面向自动化与批量选 JSON面向多人协作才考虑数据库。三者并不互斥——SillyTavern 本身就用文件系统存储 PNG同时提供 JSON 导出接口供脚本消费。防坑手册5 个高频问题排障问题一角色卡片导入失败提示无法识别症状PNG 能正常打开但导入后提示无角色数据病因tEXt 块缺失或关键字不对、元数据在传输中被第三方图床二次压缩剥离、编码损坏处理流程① 用验证器检查 JSON 结构 → ② 确认原图未经 JPEG 转换 → ③ 用read()直接读文件若抛 No PNG metadata 则确认数据确实丢失 → ④ 找原始导出文件或备份重新导入。问题二导入成功但角色名字变成乱码症状中文描述、开场白显示为乱码病因tEXt 块被非标准工具以错误编码写入处理流程用read()解码后检查是否为合法 JSON若是 Base64 内容错乱则需重新导出规范卡片都走 Base64不应出现此问题多发生在手工拼接的卡片上。问题三编辑保存后图片被压糊症状头像模糊、色块异常病因某些编辑流程先做了有损重编码或 IEND 前的 chunk 顺序被破坏处理流程① 避免在导入导出之间用非 SillyTavern 工具重存 → ② 导出前检查 chunk 顺序IDAT 必须在 tEXt 之前→ ③ 用 src/png/encode.js 重新组装。问题四旧版前端读不了新卡片症状新卡片在其他实例导入后空白病因对方版本只认 V2而卡片只有 V3 块处理流程用支持双写的版本重新保存一次write()会同时写入chara与ccv3旧版读 V2、新版读 V3两全其美。问题五导出文件比原图大很多症状分享文件体积翻倍病因数据本身大含大量世界书条目且 V2/V3 双写叠加处理流程① 精简 description 与 mes_example → ② 把大段世界书拆成独立世界书文件 → ③ 接受数据换便携的必然成本。调优与扩展性能、集成与监控性能优化三板斧缓存读结果频繁查看角色时把read()的结果按文件名做内存缓存避免重复解块批量操作走 JSON需要改大量角色的字段时用export json批量修改后再import json比逐张 PNG 读写快一个量级控制卡片体积description 控制在 1~2KB、示例对话精简既是 token 成本问题也是解析效率问题。扩展与集成方向情绪表情角色卡片的extensions字段可挂载情绪配置配套的 public/scripts/extensions/expressions 扩展会把情绪名映射到同目录下的表情图仓库自带的 default/content/Seraphina 就配齐了 28 种情绪图让角色随对话变脸角色书联动character_book内嵌世界书可与全局世界书并行注意 token_budget 与 scan_depth 的配比CI 化质量管理在提交角色卡片前写一个 Node 脚本批量跑验证器把不合规卡片挡在仓库外监控与调试服务端日志会输出 PNG metadata does not contain any text chunks 等关键错误配合/api/characters/get逐张检查卡片解析没有专门的性能面板用脚本统计read()耗时即可建立基线。收尾盘点这套设计教会了我们什么回看整个角色卡片系统最值得借鉴的是三件事用文件格式的开放规范做数据载体PNG tEXt 块 Base64 解决编码问题、用版本双写做向前兼容V2/V3 共存、读取时优先新版、用统一验证器守住数据质量V1/V2/V3 三档校验并给出精确报错。这三条原则叠加出一个结论真正好用的数据格式不是功能最全的而是旧工具打不开也不至于坏、新工具读起来还能自动升级的。学习资源清单核心解析器源码src/character-card-parser.js卡片格式验证器src/validator/TavernCardValidator.jsV2 字段规范定义src/types/spec-v2.d.ts角色管理 API 端点src/endpoints/characters.jsBYAF 格式解析src/byaf.js示例角色含 28 张情绪图default/content/Seraphina场景背景素材库default/content/backgrounds情绪扩展实现public/scripts/extensions/expressions源码获取git clone https://gitcode.com/GitHub_Trending/si/SillyTavern最佳实践清单分享前必自检导出前跑一次验证器别把半成品发出去双写是默认动作能生成 V2/V3 双份就别只写一份兼容性是最好的传播力敏感字段要剥离导出接口已内置私有字段清理自己写脚本时务必复用unsetPrivateFields逻辑版本控制进仓库角色卡片用 Git 管理图片改动同样可追踪先备份再批量改任何批量导入导出操作前先做一次全量 PNG 导出备份。角色卡片系统的魅力在于一张图就是一个世界——理解了 tEXt 块里那串 Base64你不仅能熟练导入导出还能自己写工具批量生产、校验、分发角色把 SillyTavern 真正变成你自己的角色工厂。【免费下载链接】SillyTavernLLM Frontend for Power Users.项目地址: https://gitcode.com/GitHub_Trending/si/SillyTavern创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考