# Verity 扩展增强 Mod 完整教程文档

> **Mod ID:** `verity_extended`\
> **适用版本:** Minecraft 1.20.1 + Forge 47.4.21\
> **前置 Mod:** Verity（原版 NPC 对话 Mod）\
> **Java 版本:** Java 17

***

## 目录

1. [项目概述](#1-项目概述)
2. [架构总览](#2-架构总览)
3. [安装指南](#3-安装指南)
4. [配置详解](#4-配置详解)
5. [功能模块](#5-功能模块)
6. [使用教程](#6-使用教程)
7. [常见报错与解决方案](#7-常见报错与解决方案)
8. [联机说明](#8-联机说明)
9. [FAQ](#9-faq)

***

## 1. 项目概述

### 1.1 这是什么

Verity 扩展增强 Mod 是原版 Verity NPC 对话 Mod 的扩展插件。它**不修改原版 Verity 的任何代码**，而是通过以下方式增强原版功能：

- **本地代理服务器**：在游戏内启动 HTTP 代理，拦截并转换原版 Verity 的 AI 请求
- **多服务商支持**：支持 OpenAI、DeepSeek、通义千问、智谱 AI、Ollama 等多种 AI 服务商
- **语音输入 (STT)**：支持在线 API 识别和本地 Vosk 离线识别
- **语音合成 (TTS)**：支持在线 API 合成和本地 ONNX 模型合成
- **角色人设系统**：内置 8 种角色预设，支持自定义提示词文件
- **游戏动作执行**：AI 回复可触发游戏内动作（给物品、治疗、传送等）
- **主动感知**：根据游戏事件（死亡、低血量、睡觉等）主动触发 AI 发言
- **原版 Verity 代理**：可选择语音输入/语音合成直接走原版 Verity 原生链路

### 1.2 设计原则

- **零侵入**：不修改原版 Verity 代码，仅通过代理层和反射桥实现兼容
- **配置驱动**：所有功能通过配置文件控制，支持游戏内配置界面
- **优雅降级**：原版不可用时自动回退到扩展实现，不会崩溃
- **多人兼容**：仅主机需要安装配置，联机时其他玩家无需额外设置

***

## 2. 架构总览

### 2.1 核心架构图

```
┌─────────────────────────────────────────────────────────┐
│                    Minecraft 客户端                       │
│                                                         │
│  ┌──────────┐   ┌──────────────┐   ┌─────────────────┐ │
│  │ Verity   │   │ 扩展增强 Mod  │   │  原版 Verity    │ │
│  │ 原版Mod  │◄──┤ 代理层 + 桥接 │──►│  (varmite.*)    │ │
│  └──────────┘   └──────┬───────┘   └─────────────────┘ │
│                        │                                │
└────────────────────────┼────────────────────────────────┘
                         │
                    ┌────▼────┐
                    │ 本地代理 │  (端口 4000)
                    │ 服务器  │
                    └────┬────┘
                         │
              ┌──────────┼──────────┐
              ▼          ▼          ▼
         ┌────────┐ ┌────────┐ ┌────────┐
         │ Chat   │ │ STT    │ │ TTS    │
         │ API    │ │ API    │ │ API    │
         └────────┘ └────────┘ └────────┘
```

### 2.2 模块说明

| 模块    | 包路径                           | 核心功能                        |
| ----- | ----------------------------- | --------------------------- |
| 主入口   | `com.hanchen.veritycustomapi` | Mod 初始化、配置注册、代理服务器启停        |
| AI 服务 | `.ai`                         | Chat/STT/TTS API 请求构建与发送    |
| 语音识别  | `.stt`                        | 录音采集、在线/离线/原版识别             |
| 语音合成  | `.tts`                        | 在线/离线/原版语音合成与播放             |
| 原版桥接  | `.compat`                     | 反射调用原版 Verity 的录音/转写/TTS/对话 |
| 客户端事件 | `.client`                     | 按键绑定、主动感知、客户端事件处理           |
| 配置    | `.config`                     | Forge 配置定义与配置界面             |
| 游戏动作  | `.action`                     | AI 回复解析与游戏内动作执行             |

### 2.3 请求链路

**对话流程：**

1. 玩家在游戏内发送聊天消息
2. 原版 Verity 的 `ServerChatEvent` 拦截消息
3. 原版 Verity 向 `http://127.0.0.1:4000/v1/chat/completions` 发送 OpenAI 格式请求
4. 本地代理服务器接收请求，注入系统提示词（人设）
5. 代理服务器将请求转发到用户配置的真实 AI API
6. AI 返回 JSON 格式回复（包含 response/action/emotion）
7. 代理服务器包装为 Verity 原生格式返回
8. 原版 Verity 显示回复并触发 TTS

**语音输入流程：**

1. 玩家按下 V 键
2. 扩展 Mod 根据配置模式选择录音方式
3. 松开 V 键后，音频数据发送到 STT API 或本地 Vosk
4. 识别结果作为聊天消息发送

**语音合成流程：**

1. 原版 Verity 发送 TTS 请求
2. 扩展 Mod 根据配置模式选择合成方式
3. 合成的 WAV 音频通过 Java Sound 播放

***

## 3. 安装指南

### 3.1 环境要求

- Minecraft 1.20.1
- Forge 47.4.21 或更高版本
- Java 17
- 原版 Verity Mod（必须已安装）

### 3.2 安装步骤

1. 将 `veritycustomapi-1.0.1.jar` 放入 `.minecraft/mods/` 目录
2. 确保原版 Verity Mod 也在 `mods/` 目录中
3. 启动游戏
4. 首次启动会自动生成配置文件：
   - `config/verity_extended-common.toml` — 核心配置
   - `config/verity_extended-client.toml` — 客户端配置

### 3.3 验证安装

启动游戏后，检查日志中是否出现：

```
Verity扩展增强模组加载完成
代理服务器已启动，端口：4000
Verity扩展增强模组初始化完成
```

***

## 4. 配置详解

### 4.1 配置文件位置

| 文件    | 位置                                   | 说明                 |
| ----- | ------------------------------------ | ------------------ |
| 核心配置  | `config/verity_extended-common.toml` | LLM、STT、TTS、代理服务器等 |
| 客户端配置 | `config/verity_extended-client.toml` | 内置 API 开关、主动感知     |

### 4.2 核心配置 (verity\_extended-common.toml)

#### \[server] — 代理服务器

| 配置项    | 默认值    | 范围      | 说明                         |
| ------ | ------ | ------- | -------------------------- |
| `port` | `4000` | 1-65535 | 代理服务器监听端口，需与原版 Verity 配置一致 |

#### \[llm] — 大语言模型配置

| 配置项                          | 默认值                                 | 说明                             |
| ---------------------------- | ----------------------------------- | ------------------------------ |
| `apiProvider`                | `CUSTOM_OPENAI`                     | AI 服务商，可选值见下表                  |
| `apiUrl`                     | `""` (空)                            | API 完整地址，自定义模式必填               |
| `apiKey`                     | `""` (空)                            | API 密钥                         |
| `model`                      | `""` (空)                            | 模型名称                           |
| `enableCustomPrompt`         | `false`                             | 是否启用自定义提示词（关闭则使用原版 Verity 提示词） |
| `useOriginalVerityChatChain` | `true`                              | 是否由本 Mod 代理调用原版 Verity 对话链路    |
| `selectedPreset`             | `ORIGINAL_VERITY`                   | 当前选中的人设预设                      |
| `customPromptFile`           | `./config/verity_custom_prompt.txt` | 自定义提示词文件路径                     |
| `requestTimeout`             | `30`                                | 请求超时时间（秒），范围 5-300             |

**LLM 服务商列表 (apiProvider 可选值)：**

| 枚举值             | 显示名称            | API 地址                                               | 默认模型            |
| --------------- | --------------- | ---------------------------------------------------- | --------------- |
| `CUSTOM_OPENAI` | 自定义 (OpenAI 兼容) | 用户填写                                                 | 用户填写            |
| `Ollama`        | Ollama 本地运行     | `http://127.0.0.1:11434/v1/`                         | `qwen2.5:7b`    |
| `OPENAI`        | OpenAI 官方       | `https://api.openai.com/v1/`                         | `gpt-3.5-turbo` |
| `DEEPSEEK`      | DeepSeek        | `https://api.deepseek.com/v1/`                       | `deepseek-chat` |
| `QWEN`          | 通义千问            | `https://dashscope.aliyuncs.com/compatible-mode/v1/` | `qwen-plus`     |
| `ZHIPU`         | 智谱 AI           | `https://open.bigmodel.cn/api/paas/v4/`              | `glm-4-flash`   |

#### \[speech\_recognition] — 语音识别配置

| 配置项                | 默认值                            | 说明                                                                   |
| ------------------ | ------------------------------ | -------------------------------------------------------------------- |
| `enableVoiceInput` | `true`                         | 是否启用语音输入                                                             |
| `mode`             | `local`                        | 识别模式：`local` 本地Vosk / `api` 在线接口 / `original` 原版Verity               |
| `apiProvider`      | `CUSTOM_OPENAI`                | 在线 STT 服务商                                                           |
| `apiUrl`           | `""` (空)                       | STT API 地址                                                           |
| `apiKey`           | `""` (空)                       | STT API 密钥                                                           |
| `model`            | `""` (空)                       | STT 模型名称                                                             |
| `requestFormat`    | `multipart`                    | 请求格式：`multipart` / `json` / `url_encoded`                            |
| `authType`         | `bearer`                       | 认证方式：`bearer` / `api_key_header` / `api_key_param` / `custom_header` |
| `responseField`    | `text`                         | 响应中提取文本的字段名                                                          |
| `voskModelPath`    | `./config/vosk-model-small-cn` | 本地 Vosk 模型路径                                                         |
| `sampleRate`       | `16000`                        | 音频采样率，范围 8000-48000                                                  |

**STT 服务商列表 (apiProvider 可选值)：**

| 枚举值             | 显示名称           | 默认模型                          |
| --------------- | -------------- | ----------------------------- |
| `CUSTOM_OPENAI` | 自定义 (OpenAI兼容) | 用户填写                          |
| `OPENAI`        | OpenAI         | `whisper-1`                   |
| `GROQ`          | Groq           | `whisper-large-v3`            |
| `DEEPSEEK`      | DeepSeek       | `whisper-large-v3`            |
| `SILICONFLOW`   | SiliconFlow    | `FunAudioLLM/SenseVoiceSmall` |
| `AZURE`         | Azure          | `whisper-1`                   |
| `BYTEDANCE`     | 字节跳动火山引擎       | —                             |
| `ALIBABA`       | 阿里云            | —                             |
| `TENCENT`       | 腾讯云            | —                             |
| `BAIDU`         | 百度智能云          | —                             |
| `IFLYTEK`       | 科大讯飞           | —                             |

#### \[text\_to\_speech] — 语音合成配置

| 配置项           | 默认值                  | 说明                                                        |
| ------------- | -------------------- | --------------------------------------------------------- |
| `enableTts`   | `true`               | 是否启用 TTS                                                  |
| `mode`        | `online`             | TTS 模式：`local` 本地离线 / `online` 在线接口 / `original` 原版Verity |
| `sampleRate`  | `22050`              | TTS 音频采样率，范围 8000-48000                                   |
| `modelPath`   | `./config/tts-model` | 本地 TTS 模型路径                                               |
| `speed`       | `1.0`                | 语音语速，范围 0.25-4.0                                          |
| `volume`      | `1.0`                | 语音音量，范围 0.0-2.0                                           |
| `apiProvider` | `CUSTOM_OPENAI`      | 在线 TTS 服务商                                                |
| `apiUrl`      | `""` (空)             | TTS API 地址                                                |
| `apiKey`      | `""` (空)             | TTS API 密钥                                                |
| `apiModel`    | `""` (空)             | TTS 模型名称                                                  |
| `apiVoice`    | `alloy`              | TTS 音色名称                                                  |

**TTS 服务商列表 (apiProvider 可选值)：**

| 枚举值               | 显示名称            | 请求格式        | 认证方式    | 默认音色                 |
| ----------------- | --------------- | ----------- | ------- | -------------------- |
| `CUSTOM_OPENAI`   | 自定义 (OpenAI 兼容) | openai      | bearer  | alloy                |
| `OPENAI_TTS`      | OpenAI 官方 TTS   | openai      | bearer  | alloy                |
| `KOKORO`          | Kokoro 本地 TTS   | openai      | bearer  | am\_fenrir           |
| `DEEPSEEK_TTS`    | DeepSeek 语音     | openai      | bearer  | alloy                |
| `ALIBABA_TTS`     | 阿里云 TTS         | alibaba     | alibaba | zh-CN-XiaoxiaoNeural |
| `TENCENT_TTS`     | 腾讯云 TTS         | tencent     | tencent | Zhiyu                |
| `BAIDU_TTS`       | 百度智能云 TTS       | baidu       | baidu   | 0                    |
| `BYTEDANCE_TTS`   | 火山引擎 TTS        | bytedance   | bearer  | —                    |
| `IFLYTEK_TTS`     | 讯飞开放平台 TTS      | iflytek     | iflytek | xiaoyan              |
| `SILICONFLOW_TTS` | 硅基流动 TTS        | siliconflow | bearer  | —                    |
| `MOONSHOT_TTS`    | Moonshot 语音     | moonshot    | bearer  | zh-CN-1              |
| `QIANWAN_TTS`     | 千帆大模型 TTS       | qianwan     | bearer  | —                    |
| `MIMO_TTS`        | 小米 MiMo TTS     | mimo        | api-key | 苏打                   |

**MiMo TTS 专用音色：**

| 枚举值        | 音色名 |
| ---------- | --- |
| `BINGTANG` | 冰糖  |
| `MOLI`     | 茉莉  |
| `SUDA`     | 苏打  |
| `BAIHUA`   | 白桦  |

#### \[transit] — Transit 中转配置

| 配置项              | 默认值                        | 说明                           |
| ---------------- | -------------------------- | ---------------------------- |
| `enableChat`     | `false`                    | 是否启用 Transit 中转（Chat）        |
| `enableTts`      | `false`                    | 是否启用 Transit 中转（TTS）         |
| `enableStt`      | `false`                    | 是否启用 Transit 中转（STT）         |
| `apiUrl`         | `https://api.st68.icu/api` | Transit 中转服务器地址              |
| `chatProvider`   | `""` (空)                   | Transit Chat provider，留空自动推断 |
| `ttsProvider`    | `""` (空)                   | Transit TTS provider，留空自动推断  |
| `sttProvider`    | `""` (空)                   | Transit STT provider，留空自动推断  |
| `requestTimeout` | `60`                       | Transit 请求超时（秒），范围 5-300     |

#### \[debug] — 调试配置

| 配置项                             | 默认值     | 说明                    |
| ------------------------------- | ------- | --------------------- |
| `runtimeMetrics`                | `false` | 是否输出运行时内存/线程/队列诊断日志   |
| `runtimeMetricsIntervalSeconds` | `60`    | 诊断日志输出间隔（秒），范围 5-3600 |

### 4.3 客户端配置 (verity\_extended-client.toml)

#### \[builtin\_api] — 内置 API 开关

| 配置项              | 默认值     | 说明                        |
| ---------------- | ------- | ------------------------- |
| `enableChatApis` | `false` | 启用内置 Chat 服务商（关闭则使用自定义配置） |
| `enableSttApis`  | `false` | 启用内置 STT 服务商（关闭则使用自定义配置）  |
| `enableTtsApis`  | `false` | 启用内置 TTS 服务商（关闭则使用自定义配置）  |
| `mimoTtsVoice`   | `苏打`    | 内置 MiMo TTS 专用音色          |

> **注意：** 当 `enableChatApis` / `enableSttApis` / `enableTtsApis` 设为 `true` 时，会忽略用户自定义的 API 配置，使用内置 API 地址和密钥。`original` 模式优先级最高，不受此开关影响。

#### \[proactive\_awareness] — 主动感知配置

| 配置项                    | 默认值     | 说明                     |
| ---------------------- | ------- | ---------------------- |
| `enabled`              | `false` | 是否允许 Verity 根据游戏事件主动发言 |
| `pauseEvent`           | `true`  | 打开暂停菜单时是否主动发言          |
| `deathEvent`           | `true`  | 玩家死亡时是否主动发言            |
| `lowHealthEvent`       | `true`  | 生命值 ≤25% 时是否主动发言       |
| `sleepEvent`           | `true`  | 睡觉/醒来时是否主动发言           |
| `worldEvent`           | `true`  | 进入/退出世界时是否主动发言         |
| `cooldownSeconds`      | `300`   | 全局冷却时间（秒），范围 30-3600   |
| `desktopNotifications` | `false` | 游戏窗口不活跃时是否显示系统托盘通知     |

***

## 5. 功能模块

### 5.1 对话系统 (Chat)

**工作原理：**

扩展 Mod 在游戏内启动一个本地 HTTP 代理服务器（默认端口 4000）。原版 Verity 的 AI 请求会被发送到这个代理服务器，代理服务器完成以下工作：

1. 注入系统提示词（人设预设）
2. 将请求转发到用户配置的真实 AI API
3. 对 AI 返回的内容进行 JSON 格式包装
4. 将包装后的响应返回给原版 Verity

**AI 回复格式要求：**

AI 必须返回 JSON 格式，包含三个字段：

```json
{
  "response": "你对玩家说的自然语言回复",
  "action": "none",
  "emotion": "neutral"
}
```

**可用游戏动作 (action 字段)：**

| 动作                | 参数                                    | 说明    |
| ----------------- | ------------------------------------- | ----- |
| `none`            | —                                     | 无特殊动作 |
| `answer`          | —                                     | 回答问题  |
| `follow`          | —                                     | 跟随玩家  |
| `stop_follow`     | —                                     | 停止跟随  |
| `teleport_player` | `<x> <y> <z>`                         | 传送玩家  |
| `set_weather`     | `clear` / `rain` / `thunder`          | 设置天气  |
| `set_time`        | `day` / `night` / `noon` / `midnight` | 设置时间  |
| `give_item`       | `<item_name> <count>`                 | 给予物品  |
| `heal_player`     | —                                     | 治疗玩家  |
| `feed_player`     | —                                     | 喂食玩家  |
| `enchant_item`    | `<enchantment> <level>`               | 附魔物品  |
| `dance`           | —                                     | 跳舞    |
| `sit`             | —                                     | 坐下    |
| `stand`           | —                                     | 站立    |

**情绪值 (emotion 字段)：**

`neutral` / `happy` / `sad` / `angry` / `surprised` / `worried` / `excited` / `shy` / `tsundere` / `cold` / `lazy` / `mysterious` / `serious`

### 5.2 角色人设预设

内置 8 种角色预设，可在配置中通过 `selectedPreset` 选择：

| 枚举值                 | 显示名称       | 性格描述               |
| ------------------- | ---------- | ------------------ |
| `ORIGINAL_VERITY`   | 原版Verity助手 | 友善智慧的 Minecraft 助手 |
| `CAT_GIRL`          | 软萌猫娘助手     | 温柔可爱的猫娘，称呼玩家为主人    |
| `TSUNDERE_VILLAGER` | 傲娇村民助手     | 嘴硬心软的村民少女          |
| `SALTY_FISH`        | 咸鱼摸鱼村民     | 懒洋洋的咸鱼，总劝玩家歇一歇     |
| `PETRA`             | 探险向导佩特拉    | 干练利落的探险向导          |
| `ENDERMAN`          | 毒舌末影人      | 高冷带刺的末影人           |
| `ALCHEMIST`         | 流浪炼金术士     | 神秘悠远的炼金术士          |
| `OLD_PRIEST`        | 老牧师        | 暴躁抽象的网络热梗整合角色      |
| `CUSTOM_FILE`       | 外部自定义文件    | 从外部文件读取提示词         |

**自定义提示词文件：**

1. 在配置中设置 `enableCustomPrompt = true`
2. 设置 `selectedPreset = CUSTOM_FILE`
3. 创建提示词文件（默认路径 `./config/verity_custom_prompt.txt`）
4. 文件支持 UTF-8 和 GBK 编码（自动检测）

### 5.3 语音输入 (STT)

**三种模式：**

| 模式        | 配置值        | 说明                    | 依赖             |
| --------- | ---------- | --------------------- | -------------- |
| 本地离线      | `local`    | 使用 Vosk 引擎本地识别        | 需下载 Vosk 模型    |
| 在线接口      | `api`      | 调用在线 STT API          | 需配置 API 地址和密钥  |
| 原版 Verity | `original` | 直接代理原版 Verity 录音+转写链路 | 需原版 Verity 已安装 |

**按键操作：**

- 默认按键：`V` 键
- 按下：开始录音
- 松开：结束录音并识别
- 录音时会自动停止当前 TTS 朗读

**原版 Verity 代理模式：**

选择 `original` 模式时，语音输入流程完全复用原版 Verity 的链路：

1. 通过反射获取原版 `KeybindHandler.getRecorder()` 录音器
2. 调用原版 `MicrophoneRecorder.startRecording()` 开始录音
3. 松开时调用 `MicrophoneRecorder.stopRecording()` 获取录音数据
4. 调用原版 `AiAPI.transcribeAudio(bytes, audioFormat)` 进行转写
5. 通过原版 `KeybindHandler.accept(text)` 提交识别结果
6. 原版处理空结果过滤、`thank you.` 过滤、256 字符裁切
7. 最终由原版发送聊天消息

### 5.4 语音合成 (TTS)

**三种模式：**

| 模式        | 配置值        | 说明                       | 依赖             |
| --------- | ---------- | ------------------------ | -------------- |
| 本地离线      | `local`    | 使用 ONNX Runtime 本地合成     | 需下载 ONNX 模型    |
| 在线接口      | `online`   | 调用在线 TTS API             | 需配置 API 地址和密钥  |
| 原版 Verity | `original` | 直接调用原版 `AiAPI.playTTS()` | 需原版 Verity 已安装 |

**音频格式：**

- 统一使用 WAV 格式（Java AudioSystem 原生支持）
- 在线 TTS 返回的音频会动态解析 WAV 文件头（采样率、声道数、位深）
- 不支持 MP3 格式（避免 MP3SPI 依赖问题）

**文本处理：**

- 自动过滤控制字符和 Emoji（使用 Java 17 兼容的 Unicode 范围）
- 限制最大 2000 字符
- 移除名称前缀（如 `<Verity>`、`Verity:` 等）

### 5.5 主动感知

主动感知允许 Verity NPC 根据游戏内事件自动发起对话，而不需要玩家先说话。

**触发事件：**

| 事件   | 配置项              | 触发条件         |
| ---- | ---------------- | ------------ |
| 进入世界 | `worldEvent`     | 玩家进入世界时      |
| 死亡   | `deathEvent`     | 玩家死亡时        |
| 低血量  | `lowHealthEvent` | 生命值降至 25% 以下 |
| 睡觉   | `sleepEvent`     | 玩家睡觉或醒来      |
| 暂停菜单 | `pauseEvent`     | 打开暂停菜单       |

**行为说明：**

- 所有事件共享一个全局冷却时间（默认 5 分钟）
- AI 请求失败时显示本地兜底回复
- AI 请求超时（10 秒）后强制释放状态并显示兜底回复
- 退出世界时不触发请求（服务器正在关闭）

### 5.6 游戏动作执行

AI 回复中的 `action` 字段会被解析并执行。动作通过 `GameActionHandler` 在服务器 Tick 事件中排队执行，避免线程安全问题。

**动作执行流程：**

1. 代理服务器解析 AI 回复中的 `action` 字段
2. 动作被放入 `ConcurrentLinkedQueue` 队列
3. 服务器 Tick 事件中依次取出并执行
4. 执行结果通过聊天消息反馈给玩家

### 5.7 Transit 中转服务

Transit 中转是一个可选的 API 代理层，适用于无法直接访问 AI API 的场景。

**工作方式：**

- 扩展 Mod 将请求发送到 Transit 中转服务器
- Transit 服务器转发到真实 AI API
- 支持 Chat / TTS / STT 三种中转

**配置方法：**

1. 设置 `transit.enableChat` / `transit.enableTts` / `transit.enableStt` 为 `true`
2. 配置 `transit.apiUrl` 为中转服务器地址
3. provider 留空则自动从当前 API 服务商推断

### 5.8 内置 API 服务

内置 API 是一组预配置的 AI 服务，开启后无需自行填写 API 地址和密钥。

**内置服务：**

| 类型   | 服务商          | 模型                              |
| ---- | ------------ | ------------------------------- |
| Chat | VectorEngine | `gemini-3.1-flash-lite-preview` |
| STT  | SiliconFlow  | `TeleAI/TeleSpeechASR`          |
| TTS  | MiMo TTS     | `mimo-v2.5-tts`                 |

**开启方式：**
在客户端配置 `verity_extended-client.toml` 中设置对应开关为 `true`。

> **优先级：** `original` 模式 > 内置 API > 自定义配置

***

## 6. 使用教程

### 6.1 快速开始（使用内置 API）

1. 安装 Mod 并启动游戏
2. 打开客户端配置文件 `verity_extended-client.toml`
3. 将 `enableChatApis`、`enableSttApis`、`enableTtsApis` 都设为 `true`
4. 重启游戏
5. 在游戏中与 Verity NPC 对话，或按 `V` 键使用语音输入

### 6.2 自定义 AI 服务配置

1. 在 `verity_extended-common.toml` 的 `[llm]` 段配置：
   ```toml
   [llm]
   apiProvider = "DEEPSEEK"
   apiUrl = "https://api.deepseek.com/v1/chat/completions"
   apiKey = "你的API密钥"
   model = "deepseek-chat"
   enableCustomPrompt = true
   selectedPreset = "CAT_GIRL"
   ```
2. 如果使用 OpenAI 兼容的自定义服务：
   ```toml
   apiProvider = "CUSTOM_OPENAI"
   apiUrl = "https://your-api.com/v1/chat/completions"
   apiKey = "your-key"
   model = "your-model"
   ```

### 6.3 配置语音输入

**在线 API 模式：**

```toml
[speech_recognition]
enableVoiceInput = true
mode = "api"
apiProvider = "SILICONFLOW"
apiUrl = "https://api.siliconflow.cn/v1/audio/transcriptions"
apiKey = "你的API密钥"
model = "FunAudioLLM/SenseVoiceSmall"
requestFormat = "multipart"
authType = "bearer"
responseField = "text"
```

**本地 Vosk 模式：**

```toml
[speech_recognition]
enableVoiceInput = true
mode = "local"
voskModelPath = "./config/vosk-model-small-cn"
```

**原版 Verity 模式：**

```toml
[speech_recognition]
enableVoiceInput = true
mode = "original"
```

### 6.4 配置语音合成

**在线 API 模式：**

```toml
[text_to_speech]
enableTts = true
mode = "online"
apiProvider = "MIMO_TTS"
apiUrl = "https://ai.mocwl.top/v1/chat/completions"
apiKey = "你的API密钥"
apiModel = "mimo-v2.5-tts"
apiVoice = "苏打"
```

**原版 Verity 模式：**

```toml
[text_to_speech]
enableTts = true
mode = "original"
```

### 6.5 启用主动感知

在客户端配置 `verity_extended-client.toml` 中：

```toml
[proactive_awareness]
enabled = true
pauseEvent = true
deathEvent = true
lowHealthEvent = true
sleepEvent = true
worldEvent = true
cooldownSeconds = 300
```

### 6.6 使用自定义提示词

1. 在配置中设置：
   ```toml
   [llm]
   enableCustomPrompt = true
   selectedPreset = "CUSTOM_FILE"
   customPromptFile = "./config/my_prompt.txt"
   ```
2. 创建 `config/my_prompt.txt` 文件，写入你的提示词内容
3. 文件支持 UTF-8 和 GBK 编码

***

## 7. 常见报错与解决方案

### 7.1 游戏崩溃

#### `NoSuchMethodError: ClientLevel.dimension()` / `LocalPlayer.getX()` 等

**原因：** 主动感知模块调用了运行时 SRG 命名环境中不存在的 Mojang 命名方法。

**解决方案：** 更新到最新版本的扩展 Mod。已修复的版本不再直接调用这些高风险映射方法。

#### `ClassNotFoundException: varmite.verity.*`

**原因：** 原版 Verity Mod 未安装或未正确加载。

**解决方案：**

1. 确认 `mods/` 目录中有原版 Verity Mod jar
2. 确认原版 Verity 版本与 Forge 版本兼容
3. 如果不使用原版代理模式，将 STT/TTS 模式从 `original` 改为 `local` 或 `api`/`online`

#### `NoClassDefFoundError: org.vosk.*` / `ai.onnxruntime.*`

**原因：** 本地离线识别/合成的第三方库未加载。

**解决方案：**

1. 切换到在线模式（`mode = "api"` / `mode = "online"`）
2. 或确保相关库文件已正确打包在 Mod jar 中

### 7.2 对话不显示

#### AI 回复为空或显示异常

**排查步骤：**

1. 检查 `latest.log` 中是否有 `代理服务器已启动，端口：4000`
2. 检查原版 Verity 配置中 AI endpoint 是否指向 `http://127.0.0.1:4000`
3. 检查 `verity_extended-common.toml` 中 `apiUrl` 和 `apiKey` 是否正确
4. 查看日志中是否有 HTTP 错误状态码

#### `Failed to parse AI response as JSON`

**原因：** AI 返回的内容不是标准 JSON 格式。

**解决方案：**

- 扩展 Mod 已在代理层做 JSON 格式包装兜底
- 如果仍然出现，检查 AI 模型是否支持 system prompt 指令
- 尝试更换为更遵循指令的模型（如 `gpt-3.5-turbo`、`deepseek-chat`）

#### 联机时其他玩家看不到聊天文字

**原因：** 对话代理事件取消了聊天广播。

**解决方案：** 更新到最新版本。当前版本不再取消普通聊天事件，文字会正常广播给所有玩家。

### 7.3 语音输入问题

#### 按 V 键无反应

**排查步骤：**

1. 检查 `enableVoiceInput = true`
2. 检查按键是否被其他 Mod 冲突
3. 查看 `latest.log` 中是否有语音识别相关日志
4. 如果使用 `original` 模式，检查原版 Verity 是否已加载

#### 识别结果为空

**可能原因：**

- 录音时间太短（建议至少说 1 秒）
- 麦克风权限未授予
- 采样率不匹配（默认 16000Hz）
- API 密钥无效或过期

**在线 API 模式排查：**

1. 查看 `latest.log` 中是否有 STT API 请求日志
2. 检查 HTTP 状态码
3. 确认 `requestFormat = "multipart"`（OpenAI/SiliconFlow 要求）
4. 确认 `responseField` 与 API 返回格式匹配

#### `original` 模式未走原版链路

**排查步骤：**

1. 确认配置 `mode = "original"`（不是 `"api"` 或 `"local"`）
2. 确认 `enableSttApis = false`（内置 API 开启时会覆盖为 `api`）
3. 查看日志中是否出现 `已接入原版 Verity 语音录音器`
4. 如果出现 `创建原版 Verity 语音输入代理失败`，说明原版类未找到

### 7.4 语音合成问题

#### TTS 没有声音

**排查步骤：**

1. 检查 `enableTts = true`
2. 检查 `mode` 配置是否正确
3. 查看日志中是否有 TTS 请求和响应日志
4. 检查音频格式是否为 WAV
5. 检查 `volume` 是否大于 0

#### TTS 音频播放断断续续

**可能原因：**

- 网络延迟导致音频分块到达
- Java Sound 线程被中断

**解决方案：**

- 使用本地离线 TTS 模式
- 或使用离原版 Verity TTS 更近的 API 节点
- 调整 `speed` 参数（过高可能导致问题）

#### MiMo TTS 返回错误

**注意事项：**

- 模型必须使用 `mimo-v2.5-tts`（不支持 voiceclone/voicedesign）
- 参考音频（语音克隆）需 Base64 编码，大小 ≤10MB
- 参考音频格式仅支持 mp3 和 wav
- MIME 类型必须为 `audio/mpeg`、`audio/mp3` 或 `audio/wav`
- 响应类型判断使用 `responseType` 字段（不是 `responseFormat`）

### 7.5 代理服务器问题

#### 端口 4000 被占用

**解决方案：**

1. 修改 `verity_extended-common.toml` 中 `server.port`
2. 同时修改原版 Verity 配置中的 AI endpoint 端口
3. 重启游戏

#### `SSLHandshakeException` / 证书错误

**原因：** HTTPS 连接证书验证失败。

**解决方案：** 扩展 Mod 已内置全局 SSL 信任配置。如果仍然出现：

1. 确认 API 地址使用 HTTPS
2. 检查系统时间是否正确（证书验证依赖系统时间）
3. 更新 Java 17 到最新版本

#### API 请求超时

**解决方案：**

1. 增大 `requestTimeout`（默认 30 秒）
2. 检查网络连接
   3- 如果使用 Ollama 本地模型，确保模型已加载

### 7.6 配置问题

#### 配置修改后不生效

**排查步骤：**

1. 确保完全退出游戏后再修改配置文件
2. 检查 TOML 语法是否正确（字符串用双引号，数字不用引号）
3. 检查配置段名是否正确（如 `[llm]`、`[speech_recognition]`）
4. 查看 `latest.log` 中是否有配置加载错误

#### `original` 模式被自动改回 `api`/`online`

**原因：** 内置 API 开关 (`enableSttApis`/`enableTtsApis`) 开启时会覆盖模式。

**解决方案：**

- 将 `enableSttApis` / `enableTtsApis` 设为 `false`
- 或确认 `original` 模式优先级最高，不受内置 API 影响

#### 人设切换后仍使用旧人设

**排查步骤：**

1. 确认 `enableCustomPrompt = true`
2. 确认 `selectedPreset` 值正确（使用枚举 name，如 `CAT_GIRL`）
3. 查看日志中 `当前人设已加载，提示词长度: X 字符`
4. 如果使用自定义文件，确认文件路径和内容有效

### 7.7 构建问题

#### `reobfShadowJar` 内存不足

**原因：** 重映射阶段需要较大内存。

**解决方案：**

```bash
# 调整 Gradle JVM 内存
set GRADLE_OPTS=-Xmx2g -XX:MaxMetaspaceSize=512m
.\gradlew.bat build
```

#### Cloth Config 包冲突

**原因：** ShadowJar 未排除 Cloth Config 相关包。

**解决方案：** 在 `build.gradle` 的 ShadowJar 配置中排除：

```groovy
exclude 'me/shedaniel/**'
exclude 'blue/endless/jankson/**'
exclude 'org/yaml/snakeyaml/**'
```

***

## 8. 联机说明

### 8.1 基本规则

- **仅主机需要安装扩展 Mod 和配置**
- 其他玩家无需安装扩展 Mod
- Verity NPC 和 API 调用都是服务端处理
- 语音输入和 TTS 是客户端行为，仅对主机生效

### 8.2 联机配置

1. 主机正常安装和配置扩展 Mod
2. 主机启动游戏并进入世界
3. 其他玩家正常连接到主机
4. 所有玩家都可以与 Verity NPC 对话
5. 语音输入和 TTS 仅主机可用

### 8.3 聊天可见性

- 普通聊天消息正常广播给所有玩家
- AI 回复通过原版 Verity 的网络包广播
- 主动感知回复也通过原版网络包广播

***

## 9. FAQ

### Q: 是否必须安装原版 Verity Mod？

A: 是。本 Mod 是原版 Verity 的扩展插件，不能独立运行。

### Q: 不使用原版代理模式时，是否需要原版 Verity？

A: 是。即使 STT/TTS 模式设为 `local` 或 `api`/`online`，对话系统仍然依赖原版 Verity 的 NPC 实体和事件系统。

### Q: 内置 API 是否免费？

A: 内置 API 是预配置的服务商接口，可能存在使用限制。建议长期使用时配置自己的 API 密钥。

### Q: Vosk 模型从哪里下载？

A: 可以在配置界面中点击"下载模型"按钮，或从 Vosk 官方网站下载 `vosk-model-small-cn` 模型并放到 `./config/vosk-model-small-cn` 目录。

### Q: 支持哪些 Minecraft 版本？

A: 目前仅支持 Minecraft 1.20.1 + Forge 47.4.21。不兼容 Fabric 或其他 Minecraft 版本。

### Q: 主动感知为什么不工作？

A: 排查步骤：

1. 确认 `proactive_awareness.enabled = true`
2. 确认对应事件开关已开启（如 `deathEvent = true`）
3. 确认冷却时间已过（默认 5 分钟）
4. 查看 `latest.log` 中是否有主动感知日志
5. 确认 AI API 配置正确

### Q: 如何切换人设？

A: 在 `verity_extended-common.toml` 中设置 `enableCustomPrompt = true`，然后修改 `selectedPreset` 为目标人设的枚举名（如 `CAT_GIRL`、`OLD_PRIEST` 等）。

### Q: 自定义提示词文件支持什么编码？

A: 支持 UTF-8（推荐）和 GBK。Mod 会自动检测文件编码并正确解码。

### Q: 多个 Mod 同时使用 V 键怎么办？

A: 在游戏内 `选项 → 控制 → 按键绑定` 中找到 `veritycustomapi` 分类，修改语音输入按键。

***

## 附录 A: 日志关键字速查

| 日志关键字                                             | 含义            |
| ------------------------------------------------- | ------------- |
| `Verity扩展增强模组加载完成`                                | Mod 已成功加载     |
| `代理服务器已启动，端口：4000`                                | 本地代理服务器已启动    |
| `当前人设已加载，提示词长度: X 字符`                             | 人设预设已加载       |
| `已接入原版 Verity 语音录音器`                              | 原版语音代理已连接     |
| `原版 Verity MicrophoneRecorder.startRecording 已调用` | 原版录音已开始       |
| `原版 Verity MicrophoneRecorder.stopRecording 已调用`  | 原版录音已停止       |
| `正在调用原版 Verity AiAPI.transcribeAudio`             | 原版语音转写已调用     |
| `正在调用原版 Verity KeybindHandler.accept`             | 原版语音文本已提交     |
| `主动感知触发事件: XXX`                                   | 主动感知事件已触发     |
| `主动感知直连 Chat API: url=...`                        | 主动感知正在请求 AI   |
| `主动感知事件完成: XXX`                                   | 主动感知已完成       |
| `GameActionHandler 事件已注册`                         | 游戏动作处理器已注册    |
| `已强制关闭原版 TTS`                                     | 原版 TTS 已被扩展接管 |
| `已按扩展配置启用原版 Verity TTS`                           | 原版 TTS 模式已启用  |

## 附录 B: 配置文件完整示例

### verity\_extended-common.toml

```toml
[server]
port = 4000

[llm]
apiProvider = "CUSTOM_OPENAI"
apiUrl = ""
apiKey = ""
model = ""
enableCustomPrompt = false
useOriginalVerityChatChain = true
selectedPreset = "ORIGINAL_VERITY"
customPromptFile = "./config/verity_custom_prompt.txt"
requestTimeout = 30

[speech_recognition]
enableVoiceInput = true
mode = "local"
apiProvider = "CUSTOM_OPENAI"
apiUrl = ""
apiKey = ""
model = ""
requestFormat = "multipart"
authType = "bearer"
responseField = "text"
voskModelPath = "./config/vosk-model-small-cn"
sampleRate = 16000

[text_to_speech]
enableTts = true
mode = "online"
sampleRate = 22050
modelPath = "./config/tts-model"
speed = 1.0
volume = 1.0
apiProvider = "CUSTOM_OPENAI"
apiUrl = ""
apiKey = ""
apiModel = ""
apiVoice = "alloy"

[transit]
enableChat = false
enableTts = false
enableStt = false
apiUrl = "https://api.st68.icu/api"
chatProvider = ""
ttsProvider = ""
sttProvider = ""
requestTimeout = 60

[debug]
runtimeMetrics = false
runtimeMetricsIntervalSeconds = 60
```

### verity\_extended-client.toml

```toml
[builtin_api]
enableChatApis = false
enableSttApis = false
enableTtsApis = false
mimoTtsVoice = "苏打"

[proactive_awareness]
enabled = false
pauseEvent = true
deathEvent = true
lowHealthEvent = true
sleepEvent = true
worldEvent = true
cooldownSeconds = 300
desktopNotifications = false
```