AI DataBase wAPI Core

模组

· 作者 morwapi

适用于 Minecraft 1.21.1 (NeoForge) 的核心服务端模组,支持异步外部 AI API 调用以及轻量级的基于 JSON 的数据存储。它为其他模组提供 API 接口,本身不包含任何独立功能。

0 本站下载 0 关注 更新于 8 个月前

最新 1.21.1-0.1.2 · 1.21.1 · NeoForge

一键开服(送7天)
  1. 英文 / 2. 日本語

AI DataBase wAPI Core (aidbwapi_core)

适用于 Minecraft 1.21.1 (NeoForge) 的核心服务端模组,提供与外部 AI(兼容 OpenAI 的 LLM API)进行异步请求的功能,以及基于轻量级 JSON 的持久化存储(数据库功能)。 该模组本身不提供独立功能(如聊天机器人);它被设计为系统基础设施(Core),允许其他模组(依赖模组)通过 Java API (AiCoreAPI / DatabaseManager) 轻松利用高级 AI 功能和数据存储。


? 特性与架构

1. AI 请求网络(高级 AI 集成与自动故障转移)

配备了自动故障转移和速率限制系统,旨在确保与外部 API 的安全可靠通信,同时最小化服务器负载。

  • 全异步处理与串行队列 (Async Executor): 所有对 AI 的 HTTP 请求均使用 CompletableFuture 和 Java 标准 HttpClient 机制(异步 I/O)执行,确保不会阻塞 Minecraft 的 tick。此外,通过确保“并发执行数始终最多为一个(队列管理)”,防止同一提示词字符串的多次同时传输,从而保证安全性。

  • 惰性求值重置 (Lazy Reset): 初始化时检查模型的“每日执行限制”和“每分钟执行限制”不使用周期性服务器任务(持续监控)。相反,它采用惰性重置机制,在下次请求发生时通过比较时间戳即时进行计算和重置,从而实现零待机服务器负载。

  • 密钥分发与分布式轮询(优先级与负载均衡): 可以为同一提供商或模型注册多个 API 密钥。你可以为每个 ModelEntry 设置优先级(priority:值越低优先级越高)。在发生错误或速率限制耗尽的情况下,系统会自动回退(切换到下一个最高优先级的模型/密钥)。 此外,如果存在多个具有相同优先级的模型,系统将使用“轮询”方法分配请求,自动防止负载集中在特定的 API 密钥上。 这允许通过聚合多个免费 API 密钥的速率限制配额来安全运行。

  • 惩罚点 (PP) 系统与概率跳过(惩罚系统): 当发生通信错误时,模型不会立即被禁用。而是根据错误的严重程度分配惩罚点 (PP),同时应用临时冷却时间(默认:429 = 60秒,5xx = 120秒,超时 = 60秒,连接失败 = 300秒)。

    • HTTP 429 (速率限制): +1 PP
    • HTTP 5xx (服务器错误): +5 PP
    • Timeout / 连接 / DNS 失败: +7 PP
    • 通信成功: 减半 PP (PP /= 2)

    在选择执行候选项时,具有 PP 的模型将以计算出的概率暂时跳过: $$\frac{PP}{PP + 4.0}$$ 系统通过移动到下一个候选项,自主避免或抑制访问当前不稳定的端点。

  • 100 轮故障保护循环: 如果所有候选模型当前都处于概率跳过或冷却状态,系统将循环回到候选列表开头以重新抽取。为防止无限循环,强大的故障保护会在最多 100 轮后终止进程,要么选择可用性最高的优先级模型(最低优先级值)作为妥协,要么向 API 层返回完全失败。

  • 异常处理 (HTTP 400 错误请求): 如果发生配置相关错误,如 HTTP 401 (未经授权) 或 HTTP 404 (模型未找到),特定模型将自动禁用 (disabled),系统立即回退(重试)到下一个候选项。然而,对于 HTTP 400 (错误请求),由于问题可能是提示词或数据结构特有的 bug,切换模型不太可能成功。因此,系统在不进行故障转移的情况下立即向调用方依赖模组返回错误(无用的循环即时终止)。

2. JSON 存储系统(数据库功能)

