BotStore/TODO.md

# 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-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
```

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

```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 步长写法），
  它会提前结束注释并导致语法错误（本项目已踩过一次）。