获取角色卡信息

getCharCardData

根据角色卡的名称获取对应角色卡信息。

typescript

async function getCharData(name: string, allowAvatar: boolean = false): Promise<v1CharData>;

typescript

/**
 * @typedef {object} v1CharData
 * @property {string} name - 角色卡名称
 * @property {string} description - 角色卡描述
 * @property {string} personality - 角色卡个性
 * @property {string} scenario - 角色卡背景
 * @property {string} first_mes - 角色卡开场白
 * @property {string} mes_example - 角色卡对话示例
 * @property {string} creator_notes - 角色卡创建者备注
 * @property {string[]} tags - 角色卡标签
 * @property {number} talkativeness - 角色卡话痨程度
 * @property {boolean|string} fav - 角色卡是否被收藏
 * @property {string} create_date - 角色卡创建日期
 * @property {v2CharData} data - v2角色卡数据扩展
 * // v2CharData为非标准扩展，由ST服务器添加（不是原始数据的一部分）
 * @property {string} chat - 当前聊天文件名
 * @property {string} avatar - 角色卡头像文件名
 * @property {string} json_data - 角色卡原始JSON数据
 */

typescript

/**
 * @typedef {object} v2CharData
 * @property {string} name - 角色卡名称
 * @property {string} description - 角色卡描述
 * @property {string} character_version - 角色卡版本
 * @property {string} personality - 角色卡个性
 * @property {string} scenario - 角色卡背景
 * @property {string} first_mes - 角色卡开场白
 * @property {string} mes_example - 角色卡对话示例
 * @property {string} creator_notes - 角色卡创建者备注
 * @property {string[]} tags - 角色卡标签
 * @property {string} system_prompt - 角色卡系统提示覆盖
 * @property {string} post_history_instructions - 角色卡越狱提示词覆盖
 * @property {string} creator - 角色卡创建者
 * @property {string[]} alternate_greetings - 可选开场白
 * @property {v2WorldInfoBook} character_book - 角色卡世界信息
 * @property {v2CharDataExtensionInfos} extensions - 角色卡扩展信息
 */

typescript

/**
 * @typedef {object} v2CharDataExtensionInfos
 * @property {number} talkativeness - 角色卡发言频率
 * @property {boolean} fav - 角色卡是否被收藏
 * @property {string} world - 角色卡所在虚构世界或设定（如果适用）
 * @property {object} depth_prompt - 用于角色卡中的角色备注深度提示词
 * @property {number} depth_prompt.depth - 角色备注提示词深度
 * @property {string} depth_prompt.prompt - 用于角色备注的实际提示词内容
 * @property {"system" | "user" | "assistant"} depth_prompt.role - 角色备注深度提示词的role（system, user, or assistant）
 * @property {RegexScriptData[]} regex_scripts - 角色卡自定义正则表达式脚本
 * // 非标准扩展，由外部工具添加
 * @property {string} [pygmalion_id] - 由Pygmalion.chat分配给角色的唯一标识
 * @property {string} [github_repo] - 与角色关联的GitHub仓库
 * @property {string} [source_url] - 与角色关联的源URL
 * @property {{full_path: string}} [chub] - 与角色关联的Chub数据
 * @property {{source: string[]}} [risuai] - 与角色关联的RisuAI数据
 */

typescript

/**
* @typedef {object} RegexScriptData
* @property {string} id - 脚本的UUID
* @property {string} scriptName - 脚本的名称
* @property {string} findRegex - 要查找的正则表达式
* @property {string} replaceString - 要替换的字符串
* @property {string[]} trimStrings - 要修剪的字符串
* @property {number[]} placement - 脚本的位置
* @property {boolean} disabled - 是否禁用脚本
* @property {boolean} markdownOnly - 是否仅适用于Markdown
* @property {boolean} promptOnly - 是否仅适用于提示词
* @property {boolean} runOnEdit - 是否在编辑时运行
* @property {boolean} substituteRegex - 是否应该替换正则表达式
* @property {number} minDepth - 最小深度
* @property {number} maxDepth - 最大深度
*/