一个基础框架,使依赖模组能够极其轻松地保存和加载自己的数据。存储格式严格固定为 JSON。

  • 类别注册与层级管理: 通过在初始化期间调用 registerCategory("my_mod"),依赖模组(外部模组)会自动生成与该类别名称链接的目录结构。数据会自动分类到“通用数据(全局)”和“单个玩家(UUID)数据”文件夹中。(注意:未经预先注册无法保存数据)。
  • 内存缓存与动态解析: 经常访问的数据在加载时被缓存在内存中的 Map 中。随后的 get/set 操作会立即处理,无需磁盘 I/O。存储目录的根路径通过在 ServerStartedEvent 期间检索正确路径(例如 root/world/aidbwapi_core/)自动确定。
  • 同步与即时保存机制: 当对数据库执行写入操作 (set()) 时,内存缓存会更新并执行即时同步文件写入 (flush)。(注意:虽然错误日志每 3 小时使用后台延迟计时器,但数据库本身没有异步自动保存延迟功能)。为了安全起见,还实现了一个手动强制保存命令 (db save)。

? 要求与设置

  • Minecraft: 1.21.1
  • Mod Loader: NeoForge 21.1.219 或更高版本
  • Java: Java 21 或更高版本
  • Side: 服务器和客户端均需安装

安装: 将此模组 (aidbwapi_core-x.x.x.jar) 放入服务器或客户端的 mods 文件夹中并启动。


⚙️ 配置与目录结构

所有设置、数据库和错误日志均部署在服务器根目录或客户端的 saves/[world_name]/ 目录下。

  • config/aidbwapi_core-common.toml:整个模组的基本运行设置。
    • commandPermissionLevel:执行所有 /dbwapi 命令所需的 OP 等级(默认值:2)。可更改为 0 到 4 之间的任意值。
    • requestTimeoutSeconds:AI 通信响应的超时时间(默认值:60 秒)。
    • penaltyCurveFactor:PP 跳过概率曲线的调整系数(默认值:4.0)。
    • 其他设置包括各种 HTTP 错误的冷却时间(如 rateLimitSeconds 等)以及错误日志的定期刷新间隔(flushIntervalMinutes)。部分基本设置可以通过游戏内命令即时更改并持久化保存。
  • config/aidbwapi_core-keynames.json:以结构化格式存储 AI 端点 URL、明文 API 密钥、模型列表以及各种速率限制设置(dailyLimit、minuteLimit)。
    • ⚠️ [重要] API 密钥安全与注册方法 作为本模组的规范,API 密钥未加密,而是以明文形式保存在此 JSON 文件中。虽然可以通过游戏内命令(/dbwapi keyname setkey)注册密钥,但由于 Minecraft 的规范限制,你在聊天栏中输入的完整命令(即明文 API 密钥字符串)将被原样记录在服务器的 logs/latest.log 和控制台日志文件中。 为确保安全,请避免使用游戏内命令输入。我们强烈建议直接使用文本编辑器打开此文件,编辑/保存 "apiKey": "sk-xxxx..." 字段,然后在游戏内运行 /dbwapi reload 命令以重新加载设置。
  • [World Save Root]/aidbwapi_core/[category_name]/:通过 CategoryDatabaseHandle 等保存和缓存的每个类别的设置和数据存储根目录。
    • global.json 用于通用数据,players/ 文件夹包含各个玩家的 <UUID>.json 文件,均直接位于该类别目录下。
  • [World Save Root]/aidbwapi_core/log/:内存中积累的 AI 和 DB 处理错误历史(调试日志)以 JSON 格式在后台导出的目标位置。
    • 默认情况下仅保留最新的 20 个错误日志文件,旧文件会自动轮换(删除)。
    • 任何残留在内存中的未保存错误状态都会在服务器关闭/终止时(ServerStoppingEvent)被刷新,以确保保存到磁盘。

?️ 命令参考

初始 AI 设置和各种模型设置/管理可通过游戏内命令轻松完成。 所有命令均以 /dbwapi 开头。

  • 参数与建议: 输入标识符(KeyName 或 Model 名称)时,会显示所有已注册设置的建议(Tab 补全)。语法错误或参数不足将按照 Brigadier 标准被拒绝。
  • 消息格式颜色: 所有命令反馈均以 [AiDb] 开头(绿色)。操作的目标(值或名称)以黄色高亮显示。错误和警告以红色文本输出。
  • API 密钥的严格输出保护: 当通过显示命令(info 或 list)将 API 密钥信息输出到聊天栏时,会进行掩码处理以确保护: "如果原始密钥长度为 5 个字符或更长,则仅显示前 4 个字符,其余所有字符均用 **** 掩码隐藏。" "如果密钥长度为 4 个字符或更少,则所有字符均例外地用 **** 掩码隐藏。" 原始密钥绝不会输出到屏幕或日志中。

