cortico 0.1.0 → 0.1.2

package/src/worlds/minecraft/README.md

@@ -5,23 +5,80 @@
 实时游戏 World：以 mineflayer 玩家客户端连原版服务器，把"游戏状态 → 文字观察"
 与"高层意图 → 游戏操作"接通。
 
+**症状跟服务端版本有关就先读 [ADAPT.md](ADAPT.md)。** 那里按版本记着已知的服务端判据
+差异、在日志里认出它的特征、以及客户端这边的改法。
+
+新量到一条就补进 ADAPT.md,并在情况允许时向操作员申请提一个 PR。通用的适配问题连代码
+一起提;改动牵涉上游(mineflayer、prismarine-*、服务端行为)时,代码不一定要提,那条经验
+仍然值得提。
+
 ## 结构
 
 ```
-world.ts        World:事件面、工具面、console 自报、世界变化节流、摄像机编排
+definition.ts / config.ts / world.ts  World 定义、配置段与 World 本体(事件面、工具面、
+                 console 自报、世界变化节流、摄像机编排、PWSR 三张表)
+proxy.ts / engine-child.ts / engine-ipc.ts  主进程代理、引擎子进程与两者之间的协议
+
+连上去
 bridge.ts        mineflayer 连接/断线重连/prismarine-viewer 拉起
 mineflayer-fixes.ts  把 mineflayer 里靠客户端预测的合成与放置换成等服务端回话的版本
-world.ts         纯逻辑:世界快照 → 文本渲染、变化检测(可直接单测)
-server-config.ts server.properties 与 ops.json 读写 + 存档目录枚举(存档与玩法/权限与作弊面板)
-executor.ts      异步执行器:任务队列 + 技能实现 + 自保反射(不经 LLM)
+pathfinder-perf.ts   寻路器的代价与门开关补丁(另见 patches/ 里的 upstream 补丁)
+pathfinder-lib.d.ts  寻路器没带的类型声明
+server.ts / server-config.ts  本地服务端一键启停;server.properties 与 ops.json 读写、
+                 存档目录枚举(存档与玩法/权限与作弊面板)
+client.ts / window.ts / client-launch.ts / client-options.ts / client-skins.ts
+                 观察者客户端:拉起、等窗口、改标题、.minecraft → java 命令行、皮肤
+level-dat.ts     读存档自述(世界名、种子、生成参数)
+
+读世界
+terrain.ts       世界快照 → 文本渲染与变化检测(纯逻辑,可直接单测)
+cell-facts.ts    格的读法:锚点落到哪一格、脚下与参照面、区域扫描、方块名指纹
+geometry.ts      形状与锚点的纯几何:解析、栅格化
+item-facts.ts / entity-facts.ts / item-pick.ts / item-break.ts / piglin.ts
+                 物品与实体的事实读法
+names.ts         方块/实体/生物群系/附魔/效果的中文名表
+
+技能
 skills.ts        技能注册表:SkillCall/parseSteps/SKILL_DOC/schema 全部由一份声明生成
+executor.ts      任务队列、逐步派发(runSkill)与自保反射(不经 LLM)
+skill-context.ts 技能执行的共享契约:上下文、两种终态异常、World 交给技能的只读取用口
+skills-gather.ts   collect / find / fish / trade / probe
+skills-build.ts    build 的两种形态与蓝图施工,含上岸
+skills-dig.ts      excavate / tunnel
+skills-craft.ts    craft / eat / equip
+skills-interact.ts use 的各种形态 + ride / lead / anvil / grindstone
+skills-container.ts pickup / toss / stow / take / smelt / enchant / brew / transit
+travel.ts        寻路一次的时限与卡死判据、寻路目标归属、走不通时的试算现场
+placement.ts     贴哪一面、站哪儿放得着、放完回读确认、补光与耗材许可、工作站
+containers.ts    容器与工作站窗口:找、开得稳、槽位排序、账本登记
+inventory.ts     背包读法与放置/合成/拾取后的确认等待
+tools.ts         选具:拿哪把、够不够级、快断了没有、reserve 被迫动用的记号
+melee.ts         挑兵器、挥击与冷却、远程接管判据、附近敌对生物读数,以及 attack
+until.ts         find 与 tunnel 共用的 `until` 早停名单
+receipt.ts       回执措辞:这一步是什么、受阻现场、核验结论怎么念
+precheck.ts      前置试算:受理与出队两刻的纯读判据
+
+战斗与自保
+combat.ts / combat-context.ts / ranged.ts  被动交战、方位场、弓与投掷物
+escape.ts        脱困与回生:重生点解析、tp 回执
+body-lease.ts    身体租约仲裁:谁在什么时候占着身体
+
+蓝图
+blueprint.ts     方块状态规范化与校验
+blueprint-plan.ts 编译成施工步序、账单、回读对账
+blueprint-registry.ts  原版方块状态与放置方式的对照
+blueprint-repair.ts / blueprint-resource.ts  提交修复与版本/作业登记
+
+账本与规矩
+policy.ts        mc_policy 六格常驻规矩,五格落盘
+goal-plan.ts     PWSR 目标计划的协调与判定
 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 日志转发与面板环形缓冲
+chests.ts / works.ts / explored.ts / deaths.ts  容器、成果、探索覆盖、死亡的持久账
+placed-ledger.ts 挂在 bot 实例上的小账:这一场放过、锄过、没放上的那些格
+search-observation.ts / round.ts / show.ts / readouts.ts / log.ts
+                 find 的短期观察、同轮重复查询、容器演出节拍、三份读数、日志转发
+
+console/         控制台面板两侧:服务器、存档、权限、客户端、皮肤、日志
   (Minecraft 客户端、服务端与启动器放在仓库外,不进 Git)
 ```
 
