UI 扩展

/**
 * Import a member from a module by URL, bypassing webpack.
 * @param {string} url URL to import from
 * @param {string} what Name of the member to import
 * @param {any} defaultValue Fallback value
 * @returns {Promise<any>} Imported member
 */
export async function importFromUrl(url, what, defaultValue = null) {
    try {
        const module = await import(/* webpackIgnore: true */ url);
        if (!Object.hasOwn(module, what)) {
            throw new Error(`No ${what} in module`);
        }
        return module[what];
    } catch (error) {
        console.error(`Failed to import ${what} from ${url}: ${error}`);
        return defaultValue;
     }
}

// Import a function from 'script.js' module
const generateRaw = await importFromUrl('/script.js', 'generateRaw');

{
    "display_name": "The name of the extension",
    "loading_order": 1,
    "requires": [],
    "optional": [],
    "dependencies": [],
    "js": "index.js",
    "css": "style.css",
    "author": "Your name",
    "version": "1.0.0",
    "homePage": "https://github.com/your/extension",
    "auto_update": true,
    "minimum_client_version": "1.0.0",
    "i18n": {
        "de-de": "i18n/de-de.json"
    },
    "hooks": {
        "install": "onInstall",
        "update": "onUpdate",
        "delete": "onDelete",
        "enable": "onEnable",
        "disable": "onDisable",
        "activate": "onActivate"
    }
}

const context = SillyTavern.getContext();
context.chat; // 聊天记录 - 可变对象
context.characters; // 角色列表
context.characterId; // 当前角色的索引
context.groups; // 群组列表
context.groupId; // 当前群组的 ID
// 以及更多...

const { DOMPurify } = SillyTavern.libs;

const sanitizedHtml = DOMPurify.sanitize('<script>"dirty HTML"</script>');

export {};

// 1. 为用户范围扩展的导入
import '../../../../public/global';
// 2. 为服务器范围扩展的导入
import '../../../../global';

// 如需定义其他类型...
declare global {
    // 在此添加全局类型声明
}

const { renderExtensionTemplateAsync } = SillyTavern.getContext();

// 使用给定数据渲染 'third-party/my-extension/settings.html'
const settingsHtml = await renderExtensionTemplateAsync(
    'third-party/my-extension',
    'settings',
    { title: 'My Extension', version: '1.0', defaultValue: 'test' }
);

// 追加到扩展设置面板
$('#extensions_settings2').append(settingsHtml);

<div class="my-extension-settings">
    <div class="inline-drawer">
        <div class="inline-drawer-toggle inline-drawer-header">
            <b data-i18n="{{title}}">{{title}}</b>
            <div class="inline-drawer-icon fa-solid fa-circle-chevron-down down"></div>
        </div>
        <div class="inline-drawer-content">
            <label for="my_ext_option">
                <span data-i18n="Option">Option</span>
            </label>
            <input id="my_ext_option" type="text" value="{{defaultValue}}" />
        </div>
    </div>
</div>

import { generateQuietPrompt } from "../../../../script.js";

async function handleMessage(data) {
    const text = data.message;
    const translated = await generateQuietPrompt({ quietPrompt: text });
    // ...
}

const { extensionSettings, saveSettingsDebounced } = SillyTavern.getContext();

// 为你的扩展定义一个唯一标识符
const MODULE_NAME = 'my_extension';

// 定义默认设置
const defaultSettings = Object.freeze({
    enabled: false,
    option1: 'default',
    option2: 5
});

// 定义一个获取或初始化设置的函数
function getSettings() {
    // 如果设置不存在则初始化
    if (!extensionSettings[MODULE_NAME]) {
        extensionSettings[MODULE_NAME] = structuredClone(defaultSettings);
    }

    // 确保所有默认键都存在（更新后很有用）
    for (const key of Object.keys(defaultSettings)) {
        if (!Object.hasOwn(extensionSettings[MODULE_NAME], key)) {
            extensionSettings[MODULE_NAME][key] = defaultSettings[key];
        }
    }

    return extensionSettings[MODULE_NAME];
}

// 使用设置
const settings = getSettings();
settings.option1 = 'new value';

// 保存设置
saveSettingsDebounced();