? 常规与配置

  • /dbwapi status:系统运行概况。显示已加载的 KeyNames 和 Models 数量,以及当前排队等待输出的 AI 和 DB 错误计数。
  • /dbwapi reload:强制重新加载 TOML 和 JSON(keynames.json)配置文件。手动文本编辑后请务必运行此命令。
  • /dbwapi version:显示本模组版本。
  • /dbwapi config show:显示当前应用的调试日志设置(debugLogging)和 AI 通信超时时间(requestTimeoutSeconds)。
  • /dbwapi config debug true|false:即时开启/关闭调试级别(详细日志输出)并持久化设置。
  • /dbwapi config timeout <seconds>:更改并持久化 AI 通信超时时间(基本设置)。

? KeyName 管理

集中管理系统范围的 “注册名称 (keyName)”,该名称由 URL(提供商端点)和 API 密钥组成。

  • /dbwapi keyname list / info <keyName>:显示所有已注册 KeyNames 的列表或特定 KeyName 的详细信息。(API 密钥会被掩码)。
  • /dbwapi keyname add <keyName> <apiUrl> <apiKey>:注册新的 AI 提供商(OpenAI 兼容)的连接信息集。 ※ 重复的注册名称(keyName)会导致错误,但在不同名称下注册相同的 apiUrl 和 apiKey 是被允许的(用于负载均衡)。
  • /dbwapi keyname seturl <keyName> <apiUrl>:仅更新现有 KeyName 的 API 端点 URL。
  • /dbwapi keyname setkey <keyName> <apiKey>:更新现有 KeyName 的 API 密钥。(※ 警告:存在日志泄露风险。推荐直接编辑 JSON 文件以确保安全。)
  • /dbwapi keyname remove <keyName> [confirm]:安全锁定的删除操作。需要在末尾添加 true 才能执行。

? 模型与故障转移管理

模型标识符始终指定为 <keyName>.<model_name>(例如 taro_groq.llama-3-70b)。

  • /dbwapi model list / info <keyName>.<model_name>:显示所有模型的运行状态(优先级、惩罚/PP 状态、当前状态等)以及单个模型的详细限制指标。
  • /dbwapi model add <keyName>.<model_name> [dailyLimit] [minuteLimit]:向父级 KeyName 添加一个新的可用模型。使用 -1 表示无限制。
  • /dbwapi model move <keyName>.<model_name> up|down:将指定模型的优先级向上移动一级 (up) 或向下移动一级 (down)。
  • /dbwapi model limit <keyName>.<model_name> daily|minute <value>:更改模型的最大限制(-1 表示无限制)。更改立即生效。
  • /dbwapi model enable <keyName>.<model_name> / disable <keyName>.<model_name>:启用或临时禁用特定模型的抽奖设置。
    • [自动禁用后的恢复]:如果发生端点配置问题(例如 HTTP 401/403 Invalid API Key 或 HTTP 404 Not Found),系统将自动强制禁用该模型(disabled)。在解决不匹配问题后(例如通过 seturl),使用此 enable 命令手动恢复它。
  • /dbwapi model reset <keyName>.<model_name>:立即将目标模型的累积 PP(惩罚)和冷却状态重置为零。
  • /dbwapi model resetall:一次性重置当前注册的所有模型。
  • /dbwapi model remove <keyName>.<model_name> [confirm]:删除指定的模型。(※ 需要安全锁定;末尾必须加上 true)。

? AI 测试、错误日志与数据库管理(测试与日志记录器)

  • /dbwapi ai status:显示当前正在处理的 AI 请求数(Active)和异步处理等待队列中的请求数(Queue)。
  • /dbwapi ai test:使用“当前有效模型”发送简短的测试提示,并检查是否实际返回了文本响应。
  • /dbwapi ai errors [count]:输出最近的 AI 通信错误历史记录(最多 50 条,默认为 10 条)。
  • /dbwapi ai errors clear:清除用于显示的错误历史记录内存。
  • /dbwapi db list:显示 DatabaseManager 中当前注册的所有类别名称列表。
  • /dbwapi db info <category>:显示指标,如存储根路径、全局 DB 键计数和当前玩家 UUID 缓存计数。
  • /dbwapi db errors [count] / db errors clear:与 ai errors 相同,但针对 DB 特定的日志(例如 FILE_WRITE_ERROR)。
  • /dbwapi db save:显式强制将所有数据库中内存中的所有更改写入文件(flush)。

? 面向开发者:Java API 实现(开发者的 API 层)

核心基础设施可通过从依赖模组的 Java 代码中调用单例 (getInstance()) 或各种静态方法来使用。请在实施前将 aidbwapi_core 包含在你的 build.gradle 作为依赖项(例如 compileOnly)。

1. 向 AI 发起异步请求 (AiCoreAPI)

所有内部速率限制检查、密钥分发、故障转移和异常处理管道均已隐藏。

import com.morwapi.aidbwapi_core.api.AiCoreAPI;

