AI Companion – LLM Player Bot (Ollama, llamacpp, LM Studio)

面向 Minecraft 世界的 AI 同伴

AI 朋友——不是静态 NPC，而是积极参与其中的伙伴。他们有自己的目标，能分辨朋友与威胁，自主寻路、采集和制作、按要求建造结构，并与你并肩作战。他们的“表达与判断”由一个由你运行的大语言模型提供——可以是在你自己的设备上运行的本地 OpenAI 兼容服务器（llama.cpp、Ollama、LM Studio 等），也可以是任何托管的OpenAI 兼容 API（例如 xAI/Grok、OpenAI）；如果你更愿意牺牲隐私来换取前沿模型的质量，也可以选择后者。

LLM 决定做什么、说什么。繁重的工作——寻路、任务执行、与世界交互——由引擎代码负责，即使 LLM 离线也能继续运行。

⚠️ 适用范围——单人游戏和局域网，不适用于公开服务器

这是一个Alpha 版，专为单人游戏和与你信任的人一起游玩的对局域网开放世界构建并测试。截至 0.2.4 版本，它可以在专用服务器上运行，但尚未准备好用于公开多人服务器。与其让你自己踩坑，我更愿意先说明原因：

• 同伴不是玩家，因此领地声明和保护模组无法识别它。领地声明模组会挂钩玩家专属的方块破坏事件；同伴是LivingEntity，不会触发这些事件。在受保护的服务器上，它可能会挖穿已声明的领地。
• 全服务器共用一份名单。名称、角色设定、皮肤和语音都来自同一个服务器配置文件，因此所有人使用的是同一组角色。
• 回复会发送给所有人。同伴的聊天内容会发送给所有在线玩家，不受距离限制。
• 费用上限按服务器计算，而非按玩家计算。一个人的对话会消耗所有人的预算。

这些问题会在 1.0 里程碑版本中妥善解决。在此之前：请用于单人游戏和可信任的局域网。在专用服务器上，/companion命令受 OP 权限限制，不会让你措手不及。

⚠️ 使用要求——请先阅读

这个模组无法独立运行。它需要一个OpenAI 兼容的聊天补全端点来进行思考。你需要自行提供以下任一种：

• 本地（私密、免费）：在你的设备或局域网上运行的 OpenAI 兼容服务器——llama.cpp、Ollama、LM Studio，或任何支持相同 API 的服务。所有数据都不会离开你的网络。
• 云端（前沿模型质量、付费）：托管的 OpenAI 兼容 API 和 API 密钥（例如 xAI/Grok）。内置了可选的单次会话请求上限，避免意外循环导致费用不断累积。

此外还需要：Minecraft 1.20.1、Fabric 加载器和Fabric API。寻路与任务引擎已打包在这个 JAR 文件中——你无需另行下载。

可选的语音输出（同伴大声说话）功能需要一个小型本地Kokoro TTS 容器。所需的一切都随模组一同提供：首次启动时，它会写入config/aicompanion/tts/，其中包含docker-compose.yml和一个完整的README.md。安装Docker，在该文件夹中运行docker compose up -d，然后在配置中启用 TTS。请参阅下方的配置部分。

客户端/服务端分工：音频的获取和播放都在客户端进行——服务端只向你的游戏发送文本和用于获取音频的端点。因此容器应放在玩家的机器上，而不是服务端上；在默认的http://localhost:8880下，每个想要语音的玩家都运行自己的容器。（也可以共用一个容器：在双方都能访问的任意位置运行它，并将tts.endpoint设置为它的局域网地址，而不是localhost。）开关本身是服务端侧的——tts.enabled、endpoint、model、voice和speed都从服务端 config/aicompanion.json读取并推送到客户端，所以连接到专用服务器时，在你自己的机器上修改它们不会有任何效果。

特性

