### NativeTavern 功能设计文档（供 Go + React 集成参考）

---

## 总览

本项目中，这几个模块的作用和依赖关系如下：

- **聊天功能（Chat）**：统一负责从「用户消息」到「LLM 调用」再到「写回消息」的完整流程。
- **提示词管理（Prompt Management）**：把系统提示、人设、世界信息、作者注释、历史等拆成可配置的「段」，决定顺序与注入深度。
- **宏系统（Macros）**：在构建 prompt 时，根据上下文展开 `{{user}}`、`{{char}}`、`{{time}}`、`{{random}}` 等占位符。
- **变量系统（Variables）**：提供全局 / 每会话变量 + `{{setvar}}` / `{{getvar}}` 等变量宏，支持状态机、计数等逻辑。
- **思维链支持（Chain-of-Thought / Reasoning）**：对 o1/o3、Claude、Gemini 等的推理内容单独解析、存储，并在前端单独渲染。

Go + React 中建议同样分层：**数据模型（DB） + 领域服务（Go） + 状态/UI（React）**。

---

## 一、变量系统（Variables System）

### 1.1 目标

- 支持两类变量：
    - **全局变量**：跨所有聊天共用，用户级。
    - **本地变量**：每个 chat 独立，存到 chat metadata。
- 通过宏语法在文本中读写变量，如：
    - `{{setvar::score::10}}`
    - `{{incvar::turn}}`
    - `{{getvar::user_name}}`

### 1.2 数据模型（示例）

后端可参考：

```go
// 全局变量：按 userId 存
type GlobalVariables map[string]any // name -> value

// 本地变量：按 chatId 存
type LocalVariables map[string]map[string]any // chatId -> (name -> value)

type ChatMetadata struct {
    Variables map[string]any `json:"variables,omitempty"`
    // ... 其他 metadata 字段 ...
}
```

- 全局变量：存 Redis / Postgres JSONB / KV，按 userId 分片。
- 本地变量：挂在 `chats.metadata.variables` 字段。

### 1.3 变量服务接口（Go）

```go
type VariablesService interface {
    // 全局变量
    GetGlobal(userId, name string) any
    SetGlobal(userId, name string, v any) error
    AddGlobal(userId, name string, delta any) (any, error)
    IncGlobal(userId, name string) (any, error)
    DecGlobal(userId, name string) (any, error)

    // 本地变量（带 chatId）
    GetLocal(userId, chatId, name string) any
    SetLocal(userId, chatId, name string, v any) error
    AddLocal(userId, chatId, name string, delta any) (any, error)
    IncLocal(userId, chatId, name string) (any, error)
    DecLocal(userId, chatId, name string) (any, error)

    LoadLocalFromMetadata(chatId string, metaVars map[string]any)
    ExportLocalToMetadata(chatId string) map[string]any
}
```

### 1.4 变量宏语法

支持以下语法（与项目一致）：

- 本地变量：
    - `{{setvar::name::value}}`
    - `{{addvar::name::value}}`
    - `{{incvar::name}}`
    - `{{decvar::name}}`
    - `{{getvar::name}}`
- 全局变量：
    - `{{setglobalvar::name::value}}`
    - `{{addglobalvar::name::value}}`
    - `{{incglobalvar::name}}`
    - `{{decglobalvar::name}}`
    - `{{getglobalvar::name}}`

解析函数示例：

```go
func ProcessVariableMacros(input, userId string, chatId *string, vars VariablesService) (string, error)
```

实现建议：

1. 为每种宏写一个正则，比如：
    - `\{\{setvar::([^:]+)::([^}]*)\}\}`
    - `\{\{getvar::([^}]+)\}\}` 等。
2. 按「写变量 → 读变量」顺序依次 `ReplaceAllStringFunc`：
    - set / add / inc / dec：调用 `VariablesService`，返回空串或新值字符串。
    - get：用变量值替换整段 `{{...}}`。

**集成位置**：在构建 prompt、处理用户输入时，先跑一遍 `ProcessVariableMacros`。

---

## 二、宏系统（Macro System）

### 2.1 目标

- 使用 `{{...}}` 宏在 prompt 中引入上下文信息，包括：
    - 用户/人设：`{{user}}`、`{{persona}}`、`{{user_description}}`
    - 角色：`{{char}}`、`{{char_description}}`、`{{system_prompt}}`、`{{jailbreak}}`
    - 时间：`{{time}}`、`{{date}}`、`{{weekday}}`
    - 聊天上下文：`{{lastMessage}}`、`{{lastUserMessage}}`、`{{messageCount}}` 等
    - 随机：`{{random}}`、`{{random::min::max}}`、`{{roll::2d6}}`、`{{pick::a::b}}`
    - 元信息：`{{model}}`、`{{provider}}`、`{{idle_duration}}` 等。

### 2.2 宏上下文（Go）

```go
type MacroContext struct {
    UserName            string
    UserDescription     string

    CharacterName          string
    CharacterDescription   string
    CharacterSystemPrompt  string
    PostHistoryInstructions string

    LastMessage         string
    LastUserMessage     string
    LastCharacterMessage string
    MessageCount        int
    ChatID              string

    OriginalPrompt      string
    CurrentInput        string
    ModelName           string
    ProviderName        string
    IdleDurationMinutes int

    Now                 time.Time
}
```