// 执行结果以 CompletableFuture<String> 的形式异步返回。
AiCoreAPI.getInstance().requestAI("用100个字符告诉我Minecraft的魅力")
    .thenAccept(response -> {
        // [成功时] 处理 AI 响应字符串 (response)。
        System.out.println("AI Response: " + response);
        
        // ⚠️ [注意] 这是在“独立线程(AsyncExecutor 内部)”中执行的。
        // 为了安全地访问 Minecraft 世界(发送聊天、放置方块、实体操作等),
        // 你必须确保使用类似 server.execute(() -> { ... }) 的任务队列将处理返回到主线程(服务器线程)。
    })
    .exceptionally(ex -> {
        // [失败/异常时] 如果所有模型不可用、
        // 重试限制(100次)超过或请求参数无效(HTTP 400),则进入此处。
        System.out.println("AI Communication Error: " + ex.getMessage());
        return null; // CompletableFuture 要求
    });

### 2. JSON 数据库与类别 (`CategoryDatabaseHandle`)
通过 `AiCoreAPI` 注册和获取类别,并接收 `PlayerDatabase` 或 `GlobalDatabase` 的句柄以保存和读取数据。

**[重要] JsonStorageEngine 规范与类型:**
此数据库并非用于直接保存和完全恢复复杂自定义类结构(POJOs)的高性能 ORM 工具。由于 GSON 规范,通过 `get()` 从 JSON 文件恢复的所有数据都加载为 **`Map<String, Object>`**(或基本类型)的集合。
因此,虽然在保存时可以传递自定义类实例,但其设计极其简单,假设你在读取时会从 Maps 或标准类型进行转换或重建(或使用 GSON 单独反序列化)。建议仅与简单的 Maps、数字或字符串一起使用。

import com.morwapi.aidbwapi_core.api.AiCoreAPI;
import com.morwapi.aidbwapi_core.api.CategoryDatabaseHandle;
import java.util.UUID;

// ------ 模组初始化期间(例如 FMLCommonSetupEvent)------

// [1]. 自动生成和注册类别
AiCoreAPI.getInstance().registerCategory("guild_mod");

// [2]. 获取用于操作的 DB 句柄
CategoryDatabaseHandle dbHandle = AiCoreAPI.getInstance().getCategoryDatabase("guild_mod");

// ------ 实现示例(例如 PlayerJoinEvent)------
UUID playerId = player.getUUID();

// [1]. 加载数据(读取)
// 从 JSON 恢复为 Map 格式等。如果未创建则返回 null。
Object rawData = dbHandle.getPlayerDB().get(playerId, "killCount");
int killCount = 0;

if (rawData != null) {
    // 由于 GSON 的原因,数字可能会变成 Double,因此以 Number 类型接收并进行转换。
    killCount = ((Number) rawData).intValue();
}

// [2]. 更新并保存数据(保存)
killCount += 1;

// 参数:玩家 UUID、存储标识键名、要保存的值(对象)
dbHandle.getPlayerDB().set(playerId, "killCount", killCount);

// ※ 当调用此 `set()` 方法时,文件会 [同步且立即地] 写入到
// `guild_mod/players/<UUID>.json`,同时应用于内存(缓存端的 Map)。

## ⚖️ 许可证 (License)

本模组的源代码及提供的二进制文件均在 **Apache License, Version 2.0** 下提供并发布。
在许可证条款范围内,允许自由创建和再分发使用或依赖此基础设施(API)的商业或非商业模组。
    



# AI DataBase wAPI Core (aidbwapi_core)

这是一个面向 Minecraft 1.21.1 (NeoForge) 的核心服务端模组,提供向外部 AI(OpenAI 兼容 LLM API)发起异步请求的功能,以及基于 JSON 的轻量级持久化存储(数据库功能)。
本模组本身不包含完整的功能(如聊天机器人等),而是设计为一个**系统基盘(Core)**,旨在让其他模组(依赖模组)能够轻松地通过 Java API (`AiCoreAPI` / `DatabaseManager`) 利用高级 AI 功能和数据保存功能。

---

## ? 核心功能与架构 (Features & Architecture)

### 1. AI 请求网络(高级 AI 集成与自主故障转移)
为了在将服务器负载降至最低的同时安全、可靠地运行,该模块配备了自主故障转移和速率限制系统(确保 AI 操作不会中断的机制)。

*   **完全异步处理与串行队列 (Async Executor):**
    所有对 AI 的 HTTP 请求均使用 `CompletableFuture` 和 Java 标准的 `HttpClient` 机制(异步 I/O 处理)执行,绝不阻塞 Minecraft 的 Tick。此外,“并发数始终最多为 1(队列管理)”,并实施了防止同时多次发送相同提示字符串的安全设计。
