楼层消息

getChatMessages

获取聊天消息。

酒馆虽然提供了 /messages 命令，但是它获取的是一整个字符串，并且不能获取楼层当前没在使用的消息 (点击箭头切换的那个 swipe 消息，在前端助手中我们称之为 "消息页"), 前端助手为此提供了一个函数获取更便于处理的消息。

getChatMessages

async function getChatMessages(
  range: string | number,
  option: GetChatMessagesOption = {}
): Promise<ChatMessage[]>;

GetChatMessagesOption

interface GetChatMessagesOption {
  role?: "all" | "system" | "assistant" | "user";
  hide_state?: "all" | "hidden" | "unhidden";
}

ChatMessage

interface ChatMessage {
  message_id: number;
  name: string;
  role: "system" | "assistant" | "user";
  is_hidden: boolean;

  swipe_id: number; // 当前被使用的消息页页号
  message: string; // 当前被使用的消息页文本
  data: Record<string, any>; // 当前被使用的消息页所绑定的数据

  swipes: string[];
  swipes_data: Record<string, any>[];
}

参数

range

• 类型: number | string
• 描述: 要获取的消息楼层号或楼层范围，与 /messages 相同

role?

• 类型: 'system' | 'assistant' | 'user'
• 描述: 按 role 筛选消息；默认为 'all'

hide_state?

• 类型: 'all' | 'hidden' | 'unhidden'
• 描述: 按是否被隐藏筛选消息；默认为 'all'

返回值

其获取到的结果是一个数组，数组的元素是每楼的消息 ChatMessage, 有以下内容，依据 message_id 从低到高排序：

• message_id: number
• name: string
• role: 'system' | 'assistant' | 'user'
• is_hidden: boolean
• swipe_id: number
• message: string
• data: Record<string, any>
• swipes: string[]
• swipes_data: Record<string, any>[]

示例

仅获取第 10 楼会被 ai 使用的消息页

const messages = await getChatMessages(10);
const messages = await getChatMessages("10");

获取所有楼层的所有消息页

const messages = await getChatMessages("0-{{lastMessageId}}");

setChatMessage

设置某消息楼层某聊天消息页的信息。

setChatMessage

async function setChatMessage(
  field_values: ChatMessageToSet,
  message_id: number,
  option: SetChatMessageOption = {}
): Promise<void>;

ChatMessageToSet

interface ChatMessageToSet {
  message?: string;
  data?: Record<string, any>;
}

SetChatMessageOption

interface SetChatMessageOption {
  swipe_id?: "current" | number;
  refresh?: "none" | "display_current" | "display_and_render_current" | "all";
}

参数

field_values

message?

• 类型: string
• 描述: 消息页要设置的消息文本

data?

• 类型: Record<string, any>
• 描述: 消息页要绑定的数据

message_id

• 类型: number
• 描述: 消息楼层 id

swipe_id?

• 类型: 'current' | number
• 描述: 要替换的消息页 ('current' 来替换当前使用的消息页，或从 0 开始的序号来替换对应消息页), 如果消息中还没有该消息页，则会创建该页; 默认为 'current'

refresh?

• 类型: 'none' | 'display_current' | 'display_and_render_current' | 'all'
• 描述: 是否更新页面的显示和 iframe 渲染，只会更新已经被加载显示在网页的楼层，更新显示时会触发被更新楼层的 "仅格式显示" 正则; 默认为 'display_and_render_current'
  • 'none': 不更新页面的显示和 iframe 渲染
  • 'display_current': 仅更新当前被替换楼层的显示，如果替换的是没被使用的消息页，则会自动切换为使用那一页
  • 'display_and_render_current': 与 display_current 相同，但还会重新渲染该楼的 iframe
  • 'all': 重新载入整个聊天消息，将会触发 tavern_events.CHAT_CHANGED 进而重新加载全局脚本和楼层消息

示例

设置楼层 5 的文本

await setChatMessage({ message: "设置楼层 5 当前消息页的文本" }, 5);
await setChatMessage(
  { message: "设置楼层 5 第 3 页的文本，更新为显示它并渲染其中的 iframe" },
  5,
  { swipe_id: 3 }
);
await setChatMessage(
  { message: "设置楼层 5 第 3 页的文本，但不更新显示它" },
  5,
  { swipe_id: 3, refresh: "none" }
);

为楼层 5 当前消息页绑定数据

await setChatMessage({data: {神乐光好感度： 5}}, 5);
await setChatMessage("这是要设置在楼层 5 的消息，它会替换该楼当前使用的消息", 5);
await setChatMessage("这是要设置在楼层 5 第 3 页的消息，更新为显示它并渲染其中的 iframe", 5, {swipe_id: 3});
await setChatMessage("这是要设置在楼层 5 第 3 页的消息，但不更新显示它", 5, {swipe_id: 3, refresh: 'none'});

注意

如果设置了当前会被发送给 ai 的消息文本 (正被使用且没被隐藏的消息页文本), 则 "仅格式提示词" 正则将会使用它而不是原来的消息。

formatAsDisplayedMessage

将字符串处理为酒馆用于显示的 html 格式。

1. 替换字符串中的酒馆宏
2. 对字符串应用对应的酒馆正则
3. 将字符串调整为 html 格式

formatAsDisplayedMessage

async function formatAsDisplayedMessage(
  text: string,
  option: FormatAsDisplayedMessageOption = {}
): Promise<string>;

FormatAsDisplayedMessageOption

interface FormatAsDisplayedMessageOption {
  message_id?: "last" | "last_user" | "last_char" | number; // 消息所在的楼层，要求该楼层已经存在，即在 `[0, await getLastMessageId()]` 范围内; 默认为 'last'
}

参数

text

• 类型: string
• 描述: 要处理的字符串

message_id?

• 类型: 'last' | 'last_user' | 'last_char' | number
• 描述: 消息所在的楼层，要求该楼层已经存在，即在 [0, await getLastMessageId()] 范围内; 默认为 'last'

返回值

• 处理结果: string

示例

const text = await formatAsDisplayedMessage(
  "{{char}} speaks in {{lastMessageId}}"
);
text == "<p>少女歌剧 speaks in 5</p>";

retrieveDisplayedMessage

获取消息楼层号对应的消息内容 JQuery。

相比于一个实用函数，这更像是一个告诉你可以这样用 JQuery 的示例。

function retrieveDisplayedMessage(message_id: number): JQuery<HTMLDivElement> {
  return $(`div.mes[mesid = "${message_id}"]`, window.parent.document).find(
    `div.mes_text`
  );
}

参数

message_id

• 类型: number
• 描述: 要获取的消息楼层号，必须要酒馆页面显示了该消息楼层才能获取到

返回值

• 对应的JQuery: 如果能获取到该消息楼层的 html, 则返回对应的 JQuery; 否则返回空 JQuery

示例

获取第 0 楼的消息内容文本

const text = retrieveDisplayedMessage(0).text();

修改第 0 楼的消息内容文本

// 这样的修改只会影响本次显示，不会保存到消息文件中，因此重新加载消息或刷新网页等操作后就会回到原样;
// 如果需要实际修改消息文件，请使用 `setChatMessage`
retrieveDisplayedMessage(0).text("new text");
retrieveDisplayedMessage(0).append("<pre>new text</pre>");
retrieveDisplayedMessage(0).append(
  formatAsDisplayedMessage("{{char}} speaks in {{lastMessageId}}")
);