---

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

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

它还能变强。写一篇 Markdown 教它新玩法，写一个插件把机械动力、AE2 接进来。这两样社区都能写。

你：    挖一组铁矿回来
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

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

• ⛏️ 干活——挖矿、伐木、采集、建造、精确放置与破坏、照配方合成、用熔炉熔炼、把战利品分门别类塞进箱子。
• 🧭 走位——服务端寻路引擎：会跳、游、爬、开门、跑酷、驾船，也会搭桥、垫脚、搭柱、挖隧道、下挖楼梯。走路默认不改世界——墙、地板、别人的房子、地貌原样不动；唯一的路要挖要垫时，它会把会动的方块一块块列给模型，模型点头（may_alter_terrain）才开路，每次回执都如实写明路上挖了什么、放了什么。
• ⚔️ 战斗——原生玩家近战与弓箭，真冷却、真暴击；受伤会自己吃东西，快淹死会自己游上岸。
• 🔭 感知——扫方块、扫实体、查状态、查配方、定位结构与群系，不开 GUI 就读出一台机器里装了什么。
• 🗣️ 说话——语音进语音出，也能给它设人格、换皮肤、挑音色。
• 🧠 记性——对话跨存档持久化、太长会自动压缩；它记得用过的工作台、熔炉、箱子，下次直接走回去，而不是重造一个。死了原版死亡照常掉落，缓一会儿在你身边重生。

扩展它

同伴是个真玩家，所以模组的方块它能挖能放，模组的容器它能开能拿，机器只要暴露了标准 capability，它不开界面也能读出里面装着什么。这层装上就有，不用为谁单独适配。

它不知道的是玩法。AE2 的通道要算，机械动力应力超了整条线会停，有些东西得先升到某一阶才有意义。这些读不出来，只能教。

有两种教法，社区都能写。

技能是一篇 Markdown。把你基地的规矩、或者某个模组的流程写下来，丢进 config/numen/skills/ 就生效。零代码。出厂带了五篇示例：下界、烈焰棒、末影珍珠、要塞、龙战。照着改一篇最快。

插件是一个 mod，把别的模组接进来。装上机械动力的插件，同伴就会用机械动力；装上 AE2 的，它就懂 AE2。插件能做两件事：用 NumenGateway 注册工具（比如「读一下这台机器里有什么」），以及把技能装在自己 jar 里一起发。玩家装上你的插件，工具和玩法一起到手。写法见给开发者。

设置里的 MCP 那一页可以挂外部 Model Context Protocol 服务器，里面的工具跟内置的一视同仁。那是给你自己接现成服务用的。适配一个模组不能等它出 MCP 服务器，那得写插件。

外接大脑

反过来也行：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 写成，没有任何私有通道。写插件拿到的是同一份能力：

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

引擎（api/）住在本仓库的 api/ 目录里，对第三方仍作为独立坐标发布：

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

加载器不同写法不同，要改引擎机制则改依赖 core——详见 api/README。

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

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

路线图

• 为大模组做适配。 Create、AE2、Mekanism 这些自成宇宙的科技 mod，得一个个真去适配——插件 + 技能，一个模组一套工作流。inspect_block_storage 那一眼透视是第一块砖。
• 长成一座技能库。 让"教 AI 玩一个新模组"简单到只需写一篇 Markdown，社区共建共享。
• 越玩越像个老玩家。 更深的世界记忆与长程规划。

---