前言¶

在 DeepSeek Harness（DSH）里做 Minecraft 相关自动化时，常见做法是写脚本去模拟键鼠，或单独起一个 mineflayer 进程再让智能体间接调用。前者容易和 DSH 自己的窗口抢焦点、截图把 IDE 一并截进去；后者能玩协议层，但和「真实 PCL2 客户端画面」是两套路径。

dsh-mc-client 由维护者 DRheEheAMGary 发布，分类为客户端插件，当前版本 1.2.0（MIT 许可，需 Node.js >= 20）。它把两条路线收进同一套 DSH 工具：一条用 Win32 操控 E:\Minecraft 下 PCL2 启动的可见 Java 客户端；另一条在本机隐藏控制台启动 vanilla 专用服务端，用 mineflayer 协议机器人游玩，不创建游戏窗口、不渲染、不注入桌面键鼠。无窗口侧还可读 F3 类调试信息与周围方块状态。

这是什么¶

一句话：给 DeepSeek Harness 用的 Minecraft Java Edition 插件，暴露 mc_launch、mc_control、mc_headless、mc_bot 等工具，供 agent 启动/进服、键鼠或协议层操作、截图与日志回读、方块探测。

仓库：https://github.com/DRheEheAMGary/dsh-mc-client
社区目录页：https://www.skillhub.cn/plugins/DRheEheAMGary/dsh-mc-client

维护者 README 写明：已在 DSH Desktop 的 desktop profile 安装并激活，配置为 include:mc-client（你的 profile 名可替换）。

核心功能¶

无窗口游玩（headless）¶

调用方通过 JSON 工具调用 mc_headless 与 mc_bot：本机下载并启动 vanilla 专用服务端（隐藏控制台，默认绑定 127.0.0.1），可选把现有单人存档复制为服务端世界；mc_bot 以真实服务器玩家身份连接，具备坐标、血量、物品栏等，可移动、挖掘、放置、攻击、聊天、/命令、寻路（mineflayer + mineflayer-pathfinder）。

观察世界用 mc_debug（无窗口版 F3：维度、生物群系、坐标、朝向、光照、时间、延迟、实体等）和 mc_blocks（looking / at / scan / find 等模式，返回方块名称、状态、光照、硬度等）。

也可 mode: connect 连接已有离线模式服务器，而不启动本地服务端。

窗口版（PCL2 可见客户端）¶

面向必须看到真实画面的场景：

• mc_launch 重放 PCL2 的 PCL/LatestLaunch.bat，或带 server、waitInGame 自动进服（先 --quickPlayMultiplayer，客户端忽略时再 OCR 点菜单）。
• mc_control 用 Win32 SendInput 做键鼠、视角、聊天；mc_screenshot 优先只截游戏窗口。
• mc_client_log 读 PCL 或 dev 客户端 latest.log，支持 tail / grep。

1.2.0：窗口自动化可靠性¶

1.2.0 针对「真实客户端上自动化不可靠」做了加固；无窗口工具语义不变。要点包括：

• 窗口识别排除 DSH、Electron 及标题含 “Minecraft” 的 DSH 会话；聚焦失败返回 code:"focus-failed"，避免静默把输入发到 DSH。
• 截图优先 PrintWindow，DSH 盖在上面也不入镜；必要时回退桌面裁剪并标明 method:"screen-crop"。
• mc_control {action:"chat"} 可从 latest.log 回读最新 ≤10 行 [CHAT]；以 / 开头的命令用 Unicode 输入，避免剪贴板策略吞斜杠。
• mc_control {action:"state"} 返回 inGame、screen 等；visual:true 时 OCR 解析 F3 与物品栏。

安装与启用¶

插件以可安装 bundle 形式提供（package.json 的 dsh.bundle + cordis.patch.yml）。在已有本机目录的前提下，README 给出的安装步骤如下（将 desktop 换成你的 profile 名）：

