SillyTavern 角色卡系统技术分析

// 写入时同时创建 V2 和 V3 chunks
export const write = (image, data) => {
    // 1. 清除现有 chara/ccv3 chunks
    // 2. 添加新的 V2 chunk
    chunks.splice(-1, 0, PNGtext.encode('chara', base64EncodedData));
    // 3. 尝试添加 V3 chunk（从 V2 数据转换）
    const v3Data = JSON.parse(data);
    v3Data.spec = 'chara_card_v3';
    v3Data.spec_version = '3.0';
    chunks.splice(-1, 0, PNGtext.encode('ccv3', base64EncodedV3Data));
};

export const read = (image) => {
    // V3 (ccv3) 优先
    const ccv3Index = textChunks.findIndex(chunk => chunk.keyword.toLowerCase() === 'ccv3');
    if (ccv3Index > -1) {
        return Buffer.from(textChunks[ccv3Index].text, 'base64').toString('utf8');
    }
    // 降级到 V2 (chara)
    const charaIndex = textChunks.findIndex(chunk => chunk.keyword.toLowerCase() === 'chara');
    if (charaIndex > -1) {
        return Buffer.from(textChunks[charaIndex].text, 'base64').toString('utf8');
    }
};

// PNG 文件签名
const PNG_SIGNATURE = [0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A];

// Chunk 结构：Length (4 bytes) | Type (4 bytes) | Data (n bytes) | CRC (4 bytes)
// 每个 chunk 的 CRC32 校验涵盖 Type 和 Data 部分

export class MemoryLimitedMap {
    constructor(cacheCapacity) {
        this.maxMemory = bytes.parse(cacheCapacity) ?? 0;  // 最大内存限制
        this.currentMemory = 0;                             // 当前内存使用
        this.map = new Map();                               // 键值存储
        this.queue = [];                                    // LRU 队列
    }

    static estimateStringSize(str) {
        return str ? str.length * 2 : 0;  // UTF-16: 2 bytes/char
    }

    set(key, value) {
        const newValueSize = MemoryLimitedMap.estimateStringSize(value);
        
        // 如果单条超过限制，拒绝
        if (newValueSize > this.maxMemory) return;
        
        // 驱逐旧条目直到有足够空间
        while (this.currentMemory + newValueSize > this.maxMemory && this.queue.length > 0) {
            const oldestKey = this.queue.shift();
            const oldestValue = this.map.get(oldestKey);
            this.map.delete(oldestKey);
            this.currentMemory -= MemoryLimitedMap.estimateStringSize(oldestValue);
        }
        
        // 添加新条目
        this.map.set(key, value);
        this.queue.push(key);
        this.currentMemory += newValueSize;
    }
}

class DiskCache {
    static DIRECTORY = 'characters';
    static SYNC_INTERVAL = 5 * 60 * 1000;  // 5 分钟
    
    // node-persist 配置
    const storage = {
        dir: cachePath,
        ttl: false,                    // 不过期
        forgiveParseErrors: true,      // 宽容解析错误
        expiredInterval: 0,            // 不检查过期
        maxFileDescriptors: 100,       // 最大文件描述符
    };
}

// 每 5 分钟执行一次
async #syncCacheEntries() {
    const directories = [...this.syncQueue].map(entry => getUserDirectories(entry));
    this.syncQueue.clear();
    await this.verify(directories);  // 清理无效条目
}

// 验证：删除已不存在的角色文件对应的缓存
async verify(directoriesList) {
    for (const dir of directoriesList) {
        const files = fs.readdirSync(dir.characters, { withFileTypes: true });
        // 只保留存在的 PNG 文件对应的缓存键
        const validKeys = new Set(files.filter(f => f.isFile() && path.extname(f.name) === '.png')
            .map(file => path.parse(cache.getDatumPath(getCacheKey(filePath))).base));
    }
}

function getCacheKey(inputFile) {
    if (fs.existsSync(inputFile)) {
        const stat = fs.statSync(inputFile);
        return `${inputFile}-${stat.mtimeMs}`;  // 包含修改时间
    }
    return inputFile;
}

export class TavernCardValidator {
    #lastValidationError = null;

    validate() {
        if (this.validateV1()) return 1;
        if (this.validateV2()) return 2;
        if (this.validateV3()) return 3;
        return false;
    }
}

