# TODO：留给后续开发者的待办与已知问题

> 本文档记录**尚未解决的大工程**、已经排查过的线索、以及推荐的验证方法。
> 小事已在代码里做完并提交，这里只写需要集中攻关的部分。
>
> 最后更新：2026-09-29

---

## 0. 先读这里：项目现状与部署

| 项 | 值 |
| --- | --- |
| 技术栈 | Node.js ≥ 22 + mineflayer 4.39.0 + mineflayer-pathfinder 2.4.5 |
| 测试 | `npm test`（436 个用例全绿） |
| 语法与前端 id 自检 | `npm run check` |
| 本地启动 | `npm start`（控制台 http://127.0.0.1:3080/） |
| 服务器 | `root@103.236.99.177:33851`，部署目录 `/opt/autostore-bot` |
| 控制台 | http://103.236.99.177:78/ ，密码在服务器 `.env` 的 `WEB_PASSWORD` |
| 进程管理 | pm2 应用 `autostore-bot`（端口 78）；旧版 Fabric 机器人为 `minecraft-bot`（端口 91，已停） |
| 私有 Node | `/opt/autostore-bot/runtime/current/bin/node`（v24.16.0） |

**旧版 Fabric 模组源码**（重要参考，实机可用的实现）：
`C:\Users\luoyi\AppData\Local\Temp\autostore-deploy\oldbot.js`（1356 行）。
它在这台服务器上是**真的能走路、能寻路、能扩地**的，所以遇到 mineflayer 行为诡异时，
第一件事应该是拿它的实现逐项对照，而不是自己猜。

> ⚠️ 上面的临时目录会被系统清理。若已丢失，它只作为历史参考 ——
> 不影响当前项目运行，但排查移动问题时很有价值，建议接手后先备份一份到仓库外。

> 📌 **本轮（1.7.0）已把本文档里的待办全部落地为代码** —— 详见 CHANGELOG 的 [1.7.0]。
> 下面每节都标注了「已实现 / 待实测」，未实测的部分需要部署到服务器后按验证方法确认。

---

## 0.1 🚀 部署方法（完整步骤）

### 方式一：一键部署（推荐）

```powershell
# 推荐：把 SSH_HOST / SSH_PORT / SSH_USER / SSH_PASS 写进 .env（已被 .gitignore 忽略），
# 然后直接跑 —— 命令行传密码会留在 shell 历史与进程列表里
npm run deploy
```

```bash
# 也可以临时用环境变量覆盖（.env 里的值仍作为兜底）
# Windows PowerShell
$env:SSH_HOST='103.236.99.177'; $env:SSH_PORT='33851'
$env:SSH_USER='root';          $env:SSH_PASS='<服务器密码>'
npm run deploy

# Linux / macOS
SSH_HOST=103.236.99.177 SSH_PORT=33851 SSH_USER=root SSH_PASS='<密码>' npm run deploy
```

`scripts/deploy.js` 会依次做：打包 → 上传 → 远程执行 `update.sh` →
轮询确认控制台返回 200。任一步失败都会明确报错。

可选环境变量：`DEPLOY_APP`（默认 `/opt/autostore-bot`）、`DEPLOY_PORT`（默认 `78`）。
`SSH_*` 与 `DEPLOY_*` **只在本机生效**，服务器上的 `.env` 不需要填。

### 方式二：手动部署

```bash
# 1. 打包（务必排除 data / .env / node_modules，否则会覆盖服务器上的真实数据）
tar -czf update.tar.gz \
  --exclude=node_modules --exclude=.git --exclude=data --exclude='*.log' --exclude=.env \
  -C . .

# 2. 上传
scp -P 33851 update.tar.gz root@103.236.99.177:/opt/autostore-bot/update.tar.gz

# 3. 远程应用（update.sh 会保留 .env / data / node_modules / runtime）
ssh -p 33851 root@103.236.99.177 'bash /opt/autostore-bot/update.sh'
```

### 辅助脚本

| 脚本 | 用途 |
| --- | --- |
| `scripts/deploy.js` | 一键部署（推荐） |
| `scripts/ssh-helper.js` | 单条远程命令 / 上传：`node scripts/ssh-helper.js exec "<命令>"`、`... put <本地> <远程>` |

Windows 自带 OpenSSH 但**没有 sshpass / plink**，无法非交互传密码，
所以这两个脚本用 `ssh2` 直接实现协议层（`ssh2` 是 devDependencies，
未安装时脚本会提示 `npm install --save-dev ssh2` 而不是裸崩）。

**凭据一律走环境变量，脚本里不写死任何密码。**

### update.sh 做了什么

