系统

系统

服务端AI游戏助手,具备多样且可扩展的功能。

System

一个将网络小说中的“系统”带入 Minecraft 的 NeoForge 模组。Agent 运行在服务器端,负责处理数据查询、任务、每日签到和商店交互。客户端提供完整工作区、精简对话视图以及 HUD 通知,让游戏过程不被打断,并可选语音输出。

功能

  • 玩家与物品查询: 查看自身状态和公开在线玩家名称,或按名称或注册 ID 搜索物品。
  • FTB Quests 集成: 在紧凑列表中浏览可见、已解锁、可操作和未完成的任务。按编号或名称打开详细信息,然后显式选择并领取奖励。任务完成和新解锁任务会以排队的系统通知形式出现。
  • 显式网络研究: 使用 /system search <question> 或网络搜索页面请求查询。普通问题不会触发自动浏览。搜索默认共享 DeepSeek 密钥,拥有单独可配置的循环预算,并分别计量 Search 和 Fetch 请求。
  • AI 每日签到: 模型从服务器批准的池中选择奖励。奖励进入收件箱供手动领取;模型无法编造物品或更改数量。
  • 系统商店: 浏览报价、查看报价单并通过 Saturn Costs 确认付款,包括物品交换、资源和已注册扩展。没有内置货币经济。
  • 数据驱动抽奖: 浏览奖池、查看奖品权重和单抽成本,然后确认一次抽奖。奖励进入收件箱。数据包可配置 Saturn Costs 或免费抽奖。
  • 可配置内容与工作流: 数据包定义系统名称、描述、启用模块、签到奖励、商店报价和抽奖池。模块支持 ID、标签和条件。当玩家完成进度时,服务器规则可触发有界工作流。
  • HUD 通知与语音: 通知不会接管鼠标或键盘。可选阿里云流式 TTS 朗读消息正文;关闭视图、关闭通知或切换消息会结束相应的语音会话。
  • 用量与隐私控制: 按玩家的服务器 AI 和网络用量、私有本地 TTS / ASR 用量、历史管理、外部 AI 退出、UUID 隔离数据以及对模型和工具执行的限制。

快速开始

  1. 安装此模组及其必需依赖项。如需任务集成,请添加 FTB Quests 及其依赖项。
  2. 启动服务器或打开一次单人世界,以在 config/system/ 下生成服务器配置文件。
  3. 如需使用 AI,请在服务器进程的启动环境中设置 SYSTEM_DEEPSEEK_API_KEY,然后重启。在单人模式下,Minecraft 进程必须继承该变量。配置存储的是环境变量名称,而非密钥。
  4. 安装定义系统的服务器数据包,然后由管理员使用 /system grant <system ID> [player] 绑定,例如 /system grant example:daily Steve。省略玩家则绑定自己。玩家初始未绑定,目前最多可绑定一个系统。发布 JAR 不包含默认系统定义或默认模块标签;开发默认值仅存在于 src/test-mod/。
  5. 运行 /system、/system full 或 /system simple,然后使用控件或输入请求。

例如,在 PowerShell 中设置变量,然后从同一环境启动服务器:

$env:SYSTEM_DEEPSEEK_API_KEY = "<your-api-key>"

显式查询、商店浏览和物品交换不需要模型密钥。AI 签到和基于模型的路由回退需要。/system usage 不需要绑定。

模型配置

模型设置位于 config/system/system-model.json。默认字段如下所示;更改后请重启服务器。

{
  "providerType": "auto",
  "baseUrl": "https://api.deepseek.com",
  "model": "deepseek-chat",
  "apiKeyEnvironment": "SYSTEM_DEEPSEEK_API_KEY",
  "apiKeyRequired": true,
  "jsonMode": true,
  "outputTokenParameter": "max_tokens",
  "thinkingEnabled": false
}

将 baseUrl 设置为不含 /chat/completions 的 API 前缀;适配器会自动附加该路径。如需使用其他兼容服务,请更改 URL、模型 ID 和密钥环境变量名称,并在需要时显式设置 providerType: "openai"。auto 仅对官方 DeepSeek 域名启用 DeepSeek 特定参数;当使用代理访问 DeepSeek 时,请显式选择 deepseek。

命令与交互

以下命令在 Minecraft 聊天中运行:

命令 操作
/system 打开上次选择的视图
/system full / /system simple 打开完整 / 精简视图
/system settings 直接打开统一客户端设置;无需绑定或管理员权限
/system ask <text> 提交自然语言请求
/system search <question> 显式启动付费网络研究;不会自动浏览
/system player 查看自身状态
/system usage / /system usage all 查看个人用量 / 以管理员身份查看服务器 AI 和网络用量;语音总计始终为个人
/system grant <system ID> [player] 以管理员身份绑定一个数据包系统;省略玩家则绑定自己
/system revoke [player] 以管理员身份撤销访问权限并清除系统记录;保留累计用量
/system reset [player] 清除旧格式系统记录和绑定;保留累计用量,然后再次授权
/system module add <player> <module ID> 以管理员身份为玩家启用额外模块
/system module remove <player> <module ID> 以管理员身份为玩家禁用模块
/system module list [player] 以管理员身份列出已注册模块或玩家的已启用模块
/system routing 以管理员身份查看路由诊断信息
/system help 显示可用操作

系统 ID、玩家和模块参数支持补全。再次授予同一系统不会重置玩家数据;切换到其他系统前请先撤销当前绑定。手动模块覆盖优先于数据包条件,并持续到被撤销或重置。必需模块(包括 core、binding 和 usage)无法手动移除。

