MaiCraft

让支持 MCP 的 AI 代理在 Minecraft 中感知环境、规划目标，并通过真实的第一人称操作完成任务。

MaiCraft 是一个服务端必装、普通玩家客户端可选的 Minecraft Mod；由 AI 控制的玩家仍需安装客户端。客户端在游戏进程内提供本地 Model Context Protocol（MCP） 服务，把大模型给出的语义目标转换为寻路、采集、合成、交互、建造等具体游戏行为。

MaiCraft 不内置大模型，也不要求额外运行 Python 服务；你仍需准备一个支持 Streamable HTTP MCP 的 AI 客户端和可用模型。官方客户端必须收到当前服务器的有效 MaiCraft 握手确认，才开放游戏感知和自动化；未确认时不降级到纯客户端模式，等待超时后自动断开。服务端按协商到的能力提供原生机器观察、配置、供料和生产验证。

Warning

MaiCraft 目前处于预览阶段，尚未发布稳定构建，也没有完成覆盖模组整合包的实机验收。请只在备份过的测试世界中使用，不要把它当作无人值守的生产级代理。

主要能力

• 感知与记忆：读取当前状态、周边环境、任务进度、地标和机器快照。
• 移动与探索：前往坐标或语义地点、寻找结构和实体、跨维度旅行，并处理游泳、开门和受限地形改造。
• 生存流程：采集物品、合成、烹饪、交易、整理容器、进食、装备、钓鱼、睡觉和照明。
• 建造与进度目标：根据用途、尺寸、风格和材料策略生成并执行建筑计划，也可组合多个目标形成连续任务。
• 战斗与里程碑：处理防御或明确授权的战斗任务，并支持末影龙、鞘翅等长流程目标。
• 模组机器：从组件关系与工艺模块生成 Create、AE2、Mekanism 和混合设备布局，规划输送网络，分批供料施工，安装 AE2 部件与存储盘，配置已支持的 Mek 接口，并核验机器几何及同步运行证据。
• 统一机器工序：附魔台、切石机和 AE2 世界流体加工复用机器建造与使用入口，按需读取真实菜单报价或原生配方，再完成有限次数的操作与成品回收。
• 服务端生产支持：读取真实库存、配方和连接，配置受支持的过滤器、接口与 AE2 样板，按实际加工事件分批投料，再验证真实交付与持续产出窗口。
• Dev 蓝图预览：在世界中显示半透明待建结构和差异轮廓，支持逐层查看；确认前归还玩家操控，确认后执行冻结的方案。
• 只读房屋设计：maicraft:design_build 直接显示蓝图，不移动或施工；普通建造在 Dev 确认之后才开始供料。
• 客户端调试键：F9 调试面板（MCP 端口、任务、动作行），F9+H 切任务列表页，F9+P 切导航路线显示，F9+A 循环切下方事件流（全部、只看最新一行、隐藏）；/maicraft dev 开关 Dev 模式（含施工预览）。
• 按需知识资源：自动发现安装模组的 Ponder 教程，按组件和场景读取原始旁白、操作提示及方块状态；支持 MCP Resources 和 perceive(view="knowledge")。
• 任务观察与控制：通过 Attention 等待权威状态、当前决策和结果摘要，完整证据按需找回；支持暂停、恢复和取消。
• 游戏聊天与命令：打开原版聊天框逐字输入，再自动提交消息或 / 命令；支持后台运行和人工接管。

MCP 客户端可以提供语义目标或声明式蓝图。MaiCraft 在游戏内负责路径、施工手法、菜单操作、重试和结果校验；调用方不提供远程点击脚本。

MCP 入口与语义能力

MaiCraft 在 MCP 的 tools/list 中注册四个通用入口：

工具	用途
perceive	以 Attention 为首选等待任务事件、决策和结果；也读取游戏状态、能力契约与世界证据
plan	编译目标而不立即执行；也可凭 plan_id 找回已保存的设计
execute	异步启动目标或计划，返回任务 ID 和可直接传给 perceive 的 next_attention
task	显式检查/恢复任务，暂停、恢复、取消，或回答问题；日常等待使用 Attention

以上是服务器在 MCP tools/list 中注册的名称；客户端可以附加服务器前缀来区分不同连接。旧版使用的 maicraft_ 工具名前缀已移除，升级后请让客户端重新获取工具列表，并更新固定工具名配置。

执行后按返回的 next_attention 等待，读取响应中的 task 和 wake_reason，再按新的 next_attention 续等。Attention 直接引用任务记录，即使历史事件已被挤出缓存，也能返回仍保留的任务决策和最终结果；无需轮询 task(get) 或包装同步执行工具。原生资源订阅可使用 maicraft://attention（任务监控）和 maicraft://chatflow（收到的游戏内聊天，供专门对话的 Agent 使用），模型唤醒行为由宿主决定。

日常回执保留当前目标、状态、必要的失败事实和下一步入口，原始蓝图、旧尝试和长报告按需读取。宿主可以缓存已读信息；上下文压缩后，用保留的编号找回所需证据，无需重新执行任务。