*   **延迟评估重置 (Lazy Reset):**
    对于模型“每日执行上限”和“每分钟执行上限”的初始化判定,不采用服务器的定期处理(持续监控),而是在下次请求发生时的时间戳比较中即时计算和重置,采用了“延迟评估(Lazy Reset)”机制,因此待机中的服务器负载为零。
*   **密钥分散运用与分布式轮询 (Priority & Load Balancing):**
    可以为同一提供商或模型注册多个 API 密钥。可以为每个模型(ModelEntry)设置优先级(`priority`: 数值越小优先级越高),当达到速率上限或发生错误时,系统会自动按优先级顺序回退(自动切换到其他模型或其他密钥)。
    此外,**当存在多个具有相同优先级的模型时,系统将采用“轮询方式”分散目标地址,自动防止特定 API 密钥的负载集中**。这使得可以通过多个密钥合并免费 API 的速率限制配额来安全运行。
*   **惩罚点数(PP)制与概率跳过 (Penalty System):**
    当发生通信错误等异常情况时,不会立即使目标模型无效,而是施加临时冷却秒数(默认:429=60秒, 5xx=120秒, Timeout=60秒, 连接失败=300秒),同时根据**错误的严重程度添加惩罚点数(PP)**。
    *   `HTTP 429` (速率限制): **+1 PP**
    *   `HTTP 5xx` (服务器错误): **+5 PP**
    *   `Timeout` / 连接或 DNS 解析失败: **+7 PP**
    *   通信成功时: **PP 减半** (`PP /= 2`)
    
    在选择执行候选项时,拥有 PP 的模型将以 `PP / (PP + 4.0)` 的概率被暂时跳过(转移到次优模型),从而自主避免和抑制对状态不佳的端点的访问。
*   **最大 100 周的故障安全循环 (Fail-Safe Loop):**
    如果所有模型候选项都处于概率跳过或冷却状态,候选列表将返回开头重新进行抽签循环。为防止无限循环,系统启用了坚固的故障安全机制:“**在最大 100 周后强制终止,妥协选出可用中优先级最高(priority 最小)的模型,或向 API 层返回完全失败**”。
*   **异常处理 (HTTP 400 Bad Request):**
    当发生配置不良错误(如 `HTTP 401`(认证错误)或 `HTTP 404`(模型不存在))时,系统会自动禁用目标模型 (`disabled`) 并立即回退到下一个模型候选项(重试)。然而,对于 `HTTP 400`(请求非法),由于“提示或发送数据的结构本身存在 bug”,无论切换到哪个模型都可能失败,因此不进行故障转移,而是立即向调用方的依赖模组返回错误(立即终止无用的循环)。

### 2. JSON 存储系统(数据库功能)
这是让依赖模组极其轻松地保存和读取数据的基础设施。保存格式**严格固定为 JSON**。

*   **类别的注册与层级管理:**
    依赖模组(外部模组)在初始化时调用 `registerCategory("my_mod")`,即可自动生成与该类别名称关联的目录结构。“通用数据(Global)”和“玩家专属(UUID)数据”会自动分配到文件夹中保存。(※ 未预先注册类别就无法保存数据)。
*   **内存缓存与动态解析:**
    频繁访问的数据在读取时会作为 Map 缓存在内存中,随后的 `get` / `set` 操作无需进行磁盘访问(I/O),可即时处理。保存路径的根目录路径利用服务器启动事件(`ServerStartedEvent`)自动获取 `root/world/aidbwapi_core/` 等正确路径来确定。
*   **同步即时保存机制:**
    当对数据库进行写入(调用 `set()`)时,内存中的缓存更新的同时会**立即执行同步文件写入(刷新)**。(※ 仅错误日志输出使用后台每 3 小时的延迟计时器,但数据库本身不存在异步自动保存的延迟功能)。为确保安全,还实现了手动强制保存(`db save`)命令。

---

## ? 运行要求与安装 (Requirements & Setup)

*   **Minecraft:** 1.21.1
*   **Mod Loader:** NeoForge 21.1.219 及以上版本
*   **Java:** Java 21 及以上版本
*   **Side:** 服务器和客户端均必需

**安装:**
将本模组 (`aidbwapi_core-x.x.x.jar`) 放入服务器或客户端的 `mods` 文件夹中启动即可。

---

## ⚙️ 配置文件与目录结构 (Configuration)

所有设置、数据库和错误日志都将展开至服务器根目录或客户端的 `saves/[世界名称]/` 目录下。