const { chatMetadata, saveMetadata } = SillyTavern.getContext();

// 为当前聊天设置一些元数据
chatMetadata['my_key'] = 'my_value';

// 获取当前聊天的元数据
const value = chatMetadata['my_key'];

// 将元数据保存到服务器
await saveMetadata();

const { writeExtensionField, characterId } = SillyTavern.getContext();

// 向角色卡写入一些数据
await writeExtensionField(characterId, 'my_extension_key', {
    someData: 'value',
    anotherData: 42
});

// 从角色卡读回数据
const character = SillyTavern.getContext().characters[characterId];
// 数据存储在角色数据的 `extensions` 对象中
const myData = character.data?.extensions?.my_extension_key;

const { getPresetManager } = SillyTavern.getContext();

// 获取当前 API 类型的预设管理器
const pm = getPresetManager();

// 向预设扩展字段写入数据：
// - path: 预设数据中字段的路径
// - value: 要写入的值
// - name（可选）: 要写入的预设名称，默认为当前选定的预设
await pm.writePresetExtensionField({ path: 'hello', value: 'world' });

// 从预设扩展字段读取数据：
// - path: 预设数据中字段的路径
// - name（可选）: 要读取的预设名称，默认为当前选定的预设
const value = pm.readPresetExtensionField({ path: 'hello' });

SillyTavern.getContext().addLocaleData('fr-fr', { 'Hello': 'Bonjour' });
SillyTavern.getContext().addLocaleData('de-de', { 'Hello': 'Hallo' });

{
  "display_name": "Foobar",
  "js": "index.js",
  // 其他字段...
  "i18n": {
    "fr-fr": "i18n/french.json",
    "de-de": "i18n/german.json"
  }
}

SlashCommandParser.addCommandObject(SlashCommand.fromProps({ name: 'repeat',
    callback: (namedArgs, unnamedArgs) => {
        return Array(namedArgs.times ?? 5)
            .fill(unnamedArgs.toString())
            .join(isTrueBoolean(namedArgs.space.toString()) ? ' ' : '')
        ;
    },
    aliases: ['example-command'],
    returns: 'the repeated text',
    namedArgumentList: [
        SlashCommandNamedArgument.fromProps({ name: 'times',
            description: 'number of times to repeat the text',
            typeList: ARGUMENT_TYPE.NUMBER,
            defaultValue: '5',
        }),
        SlashCommandNamedArgument.fromProps({ name: 'space',
            description: 'whether to separate the texts with a space',
            typeList: ARGUMENT_TYPE.BOOLEAN,
            defaultValue: 'off',
            enumList: ['on', 'off'],
        }),
    ],
    unnamedArgumentList: [
        SlashCommandArgument.fromProps({ description: 'the text to repeat',
            typeList: ARGUMENT_TYPE.STRING,
            isRequired: true,
        }),
    ],
    helpString: `
        <div>
            Repeats the provided text a number of times.
        </div>
        <div>
            <strong>Example:</strong>
            <ul>
                <li>
                    <pre><code class="language-stscript">/repeat foo</code></pre>
                    returns "foofoofoofoofoo"
                </li>
                <li>
                    <pre><code class="language-stscript">/repeat times=3 space=on bar</code></pre>
                    returns "bar bar bar"
                </li>
            </ul>
        </div>
    `,
}));

const { eventSource, event_types } = SillyTavern.getContext();

eventSource.on(event_types.MESSAGE_RECEIVED, handleIncomingMessage);

function handleIncomingMessage(data) {
    // 处理消息
}

const { eventSource } = SillyTavern.getContext();

// 可以是内置的 event_types 字段，也可以是任意字符串。
const eventType = 'myCustomEvent';

// 使用 `await` 确保所有事件处理程序在继续执行前完成。
await eventSource.emit(eventType, { data: 'custom event data' });

{
    "display_name": "My Interceptor Extension",
    "loading_order": 10, // 影响执行顺序
    "generate_interceptor": "myCustomInterceptorFunction",
    // ... 其他清单属性
}