• 自主智能体，而非脚本——它们会采矿、采集、合成、参与战斗，并通过经过验证的任务引擎建造结构（Automatone/Baritone 寻路 + 源自 AltoClef 的任务层）。
• 不止一个同伴——维护一个同伴名册，每个同伴都有自己的名字、性格、皮肤和声音。按名字生成它们，并在聊天中按名字（Rook, go and scout north）或一次性对整个群体（all: back to base）发号施令。
• 你的大脑，你的规则——一个配置文件就能让它们指向本地服务器或托管的前沿 API。随时在两者之间切换。
• LLM 离线也能存活——导航和任务执行都在引擎侧进行；如果模型离线或响应缓慢，同伴不会在世界中卡住。
• 人设与身份——在配置中设置每个同伴的名字、描述和性格；人设会被注入到加固的提示词框架中（它塑造声音，但不能覆盖安全结构）。
• 把东西交给它们——右键点击同伴以打开其物品栏，给它工具、武器、盔甲或食物，并取回它收集到的东西。
• 你给什么它就穿什么——同伴会主动从自己的背包中换上更好的盔甲，比较防御、韧性和保护附魔，因此绝不会降级。它会明显地在主手中挥舞工具和武器，且其手持物品是 LLM“看到”的内容之一，因此装备情况可以被确认。
• 它会使用盾牌——携带的盾牌会放在副手，用来抵挡苦力怕、箭矢和近战攻击。它会像你的盾牌一样磨损并损坏。
• 它会饿也会吃——治疗消耗食物，和你完全一样；同伴会自己进食：可见地、在正常的几秒内完成，在战斗间隙补充，而不是等到濒临绝境。它会捡起路过时遇到的food，并在击杀后清理掉落物。它不会饿死。
• 它不挑食——生肉和腐肉对同伴来说都是很好的食物。让这些食物对你不利的饥饿效果仅对玩家生效，所以它作用在同伴身上时完全无效——这一点很重要，因为它战斗的对象掉落的正是腐肉。中毒效果并非仅对玩家生效，所以蜘蛛眼不在菜单上。
• 像玩家一样战斗，而不是像怪物——攻击伤害、盔甲和武器冷却都与玩家持平，因此同伴的危险程度取决于它手里拿着什么。想让它在高难度整合包中更耐打？那四个数值由你主动提高，而不是意外提高。
• 技能 — 可重复使用的 Markdown 流程（伐木、耕种、钓鱼、收获、守家、阶梯式挖矿），可通过 /companion skill <name> 调用，也可以直接用对话方式提出需求。编辑 .md 文件即可编写自己的流程。
• 可靠的命令输出 — 容错的 JSON 解析，并提供平稳回退机制：如果模型回复格式错误，会将其作为聊天内容说出，而不是丢弃这一轮对话。
• 清楚了解用量 — 实时 HUD 面板显示本次会话的 Token 总量、输入/输出用量拆分，以及最近 30 分钟的每分钟 Token 用量图表。这样，付费端点的用量不会让你措手不及，失控的伙伴也能在一分钟内被发现（如果不想看到该面板，可使用 /companion tokens 将其隐藏）。每累计 100k 个 Token，还会在聊天和日志中报告用量总计。你也可以设置可选的硬性上限和聊天触发前缀；两者默认均关闭。
• 了解伙伴状态 — 状态面板会显示每位伙伴的生命值和饥饿值（包括饥饿条上方的饱和度余量）。只有伙伴受伤或开始饥饿时才会显示，状态恢复后会逐渐淡出。无论距离多远都能生效。/companion hud 可切换为始终显示，再次使用则关闭。
• 像玩家一样死亡 — 伙伴被杀死时会掉落身上携带的所有物品，包括盔甲，并告知你死亡地点。它收集的物品和你交给它的物品都不会因死亡而丢失；像捡回自己的物品一样前去拾取即可。（物品仍会在通常的五分钟后消失，所以别磨蹭。）
• 再次找到伙伴 — 定位条 HUD 会指向你的伙伴，即使超出实体追踪范围也能使用，因此伙伴走远了也不会彻底失联。
• 召回命令 — 将走远的伙伴召回，或询问它的位置。
• 游戏内配置界面 — /companion config 会在客户端中打开设置界面，可配置伙伴、LLM、语音和行为；修改会立即生效，无需重启。若你更喜欢手动编辑，可使用 /companion reload 重新读取 JSON 文件。安装 Mod Menu 后，那里也会出现配置按钮（可选——不安装也不会影响任何功能）。
• 可选的本地语音 — 将语音台词发送到本地 Kokoro TTS 端点，并为每位伙伴设置不同的声音；只有伙伴说出的 message 会转换为语音，推理内容和命令都不会。