`/opt/autostore-bot/update.sh` 的行为：
1. 解压 `update.tar.gz` 到 `/opt/autostore-bot`（**保留** `.env`、`data/`、`node_modules/`、`runtime/`）
2. 用私有 Node 重新安装/校验依赖
3. `pm2 restart autostore-bot --update-env`
4. 打印进程状态与端口监听情况

### 常用运维命令

```bash
# 进程状态
pm2 status
pm2 list

# 重启 / 停止
pm2 restart autostore-bot --update-env
pm2 stop autostore-bot

# 日志（实时）
tail -f /opt/autostore-bot/data/pm2-out.log     # 运行日志
tail -f /opt/autostore-bot/data/pm2-error.log   # 告警与错误
pm2 logs autostore-bot

# 端口
ss -lntp | grep ':78 '

# 回滚：把上一份备份目录改回来（update.sh 会先备份旧版本目录）
ls -1d /opt/autostore-bot/backup-* 2>/dev/null | tail -3
```

### 服务器上的关键文件

| 路径 | 说明 |
| --- | --- |
| `/opt/autostore-bot/.env` | **真实凭据**（`MC_USERNAME`、`MC_PASSWORD`、`WEB_PASSWORD`、`SIMP_API_KEY`、`SIMP_API_V2_KEY`、可选 `NOTIFY_WEBHOOK_URL`），权限 0600，**绝不进仓库** |
| `/opt/autostore-bot/data/autostore.json` | 运行时配置（控制台保存的），会被 `update.sh` 保留 |
| `/opt/autostore-bot/data/bots.json` | 机器人非敏感设置 |
| `/opt/autostore-bot/data/bots.credentials.json` | 界面添加的账号密码，权限 0600 |
| `/opt/autostore-bot/data/chat/<玩家名>.jsonl` | 公屏完整日志 |
| `/opt/autostore-bot/data/expansion-log.jsonl` | 开拓日志 |
| `/opt/autostore-bot/data/mapcache/` | 大地图瓦片缓存 |
| `/opt/autostore-bot/ecosystem.config.js` | pm2 配置 |
| `/opt/autostore-bot/runtime/current` | 私有 Node（服务器自带 Node 太旧时用） |

### 新增环境变量时

1. 在 `.env` 里加真实值（**只在服务器上加，不要提交**）；
2. 在 `.env.example` 里加**占位符**（如 `<your-xxx-key>`），绝不含真实密钥；
3. 确认 `.gitignore` 已包含 `.env`（本项目已含，并有 `!.env.example` 例外）。

---

## 1. 🟢 「机器人走不动」：**已解决**（根因是自定义高度偏好，见下）

### 🚧 2026-10-01 当前进展与剩下的拦路虎

修复高度偏好后，机器人确实能朝目标走了（实测 20 分钟前进 95 格），
但要真正开垦出第一块地，还要跨过这几关：

**① 几何约束：目标天然就在 ~770 格外。**
规划器 `generateHolePriority` 是**按到玩家的曼哈顿距离排序**取最近的合法候选
（`expansionPlanner.js:109-130`），而机器人出生在**王城**——它在「养老院」这个
**33037 区块（约 180×180 区块）** 的大邦国正中间。实测最近的候选在 53 区块
（≈768 格）外，且 `targetCount: 1` 只返回一个候选。**所以长途跋涉是邦国几何决定的，绕不开。**

**② 服务器会踢它，三种原因都实测到过：**
- `You were kicked from main: An internal error occurred in your connection.`（最常见，约 1~6 分钟一次）
- `You were kicked from main: You are sending too many packets!`
- `You were kicked from main: Flying is not enabled on this server`
- 未完成验证时还有 `验证超时！您需要在 120 秒内完成身份验证`（120 秒内要人工发码）

实测出站包速率 **57.9 个/秒**，其中 `pong` 30.6（服务端在疯狂 ping）、
协议补包（`player_input` + `tick_end`）合计 23.9、位置包 1.35。
**注意：协议补包当初的立论依据（「走不动」的根因）已经被证伪**（真因是高度偏好），
它们是否仍然必要、是否就是「发包太多」的原因，**尚未验证**——这是下一步要测的。

**③ 半路会死**：实测死因是 `fell from a high place` 与 `was slain by Zombie`。
摔死那次白走了 100 多格。
- 摔死已处理：服务器配置里 `pathing.maxDropDown` 被改成了 **64**（钳制上限），
  而原版摔落伤害超过 3 格后每格 1 点、**23 格必死**。已改回 4（代码默认本来就是 3）。
- 被僵尸杀还没处理：`autoAttack` 是开的，但夜里野外仍会被围死。

