SillyTavern加载角色卡失败如何解决？

Question

在使用 SillyTavern 过程中，用户常遇到“加载角色卡失败”的问题，表现为角色头像和信息无法显示，控制台报错“Failed to parse character card”或“Invalid JSON format”。该问题通常由角色卡文件格式不兼容、JSON 结构损坏或编码错误（如 BOM 头）引起。即使卡片来自可信源，手动编辑或下载过程中也可能引入不可见字符，导致解析失败。此外，SillyTavern 版本更新后，角色卡结构未同步适配也会引发此类错误。需检查文件完整性、确认 JSON 格式合法，并确保与当前版本兼容。

Answer 1

一、问题现象与初步诊断

在使用 SillyTavern 时，用户频繁反馈“加载角色卡失败”，具体表现为角色头像未显示、角色信息空白，浏览器控制台输出如下错误：

Failed to parse character card: Unexpected token in JSON at position X
Invalid JSON format received for character import

此类报错通常指向角色卡文件（.json）的解析异常。尽管卡片来源于社区可信平台（如 Character Hub 或 CivitAI），但在传输或编辑过程中可能引入格式偏差。常见诱因包括：

• JSON 结构语法错误（如缺少逗号、括号不匹配）
• 文件编码包含 UTF-8 BOM 头（\ufeff），干扰 JSON 解析器
• 不可见控制字符（如 \r\n 混用、零宽空格）嵌入字段中
• 角色卡结构版本与当前 SillyTavern 不兼容（v1 vs v2 schema）

二、深入分析：从文件结构到运行环境

SillyTavern 使用标准化的 JSON Schema 来定义角色卡结构。以 v2 角色卡为例，其核心字段如下表所示：

字段名	类型	说明
name	string	角色名称
description	string	角色背景描述
personality	string	性格设定
scenario	string	初始场景
mes_example	string	对话示例
creator_notes	string	创作者备注
character_version	string	卡片版本标识
spec	string	规范版本（如 "chara_card_v2"）

若上述任一字段缺失或类型不符，均会导致解析失败。此外，SillyTavern 自 v1.7 起强制要求 spec 字段声明为 "chara_card_v2"，否则视为旧格式并拒绝加载。

三、技术排查流程图

graph TD
            A[角色卡加载失败] --> B{检查控制台错误}
            B -->|Invalid JSON| C[验证JSON语法]
            B -->|Unknown format| D[确认spec字段]
            C --> E[使用JSON Lint校验]
            D --> F[比对SillyTavern文档schema]
            E --> G[移除BOM头或隐藏字符]
            F --> H[升级/降级卡片结构]
            G --> I[重新导入测试]
            H --> I
            I --> J{是否成功?}
            J -->|是| K[问题解决]
            J -->|否| L[检查SillyTavern日志]

四、解决方案与最佳实践

以下是系统性修复步骤，适用于开发运维及高级用户：

1. 使用在线工具验证 JSON 合法性：上传文件至 JSONLint，检测语法错误。
2. 清除 BOM 头：通过 VS Code 打开文件，底部状态栏点击“UTF-8” → 选择“Save with Encoding” → 保存为 UTF-8（无 BOM）。
3. 正则清洗隐藏字符：在支持正则替换的编辑器中执行以下表达式：

   [\u0000-\u001f\u007f-\u009f\u200b-\u200d\ufeff]

   替换为空字符串以清除零宽字符。
4. 适配最新 schema：参考官方 GitHub 中 /src/types/character.type.ts 定义，确保字段完整且命名一致。
5. 自动化脚本预处理：编写 Node.js 脚本批量清理角色卡：

   const fs = require('fs');
   const path = require('path');
   
   function cleanCharacterCard(filePath) {
       let content = fs.readFileSync(filePath, 'utf8');
       // 移除 BOM 和控制字符
       content = content.replace(/^\uFEFF/, '').replace(/[\u0000-\u001F\u007F-\u009F]/g, '');
       try {
           const json = JSON.parse(content);
           // 补全必要字段
           if (!json.spec) json.spec = "chara_card_v2";
           fs.writeFileSync(filePath, JSON.stringify(json, null, 2), 'utf8');
           console.log(`✅ Cleaned: ${filePath}`);
       } catch (e) {
           console.error(`❌ Parse failed: ${filePath}`, e.message);
       }
   }

6. 版本兼容性管理：建立角色卡元数据索引，记录 sillytavern_version_requirement 字段，便于回溯适配。
7. 前端容错增强：建议开发者在 SillyTavern 中增加 JSON 解析 wrapper：

   try {
       const card = JSON.parse(raw);
   } catch (e) {
       showToast(`解析失败: ${e.message}. 请检查编码或使用转换工具.`);
   }

8. CI/CD 集成检测：在角色卡仓库中配置 GitHub Action，自动运行 JSON Schema 校验和 linting。
9. 社区协作机制：推动标准化模板发布，附带校验 CLI 工具，提升整体生态健壮性。
10. 日志深度追踪：启用 SillyTavern 的 debug 模式，捕获更详细的加载上下文，辅助定位边缘 case。