需要的信息	调用方式
当前任务、待答问题与结果摘要	task(action="get", task_id=...)
原始目标或某次失败证据	task(action="get", task_id=..., path="/goal") 或 path="/attempts"
已保存的计划输入	plan(plan_id=..., path="/goal/parameters")，不重新编译或执行
更多任务或能力目录	同一查询复制 next_offset 到 offset；默认每页 5 项
大份报告、长文档的指定部分	perceive(resource_uri=返回的 resource_uri)，继续读取 next_uri

detail_path 指向保留的完整任务或计划，可能与摘要的字段结构不同。path="" 列出根字段；对象和数组分页返回 items，长文本返回连续的 value。出现 omitted=true 表示该值需要展开，summary 只包含部分事实，不能把未显示的内容当成空数据。

普通业务载荷超过约 8,000 字符时提供冻结回执引用；这是 JSON 载荷的投影预算，不是包含转义的 HTTP 字符数硬上限。maicraft://receipts/... 只读取原快照，不重新观察世界、不延长游戏内 snapshot_id 的有效期。临时回执最多保留 32 份，闲置 30 分钟或服务重启后失效；压缩存储按 64 MiB 预算淘汰旧份，单份超大结果保留到后续淘汰。引用失效时查询仍保留的任务，或重新做对应的只读观察，不能为找回输出重复 execute。

标准 resources/read 读取原始知识或 Schema URI 时保留完整正文和 MIME，供 Harness 程序校验与归档；模型通过 perceive(resource_uri=...) 按需查看摘要或页面。冻结回执 URI 自身仍使用分页格式，调用方须先取得需要的完整证据再确认事件游标或交付设计。

协议消费者升级后应刷新工具列表：普通工具的 JSON 只放在 content[0].text，不再重复提供同一份 structuredContent；短知识正文保留原文，结构化部分仅附资源元数据。Attention 使用 schema_version=3，无任务编号时返回任务索引，指定任务后返回当前状态和必要证据摘要。

四个入口不等于只有四种功能。运行时提供多项 maicraft:* 语义能力，包括 chat、inspect_machine、design_machine、operate_machine、build_machine、connect_mechanical_power、travel、acquire_items、craft、build 和 combat 等。它们作为 goal.ability 交给 plan 或 execute。

perceive(view="abilities") 默认一次返回全部公开能力名，semantic_abilities 是能力 ID 字符串数组，不附概要。选定后直接用 focus="maicraft:能力名" 读取完整参数和限制，两次调用即可定位并读取契约。需要比较用途时，可选 detail="summary" 一次读取全部“能力名＋概要”，或用 query 获取全部匹配候选；概要层不是读取契约的前置步骤。能力查询不分页，limit 不截断结果，非零 offset 不再接受。AI 客户端据此提交语义目标，具体路径与原生操作由 Mod 执行。

例如将以下参数交给 execute，会自动打开聊天框、逐字输入并发送；plan 只校验和规划，不打开界面：

{
  "goal": {
    "ability": "maicraft:chat",
    "outcome": "在游戏里向大家问好",
    "parameters": {"text": "大家好，我回来了！", "typing_interval_ms": 100}
  },
  "request_key": "greeting-001"
}

text 以 / 开头时走原版命令流程，例如 /home；服务器命令和客户端模组命令沿用当前玩家的权限与加载器处理。文字必须为单行，长度最多 256 个 UTF-16 字符，空白按原版规则整理。每个完整显示字符默认间隔 100 毫秒，可设置为 50–1000 毫秒；全部输入后停留 250 毫秒再自动提交。中文、组合 emoji 和重音组合不会被拆开显示。

无需窗口前台或模拟键盘。任务可从失焦产生的不可见暂停画面开始；保留玩家手动打开的暂停菜单、容器和已有聊天草稿。低帧率下输入会变慢，不会一次补打很多字。按 Esc 关闭或手动编辑/切换界面会取消自动发送；任务暂停会释放界面，恢复后继续原草稿。

同一次逻辑发送的网络重试应复用 request_key，新的消息使用新的键。结果中的 delivery_status="submitted_to_client" 表示已调用原版提交入口，服务器接收和命令执行效果仍需观察 Attention 中的后续消息。提交结果不确定时不会自动重发。

附魔和世界流体加工通过 operate_machine 的 run_production 共用入口，完整工序契约从 按需加工知识 和 inspect_machine 读取，示例见下方“机器生产目标”。旧 maicraft:enchant 仍兼容原请求与任务恢复，但不再列入默认能力清单；需要旧契约时可显式读取 perceive(view="abilities", focus="maicraft:enchant")。

移动目标还未定位时，可以使用 maicraft:travel 的 semantic_target="platform" 与 direction="down"，让 Mod 边移动边寻找下方平台，无须给坐标。transport_mode="jetpack" 保持同一次飞行控制，在平台进入局部观察后转入着陆；ground 使用普通步行寻路，auto 可选择可用的喷气背包。

所有平台搜索都使用 semantic_target="platform"，通过 direction 选择方向（up、down、forward、backward、left、right 或四个英文方位，默认 forward）。相对方向在任务开始时固定；区域搜索半径 max_distance 默认 64，范围 8–128 格。普通坐标移动仍支持省略 Y 和到达容差，exact=true 用于需要准确站位的动作。

