AI伴侣织物

AI 伙伴

为你的 Minecraft 世界打造 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 Loader 和 Fabric API。寻路/任务引擎已集成在此 jar 文件中——你无需单独下载。

语音输出（伙伴大声说话）是可选的，需要一个小的本地 Kokoro TTS 容器。你需要的一切都已随模组提供：首次启动时，它会写入包含 docker-compose.yml 和完整 README.md 的 config/aicompanion/tts/ 目录。安装 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 “看到”的一部分，因此装备情况可以被确认。
• 可以使用盾牌 —— 携带的盾牌位于副手，可用于抵御苦力怕、箭矢和近战攻击。它会像你的一样磨损和损坏。
• 会饥饿并进食 —— 恢复生命值需要消耗食物，就像你一样。伙伴会自己进食：明显地，用正常的几秒钟时间，在战斗间隙补充能量，而不是等到绝望时才吃。它会捡起路过的食物，并在击杀后清理战场。它不会饿死。
• 它不挑食 —— 生肉和腐肉对伙伴来说是完全好的食物。对你来说让这些食物成为坏主意的饥饿效果仅对玩家有效，因此它作用在伙伴身上不会有任何效果——这很重要，因为它战斗的对象掉落的正是腐肉。中毒并非仅对玩家有效，所以蜘蛛眼仍然不能吃。
• 像玩家一样战斗，而非怪物 —— 与玩家同等的攻击伤害、护甲和武器冷却时间，因此伙伴之所以危险是因为它手持的物品。想在硬核整合包中让它更强？这四个数值可以让你自由调高，这是有意设计而非意外。
• 技能 —— 可重复使用的 Markdown 程序（伐木工、耕种、钓鱼、收割、守家、阶梯式采矿），可通过 /companion skill <name> 调用，或直接通过对话请求。编辑 .md 文件以编写你自己的技能。
• 可靠的命令输出 —— 具有优雅降级的容错 JSON 解析：畸形模型回复会作为聊天内容说出来，而不是丢弃该轮对话。
• 了解你的花费 —— 实时 HUD 面板显示会话的令牌总数、输入/输出拆分，以及最近 30 分钟的每分钟令牌数图表，因此付费端点永远不会让你意外，失控的伙伴在一分钟内就会显而易见（/companion tokens 可隐藏它）。每 100k 令牌，运行总数也会报告到聊天和日志中。可选的硬上限和聊天触发前缀可按需启用；两者默认关闭。
• 了解它们的状况 —— 状态面板显示每个伙伴的生命值和饥饿度（饥饿条上方有饱和度缓冲），仅在有人受伤或饥饿时出现，并在它们恢复后淡出。/companion hud 可在 常开 和 关闭 之间循环。适用于任何距离。
• 像玩家一样死亡 —— 如果伙伴被杀死，它会掉落所有携带的物品，包括盔甲，并告诉你位置。它收集的或你给它的任何东西都不会因死亡丢失；去捡起来，就像捡你自己的东西一样。（物品仍会在通常的五分钟计时器后消失，所以别磨蹭。）
• 再次找到它 —— 定位条 HUD 指向你的伙伴，即使超出实体追踪范围也能工作，因此走失不会弄丢伙伴。
• 召回命令 —— 召唤走散的伙伴回来，或询问它的位置。
• 游戏内配置界面 —— /companion config 会在客户端打开设置界面（伙伴、LLM、语音、行为）；编辑实时生效，无需重启。如果你更喜欢手动编辑，/companion reload 会重新读取 JSON 文件。如果安装了 Mod Menu，那里也会有一个配置按钮（可选——没有它也不会影响任何功能）。
• 可选的本地语音 —— 将语音线路路由到本地 Kokoro TTS 端点，每个伙伴可以有不同的声音；只有伙伴的 message 会被朗读，其推理或命令永远不会。

命令

每个特定于伙伴的子命令都可以带一个可选的尾部名称来指定目标。在只有一个伙伴的世界中可以省略。

命令	功能
/companion spawn [name]	从你的名单中生成一个伙伴（无参数 = 第一个未在场的）。
/companion list	显示名单以及当前在世界中的角色。
/companion goto <x> <y> <z> [name]	将伙伴送到指定坐标。
/companion come [name]	召回伙伴到你身边，中断其当前任务。
/companion where [name]	报告其坐标和与你之间的距离。
/companion stats [name]	报告其生命值、饥饿度、手部物品和物品栏。
/companion despawn [name]	将其从世界中移除（例如卡住时）。
/companion skills	列出已加载的技能及文件位置。
/companion skill [companion] <skill>	运行一个技能（如果你有多个伙伴在场，请先指定伙伴名称）。
/companion radar	循环定位条模式：ON / AUTO / OFF。
/companion hud	循环生命/饥饿面板模式：AUTO / ON / OFF。
/companion tokens	显示或隐藏令牌使用面板。
/companion config	打开游戏内设置界面。
/companion reload	重新读取 config/aicompanion.json 并实时应用。

除了命令，只需在聊天中与它们对话——这是指挥它们的主要方式：

• 按名字： Rook, go and scout north 只影响 Rook，模型看到之前名字会被移除。
• 整个团队： 以 all:、everyone:、both: 或 team: 开头，听力范围内的每个伙伴都会收到该指令，并告知每条消息都发给了团队，以便它们分工而非重复。冒号（或逗号）是必需的——否则“all good”会让每个伙伴都回复你。这是唯一一种每个伙伴都会回复一次的形式，所以游戏会告诉你消息发给了谁。

配置

首次启动时，模组会写入带有注释默认值的 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": "<a href="/linkout?remoteUrl=https%253a%252f%252fapi.x.ai%252f" target="_blank" rel="nofollow">https://api.x.ai</a>",
  "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（默认开启）使伙伴走到现场，每 tick 放置几个方块，仅放置能到达的方块，并带有手臂摆动和放置音效。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）谱系——挖掘/收集/合成/战斗/建造。
• 大脑集成将 LLM 接口从 PlayerEngine 的 Player2 路径适配为本地/OpenAI 兼容端点。参考了消费者 Player2NPC 仅用于结构研究；未复用任何 Player2NPC 源代码（其无许可证）。

源代码： 此模组及其修改后引擎的完整源代码可在 https://github.com/adevivo/ai-companion 获取——这是 LGPL-3.0 所要求的，并据此提供。

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