企业官网建设流程全解析

用 Claude 智能体在 Minecraft 里自动挖钻石，看起来像游戏脚本，但合适定位是一次 AI Agent 学习实验。把一个明确目标“挖到钻石”交给 AI，让 AI 读取游戏状态、决定下一步动作、执行动作、再观察结果继续调整，这个过程几乎覆盖了 Agent 的核心闭环。本文围绕“Claude 智能体 MC 挖钻石对抗赛”这条主线，从 Claude Code 安装开始，逐步搭建一个能在个人 Minecraft 服务器里运行的挖钻石机器人，并把它扩展成两个智能体比赛计分的对抗赛。文章适合已经会一点 JavaScript、想动手理解 Agent 工作方式、又希望结果能可视化呈现的开发者。学完之后，你能独立完成一个“AI 决策 + 游戏执行”的完整项目，并知道日志、超时、重试、计分这些工程细节该放在哪里。

这里要强调一个前提：整个实验在你自己搭建的 Minecraft 服务器里运行，不进入公共服务器，不做任何影响其他玩家的行为。挖钻石的目标只是为了验证智能体的感知、决策和执行能力，而不是做一个作弊工具。

1. 先拆解“Claude 智能体 + Minecraft 挖钻石”的架构原理

1.1 为什么把 Minecraft 当作 Agent 实验场

Minecraft 是一个非常适合做 Agent 实验的环境，原因有三点。

第一，环境状态可读取。机器人能够拿到自己的坐标、朝向、背包物品、周围方块列表，这些信息可以直接转换成结构化 JSON，成为大模型的“眼睛”。

第二，动作可执行。移动、挖掘、放置、合成、丢弃，都是有限的离散动作，可以被脚本封装成函数。Agent 不需要控制像素级画面，只需要调用这些函数。

第三，结果可量化。挖到多少钻石、花了多少时间、走过了多少区块，都能用数字统计。对抗赛的输赢、策略优劣、路径效率，全部可以复盘。

挖钻石这个任务本身也很合适。它需要 Agent 理解“钻石矿分布在深层”“需要铁镐或更好的镐才能采集”“先找到矿洞再深入比乱挖更快”这些游戏知识，并把知识转化成连续的动作序列。相比“让 AI 聊天”，这类任务更有工程感。

1.2 从“调用 API”到“Agent”的差距

很多人第一次接触 Claude，只是通过对话框输入问题、得到回答。这是单次调用，模型没有环境，也没有行动能力。

Agent 的工作方式完全不一样，它是一条循环：

感知环境 -> 形成目标 -> 拆解任务 -> 执行动作 -> 观察结果 -> 修正计划

在这个项目里，Claude 承担的是“决策层”的角色。它不直接控制鼠标键盘，而是读取机器人发来的状态描述，输出“下一步做什么”。真正在游戏里移动、挖掘的是 Mineflayer 机器人。

把两者分开，价值很明显。模型负责复杂推理和任务规划，脚本负责稳定执行。即使模型决策偶尔不合理，也不会导致游戏客户端崩溃，只会产生一次无效动作。

1.3 整体技术选型

整个系统由四部分组成：模型决策层、执行层、环境层、编排层。

如果只是跑通最小闭环，不引入 Dify 也可以。先用 Node.js + Mineflayer + Claude Code 就能完成。Dify 的价值在于把多轮 Prompt、工具调用和日志可视化，适合后续做更复杂的流程编排。

2. 环境准备：Claude Code、Node.js、Minecraft 服务器要一次装齐

2.1 需要哪些软件

在开始写代码之前，先把运行环境确认好。很多坑都出现在版本不一致上，尤其是 Minecraft 服务器版本和 Mineflayer 版本不匹配时，机器人会反复掉线。

如果你只在本机学习，可以下载一个 Minecraft Java 版服务端，不需要游戏客户端。机器人直接通过 Mineflayer 连接到服务端。

2.2 安装 Claude Code

Claude Code 是 Anthropic 推出的命令行智能体工具，可以直接在终端里完成写代码、读文件、执行命令等任务。这个项目的思路是把它当作一个可被 Node.js 调用的决策服务。

安装命令以官方文档为准，常见方式是通过 npm 全局安装：

npm install -g @anthropic-ai/claude-code

安装完成后，确认命令可用：

claude --version

如果终端提示“claude 不是内部或外部命令”，或者“无法将‘claude’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”，说明 npm 全局目录没有加入 PATH，或者安装没有成功。先执行npm root -g查看全局目录，再确认该目录是否在 PATH 中。