已知高度且要求同层时，将 vertical_tolerance:0 放在 goal.parameters 中，与 destination 同级；水平仍可用 horizontal_radius 保留接近范围。完整调用示例、交通条件与到达回执见 旅行能力开发文档。

物理载具可先用受力试算与配重推荐检查设计，再通过强力胶/蜂蜜胶、物理组装器和部件控制执行真实修改。无线打字机支持配键、有限按键与反馈；fly_vehicle 在原生入座后由 Mod 持续起降、巡航和局部避障，已定位目的地还可衔接飞机旅行及末段步行。预测、配置、真实起降和停稳分别确认；完整自动飞行仍需实机验收，定向群系/结构航空搜索尚未接通。参数与实现见 物理结构 和 飞机飞控。

定点用物品可给 maicraft:use_item 提供 target.kind="coordinates"。例如把熔岩倒进一个空格：

{
  "goal": {
    "ability": "maicraft:use_item",
    "outcome": "把熔岩倒进指定格并确认返桶",
    "target": {"kind": "coordinates", "position": {"x": 10, "y": 64, "z": 10, "dimension": "minecraft:overworld"}},
    "parameters": {"item_id": "minecraft:lava_bucket", "expected_output_item_id": "minecraft:bucket"}
  }
}

满桶坐标表示流体落格，执行器自行走近、选择支撑面并瞄准；interact 携带满桶时也采用同一落格含义。定点末影之眼则对指定门框执行嵌眼。定点请求只执行一次；不带坐标时保留沿当前视线使用物品及原有加工批次行为。默认回执的 target_observation 返回目标格前后状态，声明返还物时另有 expected_output 数量变化；流体反应后的实际产物不冒充原计划结果。

perceive(view="surroundings", sections=["terrain_overview"]) 提供地形缩略信息：大致方位、相对高度、水平范围、surface_material 材质、支撑样本及未知区域。预览覆盖已加载地形的水平半径 128 格、向下 256 格，按距离使用 4／8／32 格采样间距。同一次请求会等待后续客户端帧补充结果；达到采样或响应预算后返回明确的完整／部分采样状态。远处不同材质的支撑面会优先保留，未采到的平台不代表不存在。

飞行航点允许高度偏差和观察区域内到达，后续路径仍检查真实身体碰撞。静止飞艇的已验证下降柱支持关包快速下降；确认无伤的短落可以直接关包到地面。地面移动会退出喷气背包飞行模式，落地保护也会在材料就绪后退出缓慢悬停；下一次飞行任务按需重新启用背包。

电梯的实际楼层见 surroundings.elevators，也可用 perceive(view="situation", focus="maicraft:travel") 读取。maicraft:travel 支持 elevator_floor="top"、bottom、next_up、next_down 或同步列表中的楼层 ID／名称；可用 elevator_id 指定轿厢，交通模式使用 auto 或 elevator，无须填写目的地高度。

使用 elevator_floor="ask"，或仅指定 transport_mode="elevator" 而不提供目的地，会先到电梯附近同步楼层，再返回 waiting_for_decision。LLM 用 task(action="answer") 的 retry 和 details.parameters 选择 elevator_id、elevator_floor。同步楼层是中间步骤，实际乘梯并出梯后才完成移动目标；needs_sync 表示信息未知，不代表没有楼层。

situation 与 surroundings 支持用 sections 点名所需段。默认周边观察返回附近实体、告示牌、安全信息与设备，不等待大范围地形，并在 additional_sections 提示可选的 terrain_overview。例如 sections=["elevators"] 只取电梯楼层；点名地形才等待采样。本次未产出的指定段在 sections_unavailable 中列出，大段内容仍可通过冻结回执展开。

maicraft:travel_dimension 和 maicraft:reach_milestone 可设置 prepare_portal=true，在没有观察到有效传送门时准备入口。下界门优先复用完整黑曜石框、补齐标准小门的缺块，或在附近已加载的安全空地新建十块黑曜石框，再使用打火石或已有火焰弹点火。建造和修复还需 may_alter_terrain=true；缺料按 material_policy 和 allowed_sources 获取，临时施工支撑也计入供料需求。

主世界可显式选择 portal_method="lava_cast"，使用单桶岩浆池手法：备桶 → 找水并装水 → 准备打火石或火焰弹 → 核实池岸和施工材料 → 浇筑、收水、点火。只有岩浆桶时，先通过原生倒桶放回已观察的池子，确认空桶返还后复用，不另造第二只桶。工具和材料沿既有补给策略取得；不要求持有黑曜石或钻石镐。只想建门时使用 maicraft:prepare_portal，参数例如 {"portal_method":"lava_cast","may_alter_terrain":true}，完成后停在门外。

缺少就近水源或合格池子时，备门流程自动调用现有探索并在新视点继续观察；max_resource_search_distance 默认每种缺失资源 768 格，可设为 64..2048，或设为 0 仅查已加载区域。max_search_radius 继续控制就近池岸与门框调查。已知池子在远处取水后卸载时，先回到勘查过的干燥站位，再施工。独立备门、跨维度和里程碑共用这套前置编排；回执包含当前阶段、实际桶内容、点火用品、补给目标及探索结果。接受目标不代表资源齐全或已经施工；没有取得资源时不把单纯跑图完成当作准备成功。