通知出现在 HUD 底部。使用配置的按键(默认为 T)打开原版聊天以点击“确认”或操作按钮。连续通知会在内容淡出时保持面板展开,切换内容淡出淡入。确认、超时或切换通知会立即切断旧语音,因此下一条消息无需等待其完成。关闭助手视图也会结束其语音会话。

可选语音

所有语音功能均在客户端运行,并使用付费 API。

所有语音功能目前使用阿里云 API。计划支持更多提供商。

语音输入

需要单独的阿里云 NLS 项目 AppKey 和 AccessKey ID / Secret。临时 Token 按需自动获取、缓存和刷新。

建议安装 Simple Voice Chat 以获得更好体验。

语音输入默认禁用。使用 /system settings,或在助手的输入框中输入 /settings,然后选择语音输入并启用。更改会自动保存。按住 F8 录音,松开结束;该按键会在游戏过程中打开助手。也可使用 /listen 和语音输入按钮。最终识别结果会填入草稿,然后按 Enter 发送;启用识别后发送可立即发送。录音最长持续 60 秒,视图关闭时取消。

通知可见时,识别出的语音首先尝试匹配其确认或操作按钮;未匹配的文本会进入主聊天。Simple Voice Chat 为可选;未安装时 Java Sound 录制音频。

语音输出

需要单独的阿里云 Model Studio API 密钥和匹配的区域。

在完整工作区中打开设置 → 语音输出,或使用 /system settings 或助手的 /settings 命令并选择该选项卡。

  1. 输入阿里云 Model Studio API 密钥并选择其区域,或为客户端进程设置 DASHSCOPE_API_KEY。
  2. 设置模型、语音、语言和音量。默认值为 qwen3-tts-flash、Cherry 和游戏语言。
  3. 预览,然后启用自动语音。更改会自动保存。自定义语音 ID 必须与其创建时使用的模型匹配。

在设置字段中直接输入导出的语音参数。TTS 不支持 JSON 导入或设置重载按钮。本地设置保存在 config/system/system-speech.json。通知音效有自己的开关,默认启用,且不需要 TTS 请求。

Python 3.10+ 实用工具 tools/voice_design.py 支持语音设计、克隆、测试合成和临时上传。它使用标准库。

python tools/voice_design.py --lang en --help

内容与扩展

系统定义位于 data/<namespace>/system/system/<path>.json。名称和描述使用客户端翻译键。例如,创建 data/example/system/system/daily.json:

{
  "name": "system.definition.default.name",
  "description": "system.definition.default.description",
  "modules": [
    "#example:basic",
    "system:web_search"
  ]
}

将相应的模块标签放在 data/example/tags/system/server_module/basic.json:

{
  "replace": false,
  "values": [
    "system:player",
    "system:items",
    "system:signin",
    "system:inbox",
    "system:shop",
    "system:lottery"
  ]
}

模块列表也接受带 condition 的对象;id 可命名单个模块或 #tag。如果多个条目匹配同一模块,任一满足的条件即可启用它。模块可用性控制工作区条目、命令和执行权限。FTB 功能还需要其依赖项。参见 系统定义和模块标签。

签到奖励、商店报价和抽奖池完全由数据包定义,包括捆绑的默认值:

data/<namespace>/system/signin_rewards/<path>.json
data/<namespace>/system/shop_offers/<path>.json
data/<namespace>/system/lottery_pools/<path>.json

详情请参阅此 GitHub 仓库中的示例。

数据与隐私

配置文件

位置 内容
服务器 config/system/system-agent.json 执行预算、并发、每日模型限制和时区
服务器 config/system/system-model.json 模型连接和提供商选项
服务器 config/system/system-search.json DeepSeek 搜索连接;默认共享模型密钥环境变量
服务器 config/system/system-search-pricing.json 每 1,000 次请求的 Search / Fetch 费率
服务器 config/system/system-semantic.json 本地意图路由、阈值、示例和缓存
服务器 config/system/system-advancements.json 受信任的进度规则
<world>/system-agent/<UUID>.json 绑定、对话、偏好、奖励、订单和工作流记录
<world>/data/system/token_usage.dat 按玩家的服务器 AI / 网络用量;撤销访问或清除内存后保留
客户端 config/system/speech-usage/<UUID>.json 此本地账户的个人 TTS / ASR 总计,跨服务器保留;永不上传
客户端 config/system/system-speech-pricing.json 个人 TTS / ASR 费率;如缺失则从捆绑默认值复制
客户端 config/system/system-client.json 视图偏好
客户端 config/system/system-speech.json 本地语音设置及在 UI 中输入的任何密钥
客户端 config/system/system-asr.json 本地识别开关、NLS AppKey、AccessKey ID / Secret 和区域

配置文件不会在客户端和服务器之间直接同步。系统定义和可用模块通过 Minecraft 网络同步。世界文件夹中的玩家数据文件由服务器管理;客户端无法直接修改它们。

API 用量

AI 用量来自服务器端模型响应。服务器网关分别跟踪 Search / Fetch 请求计数和估算成本。全玩家视图仅包含服务器 AI 和网络记录。TTS 和 ASR 总计保留在客户端,按本地账户计算;它们永不上传到 Minecraft 服务器,管理员无法查看其他玩家的语音用量记录。

Search / Fetch 费率在服务器端配置,初始化后可使用 /reload 重新加载。语音费率在客户端配置;编辑后使用 F3+T 重新加载资源或重启。ASR 默认按每 1,000 次成功识别人民币 3.5 元估算。TTS 使用所选模型返回的字符或 token 用量;两者不合并计费。

空搜索结果不产生成本估算。未知结果(如超时或网络中段)会单独记录,并不证明提供商未收费。费率变更不会重新计算历史总计;提供商账单为准。参见 用量与计费 和 外部 API 请求列表。