feat: 回城护栏 + 原点自救 + 移动诊断,并留下 TODO 交接文档

先纠正上一轮的误判:那个「寻路恒定 47 节点」是机器人卡在百米深坑里造成的,
我把它归因成配置问题并反复触发 /u return 回城,把玩家手动摆好的位置又拉走了 —— 抱歉。

回城护栏(破坏性操作不再自动执行)
- returnOnTimeout 默认关闭;即便打开,returnGraceSeconds(默认 300 秒)内也不执行,
  避免把玩家刚在客户端摆好的位置清掉
- returnCommand 可配置(默认 u return);每次回城都明确记日志说明会丢失当前位置
- 因未启用而跳过时也记一条说明,避免用户以为「怎么不回城了」

区分「被传送到原点」的两种原因(以前日志里长得一样,常被误判成机器人坏了)
- 脚下是 bedrock -> 在登录服,必须人工输入验证码,给出明确提示
- 脚下不是基岩 -> 死亡后被卡住,自动左右移动触发服务器重新传送

新增两个诊断字段(排查「走不动」的关键手段)
- moveDiag:当前按下的控制键、速度、寻路器 isMoving/goal/剩余路径点数。
  能一刀切开「寻路器没执行」与「执行了但服务端不认」
- pathingDiag:起点可走邻居数、寻路器能否读到方块、四向可见距离

_isStandingOnGround() 增加「服务端是否正把我们按在原地」的判断

排查结论(详见 TODO.md)
- 排除:GrimCompat 朝向限速(A/B 实测关闭后回弹 6.0 -> 5.5 次/秒,无变化)
- 排除:疾跑(关闭后仍 4.8 次/秒)
- 排除:世界数据错误(实测脚下 stone)
- 关键线索:寻路时 forward/sprint 确实按下、isMoving=true,但水平速度恒为 0
  (velocity.y=-0.078 恰是自由落体第一 tick 的值,说明速度每 tick 被清零),
  且 bot.entity.onGround 被服务端位置包反复置为 false,物理引擎一直按空中处理。
  下一步应从「让 entity.onGround 与出站包一致」入手。

TODO.md 面向下一位开发者:包含项目现状与部署、完整证据链、按优先级排好的假设与
验证命令、备选方案(绕开 pathfinder 自己写转向控制器)、以及其它待办。

测试 360 -> 363,全部通过。
这个提交包含在:
lyizai
2026-09-28 20:21:41 +08:00
父节点 0783249d1e
当前提交 9ca80d2f6e
共修改 7 个文件,包含 585 行新增和 10 行删除
+18
查看文件
@@ -65,6 +65,19 @@ function defaultConfig() {
retries: 2,
/** 连续寻路超时累计达到该秒数后,发送回城指令并重新开始 */
returnThresholdSeconds: 60,
/**
* 是否允许「连续超时后自动回城」。
*
* **默认关闭**,因为回城是破坏性的:它会把机器人从当前位置传送回安全点,
* 而这个安全点往往并不比原地更好(可能同样是卡死点),
* 更麻烦的是**会把玩家在游戏客户端里手动摆好的位置一并清掉**。
* 需要用它来逃离卡死状态时再打开。
*/
returnOnTimeout: false,
/** 回城指令(不带前导斜杠),默认服务器自带的 `/u return` */
returnCommand: 'u return',
/** 建立连接后多久内不自动回城(秒):刚被玩家摆好位置的机器人不该被立刻拉走 */
returnGraceSeconds: 300,
/** 发送回城指令后等待传送完成的时间(秒) */
returnWaitSeconds: 12,
/** 单个目标最多触发「往边上走两步」自救的轮数 */
@@ -382,6 +395,11 @@ function validateConfig(config) {
config.waitTimeoutSeconds = clampInt(config.waitTimeoutSeconds, 5, 3600, 60);
config.retries = clampInt(config.retries, 1, 20, 2);
config.returnThresholdSeconds = clampInt(config.returnThresholdSeconds, 0, 3600, 60);
config.returnOnTimeout = config.returnOnTimeout === true;
if (typeof config.returnCommand !== 'string') config.returnCommand = 'u return';
// 去掉玩家可能顺手写上的前导斜杠,发送时会统一补
config.returnCommand = config.returnCommand.trim().replace(/^\/+/, '');
config.returnGraceSeconds = clampInt(config.returnGraceSeconds, 0, 3600, 300);
config.returnWaitSeconds = clampInt(config.returnWaitSeconds, 1, 120, 12);
config.sideStepMaxRounds = clampInt(config.sideStepMaxRounds, 0, 10, 3);
config.claimStartHour = clampInt(config.claimStartHour, 0, 23, 11);