---

Numen 在你的世界里放一个 AI 同伴。你用自然语言把要做的事告诉它——打字或者按住 V 直接说，你的模型会的任何语言都行——它自己拆解成几十步动作、规划路线、选对工具、随机应变，一口气干完。

它不是个会聊天的 NPC。它是服务端的一个真玩家，挖矿、走路、挥剑、开箱子，每个动作都走原生玩家代码路径，和红石、怪物 AI、别人的 mod 站在同一套规则里。

你：    挖一组铁矿回来
Numen： 这就去。下矿找铁。
        ▸ 4 步 · locate_biome · move_to · auto_mine · collect_items   ✔
Numen： 拿到 64 个粗铁——要我熔了吗？

快速开始

1. 安装 mod（Fabric 端另需 Fabric API），启动一次。
2. 填入 API key。 按 G → 设置 → 模型，选一家，粘贴你自己的 key。
3. 召唤一个同伴。 点面板左栏的 +，给它起个名字，回车。
4. 点它的头像开聊，把要做的事告诉它。

模型：内置十家预设——OpenAI、Anthropic、DeepSeek、Kimi、智谱 GLM、豆包、Qwen、MiniMax、硅基流动、OpenRouter；填任意 OpenAI 兼容后端也行。Anthropic 走的是它自己的原生协议，不是兼容层套壳。

面板：按 G 有三页——Chat（聊天 + 实时计划面板）、Items（一张仿原版背包的只读角色卡）、Settings。左栏是同伴名册，点头像切换、点 + 召唤、点 ✕ 注销，基本不用敲指令。左边缘还有个小头像 HUD，它说话时会滑出来。设置页分十项：模型、语音输入、语音输出、人格、档案、皮肤、主题、技能库、外接大脑、MCP。

不开面板也能聊：按住 R 出同伴轮盘选人，或者直接把准星对准它；Y 弹一个极简输入框打字；按住 V 对讲机式说话，松开就把转写发过去。键位在 选项 → 控制 → Numen 里随便改。

说话和听见：语音输入内置七个预设，其中阿里云百炼和豆包是流式的，边说边转写。同伴也能出声，语音输出支持阿里云百炼、Fish Audio、GPT-SoVITS、MiniMax 和任意 OpenAI 兼容 TTS，配好音色后它会边生成边念，不用等整段说完。

macOS 语音输入：麦克风权限声明在启动器 .app 的 Info.plist 里，而 mod 跑在 Java 子进程中，补不了这层声明，所以要用声明了麦克风权限的启动器，推荐 Prism Launcher。首次使用时允许麦克风访问，之后可在「系统设置 → 隐私与安全性 → 麦克风」里检查。启动器只负责这个授权入口，录音和语音识别仍由 Numen 和你配置的服务完成。

能做什么

🧠 详细规划 · 逐步拆解任务	🔭 感知与寻路
⚔️ 原生战斗	🧩 模组兼容 · 图中为 Mekanism

近三十个工具，拼成它此刻的双手与双眼：

• ⛏️ 干活——挖矿、伐木、采集、建造、精确放置与破坏、照配方合成、用熔炉熔炼、把战利品分门别类塞进箱子。
• 🧭 走位——服务端寻路引擎：会搭桥、垫脚、搭柱上升、挖隧道、下挖楼梯、游泳。"去那个坐标"就是字面意思——哪怕一路挖到钻石层，或者从深井底自己凿一条路回地面。
• ⚔️ 战斗——原生玩家近战与弓箭，真冷却、真暴击；受伤会自己吃东西，快淹死会自己游上岸。
• 🔭 感知——扫方块、扫实体、查状态、查配方、定位结构与群系，不开 GUI 就读出一台机器里装了什么。
• 🗣️ 说话——语音进语音出，也能给它设人格、换皮肤、挑音色。
• 🧠 记性——对话跨存档持久化、太长会自动压缩；它记得用过的工作台、熔炉、箱子，下次直接走回去，而不是重造一个。死了原版死亡照常掉落，缓一会儿在你身边重生。

扩展它

同伴能玩到多深，取决于三件事，而这三件事的难度完全不同。

能不能碰——已经是通用的。 同伴是真玩家，所以模组的方块它能挖能放能右键，模组的容器它能开能拿能塞，暴露了标准 capability 的机器它能隔着外壳读出里面的物品、流体和能量。这一层不需要为任何模组单独写适配，装上就有。

知不知道是什么——大半是现成的。 配方、标签、物品名都是会同步到客户端的数据，模组也在这套体系里。"这台机器吃什么、吐什么"，对相当一部分模组来说本来就是可读的。

知不知道怎么玩——这层只能靠人。 AE2 的通道要算、Create 的应力超了整条线会停、有些东西得先升级到某一阶才有意义——这类知识不在任何数据结构里，读不出来，只能写下来教给它。这就是 Skill：config/numen/skills/ 下的 Markdown 工作流，相关时才加载、让提示词保持精简。零代码，人人能写。内置了一套示例（下界、烈焰棒、末影珍珠、要塞、龙战），改一篇或者自己写一篇，就能把你基地的规矩、或者一个新模组的玩法教给它。