### 2.3 宏解析函数

```go
func ProcessMacros(text string, ctx MacroContext) string
```

推荐拆为多个子步骤（顺序类似原项目）：

1. `_processRandomMacros`：
    - `{{random}}`
    - `{{random::min::max}}`
    - `{{roll::NdM}}`
    - `{{pick::opt1::opt2}}`
    - `{{uuid}}`
2. `_processConditionalMacros`：
    - `{{if::cond::then}}`
    - `{{if::cond::then::else}}`（可以做简单布尔表达式解析）
3. `_processTimeDateMacros`：
    - `{{time}}` / `{{date}}` / `{{weekday}}` / 自定义时间格式。
4. `_processCharacterMacros`：
    - `{{char}}`、`{{char_description}}`、`{{system_prompt}}`、`{{post_history_instructions}}` 等。
5. `_processUserMacros`：
    - `{{user}}` / `{{persona}}` / `{{user_description}}`。
6. `_processChatMacros`：
    - `{{lastMessage}}` / `{{lastUserMessage}}` / `{{lastCharMessage}}` / `{{messageCount}}` / `{{chatId}}`。
7. `_processSpecialMacros`：
    - `{{newline}}` / `{{nl}}`、`{{trim}}`、`{{noop}}`
    - `{{original}}`（原始 prompt，用于局部覆盖）
    - `{{input}}`（当前用户输入）
    - `{{model}}` / `{{provider}}`
    - `{{idle_duration}}`。

**集成顺序**（在构建 prompt 时）：

1. 先跑变量宏 `ProcessVariableMacros`（会改变变量状态）。
2. 再跑文本宏 `ProcessMacros`。

---

## 三、思维链支持（Chain-of-Thought / Reasoning）

### 3.1 目标

- 对支持推理的模型（o1/o3、Claude Thinking、Gemini 思考流）：
    - 把推理内容单独抓出来（从 `reasoning_content` / `thinking` / `thought` 字段等）。
    - 和正常回复一起存在消息上。
    - 前端给一个可折叠的「思维链/推理」区域。

### 3.2 数据模型

```go
type ChatMessage struct {
    ID        string
    ChatID    string
    Role      string    // "user" / "assistant" / "system"
    Content   string
    Timestamp time.Time

    Swipes          []string
    CurrentSwipeIdx int

    Reasoning       *string   // 默认推理文本
    ReasoningSwipes []string  // 每个 swipe 的推理

    // ... 其他字段（attachments、characterId 等）
}
```

前端便于使用的派生属性（在 React 里实现）：

- `currentReasoning`：
    - 如果 `ReasoningSwipes` 长度 > `CurrentSwipeIdx` → 用对应项；
    - 否则用 `Reasoning`。
- `hasReasoning`：
    - `Reasoning` 非空；或 `ReasoningSwipes` 中有任意非空字符串。

### 3.3 LLM 接口设计（Go）

**非流式：**

```go
type LLMReasoningResponse struct {
    Content   string
    Reasoning *string
}

func GenerateWithReasoning(promptCtx PromptContext, cfg LLMConfig) (LLMReasoningResponse, error)
```

**流式：**

```go
type ReasoningChunk struct {
    Content         *string
    Reasoning       *string
    IsReasoningChunk bool
}

func GenerateStreamWithReasoning(promptCtx PromptContext, cfg LLMConfig) (<-chan ReasoningChunk, error)
```

解析逻辑示例（伪代码）：

```go
for chunk := range ch {
    if chunk.IsReasoningChunk && chunk.Reasoning != nil {
        reasoningBuffer.WriteString(*chunk.Reasoning)
    }
    if chunk.Content != nil {
        contentBuffer.WriteString(*chunk.Content)
    }
    // 把当前 buffer 写回当前 assistant 消息，前端即可实时显示
}
```

- OpenAI o1/o3：从 `choice.message.reasoning_content` 或自定义扩展字段中解析。
- Claude：从 `thinking` 字段解析。
- Gemini：从 `thought` 或增强字段解析。

### 3.4 前端渲染（React）

示例：

```tsx
function MessageView({ message }: { message: ChatMessage }) {
  return (
    <div className="message">
      <div className="content">{renderMarkdownOrHtml(message.content)}</div>

      {message.hasReasoning && (
        <ReasoningPanel
          label="Thinking"
          content={message.currentReasoning ?? ""}
        />
      )}
    </div>
  );
}
```

`ReasoningPanel`：

- 折叠 / 展开。
- 文本可复制。
- UI 上与主内容区明显区分（浅色背景、小字体等）。

---

## 四、聊天功能（Chat Flow）

### 4.1 目标

- 封装完整一轮对话的流程：
    1. 记录用户消息。
    2. 做摘要/裁剪历史（可选）。
    3. 根据 PromptManager + 世界信息 + 宏/变量 构造 prompt。
    4. 调用 LLM（流式/非流式 + reasoning）。
    5. 写入 assistant 消息，并更新前端状态。

