fast-tavern 0.1.0

package/README.md

@@ -0,0 +1,202 @@
+# fast-tavern
+
+fast-tavern 是一个**与框架无关**（不依赖 Vue/Pinia/浏览器 API）的“提示词处理引擎（prompt engine）”。
+
+它把：**预设（Preset）/ 世界书（Worldbook）/ 角色卡（Character）/ 正则（Regex）/ 宏（Macros）/ 聊天记录（History）**
+按固定规则组装，并输出清晰的 4 个阶段视图，方便预览与调试：
+
+- 原始视图（raw）
+- 宏前正则完视图（afterPreRegex）
+- 宏执行完视图（afterMacro）
+- 宏后正则完视图 / 最终视图（afterPostRegex）
+
+---
+
+## 功能概览
+
+- **预设 Prompt Blocks 组装**：relative blocks 作为骨架，fixed blocks 按 depth 插入到聊天历史中
+- **世界书触发与注入**：支持 always / conditional；支持 `<<keywords:a,b>>`；支持正则 condition
+- **正则规则管道**：`before_macro` → `macro` → `after_macro`，并支持按 `target` / `view` 过滤
+- **宏替换**：`{{char}}`、`{{user}}`、`<<user>>` 以及任意 `{{key}}`
+- **多渠道聊天格式输入/输出**：Gemini / OpenAI / Simple / Tagged / Text
+- **输出多阶段结果**：raw、afterPreRegex、afterMacro、afterPostRegex（并提供逐条 perItem 明细）
+
+### system role 策略
+
+- 引擎内部 **保留 `system` role**（不会提前降级）。
+- 仅在最终输出（`output` / `stages.output.*`）可通过 `systemRolePolicy` 控制：
+  - `keep`：保留 system
+  - `to_user`：将 system 降级为 user（保留内容，仅改变角色）
+
+---
+
+## 安装
+
+### 从 npm 安装
+
+```bash
+npm i fast-tavern
+```
+
+### 本地安装（开发期）
+
+```bash
+npm i ./packages/fast-tavern
+```
+
+构建（发布前）：
+
+```bash
+cd packages/fast-tavern
+npm i
+npm run build
+```
+
+---
+
+## 快速开始
+
+```ts
+import { buildPrompt, History } from 'fast-tavern';
+
+const result = buildPrompt({
+  preset,       // PresetConfig JSON
+  character,    // CharacterCard JSON（可选）
+  globals: {
+    // 支持一次性传入多个 JSON 文件：
+    // - worldbook.json（{ name, entries }）
+    // - 或直接 entries 数组
+    worldbooks,
+
+    // 支持一次性传入多个 JSON 文件：
+    // - RegexRule[]
+    // - 或 { regex_rules: RegexRule[] }
+    regexes
+  },
+
+  // 聊天记录入口：推荐用 History.* 明确格式
+  history: History.openai([
+    { role: 'system', content: 'You are a helpful assistant.' },
+    { role: 'user', content: 'Hello' },
+    { role: 'assistant', content: 'Hi!' }
+  ]),
+
+  // 正则视图：user_view / model_view
+  view: 'model_view',
+
+  // 宏变量
+  macros: { char: 'Alice', user: 'Bob' },
+
+  // 输出格式：gemini/openai/simple/text/tagged
+  outputFormat: 'openai',
+
+  // system 输出策略
+  systemRolePolicy: 'keep'
+});
+
+// 多阶段（最推荐用于调试/预览）
+console.log(result.stages.tagged.raw);
+console.log(result.stages.tagged.afterPreRegex);
+console.log(result.stages.tagged.afterMacro);
+console.log(result.stages.tagged.afterPostRegex);
+
+// 最终输出（按 outputFormat 转换）
+console.log(result.stages.output.afterPostRegex);
+
+// 更细粒度：逐条文本的阶段明细
+console.table(result.stages.perItem);
+```
+
+---
+
+## 核心 API
+
+### buildPrompt(params)
+
+`buildPrompt()` 是主入口：输入配置与聊天记录，输出多阶段提示词。
+
+关键入参（摘选）：
+
+- `preset: PresetConfig`：预设配置（prompts / regex_rules / world_book）
+- `character?: CharacterCard`：角色卡（可内嵌 world_book / regex_rules）
+- `globals?: { worldbooks?: ..., regexes?: ... }`：全局世界书/正则（全局正则推荐直接传 rules 数组）
+- `history: HistoryInput | MessageInput`：聊天记录（多格式）
+- `view: 'user_view' | 'model_view'`：正则视图
+- `macros: Record<string,string>`：宏变量表
+- `outputFormat?: 'gemini'|'openai'|'simple'|'text'|'tagged'`：输出格式
+- `systemRolePolicy?: 'keep'|'to_user'`：system 输出策略
+- `options?: { recentHistoryForWorldbook?: number; positionMap?: Record<string,string> }`
+
+返回值重点字段：
+
+- `result.stages.tagged.*`：带 tag/target 的分段结果（最适合 UI 预览）
+- `result.stages.internal.*`：内部“类 Gemini”messages（Role: system/user/model）
+- `result.stages.output.*`：按 outputFormat 转换后的分阶段输出
+- `result.stages.perItem[]`：逐条文本的 raw/preRegex/macro/postRegex 对比
+
+### History.*（推荐）
+
+为了避免 `auto` 推断歧义，推荐用工厂函数创建明确格式的 history：
+
+```ts
+import { History } from 'fast-tavern';
+
+History.gemini(geminiContents)
+History.openai(openaiMessages)
+History.simple(simpleMessages)
+History.tagged(taggedContents)
+History.text('...')
+History.auto(anyMessageInput)
+```
+
+### convertMessagesIn / convertMessagesOut
+
+用于“渠道格式 ↔ 内部格式”的转换（不做 preset/worldbook/regex/macro 的组装与编译）。
+
+```ts
+import { convertMessagesIn, convertMessagesOut } from 'fast-tavern';
+
+const { internal } = convertMessagesIn(openaiMessages, 'openai');
+const backToOpenAI = convertMessagesOut(internal, 'openai');
+```
+
+> tagged 格式无法从 internal 无损恢复 tag/target，所以 **tagged 输出应使用 buildPrompt 的 `outputFormat:'tagged'`**。
+
+---
+
+## 数据模型（与 SillyTavern 风格接近）
+
+- `PresetConfig`：包含 `prompts: PromptBlock[]`、可选 `regex_rules`、可选 `world_book`
+- `WorldbookEntry`：包含 `mode`、`condition`、`position`、`depth`、`order` 等
+- `RegexRule`：包含 `targets`、`views`、`placement`（before/after macro）
+
+具体字段请以类型定义为准：
+
+- `src/core/types.ts`
+
+---
+
+## 目录结构（便于分开调试）
+
+- 转换层（每种格式一个文件）：`src/core/channels/*`
+- 功能模块（隔离实现）：`src/core/modules/*`
+  - `worldbook/`：条件触发与合并
+  - `assemble/`：组装 tagged prompt list
+  - `regex/`：合并规则、应用规则
+  - `macro/`：宏替换
+  - `pipeline/`：before_regex → macro → after_regex（并输出阶段）
+  - `build/`：buildPrompt 总入口
+
+---
+
+## 常见用法建议
+
+1. **做 UI 预览**：用 `result.stages.tagged.*`（带 tag/target，最直观）
+2. **发给不同模型接口**：用 `outputFormat` 控制输出格式；如果下游不支持 system，设 `systemRolePolicy:'to_user'`，取 `result.stages.output.afterPostRegex`
+3. **定位正则/宏导致的问题**：用 `result.stages.perItem` 对比每一条在各阶段的变化
+
+---
+
+## License
+
+MIT