*   **`config/aidbwapi_core-common.toml`** : 模组整体基础动作设置文件。
    *   `commandPermissionLevel`: 所有 `/dbwapi` 命令所需的 OP 权限等级(默认 `2`)。可更改为 0-4。
    *   `requestTimeoutSeconds`: AI 通信的响应超时秒数(默认 `60` 秒)。
    *   `penaltyCurveFactor`: PP 跳过概率计算曲线的调整系数(默认 `4.0`)。
    *   还可设置各种 HTTP 错误时的冷却秒数(`rateLimitSeconds` 等)以及错误日志的定期刷新间隔(`flushIntervalMinutes`)等。部分基础设置也可通过游戏内命令(`/dbwapi config ...` 等)即时更改并持久化。
*   **`config/aidbwapi_core-keynames.json`** : 结构化保存 AI 端点 URL、API 密钥明文以及模型列表和各种速率限制(`dailyLimit`, `minuteLimit`)的设置。
    *   **⚠️【重要】关于 API 密钥的安全性与注册方法**
        根据模组规范,API 密钥本身不进行加密,而是以明文形式保存在此 JSON 文件中(假设通过 `.gitignore` 等进行防护或通过操作系统服务器权限进行保护)。虽然也可以通过游戏内命令(`/dbwapi keyname setkey`)进行注册,但**受限于 Minecraft 的规范,你在聊天栏中输入的命令全文(API 密钥的明文字符串)将被原样记录在服务器的 `logs/latest.log` 或控制台画面的日志文件中。**
        为确保安全,在运营可能对外提供的服务器时,强烈建议避免在游戏内输入命令,而是**直接用文本编辑器打开本文件,修改 `"apiKey": "sk-xxxx..."` 并保存,然后在游戏内执行 `/dbwapi reload` 命令重新加载**。
*   **`[世界保存根目录]/aidbwapi_core/[类别名称]/`** : 经由 `CategoryDatabaseHandle` 等保存和缓存的各类别设置、数据保存根目录。
    *   在类别目录下放置通用数据(`global.json`)和玩家专属文件夹(`players/<UUID>.json`)。
*   **`[世界保存根目录]/aidbwapi_core/log/`** : 在内存中累积的 AI/DB 处理期间的错误历史(调试日志)以 JSON 格式在后台输出的目的地。
    *   最新的错误日志输出默认最多保留 `20` 个文件,旧文件会自动轮换(删除)。
    *   此外,残留在内存中的未保存错误状态会在服务器关闭/关机时(`ServerStoppingEvent`)被中断式刷新,确保保存到磁盘。

---

## ?️ 命令参考 (Command Reference)

AI 的初始设置以及各种模型设置和管理均可通过游戏内命令轻松完成。
所有命令均以 `/dbwapi` 开头。(默认所需权限:`common.toml` 中记载的等级。初始值为 2)

*   **参数与建议规范:** 在输入标识符(KeyName 或模型名称)时,所有已注册的配置都会在游戏中的 Tab 补全建议中显示。语法错误或参数不足将按 Brigadier 标准被拦截。
*   **消息格式显示颜色:** 来自命令的反馈均以系统消息形式呈现,以 `[AiDb]`(绿色)开头,操作对象(数值或名称)以黄色高亮显示。错误和警告将以红色文本整体输出。
*   **彻底保护 API 密钥等敏感信息的输出:** 在使用 `info` 或 `list` 等用于屏幕显示的命令导致 API 密钥信息输出到聊天栏时,出于保护目的,仅显示以下状态:“若原始密钥长度超过 5 个字符,则**仅显示前 4 个字符,其余所有字符均掩码为 `****`**”;“若原始密钥长度为 4 个字符或更少,则**作为例外,将所有字符全部掩码为 `****`**”。绝对不会在屏幕上输出明文密钥。此外,在输出系统日志等情况下,密钥也绝不会包含在内。

### ? 通用设置 (General & Config)
*   `/dbwapi status` : 显示系统整体的运行概况。包括已加载的 KeyName 数量和模型数量,以及内存中处于等待处理队列(Queue)状态的 AI 错误和数据库错误的数量。
*   `/dbwapi reload` : 强制重新加载 TOML 和 JSON(`keynames.json`)配置文件。进行手动文本编辑后请务必执行此命令。
*   `/dbwapi version` : 显示本 Mod 的版本号。
*   `/dbwapi config show` : 显示当前应用的调试日志配置(`debugLogging`)和 AI 通信超时秒数(`requestTimeoutSeconds`)。
*   `/dbwapi config debug true|false` : 立即切换并持久化调试级别(详细日志输出)的开/关状态。
*   `/dbwapi config timeout <秒>` : 修改并持久化 AI 通信的超时秒数(基础设置)。