**④ 推进速度只有物理速度的 1/5**：实测机器人几乎每 tick 都按着 `forward+sprint`、
`velocity` 约 0.2~3 格/秒，但 2 秒粒度的**净位移只有 0.405 格/秒**
（48.6 格 / 120 秒）——差额是被服务端拉回的部分。为此已补上
`flags.hasHorizontalCollision`（mineflayer 恒写 `undefined`，见 [1.10.0]），
实测该标志确实一直在被漏报（补写计数很快涨到 1 万+），但**提速效果尚未量化验证**。

**⑤ 会卡在崎岖地形前「原地起跳」** —— ✅ **已定位并修复（[1.11.0]）**。

真正的根因不是地形，是**朝向**：`bot.entity.yaw` 无界增长（mineflayer 收到 `position` 包时
直接赋值、不取模，GrimCompat 又在它基础上累加），实测涨到 **19254°（≈336 弧度）**。
抓包证据：

```
yaw°:  -1373 → 19254 → -1650 → -1407 → -1373 → 19254 → …     相邻两包折合差约 114°
坐标:  (6756.57, 11953.6) ⇄ (6757.45, 11953.8)                 0.9 格内「橡皮筋」
```

机器人一直按着前进键，但朝向每隔几个 tick 就被甩到另一个方向，于是**原地走之字形、
净位移恒为 0**。物理录制里的 `jump 74/240`、`水平碰撞 195/240`、`onGround 79/240`
都是这个 bug 的表象。
修复后实测朝向变成**平滑转向**（`0, -9, -17, -26, -34, -43 …`），速度从 0.35 提到 0.56 格/秒。

**⑥ 剩下的拦路虎：服务端在把它「钉」在固定坐标上。**
修复 yaw 之后，手动移动测试报告位移 **2.40~4.81 格**（说明客户端确实走了），
但一查状态，位置又回到同一个点（`6756.57` / `6750.3`）。`被服务器传送另有`
持续在 **16~194 次/30 秒**。也就是说**客户端走、服务端拉回**，净位移为 0 ——
这一层已经不在代码控制范围内，需要确认服务器侧的原因。

**⑦ 服务端提示过「邦国已激活科技: 疆土开拓者 I 剩余时间: 0时13分3秒」**
—— 开拓可能需要该邦国科技处于激活状态，且**有时间限制**。
这可能是「到了目标区块也未必能开垦成功」的一个前提条件，尚未验证。

### ✅ 2026-10-01 突破：修掉高度偏好后扩地真的跑起来了

**根因**：`AltitudeGoal` 把高度偏置加在**启发值**上
（`heuristic = max(0, 基础距离 - 权重 × y)`），而 `mineflayer-pathfinder`
每次 `compute()` 返回 `partial` 时用 **`h` 最小**的节点当 partial 路径的终点
（`astar.js`: `if (neighborNode.h < this.bestNode.h) this.bestNode = neighborNode`）。
于是「又高又偏」的节点 `h` 反而更小，partial 路径被引向高处而不是目标附近 ——
**A\* 一直在算、永不收敛，机器人一次移动指令都发不出来。**

**生产对照实测**（王城平台上，其余配置完全相同）：

| `altitudePreference` | `inputTicks` | 结果 |
| --- | --- | --- |
| `true`（修复前） | **0** | 永远停在「寻路超时，重新寻路」，一步不动 |
| `false`（修复后） | **237** | 每 tick 都在走，`blockedTicks = 0`、`frozenTicks = 0` |

已把默认值改为 `false`（[1.9.1]），并在 `AltitudeGoal` 的注释里写清推导与实测数据。
**想重新启用，必须把偏置改成「低处加移动代价」**（改 `getNeighbors` 的 `cost`），
不能改启发值。

**顺带修掉的第二个拦路虎**（[1.9.3]）：服务器每 1~6 分钟把机器人踢下线一次
（`An internal error occurred in your connection`），原来一掉线任务就永久停住。
现在 `autoResumeAfterReconnect`（默认开）会在世界退出时记下配置、重连后自动接上；
手动停止 / 时段外 / 耐久保护停机不会被误恢复。

**实测结果**（修复后连续 20 分钟）：

```
起点 6753.6, 143, 11953.7   距目标 763 格
终点 6768.5, 116, 12045.7   距目标 668 格      ← 前进 95 格，全程未掉线
```

「原点自救」表现完美（4/4 成功）：每次被踢到登录服大厅都能自己回到真实世界。

**仍需观察**：推进速度约 5 格/分钟（正常步行 4.3 格/秒），
因为每段路径都会走到「寻路重试耗尽 → 往边上走两步 → 跳过目标 → 重新规划同一目标」
的循环里。待优化项：`waitTimeoutSeconds`（60）偏长、以及「跳过目标后立刻重选同一个目标」。