命令

每个针对特定伙伴的子命令都可以在末尾加上可选的名称，用于指定目标伙伴。在只有一位伙伴的世界中，可以省略名称。

除了使用命令，你也可以直接在聊天中和它们交谈——这是指挥它们的主要方式：

• 按名称指定： Rook, go and scout north 只会发给 Rook，且模型看到消息前会移除名称。
• 向整个群组发送：以 all:、everyone:、both: 或 team: 开头，听得到的每位同伴都会收到消息；它们也会知道这条消息是发给整个群组的，因此会分工协作，而不是重复做同一件事。冒号（或逗号）是必需的——否则，“一切都好”会让你拥有的每位同伴都回复。这是唯一一种会为每位同伴分别消耗一次回复的形式，因此游戏会告诉你消息发给了谁。

配置

首次启动时，模组会写入 config/aicompanion.json，其中包含带说明的默认设置。你可以通过两种方式编辑：使用游戏内界面（/companion config，或 Mod Menu 中的齿轮按钮）实时应用更改；或者手动编辑 JSON 文件，然后使用 /companion reload。主要设置：

• 同伴：一个 companions 列表——每个条目都包含 name、description、systemPrompt（角色设定）、skin（file + slim）以及 voice。将 64×64 的玩家皮肤 PNG 放入 config/aicompanion/skins/，并在 skin.file 中填写其名称。
• LLM： endpoint（默认为 http://localhost:3030）、model、temperature、maxTokens（默认为 1000）、timeoutMs、useGrammar。
• 云端/前沿模型：将 endpoint 设置为托管 API，并通过 AICOMPANION_LLM_APIKEY 环境变量（推荐）或 apiKey 字段提供密钥。xAI/Grok 配置示例：

"llm": {
  "endpoint": "https://api.x.ai",
  "model": "grok-4-1-fast-non-reasoning",
  "temperature": 0.7,
  "maxTokens": 1000,
  "apiKey": "xai-your-key-here"
}

endpoint只填写基础 URL——末尾不要加斜杠，也不要添加 /v1；模组会自行追加
/v1/chat/completions。同时请选择非推理模型：推理模型速度较慢，而且会对同伴用不到的思考令牌收费。其他兼容 OpenAI 的服务提供商也采用相同配置方式。

不要将 maxTokens 设置为低于 1000。它是一个上限，不是预算——你只需为实际生成的内容付费，因此短回复使用较高的值不会增加费用，而值过低则会悄悄导致功能出错：技能会让模型逐字重复一条命令，如果回复在 JSON 中途被截断，就不会执行任何命令，伙伴也只会呆站在那里。请改用 llm.maxRequests 和
behavior.maxAutonomousTurns 来控制开销。

在使用 OpenAI？建议使用 gpt-4.1-nano、gpt-4o-mini 或 gpt-4.1。gpt-5.x 和 o 系列模型属于推理模型，其隐藏思考过程也会占用 maxTokens——预算较少时，它们可能把额度全花在思考上，最后返回没有错误提示的空回复，伙伴就会默不作声。给它们设置 2000+，或者改用非推理模型。（它们也会忽略 temperature；模组会自动为它们省略此项。）