maicraft:find_block 查找 minecraft:lava 时，即使 count=1 也会完成范围内的可见调查，并在默认回执的 lava_pool_survey 中按同层连通面分池，报告源格数、方位、距离、已观察直岸长度及浇筑候选的填岸材料和剩余源格下界。孤立源格和流水不会被合并成足量岩浆池；候选 reserve_observed 表示填岸后已观察余量至少十五格，不保证寻路、取桶或水流结算成功。隐藏连接、池深和未加载区域仍是未知，需要模型按事实决定换视点或继续探索。

明确寻找适合浇筑的池子时，可指定 maicraft:find_block 参数 {"purpose":"portal_casting","count":1,"max_distance":128}，省略的方块类型自动设为岩浆。此时 count 按符合浇筑布局、填岸后仍保留至少十五格源岩浆的连通池计数，单个源格和不足量的小池不能使任务成功。回执给出 count_unit="casting_lava_pools"、匹配池数和各池的 matches_portal_casting；没有符合项时报告 no_suitable_lava_pool_within_bound，保留所有局部观察供继续探索。这是只读查找，不自动走出搜索范围或开始施工。

nearest_match_position 返回实际观察到的最近匹配坐标。指定浇筑用途时，该坐标属于符合条件的池子；没有合适池时不返回更近的孤立源冒充匹配。岩浆源坐标说明池子位置，不代表角色可站的位置，取桶通路仍需执行时核实。

浇筑回执分别提供 casting_actions_completed、每步原生效果、整扇门的 portal_observation.differences 和 portal_prepared。倒桶成功不等于黑曜石成型或门已点燃；产物不符时保留现场，不自动重倒或拆除错误产物。临时导流模具保留在现场，供模型决定后续整理。

池岸不平整时，执行器可在四格起手区后清理操作空间，原生补出连续岸边和后排站台，并给导流水保留侧边和后方台面。天然直岸与整形弯岸都先扣除计划填格，再确认至少保留十五格相连表层源岩浆；回执中的 site_preparation 给出填格、源格消耗与保守余量。这是按“十格门框加首桶水损耗”预留的估计，实际流体反应仍单独观察；不能由余量数字保证任意池形都能成功。

末地入口会复用已加载的完整门框，必要时通过原生末影之眼寻找要塞；核对十二个门框的朝向，只为没有眼的格子补眼。搜索和嵌眼需要 allow_rare_consumables=true。准备期间保留 protected_labels 和上层区域保护，供料后重新检查现场；点击必须得到原生确认，并观察到完整传送门表面后才继续穿门。不会制造末地门框或末地返回门，受阻和未确认的操作会返回原因。

例如，前往下界可使用 details.parameters={"destination_dimension":"minecraft:the_nether","prepare_portal":true,"may_alter_terrain":true}；前往末地再设置 allow_rare_consumables=true。未开启 prepare_portal 时保持只使用已有有效传送门的行为。

快速开始

运行要求

项目	要求
Minecraft	1.21.1
Java	21
Fabric	Fabric Loader 0.18.1+，并安装 Fabric API
NeoForge	21.1.233+
安装位置	服务端必装；AI 玩家客户端必装，普通玩家客户端可选

从源码构建

当前没有稳定版下载，请克隆仓库后自行构建：

git clone https://github.com/LittleSadSheep/MaiCraftMod.git
cd MaiCraftMod
.\gradlew.bat build --no-daemon --no-parallel --max-workers=1

Linux 或 macOS 使用：

./gradlew build --no-daemon --no-parallel --max-workers=1

构建产物位于：

• Fabric：fabric/build/libs/maicraft-fabric-1.21.1-<version>.jar
• NeoForge：neoforge/build/libs/maicraft-neoforge-1.21.1-<version>.jar

将与你的加载器匹配、文件名不含 sources 的 JAR 放入服务器及 AI 所在客户端的 mods 目录。普通玩家可以不安装 MaiCraft。Fabric 版本还需要 Fabric API。

两个平台的 CI 构建都通过后会自动发布 Release：附件就是上面两个加载器的安装包，说明取自 CHANGELOG.md 中该版本的条目。构建期间的测试包也可以从 GitHub Actions 对应运行的 Artifacts 下载，保留 14 天。自动检查与日志说明见开发指南。

建议 AI 客户端与服务端使用相同版本。单人世界由同一个客户端安装提供集成服务端支持，无需另装一份。AI 客户端入服后最多等待 200 个客户端游戏刻（通常 10 秒）完成服务端确认；等待期间禁止世界感知、F8 接管及自动化操作，超时后显示安装提示并断开连接。换服必须重新确认，普通玩家不受此客户端检查影响。

选定能力的契约附带 server_assistance 概要：ready 表示已协商。完整后端诊断使用 perceive(view="abilities", focus="maicraft:server_assistance")，其中 server_required 和 server_confirmed 说明安装要求及当前连接的确认状态；诊断中的 client_only 仅表示操作协商未就绪，不能绕过连接确认。具体操作仍需满足模组、权限、距离、材料和原生状态条件；超时或结果未知不会触发重复操作或擅自切换后端重做。