### 历史记录：三种「走不动」的区分（结论仍然有效）

### 🔴 2026-10-01 实测：三种「走不动」要分开看（**先读这段**）

用新增的**物理 tick 录制**（`POST/GET /api/bots/:id/physics`，见 CHANGELOG [1.9.0]）
逐 tick 抓了「输入 → 输出」，把三种完全不同的现象区分开了：

| 场景 | 物理有没有动 | 服务端在干什么 | 结论 |
| --- | --- | --- | --- |
| **登录服大厅** | ✅ 每 tick 走 0.116 格（正常速度） | 每 2 tick 推回一次（`被服务器传送另有` 240~260 次/30 秒） | **真回弹**，但这是未完成验证的惩罚，不是 bug |
| **真实世界、建筑内** | ✅ 加速到 0.21 格/tick（≈4.3 格/秒，正常步行） | 入站位置包 **0~1 个**，没插手 | **撞墙**：`collidedHorizontally=true`，`blockedTicks` 42~59/60 |
| **真实世界、卡在低处** | ❌ **一次都没动** | — | **寻路器 60 秒规划超时**，`inputTicks=0`，从未产生可执行路径 |

**关键结论：物理引擎、协议补包、Grim 合规层全都正常**（能加速到正常步行速度），
`frozenTicks` 在所有场景都是 0 —— 「输入没进物理」这种情况从未出现。
`searchRadius` 从 -1 改成 128 对结果**没有影响**，所以也不是搜索空间无界导致的。

**当前扩地的真正拦路虎（按优先级）：**

1. **机器人被地形困在王城建筑里**：实测 `exits` 四向只有西面可走，东面头顶是 **torch**（火把）
   —— 它被 `/u return` 传送进建筑后就出不来了。而此时 `mineflayer-pathfinder`
   的「徒劳检测」会把每一段路径都清掉（见下），于是永远在「规划 → 卡住 → 清空 → 规划」里循环：
   `blockedTicks` 230/237、净位移 ~0。
2. **装备耐久**：`lastReturn.reason = "装备耐久过低（主手 剩余耐久 15% ≤ 15%）"`
   → 一启动扩地就 `/u return` 回城并停机，`inputTicks=0`。**需要人工修装备**。
3. **⚠️ `/u return` 会造成摔落伤害**：实测 `health 3.79 → 1.24`、`7.8 → 5.6`，
   更早一次直接 `fell from a high place` 摔死。回城前应确认落点高度；
   而且它把机器人送进建筑内部（见第 1 条），等于「回城即被困」。

### 🎯 死循环的确切机制（2026-10-01，读 mineflayer-pathfinder 源码定位）

`mineflayer-pathfinder/index.js` 末尾的「徒劳检测」：

```js
// check for futility
if (performance.now() - lastNodeTime > 3500) {
  resetPath('stuck')   // 3.5 秒内到不了下一个路径点 → 清空路径
}
```

机器人被墙挡住时，3.5 秒必然到不了下一个路径点 → `resetPath('stuck')` → 重新规划 →
又卡住 → 又清空。**每 3.5 秒一个循环**，日志表现为 `寻路事件：路径已生成（代价 63.07）`
每 3 秒重复一次；`resetPath` 每次都会补一对 `diggingAborted`/`diggingCompleted` 监听器，
所以日志里还会出现 `MaxListenersExceededWarning: 11 diggingAborted listeners`
—— **这条警告就是「路径被反复清空」的可靠信号**。

另外两个也会清空路径的触发点（排查时注意）：
- `blockUpdate`：路径附近的方块一变就 `resetPath('block_updated')`；
- `chunkColumnLoad`：新加载的区块与已访问区块相邻就 `resetPath('chunk_loaded')`
  —— 服务器频繁传送机器人时，这个会被反复触发，A* 的 20 秒 `thinkTimeout`
  因为每次都新建 AStar 而**永远不会到期**。

**结论：只要机器人被墙挡住，它就会无限循环「规划 → 卡住 → 清空」，
既不会放弃目标也不会自己脱困。** 需要先把它挪到开阔地；长期看应处理
`path_reset('stuck')` 的累计次数（连续 N 次就判定「此处出不去」并上报 / 换目标）。

### ⚠️ 线上实测补充（2026-09-29，**它推翻了下面原有的框架**）

用新增的**出站包抓取**（`POST/GET /api/bots/:id/capture`，见 CHANGELOG [1.8.0]）做了对照，
结论是：**「走不动」不是服务端回弹造成的，是客户端物理引擎没有把按键积分成位移。**

