Verity 扩展增强 Mod

Quick Start

三步开启 Verity 新体验

前置已安装原版 Verity Mod，扩展增强 Mod 通过代理层接入，零侵入即用。

STEP 01

放入 Mods 目录

将 veritycustomapi-1.0.1.jar 放入 .minecraft/mods/，确保原版 Verity Mod 同处此目录。

STEP 02

启动游戏生成配置

首次启动自动生成 verity_extended-common.toml 与 verity_extended-client.toml 两份配置文件。

STEP 03

按需启用功能

开启内置 API 即可零配置对话，或填写自有 API 地址与密钥，按 V 键与 Verity 自然交流。

验证安装 · 启动日志关键字

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

Architecture

代理层 + 桥接，零侵入

在游戏内启动本地 HTTP 代理，拦截并转换原版 Verity 的 AI 请求，原版代码一行不改。

Minecraft 客户端

Verity 原版 Mod

扩展增强 Mod

代理 + 桥接

Verity 原版 Mod

varmite.*

本地代理服务器

端口 4000

Chat API

STT API

TTS API

主入口com.hanchen.veritycustomapi

Mod 初始化、配置注册、代理服务器启停

AI 服务.ai

Chat / STT / TTS API 请求构建与发送

原版桥接.compat

反射调用原版 Verity 录音 / 转写 / TTS / 对话

游戏动作.action

AI 回复解析与游戏内动作执行（Tick 安全队列）

客户端事件.client

按键绑定、主动感知、客户端事件处理

对话请求链路 · 玩家发送消息到 Verity 回复

玩家在游戏内发送聊天消息
原版 Verity 的 ServerChatEvent 拦截消息
原版向 127.0.0.1:4000/v1/chat/completions 发请求
本地代理接收请求，注入系统提示词（人设）
代理转发到用户配置的真实 AI API
AI 返回 JSON（response / action / emotion）
代理包装为 Verity 原生格式返回
原版 Verity 显示回复并触发 TTS 朗读

How To Use

配置场景一览

覆盖从零配置开箱到深度自定义的典型使用路径，按需取用。

零配置 · 内置 API

快速开始（内置 API）

无需填写任何 API 地址与密钥，开启内置服务即可对话与语音。优先级：original > 内置 API > 自定义配置。

# verity_extended-client.toml [builtin_api] enableChatApis = true enableSttApis = true enableTtsApis = true mimoTtsVoice = "苏打"

自定义 · LLM

接入自有 AI 服务

支持 OpenAI 兼容接口与 DeepSeek、通义千问、智谱、Ollama 等服务商，自定义时必填 apiUrl。

[llm] apiProvider = "DEEPSEEK" apiUrl = "https://api.deepseek.com/v1/chat/completions" apiKey = "your-key" model = "deepseek-chat" enableCustomPrompt = true selectedPreset = "CAT_GIRL"

语音输入 · STT

三种识别模式

local 本地 Vosk 离线、api 在线接口、original 复用原版 Verity 录音转写链路。按 V 键开始 / 松开识别。

# 在线 API 模式 [speech_recognition] mode = "api" apiProvider = "SILICONFLOW" apiUrl = "https://api.siliconflow.cn/v1/audio/transcriptions" model = "FunAudioLLM/SenseVoiceSmall" requestFormat = "multipart" responseField = "text"

语音合成 · TTS

在线与离线双方案

online 调用在线 TTS API、local 使用 ONNX 本地合成、original 走原版 Verity。统一 WAV 格式，最大 2000 字符。

[text_to_speech] mode = "online" apiProvider = "MIMO_TTS" apiUrl = "https://ai.mocwl.top/v1/chat/completions" apiModel = "mimo-v2.5-tts" apiVoice = "苏打" speed = 1.0 volume = 1.0

主动感知 · Proactive

事件驱动的主动发言

基于游戏事件（死亡、低血量、睡眠、进出世界、暂停菜单）触发 Verity 主动开口，全局冷却可配，失败有本地兜底。

# verity_extended-client.toml [proactive_awareness] enabled = true deathEvent = true lowHealthEvent = true sleepEvent = true worldEvent = true pauseEvent = true cooldownSeconds = 300

自定义 · 提示词

外部人设文件

设置 enableCustomPrompt 与 CUSTOM_FILE 预设，从外部文件读取提示词，支持 UTF-8 与 GBK 自动检测编码。

[llm] enableCustomPrompt = true selectedPreset = "CUSTOM_FILE" customPromptFile = "./config/my_prompt.txt" # 提示词文件支持 UTF-8 / GBK

FAQ

常见问题

来自真实使用场景的高频疑问与排查思路。

是否必须安装原版 Verity Mod？

是。本 Mod 是原版 Verity 的扩展插件，不能独立运行。即使 STT / TTS 模式设为 local 或 api / online，对话系统仍然依赖原版 Verity 的 NPC 实体与事件系统。

支持哪些 Minecraft 版本？

目前仅支持 Minecraft 1.20.1 + Forge 47.4.21，不兼容 Fabric 或其他 Minecraft 版本。Java 版本要求 Java 17。

内置 API 是否免费？

内置 API 是预配置的服务商接口（Chat: VectorEngine / STT: SiliconFlow / TTS: MiMo TTS），可能存在使用限制。建议长期使用时配置自己的 API 密钥。

如何切换人设？

在 verity_extended-common.toml 中设置 enableCustomPrompt = true，然后修改 selectedPreset 为目标人设的枚举名（如 CAT_GIRL、OLD_PRIEST 等）。日志中会出现「当前人设已加载，提示词长度: X 字符」。

按 V 键无反应怎么办？

排查步骤：确认 enableVoiceInput = true；检查按键是否被其他 Mod 冲突（可在「选项 > 控制 > 按键绑定 > veritycustomapi」中修改）；查看 latest.log 中是否有语音识别日志；若使用 original 模式，确认原版 Verity 已加载。

主动感知为什么不工作？

确认 proactive_awareness.enabled = true；确认对应事件开关已开启（如 deathEvent = true）；确认全局冷却时间已过（默认 5 分钟）；查看日志中是否有「主动感知触发事件: XXX」。AI 请求失败或超时（10 秒）会显示本地兜底回复。

提示「ClassNotFoundException: varmite.verity.*」

原版 Verity Mod 未安装或未正确加载。确认 mods/ 目录中有原版 Verity Mod jar 且版本与 Forge 兼容；若不使用原版代理模式，可将 STT / TTS 模式从 original 改为 local 或 api / online。

端口 4000 被占用如何处理？

修改 verity_extended-common.toml 中 server.port，同时修改原版 Verity 配置中的 AI endpoint 端口保持一致，重启游戏即可。

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

支持 UTF-8（推荐）与 GBK，Mod 会自动检测文件编码并正确解码。默认路径为 ./config/verity_custom_prompt.txt。

完整使用指南