cortico 0.1.0

package/src/worlds/minecraft/README.md

@@ -0,0 +1,917 @@
+<!-- Owner: src/worlds/minecraft/definition.ts -->
+
+# worlds/minecraft
+
+实时游戏 World：以 mineflayer 玩家客户端连原版服务器，把"游戏状态 → 文字观察"
+与"高层意图 → 游戏操作"接通。
+
+## 结构
+
+```
+world.ts        World:事件面、工具面、console 自报、世界变化节流、摄像机编排
+bridge.ts        mineflayer 连接/断线重连/prismarine-viewer 拉起
+mineflayer-fixes.ts  把 mineflayer 里靠客户端预测的合成与放置换成等服务端回话的版本
+world.ts         纯逻辑:世界快照 → 文本渲染、变化检测(可直接单测)
+server-config.ts server.properties 与 ops.json 读写 + 存档目录枚举(存档与玩法/权限与作弊面板)
+executor.ts      异步执行器:任务队列 + 技能实现 + 自保反射(不经 LLM)
+skills.ts        技能注册表:SkillCall/parseSteps/SKILL_DOC/schema 全部由一份声明生成
+check.ts         mc_check 的断言器:受理 → 对世界求值 → 只报差异的回执(纯函数)
+client.ts        观察者客户端进程:拉起、等窗口、收干净
+window.ts        客户端那扇窗:按进程号探测有没有出来、改标题(+ client-window.ps1)
+client-launch.ts 纯计算:.minecraft 安装 → java 命令行(认 inheritsFrom)
+client-skins.ts  皮肤:选中的那张留底,启动前按账号名铺进游戏目录
+server.ts     控制台一键启停:本地 MC 服务器(java -jar server.jar)
+log.ts           World 日志转发与面板环形缓冲
+  (Minecraft 客户端、服务端与启动器放在仓库外,不进 Git)
+```
+
+客户端与服务端的固定来源在控制台对应面板上给出，本仓库不含它们；这些路径没有
+默认值，配置留空即未配置。
+
+## 版本约定:1.20.6 + Java 21
+
+全链路钉在 **1.20.6**（`worlds.minecraft.version` 默认值）：服务器（Paper）、观察者
+客户端（Fabric）、mineflayer 协议。选它的原因是 SpectatorPlus——观察者附身时
+原版客户端把整个 HUD 都藏掉（wiki 载明的客户端行为，服务器改不了），这个 World
+把被附身者的道具栏/手持/生命/经验**连同第一人称手臂与挥击动画**一起补回来，
+其客户端侧支持的 1.20.x 最高版就是 1.20.6。完整道具栏需要服务端配合发数据，
+所以服务器用 Paper + 它的 paper 插件。
+
+本项目使用 Java 21 启动服务端与客户端。客户端日志中的
+`[LWJGL] [ThreadLocalUtil] Unsupported JNI version detected` 表示 LWJGL 未识别当前 JNI 版本；需核对启动所用的 JDK。
+
+装机清单（自己装，来源都是各自官方；本仓库不含也不代下这些文件）：
+- 服务器：`server.jar` = Paper 1.20.6，`plugins/spectatorplus-paper-1.2.0.jar`
+- 客户端：`versions/1.20.6` + `versions/fabric-loader-*-1.20.6`（配置
+  `client.versionId` 指后者）、`mods/fabric-api-*.jar` + `mods/spectatorplus-fabric-*.jar`
+  + `mods/CustomSkinLoader_Universal-*.jar`（皮肤；没有它「皮肤」面板照样能选，只是
+  客户端不会读）
+
+客户端和服务端安装在仓库外，分别配置 `serverDir` 与两份客户端的 `gameDir`。首次启动服务器需接受 EULA：运行一次 `server.jar` 后修改 `eula.txt`。
+
+## 画面:viewer 还是主视角
+
+观众看到的画面由 OBS 采集，两条来路任选一条：
+
+| | prismarine-viewer | 观察者客户端 |
+|---|---|---|
+| 是什么 | 独立的 WebGL 渲染器，网页 | 真 Minecraft 客户端，旁观模式跟着 bot |
+| 画质 | 没有光影/材质包/模组的画面 | 与观众同一幅画面，含 SpectatorPlus 补回的 HUD 与手臂 |
+| 代价 | 轻，无人值守 | 一份客户端进程 + 一块显卡 |
+
+客户端窗口出现后，World 将其标题设置为该客户端的账号名，供 OBS 按标题区分。直连进服后再次更新标题。
+
+`client-launch.ts` 读取 `versions/<id>/<id>.json` 生成 Java 命令行，支持 `inheritsFrom`。
+1.20+ 使用 `--quickPlayMultiplayer` 直连服务器，更早版本使用 `--server/--port`。
+离线账号 UUID 按 `OfflinePlayer:<账号名>` 的 MD5 生成。
+
+摄像机进服以 bot 的玩家列表为准。World 依次发送 `op`、`gamemode spectator`、
+`execute as <摄像机> run spectate`（脱离）与 `spectate <bot> <摄像机>`。
+托管服务器使用 stdin；外部服务器由 bot 发送聊天命令，需要相应 op 权限。
+SpectatorPlus 在开始旁观时发送道具栏全量快照，因此重新附身前先脱离。
+bot 死亡、重连及 `client.resyncSec` 周期触发重新附身。
+
+摄像机账号不进入世界快照的在线玩家列表，进出服务器也不生成事件。
+
+### 启动前的设置调整
+
+`client.noPauseOnLostFocus` 默认启用，启动前修改该目录的 `options.txt` 和
+SpectatorPlus 的 `config/spectatorplus/client.json`。客户端启动时读取设置，退出时写回。
+
+- SpectatorPlus 的 `openScreens` 按 `client.syncGui` 写入。启用时同步 bot 打开的箱子、工作台和熔炉界面，包括槽位和光标物品。操作间隔由 `show.clickMs` 等参数控制，摄像机关闭时节拍归零。徒手 2×2 合成没有可同步的容器窗口。
+- 队列清空时关闭尚未关闭的容器；关窗后经 2.5 秒去抖重新附身，`client.resyncSec` 另行周期同步。
+- `pauseOnLostFocus` 设为 false，后台运行时不因失焦暂停；游戏内对应 F3+P。
+- `onboardAccessibility` 设为 false，跳过首次启动的无障碍引导。
+- `soundCategory_master` 设为 `1.0`。
+
+需要保留目录原有设置时，关闭 `client.noPauseOnLostFocus`。两份客户端共用目录时共享
+`options.txt`，退出时各自按内存设置写回；需要独立设置时应使用不同 `gameDir`。
+
+## 控制台面板(自有面板 bundle)
+
+五个面板在 `console/` 里各占一个文件，`console/client.ts` 是装配口(default
+export 的 `panels` 键就是服务端 `console().panels[].id`)：`mount` 挂载、
+`skin` 皮肤、`world` 存档与玩法、`access` 权限与作弊、`log` World 日志。数据面一律走
+`ctx.invoke / invokeBinary`，DOM 一律用 `ctx.ui` 原语，定时器一律 `ctx.interval`。
+
+面板 id 与标题由 `MINECRAFT_PANEL_DECLS` 一处给出，真 World 与子进程代理共用——
+控制台隔着代理看到的表面必须与直连时一模一样。
+
+### 挂载(mount)
+
+挂载接口分别管理服务器、观察者和玩家客户端，方法名使用对应前缀，例如
+`server.state`、`client.start` 与 `player.teleport`。
+
+- **游戏服务器**：`worlds.minecraft.local.serverDir` 指定含 `server.jar` 的目录，`local.javaPath` 指定 Java。停止时通过 stdin 发送 `stop` 保存存档，15 秒后仍未退出则强制终止。
+- **观察者客户端**：窗口出现表示客户端进程已就绪，进服和附身另按玩家列表确认。`client.enabled=false` 时仍可手动启停；World 启动及一键挂载不自动启动它。
+- **玩家客户端**：与观察者使用独立进程和账号，共用 `GameClient` 实现；附身与传送由 World 编排。默认继承观察者的游戏目录和版本，`worlds.minecraft.player.*` 可覆盖。仅在共用游戏目录时，将 `chatVisibility` 设为 FULL，以允许打开聊天框和命令行；不应用观察者的其他启动设置。
+- 服务器健康探测独立于托管进程，已运行的外部服务器显示为外部实例。World 停止时终止其托管进程。
+- 接口为 `mount.{server,client,player}.{state,start,stop}` 与 `mount.player.teleport`。兼容路由 `/api/console/providers/world%3Aminecraft/panels/{server,client}/{state,start,stop}` 调用相同实现，World 未挂载时返回 503。
+
+#### 玩家传送
+
+启用 `player.teleportToBot` 时，World 在玩家进入 bot 的玩家列表后等待 2 秒，执行
+`tp <玩家> <bot>`。托管服务器使用 stdin，外部服务器使用 bot 的 op 权限发送聊天命令。
+`mount.player.teleport` 提供手动入口，不受自动传送开关限制。
+
+### 皮肤(skin)
+
+皮肤操作与生效条件见下文「皮肤」。预览按材质中的 8×8 脸部区域及帽子层生成。
+
+### 存档与玩法(world) / 权限与作弊(access) / World 日志(log)
+
+存档和权限见下文对应章节。日志通过 `log.entries(after)` 按 seq 增量读取，每 2 秒轮询一次；`WorldConsoleDecl` 未声明流式接口。
+
+## 皮肤
+
+皮肤由客户端 mod **CustomSkinLoader** 按账号名读取：
+`<gameDir>/CustomSkinLoader/LocalSkin/skins/<账号名>.png`。离线服务器按名字生成的玩家档案不含皮肤材质；此功能不修改服务端或 Mineflayer 连接。
+
+World 将所选文件保存在部署的 `data/minecraft-skin-{bot,player}.png`，用于游戏目录或账号名变化后的重新分发。bot 和玩家的皮肤均分发到观察者与玩家两份游戏目录；摄像机账号没有可渲染身体，不配置皮肤。
+
+本地 loader 在 `CustomSkinLoader.json` 的 `loadlist` 中排第一，其余条目保留，以优先使用本地皮肤。模型配置为 `model:"auto"`，由 CustomSkinLoader 按材质识别 classic/slim。
+
+客户端读取玩家档案时加载材质：未启动的客户端在下次启动生效，运行中的客户端需重新进入服务器。撤回只删除内容与部署留存文件一致的已分发皮肤，保留其他内容的文件。
+
+## 工具面
+
+| 工具 | 说明 |
+|---|---|
+| `mc_do(steps, queue?)` | 提交任务。立即返回带时刻与任务号（#N）的受理回执；后台依次执行，结果以同一任务号的 `minecraft.task` 事件返回。`queue` 三态见「队列」 |
+| `mc_scout(steps, queue?)` | `tags:['read']`。与 `mc_do` 共用队列和回执，执行 probe，以及按 dryRun 入队的 goto / build / excavate / tunnel。后续操作仍可入队 |
+| `mc_check(checks)` | `tags:['read']`。提交至多 16 条断言（单格 `at/is`、区域 `count/all/air/sealed`、背包 `inv`、蓝图 `blueprint`、路标 `mark`），对照世界后只报差异。同步返回、不进队列、不移动，只读已加载区块；未加载单独报告。`sealed` 按流入通路判断，水和岩浆算通路 |
+| `mc_policy(六格，全可选)` | `tags:['write']`。设置垫脚/照明名单、照明场合、赶路取向、保留工具、主动交战条件。不进队列、不占任务号，同步回执；空调用只回读。见「策略面」 |
+| `mc_stop()` | 停止当前任务并清空待办队列。单步受阻不自动清队 |
+| `mc_escape()` | 仅用于移动或任务无法推进时的作弊脱困，不能用于旅行或濒死自救；使用前须先对外说明。立即清队并用 `/tp` 前往选定安全锚，物品保留。候选为床/重生锚、世界出生点及 `mc_map` 的「家」「床」路标；同维度无候选时回退为个人重生点优先。同维度候选优先，明确不可站立的落点降级后按水平距离选点，回执列出候选、距离、所选落点及是否位于标记的危险区 |
+| `mc_goal(add/milestone/reopen/done/drop/查询)` | `tags:['write']`。目标必须用 `plan[{do,verify\|judgment}]` 写分步实施预案。`verify` 支持方块、背包、蓝图现场、位置、实体、掉落物和身体状态的现读旁证；`judgment` 由 `milestone` 明确登记，机械步骤不能代填。按顺序推进并复核当前证据前沿，旁证失效会回退；全部成立后才受理 `done`。状态变化进事件，稳定态不周期复述。初始计数只供展示，不影响世界旁证判定 |
+| `mc_blueprint(design/save/查询/unload)` | `tags:['write']`。Palette 满矩阵功能工程蓝图。`site_mode:new` 空地新建，`retrofit` 先探测现有结构；冲突格均需审阅后带 `confirm:true`。建筑、农场、液源、作物和常见红石状态共用施工链。按 palette 编码后的总输出长度受理，IR 自动切分大平面。`design` 支持同键携现场探测结果迭代；锚点、探测、游标按 realm + dimension 隔离，首次开工回执要求登记工地路标。施工使用 `mc_do` 的 `build {blueprint, at?, stopAfter?, confirm?, dryRun?}` |
+| `mc_map(set/drop/rename/查询)` | `tags:['write']`。路标格式为 `{name, pos, kind, dimension?, note?, radius?}`；`dimension` 缺省按主世界记并在回执点名。最多 24 条，kind 限九种。set 支持批量装载，并核验当前维度的床、箱、工作站族；查询列出各维度记录，仅计算当前维度的距离方位。本工具只读写路标。路标用于死亡、行军、快照的相对位置说明及「你标记的危险区」提示 |
+
+PWSR 的设计原则见 [docs/worlds.md](../../../docs/worlds.md)：目标和路标的长期记录由 Persona 写入 Memory，World 按 realm 保存运行期内存表；切换 realm 保留旧表，切回后继续使用。重新创建 MinecraftWorld 实例或清除暂态存储项后，目标与路标为空。何时从 Memory 恢复由 Persona 决定，只有语义写操作提示同步 Memory，位置和进度等机械变化不触发提醒。
+
+当前蓝图实现与上述仅保存暂态的原则有差异：`BlueprintBook` 将设计及按 realm、维度保存的施工绑定写入 `<dataDir>/minecraft-blueprints.json`，创建实例时加载。设计可跨 realm 使用；PwsrTables 只登记蓝图的 realm 视图。未提供 `dataDir` 时蓝图只保存在内存中。
+
+空间计算以 realm + dimension 为边界。普通寻路避开传送面且不破坏门框；维度切换只由
+`transit` 明确发起，并以实际维度变化和落点稳定为完成条件。切换时移动、环境与位置突变基线
+一并重置，门两端的坐标差不会被写成步行事实。`transit` 受阻、被打断或被前置条件跳过时，
+同一任务的整条尾巴停止；非 `transit` 步骤若意外换维度，本步也不按完成并停止尾巴。维度边界
+采用失效关闭，因为后续步骤即使没有物品依赖，也可能把另一维的坐标解释成当前维坐标。
+
+### 文本与校验的归属
+
+- **`SKILL_DOC`** 声明技能行为、坐标与 id 约定及边界。`mc_scout` 的说明由同一注册表生成，只包含只读技能。
+- **schema** 声明字段类型、范围与适用技能。当前使用扁平顶层 `properties`，作为部分模型无法正确解码判别式 `oneOf` 的兼容 fallback；必填和跨字段规则由 `SKILL_DOC` 说明并由 `parseSteps` 校验。
+- **`ENV_PROMPT.md`** 声明感知模型、闭包原则与直播口径。
+- **回执**报告现场事实。仅多步任务附任务标签；单步使用该技能的回执。
+
+**受理回执只回念解析、冻结后与原输入不同的字段。** `parseSteps` 的 `notes`
+（`ParseNote`，由 `parseNoteText` 渲染）说明被忽略或归一化的参数；首步相对锚点在受理时
+冻结，回执显示冻结导致的差异。
+
+**受理回执带 `[HH:MM:SS]`。** 结局回执带受理与完成时刻、总耗时；总耗时包含排队，实际排队时另报等待时长。每一步单独报告耗时。
+
+**中断回执包含各步终态。** `reportCancelled` 与 `preempt` 报告已完成步骤的 `outcomes`，并标明正在执行的步骤被中断；最多列 6 步，其余只报数量。`cancelled` 不 urgent，仍按攒批投递。
+
+**入口校验失败回念无效输入及原因。** 例如 `[mc_do 失败] 第 1 步的 skill「往下挖」不是技能表里的动作。你写的是 [{"skill":"往下挖"}]`；不附整张技能表。
+
+**`smelt` 使用熔炉的 input / fuel / output 三槽术语。** `input` 是待烧炼的原料，
+`fuel` 是燃料，`output` 是产物。
+
+### 队列
+
+执行器使用单条顺序队列，`mc_do` 与 `mc_scout` 共用；前一任务结束后启动下一任务。
+agent 可以在同一轮发出多次调用以提交已确定的后续任务。
+
+**新任务与队列的关系由 `queue` 三态说了算**（`submit(steps, mode)`，三个分支复用同一批机械）：
+
+| 值 | 正在跑的那件 | 排着的那些 | 新任务 | 对应她的哪句话 |
+|---|---|---|---|---|
+| **`replace`（缺省）** | 继续跑 | **全部撤掉** | 接在正在跑的后面 | 「后面排的不算数了，改做这个」 |
+| `append` | 继续跑 | 保留 | 排队尾 | 「手上和排着的做完，再做这个」 |
+| `now` | **中断丢弃**，回执报它做到第几步 | 保留 | **插到队头，立刻开做** | 「别挖了，先插火把」 |
+
+- `queue:"now"` 不抢占正在自保的任务（flee / surface / eat 等 `escaping` 任务）；新任务排到队头，脱身后执行。战斗会话先经 stopCombat 交还身体，再处理任务中断。
+- 缺省 `replace` 撤掉已有待办，受理回执点名被撤任务；`now` 还报告被中断任务做到第几步。
+- `mc_stop` 停止当前任务并清空队列；需要提交急件时使用 `queue:"now"`。
+
+**首步相对锚点在受理时冻结**（`freezeFirstStep`），后续步骤仍按各自执行时的位置解析。冻结改写的字段在受理回执中以绝对坐标回念。
+
+**任务受阻保留待办队列。** `replace`、`now`、`mc_stop`、自保抢占及死亡、断线、停机等生命周期处理按各自规则撤销任务。
+
+**任务终态按步骤结果归并。** 存在受阻或跳过步骤时记 `blocked`；无受阻但有部分完成时记 `partial`；其余记 `done`，包含全为无操作的任务。
+
+世界快照和任务结局事件都通过 `renderQueue` 生成队列状态。
+
+进度、完成和受阻通过事件推送，世界快照包含队列。`mc_queue` 可现读队列及最近任务终态；同轮且读数指纹相同的重复查询返回短回执。
+
+**受阻回执包含结论和现场事实。** `SkillBlocked.message` 给出原因，`scene` 渲染受阻时的读数。寻路失败可附当前位置、目标方位与高差、三种走法的试算结果（`renderRouteMenu`）。不可见目标不在回执中暴露处数或坐标；后续路线由 agent 决定。
+
+**结论句点明实际阻碍。** 例如 `take` 因背包已满失败时，先说明背包容量问题。
+
+走不到的现场还带**目标分诊**（`probeTarget`：world.ts 的落脚预检 + 死角灌水两个
+纯函数）：A* 对"目标本身进不去"只会 timeout，10 格外的树冠会被说成"太远或太绕"。
+预检 O(27) 识别"目标那一格站不进人"，灌水 ≤128 格识别"封在小死角"。
+
+**现场分诊有结论时优先呈现，寻路器信息置后。** A* 超时仅表示未在限时内完成搜索；试算菜单的超时行不附出发距离。
+
+寻路失败只转述已知结果：`Took to long to decide` 表示限时内未算完，不能据此判定目标太远或无路。
+
+出发前试算仅在确认目标无法站立或被封闭时阻止执行；路线代价随回执报告，由 agent 决定是否停止。分诊无结论且目标距离不超过 32 格时，超时回执报告实际距离。
+
+**无进展跳闸时，净位移不足 1.5 格先做一次物理解卡。** 撤销寻路目标后释放控制键，再跳跃、后退和侧移；解卡产生位移才重发同一目标，否则立即受阻。回执区分无法移动与路线受阻。
+
+**分段寻路的受阻回执点明本段落点 `(x,y,z)`。** tunnel/build 的段目标与整步终点分别标识，便于对照核验读数。
+
+**`flee` 的时限为 30 秒**（`FLEE_DEADLINE_MS`）。到期仍未拉开指定距离时撤销目标并以受阻结束，报告耗时、拉开距离、原目标当前距离及 32 格内敌对数量；后续步骤照因果闸处理。
+
+### 技能序列
+
+技能表、参数 schema 与技能文档由 `skills.ts` 的 `SKILLS` 统一生成。
+
+**步骤依赖由显式 `needs` 或默认因果规则确定。** 省略时，`causalNeeds` 按所需材料与早先产出的交集建立依赖，物品名按类别规则双向匹配。
+显式依赖要求上游为 ok 或 partial；自动因果边在所需入料已在背包时也可放行。条件不满足则跳步并报告依赖原因。`needs:[]` 声明独立步。执行始终按列表顺序。
+
+默认因果依赖按步骤的产出与后续所需材料相交建立，例如 craft→equip、collect→craft。smelt→eat 不自动连边：烧炼产物由服务端确定，eat 也可不点名食物，执行时由自身前置检查判定。
+
+未显式声明 `expect` 时，`deriveExpect` 按技能和参数推导位置、库存、方块或手持状态：`goto` 核对位置，`craft` 核对目标物库存，单格 `build`/`excavate` 核对方块，`tunnel` 核对终点。`collect` 不自动推导库存判据，按实际挖掘量与入包量报告。推导出的判据在技能结束后核验，并将期望与实测结果写入回执。
+
+**核验回显无条件进回执，达成也写**，一步一行、达成与落空同一句式：
+
+```
+该步按「背包内原木 ≥5」核验:达成(实测 7)
+该步按「距 (10,64,10) 2 格内」核验:落空(实测 45.0 格)
+```
+
+期望核验同时报告达成与落空。核验内容与技能结论相同时合并表述；回执以世界状态为主语。
+
+无法推导可靠后置状态时，`deriveExpect` 返回 null，保留技能自身的结论。
+
+- 相对坐标不自动生成绝对位置判据；`goto` 的 `[x,z]` 形态仅核对水平距离。
+- `flee`、`attack`、`toss`、`stow`、`smelt` 和多格 `build`/`excavate` 不自动生成判据，分别由技能核对距离、目标、物品或操作结果。
+- `equip` 仅对主手物品生成 `{holding:{item}}`；盔甲、鞘翅与盾不使用手持判据。
+
+自动推导的库存判据只能否定完成，不能据此推翻失败。`craft.count` 是本步产出数量，`{has}` 是库存总量：总量不足可否定完成，总量足够不能证明本步有产出。受阻时仍附读数。`{near}`/`{block}` 直接核验位置或方块状态，可双向修正技能结论。
+
+**她写的 `expect` 是覆写**：写了就以她的为准，四种形态——`{has:{item,count}}`、
+`{near:[x,y,z],within}`（默认 2）、`{block,at:[x,y,z]}`、`{holding:{item}}`；
+锚点按评估时刻脚下解析。
+她自己声明的不受"存量不翻案"约束：那是她说的话，不是执行器猜的。
+被叫停/抢占的步不评估。
+
+
+
+`eat` 将点名食物交给 Mineflayer 的 `consume()`，由游戏决定满饱食时能否使用。上游精确返回 `Food is full` 时按「已经吃饱了，没吃」记正常无操作，后续无关步骤继续；其他错误按受阻处理。
+
+`DRINKABLES`（`item-facts.ts`）补充 minecraft-data 的 `foods` 表之外的可饮用物品，当前包含 `milk_bucket`。牛奶通过完整的饮用流程使用；回执核对状态效果与空桶，不使用饱食度判定，也不更新“上次进食”时间。
+
+`use.times` 对每种右键操作生效，最多 16 次。回执报告已完成的右键次数与请求次数；物品用完或单次操作失败时停止，并注明中止位置。已完成至少一次时保留部分结果；次数本身不证明未核验的效果已发生。
+
+`equip` 省略 `item` 或写 `air` 表示清空主手；`use` 省略 `item` 则沿用当前手持物。解析归一化进入受理回执。背包已满时，Mineflayer 的 `equipEmpty` 可能通过 `tossStack` 将主手物品扔到地上，回执需报告实际掉落。
+
+`find` 是**找东西这件事唯一的动词**，一个 `distance` 旋钮，执行器按有没有给
+`direction` 分诊：不给 = 站着扫一圈（最远 `FIND_STATIC_MAX` = 48 格，不挪地方）；
+给了 = 朝那个方向边走边找，每 24 格回头扫一次，看见目标就停下报坐标，走满了报走了
+多远、这一路没看见什么、人现在在哪。**两档都过同一条视线闸。**
+
+搜索回执把事实分成三层：`blockAt` 是当前复核到的方块坐标，`seenAt` 是短期真实目击，
+「这一次没有看见」只描述当前加载范围与视线，不能推出目标不存在。目击缓存按连接代次、realm
+和 dimension 隔离，15 分钟后淘汰；它只收真实命中，不把空搜索写成世界事实。
+
+**视线闸是感知纪律，不是能力上限。** 封在结构里的东西（堡垒房间里的刷怪笼、埋着的
+箱子、石头里的矿脉）从外面永远看不见，`find` 对它们结构性地无解。这一格由 `probe`
+的 `where` 名单补（见下面 probe 那一条）：`probe` 本来就是"读你圈的这片"而不是"看见"。
+两条路的分工写在措辞里——`find` 说"看见"，`where` 档说"读区块，不受遮挡与视线限制"。
+
+**命中回执区分目标方块与可站立落点。** `blockAt` 是目标占用格；可找到相邻落脚格时另行报告，目标上方有支撑的格也可作为落点。无可用落点时不编造。
+
+**一次直线搜索不能排除整个方向。** `target` 支持方块和实体 id（sheep/cow/zombie）；实体同样经过 `canSeeEntity`，回执注明其位置为看见时的读数，可能移动。找玩家使用 `goto_player`。
+
+**无可见目标时，`findEmptyHint` 按类别给出探索方向。** 矿类提示挖通道或沿洞穴探索；室内方块提示靠近门窗；活物提示换方向行进；其余提示给出 `direction`。
+
+`skills.ts` 的 `SKILLS` 声明字段名、类型、必填、范围及文档，生成 `SKILL_NAMES`、schema、`parseSteps` 校验和 `SKILL_DOC`。跨字段条件由各技能的 parse 钩子校验，包括 build 的形状与锚点数量、use 的 at/target 互斥及 craft 的 item/grid 二选一。任一步无效时整组拒绝，回执指出步骤和原因；数值越界时返回允许范围，不截断。
+
+**解析差异进入受理回执。** `parseSteps.notes` 记录步骤、字段、原值及忽略或归一化结果，由 `parseNoteText` 渲染。没有差异时不生成 notes；schema 中未使用字段的 `null` 不视为有意输入。
+
+任务名由技能序列自己渲染（`朝北走 30 格;采集 oak_log x3`），回执与世界快照
+里都用它指代任务。
+
+### 回执按实际发生的说
+
+**采集与合成报告实测入包数，放置报告服务端确认后的方块读数。** 必须有目标产出的步骤在净增为零时受阻；概率掉落采集的例外见下文。
+
+- 合成每次执行一份并记录入包数，最终按整条合成链的目标物净增裁决。槽位回灌可能迟到，单次读到零不立即停止；缺口回执注明涉及的批次，中间产物不代替目标物。
+- 采集分别报告方块是否挖掉与物品是否入包。必有掉落的采集无入包时受阻；草掉种子、树叶掉树苗等概率掉落，挖成但未掉落仍属正常结局。`dropNamesOf` 使用 minecraft-data 掉落表核对，例如 `coal_ore`→`coal`、`stone`→`cobblestone`。
+- 挖空间区分原本为空（无须挖，完成）与只有水、岩浆、火把等无碰撞箱方块（未挖成，受阻并点名内容）。
+- 放置按服务端回读确认。上游客户端预测可能提前扣物品，项目修补的 `bot.placeBlock` 会等待目标格确认；回执分别报告放成、八个候选位均被拒、或脚边没有同时满足目标格为空气、下方实心的落点。
+- 无可用落点时，`padAdjacent` 在正四方向选择一格垫底，再重试一轮。只垫一格且不试斜角：Mineflayer 会把面向量折成单轴，斜向参照可能导致落点偏移。
+- craft 与 smelt 自备工作站共用 `ensureStation`→`placeBlockNearby(pad=true)`。成功放置的工作站从 `placedLedger` 耗材记录中摘除；寻路实际垫掉的方块仍计入。
+
+**放置前按玩家碰撞箱检查占位。** 0.6 格宽的碰撞箱可能越过中心格边界；`hitboxBlocks` 命中时先用 `stepOffCell` 退到同层四邻中可站立且离目标最远的一格，退不开则受阻，不发放置包。中心格判据仍供跳跃垫脚和移开头顶格使用。
+`placeReferenceFace` 找不到参照面时报告无可贴实心面且未发包；已有参照面、发包后未确认时才报告服务端未接受。
+
+**放置与合成分别核对世界和背包读数：**
+
+- `place-unconfirmed` 记录放置未获确认的落点，进入 `placeMisses` 并写入回执；寻路支撑失败另记 `pathSupportFailure`，终止当前移动段。不能仅凭未确认断言物品已消耗。
+- `craft/no-gain` 表示某一次摆放后暂未读到入包；槽位回灌可能迟到，合成最终仍按整条链的目标物净增裁决。
+
+collect **只挖看得见的**：`collectVisible` 经 `canSeeBlockAt` 检查视线；挖掘可及距离
+4.5 格内的空形状方块直接视为可见，避免草、花被后方地面误判遮挡。看不见的目标不在
+回执中呈现处数或坐标；找不到可见目标时，`findEmptyHint` 按目标类别提示后续探索方向。
+
+`"buried":true` 必须由 agent 显式写进任务。目标仍须先过视线闸；寻路失败后才允许挖路
+接近，并照常经过贵路闸门。同一目标挖到跟前仍不存在就停止，最多打 4 次洞。
+
+### 放置 =（参照方块，面）
+
+放东西在原版里是**点一个已有方块的某一面**，新方块落在那一面的外侧：协议是
+`use_item_on { position, face, cursor }`，mineflayer 是 `placeBlock(参照方块, 面向量)`，
+而面同时决定新方块的状态（火把落地上是 `torch`、贴墙是 `wall_torch`；楼梯与活板门的
+`half` 由 cursorY 定，原木的 `axis` 由面所在的轴定）。`build` 因此收两种入参，
+**判别式，判据是 `on` 在不在**：
+
+| 形态 | 写法 | 面从哪来 |
+|---|---|---|
+| 贴面 | `"on":[{"at":[103,63,-31],"face":"up"}]` | 她给的，只点这一面，服务端不认就报不认 |
+| 格子 | `"anchors":[[103,64,-31],…]`，或 `shape` + 锚点 | 执行器按 up→down→north→south→west→east 挨个试 |
+
+`anchors` 始终表示目标格。面使用原版六个绝对名称，不接受依赖朝向的相对面；贴面形态不使用 `shape`。
+
+直接放置的 `build.material` 使用物品 id，不接收 `minecraft:torch[facing=north]` 这样的方块状态串。放置请求传递参照坐标、面和点击位置，目标格的状态以服务端回读为准。
+
+回执点明放置面：成功时报告参照坐标与面；尝试失败时报告已试六面或指定面；没有参照时报告无可贴实心方块。不以邻域其他格代替请求落点。
+
+### use：(item × 目标方块) 效果表
+
+**右键核验由手持物与目标共同确定。** `use` 据此选择方块属性、物品栏或睡眠等读数，核对该操作可观察的结果。
+
+表照原版的因果写，不自创中间概念：知道意图就知道读哪儿。
+
+| 手上 | 目标 | 读哪儿 | 把握 |
+|---|---|---|---|
+| 锄头 | 草方块 / 泥土 / 土径 | 目标格变 `farmland` | 确定（土径比较确定）|
+| 锄头 | 粗泥 / 根泥 | 目标格变 `dirt` | 比较确定 |
+| 锄头 | 耕地 | 本来就是耕地，算已达成 | 确定 |
+| 种子（小麦/甜菜/胡萝卜/土豆/西瓜/南瓜/火把花/瓶子草）| 耕地 | **上面一格**长出对应作物 | 前六确定，后二比较确定 |
+| 下界疣 | 灵魂沙 | 上面一格长出下界疣 | 确定 |
+| 空桶 | 水 / 岩浆 / 细雪 | 包里多一个对应的满桶 | 确定 |
+| 满桶 | 任意 | 包里多一个空桶 | 确定 |
+| 打火石 / 火焰弹 | 营火族 / 蜡烛族 | 目标格 `lit` 变 `true` | 比较确定 |
+| 打火石 / 火焰弹 | TNT | 目标格空出来（点着飞走了）| 确定 |
+| 打火石 / 火焰弹 | 其余方块 | **上面一格**出火（灵魂沙族出灵魂火，黑曜石框里当场成传送门）| 确定 |
+| 骨粉 | 有 `age` 的作物 | 目标格 `age` 往上走一档 | 确定 |
+| 任意 | 床 | **自身** `isSleeping` | 确定 |
+| 任意 | 门 / 活板门 / 栅栏门 | 目标格 `open` **翻了没有** | 确定 |
+| 任意 | 拉杆 | 目标格 `powered` 翻了没有 | 确定 |
+| 剪刀 | 羊 | 包里多出羊毛 | 确定 |
+| 空桶 | 牛 / 哞菇 / 山羊 | 包里多一桶奶 | 前二确定，山羊比较确定 |
+| 鞍 | 马/驴/骡/猪/炽足兽/骆驼 | **包里的鞍少一个** | 比较确定 |
+
+几条判断：
+
+- 开关类核验状态是否变化；铁门、铁活板门无法由空手切换时据实判定。
+- 按钮会自行复位（石按钮约 1 秒），单次回读不作为稳定成败判据。无对应核验规则时返回 null，只报告事实，并写 `use-off-table` 调试记录。开箱、开炉仍在关窗前将读数写入容器账本，回执列箱内内容或炉内 input/fuel/output 三槽。
+- 给已驯服的马驴装鞍以鞍的库存减少核验；骑上去是空手右键操作。
+- 无对应核验规则且目标为空气或液体时受阻，并附下方方块读数；空桶取水和满桶倒水有独立规则。
+
+`use.face` 接受绝对面名，省略时使用顶面。显式面同时传给 `activateBlock` 和对应的结果核验；读数中的坐标标识实际检查的格子。
+
+### 锚点几何技能族（geometry.ts + executor.ts）
+
+**锚点几何语言**由 build/excavate/tunnel 的操作、probe 的测量及 dryRun 的试算共用：
+
+- line/rect/triangle/arc/box 由锚点描述；坐标接受绝对值及 `~`/`~-3`，相对脚下格解析。`geometry.ts` 的纯函数栅格化由执行与试算共用。build 不写形状时只处理给定的格。
+- **build**：只放有参照面的格，近的优先；脚下格用 `jumpPlaceBelow` 跳跃垫高，头部占位先横移，无法移开则受阻。材料不足、无依托或不可及均如实停止；一块未放成时受阻，并报告占位方块。一单最多 256 块。竖直单列完成后报告实际站立列；寻路可能另搭临时柱，要站上逐格垫出的塔使用 tunnel 向上形态。不写 `shape` 时最多 16 个 anchors，逐格报告且各格独立；形状形态按连片结果汇总。
+- **excavate**：按形状自上而下、由近及远挖空间，最多 512 格。跳过紧邻液体的格并报液体名；不可挖方块单独计数，工具造成的无掉落按 dig 前 `canHarvest` 读数报告。竖井不保证回程。
+- **tunnel**：从脚下挖 1 宽 2 高通道，斜向形成楼梯，非竖直形态保证可走回。坡度超过 45° 时拒绝并指向 excavate/build；液体、区块未加载或无法补齐支撑时停止。空处由垫桥补路；到达终点才完成，否则受阻并报告已挖格、已走步数和停止原因。
+- **tunnel 横向位移为零**：向下逐格挖竖井，待挖格下方无支撑时停止；向上逐格垫塔。竖井是单程的，返回可搭塔；两者到达终点才完成，回执分别报告到底或到顶。
+- **probe**：只读指定形状内的材质构成、矿石最近坐标、液体与空气连通性；`pocketScan` 报封闭空气容积。27 格以内逐格报告坐标和方块，作物附 age。必须给出形状和锚点，不提供以自身为圆心的 target/radius 搜索。
+  `where` 可在明确圈定区域中列出指定方块的位置，最多 8192 格；它直接读取已加载区块，不受遮挡与视线限制，回执明确标注此口径。
+- **dryRun**：build/excavate/tunnel 共用规划路径，运行至栅格化和读取世界为止，报告格数、材料缺口和无掉落工具条件。goto 仅探路不移动，报告三种走法的步数、垫块数和挖块数。
+
+collect 认名字分三层：整名、类别名（`log` → 各树种原木）、**掉落物反查**。第三
+层是名字陷阱那一关：`cobblestone` 自己也是个方块（石头挖过之后放下的那种），
+地下一块都没有，要挖的其实是 `stone`。照 minecraft-data 自己的掉落表反查"挖了
+会掉出它的方块"，不写死 cobblestone→stone 这类映射。
+
+### craft：摆格子，服务端裁决
+
+**没有配方树规划器。** `bot.craft` 在协议层根本不查配方表——mineflayer-fixes 的
+覆写版只做两件事：按 `inShape` 把物品点进合成格，然后等**服务端**往产出槽放东西
+（`waitForResult`）。配方对象是摆位指令，不是许可证。
+
+- `{"skill":"craft","grid":[["charcoal"],["stick"]]}`：按显式格子摆放，以服务端产出槽为准，不预设产物。
+- `{"skill":"craft","item":"torch"}`：按配方表选择材料齐全的配方；都不齐时列出各配方的直接材料。minecraft-data 的 1.20.6 配方快照可能将 `#minecraft:coals` 展平为 coal，使用木炭等替代材料可显式给出 grid。
+- 中间材料不自动补齐；缺料回执报告当前配方的直接材料。
+
+**工作台按可及性与库存选择。** 够得着的现成工作台直接使用；否则有自备工作台就在本地放置，没有才走向现成工作台。回执报告所用或所放坐标、库存余量、现成台子的距离及是否前往。
+
+工作台与炉子共用 `ensureStation` 的查找、自备和放置逻辑。
+
+### 世界侧异步过程:哪些"等"该搬出技能
+
+判据一句话:**世界侧这个过程,人走开之后还继续跑吗?**
+
+| 还继续跑(必须拆:下单与收货分开) | 人走开就停(同步等是**对的**,别"优化") |
+|---|---|
+| 熔炉/烟熏炉/高炉(约 160 格内照烧,超出停烧、回来接着烧不丢进度,`simulation-distance=10` 的账) | `fish` 的浮漂(人走了漂就白抛) |
+| 作物生长(随机刻,与人在不在无关) | `attack`(打一半走人=没打) |
+| 酿造台、繁殖冷却(还没接) | `eat`、睡床(过程就是人在做) |
+
+**下料、到期通知与取货分开。** 下料步骤立即返回，容器账本到期后推送事件，是否取货由 agent 决定；到期不自动移动或取货。
+
+### smelt:下料点火就走
+
+`smelt` 找到 furnace/smoker/blast_furnace 后写入输入与燃料槽并立即返回。执行器不预判烧炼配方或燃料规则，实际产物由服务端决定，取货时读取。
+
+- 回执报告炉子坐标、放入物品、预计耗时及取货调用 `{"skill":"take","at":[x,y,z],"all":true}`。估时按熔炉每件 200 tick（10 秒），烟熏炉/高炉减半；远离约 160 格、区块停止模拟后可能停烧。
+- 下料时将 input/fuel/output 三槽与 `expectedDoneAt` 写入账本；到期由 `worldTick` 推 piggyback 事件。耗时是估计，槽位真值只在开窗时读取。
+- 开窗期间被中断，也先记录槽位再关窗；自保抢占回执点名账上仍有料或成品的炉子。
+- `fuel` 必填，由 agent 指定；未消耗燃料可在取货时收回。`input` 接受类别名，例如 log 可匹配背包中任意树种原木。配方不被服务端接受时输出槽仍为空。
+- 输入物品不作为本次燃料候选。
+- 找炉子共用 `ensureStation` 的三档选择；无现成或自备炉子时提示先 craft。自备炉子的坐标与放置时刻进入容器账本；其放置记录从 `placedLedger` 耗材账摘除，寻路垫块仍保留。
+- 多炉并行时跳过账上尚在烧其他材料且未到期的炉子，并报告原因；同料可续入。显式 `at` 直接指定炉子，目标不是炉子时受阻。
+- 下料前先收取输出槽已有成品，并写入回执。
+
+### take:收货的两种寻址
+
+- `{"skill":"take","item":"coal","count":16}`：按物品查找容器，优先使用账本记录，内容不符时继续开箱，最多检查 3 个。回执报告实取量；未取够时注明库存不足或背包已满。
+- `{"skill":"take","at":[x,y,z],"all":true}`：取出指定容器中的物品。炉子使用 `openFurnace`，取输出、剩余输入与燃料；箱子不带 `item` 时取出全部物品。实际取出量和剩余槽位写入回执与账本。
+
+### 挑选词:同 id 的几件里点名哪一件
+
+`stow`、`take`、`toss`、`equip`、`anvil` 和 `grindstone` 使用 `pick` 区分同 id 的物品，铁砧右格使用 `withPick`。匹配规则在 `item-pick.ts`，支持中文附魔名、英文附魔 id、罗马或阿拉伯等级，以及完整标签。
+
+`pick` 按内容筛选，`count` 决定数量；未命中时受阻，并列出同 id 物品的可选标签。
+
+Mineflayer 的按类型搬运接口使用旧 NBT 匹配，不能据此区分 1.20.5+ 的物品组件。点名一格一件的物品时，使用 `moveSlotItem` 或 `tossStack` 按槽位处理。`containerStacks` 按名称与附魔合并显示，与背包规则一致。
+
+`mc_check` 的 `inv` 按精确英文物品 id 核对，可用 `{enchant,count?}` 值筛选附魔并限定数量；挑选物品的关键词匹配另由 item-pick 处理。
+
+attack 先验证目标名（实体英文 id 或在线玩家名），不认识与不在范围分开报；
+近战按武器攻速满冷却再挥，落地跳、下落出手（crit），8 格内用方向键贴身侧移，
+苦力怕贴脸就后撤。战斗中生命跌破脱战血线（与反射同源的 `reflex.fleeHealth`）
+自动收手，**走完撤离路线**（寻路 24 格）再汇报撤到了哪。
+
+surface 是尽力而为：先浮上水面换气（这步永远做得到），再找 32 格内的登岸点；
+宽水面找不到岸、或看见了岸但游不过去时，都如实说"浮着"，不算失败——寻路器在
+水里能游，move/goto/flee 照常可用，宽水面靠它们赶路。
+
+### 寻路与挖掘的结束条件
+
+`gotoGoal` 在寻路调用返回后复核 `goal.isEnd`，同时检查脚下取整坐标及其上方一格，未到达则受阻。寻路尝试受 120 秒时限约束。
+
+`digBlock` 在挖掘前调用 `bot.canDigBlock`；当前 Mineflayer 使用眼部到目标格中心不超过 5.1 格的距离条件。挖掘预算为 `max(15 秒, digTime × 3)`，到期停止挖掘。移动和挖掘技能使用这两个公共入口。
+
+### 服务端确认补丁
+
+`mineflayer-fixes.ts` 必须通过 `bot.loadPlugin` 在 `inject_allowed` 后安装;过早安装会
+因 `bot.craft` 尚不存在而失败。安装成功写入一条 runlog 记录。
+
+补丁包含以下规则：
+
+1. **合成产物以服务端槽位更新为准。** 材料按种类分批放置，批次之间清空光标。
+2. **合成前清空合成格。** 光标物品无法放回时返回错误；徒手 2×2 合成使用不会关闭的窗口 0，失败后由补丁取回格内材料。
+3. **放置后回读目标格。** 每次等待 400ms，最多尝试三次；最终错误保留 Mineflayer 的文本契约，供寻路器处理。
+4. **丢弃 `windowId=-2` 的 `set_slot`。** 其他窗口的 `set_slot` 和 `window_items` 继续传递；已收到当前窗口的 `stateId` 时，用该值替换其他窗口包中的 `stateId`。
+
+合成与放置期间的包流记为 World 日志 `craft` 类别（`click-out`、`slot-in`、
+`items-in`、`stateid-guard`、`result-slot`、`grid-clear`);窗口外的高频 `set_slot`
+不记录。
+
+## 世界渲染与中文名
+
+**可见方块通过 `isBackground(name)` 排除天然背景。** 石土沙砾、常见岩石、树叶、野草和水生植被按背景处理，其余保留。水、岩浆、火、细雪、蛛网优先保留，再应用可见性检查。
+
+`canSeeBlockAt` 的透光集包含各色玻璃、玻璃板和铁栏杆；`tinted_glass`、树叶及门不在该集合中。先采用 `bot.canSeeBlock` 的可见结果，仅在其判遮挡时补做带 matcher 的射线，以识别透光阻挡物。
+
+可见方块分三次扫描：水、岩浆各自限量，其余使用一次判据函数扫描（`count: 2048`）。独立扫描避免高密度液体耗尽其他方块的配额。该上限在离线样本中覆盖了每种最近八处所需的最多 1542 格；使用函数判据避免大 id 数组的逐项线性匹配。
+
+`world.ts` 的渲染出口是 `narrateWorld` → 世界快照事件与其余事件正文：中文散文，写成话
+不是字段表。带**运动状态**（站着/走/跑/游/上浮/下坠，由速度与落地判断）、
+**朝向**、以及每个实体与方块的**八方位 + 距离 + 高度差**——只报距离不知道往哪走。
+
+**明暗**跟时辰、天候同段（`clock`），只有一句话、只在真的黑的时候出现：
+「四周一片漆黑，什么都看不见。」亮着就一个字都不加，具体读数一律不进快照——
+几点几她不用关心，能不能看见才是。
+
+读法是 `sampleLight`：从脚和头两格出发**按面连通**往外漫，只走透光的格
+（切比雪夫半径 4、最多 96 格），每格取 `max(方块光, 天光扣夜间惩罚 11)`，取**众数**；
+众数 ≤1 才算黑，并列取大的那个。采不到样（区块没加载、她整个人被埋住、world 不给
+光照接口）报 null 不猜——prismarine 在区块没加载时两路都返回 0，跟真的全黑分不开。
+
+不透光方块内部的光照值为 0，不能代表周围明暗；采用前述连通采样。无法采样与确实黑暗分别表示，快照按明暗文本比较，不因单格数值微变重发。
+
+`installLightRelay`（`mineflayer-fixes.ts`）修正光照 nibble 的解码布局，使采样读取对应坐标的亮度。
+
+**现实时间**自成一段（`realclock`），报到分：`现实世界现在是 8 月 19 日 20:15。`
+游戏里的昼夜和现实几点是两件事，而"播了多久""是不是该收了"只有后者答得上。不并进
+`clock` 是因为两者更新节奏差着数量级——现实的分针每分钟走一格，游戏内时辰几个小时
+才翻一次牌，混在一段里会把整段环境读数拖着一起重发。时区取部署的 `timezone`
+（`CORE_DEFAULTS` 默认 `Asia/Shanghai`），`snapshotFromBot` 不给时区时也按东八区。
+
+`names.ts` 是中文名的来源。minecraft-data 只带 en_us，所以自己给：整词表收不
+规则与常用的，词素表收前缀（材质/颜色/木种）与后缀（器物类别），其余递归拆
+——`deepslate_iron_ore` 拆两层、`waxed_weathered_cut_copper` 拆四层。实体与群系
+是闭集，全量覆盖；方块 95%、物品 92%，剩下的（陶片、盔甲纹饰、唱片）返回原始
+ID，表示中文词表未覆盖。覆盖率可用 `scratch/` 下的探针脚本复测。
+
+## 事件面
+
+| 事件 | urgent | 内容 |
+|---|---|---|
+| `minecraft.event` | 多为 true | 连入/断线、掉血、濒死、死亡、夜幕/黎明、玩家进出 |
+| `minecraft.task` | 反射急报 true | 队列里一件事的完成/受阻/被抢占（后面跟一行当下的队列）；反射的事后汇报 |
+| `minecraft.world` | false | 节流后的位移、群系、天气、背包、饥饿和新出现敌对种类的变化摘要；仅含背包增减时使用 `piggyback` |
+| `minecraft.world.snapshot` | 投递成文 | 世界状态与队列，投递时读取；按 `snapshotSec` 限制频率，与上一份相同则不生成事件，详见「世界快照事件」 |
+| `minecraft.chat` | 被点名 true | 他人聊天；自己说话回录不投递 |
+
+画面**不是**事件：观众那边由 OBS 采集， World 只投递世界数据。
+
+### 目标表陈旧自察
+
+带 plan 的目标在 1 秒世界心跳和任务终态各做一次独立现读。任务回执只触发采样，不能
+充当旁证；求值复用 `mc_check` 的方块、背包和蓝图世界取用面，实体与掉落物只在明确
+维度且区域完整加载时计数。推进、回退和 ready 只在状态边沿通知；`done` 会先重采样，
+遇到 pending、区块未知或读数错误都保留目标。已被后续里程碑承接的机械步骤冻结，当前
+证据前沿仍会复核；需要撤回主观判断时显式调用 `reopen`。
+
+目标表非空、`GOAL_STALE_MS`（45 分钟）内没有任何一次 `mc_goal` 写入、而且这中间
+World 真的做完了 `GOAL_STALE_TASKS`（3）件活——三条都成立才发一条 `piggyback`
+「目标表 N 分钟没动了，#1 …… 还挂着」。**判定、发射、预算全在 World 自己头上**，
+总线只看见一个通用档位；检测挂在 1 秒心跳上，不另起定时器。
+
+第三条判定线是关键：少了它，「她在跟观众聊天」也会被判成陈旧。响一次冷却 45 分钟，
+另有每小时 `GOAL_NOTICE_HOURLY_CAP`（2）条的类别预算兜底——超了静默跳过，
+不补一句「我本来还想提醒」（那本身又是一条提醒）。
+
+节流的第一责任在 World 内：世界摘要走 `world.tickSec` 窗口 + `moveThreshold`
+位移阈值，昼夜转换即时报。
+
+物品栏的增减单独算一条：执行器说合成了什么、采到了什么是执行器自己的说法，
+包里实际多了什么由这条说，两边对不上时看得出来。物品栏尚未同步的快照不参与
+比对——拿空栏当基准会把整包东西报成刚到手。
+
+每一项都带变化之后的总数（`云杉原木×4(共 13)`）。总数不受事件迟到或合批影响，
+可直接判断目标数量是否满足。任务期间也照常投递，不压到下一批：任务跑着的时候，
+这条是 agent 唯一读得到的进度。
+
+立即投递的事件（收工回执、反射汇报）在推出去之前先结一次世界摘要。它们会把
+整个积压一起带走，而摘要按窗口节流——不先结的话，"做完了"会排在它自己那批
+采集的前面，时间轴是倒的。
+
+伤害不进入世界摘要;含攻击者信息和反射去重的 World 播报负责该事件。
+
+### 重生点与死亡：会落在哪儿、离多远、还剩多久
+
+| 突变 | 事件 | urgent |
+|---|---|---|
+| 重生点换地方 | `重生点搬到 (x,y,z) 了，离原来那个 N 格` | 搬超过 256 格或换维度才 true |
+| 重生点失效 | `重生点失效了……从现在起死了会回世界出生点 (x,y,z)，离你现在的位置 N 格` | true |
+| 死亡 | 三段：死亡点在哪、回哪儿重生（带坐标与离死亡点多远）、掉的东西 5 分钟后消失 | true |
+| 重生落地（+3s） | `重生了，现在在 (x,y,z)，离死亡点 N 格`（实测坐标复核） | false |
+| 掉落到期（+5min） | `死亡点 (x,y,z) 那堆掉落物到 5 分钟了，没捡的已经消失` | false |
+
+三条设计约束：
+
+- **掉落物提示带时限。** 到期通知只陈述计时规则，不推断物品是否已被拾取。
+- **状态变化说明后果。** 重生点失效事件带坐标、距离和后续重生位置。
+- **重生后重设位置基线。** 瞬移不计入步行距离；物品变化与群系变化仍据实报告。
+
+原版 `startSleepInBed` 先设置重生点，再判断是否因白天拒绝睡眠。因此白天点击床可能改变重生点而未入睡。`use` 仅在 World 记录的 `set_spawn` 消息距今不超过 5 秒时附重生点说明；记录床的位置。
+
+## 水面上不许疾跑
+
+`bridge.ts` 在 `physicsTick` 上按"沾水"给 `movements.allowSprinting` 加了一层滞回：
+读到一次水就压住疾跑，离水一秒后才放开。
+
+`bot.entity.isInWater` 在水面附近可能逐 tick 抖动，直接驱动疾跑会使客户端视场角
+以 20Hz 来回插值。滞回仅作用于水面附近，陆地疾跑不受影响。
+
+## 水里不垫塔
+
+`pathfinder-perf.ts` 只允许在脚下有实心参照面的浅水中垫塔。脚在液体中且脚下格不实心时，`getMoveUp` 不生成垂直放置动作，`getMoveJumpUp` 也不生成横向垫块；放置需要可贴的实心面。
+
+## 容器账本
+
+命名地点由 `mc_map` 登记和查询，按 realm 保存并记录维度。`mc_do` 的 `goto` 可使用当前维度的路标名作为 `at` 参数。
+
+容器账本由 `chests.ts` 管理，保存到 `<dataDir>/minecraft-chests.json`，按方块坐标记录：
+
+- 箱子族记录 `stow`、`take`、`use` 开窗时最后看见的内容；近处快照标明库存或尚未打开。
+- 炉子族记录 input/fuel/output 三槽及估计的 `expectedDoneAt`，到期推 piggyback 事件，读数也进入近处快照。
+- `ensureStation` 放下的工作台/炉子记录坐标与放置时刻；几何 dryRun 覆盖账本落点时只提示，不阻断。方块被挖掉后销账。
+- 实际挖掘时：寻路器以 `blocksCantBreak` 保护容器与工作站；`excavate` 跳过账本容器并报告；`tunnel` 遇账本有料容器时停止并列账上内容。需拆除时先 `take` 掏空，再 `collect` 点名采集，采掉后销账。
+
+容器账本跨重启保存，只在附近快照中显示；未打开的容器不报告库存。
+
+## 世界快照事件（投递成文）
+
+完整世界快照通过 `minecraft.world.snapshot` 事件提供，没有对应的完整快照查询工具；背包、队列和受阻记录可分别通过 `mc_bag`、`mc_queue`、`mc_blocked` 查询。
+
+`worldTick` 每秒检查一次。距上次快照投递超过 `world.snapshotSec`（默认 10 秒）且没有待投递快照时，通过 `pushDeferred` 登记 `piggyback` 事件，不单独触发唤醒。正文在下一批事件投递时读取世界状态并生成。跨进程时，由 `arm-deferred` 登记，再用 `render-deferred` 调用引擎子进程的渲染函数。
+
+待投递超过 5 分钟时允许重新登记。渲染侧抑制 1 秒内的重复快照；断线时返回 null，不生成事件。
+
+掉血单独播报：反射只在它出手时才汇报（攻击者要在 6 格内、还得没在冷却），
+远处射来的箭、摔伤它不管。所以掉够 2 点就报一次（6s 节流），并带上
+最近的敌对是谁、在几格外；反射刚汇报过掉血来由的 5s 内不复述（按汇报的 `hurt`
+标记认，不猜措辞）。
+
+**单次掉血达到 4 点即 urgent，不受普通伤害的 6 秒节流。** 快速伤害由反射负责即时自保， World 事件报告伤害事实。
+
+## 存档与玩法
+
+控制台面板 `world`（`worldConsole()` → `world.{state,select,create,apply}`）：换存档、
+开新世界、调游戏模式与难度、极限/PVP/刷怪。
+
+改动落在 `server.properties`，而 Minecraft 只在**启动时**读它一次，所以时机分两种：
+
+- **停着**：写文件，什么都能改，下次启动生效。开新存档只是把 `level-name` 写成一个
+  不存在的名字（可带 `level-seed`），世界由服务器下次启动时生成。
+- **跑着**（含外部起的）：只有难度与默认游戏模式能经控制台指令当场改，且**不落盘**。
+  那会儿写文件既不生效，还可能被服务端自己的存盘盖掉，所以面板把其余项禁掉。
+  外部起的服务器没有 stdin，连这两项也改不了，回执直说。
+
+`server-config.ts` 读写时保留原文的顺序与注释：这份文件是人也会去编辑的。存档名直接
+当目录名用，所以挡掉路径分隔符与相对路径。Paper 的 `<world>_nether` 与
+`<world>_the_end` 是主世界的维度目录，不进入存档列表(但算进那个世界的占盘)。
+
+### 存档列表：分组 + 两种版式
+
+存档按**最近活跃**分组(今天 / 最近 7 天 / 最近 30 天 / 更早 / 还没生成)，默认只展开
+最近的那一组——服务器目录里躺着几十份存档时，要找的永远是最上面那几份。版式两种，
+记在 `ctx.memo` 里：**网格**(一眼扫完有哪些)与**详情**(每份摊开 level.dat 自述)。
+
+活跃时间取 `level.dat` 的 `LastPlayed`，退回文件 mtime——mtime 会被备份、复制这类与
+游玩无关的动作改写。占盘按 `level.dat` 的 mtime 缓存：世界没存过盘，占盘也不会变。
+
+`level-dat.ts` 是一份只读的 NBT 解析：种子、游戏模式、难度、版本、世界类型、世界天数
+都在 `Data` 下。种子是 64 位的，按字符串带出界面才不掉精度。读坏了整份当作没有——
+存档还在，只是少几行字。
+
+### 世界生成参数
+
+`level-type` / `generator-settings` / `level-seed` / `generate-structures` 只在世界
+**第一次生成**时被读到，对着已有的世界改毫无作用。所以它们不在"应用"那条路上，而是
+**开新存档**这个动作的参数(`world.create(name, gen)`)。世界类型词表与超平坦预设由
+服务端一处给出(`LEVEL_TYPE_LABELS` / `FLAT_PRESETS`)，随 `world.state` 下发——浏览器
+面板 bundle 不 import 服务端模块，措辞与层配方也就只有一份。
+
+超平坦预设里除了原版那三个，还有一个自配的「可挖平坦」：原版超平坦的三层底下没有
+石头，挖掘类技能在那种世界里一无所获。生成器细则在写盘前校验必须是 JSON 对象——
+服务器读不了这个键会直接崩在启动上。
+
+服务器级的世界规则(允许下界、出生点保护、视距、模拟距离、世界边界)收在面板的折叠块
+里，与生成参数分开：它们随时可改，只是同样要停机。
+
+## 权限与作弊
+
+专用服务器没有单人存档里那个「开作弊」勾选框。同一件事在这里是两半：**谁在
+`ops.json` 里**（能不能下 `/tp`、`/gamemode`、`/spectate`），以及
+`op-permission-level`（op 拿到第几级，4 才够全部指令）。
+
+吃这份名单的是 **bot 与人在游戏里打的命令**：`mc_escape` 的 `/tp`、把玩家传送到她
+旁边、摄像机附身。服务器由 World 托管时它们优先走控制台 stdin（天生 4 级，不看名单）；
+外部起的服务器没有 stdin，那条退路就是全部——名字不在名单里，这些动作会被服务端
+静默拒绝。
+
+`worlds.minecraft.local.cheats` 默认开：每次由本 World 启动服务器**之前**，把她、摄像机、
+玩家三个名字补进 `ops.json`（4 级，已在名单里的不动，谁都不删）。补齐必须赶在服务端
+读它之前——那份文件和 `server.properties` 一样只在启动时读一次。关掉这个开关则完全
+不碰名单。
+
+控制台面板 `access`（`accessConsole()` → `access.{state,setOp,apply}`）：
+
+- **停着**：直接改 `ops.json` 与 `server.properties`，下次启动生效。
+- **跑着且是托管的**：名单走控制台 `op` / `deop` 当场生效（服务端自己把新名单写回
+  文件）；`server.properties` 那几项一概要停机。
+- **跑着但是外部起的**：什么都改不了。这会儿写 `ops.json` 只会被服务端退出时的整份
+  写回盖掉，所以回执直说"先停机"，不假装成功。
+
+`ops.json` 按 **UUID** 认人，名字只是给人看的：写错 UUID 的条目服务端认不出是谁。
+名字→UUID 先问服务器自己见过谁（`usercache.json`），没见过的按离线账号算
+（`md5("OfflinePlayer:<名字>")`，大小写敏感）——`online-mode=false` 下三个账号都走这条。
+
+面板第二张卡是那几项与"谁能下命令"有关的 `server.properties`：`op-permission-level`、
+`enable-command-block`、`allow-flight`、`online-mode`、`white-list`。正版验证开着时这三个
+离线账号都进不来，白名单开着则名单外的进不来——两项都是"服务器起来了却没人能进"的
+常见来由，所以摆在同一屏。
+
+## 维持条件层
+
+干活途中世界不对劲时，就地补一个有界的小动作，然后接着做原来那件事。三条，每条
+由四件事定义——**什么时候触发、补什么、料从哪来、没料就不做**：
+
+| 条件 | 触发 | 补救 | 料（`mc_policy`） | 谁在用 |
+|---|---|---|---|---|
+| `footing` | 要落脚的那一格没底 | 往那一格放一块 | `scaffold`，默认泥土/圆石 | tunnel 垫桥、竖井挖穿前、`padAdjacent` |
+| `climb` | 上不去 | 跳起来把方块垫到脚下 | 同上 | surface 上行、tunnel 的塔 |
+| `light` | 周身黑下来 | 脚边插一根，先贴墙后贴地 | `light`，默认火把；场合见 `lightWhen` | tunnel（塔不插）、excavate；`lightWhen:"anywhere"` 时再加 collect 与 explore |
+
+**与反射层的分界是"要不要放下手上这件事"**：反射（岩浆、低血、溺水）**打断并接管**，
+走 `preempt()`，任务以"被自保反射抢占"收场；维持**不打断**，补一格、插一根，回到原来
+那一步。两层解决的是两类不同的"世界不对劲"。
+
+**这一层自己不判成败。** 没料就不做，接不接得下去由调用方按它自己的判据裁决：照明补不上，
+通道照样挖通；垫脚补不上，通道就是没挖通、塔就是没到顶——那两句是 tunnel 的判据说的，
+不是这一层说的。
+
+**做过的事进收工回执报数**（「路上有 9 格没底，垫上了」「顺手插了 3 根火把」）；
+**没做成的单独可报**，且原因分三种（名单是空的 / 名单里的方块包里都没有 / 服务端不认）。
+`climb` 不单独报数——它的次数就是调用方自己的进度数（塔的格数、上来几格），
+再报一遍就是同一件事说两遍。
+
+料一律来自 `mc_policy` 这条**常驻规矩**（见下一节）：设一次一直有效，`[]` 关掉某一条。
+`scaffold` 同时是寻路器搭路的名单。这一层只读规矩，改它的唯一入口是工具面。
+
+**策略设置和失败原因必须可见。** `mc_policy` 回执列出六项当前值，包括未修改项的默认值；因名单缺料受阻时，结论后附名单内容。
+
+照明按"周身黑不黑"触发，不按格数配额：判据与世界快照那句「四周一片漆黑」同源
+（`isDark`，连通小片取众数 ≤1），插上之后光照一涨这条自己就不再触发。插下去到服务端
+把新光照推回来之间有一拍，所以离上一根火把 6 格内不再判黑（火把光源 14、每格衰减 1）。
+**火把先贴四面墙、贴不住才落到地上**：竖井里脚下那一格就是下一铲，插在地上一挖就跟着掉。
+塔整个跳过这一条——它的下一块垫脚正是现在脚底那一格。
+
+
+## 策略面（`mc_policy`）
+
+**干活的常驻规矩，六格，各自独立。**契约面（schema / 说明 / 校验 / 落盘）一处给出，
+住在 `policy.ts`，与 `skills.ts` 的注册表同构。
+
+| 格 | 值域（默认） | 谁读它 | 层 |
+|---|---|---|---|
+| `scaffold` | 名单（`worlds.minecraft.scaffoldBlocks`） | `Upkeep.footing`/`climb`、寻路器 `scafoldingBlocks` | TASK |
+| `light` | 名单（火把） | `Upkeep.light` | TASK |
+| `lightWhen` | `dig`（默认）/ `anywhere` | 哪些技能挂 `keep.light()` | TASK |
+| `travel` | `auto`（默认）/ `dig` / `place` | `TRAVEL_COSTS` → 寻路代价 | TASK |
+| `reserve` | 名单（空） | `equipToolFor` | TASK |
+| `fight` | `armed`（默认）/ `auto` / `off` | `CombatSession.watchTick` 的主动进场 | FIGHT |
+
+**前五项策略持久化，`fight` 重启后恢复 `DEFAULT_FIGHT`。** `loadPolicy` 不读取已保存的 `fight`。连入时 `renderPolicyEnv(s, restored)` 标注恢复的设置；本次修改后不再显示恢复提示。
+
+**`DEFAULT_FIGHT` 为 `armed`。** 主动进场要求近战武器或可用远程武器，并继续检查血线等条件。
+
+
+
+`mc_policy` 提供 `ENV > FIGHT > TASK` 各层使用的参数，不能放宽硬约束。`combat.enabled=false` 时 `fight` 不生效；`travel:"place"` 不允许违反液体中的放置限制；`fight:"auto"` 不允许与 warden、wither 或末影龙交战；`reserve` 不影响战斗武器选择。
+
+`reserve` 先从可产出目标掉落物的工具中排除名单项，再按等级选择。排除后无可用工具时，使用原候选中最好的工具，并在回执说明使用了保留项。例如两把镐都能产出时可保留铁镐，只有铁镐能产出钻石时仍使用铁镐。
+
+**`fight` 控制主动进场**：`off` 禁止主动进场，`armed` 要求有近战武器或可用远程武器，
+`auto` 不设武器门槛。主动进场仍须达到 `fleeHealth + 3` 的血线。
+
+**被打后的处理另有保护条件**：无近战武器且无可用远程武器、血量低于 `fleeHealth + 3`
+时直接撤退；其余受击进场仍须达到 `fleeHealth`。血线不足时转撤退并播报。环境占用、
+冷却和不可交战目标等闸门继续生效；`fight` 三档均不意味着挨打一律还手。
+
+控制台的 `reflex.fightBack` 控制反射层的受击反击；关闭它仍允许低血逃离。受击会先
+尝试交给战斗会话处理，未被接手时才进入此反射开关控制的降级路径。战斗会话由
+`combat.enabled` 总开关控制。
+
+世界快照频率、战斗常数与退出条件、反射开关、`reflex.fleeHealth`、`combat.enabled` 及部署参数由操作员配置，`mc_policy` 不提供这些设置。
+
+`{{minecraft.policy}}` 在环境提示词中列出非默认设置，全为默认值时返回空串；连入服务器时也报告非默认项。策略不进入周期世界快照。
+
+策略保存在 `data/minecraft-policy.json`，可通过 `console().storage` 清除。跨进程时，代理的 `envPromptVars()` 读取该文件。
+
+## 战斗模式(档 1:常驻夜间自保)
+
+被打或敌对进入 `engageRadius`（默认 3 格）时，战斗会话（`combat.ts`）按上述策略与
+血线条件决定交战或撤退。移动层使用 `combat-context.ts` 的上下文图：行为提供
+interest/danger 图，硬约束通过 masking 执行。
+
+普通猪灵走处境判定：成年个体在未穿金甲时进入敌对池，实际穿着任一件金甲时不主动
+进场，幼体不主动进场；猪灵蛮兵始终敌对。任何实体一旦成为 `entityHurt` 的实际来源，
+就进入本场还手目标，不再由附近生物猜攻击者。金锭右键成年猪灵会等到确认收金与观察到
+延迟回礼才结束；地面回礼只报告种类、数量与坐标，不隐式拾取。
+
+控制权优先级为 `ENV > FIGHT > TASK`。环境自保通过 `yieldToEnv` 和 `envBusy` 使战斗让出控制，由环境反射汇报。战斗期间，`busyWith` 暂停任务执行器；`mc_do` 仍受理新任务并说明等待原因。
+
+`body-lease.ts` 把这三类 owner 的交接表示成同一份短租约：控制器只提交生存收益、
+紧迫性、可行性、进展、连续性、执行风险和中断成本，仲裁器不认识具体怪物或动作名。
+它是纯观测器：每秒记录候选、建议 owner、迟滞/抢占理由和现有控制器的实际 heartbeat，
+死亡、断线、停止与连接代次切换先使旧租约失效；观测结果不拦截现有动作。
+
+交战期间继续投递事件：接敌、击杀和撤退使用 urgent，战况每 6 秒随其他事件投递。事件正文采用第一人称可观察事实，遵守闭包原则。战斗会话已报告的击杀不再由 World 重复播报。
+
+战斗暂停当前任务并保存断点，战后继续。当前步骤经 `checkAbort` 中止，任务与 `stepIndex` 保留。已结束步骤的终态保留在 `stepLog`，用于后续依赖判断和最终回执；正在执行的 collect 保留计数进度，只继续剩余数量。开工时间、主动丢弃物的位置及附带完成的操作也保留。craft、smelt、toss、stow、take、多次 use 和交易等可能重复消耗物品的步骤不重跑，按未完成处理，后续步骤按依赖条件判断。
+
+**寻路目标按 bot 实例登记所有权。** `setOwnedGoal` / `dropGoal(bot, by, why)` 记录
+目标的主人（`task`/`combat`/`escape`/`fall`/`path-support`/`link`）、意图与时间。允许
+覆盖或撤销其他主人的目标，但必须给出理由并记录 `goal-owner-override`。`releaseBody`
+保留反射登记的逃生目标（`escape`）及方向键；重连更换实例后旧账失效。零位移探针的
+`goalOwner` 读取同一份登记。
+
+**队列冻结分 environment/fall 两槽。** 环境危机（`pauseForEnvironment`）与深坠
+（`stopCurrent`）各持令牌，各自释放、看门狗独立计时（60 秒）。**两槽都空才恢复队列**；
+先释放的一槽返回 `released:true`，记录 `hold-partial-release`，但不解冻断点。环境等待
+危险解除，深坠等待稳定落脚。mc_stop、抢占、死亡、断线、停机同时清空两槽。
+
+断点只有一个，归 `QueueFreezeOwner` 组所有；环境与深坠属于 `queue` 组，战斗冻结
+属于 `combat` 组，走 `busyWith` 闸。
+
+战斗的结束、撤退与冷却条件：
+
+- 当前退出判据内的威胁持续为空 3 秒时结束。
+- 仍有威胁且生命低于 `reflex.fleeHealth` 时撤退；撤退失败后进入 `desperate` 状态的还手不再检查这条血线。进场血线见「策略面」。
+- 达到最长时限（默认 30 秒）时结束，并报告附近剩余威胁数量。
+- 准备进入新战斗时，若过去 5 分钟的战斗时长占比超过 `busyRatio`，进入 `cooldownSec` 冷却；冷却期间受击由反射降级路径处理。
+- 连续 6 秒无法攻击且无法接近目标时结束；其他无进展判据由 `combat.ts` 管理。
+- 环境自保占用控制权时结束战斗。
+- 不与 warden、wither、末影龙交战，遇到时撤退；未被激怒的末影人不进入主动目标集合。
+- `mc_stop` 停止攻击并开始撤退，同时清空任务队列。
+- 死亡或断线时释放战斗控制。
+
+`worlds.minecraft.combat.space` 是近战期望距离，默认 2.6 格。`combat.*` 支持热改。
+
+`combat.enabled` 关掉退回下面反射层的"受击反击"降级行为。她显式点名的
+`attack` 技能仍是独立入口(走执行器,不经会话)。
+
+## 反射层
+
+受击反击（血少改脱离，不追击;`combat.enabled` 开着时这条由战斗会话接手,
+这里只是降级行为）、防溺水上浮、挨烧逃离。
+全部不经 LLM，事后 `minecraft.task` 汇报。阈值与开关都在
+`worlds.minecraft.reflex.*`，热改即生效。
+
+防烧与防溺水在开关启用时按 200ms 心跳检查；受击事件挂钩按 SLOW_EVERY 分频维护，已开始的窒息自救逐心跳复查。饥饿进入世界快照，由 agent 调用 eat 处理。
+
+生命低于 `fleeHealth` 时可触发撤退，不受 `fightBack` 开关限制；默认血线为 10 点。
+
+**撤寻路目标一律使用 `setGoal(null)`，不用 `pathfinder.stop()`。** `stop()` 仅设置
+延迟处理的 `stopPathing`，下一次 `setGoal()` 会经 `resetPath` 清除新目标。
+`setGoal(null)` 同步撤销旧目标并使在途 `goto` 拒绝；`preempt` 不重复撤销寻路目标。
+
+反射接管寻路前中断执行器的当前任务，并报告自保抢占原因。当前任务已处于 flee、surface 或战斗撤退等逃离状态时，反射不再抢占、反击或设置另一个寻路目标。
+
+防溺水要求头部位于水体中；刚进入水中的前 2 秒不采信氧气读数，以免使用上次浸水的残留值。世界快照也仅在头部位于水中时显示氧气。
+
+不可信期间仅按水下计时触发；头出水连续三秒或已经干燥落脚时清除溺水状态。可信读数在头出水后达到 15/20 也可解除。仍在水中且无其他环境危机时立即释放环境租约，干燥落脚走稳定窗口。水下每两秒记录浸水、氧气、可信度与持续时间。
+
+逃生先在头顶被实心封住时寻找同一水体、水平 6 格内头顶为空气的水面格换气（`drown-breath`），再找登岸点。登岸点要求脚下实心、脚与头为空气，并检查从当前列上浮到目标头高、再直行的通路；上浮段检查头部经过的各格，水平段检查脚、头两层的实心阻挡。因无进展撤销的目标进入本轮排除集，危机解除后清空。
+
+### 挨烧
+
+**`hazardTouch` 按碰撞箱范围检测烧人方块。** 从脚格至头格，水平方向各留 0.1 格余量；玩家碰撞箱宽 0.6 格，边缘接触也会命中。身上着火且 3 格内仍有火源时也触发处理。
+
+逃离烧灼区域时先撤销旧寻路目标，朝候选落点按住 forward 和 sprint；陷入岩浆时同时按住 jump。1.2 秒后将落点交给寻路器，交接后两个 DASH 周期内仍未脱离时恢复手动移动。
+
+候选落点要求脚下实心、脚和头部为空间可用且非烧灼方块或液体，与每处火源至少相距 3 格，直线路径不经过火源。每次检查重新计算落点。急报间隔至少 20 秒，脱离时另行报告。
+
+### 环境伤害
+
+`entityHurt` 优先使用实际攻击源（1.20+ `damage_event`）；source 缺席或指向自身时回退到 6 格内最近的敌对生物，排除玩家。仍无攻击者时按环境伤害处理：不占用、不受反击冷却，立即复查烧灼并记录 `env-hurt`。掉血由 World 播报，反射不重复报告。
+
+## World 日志
+
+Minecraft 日志通过 `WorldHost.log` 写入 `<dataDir>/runs/<run>/log.jsonl`，写入级别由 `logging` 配置控制。文件超过 64 MiB 后，于下次写入前轮换为 `log.1.jsonl`，已有轮换文件依次编号。
+
+控制台读取最近 2,000 条内存记录，可按 `lane` 筛选。面板记录使用 `MinecraftLogEntry`：`{seq, ts, lane, event, taskId?, durMs?, msg, data}`；落盘记录使用 Core 的 `LogRecord`，其中 `taskId` 对应 `task`。当前 World 的日志转发器忽略 `child(lane)`，落盘 `area` 为 `worlds.minecraft`，类别仅保留在面板记录中。
+
+| 类别 | 内容 |
+| --- | --- |
+| `tool` | 工具参数与即时回执 |
+| `event` | 已投递事件的完整正文 |
+| `task` | 排队、开始、抢占、取消和终态 |
+| `skill` | 步骤参数、耗时、结果与受阻原因 |
+| `craft` | 合成计划、工作台条件、槽位更新与目标物净增 |
+| `path` | `path_update`、`path_reset`、`goal_updated`，含路径步数、搜索节点数、耗时与重置原因；5 秒内的同类更新只计数 |
+| `reflex` | 自保触发时的氧气、位置、浸水时长与登岸条件 |
+| `combat` | 进入、结束、击杀、挥刀与命中记录 |
+| `link` | 连接、物品栏同步与摄像机附身 |
+| `world` | 服务端死因、重生点变化与死亡时记录的重生点 |
+
+运行日志通过 `task` 等字段关联工具、事件与执行记录；各类记录是否落盘取决于日志级别。
+
+- **`skill/aborted` 记录抢占方**：`data.by` 与 `Aborted` message 说明战斗挂起、环境
+  自保、`mc_stop` 或 `queue:"now"` 顶替；原因进入回执和诊断。
+- **`world/death-cause` 记录服务端官方死因**：自己的 `death.*` 系统消息并入死亡专报，
+  不再单独投递。
+- **`reflex/lava-clear` 记录进出计次**（`data.bout`）：连续 600ms 无危险接触且熄火才
+  结算，驻留期间不交还执行权；从第 2 次起点明本轮脱离次数。
+
+`MinecraftLog.clear()` 只清除面板缓冲，不删除运行日志文件。容器等账本由 World 通过 `console().storage` 声明各自的清除操作。
+
+## 死亡账本
+
+`deaths.ts` 将最近一次记录死亡的世界、当日和累计死亡数保存在 `data/minecraft-deaths.json`。死亡回执报告当日序号；日界为部署时区 **06:00**，进程重启保留记录。记录不同世界的死亡时重置并覆盖账本，不保存各世界的历史副本。
+
+## 配置
+
+控制台里分成四组：**连接**（重启生效）、**节奏与反射**（全热改）、
+**观察者客户端**、**玩家客户端**。技能表由
+`skills.ts` 注册表提供,并直接进入 `mc_do` 的参数说明。
+
+## 挂载
+
+```ts
+if (cfg.worlds.minecraft.enabled) {
+  worlds.push(new MinecraftWorld({
+    cfg: cfg.worlds.minecraft,        // 活对象引用,x-hot 键热改生效
+    timezone: cfg.timezone,
+    botName: cfg.displayName,
+  }));
+}
+```
+
+将 `"minecraft"` 加入 `worlds.vtuber.delayedSources`，并在 OBS 对 viewer 网页或客户端窗口设置固定延迟，以同步音频。