189 lines
6.8 KiB
Markdown
189 lines
6.8 KiB
Markdown
# 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`
|
||
|
||
一个用于定义数据来源的常量表。
|
||
|
||
```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` 对象与此插件交互。
|