建筑规模与资源配置

客户端首次启动会生成 UTF-8 文件 config/maicraft-building.properties，包含每个配置项的中文说明。编辑后重启客户端生效；已有文件不会被默认值覆盖。数字无效时仅该项回退到默认值，并在日志及能力预算中说明。

配置项	默认值	含义
maxTargets	262144	一份建筑的最终目标数，包含明确的空气目标
maxObjects	8192	作者对象、组件及展开节点预算
maxRadius	512	相对锚点的坐标半径，单位为格
preview.maxCells	262144	预览方块和部件总数
preview.distance	256	预览绘制距离，单位为格
preview.frameMillis	2.0	每帧准备和刷新预览的工作预算，毫秒
maxProjectBytes	134217728	冻结施工单文件上限，128 MiB

配置还包含模型文件、蓝图导入、NBT 解压、采样工作量、临时支撑、MCP 请求及任务记录的容量。完整说明见内置蓝图文档。perceive(view="abilities", focus="maicraft:build") 的 planning_budget 返回本实例实际生效的值；建筑预算与机器自主规划预算分别管理。

默认容量可容纳一个 120×80×18 格、包含全部内部空气的大厅。完整目标仍会展开到内存；提高上限不会自动加载远处区块，也不代表已验证对应规模的帧率或施工速度。每帧预算在工作单元之间检查，不能中断一次原生模型或显卡操作。调低限额使旧任务无法恢复时，旧文件会保留，恢复前拒绝新的持久化执行；提高限额并重启后再恢复原任务。

清障白名单

客户端首次启动生成 config/maicraft-clearance.json，寻路挖路与建造清场共用。它是方块 ID／#方块标签 的 JSON 数组，修改后重启生效；空数组或无效配置禁止自动清障。默认明确列出原版自然地形、矿石、原木、树叶与植被；模组地形可自行加入注册 ID 或同步的标签，例如 "#c:ores"。按方块类型判断，因此玩家放置的同种泥土、石头、原木也会命中名单。

寻路遇到名单外方块会绕行；没有可行路线就失败。施工遇到名单外障碍会停止，并通过 clearance_report 向 LLM 返回维度、方块 ID、坐标、冲突数量和最近的水平选址偏移。偏移建议在已加载地形中核对整份蓝图，搜索半径 16 格；未知区块或预算不足会注明。建议仅证明目标格的清障条件，仍须重新检查地基、通路和新场地；不会自动搬迁已有工程。替换许可、保护区域、流体与不可破坏限制继续生效，自有临时支撑仍按原清理流程回收。

已建机器的现状与差异

build_machine 完成后会自动保存机器编号、名称、原地范围和设计蓝图，并在完成结果中附上一轮 blueprint_diff。该差异只报告观察结果，不触发重建或把完成的施工改判为失败；施工过程中不持续扫描。perceive(view="machines") 的 recorded_machines 可找回这些记录。

inspect_machine 支持 mode: "full" | "diff"，默认 full。例如把下面的目标交给 plan / execute，并替换实际的机器编号：

{
  "ability": "maicraft:inspect_machine",
  "outcome": "查看已建机器的实际布局",
  "parameters": {"machine_id": "<完工结果中的 machine_id>", "mode": "full"}
}

full 返回 as_built_blueprint，其中方块 ID、状态和相对位置全部从当前地图读取，包含范围内后来更换或添加的方块；不会复述存档中的旧设计。默认使用完工时记录的整机范围，也可用 radius 指定观察范围。它是地图方块状态的观察格式；库存、接口配置与生产证据仍在各自的原生观察中。

有设计记录时，full 也会附整机 blueprint_diff 和运行事实；diff 直接比较全部登记目标，省去局部勘测和库存补读，也不创建新 snapshot_id。差异区分缺块、错块、状态不符、显式空气目标被占用及真正未知；未声明格子不算隐含空气约束，结构匹配也不等于生产达标。没有设计记录时，full 仍可读现场，diff 明确返回不可用。

默认 full（offset=0）一次返回所选范围全部格子，只有非零 offset 才使用 limit；diff 接受但忽略这两个分页参数，始终比较整机。原生组件和资源页由 Mod 连续读取。部分 full 页的 has_more/next_offset 描述新的现场读取，不是冻结快照；未加载格始终为未知。参数的完整适用范围、回执路径和恢复边界见机器检查文档。

机器生产目标

沿用“生成结构 → 建造机器 → 使用机器”：design_machine 设计结构，build_machine 施工，已有场地用 operate_machine 的 operation: "run_production" 执行工序。也可在 build_machine 中提供 production 与 allow_use: true，先完成施工，再运行同一工序。机器蓝图里的源流体最终通过原生桶操作装配，并核验源格与桶的变化。

production 支持两个版本。v1 保留源、工序、接口、输送路径、配置与观察窗口，用于机器网络和持续产出验收。v2 用简短的 {schema_version:2, process, offset?, parameters} 指定有限原生过程；process 是机制，不按每种产物新增能力，offset 相对观察或建造锚点。