手动按住一个方向键 3 秒的逐包实测（任务未启动、机器人空闲）：

| 项 | 实测 |
| --- | --- |
| 入站位置包（服务端回弹） | **0 个** —— 服务端全程没插手 |
| 出站位置包 | 5 个，全是 1 秒一次的空闲包（**不是**每 tick 一个） |
| 客户端自己的坐标 | **完全没变**（`6752.3000, 146, 11922.3000` → 一字不差） |
| 朝向 | 完全没变（`-0.20876`） |
| `moveDiag.velocity` | 恒为 `(0, -0.078, 0)`，`speed = 0.078` |
| `player_input` 位标志 | `backward: true` ✅ —— 控制键确实按下去了 |

四方向各按 3 秒的位移：`forward 0.02 / back 0.00 / left 1.22 / right 1.40`（正常应约 12 格）。

**推论：**

1. `player_input` 如实上报了输入、`bot.getControlState()` 也是 true，
   但 `prismarine-physics` 的 `applyHeading` 没有产生任何水平速度 ——
   要么物理引擎拿到的 `control` 快照里 `forward/back` 是 0，
   要么 `moveEntity` 把位移全吃掉了。**下一步要加 `physicsDiag` 直接看**：
   `bot.physicsEnabled`、每 tick 的 `physicsTick` 计数、simulate 前后 `onGround`、
   `world.getBlock(脚下)` 是否命中、以及 PlayerState 里读到的 `control` 快照。
2. **「服务端回弹」只在寻路任务运行时出现**（实测任务中入站 6/秒、出站 `position_look` 25/秒），
   手动移动时入站为 **0** —— 回弹是「任务驱动移动」的伴生现象，**不是走不动的原因**。
   这也解释了为什么下面两套针对回弹的修正（方案 A/B）开关对位移毫无影响
   （实测：修正开 0.4~6.4 格 / 修正关 0.4~2.4 格，同量级）。
3. 原先记的「手动按键移动完全正常（forward 2 秒 4~8 格）」**已不成立**，
   该基准需要重建 —— 基于它的推理（「规划问题 vs 协议问题」二分）也就全部偏了。

**顺带确认（1.21.4 协议）：**

- `flags.hasHorizontalCollision` 恒为 `null`（= 0）：mineflayer 在 `physics.js` 里
  把它写成 `undefined`，而原版客户端会在水平碰撞时置位；实测 62/62 个位置包都是 0。
- `teleport_confirm.teleportId` 是大负数（如 `-1884468723`）：该服务端用的是随机大整数，
  不是原版的自增小整数，属于它自己的实现，不是 bug，但排查时别按原版预期去读。
- 包类型分布对照（5 秒）：空闲 `player_input/tick_end/pong ≈ 100` 且 `position=5`；
  手动按键与空闲同构（**没有** `position_look`）；寻路中才有 `position_look=126`。

### 现象回顾（历史记录；其中「手动移动正常」已被上面的实测推翻）

- **手动按键移动完全正常**：通过控制台「移动测试」按 forward 2 秒，实测位移 4~8 格，位置保持。
- **寻路器驱动的移动被回弹**：一旦 `bot.pathfinder.setGoal()` 开始执行，
  服务端以 **5~9 次/秒** 的频率强制同步位置（`forcedMove`），机器人几乎原地不动。
- 偶尔能挪动一点，但速度只有 **0.3 格/秒**（正常步行 4.3 格/秒）。

### 已确认正常的部分（不要再怀疑这些）

| 项 | 状态 | 证据 |
| --- | --- | --- |
| `player_input` 补包 | ✅ 每 physicsTick 都发（~20/s），bitflags 正确 | `packetStats.playerInput` 持续增长 |
| `tick_end` 补包 | ✅ 每帧发送 | `grim.protocolPackets.tickEndSent` |
| `onGround` 标志（出站包） | ✅ 已按世界数据复核 | `packetStats.onGroundFixed` |
| 世界数据可读性 | ✅ `world.getBlock` 正常，四向可见 115~125 格 | `pathingDiag.visibleDistance` |
| 寻路器本身 | ✅ 在开阔地能找到路径 | 实测「已探索 3633 节点 → success，代价 113.8」 |
| 服务端回弹是否持续 | ❌ **只在机器人尝试移动时出现** | 12 秒采样：空闲 +0，寻路中 +105 |
| 关闭疾跑 | 试过，**无改善** | `allowSprint=false` 后仍是 4.8 次/秒回弹 |
| 关闭合规层（`grim.enabled=false`） | 试过，**无改善** | A/B 实测 6.0 vs 5.5 次/秒，位移都是 0 |
| 世界数据是否错误 | ❌ **不是原因** | 实测脚下 `stone`，`blockBelow` 正确 |

