前言¶
在 DSH 里做「会玩 Minecraft」的智能体，常见做法是走协议库连服务器：要处理版本、模组方块映射，容器和合成也往往和真实客户端不一致。若目标是控制你自己已经登录的整合包客户端——正版、authlib-injector、同一套模组注册名——更直接的路径是把游戏进程变成可被调用的端点，再在 DSH profile 里挂上 mc_* 工具。
下面介绍社区插件 dsh-mc-bridge（DSH 侧 npm 包名 dsh-minecraft-agent，维护者 hx95270000-lang）：一半装在客户端 mods/，一半通过 DSH 插件管理器装进当前 profile，经本机 localhost 桥接，不共享账号密码。
这是什么¶
插件由两个彼此独立的部件组成：
| 部件 | 安装位置 | 作用 |
|---|---|---|
dsh-mc-bridge-1.0.0.jar |
Minecraft 客户端 mods/ |
把真实客户端变成可被控制的机器人（仅客户端，服务器与整合包分发不必装） |
dsh-minecraft-agent/ |
DSH Desktop 的 profile | 向智能体提供 mc_join、mc_observe、mc_chat 等 mc_* 工具 |
桥驱动的是本机已登录的客户端；mod 声明 side=CLIENT，displayTest=IGNORE_ALL_VERSION，按 README 说明不挑整合包、也不影响联机握手。许可为 MIT（mod 与插件均为 MIT）。
社区目录页：hx95270000-lang/dsh-mc-bridge-1.0.0。源码与说明：GitHub 仓库。
前提与环境¶
- Minecraft 1.20.1 + Forge 47.x（
mods.toml声明 Forge[47,)、MC[1.20.1,1.21)）。 - 已安装 DSH Desktop。
- 桥接后端默认不需要 Node.js / pnpm（README 写明插件在桥后端下零第三方依赖；仅当要用协议后端连普通服务器
mc_join address=...，或读取旧版.schematic蓝图时，才涉及可选依赖与pnpm install/pnpm add prismarine-nbt）。
核心功能¶
按 README「能力与边界」一节，当前可实现：
- 进服或进单人世界；观察周围（坐标、方块普查、玩家、实体、聊天），模组方块可按真实注册名识别（如
create:cogwheel、ae2:controller）。 - 游戏内聊天与以
/开头的命令；行走（直线与跳跃）；按注册名采集、捡掉落物。 - 按蓝图、形状或
.schem建造；放置与破坏方块；点击客户端界面按钮、加载存档。 - 可选：通过
mc_join address=host:port连普通服务器（协议后端，需pnpm install）。
明确不能或尚未覆盖的：无寻路（复杂障碍会如实返回未到达）；eat 未实现；容器存取与合成目前仅在协议后端可用；不自动避怪/避岩浆；只在已加载区块内工作。
安装与启用¶
一、Minecraft 侧：安装 mod¶
- 完全关闭游戏（运行中替换 jar 可能导致
NoClassDefFoundError: local/dsh/mcbridge/Ops）。 - 将
dsh-mc-bridge-1.0.0.jar复制到整合包实例的mods/。 - 启动游戏至主菜单。
- 确认游戏目录下出现
dsh-bridge/status.json，例如：
{"port":25577,"status":"listening","pid":1234,"ticks":42}
若 port 为 -1，表示端口被占用。在启动器 JVM 参数中指定（不要把 bind 改成 0.0.0.0）：
-Ddshmcbridge.port=25588
-Ddshmcbridge.bind=127.0.0.1
二、DSH 侧：安装 profile bundle¶
插件以 npm 包 dsh-minecraft-agent 发布，package.json 中声明 dsh.bundle.patch，可由 DSH 插件管理器安装。在需要 danger-full-access 或本次批准的前提下，对当前 profile 执行：
plugin_manager action=install_bundle target=dsh-minecraft-agent
也可指定本地 tarball 或绝对路径，例如：
plugin_manager action=install_bundle target=D:/share/dsh-minecraft-agent-1.1.0.tgz
必须重启 DSH Desktop（Loader/ESM 会缓存模块）。验证：对 DSH 说「看看 Minecraft 状态」，应出现 mc_state；重启后 mc_state 应返回 status: idle。
可选：在 profile 的 cordis.patch.yml 中修改默认用户名或桥端口：
- id: mc-bot
disabled: false
config:
defaultUsername: SkyAgent
bridgePort: 25577
典型用法¶
先在游戏中进入世界或联机服务器，并保持游戏窗口在前台（单人世界失焦会暂停，服务端不 tick）。随后在 DSH 中调用工具，例如：
mc_join # 不带参数：探测本机客户端桥并连接
mc_observe radius=16 # 观察周围
mc_chat message=大家好 # 游戏内发言（亦支持 / 命令）
mc_collect block=create:cogwheel count=8
mc_build source=shape shape=hollow_box options={"width":9,"height":4,"length":7,"block":"oak_planks"}
整合包停在 Forge「加载错误」界面时，可用界面控制（中文客户端需按 screen 返回的文字或索引点击，勿依赖英文 text=continue）：
mc_control action=screen
mc_control action=screen_click index=2
mc_control action=open_world world=创造1
适用场景与注意¶
适合谁：已在 1.20.1 Forge 整合包上游玩、希望 DSH 智能体直接操作同一客户端的开发者或玩家；需要按模组注册名采集、建造、点 UI 的场景。若只需连无 mod 的公共服务器，可选用协议后端，但需额外安装依赖。
安全：桥默认只绑定 127.0.0.1，无鉴权；本机可访问该端口的程序即可控制客户端。勿使用 -Ddshmcbridge.bind=0.0.0.0 暴露到局域网或公网。插件以当前 DSH 进程权限运行，安装前请阅读源码与 MIT 许可证。
排错速查：mc_join 报 ECONNREFUSED 时检查游戏是否运行、status.json 端口；place 返回 player-occupied / no-support 时换相邻格或贴地位置；改插件代码后须重启 DSH Desktop。
DSH 生态强调「一切皆插件」；SkillHub 为社区目录，与 DeepSeek / 幻方无官方从属关系。本文事实均来自上述 GitHub README 与 package.json。
链接¶
- 目录页：https://www.skillhub.cn/plugins/hx95270000-lang/dsh-mc-bridge-1.0.0
- GitHub：https://github.com/hx95270000-lang/dsh-mc-bridge-1.0.0
