Developer Guide

开发指南 · Developer Guide

面向想阅读、修改、扩展 AIBot 的开发者。先读 Architecture 建立全局认知。

构建与运行

./gradlew clean build   # 全量构建(提 PR 前请确保通过)
./gradlew runServer     # 开发服务端
./gradlew runClient     # 开发客户端

版本兼容(重要)

本项目锁定 Yarn 1.21.3+build.2。Minecraft / Fabric API 跨版本方法签名常变——在改动以下内容前,务必先确认当前版本的方法签名:

• 物品组件(Components)
• 进食 / 食物属性
• 燃料注册
• 挖掘速度
• 熔炉库存
• 客户端网络代码

内置验证工具

AIBot 自带两个诊断命令,支撑"改动 → 验证 → 回归":

命令	用途
/aibot verify <bot> <feature>	跑内置验证场景(导航绕障 / 缺口 / 下挖 / 挖矿 / 战斗 等),观察真实行为
/aibot deplint <bot> <spec>	离线审计某目标的规划链(只看 GoalPlanner 倒推结果,不实际执行)

配合结构化日志 / replay / profile:

/aibot observe tps
/aibot observe profile <bot>
/aibot observe replay …

扩展:加一个新任务

1. 继承 AbstractTask,实现 onStart / onTick / onAbort。
2. 遵守 Task System:G1 内部不 assign 子任务(调用 BlockMiner / DigNav / ActionPack 等共享原语);G2 只在主线程操作世界。
3. 站桩类任务重写 isWaiting() 返回 true,并自带 NO_PROGRESS / timeout 看门狗。
4. 用 complete() / fail(reason) 收尾,失败原因要清晰(便于 GoalExecutor 重规划与日志诊断)。

扩展:加一个新工具

1. 在 ToolRegistry 用 register("tool_name", 描述, schema, [Group], handler) 注册。
2. 选择合适的 Group(低层 / 记忆 / 协调,或默认高层),受 brain 配置开关影响(见 Configuration)。
3. handler 里把参数落成一个 Task System 或 Goal Engine,而不是直接操作世界——保持 LLM plans, Tasks execute。

扩展:加一个新目标

1. 在 Goal 密封类型里新增一种目标。
2. 在 GoalPlanner 的 ensureItem / 规划分支里补上"如何倒推获得"的逻辑。
3. 用 /aibot deplint 离线验证倒推链是否正确,再下场实测。

代码地图

brain/        大脑:LLM 请求、ToolRegistry、ActionDispatcher
goal/         目标:Goal、GoalPlanner、GoalExecutor
task/         任务状态机 + 协调器 + 看门狗
action/       低层动作原语
pathfinding/  A* 寻路与可站性
craft/ mining/ 配方与矿物知识
entity/       AIPlayerEntity
command/      /aibot 命令
network/ persist/ memory/ observe/ log/ mixin/   基础设施

详见 Architecture。欢迎提 Issue / PR 🙌