globalThis.myCustomInterceptorFunction = async function(chat, contextSize, abort, type) {
    // 示例：在最后一条用户消息之前添加一条系统说明
    const systemNote = {
        is_user: false,
        name: "System Note",
        send_date: Date.now(),
        mes: "This was added by my extension!"
    };
    // 在最后一条消息之前插入
    chat.splice(chat.length - 1, 0, systemNote);
}

{
    "display_name": "My Extension",
    "js": "index.js",
    // 其他字段...
    "hooks": {
        "install": "onInstall",
        "update": "onUpdate",
        "delete": "onDelete",
        "enable": "onEnable",
        "disable": "onDisable",
        "activate": "onActivate",
        "clean": "onClean"
    }
}

// index.js - 你的扩展入口点

export async function onInstall() {
    console.log('Extension installed! Performing first-time setup...');
    // 例如：初始化默认数据、创建存储条目
}

export async function onActivate() {
    console.log('Extension activated during page load');
}

export async function onUpdate() {
    console.log('Extension updated! Running migrations...');
    // 例如：将数据从旧格式迁移到新格式
}

export async function onDelete() {
    console.log('Extension about to be deleted. Cleaning up...');
    // 例如：删除存储的数据、清理 localStorage
    const { localforage } = SillyTavern.libs;
    await localforage.removeItem('my_extension_data');
}

export function onEnable() {
    console.log('Extension enabled');
}

export function onDisable() {
    console.log('Extension disabled');
}

export async function onClean() {
    console.log('Extension data cleaned');
    // 例如：在此处清理扩展数据
}

const { generateQuietPrompt } = SillyTavern.getContext();

const quietPrompt = 'Generate a summary of the chat history.';

const result = await generateQuietPrompt({
    quietPrompt,
});

const { generateRaw } = SillyTavern.getContext();

const systemPrompt = 'You are a helpful assistant.';
const prompt = 'Generate a story about a brave knight.';
const prefill = 'Once upon a time,';

/*
在 Chat Completion 模式下，将生成如下提示词：
[
  {role: 'system', content: 'You are a helpful assistant.'},
  {role: 'user', content: 'Generate a story about a brave knight.'},
  {role: 'assistant', content: 'Once upon a time,'}
]
*/

/*
在 Text Completion 模式下（无指令格式），将生成如下提示词：
"You are a helpful assistant.\nGenerate a story about a brave knight.\nOnce upon a time,"
*/

const result = await generateRaw({
    systemPrompt,
    prompt,
    prefill,
});

const { generateRaw, generateQuietPrompt } = SillyTavern.getContext();

// 为预期输出定义 JSON schema
const jsonSchema = {
    // 必填：schema 的名称
    name: 'StoryStateModel',
    // 可选：schema 的描述
    description: 'A schema for a story state with location, plans, and memories.',
    // 可选：schema 将以严格模式使用，意味着只允许 schema 中定义的字段
    strict: true,
    // 必填：schema 的定义
    value: {
        '$schema': 'http://json-schema.org/draft-04/schema#',
        'type': 'object',
        'properties': {
            'location': {
                'type': 'string'
            },
            'plans': {
                'type': 'string'
            },
            'memories': {
                'type': 'string'
            }
        },
        'required': [
            'location',
            'plans',
            'memories'
        ],
    },
};

const prompt = 'Generate a story state with location, plans, and memories. Output as a JSON object.';

const rawResult = await generateRaw({
    prompt,
    jsonSchema,
});

const quietResult = await generateQuietPrompt({
    quietPrompt: prompt,
    jsonSchema,
});

const { macros } = SillyTavern.getContext();

// 带处理函数的简单宏
macros.register('tomorrow', {
    description: 'Returns tomorrow\'s date',
    handler: () => {
        return new Date(Date.now() + 24 * 60 * 60 * 1000).toLocaleDateString();
    },
});

// 带无名参数和分类的宏
macros.register('greet', {
    description: 'Generates a greeting for the given name',
    category: macros.category.UTILITY,
    unnamedArgs: [
        { name: 'name', description: 'The name to greet' },
    ],
    handler: ({ unnamedArgs }) => {
        const [name] = unnamedArgs;
        return `Hello, ${name}!`;
    },
});

const { macros } = SillyTavern.getContext();

macros.registry.unregisterMacro('greet');