validateV1() {
    const requiredFields = [
        'name', 'description', 'personality', 
        'scenario', 'first_mes', 'mes_example'
    ];
    return requiredFields.every(field => Object.hasOwn(this.card, field));
}

validateV2() {
    return this.#validateSpecV2()           // spec === 'chara_card_v2'
        && this.#validateSpecVersionV2()    // spec_version === '2.0'
        && this.#validateDataV2()           // data 对象验证
        && this.#validateCharacterBookV2(); // character_book 验证
}

#validateDataV2() {
    const requiredFields = [
        'name', 'description', 'personality', 'scenario',
        'first_mes', 'mes_example', 'creator_notes', 'system_prompt',
        'post_history_instructions', 'alternate_greetings', 'tags',
        'creator', 'character_version', 'extensions'
    ];
    // 检查所有必需字段 + 数组类型验证
}

validateV3() {
    return this.#validateSpecV3()           // spec === 'chara_card_v3'
        && this.#validateSpecVersionV3()    // 3.0 <= version < 4.0
        && this.#validateDataV3();          // data 对象存在
}

router.post('/merge-attributes', async (request, response) => {
    const validator = new TavernCardValidator(character);
    
    if (validator.validate()) {
        await writeCharacterData(avatarPath, JSON.stringify(character), targetImg, request);
        response.sendStatus(200);
    } else {
        response.status(400).send({
            message: `Validation failed for ${character.name}`,
            error: validator.lastValidationError
        });
    }
});

// jimp.js - 自定义 Jimp 实例
const Jimp = createJimp({
    formats: [
        webp, png, jpeg, avif,  // WASM 优化格式
        bmp, msBmp, gif, tiff   // JS 实现格式
    ],
    plugins: [
        blit, circle, color, contain, cover,
        crop, displace, fisheye, flip, mask,
        resize, rotate, threshold, quantize
    ],
});

export const AVATAR_WIDTH = 512;
export const AVATAR_HEIGHT = 768;

export async function applyAvatarCropResize(jimp, crop) {
    let finalWidth = image.bitmap.width;
    let finalHeight = image.bitmap.height;

    // 1. 应用裁剪（如果指定）
    if (crop && [crop.x, crop.y, crop.width, crop.height].every(x => typeof x === 'number')) {
        image.crop({ x: crop.x, y: crop.y, w: crop.width, h: crop.height });
        
        // 2. 应用标准缩放（如果请求）
        if (crop.want_resize) {
            finalWidth = AVATAR_WIDTH;
            finalHeight = AVATAR_HEIGHT;
        }
    }

    // 3. 使用 cover 模式调整尺寸（保持比例，裁剪溢出）
    image.cover({ w: finalWidth, h: finalHeight });
    
    return await image.getBuffer(JimpMime.png);
}

function convertToV2(char, directories) {
    return charaFormatData({
        json_data: JSON.stringify(char),
        ch_name: char.name,
        description: char.description,
        personality: char.personality,
        scenario: char.scenario,
        first_mes: char.first_mes,
        mes_example: char.mes_example,
        creator_notes: char.creatorcomment,
        talkativeness: char.talkativeness,
        fav: char.fav,
        creator: char.creator,
        tags: char.tags,
        depth_prompt_prompt: char.depth_prompt_prompt,
        depth_prompt_depth: char.depth_prompt_depth,
        depth_prompt_role: char.depth_prompt_role,
    }, directories);
}

function readFromV2(char) {
    const fieldMappings = {
        name: 'name',
        description: 'description',
        personality: 'personality',
        scenario: 'scenario',
        first_mes: 'first_mes',
        mes_example: 'mes_example',
        talkativeness: 'extensions.talkativeness',
        fav: 'extensions.fav',
        tags: 'tags',
    };

    _.forEach(fieldMappings, (v2Path, charField) => {
        const v2Value = _.get(char.data, v2Path);
        if (_.isUndefined(v2Value)) {
            // 填充默认值
            if (v2Path === 'extensions.talkativeness') defaultValue = 0.5;
            if (v2Path === 'extensions.fav') defaultValue = false;
        }
        char[charField] = v2Value;
    });
}

function unsetPrivateFields(char) {
    _.set(char, 'fav', false);                    // 重置收藏状态
    _.set(char, 'data.extensions.fav', false);
    _.unset(char, 'chat');                        // 移除聊天记录引用
}