### ? KeyName 管理 (KeyName Management)
将 URL(提供商端点)和 API 密钥的组合作为系统通用的**“注册名(keyName)”**进行统一管理。
*   `/dbwapi keyname list` / `info <keyName>` : 显示所有已注册的 KeyName 列表,或指定 KeyName 的详细信息。(API 密钥会被掩码处理)
*   `/dbwapi keyname add <keyName> <apiUrl> <apiKey>` : 注册新的 AI 提供商(OpenAI 兼容)的连接信息集。⚠️ 注册名 (`keyName`) 重复会报错,但允许以不同名称多次注册相同的 `apiUrl` 和 `apiKey`(用于负载均衡)。
*   `/dbwapi keyname seturl <keyName> <apiUrl>` : 更新现有 KeyName 的 API 端点 URL。
*   `/dbwapi keyname setkey <keyName> <apiKey>` : 更新现有 KeyName 的 API 密钥。**(※存在前述的日志残留风险。为确保安全,建议直接编辑 JSON 文件。)**
*   `/dbwapi keyname remove <keyName> [confirm]` : 带有防误操作安全装置的删除功能。若省略末尾参数(`[confirm]`)或设置为 `false` 执行,则仅输出删除确认警告日志并结束。仅在末尾明确指定 `true` 时,KeyName(及其关联的所有模型配置组)才会被完全删除。

### ? 模型管理 (Model & Failover Management)
模型的标识符始终通过 `<keyName>.<模型名>`(例如 `taro_groq.llama-3-70b`,用点分隔)指定,以便区分属于哪个提供商的模型。
*   `/dbwapi model list` / `info <keyName>.<模型名>` : 显示所有模型的运行状态(优先级、惩罚/PP 情况、当前是否启用等),以及单个模型的详细限制指标。
*   `/dbwapi model add <keyName>.<模型名> [dailyLimit:日上限] [minuteLimit:分上限]` : 向父级 KeyName 添加新的可用模型。若省略上限值参数或输入 `-1`,则注册为“日/分钟均无限制”。
*   `/dbwapi model move <keyName>.<模型名> up|down` : 将指定模型的优先级(Priority 排名)向上(`up`)或向下(`down`)移动一位。
*   `/dbwapi model limit <keyName>.<模型名> daily|minute <值>` : 更改模型的上限次数(输入 `-1` 表示无限制)。设置变更即时生效。
*   `/dbwapi model enable <keyName>.<模型名>` / `disable <keyName>.<模型名>` : 启用/临时禁用指定模型的抽取设置。
    *   **【从自动禁用中恢复】**: 当发现如 `HTTP 401/403 Invalid API Key` 或 `HTTP 404 Not Found` 等会导致永久失败的配置问题时,系统会自动强制禁用(`disabled`)目标模型。在解决端点不一致等问题(使用 `seturl` 等)后,请通过此 `enable` 命令手动恢复。
*   `/dbwapi model reset <keyName>.<模型名>` : 立即将目标模型累积的 PP(惩罚)或冷却状态重置为零。
*   `/dbwapi model resetall` : 一次性重置当前注册的所有“模型”。
*   `/dbwapi model remove <keyName>.<模型名> [confirm]` : 删除指定模型。(※具备安全装置。必须提供末尾参数 `true`)

### ? AI 运行测试・错误日志・DB 管理 (Tests & Logger)
*   `/dbwapi ai status` : 显示当前正在执行/处理中的(`Active`)请求数量,以及处于异步处理等待队列(`Queue`)中的 AI 请求数量。
*   `/dbwapi ai test` : 利用“当前启用的模型(优先级最高且可通信的模型)”,从系统向 AI 发送数十个字符的简短测试提示词,实际检查是否能收到文本回复,从而进行连通性(集成)测试。
*   `/dbwapi ai errors [显示数量]` : 快速在聊天栏输出队列中积累的“最近发生的 AI 通信错误(HTTP 状态码或原因异常等)”历史记录,附带时间和目标模型名称,最多 50 条(省略时默认为 10 条)。便于定位错误。
*   `/dbwapi ai errors clear` : 清空用于屏幕显示的错误历史内存。(※不会删除磁盘上的日志文件本身)
*   `/dbwapi db list` : 显示从依赖 Mod 等在 `DatabaseManager` 中注册的所有类别名称列表。
*   `/dbwapi db info <类别名>` : 显示目标类别的保存根路径、全局 DB 的键数量(反映已加载规模)、以及当前缓存中的按玩家 UUID 划分的总数据量等指标。
*   `/dbwapi db errors [数量]` / `db errors clear` : 与 `ai errors` 机制相同,在聊天栏输出 DB 特有的日志(如 `FILE_WRITE_ERROR` 等)(省略时默认为 10 条)或清除。
*   `/dbwapi db save` : 显式地强制将内存中所有数据库的更改内容写入文件(Flush)。(※通常在 `set` 时会自动即时同步保存,因此主要用于补救直接篡改内存的情况)。