### 4.2 核心流程（伪代码）

```go
func (svc *ChatService) SendMessage(userId, chatId, input string, cfg LLMConfig, atts []ChatAttachment) error {
    chat := repo.GetChat(chatId)
    character := repo.GetCharacter(chat.CharacterID)
    history := repo.ListMessages(chatId)

    // 1. 写 user 消息
    userMsg := ChatMessage{
        ID:        newID(),
        ChatID:    chatId,
        Role:      "user",
        Content:   input,
        Timestamp: time.Now(),
        Swipes:    []string{input},
        // Attachments: atts, ...
    }
    repo.AddMessage(userMsg)

    // 2. 可选：基于 token 限制做摘要或丢弃最老历史
    svc.checkAndSummarize(chat, history, cfg)

    // 3. 构建 prompt 上下文
    promptCtx := svc.BuildPromptContext(userId, chat, character, history, input)

    // 4. LLM 调用
    if cfg.Stream {
        return svc.streamAssistantResponse(chatId, promptCtx, cfg)
    }
    return svc.oneShotAssistantResponse(chatId, promptCtx, cfg)
}
```

### 4.3 BuildPromptContext 的职责

- 从 PromptManager 获取启用的 PromptSection（排序后）。
- 从世界信息系统取匹配条目（按关键词、优先级、位置）。
- 按「深度注入」规则遍历历史消息，决定在每条消息前插入哪些 PromptSection / 世界信息 / 作者注释：
    - 定义 `depthFromEnd = total-1 - i`。
    - 若 `section.InjectionDepth == depthFromEnd` → 在该消息之前插入对应提示。
- 对所有文本块跑：
    1. `ProcessVariableMacros(...)`
    2. `ProcessMacros(...)`
- 输出统一形式的 prompt，例如 `[]OpenAIMessage{ {role, content}, ... }`，交给 LLMProvider 层。

---

## 五、提示词管理（Prompt Management）

### 5.1 目标

- 把 prompt 拆成若干「段」，每段可：
    - 单独启用/禁用。
    - 调整顺序。
    - 指定注入深度（在倒数第几条消息前插入）。
- 与 SillyTavern 的 `prompts` / `prompt_order` JSON 兼容。

### 5.2 数据模型

```go
type PromptSectionType string

const (
    SectionSystemPrompt         PromptSectionType = "systemPrompt"
    SectionPersona              PromptSectionType = "persona"
    SectionCharacterDescription PromptSectionType = "characterDescription"
    SectionCharacterPersonality PromptSectionType = "characterPersonality"
    SectionCharacterScenario    PromptSectionType = "characterScenario"
    SectionExampleMessages      PromptSectionType = "exampleMessages"
    SectionWorldInfo            PromptSectionType = "worldInfo"
    SectionWorldInfoAfter       PromptSectionType = "worldInfoAfter"
    SectionAuthorNote           PromptSectionType = "authorNote"
    SectionPostHistoryInstr     PromptSectionType = "postHistoryInstructions"
    SectionNsfw                 PromptSectionType = "nsfw"
    SectionChatHistory          PromptSectionType = "chatHistory"
    SectionEnhanceDefinitions   PromptSectionType = "enhanceDefinitions"
    SectionCustom               PromptSectionType = "custom"
)

type PromptSection struct {
    Type   PromptSectionType
    Name   string
    Enabled bool
    Order  int

    Content    *string
    Identifier *string // ST 中的 identifier
    Role       *string // "system" / "user" / "assistant"
    InjectionPosition *int
    InjectionDepth    *int
}
```

### 5.3 PromptManager 服务

```go
type PromptManager struct {
    Sections []PromptSection
}

func (pm *PromptManager) EnabledSections() []PromptSection {
    // 过滤 Enabled，并按 Order 排好
}
```

从 SillyTavern 导入：

1. 建一个 `identifier -> PromptSectionType` 映射。
2. 解析 `prompts`（内容）和 `prompt_order`（顺序 & enabled），生成 `PromptSection`。
3. 对不在映射表里的 identifier，统一归类为 `SectionCustom`。

### 5.4 深度注入逻辑

在构建 prompt 时，遍历历史消息 `messages`：

```go
N := len(messages)
for i, msg := range messages {
    depthFromEnd := N - 1 - i

    // 1. 深度注入世界信息
    for _, entry := range depthWorldInfo {
        if entry.Depth == depthFromEnd {
            systemMsg := buildWorldInfoMessage(entry)
            promptMessages = append(promptMessages, systemMsg)
        }
    }

    // 2. 深度注入 PromptSection
    for _, sec := range depthBasedSections {
        if sec.InjectionDepth != nil && *sec.InjectionDepth == depthFromEnd {
            secMsgs := buildSectionMessages(sec, ctx)
            promptMessages = append(promptMessages, secMsgs...)
        }
    }

    // 3. Author’s Note 深度注入
    // ...

    // 4. 加入当前 chat 消息本身（user / assistant）
    promptMessages = append(promptMessages, convertChatMessage(msg))
}
```

---