首次使用 Claude Code 需要配置 API Key。推荐通过环境变量注入，而不是写在代码里：

export ANTHROPIC_API_KEY="你的密钥"

在 Windows PowerShell 下可以改成：

$env:ANTHROPIC_API_KEY="你的密钥"

密钥要像密码一样管理，建议放进项目根目录的.env文件，并通过dotenv加载，不进 Git 仓库。

2.3 初始化 Node.js 项目并安装 Mineflayer

在一个新目录里初始化项目：

mkdir claude-diamond-agent cd claude-diamond-agent npm init -y

然后安装 Mineflayer 和寻路插件：

npm install mineflayer npm install mineflayer-pathfinder

mineflayer负责连接服务器和操作方块，mineflayer-pathfinder提供自动寻路能力。如果没有寻路插件，机器人就只能原地跳和转身，无法主动走向目标方块。

安装完成后，用以下代码验证能创建一个机器人：

const mineflayer = require('mineflayer') const bot = mineflayer.createBot({ host: '127.0.0.1', port: 25565, username: 'Claude_Bot_01', version: '1.20.1' }) bot.on('spawn', () => { bot.chat('AI agent online') console.log('[bot] 已进入服务器') }) bot.on('error', (err) => { console.error('[bot] 连接错误:', err.message) }) bot.on('end', (reason) => { console.log('[bot] 连接断开:', reason) })

username是机器人在游戏中的名字，必须保证服务器里没有同名在线玩家。version必须和服务端版本一致，否则协议解析会出现问题。

2.4 准备 Minecraft 个人服务器

从 Minecraft 官网或服务端发布页下载对应版本的 server 包，放到一个独立目录，启动时接受 EULA：

echo "eula=true" > eula.txt java -Xmx2G -jar server.jar nogui

为了让机器人更容易发挥，建议关闭 PvP、把难度调整为和平或简单、关闭怪物生成，避免智能体在挖钻石途中被僵尸干扰。如果是单机实验，可以把server.properties中的online-mode设为false，但这会降低安全性，必须保证只有局域网内可信设备能连接。

注意：不要把online-mode=false的服务器直接暴露到公网。个人实验环境建议只监听127.0.0.1或局域网地址。

3. 从零写一个 Mineflayer 机器人，让智能体具备“手脚”

3.1 先让机器人学会寻找钻石矿石

机器人要能挖钻石，第一步是“看见”钻石。Mineflayer 提供了findBlock接口，可以按方块名搜索周围方块。

const mineflayer = require('mineflayer') const pathfinder = require('mineflayer-pathfinder') const { GoalBlock } = require('mineflayer-pathfinder').goals const bot = mineflayer.createBot({ host: '127.0.0.1', port: 25565, username: 'Claude_Bot_01', version: '1.20.1' }) bot.loadPlugin(pathfinder.pathfinder) function findNearestDiamond(maxDistance = 32) { return bot.findBlock({ matching: (block) => block.name === 'diamond_ore' || block.name === 'deepslate_diamond_ore', maxDistance }) } async function moveToBlock(block) { await bot.pathfinder.goto(new GoalBlock(block.position.x, block.position.y, block.position.z)) } async function digBlock(block) { await bot.dig(block) }

diamond_ore是普通石质钻石矿石，deepslate_diamond_ore是深板岩钻石矿石。在 1.18 版本之后，钻石矿主要出现在深层，所以两种都要匹配。

3.2 把“挖钻石”组织成可执行函数

找到方块之后，不能直接冲过去挖。机器人要先确认自己的工具、当前位置和目标方块之间是否有障碍，然后才执行挖掘。

下面是一个更完整的挖掘函数：

async function collectDiamond() { const target = findNearestDiamond(48) if (!target) { console.log('[collect] 附近没有钻石矿石，需要继续探索') return { success: false, reason: 'not_found' } } try { await moveToBlock(target) await bot.waitForTicks(5) await digBlock(target) await bot.waitForTicks(10) console.log('[collect] 挖掘完成') return { success: true, reason: 'digged' } } catch (err) { console.error('[collect] 挖掘失败:', err.message) return { success: false, reason: 'failed' } } }

waitForTicks是 Mineflayer 中的等待函数，用于模拟游戏刻的推进。移动之后立刻挖掘，可能会因为机器人和方块之间还没对齐而失败，加几个 tick 等待会更稳定。

3.3 用结构化状态描述让 AI 理解环境

