193 lines
7.4 KiB
Markdown
193 lines
7.4 KiB
Markdown
# Amily-Databin
|
|
|
|
A Databin component designed to optimize data storage persistence. It does not directly provide a user interface but is intended for developers to call for data operations.
|
|
|
|
The purpose of this component is to simplify data storage for developers, offering a straightforward method for data storage with persistence support. This component solely manages data storage and retrieval; it does not offer a user interface. (However, this does not mean the component cannot be used for user interfaces; users are encouraged to design their own user interfaces.)
|
|
|
|
## Installation
|
|
|
|
### Install via Link (Recommended)
|
|
|
|
1. In the SillyTavern extensions page, click "Install from URL".
|
|
2. Enter the following link: `https://amily-gitlab.amily49.cc/slvccans/Amily-Databin`
|
|
3. Click "Install".
|
|
4. Restart SillyTavern.
|
|
|
|
### Manual Installation
|
|
|
|
1. Download the ZIP archive of this repository.
|
|
2. Extract the ZIP file.
|
|
3. Copy the `Amily-Databin` folder to the `SillyTavern/public/extensions` directory.
|
|
4. Restart SillyTavern.
|
|
|
|
## Usage
|
|
|
|
This plugin acts as a data bucket component and does not provide a user interface. It is primarily intended for developers to call.
|
|
|
|
## API Usage
|
|
|
|
This plugin injects a global `window.AmilyDatabin` object into the client-side environment for simplified, granular data interaction.
|
|
|
|
**Architectural Note:** The `SourceType` constants table is dynamically managed via the `sourcetype.json` file. The client automatically fetches this configuration from the server upon loading, making the system extensible without requiring client-side code changes.
|
|
|
|
### `AmilyDatabin.SourceType`
|
|
|
|
A constants table used to define the source of the data.
|
|
|
|
```javascript
|
|
{
|
|
CHAT_LOG: 1, // For chat log storage
|
|
CHARACTER_CARD: 2, // For character card storage
|
|
WORLD_BOOK: 3 // For world book storage
|
|
}
|
|
```
|
|
|
|
### `AmilyDatabin.getData(source, fileName, objName = null)`
|
|
|
|
Retrieves specific data from the server. The `objName` is optional and will be auto-detected from the current context if omitted.
|
|
|
|
```javascript
|
|
/**
|
|
* Fetches specific data from the server.
|
|
* @param {number} source - The data source identifier (use AmilyDatabin.SourceType).
|
|
* @param {string} fileName - The file name or unique key for the data.
|
|
* @param {string} [objName=null] - Optional. The specific object name (e.g., character ID). If null, it's auto-detected. **Note: For `WORLD_BOOK` type, `objName` cannot be automatically detected and must be provided explicitly.**
|
|
* @returns {Promise<object|null>} A Promise that resolves to the requested data object, or null if not found.
|
|
*/
|
|
async function retrieveCurrentCharacterMemory() {
|
|
try {
|
|
// We omit objName, so the plugin will automatically use the current character's ID.
|
|
const memory = await window.AmilyDatabin.getData(
|
|
window.AmilyDatabin.SourceType.CHARACTER_CARD,
|
|
"character_memory.json"
|
|
);
|
|
|
|
if (memory) {
|
|
console.log("Retrieved current character memory:", memory);
|
|
} else {
|
|
console.log("No memory found for the current character.");
|
|
}
|
|
return memory;
|
|
} catch (error) {
|
|
console.error("Failed to retrieve data:", error);
|
|
return null;
|
|
}
|
|
}
|
|
|
|
// Example call for automatic context:
|
|
retrieveCurrentCharacterMemory();
|
|
```
|
|
|
|
### `AmilyDatabin.saveData(source, fileName, fileContent, objName = null)`
|
|
|
|
Saves a JavaScript object to a specific path on the server. The `objName` is optional.
|
|
|
|
```javascript
|
|
/**
|
|
* Saves a data object to a specific path on the server.
|
|
* @param {number} source - The data source identifier (use AmilyDatabin.SourceType).
|
|
* @param {string} fileName - The file name or unique key for the data.
|
|
* @param {object} fileContent - The JavaScript object to save.
|
|
* @param {string} [objName=null] - Optional. The specific object name. If null, it's auto-detected. **Note: For `WORLD_BOOK` type, `objName` cannot be automatically detected and must be provided explicitly.**
|
|
* @returns {Promise<boolean>} A Promise that resolves to true if successful, false otherwise.
|
|
*/
|
|
async function saveCurrentChatLog(chatHistory) {
|
|
try {
|
|
// objName is omitted here, it will be resolved to the current chat's ID automatically.
|
|
const success = await window.AmilyDatabin.saveData(
|
|
window.AmilyDatabin.SourceType.CHAT_LOG,
|
|
`log_${new Date().getTime()}.json`, // Example of a unique key
|
|
{ history: chatHistory, savedAt: new Date().toISOString() }
|
|
);
|
|
|
|
if (success) {
|
|
console.log("Chat log for current chat saved successfully.");
|
|
} else {
|
|
console.error("Failed to save chat log.");
|
|
}
|
|
return success;
|
|
} catch (error) {
|
|
console.error("Error during data saving:", error);
|
|
return false;
|
|
}
|
|
}
|
|
|
|
// Example call:
|
|
const currentChat = ["User: Hi!", "Character: Hello!"];
|
|
saveCurrentChatLog(currentChat);
|
|
```
|
|
|
|
### `AmilyDatabin.deleteData(source, fileName, objName = null)`
|
|
|
|
Deletes a specific data file from the server. The `objName` is optional.
|
|
|
|
```javascript
|
|
/**
|
|
* Deletes a specific data file from the server.
|
|
* @param {number} source - The data source identifier (use AmilyDatabin.SourceType).
|
|
* @param {string} [objName=null] - Optional. The specific object name. If null, it's auto-detected. **Note: For `WORLD_BOOK` type, `objName` cannot be automatically detected and must be provided explicitly.**
|
|
* @returns {Promise<boolean>} A Promise that resolves to true if successful, false otherwise.
|
|
*/
|
|
async function deleteCurrentCharacterMemory() {
|
|
try {
|
|
const success = await window.AmilyDatabin.deleteData(
|
|
window.AmilyDatabin.SourceType.CHARACTER_CARD,
|
|
"character_memory.json"
|
|
);
|
|
|
|
if (success) {
|
|
console.log("Successfully deleted current character memory.");
|
|
} else {
|
|
console.log("Failed to delete character memory.");
|
|
}
|
|
return success;
|
|
} catch (error) {
|
|
console.error("Failed to delete data:", error);
|
|
return false;
|
|
}
|
|
}
|
|
|
|
// Example call:
|
|
deleteCurrentCharacterMemory();
|
|
```
|
|
|
|
## Debug Methods
|
|
|
|
These methods are designed for quick debugging in the browser console. They do not interact with the backend API.
|
|
|
|
### `AmilyDatabin.getDebugInstance()`
|
|
|
|
Outputs the `AmilyDatabin` object itself to the console. Useful for inspecting its current state, `SourceType` map, and available methods.
|
|
|
|
```javascript
|
|
// Call in browser console:
|
|
AmilyDatabin.getDebugInstance();
|
|
// Expected output: { SourceType: { CHAT_LOG: 1, ... }, initialize: f, ... }
|
|
```
|
|
|
|
### `AmilyDatabin.getDebugChatId()`
|
|
|
|
Attempts to resolve the current chat ID using the same logic as the main API methods and logs it to the console.
|
|
|
|
```javascript
|
|
// Call in browser console:
|
|
AmilyDatabin.getDebugChatId();
|
|
// Expected output: [Amily-Databin] Current Chat ID (Debug): "your_chat_id_here"
|
|
```
|
|
|
|
### `AmilyDatabin.getDebugCardId()`
|
|
|
|
Attempts to resolve the current character card ID using the same logic as the main API methods and logs it to the console.
|
|
|
|
```javascript
|
|
// Call in browser console:
|
|
AmilyDatabin.getDebugCardId();
|
|
// Expected output: [Amily-Databin] Current Character Card ID (Debug): "your_character_id_here"
|
|
```
|
|
|
|
## Developer
|
|
|
|
The main logic is located in `index.js` (server-side) and `public/client.js` (client-side). The plugin registers itself with SillyTavern's extension API.
|
|
|
|
You can interact with this plugin via the global `window.AmilyDatabin` object directly.
|