### 🎯 关键线索（未变）

用 `/api/status` 的 `moveDiag` 采集到的实测数据：

- 寻路时 `forward`/`sprint` 都按下、`isMoving=true`，但**水平速度恒为 0**；
- `velocity.y = -0.078` 恰是自由落体第一 tick 的重力值 —— 说明速度每 tick 被清零；
- `bot.entity.onGround` 被服务端位置包反复置为 false（mineflayer 的 `physics.js`
  在处理 `position` 包时无条件置 false），物理引擎因此一直走「空中」分支。

### ✅ 本轮已实现的代码（`1.7.0`）

| 手段 | 开关 | 位置 |
| --- | --- | --- |
| 方案 A：物理引擎 onGround 对齐 | `grim.syncGroundToPhysics`（默认开） | `botManager._installGroundStateFix` |
| 方案 B：例行同步不采纳 onGround=false | `grim.trustSetbackOnGround` + `grim.setbackSyncEpsilon`（默认 0.5 格） | 同上（`prependListener` 抢在 mineflayer 之前快照） |
| 出站包类型分布（假设 4 的对照依据） | 常开 | `packetStats.outboundTypes` |
| 备选执行器：只借 A* 算路径、自己按键执行 | `pathing.executor: 'manual'` | `src/bot/manualMover.js` |

**请按下面的顺序实测**：

1. 部署后先在控制台确认「Grim 合规」卡片里的 `地面修正` 一行出现非零计数
   （`物理对齐 N · 保住 M · 最近同步差 X 格`）；
2. 用「移动测试」确认手动移动仍然正常；
3. 开始扩地，观察 `moveDiag.speed` 是否 > 0.1、`moveDiag.onGround` 是否稳定为 true、
   「被服务器传送另有」的计数是否下降、以及是否真的能走完一段路；
4. 若仍有回弹 → 在配置「寻路 → 寻路执行器」切到 **手动执行（备选方案）**，
   再观察一次（它只借用 A* 规划，执行层完全是我们自己的按键时序）；
5. 若两者都不行 → 回到下面「未完成的排查方向」，用 `packetStats.outboundTypes` +
   旧模组抓包做逐项 diff（假设 5）。

### 未完成的排查方向（按优先级）

#### 假设 3：跳跃 / 跑酷的物理预测不匹配

Grim 的 Prediction 检查对**跳跃**最严格（起跳时机、跳跃高度、疾跑跳加成）。
mineflayer 的 `physics.js` 在这些细节上与原版有已知偏差。

**验证方法**：把路径限制成纯平地，禁用一切跳跃：

```json
{"allowSprint": false, "pathing": {"allowParkour": false, "allow1by1towers": false, "maxDropDown": 1}}
```

若回弹消失 → 需要在 `GrimCompat` 里拦下 `jump` 控制状态，改用更保守的移动策略。

#### 假设 5：直接抓包对照（最彻底）

用 `scripts/check-protocol.js` 的思路扩展一个抓包脚本，
分别在「旧模组移动」和「mineflayer 寻路移动」时记录 5 秒的**完整出站包序列**，diff 出差异。
`packetStats.outboundTypes` 已经给出包类型分布作为起点。

> 提示：`scripts/check-protocol.js` 里读取 `node_modules` 的路径用了
> `path.join(__dirname, 'node_modules', ...)`，在 `scripts/` 下是拿不到的 ——
> 顺手修一下（应为 `path.join(__dirname, '..', 'node_modules', ...)`）。

---

## 2. ✅ 原点自救（已实现判定与统计，实测成功率待观察）

服务器把玩家丢到世界原点附近有两种完全不同的原因，**以前在日志里长得一样**：

| 原因 | 判断依据 | 处理方式 | 现状 |
| --- | --- | --- | --- |
| 死亡后被卡住 | **服务器没有要求验证码** | 左右 / 前后移动即可触发服务器重新传送 | ✅ 两轮自救 + 成败判定 |
| 被切到登录服 | **服务器要求输入验证码** | **必须重新输入验证码**，只能人工完成 | ✅ 已识别并提示，支持 Webhook 提醒 |

> ⚠️ **不要用「脚下是不是基岩」来区分这两种情况 —— 实测两种情况下脚下都是基岩。**
> 唯一可靠的信号是**服务器有没有发「请直接输入验证码进行验证」这类提示**。

**本轮改进**：分两轮（左右 → 前后 + 跳），每轮结束后等 800ms 让传送落地再判定「位置是否恢复」；
统计 `attempts / successes / lastResult`（`/api/status` 与控制台「连接」卡片可见）；
两轮都失败时升级为明确提示，并支持 Webhook 提醒。
**待观察**：线上实际成功率（看 `originRescue.successes / attempts`），
若长期为 0，说明该服务器对移动输入不再响应，应把重心放在验证码流程上。