---

## ? 开发者指南:Java API 实现使用方法 (API Layer for Developers)

本 Core 基盘允许通过单例模式(`getInstance()`)或各种静态方法,从依赖 Mod(自制 Mod 等)的 Java 代码中调用并使用。请在 `build.gradle` 中将 `aidbwapi_core` 包含在依赖解析(`compileOnly` 等)中进行实现。

### 1. AI 异步请求 (`AiCoreAPI`)
内部已完全隐藏了速率限制检查、密钥分发、故障转移和异常处理管道。
对于调用方的开发者而言,只需“提交提示词字符串,并通过 CompletableFuture 接收结果字符串”,即可实现非常简洁的设计。

```java
import com.morwapi.aidbwapi_core.api.AiCoreAPI;

// 执行结果将以 CompletableFuture<String> 的形式异步返回。
AiCoreAPI.getInstance().requestAI("请用100字介绍Minecraft的魅力")
    .thenAccept(response -> {
        // [成功预期] 获取并处理 AI 的响应字符串(response)。
        System.out.println("AI的回答: " + response);
        
        // ⚠️【注意】此处是在“另一个线程(AsyncExecutor内部)”执行的。
        // 为了安全地访问 Minecraft 世界(发送聊天、放置方块、操作实体等),
        // 请务必使用任务队列如 server.execute(() -> { ... })
        // 将处理逻辑确确实实地切回主线程(Server Thread)。
    })
    .exceptionally(ex -> {
        // [失败/异常时] 当所有注册的模型均不可用(全军覆没)、重试超过100次,
        // 或因请求参数不正确(HTTP 400)等原因导致完全失败时,将进入此分支。
        // 错误类型(RATE_LIMITED, ALL_FAILED等)及详细信息包含在消息(ex.getMessage())中。
        System.out.println("AI通信错误: " + ex.getMessage());
        return null; // CompletableFuture 要求
    });

2. JSON 数据库与类别 (CategoryDatabaseHandle)

通过 AiCoreAPI 注册和获取类别,并获取 PlayerDatabase 或 GlobalDatabase 的句柄以进行数据的保存和读取。

【重要】JsonStorageEngine 的规范与类型: 本数据库并非能够直接保存和完全还原复杂类结构(POJO)的高级 ORM 工具。由于 Gson 等规范的限制,通过 get() 从 JSON 文件展开(还原)的数据都将作为 Map<String, Object>(或基本类型)的集合进行加载。 因此,虽然在保存时可以传递自定义类的实例,但在读取时必须假设需要从 Map 或标准类型中进行自行转换/重构(或通过单独的 Gson 反序列化)。这是一个极其简单的设计,建议仅使用简单的 Map、数值或基于字符串的类型。

import com.morwapi.aidbwapi_core.api.AiCoreAPI;
import com.morwapi.aidbwapi_core.api.CategoryDatabaseHandle;
import java.util.UUID;

// ------ Mod 初始化时 (FMLCommonSetupEvent 等) ------

// [1]. 类别的自动生成与注册
AiCoreAPI.getInstance().registerCategory("guild_mod");

```java
// [2]. 获取数据库操作句柄
CategoryDatabaseHandle dbHandle = AiCoreAPI.getInstance().getCategoryDatabase("guild_mod");

// ------ 实现示例 (PlayerJoinEvent 等事件) ------
UUID playerId = player.getUUID();

// [1]. 加载数据(读取)
// 从 JSON 还原为 Map 等形式。若尚未创建,则返回 null。
Object rawData = dbHandle.getPlayerDB().get(playerId, "killCount");
int killCount = 0;

if (rawData != null) {
    // 由于 Gson 可能将数值转换为 Double 等类型,因此以 Number 类型接收并强制转换
    killCount = ((Number) rawData).intValue();
}

// [2] 更新数据并保存
killCount += 1;

// 参数: 玩家 UUID, 保存标识键名, 要保存的值 (Object)
dbHandle.getPlayerDB().set(playerId, "killCount", killCount);

// ※ 调用此 `set()` 方法的瞬间,不仅会应用到内存(缓存侧的 Map)中,
// 还会【同步且立即】将文件写入 `guild_mod/players/<UUID>.json`。

⚖️ 许可证 (License)

本模组的源代码及提供的二进制文件均在 Apache License, Version 2.0 许可下提供和发布。 在许可证条款允许的范围内,您可以自由地创建、使用或再分发基于本基础框架(API)的商业或非商业模组。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源