Amily-Databin/README.md

Amily-Databin

Databin组件，优化数据存储持久化功能，不直接提供用户界面，默认仅供开发者进行调用。

该组件的意义为降低开发者对数据存储的复杂度，提供一种简单的数据存储方式，并支持数据持久化。该组件维护且仅维护存储和读取数据，不提供用户界面。（当然，并不意味着该组件不可用于用户界面，我们鼓励用户自行设计用户界面）

安装

通过链接安装 (推荐)

1. 在 SillyTavern 的扩展页面，点击 "Install from URL"。
2. 输入以下链接: https://amily-gitlab.amily49.cc/slvccans/Amily-Databin
3. 点击 "Install"。
4. 重启 SillyTavern.

手动安装

1. 下载本仓库的 ZIP 压缩包。
2. 解压 ZIP 文件。
3. 将 Amily-Databin 文件夹复制到 SillyTavern/public/extensions 目录下。
4. 重启 SillyTavern.

API 用法

本插件会在客户端环境中注入一个全局的 window.AmilyDatabin 对象，用于进行精细化的数据交互。

架构说明: SourceType 常量表现在通过根目录的 sourcetype.json 文件进行动态管理。客户端会在加载时自动从服务器获取此配置，这使得系统具有很强的扩展性，未来增加新的数据类型也无需修改客户端代码。

AmilyDatabin.SourceType

一个用于定义数据来源的常量表。

{
    CHAT_LOG: 1,       // 用于聊天文件存储
    CHARACTER_CARD: 2, // 用于角色卡存储
    WORLD_BOOK: 3      // 用于世界书存储
}

AmilyDatabin.getData(source, fileName, objName = null)

从服务器获取特定数据。objName 是可选的，如果省略，插件会从当前上下文中自动检测。

/**
 * 从服务器获取特定数据。
 * @param {number} source - 数据来源标识 (使用 AmilyDatabin.SourceType)。
 * @param {string} fileName - 文件名或唯一键。
 * @param {string} [objName=null] - 可选。指定对象名（如角色ID）。若为null，则自动检测。**注意：对于 `WORLD_BOOK` 类型，`objName` 无法自动检测，必须明确提供。**
 * @returns {Promise<object|null>} 一个Promise，解析为请求到的数据对象；如果未找到则为 null。
 */
async function retrieveCurrentCharacterMemory() {
    try {
        // 此处省略了 objName，插件将自动使用当前角色的ID
        const memory = await window.AmilyDatabin.getData(
            window.AmilyDatabin.SourceType.CHARACTER_CARD,
            "character_memory.json"
        );
        
        if (memory) {
            console.log("成功获取当前角色记忆:", memory);
        } else {
            console.log("没有找到当前角色的记忆。");
        }
        return memory;
    } catch (error) {
        console.error("获取数据失败:", error);
        return null;
    }
}

// 自动上下文调用示例:
retrieveCurrentCharacterMemory();

AmilyDatabin.saveData(source, fileName, fileContent, objName = null)

将一个JavaScript对象保存到服务器的指定路径。objName 是可选的。

/**
 * 将一个数据对象保存到服务器的指定路径。
 * @param {number} source - 数据来源标识 (使用 AmilyDatabin.SourceType)。
 * @param {string} fileName - 文件名或唯一键。
 * @param {string} [objName=null] - 可选。指定对象名。若为null，则自动检测。**注意：对于 `WORLD_BOOK` 类型，`objName` 无法自动检测，必须明确提供。**
 * @returns {Promise<boolean>} 一个Promise，如果保存成功则解析为 true，否则为 false。
 */
async function saveCurrentChatLog(chatHistory) {
    try {
        // 此处省略了 objName，它将自动解析为当前聊天的ID
        const success = await window.AmilyDatabin.saveData(
            window.AmilyDatabin.SourceType.CHAT_LOG,
            `log_${new Date().getTime()}.json`, // 唯一键示例
            { history: chatHistory, savedAt: new Date().toISOString() }
        );

        if (success) {
            console.log("当前聊天的记录已成功保存。");
        } else {
            console.error("聊天记录保存失败。");
        }
        return success;
    } catch (error) {
        console.error("保存数据时出错:", error);
        return false;
    }
}

// 调用示例:
const currentChat = ["用户: 你好!", "角色: 你好！"];
saveCurrentChatLog(currentChat);

AmilyDatabin.deleteData(source, fileName, objName = null)

从服务器删除一个指定的数据文件。objName 是可选的。

/**
 * 从服务器删除一个特定的数据文件。
 * @param {number} source - 数据来源标识 (使用 AmilyDatabin.SourceType)。
 * @param {string} fileName - 要删除的数据的文件名或唯一键。
 * @param {string} [objName=null] - 可选。指定对象名。若为null，则自动检测。**注意：对于 `WORLD_BOOK` 类型，`objName` 无法自动检测，必须明确提供。**
 * @returns {Promise<boolean>} 一个Promise，如果删除成功则解析为 true，否则为 false。
 */
async function deleteCurrentCharacterMemory() {
    try {
        const success = await window.AmilyDatabin.deleteData(
            window.AmilyDatabin.SourceType.CHARACTER_CARD,
            "character_memory.json"
        );
        
        if (success) {
            console.log("成功删除当前角色记忆。");
        } else {
            console.log("删除角色记忆失败。");
        }
        return success;
    } catch (error) {
        console.error("删除数据失败:", error);
        return false;
    }
}

// 调用示例:
deleteCurrentCharacterMemory();

调试方法

这些方法设计用于在浏览器控制台中进行快速调试。它们不与后端API交互。

AmilyDatabin.getDebugInstance()

将 AmilyDatabin 对象本身输出到控制台。可用于检查其当前状态、SourceType 映射和可用方法。

// 在浏览器控制台调用:
AmilyDatabin.getDebugInstance();
// 预期输出: { SourceType: { CHAT_LOG: 1, ... }, initialize: f, ... }

AmilyDatabin.getDebugChatId()

尝试使用与主API方法相同的逻辑解析当前聊天ID，并将其记录到控制台。

// 在浏览器控制台调用:
AmilyDatabin.getDebugChatId();
// 预期输出: [Amily-Databin] Current Chat ID (Debug): "你的聊天ID"

AmilyDatabin.getDebugCardId()

尝试使用与主API方法相同的逻辑解析当前角色卡ID，并将其记录到控制台。

// 在浏览器控制台调用:
AmilyDatabin.getDebugCardId();
// 预期输出: [Amily-Databin] Current Character Card ID (Debug): "你的角色卡ID"

开发者

主要逻辑分别位于 index.js (服务器端) 和 public/client.js (客户端)。

你可以直接通过全局的 window.AmilyDatabin 对象与此插件交互。