---

## 3. ✅ 自动回城（已加「原地是否更差」评估与前后坐标）

回城是**破坏性**操作：它把机器人拉回安全点，会**清掉玩家在游戏客户端里手动摆好的位置**。

现状（1.7.0 之后）：

- `returnOnTimeout` **默认关闭**；即便打开，`returnGraceSeconds`（默认 300 秒）内不执行；
- **回城前先评估**：`pathing.diagnostics().neighborCount` 为 0（确实无路可走）才回城，
  否则记为「原地还能走」并跳过目标 —— 回城只会白白丢掉位置；
- **回城后会记录前后坐标与直线距离**，日志写「回城结果：机器人从 (A) 挪到了 (B)（直线 X 格）」，
  控制台「任务」卡片显示 `最近回城`；位置几乎没变时明确提示回城没有帮助。

---

## 4. ✅ 其它已知问题（本轮都已落地）

### 4.1 大地图 ✅

- 层级 1~3 现在有**后台预热**：机器人移动超过 `bigMap.prewarmMinMoveBlocks`（默认 512 格）
  或距上次超过 `prewarmIntervalMs`（默认 10 分钟）时，用一半并发把周边瓦片补下来；
- 领土多边形按**视野裁剪**绘制，全世界视角不再全量绘制。

### 4.2 控制台 ✅

- 日志改为**按帧批量写入**（一次布局、一次滚动），并用 `content-visibility: auto`
  让浏览器跳过视口外行的渲染（等价于浏览器自带的虚拟列表，不改变内容与滚动位置）；
- 配置面板新增**搜索框**：按名称 / 字段名 / 说明过滤，隐藏不删除（保存时仍能读到隐藏字段的值）。

### 4.3 多机器人 ✅

- 新增**目标区块租约表**（`src/core/targetLease.js`）：谁先抢到谁去，其余机器人跳过；
- 持有者每个 tick 续租；停止任务 / 完成任务时归还；掉线 / 卡死后租约到期自动失效；
- 候选区块全被其他机器人预定时，等 15 秒再规划（而不是提前判「没有可用区块」）。
- **待观察**：多机器人同时扩地的实际撞车率（日志里出现「已被其他机器人预定，跳过」的次数）。

### 4.4 定时消息 ✅

- 支持 **cron 表达式**（5 段，本地时间，含步长 / 区间 / 列表 / 星期范围）；
  非法表达式不会被静默吞掉，列表里会显示原因并按间隔发送；
- 支持**发送结果确认**：填「期望回复」（正则）后，命中回复记「已确认」，
  超时记「未确认」并写警告 —— 不再只靠人翻日志判断 `/u restore confirm` 是否生效。

### 4.5 登录验证 ✅

- 验证码仍只能人工输入（服务器设计如此），但等待验证码与原点自救失败时会通过
  **Webhook 通知**（默认按飞书 / Lark 自定义机器人的文本格式）提醒，避免错过 120 秒时限；
- 配置位置：控制台「服务器 → 通知提醒（Webhook）」，或环境变量 `NOTIFY_WEBHOOK_URL`。

---

## 5. 常用排查命令

