update by Silence_Lurker
Init plugin
This commit is contained in:
192
README_en.md
Normal file
192
README_en.md
Normal file
@@ -0,0 +1,192 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user