人工智能辅助开发

本指南记录的是 MCC 的 AI 辅助开发工作流，它是一个真正可运行的闭环，而非基于猜测的补丁生成器。 目标是为智能体提供一个可自主运行的环境：构建 MCC、启动本地服务器、发送命令、检查日志，并循环执行。 一旦这个循环搭建好了，迭代就会更快，也更容易发现并修复回归问题。

如果您想先了解更广泛的贡献者入口，请先参阅 Contributing，然后再返回此处查看代理工作流。

实际目标是一个闭环：

索引

• 此工作流涵盖的内容
• 设置
• Harness 的工作原理
• 仓库工具
• 技能
• 标准开发流程
• 测试与验证
• 版本适配说明
• 示例流程

此工作流涵盖的内容

这是……的工作流程：

• 本地 MCC 开发
• 本地离线服务器测试
• AI辅助调试
• 机器人创作
• 协议和版本适配工作
• 仍应遵循相同规范流程的文档工作

它基于两层构建：

• tools/ 目录下的工具脚本，负责执行实际操作。
• .skills/ 目录下的 AI 技能，用于指示智能体何时以及如何使用这些工具。

设置

你只需要做大部分这些操作一次。

wsl --install

wsl --install -d Ubuntu

wsl --install --web-download -d Ubuntu

echo $SHELL

sudo apt update
sudo apt install git

sudo pacman -S git

brew install git

git --version

sudo apt-get update && sudo apt-get install -y dotnet-sdk-10.0

wget https://packages.microsoft.com/config/debian/12/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb
sudo apt-get update && sudo apt-get install -y dotnet-sdk-10.0

wget https://packages.microsoft.com/config/debian/13/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb
sudo apt-get update && sudo apt-get install -y dotnet-sdk-10.0

sudo pacman -S dotnet-sdk

brew install --cask dotnet-sdk

dotnet --version

sudo apt update
sudo apt install openjdk-21-jdk

sudo pacman -S jdk21-openjdk

brew install openjdk@21
sudo ln -sfn "$(brew --prefix openjdk@21)/libexec/openjdk.jdk" /Library/Java/JavaVirtualMachines/openjdk-21.jdk

Java 版本

sudo apt update
sudo apt install python3

sudo pacman -S python

brew install python@3.14

python3 --version

sudo apt update
sudo apt install tmux

sudo pacman -S tmux

brew install tmux

tmux -V

git clone https://github.com/MCCTeam/Minecraft-Console-Client.git --recursive

git submodule update --init --recursive

tools/decompile.sh --version 1.20.6

source "$HOME/Minecraft/Minecraft-Console-Client/tools/mcc-env.sh"

source ~/.bashrc

source "$HOME/Minecraft/Minecraft-Console-Client/tools/mcc-env.sh"

source ~/.zshrc

git --version
dotnet --version
java -version
python3 --version
tmux -V

type mc-start
type mcc-build
type mcc-run

装备的运作方式

AI 代理无法像人类玩家那样获得丰富的交互式终端界面。 这就是为什么这个工作流使用挂件，而不是依赖实时键盘输入。

移动部件是：

• 在 tmux 中运行的本地 Minecraft 服务器
• mc-rcon 用于执行服务器端命令，例如 /op、/give、/summon 或游戏规则设置。
• MCC 启动时设置了 MCC_FILE_INPUT=1
• FileInputBot，用于监控 mcc_input.txt 文件，并将文件中的每一行转换为 MCC 命令或服务器聊天消息。
• 来自 MCC 和本地服务器的日志，代理可以在每次运行之间检查这些日志。

结果很简单：代理可以无需等待人工坐在终端前，就能修改代码、重新构建、启动应用、注入命令并读取执行结果。

仓库工具

这些是让工作流程变得实用的仓库级工具。

还有一点值得一提：

• MinecraftClient/ChatBots/FileInputBot.cs 是实现基于文件的命令注入功能的核心代码。
• 当设置 MCC_FILE_INPUT=1 时加载。
• tools/mcc-env.sh 中的 mcc-run 已经为您设置了该标志。

技能

上面的工具就能完成工作。 .skills/ 目录中的技能文件会告诉 AI 何时使用这些技能，以及理想的输出应是什么样。

重要的区别在于：

• 仓库工具是可执行脚本和源代码文件。
• 技能是针对 AI 的指令、参考、模板以及工作流约束。

一些技能还自带资源包：

• mcc-integration-testing 包含脚本和命令矩阵参考
• mcc-chatbot-authoring 包含引用和机器人模板
• skill-creator 封装了脚本、评估工具和审核者资源。

标准开发循环

这就是你应该期望智能体遵循的核心循环。

1. 启动本地服务器

mc-start 1.20.6

查看最近的服务器输出：

mc-log 1.20.6

2. 构建 MCC

mcc-build

3. 启用文件输入运行 MCC

mcc-run

原始形式如下：

MCC_FILE_INPUT=1 dotnet run --project MinecraftClient -c Release -- CursorBot - localhost:25565

4. 通过RCON设置服务器状态

示例：