typescript

/**
 * @typedef {object} v2WorldInfoBook
 * @property {string} name - 世界书名称
 * @property {v2DataWorldInfoEntry[]} entries - 世界书中的条目
 */

typescript

/**
 * @typedef {object} v2DataWorldInfoEntry
 * @property {string[]} keys - 条目主键
 * @property {string[]} secondary_keys - 条目次键
 * @property {string} comment - 条目注释
 * @property {string} content - 条目内容
 * @property {boolean} constant - 条目内容是否固定且不可更改
 * @property {boolean} selective - 条目内容是否受特定条件控制
 * @property {number} insertion_order - 条目在处理过程中的插入顺序
 * @property {boolean} enabled - 控制条目是否当前活跃并使用
 * @property {string} position - 指定条目适用的位置或上下文
 * @property {v2DataWorldInfoEntryExtensionInfos} extensions - 条目扩展信息
 * @property {number} id - 条目的唯一标识
 */

typescript

/**
 * @typedef {object} v2DataWorldInfoEntryExtensionInfos
 * @property {number} position - 条目的深度位置
 * @property {boolean} exclude_recursion - 防止条目递归应用
 * @property {number} probability - 条目应用的概率（0到1之间）
 * @property {boolean} useProbability - 确定是否使用`probability`属性
 * @property {number} depth - 递归应用条目的最大级别
 * @property {number} selectiveLogic - 定义用于确定是否选择性地应用条目的逻辑
 * @property {string} group - 条目的类别或分组
 * @property {boolean} group_override - 覆盖任何现有条目组的分配
 * @property {number} group_weight - 用于优先处理同一组中的条目
 * @property {boolean} prevent_recursion - 完全禁止递归应用条目
 * @property {boolean} delay_until_recursion - 仅在递归期间检查
 * @property {number} scan_depth - 在应用条目时搜索匹配的最大深度
 * @property {boolean} match_whole_words - 指定是否仅在整个单词上进行匹配
 * @property {boolean} use_group_scoring - 是否考虑组权重
 * @property {boolean} case_sensitive - 是否区分大小写
 * @property {string} automation_id - 自动化标识
 * @property {number} role - 条目角色
 * @property {boolean} vectorized - 是否向量化
 * @property {number} display_index - 显示顺序
 */

参数

`name?`

类型: string
描述: 角色卡的名称，如果未提供，则返回当前打开的角色卡信息

`allowAvatar?`

类型: boolean
描述: 是否将name视为准确的头像文件名进行查找，用于存在同名角色卡的情况；默认为 false

返回值

角色卡数据: v1CharData - 包含角色卡信息的对象

示例

获取当前打开的角色卡信息获取指定角色卡信息知晓准确头像文件名并用于查找

typescript

const charData = await getCharData();
console.log(charData);

typescript

const charData = await getCharData("少女歌剧");
console.log(charData);

typescript

const charDataWithAvatar = await getCharData("少女歌剧2.png", true);
console.log(charDataWithAvatar);

getCharAvatarPath

获取角色头像的URL路径。

typescript

async function getCharAvatarPath(name: string, allowAvatar: boolean = false): Promise<string>;

参数

`name?`

类型: string
描述: 角色卡的名称，如果未提供，则返回当前打开的角色卡信息

`allowAvatar?`

类型: boolean
描述: 是否将name视为准确的头像文件名进行查找，用于存在同名角色卡的情况；默认为 false

返回值

头像路径: string - 角色头像的URL路径信息，可直接用于img标签的src属性

示例

typescript

const avatarPath = await getCharAvatarPath("少女歌剧");
console.log(avatarPath);

getChatHistoryBrief

获取与角色的聊天历史概要信息。