const { macros } = SillyTavern.getContext();

macros.registerAlias('greet', 'hello', { visible: true });

const { registerMacro, unregisterMacro } = SillyTavern.getContext();

// 简单字符串宏
registerMacro('fizz', 'buzz');
// 函数宏（必须是同步的）
registerMacro('tomorrow', () => {
    return new Date(Date.now() + 24 * 60 * 60 * 1000).toLocaleDateString();
});

// 取消注册
unregisterMacro('fizz');

const { messageFormatter } = SillyTavern.getContext();

// 简单钩子 - 转换消息文本
messageFormatter.addHook((mes, ctx) => {
    // 跳过用户消息
    if (ctx.isUser) return mes;

    // 为日文文本添加振假名
    return addFurigana(mes);
});

// 带有明确阶段和顺序的钩子
messageFormatter.addHook((mes, ctx) => {
    // 在 Markdown 转换后、净化前进行转换
    return mes.replace(/\*\*(.+?)\*\*/g, '<mark>$1</mark>');
}, {
    stage: messageFormatter.stage.AFTER_MARKDOWN,
    order: messageFormatter.order.EARLY,
});

const { hook_order } = messageFormatter;

// 预定义常量
hook_order.EARLIEST;  // 0
hook_order.EARLY;     // 10
hook_order.NORMAL;    // 50（默认值）
hook_order.LATE;      // 90
hook_order.LATEST;    // 100

// 自定义数值
messageFormatter.addHook(myHook, { order: 25 });

const { registerFunctionTool } = SillyTavern.getContext();

registerFunctionTool({
    name: 'get_weather',
    displayName: 'Get Weather',
    description: 'Get the current weather for a given location',
    parameters: {
        $schema: 'http://json-schema.org/draft-04/schema#',
        type: 'object',
        properties: {
            location: { type: 'string', description: 'City name' },
        },
        required: ['location'],
    },
    action: async ({ location }) => {
        const data = await fetchWeatherData(location);
        return JSON.stringify(data);
    },
});

const { loader } = SillyTavern.getContext();

// 基本阻塞加载器，带有可停止的通知提示
const handle = loader.show({ message: 'Processing data...' });
try {
    const result = await someExpensiveOperation();
} finally {
    await handle.hide();
}

const { loader } = SillyTavern.getContext();

const loader1 = loader.show({ message: 'Task 1...' });
const loader2 = loader.show({ message: 'Task 2...' });
await loader1.hide(); // 覆盖层保持——loader2 仍在活动
await loader2.hide(); // 现在覆盖层隐藏

const { loader } = SillyTavern.getContext();

const handle = loader.show({
    blocking: false,
    message: 'Downloading in background...',
    onStop: () => abortDownload(),
});

const { Popup } = SillyTavern.getContext();

// 确认对话框——返回 POPUP_RESULT.AFFIRMATIVE 或 POPUP_RESULT.NEGATIVE
const confirmed = await Popup.show.confirm('Confirm Action', 'Are you sure you want to proceed?');

// 文本输入对话框——返回输入的字符串，取消则返回 null
const userInput = await Popup.show.input('Enter Name', 'Please provide a name:', 'default value');

// 信息显示——返回点击的按钮结果
await Popup.show.text('Info', 'Operation completed successfully.');

const { Popup, POPUP_TYPE, POPUP_RESULT } = SillyTavern.getContext();

const popup = new Popup(
    '<div>Custom HTML content here</div>',
    POPUP_TYPE.TEXT,
    '',
    {
        wide: true,              // 宽屏显示模式
        okButton: 'Save',       // 自定义确认按钮文本
        cancelButton: 'Discard', // 自定义取消按钮文本
        customButtons: [
            {
                text: 'Export',
                icon: 'fa-download',
                result: POPUP_RESULT.CUSTOM1,
            },
        ],
        customInputs: [
            {
                id: 'my_checkbox',
                label: 'Enable feature',
                type: 'checkbox',
                defaultState: false,
            },
        ],
        allowVerticalScrolling: true,
    }
);

const result = await popup.show();

