update by Silence_Lurker

Init plugin
2025-12-23 16:22:27 +08:00
parent 5635b3441a
commit fd244519cc
10 changed files with 878 additions and 1 deletions
--- a/README.md
+++ b/README.md
@@ -1,3 +1,188 @@
 # Amily-Databin

-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`
+
+一个用于定义数据来源的常量表。
+
+```javascript
+{
+    CHAT_LOG: 1,       // 用于聊天文件存储
+    CHARACTER_CARD: 2, // 用于角色卡存储
+    WORLD_BOOK: 3      // 用于世界书存储
+}
+```
+
+### `AmilyDatabin.getData(source, fileName, objName = null)`
+
+从服务器获取特定数据。`objName` 是可选的，如果省略，插件会从当前上下文中自动检测。
+
+```javascript
+/**
+ * 从服务器获取特定数据。
+ * @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` 是可选的。
+
+```javascript
+/**
+ * 将一个数据对象保存到服务器的指定路径。
+ * @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` 是可选的。
+
+```javascript
+/**
+ * 从服务器删除一个特定的数据文件。
+ * @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` 映射和可用方法。
+
+```javascript
+// 在浏览器控制台调用:
+AmilyDatabin.getDebugInstance();
+// 预期输出: { SourceType: { CHAT_LOG: 1, ... }, initialize: f, ... }
+```
+
+### `AmilyDatabin.getDebugChatId()`
+
+尝试使用与主API方法相同的逻辑解析当前聊天ID，并将其记录到控制台。
+
+```javascript
+// 在浏览器控制台调用:
+AmilyDatabin.getDebugChatId();
+// 预期输出: [Amily-Databin] Current Chat ID (Debug): "你的聊天ID"
+```
+
+### `AmilyDatabin.getDebugCardId()`
+
+尝试使用与主API方法相同的逻辑解析当前角色卡ID，并将其记录到控制台。
+
+```javascript
+// 在浏览器控制台调用:
+AmilyDatabin.getDebugCardId();
+// 预期输出: [Amily-Databin] Current Character Card ID (Debug): "你的角色卡ID"
+```
+
+## 开发者
+
+主要逻辑分别位于 `index.js` (服务器端) 和 `public/client.js` (客户端)。
+
+你可以直接通过全局的 `window.AmilyDatabin` 对象与此插件交互。