先用 inspect_machine 观察实际目标，取得新鲜 snapshot_id 和同一目标标签；native_processes 按现场匹配返回机制契约及只读配方观察。完整格式按需读取 maicraft://knowledge/processes，也可使用 perceive(view="knowledge", resource_uri="maicraft://knowledge/processes")。例如把下列参数交给 execute，用已观察的附魔台为一把背包铁镐附魔；尖括号内容须替换为实际观察值：

{
  "goal": {
    "ability": "maicraft:operate_machine",
    "outcome": "为一把铁镐附魔并取回",
    "target": {"kind": "landmark", "label": "<观察时使用的场地标签>"},
    "parameters": {
      "operation": "run_production",
      "snapshot_id": "<inspect_machine 返回的 snapshot_id>",
      "allow_use": true,
      "material_policy": "inventory_only",
      "production": {
        "schema_version": 2,
        "process": "minecraft:enchanting",
        "parameters": {"item_id": "minecraft:iron_pickaxe", "offer_tier": 1, "max_levels_spent": 1, "max_lapis": 1}
      }
    }
  },
  "request_key": "enchant-pickaxe-001"
}

AE2 世界流体加工沿用同一结构，换成现场流体位置的标签与快照，并使用 process: "ae2:transform"、parameters: {"recipe_id":"<现场返回的配方 ID>","batches":1}。配方、投入数量和环境条件来自原生观察；附近已有成品不能当成本次产物。

加工使用可完整观察的有界接收区，保留原模组的投掷、漂移和延迟反应。若实际早投材料也能充当触发物，无法保证逐次投料回执，任务会在消费前报告此限制。已确认产物由通用拾取流程按身份收取；拾取或同步中断时，pending_output 保留已生成物品的证据。

v2 加工只消费现有主背包原料；直接运行的材料策略仅接受 inventory_only。施工材料仍按 build_machine 的既有材料策略补给，加工缺料时组合已有 acquire_items 流程再运行，不会隐式自动补齐。

附魔过程会打开原生 GUI，读取真实报价，只提交指定档位一次，核验费用与附魔，取回成品并关闭界面。等级门槛与实际扣除等级不同，隐藏随机词条不作保证；报价、预算或空间不满足时停止。结果中的 item_return_verified、gui_closed 分别说明取回和关闭是否已核验。

同一请求的网络重试复用 request_key。过程支持暂停、取消和手动接管；开始持久化消费预约后禁止普通自动重试，刷新快照也不会重置同一消费身份。出现 outcome_uncertain 时先检查现场、物品与经验，再决定后续恢复目标。

v1 网络配方、配置、供料与生产证明仍依赖协商到的服务端能力；精确格式见能力契约、加工知识与蓝图说明。服务器确认安装后，普通建造与原版附魔等过程仍由客户端执行；需要特定服务端证据的目标会明确说明缺少的能力。

v1 成功要求真实加工事件、声明的时间跨度和目标物品的原生交付。世界流体加工的 native_recipe_verified 表示原生配方事件已验证；仅观察到产物拾取与背包变化时，evidence_scope="client_observed_output_and_inventory"，不宣称原生配方事件已确认。这些有限过程也不证明持续产线；库存增加、机器旋转或一次接口调用成功都不能单独证明持续生产。

地图探索与跑图记忆

maicraft:explore 可指定 biome_id、biome_tag 或 structure_id；不指定种类时执行跑图勘察。 direction 支持水平八方和 forward/backward/left/right，相对方向在出发时固定。 angle_degrees 是扇区的总开口角，指定方向后默认 90°；扇区外更近的地点不能代替目标，行走路线仍允许绕障碍。 min_distance 指定候选地点离起点的最小距离，定向探索默认 16 格。 coast 等价于 minecraft:beach；其他海岸或模组群系可通过群系 ID、标签选择。

先按当前模组注册表列出或查询种类，省略 query 即为 list，按 next_query 翻页：

{"view":"exploration","focus":"biomes","query":"forest","limit":5}