if (result === POPUP_RESULT.AFFIRMATIVE) {
    // 点击了确认
} else if (result === POPUP_RESULT.CUSTOM1) {
    // 点击了导出按钮
}

// 读取自定义输入值
const checkboxValue = popup.inputResults?.get('my_checkbox');

toastr.success('Data saved successfully');
toastr.error('Failed to connect to API');
toastr.warning('This feature is experimental');
toastr.info('Processing...');

const { registerDataBankScraper } = SillyTavern.getContext();

await registerDataBankScraper({
    id: 'my_scraper',
    name: 'My Data Source',
    description: 'Import data from My Data Source',
    iconClass: 'fa-solid fa-database',
    iconAvailable: true,
    isAvailable: async () => true,
    scrape: async () => {
        // 返回 File 对象数组
        const content = await fetchDataFromSource();
        return [new File([content], 'data.txt', { type: 'text/plain' })];
    },
});

const { registerDebugFunction } = SillyTavern.getContext();

registerDebugFunction(
    'my_ext_clear_cache',        // 唯一函数 ID
    'Clear My Extension Cache',   // 显示名称
    'Clears all cached data for My Extension', // 描述
    async () => {
        const { localforage } = SillyTavern.libs;
        await localforage.removeItem('my_extension_cache');
        toastr.success('Cache cleared');
    }
);

import { getApiUrl, doExtrasFetch } from "../../extensions.js";

const url = new URL(getApiUrl());
url.pathname = '/api/summarize';

const apiResult = await doExtrasFetch(url, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Bypass-Tunnel-Reminder': 'bypass',
    },
    body: JSON.stringify({
        // 请求体
    })
});

// 错误做法——请勿这样做！
extensionSettings[MODULE_NAME].apiKey = 'secret_key_123';

// 注意：没有安全的方式在客户端扩展中存储机密信息。
// 如果需要处理敏感数据，请改用服务器插件。
// 参见：https://docs.sillytavern.app/for-contributors/server-plugins/

// 先验证输入类型
if (typeof userInput !== 'string') {
    toastr.error('Invalid input type');
    return;
}
// 使用 DOMPurify 净化 HTML 输入
const { DOMPurify } = SillyTavern.libs;
const cleanInput = DOMPurify.sanitize(userInput);

// 错误做法——不要存储大量数据
extensionSettings[MODULE_NAME].largeDataset = { /* 数 MB 的数据 */ };

// 正确做法——使用 localforage（IndexedDB/localStorage 的抽象层）
const { localforage } = SillyTavern.libs;
await localforage.setItem(`${MODULE_NAME}_data`, largeData);

// 或者使用 localStorage 存储较小的数据
localStorage.setItem(`${MODULE_NAME}_data`, JSON.stringify(smallData));

function cleanup() {
    eventSource.removeListener(event_types.MESSAGE_RECEIVED, handleMessage);
    document.getElementById('myElement').removeEventListener('click', handleClick);
}

// 对 I/O 操作使用 async
async function processData() {
    const result = await fetch('/api/process');
    return result.json();
}

// 拆分繁重的计算任务
async function heavyComputation(data) {
    for (let i = 0; i < data.length; i++) {
        // 处理数据块
        if (i % 1000 === 0) {
            await new Promise(resolve => setTimeout(resolve, 0)); // 让出 UI 控制权
        }
    }
}

// 正确做法——稳定的 API
const { chat, characters, saveSettingsDebounced } = SillyTavern.getContext();

// 应避免——可能随内部变更而失效
import { chat, characters } from '../../../../script.js';

// 正确做法——具体且唯一
const MODULE_NAME = 'my_extension_name';

// 错误做法——过于通用，容易冲突
const MODULE_NAME = 'settings';

const MODULE_NAME = 'MyExtension';

console.log(`[${MODULE_NAME}] Extension loaded`);
console.debug(`[${MODULE_NAME}] Processing data:`, data);
console.error(`[${MODULE_NAME}] Error occurred:`, error);

function loadSettings() {
    // 与默认值合并，以处理更新后的新键并在不存在时初始化。
    extensionSettings[MODULE_NAME] = SillyTavern.libs.lodash.merge(
        structuredClone(defaultSettings),
        extensionSettings[MODULE_NAME]
    );
}