Claude 无法直接读取游戏运行时的变量，你必须把机器人当前状态整理成文本或 JSON 再发给它。状态信息越简洁，模型越容易给出有效决策。

推荐只保留这些字段：坐标、朝向、背包钻石数量、当前目标任务、附近方块摘要。

function buildStateReport() { const inventory = bot.inventory.items() const diamonds = inventory .filter((item) => item.name === 'diamond') .reduce((sum, item) => sum + item.count, 0) return { position: bot.entity.position, yaw: Math.round(bot.entity.yaw * 100) / 100, diamondCount: diamonds, nearbyBlocks: bot.findBlock({ matching: () => true, maxDistance: 16, count: 20 }).map((block) => block.name) } }

这样 AI 看到的状态就是“我现在在坐标 X 深度是 Y，背包装备是铁镐，钻石数量是 0，附近 16 格内有石头、泥土、铁矿石”。它不需要理解游戏画面，只需要处理这个结构化的环境摘要。

3.4 让机器人具备基本“探索”策略

钻石矿不会总在眼前。机器人必须有一套不依赖模型也能运行的探索逻辑，否则每次找不到钻石都去问 Claude，既慢又费 token。

可以先用启发式规则兜底：当机器人周围找不到钻石矿石时，向更深层下降，或者沿矿洞方向前进。

async function explore() { const pos = bot.entity.position const targetY = Math.max(pos.y - 1, -58) const target = new GoalBlock(pos.x + 10, targetY, pos.z) await bot.pathfinder.goto(target) }

这里的“探索”是确定性的脚本行为。Claude 的职责是判断“当前应该挖、应该找、还是应该继续深入”，具体移动路径由寻路插件完成。这种分工能大幅减少模型调用次数。

4. 接入 Claude Code 决策层，形成感知-决策-执行闭环

4.1 用 Claude Code 的非交互模式做决策

Claude Code 除了交互式聊天，还提供了适合脚本调用的非交互模式。可以在终端中直接传 prompt：

claude -p "用一个词回答：Minecraft 钻石矿石通常出现在什么深度？"

Node.js 可以通过child_process调用这个命令，把机器人的状态报告放进 prompt，把返回结果解析成动作指令。

const { execSync } = require('child_process') function askClaudeForAction(stateReport) { const prompt = ` 你是 Minecraft 挖钻石智能体。请根据状态决定下一步动作。 状态： ${JSON.stringify(stateReport, null, 2)} 只能输出 JSON： { "action": "dig | explore | move | done", "target": "具体方向或坐标", "reason": "选择该动作的简短理由" } ` const result = execSync(`claude -p "${prompt}"`, { encoding: 'utf-8', timeout: 30000, env: process.env }) return JSON.parse(result.trim()) }

这段代码的关键在于 prompt 格式固定、动作枚举有限、输出强制 JSON。如果让 AI 自由发挥，后面的解析逻辑会变得不可维护。

4.2 构造感知-决策-执行主循环

有了感知函数、执行函数和决策函数，就可以把它们组合成一个主循环。