光靠文字说不清的，可以直接给它加工具：mod 作者用 NumenGateway 注册一个工具，或者在设置的 MCP 一页挂上任意 Model Context Protocol 服务器（stdio 或 HTTP，带 OAuth），两种方式接进来的工具都跟内置工具一视同仁。工具是给它一把锤子，Skill 是教它怎么抡这把锤子。

前两层是一次性工程，第三层会一直长——这需要社区一起写。我们不打算假装有一天能把它写完。

外接大脑

反过来也行：Numen 能在你本机起一个 MCP 服务器，让外部 AI 客户端（Claude Desktop、Cursor，或任何支持 MCP 的东西）直接驱动你世界里的同伴——挖矿、建造、战斗、跟你说话，全部经由那个 AI。

开启期间内置大脑完全停手，同一具身体不能有两个大脑。设置里按开关即开，端点和访问令牌就在那一页，令牌默认随机生成。详见 外接大脑文档。

设计

你聊天的那个同伴，只是这套系统穿上的一具身体。底下是四部分：

• 🧍 身体——一具真玩家。 同伴是服务端的假玩家（ServerPlayer），每个动作都走原生玩家代码路径。这意味着它天生就和红石、怪物 AI、容器、以及别人的 mod 站在同一套规则里。
• 👁️ 眼睛——感知 API。 自身与世界的状态、范围方块与实体扫描、配方查询、单块检视，以及不开 GUI 就读出一台机器装着什么（物品、流体、能量）。
• ✋ 双手——行动 API。 移动、挖矿、放置、战斗、驱动任意容器/机器 GUI、管理背包、定位结构与群系。
• 🔁 反馈回路。 每一次工具返回——无论成功还是失败——都被写成教模型"Minecraft 怎么玩"的一句话。"徒手挖不动铁矿——至少装备一把石镐"，就是这套回路在干活。模型靠在环境里拿到的真实反馈决定下一步。

大脑跑在你自己的机器上：agent loop 在 owner 的客户端、用 owner 的 API key 调 LLM，每个玩家各付各的用量，服主不必替所有人买单，你也不必上交 key。LLM 传输零第三方运行时依赖，只用 JDK 的 HttpClient + Gson。

常见问题

要花钱吗？用哪个模型好？ Numen 本身开源免费，调用大模型用的是你自己的 key。想省钱用 DeepSeek、Qwen、Kimi、GLM，一次典型任务通常几分钱；想要最聪明用 Claude、GPT。模型越快越聪明，同伴表现越好。语音那两项同理，各用各的 key。

我的 API key 安全吗？ 大脑跑在你自己的客户端，key 只存在本地、只用于直连你选的后端，不经过任何第三方服务器，也不会上传给作者。

联机服能用吗？ 能。同伴是服务端的真玩家，动作由服务端逐一校验，你只能驱动自己的同伴。服务端只需装 Numen，客户端各自填各自的 key。

它会拆我家、乱来吗？ 它只做生存里一个真玩家能做的事，且每个动作都归属校验到它的主人——不会凭空造物，也不碰不属于你的东西。

响应有点慢？ 每走一步都要过一次大模型推理，模型越快体验越顺；这块仍在持续优化。

给开发者

Numen 出厂的每一个工具、每一篇技能，全部只用公共 API 写成，没有任何私有通道。任何 mod 作者都拿得到同一份能力：

• 🔧 通过 NumenGateway 注册一个工具，你 mod 的能力就长在了 AI 的手上。工具契约里刻意不含任何 Minecraft 概念——怎么完成调用（同步、异步、自己发包、调外部网络服务）完全由工具自己做主。正因如此，同一套 API 伸向一个聊天平台，和伸向一条矿脉一样顺手。
• 📖 随 jar 附带技能——一句调用就把你 jar 里的 /skills 目录变成内置技能，玩家装上你的 mod，AI 自动学会怎么玩它。
• 🏗️ 或者造一个完全不同的 AI——同一块地基上，AI NPC、剧情角色、服务器管家，随你想象。

引擎（api/）在 1.21.1 上已经并入本仓库，其余版本分支陆续跟进；对第三方它仍然作为独立坐标发布，依赖方式不变：

repositories { maven { url = 'https://raw.githubusercontent.com/Dwinovo/numen-maven/main' } }
dependencies  { modImplementation "com.dwinovo.numen:numen-api-fabric-1.21.1:<version>" }

面向集成的公共对接 API 采用 MIT 授权——写工具、写技能、写兼容，不必被 LGPL 牵着走。

自己构建：克隆仓库，./gradlew :core:fabric:build（或 :core:neoforge:build）。Bug、点子、兼容实验都欢迎——开个 issue，或者写一篇技能提 PR。

路线图

• 为大模组做适配。 Create、AE2、Mekanism 这些自成宇宙的科技 mod，得一个个真去适配——注册工具、写技能、接 MCP，哪种合适用哪种。模组生态太大，指望单一机制打通不现实。inspect_block_storage 那一眼透视是第一块砖。
• 长成一座技能库。 让"教 AI 玩一个新模组"简单到只需写一篇 Markdown，社区共建共享。
• 越玩越像个老玩家。 更深的世界记忆与长程规划。

---