@@ -375,7 +432,7 @@ collect **只挖看得见的**：`collectVisible` 经 `canSeeBlockAt` 检查视
 
 `use.face` 接受绝对面名，省略时使用顶面。显式面同时传给 `activateBlock` 和对应的结果核验；读数中的坐标标识实际检查的格子。
 
-### 锚点几何技能族（geometry.ts + executor.ts）
+### 锚点几何技能族（geometry.ts + skills-build.ts + skills-dig.ts）
 
 **锚点几何语言**由 build/excavate/tunnel 的操作、probe 的测量及 dryRun 的试算共用：
 
@@ -473,6 +530,7 @@ surface 是尽力而为：先浮上水面换气（这步永远做得到），再
 2. **合成前清空合成格。** 光标物品无法放回时返回错误；徒手 2×2 合成使用不会关闭的窗口 0，失败后由补丁取回格内材料。
 3. **放置后回读目标格。** 每次等待 400ms，最多尝试三次；最终错误保留 Mineflayer 的文本契约，供寻路器处理。
 4. **丢弃 `windowId=-2` 的 `set_slot`。** 其他窗口的 `set_slot` 和 `window_items` 继续传递；已收到当前窗口的 `stateId` 时，用该值替换其他窗口包中的 `stateId`。
+5. **水平碰撞停在离方块面 `WALL_GAP` 处。** 服务端拒绝包围盒恰好贴着方块侧面的位置(静默传送回上一个好位置,不打 `moved wrongly`),prismarine-physics 原本停在贴面处;竖直方向贴面服务端照收,不改。改的是 `prismarine-physics` 的 AABB 原型,bot 物理与寻路器模拟同时生效。
 
 合成与放置期间的包流记为 World 日志 `craft` 类别（`click-out`、`slot-in`、
 `items-in`、`stateid-guard`、`result-slot`、`grid-clear`);窗口外的高频 `set_slot`

package/src/worlds/minecraft/cell-facts.ts