cd E:\Github\dsh-mc-client
npm install
dsh plugin --profile desktop add "E:\Github\dsh-mc-client"

卸载：

dsh plugin --profile desktop remove dsh-mc-client

若你已在插件目录内，也可 dsh plugin --profile desktop add .（需先在该目录执行 npm install）。

安装前请自行阅读仓库源码与 MIT 许可证；插件随当前 DSH 进程权限运行，涉及本机进程、文件路径与网络下载（如无窗口模式拉取服务端），应按你的环境评估风险。

典型用法¶

无窗口：从启动到收尾¶

下面命令摘自 README 快速开始（默认版本示例为 26.1.2）：

mc_headless { "action": "start" }

从现有存档复制世界（路径按本机修改）：

mc_headless {
  "action": "start",
  "version": "26.1.2",
  "worldSource": "E:\\Minecraft\\.minecraft\\versions\\26.1.2\\saves\\新的世界 (1)"
}

查看状态并操作：

mc_bot { "action": "state" }
mc_bot { "action": "move", "keys": ["forward", "sprint"], "durationMs": 2000 }
mc_bot { "action": "chat", "text": "hello from the windowless world" }
mc_bot { "action": "command", "text": "/time set day" }
mc_debug {}
mc_blocks { "mode": "looking", "maxDistance": 8 }

结束：

mc_headless { "action": "stop" }

连接已有服务器（不启动本地服务端）：

mc_headless {
  "action": "start",
  "mode": "connect",
  "host": "127.0.0.1",
  "port": 25565,
  "version": "26.1.2"
}

窗口版：1.2.0 自测顺序¶

README 给出的自测顺序（需本机已启动目标服务端，示例端口 25566）：

mc_launch {edition:"java", server:"localhost:25566", waitInGame:true, waitGameSeconds:120}
mc_control {action:"state", visual:false}
mc_control {action:"chat", text:"/time set day"}
mc_screenshot {scope:"window", savePath:"docs/self-test-window.png"}
mc_client_log {grep:"CHAT|HubSuite|ERROR", tail:50}

需要 F3/背包结构化信息时，可先按 F3 或打开背包，再执行 mc_control {action:"state", visual:true}。

工具一览¶

更细的 1.2.0 参数变化见 README 中的「工具参数速查」表；完整实测输出与限制见仓库 docs/client-verification-1.2.0.md 与 docs/headless-verification.md。

适用场景与注意¶

适合谁

• 希望在 DSH agent 里统一调用 Minecraft Java：既要 PCL2 真实客户端画面与键鼠，又要无窗口、可脚本化的协议机器人和方块探测。
• 做进服、聊天/命令回读、游戏窗口截图、F3 与方块状态查询等可复现自动化（README 含本机实测记录）。

环境与限制

• 窗口版路径与示例大量面向 Windows（PCL2、E:\Minecraft、Win32 聚焦与截图）；无窗口版依赖本机 Java 与服务端下载，默认版本以 README 为准（如 26.1.2）。
• 1.2.0 明确区分游戏窗口与 DSH 窗口，但 OCR 进服、GPU 拒绝 PrintWindow 等仍有文档中记载的回退与限制。
• 社区目录 SkillHub 与 GitHub 仓库由社区维护，与 DeepSeek / 幻方无官方从属关系；DSH 生态强调「一切皆插件」，安装前以仓库 README、CHANGELOG 与许可证为准。

结尾¶

dsh-mc-client 把「可见 PCL2 客户端操控」和「无窗口专用服 + 协议机器人」放进同一插件，当前 1.2.0 又加强了窗口聚焦、截图与聊天回读，便于在 DSH 里做可验证的 Minecraft Java 自动化。

• 目录页：https://www.skillhub.cn/plugins/DRheEheAMGary/dsh-mc-client
• 源码与文档：https://github.com/DRheEheAMGary/dsh-mc-client