• 消耗监控： llm.usageReportEveryTokens（默认 100000）会在聊天中持续显示令牌总数；0会将其静音。llm.maxRequests是单独启用的硬性上限，达到上限后伙伴将停止回应——除非你想让它们彻底停止，否则请保持为0。
• 聊天筛选： behavior.triggerPrefix（默认为空）会让伙伴只回复以此前缀开头的消息，因此闲聊不会产生消耗。behavior.thinkThrottleSeconds设置 LLM 两次响应之间的最短间隔——间隔内的消息会排队，而不会被丢弃。behavior.aiCrossTalk（默认关闭）允许伙伴旁听并回复彼此；每条转发的消息都会触发一次完整的 LLM 响应，因此除非响应次数不收费，否则请保持关闭。
• 不自找活干：完成你交代的事情后，伙伴最多会主动再采取两次行动，然后就会等待你发话。behavior.maxAutonomousTurns可调整这个次数；0则会取消上限。
• 建造遵循生存模式规则：伙伴建造时会从自己的物品栏中支付材料，每个方块消耗一件物品，而不是凭空变出方块。缺少材料？它会先去收集，再进行建造——你只需下达一次指令。将behavior.buildCostsMaterials设为false即可使用创造模式风格建造。
• 建筑会出现在你指定的位置：放置方块前，系统会根据真实地形检查每个建造方案，避免建筑被埋在地下而看不见——不过“放在地面上”仍然意味着放在地面上，塔楼也仍会向上建造。只有幻化到高空的方案会被拒绝，且不会消耗材料。重建已经存在的建筑不会消耗材料，伙伴会如实告知，而不是假装建造了东西。behavior.buildGroundCheck可关闭此项检查。
• 手动建造： behavior.buildPhysicalPlacement（默认开启）会让伙伴走到建造地点，每个游戏刻放置几个方块，并且只放置在它能够到达的位置，同时播放挥臂动作和放置音效。behavior.buildBlocksPerTick用于设置建造速度。关闭后会恢复旧版的即时建造行为。
• 装备与补给： behavior.autoEquipArmor（开启）允许伙伴自动穿上更好的盔甲。behavior.scavengeFood（开启）会让伙伴收集附近掉落的食物，范围为behavior.scavengeRadius（16 格）。
• 防御： behavior.mobsTargetCompanion（开启）会让敌对生物像追踪玩家一样追踪伙伴。defenseFightBack（开启）和defenseUseShield（开启）用于控制交战与防护。defenseFleeFromHostiles默认关闭——开启后，伙伴会在受伤时撤退；还可以通过defenseBravery（2.0）调整它的勇敢程度。
• 战斗属性对齐：combat区块会公开attackDamageBase（1.0）、armorBase（0.0）、maxHealth（20.0）和followRange（16.0）——默认值与玩家的属性相同。如果想让伙伴在高难度整合包中更耐打，可以调高这些数值；更改会于/companion reload应用到现有伙伴。
• 语音（可选）：启用 TTS，并将tts.endpoint指向一台可通过玩家的设备访问的 Kokoro 服务器——语音播放在客户端进行（参见“需求”）。为每位伙伴设置不同的voice，方便通过声音区分它们。只有伙伴的主人能听见语音。
• 技能： skills.advertiseInPrompt（开启）会向伙伴提供每项技能的名称和描述，让你可以直接通过对话要求它使用某项技能。只有调用技能时，才会注入技能内容。

在专用服务器上，/companion config修改的是你自己的设备上的副本，而不是服务器上的副本——每个选项卡的屏幕都会用红字提示这一点。请在服务器上编辑config/aicompanion.json，然后运行/companion reload。在单人游戏和局域网主机上，屏幕功能正常。

内置内容

此下载内容独立完整。它将模组分支版本的 PlayerEngine（寻路 + 任务引擎）和 Cloth Config 前置库（用于设置界面）内置在自己的 jar 文件中，无需单独下载。内置技能和 Kokoro TTS 配置文件会在首次启动时解压到 config/aicompanion/。

请勿在你的 mods/ 文件夹中另外安装独立的 PlayerEngine jar 文件——加载时两个引擎副本会发生冲突。

鸣谢与许可

本模组基于并使用了其他创作者的优秀作品进行分支开发，并遵循上游项目的许可，采用 GNU LGPL-3.0 发布。完整鸣谢如下：

• PlayerEngine，作者 Goodbird-git — LGPL-3.0 — 本模组内置并基于此框架构建。
• Automatone，基于 Baritone（leijurv 及贡献者）的分支 — LGPL-3.0 — 提供寻路与导航功能。
• 任务引擎源自 AltoClef（adris.altoclef）系列 — 提供挖掘、收集、合成、战斗与建造功能。
• 大脑集成部分借鉴了 PlayerEngine 的 Player2 路径中的 LLM 接口，并将其改为连接本地或兼容 OpenAI 的端点。我们仅研究了参考使用者 Player2NPC 的结构；没有复用任何 Player2NPC 源代码（该项目未附带许可证）。

源代码：本模组及其修改版引擎的完整源代码可在此处获取
https://github.com/adevivo/ai-companion——这是 LGPL-3.0 的要求，源代码也依照该许可提供。

与 Mojang 或 Microsoft 无关，也未获其认可。“Minecraft”是 Mojang Synergies AB 的商标。