```bash
# 机器人完整状态（含寻路诊断 / 地面修正计数 / 自查统计）
curl -s -H "X-Auth-Token: $PW" http://103.236.99.177:78/api/status | jq '.data.bots[0]'

# 寻路诊断：邻居数、世界可读性、四向可见距离、当前执行器
curl -s -H "X-Auth-Token: $PW" http://103.236.99.177:78/api/status | jq '.data.bots[0].pathingDiag'

# 地面状态修正与出站包类型分布
curl -s -H "X-Auth-Token: $PW" http://103.236.99.177:78/api/status | jq '.data.bots[0].packetStats'

# 原点自救成功率 / 最近回城
curl -s -H "X-Auth-Token: $PW" http://103.236.99.177:78/api/status | jq '.data.bots[0].originRescue'
curl -s -H "X-Auth-Token: $PW" http://103.236.99.177:78/api/status | jq '.data.bots[0].task.lastReturn'

# 实时日志
tail -f /opt/autostore-bot/data/pm2-out.log
tail -f /opt/autostore-bot/data/pm2-error.log

# 公屏完整日志（含服务器消息，JSONL）
tail -f /opt/autostore-bot/data/chat/<玩家名>.jsonl

# 寻路状态（判断「探索了多少节点」是定位卡死的关键指标）
grep '寻路状态' /opt/autostore-bot/data/pm2-out.log | tail -20

# 被服务器回弹的频率（>100/30秒 说明移动被反作弊拒绝）
grep '被服务器传送另有' /opt/autostore-bot/data/pm2-error.log | tail -5

# 多机器人协调：谁在占哪块（日志）
grep '已被其他机器人预定' /opt/autostore-bot/data/pm2-out.log | tail -10

# 抓出站包（诊断「走不动」的主力工具，见问题 1 · 假设 5）：
# 先在「能走」时抓 5 秒，再在「走不动」时抓 5 秒，然后逐包 diff
BOT=<机器人id>
curl -s -X POST -H "X-Auth-Token: $PW" -H 'Content-Type: application/json' \
  -d '{"seconds":5}' http://103.236.99.177:78/api/bots/$BOT/capture/start
# 取包类型分布（先看「发了哪几种、各多少次」）
curl -s -H "X-Auth-Token: $PW" http://103.236.99.177:78/api/bots/$BOT/capture | jq '.data.byType'
# 只取移动相关的原始包内容（看 onGround / hasHorizontalCollision / player_input 位标志 / teleportId）
curl -s -H "X-Auth-Token: $PW" \
  'http://103.236.99.177:78/api/bots/$BOT/capture?types=position_look,look,position,flying,player_input,teleport_confirm&limit=60' \
  | jq '.data.packets'
# 手动停止（给 seconds 时可省略）
curl -s -X POST -H "X-Auth-Token: $PW" http://103.236.99.177:78/api/bots/$BOT/capture/stop

# 协议字段定义自检（核对 mineflayer 写出的字段名与 1.21.4 是否一致）
node scripts/check-protocol.js

# 录物理 tick（诊断「走不动」的另一半：抓包看「发了什么」，这里看「物理读到了什么、动没动」）
# 一边录一边按方向键，然后看三个计数：
#   inputTicks>0 且 inputMovedTicks=0 且 frozenTicks>0  → 输入根本没进物理
#   inputTicks>0 且 inputMovedTicks=0 且 blockedTicks>0 → 被方块挡住（地形）
#   inputMovedTicks>0 但服务端把位置拉回            → 才是服务端回弹
curl -s -X POST -H "X-Auth-Token: $PW" -H 'Content-Type: application/json' \
  -d '{"seconds":10}' http://103.236.99.177:78/api/bots/$BOT/physics/start
curl -s -X POST -H "X-Auth-Token: $PW" -H 'Content-Type: application/json' \
  -d '{"direction":"forward","seconds":3}' http://103.236.99.177:78/api/bots/$BOT/move
curl -s -H "X-Auth-Token: $PW" http://103.236.99.177:78/api/bots/$BOT/physics \
  | jq '.data | {inputTicks, inputMovedTicks, blockedTicks, frozenTicks, movedTicks, maxHorizDelta, last}'
# 逐 tick 明细（看速度、onGround、碰撞、脚下方块）
curl -s -H "X-Auth-Token: $PW" 'http://103.236.99.177:78/api/bots/$BOT/physics?limit=40' \
  | jq '.data.ticks[] | {t, dx, dz, vx, vz, onGround, collidedHorizontally, blockBelow, control}'
```

### 判断「机器人是不是卡在登录服」

```bash
curl -s -H "X-Auth-Token: $PW" http://103.236.99.177:78/api/status \
  | jq '.data.bots[0] | {position, chunk, needsVerification}'
```
- `needsVerification == true` → 服务器正在等待验证码，控制台会显示醒目提示（**这是可靠信号**）
- 位置靠近原点且 `needsVerification == false` → 多半是死亡后卡住，机器人会自动自救（并记录成败）
- ⚠️ `world.blockBelow == "bedrock"` **不能**用来判断 —— 实测两种情况脚下都是基岩

---

## 6. 代码约定（改动前请遵守）

- 提交信息用约定式提交（`feat:` / `fix:` / `docs:` / `refactor:` / `test:` / `chore:`），主题行说清做了什么。
- **所有密钥只走 `.env`**（已在 `.gitignore` 里），代码里绝不硬编码；
  新增配置项要同时更新 `.env.example` 的占位符。
- 注释与文档用中文，解释「为什么」而不是「做了什么」。
- 每个 `fix` 都应补一个能复现原问题的测试；本项目测试在 `test/`，用 `node:test`。
- 改前端记得跑 `npm run check`，它会校验 `app.js` 引用的元素 id 在 `index.html` 里都存在。
- ⚠️ 写块注释时注意：**中文解释里不要出现 `*/` 这两个字符**（例如 cron 步长写法），
  它会提前结束注释并导致语法错误（本项目已踩过一次）。