getChatHistoryBriefChatHistoryBrief

typescript

async function getChatHistoryBrief(name: string, allowAvatar: boolean = false): Promise<ChatHistoryBrief[]>;

typescript

interface ChatHistoryBrief{
  chat_item: number; // 楼层总数
  file_name: string;
  file_size: string;
  last_mes: string; // 最后一条消息的时间
  mes: string; // 最后一条消息的内容
}

参数

`name?`

类型: string
描述: 角色卡的名称，如果未提供，则返回当前打开的角色卡信息

`allowAvatar?`

类型: boolean
描述: 是否将name视为准确的头像文件名进行查找，用于存在同名角色卡的情况；默认为 false

返回值

聊天历史概要: ChatHistoryBrief[] - 包含聊天历史概要信息的数组

示例

typescript

const historyBrief = await getChatHistoryBrief("少女歌剧");
console.log(historyBrief);

getChatHistoryDetail

根据聊天文件名，获取详细的聊天历史信息。

通常是使用从 getChatHistoryBrief 获取的结果。

getChatHistoryDetailChatHistoryDetail

typescript

async function getChatHistoryDetail(data: any[], isGroupChat: boolean = false): Promise<Record<string, ChatHistoryDetail[]>>;

typescript

interface ChatHistoryDetail {
  name: string;        // 发送者名称
  is_user: boolean;    // 是否用户发送的消息
  is_system: boolean;  // 是否系统消息
  send_date: string;   // 消息发送日期时间
  mes: string;         // 消息内容
  extra: {             // 额外信息
    bias: string;         // 消息偏置设置
  };
  swipe_id: number;    // 当前选中的swipe索引
  swipes: string[];    // 可选择的消息内容数组
  swipe_info: any[];   // swipe相关信息
  // 可能存在扩展引入的额外字段
}

参数

`data`

类型: any[]
描述: 聊天历史数据，通常是从 getChatHistoryBrief 获取的结果，也可以是其他数据，但必须包含 file_name 字段

`isGroupChat?`

类型: boolean
描述: 指定是否获取群聊的历史记录；默认为 false

返回值

聊天历史详情: Promise<Record<string, ChatHistoryDetail[]>> - 返回一个对象，其中键是聊天文件名，值是包含聊天消息的数组

注意

getChatHistoryDetail 根据 file_name 来获取头像名，因此不支持存在多个同名角色卡时，对聊天记录的精确获取，函数将始终返回最早创建的角色卡的聊天记录。

示例

获取某一角色卡的聊天历史获取多个角色卡的聊天历史

typescript

const historyBrief = await getChatHistoryBrief("少女歌剧");
const historyDetail = await getChatHistoryDetail(historyBrief);

typescript

const charNames = ["少女歌剧", "舞台少女"];
const allHistoryBriefs = [];

for (const name of charNames) {
  const historyBrief = await getChatHistoryBrief(name);
  allHistoryBriefs.push(...historyBrief);
}

const historyDetail = await getChatHistoryDetail(allHistoryBriefs);

获取角色卡信息 ​

getCharCardData ​

参数 ​

name? ​

allowAvatar? ​

返回值 ​

示例 ​

getCharAvatarPath ​

参数 ​

name? ​

allowAvatar? ​

返回值 ​

示例 ​

getChatHistoryBrief ​

参数 ​

name? ​

allowAvatar? ​

返回值 ​

示例 ​

getChatHistoryDetail ​

参数 ​

data ​

isGroupChat? ​

返回值 ​

示例 ​

获取角色卡信息

getCharCardData

参数

`name?`

`allowAvatar?`

返回值

示例

getCharAvatarPath

参数

`name?`

`allowAvatar?`

返回值

示例

getChatHistoryBrief

参数

`name?`

`allowAvatar?`

返回值

示例

getChatHistoryDetail

参数

`data`

`isGroupChat?`

返回值

示例