@@ -0,0 +1,226 @@
+/**
+ * 格的读法:锚点落到哪一格、脚下与参照面、区域扫描、方块名指纹。
+ *
+ * 纯读,不改世界也不发包;`geometry.ts` 算形状,这里把形状对到活着的 bot 上。
+ */
+import type { Bot } from 'mineflayer';
+import { Vec3 } from 'vec3';
+import {
+  BLOCK_FACES, rasterize, resolveAnchors,
+  type Anchor, type BlockFace, type BoxFill, type Cell, type ShapeName,
+} from './geometry.ts';
+import { SkillBlocked } from './skill-context.ts';
+import { cropAgeAt } from './terrain.ts';
+
+/** 竖井遇到这些方块时停止下挖。 */
+export const LIQUIDS = new Set(['water', 'lava', 'bubble_column']);
+
+export const BUILD_CELL_CAP = 256;
+export const EXCAVATE_CELL_CAP = 512;
+export const PROBE_CELL_CAP = 2048;
+/** probe.where 的格数上限；只逐格读取，不生成材质构成或完整逐格报告。 */
+export const PROBE_WHERE_CELL_CAP = 8192;
+
+/** 放置的稳妥手长:服务端上限 5.1,留出身位余量 */
+export const PLACE_REACH = 4;
+
+/** 一格的六个邻格偏移;与六个面同一批向量,只是这里问的是"周围有没有",不问哪一面 */
+export const NEIGHBORS6 = Object.values(BLOCK_FACES);
+
+/** 检查目标格的六个正交相邻格是否有岩浆；不包含斜对角或隔一格的位置。 */
+export function nearLavaAt(bot: Bot, c: Cell): boolean {
+  return NEIGHBORS6.some(([dx, dy, dz]) => blockAtCell(bot, { x: c.x + dx, y: c.y + dy, z: c.z + dz })?.name === 'lava');
+}
+
+export const FACE_ZH: Record<BlockFace, string> = {
+  up: '上', down: '下', north: '北', south: '南', west: '西', east: '东',
+};
+
+/**
+ * 没指定面时挨个试的次序:先脚下那一块的上面(地上的火把、路面、垫脚全走这一条),
+ * 再头顶那一块的下面,最后四个侧面按原版 Direction 的序。
+ */
+export const FACE_TRY_ORDER: readonly BlockFace[] = ['up', 'down', 'north', 'south', 'west', 'east'];
+
+/** 「贴着 (x,y,z) 的北面」:回执里点名这一次贴的是谁的哪一面 */
+export function faceText(ref: Cell, face: BlockFace): string {
+  return `贴着 ${cellText(ref)} 的${FACE_ZH[face]}面`;
+}
+
+/** 贴某一面放时的参照方块:新方块那一格沿面的反方向退一格 */
+export function refCellOf(cell: Cell, face: BlockFace): Cell {
+  const [dx, dy, dz] = BLOCK_FACES[face];
+  return { x: cell.x - dx, y: cell.y - dy, z: cell.z - dz };
+}
+
+export function feetOf(bot: Bot): Cell {
+  const p = bot.entity.position.floored();
+  return { x: p.x, y: p.y, z: p.z };
+}
+
+/** 单个锚点 → 绝对格坐标(相对写法以执行这一刻我脚下那一格为原点) */
+export function resolveAt(bot: Bot, at: Anchor): Cell {
+  const resolved = resolveAnchors([at], feetOf(bot));
+  if (!Array.isArray(resolved)) throw new SkillBlocked(resolved.error);
+  return resolved[0];
+}
+
+export function blockAtCell(bot: Bot, c: Cell): ReturnType<Bot['blockAt']> {
+  return bot.blockAt(new Vec3(c.x, c.y, c.z));
+}
+
+export const cellKeyOf = (c: Cell): string => `${c.x},${c.y},${c.z}`;
+
+/** goto [x,z] 的落脚格:从世界顶往下第一块实心的上一格。区块未加载照实受阻,不猜 */
+export function surfaceFeetAt(bot: Bot, at: Anchor): Cell {
+  const c = resolveAt(bot, at);
+  const game = bot.game as { minY?: number; height?: number } | undefined;
+  const minY = game?.minY ?? -64;
+  const top = minY + (game?.height ?? 384);
+  for (let y = top - 1; y >= minY; y--) {
+    const b = bot.blockAt(new Vec3(c.x, y, c.z));
+    if (!b) {
+      throw new SkillBlocked(
+        `(${c.x}, ${c.z}) 那里还没加载,先走近些再用 [x,z];或者直接给 y`,
+      );
+    }
+    if (b.boundingBox === 'block') return { x: c.x, y: y + 1, z: c.z };
+  }
+  throw new SkillBlocked(`(${c.x}, ${c.z}) 整柱都没有实心方块,落不了脚`);
+}
+
+export function solidAt(bot: Bot, c: Cell): boolean {
+  const b = blockAtCell(bot, c);
+  return b != null && b.boundingBox === 'block';
+}
+
+/** 这一格贴不贴得住:实心之外还要排掉服务端必拒的参照面(见 NO_PLACE_REFERENCE) */
+export function refAt(bot: Bot, c: Cell): boolean {
+  const b = blockAtCell(bot, c);
+  return b != null && b.boundingBox === 'block' && !NO_PLACE_REFERENCE.has(b.name);
+}
+
+/** 锚点解析 + 栅格化 + 规模上限,一步到位;错误一律按受阻交回 agent */
+export function shapeCells(
+  bot: Bot,
+  shape: ShapeName | undefined,
+  anchors: readonly Anchor[],
+  fill: BoxFill | undefined,
+  cap: number,
+): Cell[] {
+  const resolved = resolveAnchors(anchors, feetOf(bot));
+  if (!Array.isArray(resolved)) throw new SkillBlocked(resolved.error);
+  // 不写形状 = 就这些格,各是各的,不连成片(build 一步放 N 处走的就是这条)
+  if (!shape) return resolved;
+  const cells = rasterize(shape, resolved, fill ?? 'solid');
+  if (!Array.isArray(cells)) throw new SkillBlocked(cells.error);
+  if (cells.length > cap) {
+    throw new SkillBlocked(`这个${SHAPE_ZH[shape]}有 ${cells.length} 格,一单上限 ${cap}`);
+  }
+  return cells;
+}
+
+export interface RegionReading {
+  /** 按方块名计数;sample 是该材质任一 Block(用于工具适配判断),nearest 是离我最近的一格 */
+  counts: Map<string, { n: number; nearest: Cell; nearestD: number; sample: NonNullable<ReturnType<Bot['blockAt']>> }>;
+  /** 真空气(air/cave_air/void_air)。作物/火把等无碰撞箱方块按名字进 counts */
+  air: Cell[];
+  unloaded: number;
+}
+
+export function readRegion(bot: Bot, cells: Cell[]): RegionReading {
+  const me = bot.entity.position;
+  const counts: RegionReading['counts'] = new Map();
+  const air: Cell[] = [];
+  let unloaded = 0;
+  for (const c of cells) {
+    const b = blockAtCell(bot, c);
+    if (!b) { unloaded++; continue; }
+    if (AIR_NAMES.has(b.name)) { air.push(c); continue; }
+    const d = Math.hypot(c.x - me.x, c.y - me.y, c.z - me.z);
+    const e = counts.get(b.name);
+    if (!e) counts.set(b.name, { n: 1, nearest: c, nearestD: d, sample: b });
+    else {
+      e.n++;
+      if (d < e.nearestD) { e.nearest = c; e.nearestD = d; }
+    }
+  }
+  return { counts, air, unloaded };
+}
+
+/** 这个体积以内逐格报「(x,y,z):方块」,再大只报聚合构成 */
+export const PROBE_CELLWISE_MAX = 27;
+export const AIR_NAMES = new Set(['air', 'cave_air', 'void_air']);
+
+/** FNV-1a;probe 差分只比对指纹,不留整片读数 */
+export function fnv32(s: string): number {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return h >>> 0;
+}
+
+/** matchBlockIds 的 id 集换成名字集,供按名读格 */
+export function blockNamesOf(bot: Bot, ids: number[]): Set<string> {
+  const wanted = new Set(ids);
+  const byName = bot.registry.blocksByName as Record<string, { id: number; name: string }>;
+  const names = new Set<string>();
+  for (const b of Object.values(byName)) if (wanted.has(b.id)) names.add(b.name);
+  return names;
+}
+
+/** (x,z) 柱在 yFrom 以上有没有实心遮盖;未加载的一律按露天算(宁可少说不说错) */
+export function skyBlocked(bot: Bot, x: number, yFrom: number, z: number): boolean {
+  const game = bot.game as { minY?: number; height?: number } | undefined;
+  const top = (game?.minY ?? -64) + (game?.height ?? 384);
+  for (let y = yFrom; y < top; y++) {
+    const b = bot.blockAt(new Vec3(x, y, z));
+    if (!b) return false;
+    if (b.boundingBox === 'block') return true;
+  }
+  return false;
+}
+
+/** 读取作物 age 前构造 Vec3；真实 Mineflayer 的 blockAt 需要坐标的 floored()。 */
+export function cropAgeOfCell(bot: Bot, c: Cell): { value: number; max: number } | null {
+  return cropAgeAt(bot, new Vec3(c.x, c.y, c.z));
+}
+
+export function chebyshev(a: Cell, b: Cell): number {
+  return Math.max(Math.abs(a.x - b.x), Math.abs(a.y - b.y), Math.abs(a.z - b.z));
+}
+
+export const SHAPE_ZH: Record<ShapeName, string> = {
+  line: '直线', rect: '平面', triangle: '三角面', arc: '弧线', box: '长方体',
+};
+
+/** 格坐标进回执的样子 */
+export function cellText(c: Cell): string {
+  return `(${c.x}, ${c.y}, ${c.z})`;
+}
+
+/**
+ * 拿它当放置参照面服务端必拒的那些方块。耕地的顶面不是完整实心面,作物根本没有
+ * 碰撞箱;两者都点不成一次 use_item_on。这份集合只收原版确定性拒绝的,
+ * 悬空/树上那类「有时能成」的不进。
+ */
+export const NO_PLACE_REFERENCE = new Set([
+  'farmland',
+  'wheat', 'carrots', 'potatoes', 'beetroots', 'nether_wart',
+  'melon_stem', 'pumpkin_stem', 'attached_melon_stem', 'attached_pumpkin_stem',
+  'torchflower_crop', 'pitcher_crop',
+]);
+
+export function dimensionOf(bot: Bot): string {
+  return String(bot.game?.dimension ?? 'overworld');
+}
+
+/** 方块状态属性的原值;prismarine 不给 `getProperties` 时返回 null */
+export function blockProp(b: ReturnType<Bot['blockAt']>, key: string): string | null {
+  if (!b || typeof b.getProperties !== 'function') return null;
+  const v = b.getProperties()[key];
+  return v === undefined ? null : String(v);
+}
+