mc-rcon "op CursorBot"
mc-rcon "gamerule sendCommandFeedback true"
mc-rcon "give CursorBot diamond_sword 1"
mc-rcon "summon minecraft:armor_stand ~ ~ ~"

5. 通过 mcc_input.txt 驱动 MCC

示例：

mcc-cmd "inventory player list"
mcc-cmd "entity"
mcc-cmd "/gamemode creative"

行为：

• 以 / 开头的行将作为服务器命令或聊天消息发送。
• 当该行不以“/”开头时，首先将其视为MCC内部命令。
• 如果一行内容不是 MCC 内部命令，则会回退为普通聊天消息发送。

6. 当……时

阅读 MCC 输出和服务器日志，判断发生了哪些变化，然后决定是继续迭代还是停止。

7。 重建并快速重启

mcc-reload

这就是回归测试的常规流程。

测试与验证

在这个工作流中主要有两种测试方式。

手动验证

对于较小的改动来说，这就足够了：

• 加入本地服务器
• 使用 mc-rcon 授予操作员权限
• 通过 mcc-cmd 运行 MCC 内部命令
• 通过 mc-rcon 触发游戏玩法或服务器状态变化
• 检查日志以查找解析错误、断连或输出异常

典型的手动检查：

• 库存列表与创造模式物品注入
• summon 后的实体追踪
• 加入后地形与区块处理
• 聊天和命令流程
• 爆炸、粒子和音效事件

脚本化全范围测试

mcc-integration-testing 技能更进一步。 它会将自己的脚本打包到 .skills/mcc-integration-testing/scripts/ 目录下，并期望从 ~/.zshrc 中加载 shell 辅助脚本。

将这些脚本视为技能专属资源。 在直接运行这些技能之前，请先阅读其说明，不要假设它们的行为与顶级仓库工具相同。

该技能旨在用于可重复的离线验证：

• 聊天
• 斜杠命令
• MCC 内部命令
• 库存管理
• 实体处理
• 粒子和音效
• TNT与爆炸处理

对AI驱动的离线测试有影响的服务器设置：

• eula=true
• online-mode=false
• enforce-secure-profile=false
• enable-rcon=true
• rcon.password=test123

如果这些设置错了，循环就会很快变得嘈杂。

版本适配说明

版本开发需要比普通 Bug 修复更严格的流程。

重要的规则很简单：

• 对于较新版本，尤其是 1.21.9+，请以服务器数据报告为准来确定物品和方块的信息。
• 使用反编译的源代码获取实现细节、字段顺序、编解码器逻辑及序列化器逻辑。
• 先别停在资源包对比上，还要完成构建并在真实服务器上测试一遍。

通常的顺序是：

1. tools/decompile.sh --version <ver>
2. 从 server.jar 生成服务器报告
3. 运行 tools/diff_registries.py
4. 重新生成实际已更改的调色板
5. 更新版本路由和数据包处理
6. 构建 MCC
7. 针对实际目标版本进行测试

这正是 mcc-version-adaptation 工具旨在引导完成的工作。

示例流程

以下是本指南旨在支持的四种常见模式。

调试运行时回归问题

使用技能：

• mcc开发工作流
• C#最佳实践

典型的循环：

mc-start 1.20.6
mcc-build
mcc-run
mc-rcon "op CursorBot"
mcc-cmd "inventory player list"
mcc-cmd "entity"

然后检查 MCC 的输出，修复代码，并使用：

mcc-reload

建造或修复机器人

使用技能：

• MCC聊天机器人创作
• C#最佳实践
• mcc开发工作流

典型流程：

1. 决定这是独立的 /script 机器人还是内置机器人。
2. 当物品栏满时，无法拾取更多物品。
3. 构建 MCC。
4. 启动本地服务器并加入。
5. 通过实时命令、聊天或事件驱动的操作来测试机器人行为。
6. 请确保清理路径（如 OnUnload()）正确无误。

对于独立脚本，技能默认为 /script，除非明确需要使用内置仓库的绑定。

将 MCC 适配到新的 Minecraft 版本

使用技能：

• MCC版本适配
• mcc开发工作流
• MCC集成测试

典型流程：

tools/decompile.sh --version 26.1

生成服务器报告：

cd /tmp
java -DbundlerMainClass=net.minecraft.data.Main \
  -jar "$MCC_SERVERS/26.1/server.jar" \
  --reports --output /tmp/mc_reports

运行注册表对比：

python3 tools/diff_registries.py 1.21.10 26.1 --registry /tmp/mc_reports/reports/registries.json

然后重新生成已更改的调色板，更新路由，编译 MCC，启动目标版本的本地服务器，并在认为工作完成之前运行实时验证。

为工作流本身编写或更新文档

使用技能：

• 人性化
• “技能创建者”，如果你是在修改技能本身，而不仅仅是文档的话

典型流程：

1. 重新阅读相关的技能文件和仓库工具。
2. 更新指南，使书面流程与实际流程一致。
3. 翻译时需保持足够具体，以便其他贡献者无需猜测即可照做。
4. 当工作流本身发生变更时，请一并更新相关技能，而不要让文档落后于自动化流程。