focus 还可取 biome_tags 或 structures。结构目录说明可用的可见证据规则；客户端未同步完整结构注册表时会标出目录范围。 模组可在 assets/<namespace>/maicraft/structure_evidence/*.json 提供结构规则，本地规则放在 config/maicraft/structure_evidence/*.json。 规则声明 canonicalId、dimensions、clusterRadius、minimumTotal、evidenceDescription 与 groups（每组有 label、minimum、blockIds）。 可见方块组合只能证明符合特征，不证明建筑由世界生成器生成。

{"goal":{"ability":"maicraft:explore","outcome":"向北寻找森林","parameters":{"biome_tag":"minecraft:is_forest","direction":"north","angle_degrees":100,"max_distance":768}}}

探索只通过实际移动加载地形，并把沿途看见及到访的群系、目标结构写入共用 config/maicraft/memory.sqlite 的 exploration 分区。 世界、维度和空间区域分别标识；重新启动后可查询，普通身体状态不加载全部历史。 默认回执只给保存状态及本次跑图的 run:... 查询入口，可跨重启分页找回该次发现；历史地点展示最近观察，使用前需重新确认现状。

{"view":"exploration","focus":"discoveries","query":"forest","limit":5}

地点摘要返回 details_focus 和可直接用于 maicraft:travel 的 travel_target。 选中 details_focus 可读取坐标及完整证据；focus=pending 可查看保存失败后保留的待写记录。 自由跑图到达范围边缘或没有新前沿时结束，并报告实际原因，不宣称已经覆盖全部区块。

机器记忆与后台生产

固定设备可以把动力、电力等声明为 external_inputs，优先接入主城已有设施。每种介质默认只设一个入口；确需分网时最多三个，且每个入口都要说明理由。语义设计为入口列出 consumers，布局器生成真实被动连接器和内部支路；显式蓝图则保存入口的相对坐标、方块及连接面。入口本身不会产生应力、电能或物资。

施工与外部接线分开执行：先用不带 production 的 build_machine 建成设备，再重新观察机器，用 modify_machine 的 connect_external_input 指定 input_id 和主城设施的 source_label。最后才按需 run_production。perceive(view="machines") 的 utility_installations 会保存接口和历史施工状态，标签可用 机器名/入口ID 定位；历史记录不证明现在仍已通电。

当前自动接线覆盖 Create 竖轴接口和 FE／Mek 电缆，使用真实材料并核对精确接入面。流体、化学品和物品可声明布局接口，自动外部接线尚需对应的原生资源出入验证，当前会在修改前报告不支持。旋转、电量、连接和实际生产各有独立证据，接通并不表示已达到持续吞吐量。

supply_preference 默认为 external；有意自建能源时使用 onsite 并填写 onsite_reason。生存预检会指出已知创造专用物品；只有真实携带该物品或观察到整合包提供的配方产物证据才放行这项检查，普通缺料仍按材料策略处理，配方证据也不代表材料已经齐全。

MaiCraft 会增量记录附近已加载区块里的机器和容器，不为发现设备额外寻路或加载远处区块。perceive(view="machines") 同时列出现场快照、记住的设备、登记的产线及后台监测任务；focus 可指定设备 ID、产线标签或 产线标签/节点ID。用途线索与原生观察分开显示，自动发现不会把相邻方块猜成已经验证的完整工厂。

永久状态统一保存在游戏目录 config/maicraft/memory.sqlite，覆盖任务进度、地标、容器记忆、施工归属、机器及完整蓝图、作者模型版本、续建项目与支撑账、原生提交预约和服务端未决请求。SQLite 驱动随 Fabric 和 NeoForge 发布包内置，无需安装数据库服务。任务记忆沿用存档或服务器身份；机器档案和施工归属继续区分玩家。已登记生产清单保留节点、接口、坐标关系和历史调试证据。重连后历史记录不会自动变成当前状态或修改权限；修改前仍需重新观察现场。

首次读取对应记录时，自动导入旧 config/maicraft/state/、config/maicraft/machines/ 以及 server-assistance-unresolved.json 和其 .pending 文件；导入成功后保留源文件，新写入使用 SQLite。机器索引与引用蓝图在同一事务中保存，旧工程编号、模型父版本和原生预约身份继续有效。数据库不可读或恢复超过当前预算时保留原记录并报告原因，不以空记忆覆盖旧进度。备份时先正常退出游戏，再复制整个 config/maicraft/ 目录。

MCP 大回执也使用 SQLite，按原有会话寿命存入独立临时数据库，过期或关闭服务时清理；压缩计费和完整回执读取方式保持一致。配置以及 JSON/NBT 蓝图导入导出使用其文件格式。各类记录的分区与迁移说明见世界身份绑定与检查点。

直播和日常使用可采用“短时调试 → 登记后台观察 → 通过真实界面备料/启动 → 去做其他事情”的流程：

• run_production 可执行 v1 网络样本或 v2 有限过程；v1 的样本最小跨度与允许的加工间隔分别配置，无需为了调试刻意跑很长一批。
• 在下一批开始前，调用 operate_machine 的 watch_production，提供新鲜 snapshot_id、v1 production 和 allow_use: true。登记时就近核对必要位置，成功只表示监测已登记，随后释放角色；v2 过程不支持后台监测。
• 后台只读原生加工、配送和收货状态，通过 Attention 发出 machine_production_completed 或 machine_production_attention；不会自行补料、改配置或反复巡视。cancel_watch 使用返回的 job_id 停止监测，不关闭机器。
• 监测不强制加载区块，未加载时保持未知；当前监测限于同一玩家连接与维度，重连、换维度或重新进入世界后需重新登记。默认最多一小时，具体额度以能力契约为准。

有原生 GUI 的供料容器、已接入的机器配置和固定 AE2 终端会实际打开对应界面；服务端请求绑定该菜单和具体目标，并同步真实库存变化。Create 的世界交互面板等没有容器 GUI 的操作沿用原生世界交互。

连接 MCP 客户端

1. 启动装有 MaiCraft 的 Minecraft 客户端。
2. 在游戏中执行 /maicraft status，确认 MCP 显示为可用。
3. 在支持 Streamable HTTP 的 MCP 客户端中添加以下地址：

http://127.0.0.1:8766/mcp

4. 进入世界后，让 AI 客户端先读取 perceive 提供的能力，再开始任务。

同一台电脑运行多个客户端时，后启动的进程在配置端口被占时会自动向后让行（最多 +16），各自拿到可用端点；实际地址写入启动日志（让行为 WARN 级），也可在游戏内调试面板或 /maicraft status 查看。要固定某个进程的端口身份（例如给不同 AI 会话配置不同地址），可添加 JVM 参数 -Dmaicraft.mcp.port=8767 并连接对应端口；设为 0 时由系统分配端口。多客户端同时驱动时注意实际端口对应的是哪个游戏进程。

运行中的客户端也可以用 /maicraft port <端口> 把 MCP 搬到新端口：只重启传输层，游戏内正在执行的任务继续；旧连接全部断开，聊天栏会回报实际地址，AI 客户端需改连并重新初始化。

人工临时接管角色（手动走位、脱离险境）后，可用 /maicraft cleartask 清空正在执行的任务：被清任务按取消结算，等待中的 AI 调用会收到取消回执，松开控制后 AI 不会继续执行已失位的旧任务。

默认服务只监听本机回环地址，但当前默认配置不启用 Bearer Token。不要通过端口转发、反向代理或隧道将 8766 端口暴露给其他设备或公网。

当前限制

• 执行仍由客户端控制真实玩家。服务端增强补充权威状态和受检查的原生操作；未观察到的信息保持未知。
• 自动化会操作本地玩家的真实身体、物品和方块。破坏地形、攻击、丢弃物品或修改机器等行为需要明确授权，但测试世界和备份仍然必不可少。
• 机器编译器支持已建模的组件、工艺模块与接口。未知模组结构或介质会返回具体编译问题；机器摆放、配置、成型和实际产出使用分别可核验的证据。
• AE2、Create、Mekanism 及其他模组的兼容能力仍在扩展；特殊 GUI、过滤器、侧面配置和动态配方可能无法操作。
• 目前真实生产事件覆盖 Create 压机、磨粉机、粉碎轮及受支持的 Mek 配方缓存，目标物品交付使用 Mek 原生物流事件。流体、化学品运输、持续化学消耗和复杂多方块工艺不能据此视为已完整验证；具体不支持项会保留在结果中。
• Fabric、NeoForge、真实服务器与整合包需分别验证；编译和自动回归不能替代真实游玩环境的验收。

开发

从开发文档开始，可以按玩家目标查找能力入口、理解任务生命周期，并查看各条执行链的审阅进度与验证方法。

仓库采用多加载器结构：

目录	内容
common/	MCP、语义任务、第一人称执行、寻路与共享游戏逻辑
fabric/	Fabric 通用与客户端入口、加载器配置
neoforge/	NeoForge 通用与客户端入口、加载器配置
third_party/baritone/	内嵌寻路代码及其许可证

运行回归测试

日常修改只跑与改动对应的回归套件（套件名登记在 common/build.gradle，每行附有它验证的内容）。例如改了合成相关代码：

.\gradlew.bat :common:craftingRegression --console=plain

最后一行 BUILD SUCCESSFUL 表示通过；BUILD FAILED 时日志会点名失败的套件和断言原因。改动范围与套件的对照表、全量并行入口 :common:parallelRegressionCheck --max-workers=4（约 3 分半）的用法，见开发指南的构建与回归。

完整验证（并入或发布前）：

.\gradlew.bat check --no-daemon --no-parallel --max-workers=1

开发启动至少运行对应加载器的 classes 任务以更新类和资源，例如 :neoforge:classes。仅运行 compileJava 不会更新 Mod 元数据或 Mixin 配置；发布包使用 build 或 assemble。

提交问题时请附上 Minecraft 版本、加载器及版本、相关模组列表、复现步骤，以及日志中与 MaiCraft 有关的片段。欢迎提交聚焦单一问题的 Issue 和 Pull Request。

许可证

MaiCraft 作为整体以 GNU General Public License v3.0 only 发布（SPDX：GPL-3.0-only）。本项目是经过修改的作品，自 2026 年 7 月 30 日起由 LittleSadSheep 修改和维护。

仓库包含以下第三方来源：

• 部分代码派生自 minecraft-numen 的 1.21.1 分支，原许可证为 LGPL-3.0-only。本仓库依照 GNU GPLv3 第 7 条移除该副本的 LGPLv3 额外许可，将修改后的 Numen 派生代码按 GPL-3.0-only 分发；原项目及贡献者仍保留其版权。本仓库不包含 Numen 的美术、音频或品牌资产。
• 内嵌寻路代码来自 Baritone，基于上游提交 5f259b7f 修改。与 Numen 派生代码相同，本仓库依照 GNU GPLv3 第 7 条移除该副本的 LGPLv3 额外许可及非许可性附加条款，并按 GPL-3.0-only 分发；来源和修改说明见 third_party/baritone/。
• 使用 MultiLoader-Template 提供的多加载器项目结构。
• 发布包内置 SQLite JDBC 驱动，嵌套 JAR 保留上游许可证、NOTICE 和平台原生库。

鸣谢

• Minecraft 与 Mojang Studios
• minecraft-numen
• Baritone
• MultiLoader-Template