fast-tavern 0.1.2 → 0.1.3

package/README.md

@@ -1,31 +1,25 @@
 # fast-tavern
 
-fast-tavern 是一个**与框架无关**（不依赖 Vue/Pinia/浏览器 API）的“提示词处理引擎（prompt engine）”。
+fast-tavern 是一个**与框架无关**的“提示词组装与调试引擎（prompt engine）”。
 
-它把：**预设（Preset）/ 世界书（Worldbook）/ 角色卡（Character）/ 正则（Regex）/ 宏（Macros）/ 聊天记录（History）**
-按固定规则组装，并输出清晰的 4 个阶段视图，方便预览与调试：
+它以 `st-api-wrapper` 的**新格式字段**为准，把：
+**预设（Preset）/ 世界书（WorldBook）/ 角色卡（CharacterCard）/ 正则脚本（RegexScriptData）/ 宏与变量 / 聊天历史（ChatMessage）**
+按固定流程组装，并输出**可调试的多阶段结果**（便于 UI 预览与定位问题）：
 
-- 原始视图（raw）
-- 宏前正则完视图（afterPreRegex）
-- 宏执行完视图（afterMacro）
-- 宏后正则完视图 / 最终视图（afterPostRegex）
+- `raw`
+- `afterPreRegex`（为兼容保留：当前等同 `raw`）
+- `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>>`、`<<char>>` 以及任意 `{{key}}` / `<<key>>`
-- **自动宏提取**：从 `character.character_name` 和 `persona.persona_name` 自动提取 char/user 宏
-- **变量系统**：支持局部/全局变量，在宏阶段线性执行（同时支持 `{{}}` 和 `<<>>` 格式）
-  - `{{getvar::name}}` / `<<getvar::name>>` - 获取局部变量
-  - `{{setvar::name::value}}` / `<<setvar::name::value>>` - 设置局部变量
-  - `{{getglobalvar::name}}` / `<<getglobalvar::name>>` - 获取全局变量
-  - `{{setglobalvar::name::value}}` / `<<setglobalvar::name::value>>` - 设置全局变量
-- **多渠道聊天格式输入/输出**：Gemini / OpenAI / Simple / Tagged / Text
-- **输出多阶段结果**：raw、afterPreRegex、afterMacro、afterPostRegex（并提供逐条 perItem 明细）
+- **预设组装**：`position=relative` 作为骨架；`position=fixed` 按 `depth/order` 注入到 `chatHistory`
+- **世界书触发与注入**：`always/keyword/vector`（vector 通过 hook）；支持概率与递归控制
+- **正则脚本**：对齐 `RegexScriptData`（targets/view/trim/{{match}}/macroMode/minDepth/maxDepth）
+- **宏与变量**：宏保持简单；变量对齐 `local/global` 且值为 `any`
+- **输出多阶段结果**：`stages.tagged/internal/output/perItem`
 
 ### system role 策略
 
@@ -54,171 +48,78 @@ npm i fast-tavern
 ### 本地安装（开发期）
 
 ```bash
-npm i ./packages/fast-tavern
+# 在你的项目中
+npm i ../fast-tavern
 ```
 
-构建（发布前）：
+---
+
+## 开发与发布
+
+### 构建
 
 ```bash
-cd packages/fast-tavern
+cd npm-fast-tavern
 npm i
 npm run build
 ```
 
+### 发布到 npm
+
+1. **更新版本号**：修改 `package.json` 中的 `version`。
+2. **构建项目**：执行 `npm run build`。
+3. **登录 npm**（若未登录）：`npm login`。
+4. **执行发布**：`npm publish --access public`。
+
 ---
 
-## 快速开始
+## 快速开始（最小示例）
 
 ```ts
 import { buildPrompt, History } from 'fast-tavern';
 
 const result = buildPrompt({
-  preset,       // PresetConfig JSON
-  character,    // CharacterCard JSON（可选）- 自动提取 char 宏
-  persona,      // PersonaCard JSON（可选）- 自动提取 user 宏
+  preset,       // PresetInfo
+  character,    // CharacterCard（可选）
   globals: {
-    // 支持一次性传入多个 JSON 文件：
-    // - worldbook.json（{ name, entries }）
-    // - 或直接 entries 数组
-    worldbooks,
-
-    // 支持一次性传入多个 JSON 文件：
-    // - RegexRule[]
-    // - 或 { regex_rules: RegexRule[] }
-    regexes
+    worldBooks,
+    regexScripts
   },
 
-  // 聊天记录入口：推荐用 History.* 明确格式
+  // 聊天记录（ChatMessage[]）
   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',
-
-  // 宏变量（可选，会与 character/persona 自动提取的合并，显式传入的优先级更高）
-  macros: { custom_var: 'value' },
+  // 正则视图：user / model
+  view: 'model',
 
-  // 局部变量初始值（可选）
-  variables: { counter: '0', name: 'Alice' },
+  // 宏变量（可选）
+  macros: { user: 'Bob' },
 
-  // 全局变量初始值（可选，建议由调用方维护状态）
-  globalVariables: { totalTurns: '10' },
+  // 变量（any）
+  variables: { score: 1, cfg: { a: 1 } },
 
-  // 输出格式：gemini/openai/simple/text/tagged
+  // 输出格式：gemini/openai/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);
+console.log(result.stages.tagged.afterPostRegex); // UI 预览最推荐
+console.log(result.stages.output.afterPostRegex); // 最终输出
 
-// 最终输出（按 outputFormat 转换）
-console.log(result.stages.output.afterPostRegex);
-
-// 获取变量最终状态（用于持久化）
-console.log(result.variables.local);   // 局部变量
-console.log(result.variables.global);  // 全局变量
-
-// 更细粒度：逐条文本的阶段明细
-console.table(result.stages.perItem);
+console.log(result.variables.local);
 ```
 
----
-
-## 核心 API
-
-### buildPrompt(params)
-
-`buildPrompt()` 是主入口：输入配置与聊天记录，输出多阶段提示词。
-
-关键入参（摘选）：
-
-- `preset: PresetConfig`：预设配置（prompts / regex_rules / world_book）
-- `character?: CharacterCard`：角色卡（可内嵌 world_book / regex_rules，自动提取 char 宏）
-- `persona?: PersonaCard`：用户人设卡（自动提取 user 宏）
-- `globals?: { worldbooks?: ..., regexes?: ... }`：全局世界书/正则（全局正则推荐直接传 rules 数组）
-- `history: HistoryInput | MessageInput`：聊天记录（多格式）
-- `view: 'user_view' | 'model_view'`：正则视图
-- `macros?: Record<string,string>`：宏变量表（会与 character/persona 自动提取的合并）
-- `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` 对比每一条在各阶段的变化
+- **格式与组装流程（详细）**：[`docs/FORMAT_ZH.md`](docs/FORMAT_ZH.md)
+- **API 文档**：[`docs/API_ZH.md`](docs/API_ZH.md)
+- **使用教程（详细示例）**：[`docs/GUIDE_ZH.md`](docs/GUIDE_ZH.md)
 
 ---