fast-tavern 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,462 @@
+type View = 'user_view' | 'model_view';
+type Target = 'preset' | 'world_book' | 'chat_history' | 'model' | 'user';
+/** 统一的消息角色（引擎内部保留 system） */
+type Role = 'system' | 'user' | 'model';
+interface RegexRule {
+    id: string;
+    name: string;
+    enabled: boolean;
+    mode: 'always' | 'conditional';
+    find_regex: string;
+    replace_regex: string;
+    targets: ('preset' | 'world_book' | 'chat_history' | 'assistant_response' | 'model' | 'user')[];
+    views: (View | 'assistant_view')[];
+    placement: 'before_macro' | 'after_macro';
+    description?: string;
+    min_depth?: number;
+    max_depth?: number;
+}
+type WorldbookPosition = 'before_char' | 'after_char' | 'fixed';
+/**
+ * 世界书条目（输入）
+ * - role 可省略（默认 user）
+ * - 只有 position=fixed 才需要 depth
+ */
+type WorldbookEntryInput = {
+    id: string;
+    name: string;
+    enabled: boolean | null;
+    mode: 'always' | 'conditional';
+    content: string;
+    role?: Role;
+    position: 'before_char' | 'after_char';
+    order: number;
+    condition?: string;
+    /** slot 条目不使用 depth */
+    depth?: never;
+} | {
+    id: string;
+    name: string;
+    enabled: boolean | null;
+    mode: 'always' | 'conditional';
+    content: string;
+    role?: Role;
+    position: 'fixed';
+    order: number;
+    /** fixed 条目必须提供 depth */
+    depth: number;
+    condition?: string;
+};
+/**
+ * 世界书条目（引擎内部使用：严格版）
+ * - role 必有
+ * - slot 条目没有 depth
+ * - fixed 条目必须有 depth
+ */
+type WorldbookEntry = (Omit<Extract<WorldbookEntryInput, {
+    position: 'before_char' | 'after_char';
+}>, 'role'> & {
+    role: Role;
+}) | (Omit<Extract<WorldbookEntryInput, {
+    position: 'fixed';
+}>, 'role'> & {
+    role: Role;
+});
+/** 世界书（输入文件） */
+interface Worldbook {
+    name: string;
+    description?: string;
+    entries: WorldbookEntryInput[];
+}
+/**
+ * 兼容外部传入的世界书 JSON。
+ * - 既可以传完整 worldbook（{name, entries}）
+ * - 也可以直接传 entries 数组
+ */
+type WorldbookInput = Worldbook | WorldbookEntryInput[] | ({
+    entries: WorldbookEntryInput[];
+    enabled?: boolean;
+    name?: string;
+    description?: string;
+    id?: string;
+});
+type WorldbooksInput = WorldbookInput | WorldbookInput[];
+/** 预设提示词块（严格版） */
+type PromptBlock = {
+    identifier: string;
+    name: string;
+    enabled: boolean | null;
+    role: Role;
+    position: 'relative';
+    content?: string;
+    /** relative 不使用 depth */
+    depth?: never;
+    /** relative 允许 order（如果你想给 UI 排序用），但组装逻辑不会使用它 */
+    order?: number;
+} | {
+    identifier: string;
+    name: string;
+    enabled: boolean | null;
+    role: Role;
+    position: 'fixed';
+    content?: string;
+    /** fixed 必须提供 depth */
+    depth: number;
+    /** 注入排序：同 depth 下按 order 升序（fixed 必填） */
+    order: number;
+};
+interface PresetConfig {
+    id: string;
+    name: string;
+    description: string;
+    prompts: PromptBlock[];
+    regex_rules?: RegexRule[];
+    world_book?: Worldbook;
+}
+interface CharacterCard {
+    id: string;
+    name: string;
+    character_name: string;
+    avatar?: string;
+    description: string;
+    message: string[];
+    world_book?: Worldbook;
+    regex_rules?: RegexRule[];
+}
+interface TaggedContent {
+    tag: string;
+    role: Role;
+    text: string;
+    target: Target;
+}
+interface GeminiPart {
+    text: string;
+}
+/**
+ * “类 Gemini”内部格式。
+ * 注意：这里我们保留 system。
+ * - 当下游输出格式不支持 system 时，才在输出转换阶段做降级（system -> user）。
+ */
+interface GeminiContent {
+    role: Role;
+    parts: GeminiPart[];
+}
+interface OpenAIMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+interface SimpleMessage {
+    role: 'system' | 'user' | 'assistant' | 'model';
+    text: string;
+}
+type MessageInput = string | string[] | GeminiContent[] | OpenAIMessage[] | SimpleMessage[] | TaggedContent[];
+type MessageFormat = 'auto' | 'gemini' | 'openai' | 'simple' | 'tagged' | 'text';
+/**
+ * 兼容外部传入的正则 JSON。
+ * - RegexRule[]
+ * - { regex_rules: RegexRule[] }
+ * - { rules: RegexRule[] }
+ * - RegexRule
+ * - 以上任意形式的数组（多文件）
+ */
+type RegexesFileInput = RegexRule[] | {
+    regex_rules: RegexRule[];
+} | {
+    rules: RegexRule[];
+} | RegexRule;
+type RegexesInput = RegexesFileInput | RegexesFileInput[];
+/**
+ * 明确的“聊天记录入口”。
+ * 设计目标：调用方一眼能看出自己传的是什么格式，而不是依赖 auto 推断。
+ */
+type HistoryInput = {
+    format: 'gemini';
+    messages: GeminiContent[];
+} | {
+    format: 'openai';
+    messages: OpenAIMessage[];
+} | {
+    format: 'simple';
+    messages: SimpleMessage[];
+} | {
+    format: 'tagged';
+    messages: TaggedContent[];
+} | {
+    format: 'text';
+    text: string | string[];
+} | {
+    format: 'auto';
+    input: MessageInput;
+};
+interface PromptStages<T> {
+    /** 原始视图：仅完成组装，尚未进入正则/宏管道 */
+    raw: T;
+    /** 宏前正则完视图：已执行 placement=before_macro 的正则 */
+    afterPreRegex: T;
+    /** 宏执行完视图：已完成宏替换（位于两段正则之间） */
+    afterMacro: T;
+    /** 宏后正则完视图（最终视图）：已执行 placement=after_macro 的正则 */
+    afterPostRegex: T;
+}
+interface PerItemStages {
+    tag: string;
+    role: Role;
+    target: Target;
+    raw: string;
+    afterPreRegex: string;
+    afterMacro: string;
+    afterPostRegex: string;
+}
+interface BuildPromptParams {
+    preset: PresetConfig;
+    character?: CharacterCard;
+    globals?: {
+        /**
+         * 全局世界书（可选）。
+         * 允许一次性传入多个世界书 JSON（多文件），内部会拼接 entries 后使用。
+         */
+        worldbooks?: WorldbooksInput;
+        /**
+         * 全局正则（可选）。
+         * 允许一次性传入多个正则 JSON（多文件），内部会拼接 rules 后使用。
+         */
+        regexes?: RegexesInput;
+    };
+    /**
+     * 聊天记录入口（推荐传 HistoryInput，使格式明确）。
+     * 兼容：你也可以直接传 MessageInput + historyFormat。
+     */
+    history: HistoryInput | MessageInput;
+    /** 当 history 直接传 MessageInput 时，用该字段声明格式；默认 auto */
+    historyFormat?: MessageFormat;
+    /** 输出格式；默认：跟随输入（若输入为 auto，则跟随检测到的格式） */
+    outputFormat?: Exclude<MessageFormat, 'auto'> | 'tagged';
+    /**
+     * system 角色输出策略（仅影响最终 output / stages.output）。
+     * - keep: 保留 system
+     * - to_user: 将 system 降级为 user（用于下游不接受 system 的渠道）
+     */
+    systemRolePolicy?: 'keep' | 'to_user';
+    /** 用于宏替换，例如 { char: 'Alice', user: 'Bob' } */
+    macros: Record<string, string>;
+    /** 选择正则视图 */
+    view: View;
+    options?: {
+        /** 世界书匹配上下文使用最近几条聊天历史；默认 5 */
+        recentHistoryForWorldbook?: number;
+        /**
+         * 世界书 position 到 preset block.identifier 的映射。
+         * - before_char / after_char 属于插槽条目
+         * - fixed 不参与映射（它是注入到 chatHistory 的）
+         */
+        positionMap?: Partial<Record<'before_char' | 'after_char', string>>;
+    };
+}
+interface BuildPromptResult {
+    detectedHistoryFormat: Exclude<MessageFormat, 'auto'>;
+    outputFormat: Exclude<MessageFormat, 'auto'> | 'tagged';
+    systemRolePolicy: 'keep' | 'to_user';
+    /** 世界书激活结果 */
+    activeWorldbookEntries: WorldbookEntry[];
+    /** 合并后的正则规则（global + preset + character） */
+    mergedRegexRules: RegexRule[];
+    /**
+     * 不同处理阶段的提示词（用于调试/预览）。
+     * 约定阶段：
+     * - raw：原始视图
+     * - afterPreRegex：宏前正则完视图
+     * - afterMacro：宏执行完视图
+     * - afterPostRegex：宏后正则完视图（最终视图）
+     */
+    stages: {
+        /** 每个片段都带 tag/target，最适合用于 UI 展示 */
+        tagged: PromptStages<TaggedContent[]>;
+        /** 内部统一后的“类 Gemini”格式（role: system/user/model） */
+        internal: PromptStages<GeminiContent[]>;
+        /** 按 outputFormat 转换后的输出 */
+        output: PromptStages<GeminiContent[] | OpenAIMessage[] | SimpleMessage[] | TaggedContent[] | string>;
+        /** 单条文本的阶段明细（更细粒度，便于定位某条规则/宏造成的变化） */
+        perItem: PerItemStages[];
+    };
+}
+
+declare function detectMessageFormat(input: MessageInput): Exclude<MessageFormat, 'auto'>;
+
+declare function isTextInput(v: unknown): v is string | string[];
+declare function toInternalFromText(input: string | string[]): GeminiContent[];
+declare function fromInternalToText(internal: GeminiContent[]): string;
+
+/**
+ * 将任意输入历史统一转换为 GeminiContent[]（role 只保留 user/model）。
+ * - openai: system/user -> user, assistant -> model
+ * - simple: system/user -> user, assistant/model -> model
+ */
+declare function convertMessagesIn(input: MessageInput, format?: MessageFormat): {
+    detected: Exclude<MessageFormat, 'auto'>;
+    internal: GeminiContent[];
+};
+declare function convertMessagesOut(internal: GeminiContent[], format: Exclude<MessageFormat, 'auto'>): GeminiContent[] | OpenAIMessage[] | SimpleMessage[] | string;
+
+/**
+ * 帮助你创建“明确格式”的 history 入参，避免依赖 auto 推断。
+ */
+declare const History: {
+    readonly gemini: (messages: Extract<HistoryInput, {
+        format: "gemini";
+    }>["messages"]) => HistoryInput;
+    readonly openai: (messages: Extract<HistoryInput, {
+        format: "openai";
+    }>["messages"]) => HistoryInput;
+    readonly simple: (messages: Extract<HistoryInput, {
+        format: "simple";
+    }>["messages"]) => HistoryInput;
+    readonly tagged: (messages: Extract<HistoryInput, {
+        format: "tagged";
+    }>["messages"]) => HistoryInput;
+    readonly text: (text: Extract<HistoryInput, {
+        format: "text";
+    }>["text"]) => HistoryInput;
+    readonly auto: (input: MessageInput) => HistoryInput;
+};
+
+declare function isHistoryInput(v: unknown): v is HistoryInput;
+/**
+ * 用于兼容：当调用方没有使用 HistoryInput，而是直接传了 MessageInput 时，
+ * 可通过该函数统一推断/声明其格式。
+ */
+declare function normalizeHistoryFormat(format?: MessageFormat): MessageFormat;
+
+declare function testCondition(condition: string | undefined, text: string): boolean;
+
+declare function getActiveEntries(params: {
+    contextText?: string;
+    /** 已归一化后的全局世界书 entries */
+    globalEntries?: WorldbookEntry[];
+    presetWorldbook?: Worldbook;
+    characterWorldbook?: Worldbook;
+}): WorldbookEntry[];
+
+/**
+ * 复刻你当前 store 里的 applyRegex 行为（含 target 映射逻辑）。
+ */
+declare function applyRegex(text: string, params: {
+    rules: RegexRule[];
+    target: Target;
+    view: View;
+    placement?: 'before_macro' | 'after_macro';
+}): string;
+
+declare function mergeRegexRules(params: {
+    /** 全局正则规则（可选） */
+    globalRules?: RegexRule[];
+    /** 预设内嵌正则 */
+    presetRules?: RegexRule[];
+    /** 角色卡内嵌正则 */
+    characterRules?: RegexRule[];
+}): RegexRule[];
+
+/**
+ * 简单宏替换。
+ * 兼容：{{char}} {{user}} <<user>>
+ * 同时支持传入任意 key：{{key}}
+ */
+declare function replaceMacros(text: string, macros: Record<string, string>): string;
+
+declare function assembleTaggedPromptList(params: {
+    presetBlocks: PromptBlock[];
+    activeEntries: WorldbookEntry[];
+    /** 线性聊天历史（允许包含 system） */
+    chatHistory: Array<{
+        role: Role;
+        text: string;
+    }>;
+    positionMap?: Partial<Record<'before_char' | 'after_char', string>>;
+}): TaggedContent[];
+
+declare function processContentStages(text: string, params: {
+    target: Target;
+    view: View;
+    rules: RegexRule[];
+    macros: Record<string, string>;
+}): Pick<PerItemStages, 'raw' | 'afterPreRegex' | 'afterMacro' | 'afterPostRegex'>;
+
+declare function compileTaggedStages(tagged: TaggedContent[], params: {
+    view: View;
+    rules: RegexRule[];
+    macros: Record<string, string>;
+}): {
+    stages: PromptStages<TaggedContent[]>;
+    perItem: PerItemStages[];
+};
+
+/**
+ * 兼容用户一次性传入多个“正则 JSON 文件”的情况。
+ * 支持格式：
+ * - RegexRule[]
+ * - { regex_rules: RegexRule[] }
+ * - { rules: RegexRule[] }
+ * - RegexRule
+ * - 以上任意形式的数组（多文件）
+ */
+declare function normalizeRegexes(input?: RegexesInput): RegexRule[];
+
+/**
+ * 兼容用户一次性传入多个“世界书 JSON 文件”的情况。
+ * 支持格式：
+ * - Worldbook（{ name, entries }）
+ * - WorldbookEntryInput[]
+ * - 以上任意形式的数组（多文件）
+ */
+declare function normalizeWorldbooks(input?: WorldbooksInput): WorldbookEntry[];
+
+declare function buildPrompt(params: BuildPromptParams): BuildPromptResult;
+
+declare function isGeminiContents(v: unknown): v is GeminiContent[];
+declare function toInternalFromGemini(input: GeminiContent[]): GeminiContent[];
+declare function fromInternalToGemini(internal: GeminiContent[]): GeminiContent[];
+
+declare function isOpenAIMessages(v: unknown): v is OpenAIMessage[];
+/**
+ * openai: system/user/assistant 都保留。
+ * - assistant -> model（内部）
+ */
+declare function toInternalFromOpenAI(input: OpenAIMessage[]): GeminiContent[];
+declare function fromInternalToOpenAI(internal: GeminiContent[]): OpenAIMessage[];
+
+declare function isSimpleMessages(v: unknown): v is SimpleMessage[];
+/**
+ * simple: 保留 system/user；assistant/model -> model（内部）。
+ */
+declare function toInternalFromSimple(input: SimpleMessage[]): GeminiContent[];
+declare function fromInternalToSimple(internal: GeminiContent[]): SimpleMessage[];
+
+declare function isTaggedContents(v: unknown): v is TaggedContent[];
+declare function toInternalFromTagged(input: TaggedContent[]): GeminiContent[];
+/**
+ * 注意：tagged 的“反向转换”没有足够信息恢复 tag/target。
+ * 所以 fromInternal 只能退化成 simple 或文本。
+ * buildPrompt() 会在 outputFormat='tagged' 时直接返回 taggedStages，而不是走 convertMessagesOut。
+ */
+declare function fromInternalToTagged(_internal: GeminiContent[]): TaggedContent[];
+
+declare const index_detectMessageFormat: typeof detectMessageFormat;
+declare const index_fromInternalToGemini: typeof fromInternalToGemini;
+declare const index_fromInternalToOpenAI: typeof fromInternalToOpenAI;
+declare const index_fromInternalToSimple: typeof fromInternalToSimple;
+declare const index_fromInternalToTagged: typeof fromInternalToTagged;
+declare const index_fromInternalToText: typeof fromInternalToText;
+declare const index_isGeminiContents: typeof isGeminiContents;
+declare const index_isOpenAIMessages: typeof isOpenAIMessages;
+declare const index_isSimpleMessages: typeof isSimpleMessages;
+declare const index_isTaggedContents: typeof isTaggedContents;
+declare const index_isTextInput: typeof isTextInput;
+declare const index_toInternalFromGemini: typeof toInternalFromGemini;
+declare const index_toInternalFromOpenAI: typeof toInternalFromOpenAI;
+declare const index_toInternalFromSimple: typeof toInternalFromSimple;
+declare const index_toInternalFromTagged: typeof toInternalFromTagged;
+declare const index_toInternalFromText: typeof toInternalFromText;
+declare namespace index {
+  export { index_detectMessageFormat as detectMessageFormat, index_fromInternalToGemini as fromInternalToGemini, index_fromInternalToOpenAI as fromInternalToOpenAI, index_fromInternalToSimple as fromInternalToSimple, index_fromInternalToTagged as fromInternalToTagged, index_fromInternalToText as fromInternalToText, index_isGeminiContents as isGeminiContents, index_isOpenAIMessages as isOpenAIMessages, index_isSimpleMessages as isSimpleMessages, index_isTaggedContents as isTaggedContents, index_isTextInput as isTextInput, index_toInternalFromGemini as toInternalFromGemini, index_toInternalFromOpenAI as toInternalFromOpenAI, index_toInternalFromSimple as toInternalFromSimple, index_toInternalFromTagged as toInternalFromTagged, index_toInternalFromText as toInternalFromText };
+}
+
+export { type BuildPromptParams, type BuildPromptResult, index as Channels, type CharacterCard, type GeminiContent, type GeminiPart, History, type HistoryInput, type MessageFormat, type MessageInput, type OpenAIMessage, type PerItemStages, type PresetConfig, type PromptBlock, type PromptStages, type RegexRule, type RegexesFileInput, type RegexesInput, type Role, type SimpleMessage, type TaggedContent, type Target, type View, type Worldbook, type WorldbookEntry, type WorldbookEntryInput, type WorldbookInput, type WorldbookPosition, type WorldbooksInput, applyRegex, assembleTaggedPromptList, buildPrompt, compileTaggedStages, convertMessagesIn, convertMessagesOut, detectMessageFormat, getActiveEntries, isHistoryInput, isTextInput, mergeRegexRules, normalizeHistoryFormat, normalizeRegexes, normalizeWorldbooks, processContentStages, replaceMacros, testCondition };