package/src/worlds/minecraft/chests.ts

@@ -290,3 +290,8 @@ export class ChestBook {
     writeFileSync(this.file, `${JSON.stringify(obj)}\n`, 'utf8');
   }
 }
+/** 箱子族在世界里的扫描名单;与账本认箱子的口径同一份(见 chests.ts CHEST_BLOCKS) */
+export const CONTAINER_FIND: readonly string[] = CHEST_BLOCKS;
+
+export const FURNACE_KINDS = new Set<string>(FURNACE_BLOCKS);
+

package/src/worlds/minecraft/containers.ts

@@ -0,0 +1,325 @@
+/**
+ * 容器与工作站的窗口:找到哪一个、开得稳、槽位怎么排、这一次看见了什么记进账本。
+ *
+ * 只管开窗与读写槽位,存什么取什么由技能族决定。
+ */
+import type { Bot } from 'mineflayer';
+import pathfinderPkg from 'mineflayer-pathfinder';
+import { Vec3 } from 'vec3';
+import { type Cell } from './geometry.ts';
+import { SkillBlocked, checkAbort, sleep, type SkillContext } from './skill-context.ts';
+import { gotoGoal, reachCell } from './travel.ts';
+import { blockAtCell, cellText, dimensionOf } from './cell-facts.ts';
+import { zhName } from './names.ts';
+import { moveExactSlot, playerInvIn, type InvPred } from './inventory.ts';
+import { readDurability, readEnchants, type EnchantRegistry } from './item-facts.ts';
+import {
+  CONTAINER_FIND, ChestBook, FURNACE_KINDS, chestBlockName, hasItem, hasRoom, type ChestRecord,
+} from './chests.ts';
+import { type ItemStack } from './terrain.ts';
+import { contentsText } from './receipt.ts';
+
+const { goals } = pathfinderPkg;
+
+/** 三种磨损态的铁砧都认 */
+export const ANVIL_BLOCKS = ['anvil', 'chipped_anvil', 'damaged_anvil'] as const;
+/** 找工作方块的半径,与 smelt 找炉子一个量级 */
+export const STATION_FIND_R = 16;
+/** 放料/取货后等服务端回灌窗口槽位 */
+export const WINDOW_SETTLE_MS = 600;
+
+export interface StationWindow {
+  id: number;
+  type: string;
+  slots: Array<{ name: string; type: number; count: number } | null>;
+  inventoryStart: number;
+  inventoryEnd: number;
+}
+
+export function findStationCell(bot: Bot, names: readonly string[]): Cell | null {
+  const reg = bot.registry.blocksByName as unknown as Record<string, { id: number } | undefined>;
+  const ids = names.map((n) => reg[n]?.id).filter((n): n is number => typeof n === 'number');
+  if (ids.length === 0) return null;
+  const found = bot.findBlocks({ matching: ids, maxDistance: STATION_FIND_R, count: 1 });
+  return found.length > 0 ? { x: found[0].x, y: found[0].y, z: found[0].z } : null;
+}
+
+/** 走到 cell、开它的窗;那一格不是这种工作方块当场说清 */
+export async function openStationWindow(
+  bot: Bot, ctx: SkillContext, cell: Cell, blockNames: readonly string[], zhStation: string,
+): Promise<{ win: StationWindow; blockName: string }> {
+  await reachCell(bot, cell, ctx);
+  checkAbort(ctx);
+  const block = blockAtCell(bot, cell);
+  if (!block) throw new SkillBlocked(`${cellText(cell)} 所在区块没加载`);
+  if (!blockNames.includes(block.name)) {
+    throw new SkillBlocked(`${cellText(cell)} 那一格是${zhName(block.name)},不是${zhStation}`);
+  }
+  const win = await (bot as unknown as { openBlock(b: unknown): Promise<StationWindow> }).openBlock(block);
+  return { win, blockName: block.name };
+}
+
+/**
+ * 把包里符合判据的一件挪进窗口的某个格。
+ *
+ * 找料照**开着的那扇窗**自己的账读(见 playerInvIn),槽位号也只在那扇窗里成立。
+ * 一格一件的按槽位挪(见 moveExactSlot):`transfer` 按类型找槽,同 id 的几件在它
+ * 眼里没有分别,点名挑的那一件就白挑了。
+ */
+export async function putIntoStation(
+  bot: Bot, win: StationWindow, pred: InvPred, destSlot: number, asked: string,
+): Promise<void> {
+  const item = playerInvIn(bot, win).items().find((i) => pred(i.name, i));
+  if (!item) throw new SkillBlocked(`包里没有${asked}`);
+  if (item.count === 1) {
+    await moveExactSlot(bot, item.slot, destSlot);
+    return;
+  }
+  await (bot as unknown as { transfer(o: Record<string, unknown>): Promise<void> }).transfer({
+    window: win, itemType: item.type, metadata: null, count: 1,
+    sourceStart: win.inventoryStart, sourceEnd: win.inventoryEnd,
+    destStart: destSlot, destEnd: destSlot + 1,
+  });
+}
+
+/** 一件东西的读数:耐久 + 附魔,回执格式统一 */
+export function stationItemFacts(bot: Bot, item: { name: string } | null): string {
+  if (!item) return '';
+  const parts: string[] = [];
+  const dur = readDurability(item as never);
+  if (dur) parts.push(`耐久 ${dur.left}/${dur.max}`);
+  const ench = readEnchants(item as never, bot.registry as never);
+  parts.push(ench.length > 0 ? `附魔 ${ench.map((e) => `${e.name}${e.level}`).join('、')}` : '没有附魔');
+  return parts.join(',');
+}
+
+export function findContainers(bot: Bot, range: number): Array<{ x: number; y: number; z: number; name: string; d: number }> {
+  const ids = CONTAINER_FIND
+    .map((n) => (bot.registry.blocksByName as Record<string, { id: number } | undefined>)[n]?.id)
+    .filter((id): id is number => id !== undefined);
+  if (ids.length === 0) return [];
+  const me = bot.entity.position;
+  const found = bot.findBlocks({ matching: ids, maxDistance: range, count: 16 });
+  const out: Array<{ x: number; y: number; z: number; name: string; d: number }> = [];
+  for (const p of found) {
+    const b = bot.blockAt(p);
+    if (!b) continue;
+    out.push({ x: p.x, y: p.y, z: p.z, name: b.name, d: p.distanceTo(me) });
+  }
+  out.sort((a, b) => a.d - b.d);
+  return out;
+}
+
+/**
+ * 报告本维度账本中最近箱子的上次观测位置与取整直线距离；没有则返回 null。
+ * 不跨维度比较坐标，也不决定走过去或放新箱子。
+ */
+export function knownChestNote(bot: Bot, chests: ChestBook | undefined): string | null {
+  const me = bot.entity.position;
+  let best: { rec: ChestRecord; d: number } | null = null;
+  for (const rec of chests?.chestsIn(dimensionOf(bot)) ?? []) {
+    const d = Math.hypot(rec.x - me.x, rec.y - me.y, rec.z - me.z);
+    if (!best || d < best.d) best = { rec, d };
+  }
+  if (!best) return null;
+  const r = best.rec;
+  const origin = r.placedAt !== undefined ? '你放的' : '你开过的';
+  return `;账上本维度最近的是${origin}${zhName(chestBlockName(r))}`
+    + ` (${r.x}, ${r.y}, ${r.z}),直线 ${Math.round(best.d)} 格(上次看见)`;
+}
+
+/** 附近一个容器都扫不到:两处(stow / take)共用同一句措辞与同一段账本补注 */
+export function noContainerNearby(bot: Bot, ctx: SkillContext): SkillBlocked {
+  return new SkillBlocked(`32 格内没有箱子${knownChestNote(bot, ctx.chests) ?? ''}`);
+}
+
+/**
+ * 箱内容按「名字 + 附魔」并栈,与背包同一条线(原版里带不同附魔的同名物品不能堆叠)。
+ * 只按名字并,五本各不相同的附魔书会念成「附魔书×5」:数量读得到,哪一本在里面读不到,
+ * 于是也点不了名(见 item-pick)。
+ */
+export function containerStacks(win: {
+  containerItems?: () => Array<{ name: string; count: number }>;
+  slots?: Array<{ name: string; count: number } | null>;
+  inventoryStart?: number;
+}, registry?: EnchantRegistry | null): { items: ItemStack[]; usedSlots: number; slots: number } {
+  const raw = typeof win.containerItems === 'function'
+    ? win.containerItems()
+    : (win.slots ?? []).slice(0, win.inventoryStart ?? 27).filter((s): s is { name: string; count: number } => s != null);
+  const merged = new Map<string, ItemStack>();
+  for (const it of raw) {
+    const ench = readEnchants(it as never, registry as never);
+    const key = ench.length > 0 ? `${it.name}|${ench.map((e) => `${e.name}${e.level}`).join(',')}` : it.name;
+    const cur = merged.get(key);
+    if (cur) cur.count += it.count;
+    else merged.set(key, { name: it.name, count: it.count, ...(ench.length > 0 ? { enchantments: ench } : {}) });
+  }
+  return {
+    items: [...merged.values()],
+    usedSlots: raw.length,
+    slots: win.inventoryStart ?? 27,
+  };
+}
+
+export function rememberChest(
+  ctx: SkillContext,
+  bot: Bot,
+  pos: { x: number; y: number; z: number },
+  win: Parameters<typeof containerStacks>[0],
+): { items: ItemStack[]; usedSlots: number; slots: number } {
+  const snap = containerStacks(win, bot.registry as never);
+  ctx.chests?.remember(dimensionOf(bot), pos, snap.items, snap.usedSlots, snap.slots);
+  return snap;
+}
+
+/**
+ * 原版烧一件的耗时:熔炉 200 刻(10 秒);高炉与烟熏炉减半(100 刻)。
+ * 这是确定性数值,所以熔炉的到期**可以**估;作物不行(随机刻),别把这条挪去作物。
+ */
+export function smeltPerItemMs(blockName: string): number {
+  return blockName === 'furnace' ? 10_000 : 5_000;
+}
+
+/** 槽位有料不能证明正在烧炼;估时需要炉火和进度读数同时确认。 */
+export function furnaceDoneAt(win: unknown, input: ItemStack | null, blockName: string, now: number): number | null {
+  const { fuel, progress } = win as { fuel?: number | null; progress?: number | null };
+  return input && typeof fuel === 'number' && fuel > 0 && typeof progress === 'number' && progress > 0
+    ? now + (input.count - progress) * smeltPerItemMs(blockName)
+    : null;
+}
+
+/** 窗口 slots 里的一格转成账本的 ItemStack;空格与读不出都算 null */
+export function slotStack(win: unknown, i: number): ItemStack | null {
+  const slots = (win as { slots?: Array<{ name?: string; count?: number } | null> }).slots;
+  const s = slots?.[i];
+  return s && typeof s.name === 'string' && typeof s.count === 'number'
+    ? { name: s.name, count: s.count }
+    : null;
+}
+
+/**
+ * 右键开出来的窗口在关窗前记进容器账本,回执带上看见了什么。
+ * 箱子族整窗记;炉子族记三槽位,有炉火和进度读数才估到期。不是容器就什么都不做。
+ */
+export function rememberWindow(
+  bot: Bot,
+  ctx: SkillContext,
+  cell: Cell,
+  blockName: string,
+  win: NonNullable<Bot['currentWindow']>,
+): string {
+  if (CONTAINER_FIND.includes(blockName)) {
+    const snap = rememberChest(ctx, bot, cell, win as Parameters<typeof containerStacks>[0]);
+    return `。箱里:${contentsText(snap.items)}`;
+  }
+  if (FURNACE_KINDS.has(blockName)) {
+    const state = { input: slotStack(win, 0), fuel: slotStack(win, 1), output: slotStack(win, 2) };
+    const now = Date.now();
+    const expected = furnaceDoneAt(win, state.input, blockName, now);
+    ctx.chests?.rememberFurnace(dimensionOf(bot), cell, blockName, state, now, expected);
+    const slot = (s: ItemStack | null): string => (s ? `${zhName(s.name)}×${s.count}` : '空');
+    return `。炉里:输入${slot(state.input)},燃料${slot(state.fuel)},输出${slot(state.output)}`;
+  }
+  return '';
+}
+
+export function orderForStow(
+  found: Array<{ x: number; y: number; z: number; name: string; d: number }>,
+  ctx: SkillContext,
+  bot: Bot,
+  item: string,
+): typeof found {
+  const dim = dimensionOf(bot);
+  const withRoom: typeof found = [];
+  const unseen: typeof found = [];
+  const rest: typeof found = [];
+  // 堆叠上限是物品自带的属性(原版:大多 64,鸡蛋/雪球 16,工具/桶 1),registry 里就有
+  const stackMax = (bot.registry.itemsByName as Record<string, { stackSize?: number } | undefined>)
+    ?.[item]?.stackSize ?? 64;
+  for (const s of found) {
+    const rec = ctx.chests?.get(dim, s);
+    if (rec && hasRoom(rec, item, stackMax)) withRoom.push(s);
+    else if (!rec) unseen.push(s);
+    else rest.push(s);
+  }
+  return [...withRoom, ...unseen, ...rest];
+}
+
+export function orderForTake(
+  found: Array<{ x: number; y: number; z: number; name: string; d: number }>,
+  ctx: SkillContext,
+  bot: Bot,
+  item: string,
+): typeof found {
+  const dim = dimensionOf(bot);
+  const withItem: typeof found = [];
+  const rest: typeof found = [];
+  for (const s of found) {
+    const rec = ctx.chests?.get(dim, s);
+    if (rec && hasItem(rec, item)) withItem.push(s);
+    else rest.push(s);
+  }
+  return [...withItem, ...rest];
+}
+
+/** mineflayer 拿错窗口身份时抛的话:「Non-container window used as a container」一族 */
+export function isWindowIdentityError(err: unknown): boolean {
+  return err instanceof Error && / window used as a /i.test(err.message);
+}
+
+/**
+ * 开容器前退役遗留窗口；返回窗口身份不符时关闭并重开一次，连续失败才受阻。
+ * 此处校验窗口身份，窗口状态版本由 mineflayer-fixes 的 stateId 守卫处理。
+ */
+export async function openWindowGuarded<T>(bot: Bot, ctx: SkillContext, open: () => Promise<T>): Promise<T> {
+  const cur = bot.currentWindow;
+  if (cur) {
+    ctx.diag?.write({
+      lane: 'skill', event: 'stale-window-retire',
+      msg: `开容器前发现还挂着窗口${cur.id}(${cur.type}),先关掉`,
+      data: { windowId: cur.id, type: String(cur.type) },
+    });
+    bot.closeWindow(cur);
+    await sleep(150);
+  }
+  try {
+    return await open();
+  } catch (err) {
+    if (!isWindowIdentityError(err)) throw err;
+    const w = bot.currentWindow;
+    ctx.diag?.write({
+      lane: 'skill', event: 'window-identity-retry',
+      msg: `开出来的窗口身份不对(${w ? `窗口${w.id} ${w.type}` : '窗口已不在'}),强制关窗重开一次`,
+      data: { windowId: w?.id, type: w ? String(w.type) : null },
+    });
+    if (w) bot.closeWindow(w);
+    await sleep(300);
+    try {
+      return await open();
+    } catch (err2) {
+      if (!isWindowIdentityError(err2)) throw err2;
+      throw new SkillBlocked(
+        '窗口串号了:上一个界面窗口没退干净,这次开容器拿到的是错的窗口身份;' +
+        '已强制关窗重试一次仍没成。东西都还在,没有丢——过几秒再开一次多半就好',
+      );
+    }
+  }
+}
+
+export async function openNearbyContainer(
+  bot: Bot,
+  spot: { x: number; y: number; z: number; name: string },
+  ctx: SkillContext,
+): Promise<Awaited<ReturnType<Bot['openContainer']>>> {
+  await gotoGoal(bot, new goals.GoalNear(spot.x, spot.y, spot.z, 2), ctx);
+  const block = bot.blockAt(new Vec3(spot.x, spot.y, spot.z));
+  if (!block) throw new SkillBlocked(`${zhName(spot.name)}不见了`);
+  return openWindowGuarded(bot, ctx, () => bot.openContainer(block));
+}
+
+export interface GenericWindow {
+  slots: Array<{ name: string; count: number; slot: number } | null>;
+  items(): Array<{ name: string; count: number; slot: number }>;
+  close(): void;
+}
+