let running = true async function agentLoop() { while (running) { const state = buildStateReport() const decision = askClaudeForAction(state) console.log('[agent] 决策:', decision) if (decision.action === 'done' || state.diamondCount >= 8) { console.log('[agent] 目标完成，结束循环') running = false break } if (decision.action === 'dig') { await collectDiamond() } else if (decision.action === 'explore') { await explore() } else if (decision.action === 'move') { // 尝试解析坐标 } // 每次动作之间留出时间，避免游戏刻响应不过来 await bot.waitForTicks(20) } }

这个循环看起来简单，却是 Agent 的骨架。模型的一次输出只决定一个动作，真正的判断依据仍然是下一次环境感知。多轮下来，任务会被逐步推进。

4.3 让循环在出错时也能继续运行

模型输出不一定每次都合法。JSON 解析失败、动作枚举不存在、路径寻路超时，都是会出现的问题。

要给循环加上容错机制：

function safeParseAction(rawOutput) { try { const parsed = JSON.parse(rawOutput) if (!parsed.action) return { action: 'explore', reason: '缺少 action 字段' } return parsed } catch (err) { console.error('[agent] JSON 解析失败:', rawOutput) return { action: 'explore', reason: '模型输出非法' } } }

兜底动作选择“explore”而不是“停止”，是为了让机器人至少保持移动。如果每次非法输出都结束进程，整个项目会非常脆弱。

4.4 引入 cc-switch 和 Ollama 作为可选配置

Claude Code 的 API 配置可以通过环境变量控制。如果团队需要在多个模型网关之间切换，可以使用 cc-switch 这类社区工具管理配置。它本质上是一个配置切换器，不改变 Agent 的运行逻辑。

如果希望把决策层换成本地模型，可以借助 Ollama 部署模型，并通过兼容接口把 Claude Code 的 base URL 指向本地服务。代价是本地模型的推理能力通常不如云端模型，但优势是数据不出本机、成本固定。实际选择取决于你的场景：学习实验用官方 Claude Code 更省心；离线开发或隐私敏感场景才需要考虑本地模型方案。

5. 升级成双人对抗赛：裁判计分与多智能体协作

5.1 对抗赛规则设计

单机器人只能验证“能不能挖到钻石”，对抗赛才能真正展示“谁的策略更好”。规则要简单、可执行、可统计。

规则越简单，裁判逻辑越容易写。实际运行时，两个机器人分别用不同username登陆同一个服务器，互不通信，各自执行自己的决策循环。

5.2 裁判模块与计分

裁判模块独立于机器人运行，负责周期性地读取两个机器人的背包状态并输出比分。

let scoreA = 0 let scoreB = 0 let elapsed = 0 const timeLimit = 600 const checkInterval = 5 function countDiamonds(bot) { return bot.inventory.items() .filter((item) => item.name === 'diamond') .reduce((sum, item) => sum + item.count, 0) } setInterval(() => { elapsed += checkInterval scoreA = countDiamonds(botA) scoreB = countDiamonds(botB) console.log(`[score] ${elapsed}s A=${scoreA} B=${scoreB}`) if (elapsed >= timeLimit || scoreA >= 8 || scoreB >= 8) { endMatch(scoreA, scoreB) } }, checkInterval * 1000) function endMatch(scoreA, scoreB) { if (scoreA === scoreB) console.log('[result] 平局') if (scoreA > scoreB) console.log('[result] A 获胜') if (scoreA < scoreB) console.log('[result] B 获胜') console.log(`[result] 最终比分 A=${scoreA} B=${scoreB}`) process.exit(0) }

裁判模块的价值不只是决定输赢，它还会产生结构化的时间线日志。比赛结束后，你可以回放任意时间点的双方分差，分析某个决策是否有效。

5.3 从竞争到协作：多智能体扩展

对抗赛是竞争型多智能体。另一种更复杂的模式是协作型多智能体：一个机器人负责探路和标记矿洞，另一个负责跟随挖掘。协作场景需要共享状态，最简单的方式是让两个机器人读写同一个 JSON 文件。

{ "shared_goal": "find_diamond", "known_caves": [ { "x": 100, "y": -50, "z": 200, "status": "exploring" } ], "target_diamond_count": 8, "updated_at": 1710000000 }

两个机器人每隔几秒读取一次共享文件，把自己的探索结果更新进去。这个方案比直接让两个智能体互相聊天更可靠，因为文件状态天然可回溯、可恢复。

注意：多机器人同时跑会导致服务器 TPS 下降，机器人数量越多，决策循环频率就要越低。本地实验建议先跑 2 个机器人。

5.4 多智能体对抗赛的观察重点

对抗赛结束后，重点复盘三类问题：

第一，决策质量。Claude 有没有在明显有钻石矿的位置继续盲目探索？有没有反复在同一个矿洞口进出？

第二，执行效率。机器人寻路是否绕路？挖掘后有没有立刻拾取掉落物？

第三，资源配置。两个机器人是否抢同一个矿脉？如果是在协作模式下，探路信息有没有被另一方有效利用。

这些观察比最终比分更重要，因为它们直接指向 Agent 系统下一步要调优的地方。

6. 完整运行流程、预期输出与常见问题排查

6.1 完整启动顺序

按以下顺序启动，能最大程度避免环境混乱：

# 第一步：启动 Minecraft 服务端 java -Xmx2G -jar server.jar nogui # 第二步：确认服务端已输出 "Done" 启动信息 # 第三步：启动机器人 A node botA.js # 第四步：启动机器人 B node botB.js # 第五步：启动裁判进程 node referee.js

如果在同一台机器上运行，三个机器人脚本会共享 CPU 和内存资源。先启动服务端，再启动机器人，最后启动裁判，可以避免机器人因为服务端未就绪而反复重连。

6.2 预期输出

正常情况下，可以期待看到以下日志：

[bot] 已进入服务器 [agent] 决策: { action: 'explore', target: '向下', reason: '钻石矿通常在深层，需要下降' } [bot] 移动到坐标 100, -50, 200 [collect] 附近没有钻石矿石，需要继续探索 [agent] 决策: { action: 'dig', target: 'diamond_ore', reason: '发现钻石矿石，开始挖掘' } [collect] 挖掘完成 [score] 120s A=2 B=1 [result] 最终比分 A=8 B=5

如果日志长时间停在“附近没有钻石矿石”，说明探索策略没有有效向深层推进。如果频繁出现“JSON 解析失败”，说明 prompt 格式约束不够严格，需要在提示词里增加更强硬的输出限制。

6.3 常见问题排查表

6.4 排查链路推荐顺序

遇到问题时，不要先怀疑模型。按以下顺序排查：

1. 服务器是否正常启动，TPS 是否稳定。
2. 机器人是否成功上线，日志有没有连接错误。
3. 机器人所在位置、深度是否符合预期。
4. 感知函数返回的状态字段是否完整。
5. 模型返回的动作是否被正确解析。
6. 执行函数是否正常返回，有没有抛异常。

大多数“AI 不干活”的问题，其实都出在前三层。环境稳定之后，再逐步调试模型 Prompt。

7. Agent 工程化最佳实践与后续扩展方向

7.1 Agent 循环里的工程细节

跑通最小闭环之后，要把精力放在稳定性上。以下几个细节是实际运行中最重要的。

固定 Prompt 输出格式。大模型对格式的要求依赖 prompt 约束，要在 prompt 中明确“只能输出 JSON，禁止额外解释”，同时在代码里做兜底解析。

限制单次决策成本。每次调用都会消耗 token。不要让 Agent 在“前方没有钻石”的情况下反复问模型，先用脚本做简单探索。

日志要带时间戳和状态切片。每一轮循环记录决策、动作、状态变化，赛后才能定位问题。

function logRound(state, decision, result) { const line = { time: new Date().toISOString(), position: state.position, diamondCount: state.diamondCount, decision, result } console.log(JSON.stringify(line)) }

结构化日志比散装文字更容易处理。用JSON.stringify输出一整行，后续可以用 jq 或 Python 脚本快速分析。

7.2 成本、安全与资源控制

生产化运行之前，要解决成本和风险问题。

API Key 必须通过环境变量或密钥管理服务加载，不能出现在代码仓库和日志里。单次实验也要关注 token 消耗，建议记录每一轮调用 token 数，设置单次比赛预算。

Minecraft 服务器只监听本机或可信局域网地址。不要把带online-mode=false的服务器暴露到公网，否则任何人都能连接并进入你的实验环境。

每次运行要设置硬性超时。智能体循环不能无限跑，比赛时间、最大决策次数、最大循环次数都要有上限。

7.3 从“挖钻石”扩展到更复杂的 Agent 项目

挖钻石项目本质上是一个“目标导向型 Agent”的最小原型。把“钻石”替换成“木材”“铁锭”，或者把“挖”替换成“建造”，方法几乎不变。

可以按以下方向扩展：

如果觉得写代码成本高，可以尝试 Dify 搭建可视化工作流，把“感知-决策-执行”节点化。它的逻辑和本文一致，只是把胶水代码变成了可视化连线。

7.4 运行前检查清单

每次实验前，按下面清单确认一遍，能省下大量排错时间：

• 服务器版本与mineflayer和minecraft-data版本一致。
• 机器人用户名没有冲突。
• 服务器只监听本机或局域网地址。
• ANTHROPIC_API_KEY已配置且未写入代码。
• 决策命令配置了超时和重试。
• 探索逻辑有最小深度下限，避免在地表反复徘徊。
• 裁判模块有时间限制和结束条件。
• 每轮循环输出结构化日志。
• 记录了比赛开始前的 token 数量或预算。
• 赛后保存了比分时间线和关键决策日志。

这份清单同时适用于单机器人测试和双机器人对抗赛。稳定跑完一次完整比赛之后，再考虑增加模型能力、视觉模块或更复杂的协作协议。

这个项目里最值得一提的判断是：不要让 AI 控制每一个细节，而是让 AI 只做它擅长的决策，把执行交给稳定脚本。挖钻石任务之所以适合入门，正是因为它能让决策层和执行层的边界变得非常清楚。下一步练习建议，是回到日志文件，挑一段失败路径，还原当时的 Prompt、状态和决策，找出是模型策略问题还是环境感知问题。能完成这个复盘，你对 Agent 系统的理解就真正超过“能跑通 demo”的水平了。