cortico 0.1.0

package/src/worlds/minecraft/item-break.ts

@@ -0,0 +1,126 @@
+import type { Bot } from 'mineflayer';
+import { readDurability, type Durability, type ItemLike } from './item-facts.ts';
+
+type ItemBreakSlot = 'mainhand' | 'offhand' | 'head' | 'chest' | 'legs' | 'feet';
+
+export interface ItemBreakFact {
+  kind: 'item-break';
+  slot: ItemBreakSlot;
+  name: string;
+  /** 事件前最近一次装备快照中的剩余耐久。 */
+  durability: Durability;
+}
+
+interface EntityStatusPacket {
+  entityId: number;
+  entityStatus: number;
+}
+
+type ItemSnapshot = Omit<ItemBreakFact, 'kind'> & {
+  /** 槽位先清空时给同一批服务端损坏事件留出的短暂关联窗口。 */
+  validUntil?: number;
+};
+
+const CLEARED_SNAPSHOT_MS = 1_000;
+
+const STATUS_SLOT = new Map<number, ItemBreakSlot>([
+  [47, 'mainhand'],
+  [48, 'offhand'],
+  [49, 'head'],
+  [50, 'chest'],
+  [51, 'legs'],
+  [52, 'feet'],
+]);
+
+const INVENTORY_SLOT = new Map<number, ItemBreakSlot>([
+  [45, 'offhand'],
+  [5, 'head'],
+  [6, 'chest'],
+  [7, 'legs'],
+  [8, 'feet'],
+]);
+
+/** 从本玩家的 entity_status 47–52 读取物品损坏事件；槽位变化只更新关联用的装备快照。 */
+export class ItemBreakDecoder {
+  private attached = false;
+  private readonly snapshots = new Map<ItemBreakSlot, ItemSnapshot>();
+
+  private readonly onHeldItemChanged = (item: ItemLike | null): void => {
+    this.remember('mainhand', item);
+  };
+
+  private readonly onInventorySlot = (
+    index: number,
+    _oldItem: ItemLike | null,
+    newItem: ItemLike | null,
+  ): void => {
+    const slot = INVENTORY_SLOT.get(index);
+    if (slot) this.remember(slot, newItem);
+  };
+
+  private readonly onEntityStatus = (packet: EntityStatusPacket): void => {
+    if (packet.entityId !== this.bot.entity.id) return;
+    const slot = STATUS_SLOT.get(packet.entityStatus);
+    if (!slot) return;
+    const snapshot = this.snapshots.get(slot);
+    if (!snapshot) return;
+    this.snapshots.delete(slot);
+    if (snapshot.validUntil !== undefined && Date.now() > snapshot.validUntil) return;
+    this.onBreak({
+      kind: 'item-break',
+      slot: snapshot.slot,
+      name: snapshot.name,
+      durability: { ...snapshot.durability },
+    });
+  };
+
+  constructor(
+    private readonly bot: Bot,
+    private readonly onBreak: (fact: ItemBreakFact) => void,
+  ) {}
+
+  get active(): boolean { return this.attached; }
+
+  attach(): void {
+    if (this.attached) return;
+    this.attached = true;
+    this.captureAll();
+    this.bot.on('heldItemChanged', this.onHeldItemChanged as never);
+    this.bot.inventory.on('updateSlot', this.onInventorySlot as never);
+    this.bot._client.on('entity_status', this.onEntityStatus as never);
+  }
+
+  detach(): void {
+    if (!this.attached) return;
+    this.attached = false;
+    this.bot.off('heldItemChanged', this.onHeldItemChanged as never);
+    this.bot.inventory.off('updateSlot', this.onInventorySlot as never);
+    this.bot._client.off('entity_status', this.onEntityStatus as never);
+    this.snapshots.clear();
+  }
+
+  private captureAll(): void {
+    this.snapshots.clear();
+    this.remember('mainhand', this.bot.heldItem);
+    for (const [index, slot] of INVENTORY_SLOT) {
+      this.remember(slot, this.bot.inventory.slots[index] as ItemLike | null | undefined);
+    }
+  }
+
+  private remember(slot: ItemBreakSlot, item: ItemLike | null | undefined): void {
+    if (!item) {
+      const previous = this.snapshots.get(slot);
+      if (previous && previous.validUntil === undefined) {
+        this.snapshots.set(slot, { ...previous, validUntil: Date.now() + CLEARED_SNAPSHOT_MS });
+      }
+      return;
+    }
+    const durability = readDurability(item);
+    if (!durability) return;
+    this.snapshots.set(slot, {
+      slot,
+      name: item.name,
+      durability: { ...durability },
+    });
+  }
+}

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

@@ -0,0 +1,146 @@
+/**
+ * 读取物品的附魔与耐久，支持组件数据和 NBT。
+ * 当前 1.20.6 注册表的 maxDurability 数据不完整，耐久上限使用下方原版公式表。
+ */
+
+/** 附魔 ID 去掉 minecraft: 前缀；level 为数值等级。 */
+export interface ItemEnchant {
+  name: string;
+  level: number;
+}
+
+/** 剩余耐久与上限,单位是原版的「点」 */
+export interface Durability {
+  left: number;
+  max: number;
+}
+
+export interface ItemLike {
+  name: string;
+  count?: number;
+  componentMap?: Map<string, { type?: string; data?: unknown }>;
+  nbt?: unknown;
+}
+
+export interface EnchantRegistry {
+  enchantments?: Record<number, { name?: string } | undefined>;
+}
+
+const TOOL_MAX: Record<string, number> = {
+  wooden: 59, stone: 131, iron: 250, golden: 32, diamond: 1561, netherite: 2031,
+};
+const TOOL_KIND = new Set(['pickaxe', 'axe', 'shovel', 'hoe', 'sword']);
+
+/** 盔甲耐久 = 材质基数 × 部位系数(原版公式) */
+const ARMOR_BASE: Record<string, number> = {
+  leather: 5, chainmail: 15, iron: 15, golden: 7, diamond: 33, netherite: 37,
+};
+const ARMOR_SLOT: Record<string, number> = {
+  helmet: 11, chestplate: 16, leggings: 15, boots: 13,
+};
+
+/** 不按材质×部位算的那几件 */
+const WHOLE_MAX: Record<string, number> = {
+  shield: 336, bow: 384, crossbow: 465, trident: 250, elytra: 432,
+  fishing_rod: 64, flint_and_steel: 64, shears: 238, brush: 64,
+  carrot_on_a_stick: 25, warped_fungus_on_a_stick: 100,
+  turtle_helmet: 275,
+};
+
+/** 这件东西的耐久上限;不带耐久的物品返回 null */
+export function maxDurabilityOf(id: string): number | null {
+  const name = id.replace(/^minecraft:/, '');
+  const whole = WHOLE_MAX[name];
+  if (whole !== undefined) return whole;
+  const cut = name.lastIndexOf('_');
+  if (cut < 0) return null;
+  const head = name.slice(0, cut);
+  const tail = name.slice(cut + 1);
+  if (TOOL_KIND.has(tail) && TOOL_MAX[head] !== undefined) return TOOL_MAX[head];
+  const slot = ARMOR_SLOT[tail];
+  const base = ARMOR_BASE[head];
+  if (slot !== undefined && base !== undefined) return base * slot;
+  return null;
+}
+
+function componentData(item: ItemLike, type: string): unknown {
+  return item.componentMap?.get(type)?.data;
+}
+
+/** NBT compound 里取一个键的裸值;层级对不上就返回 undefined */
+function nbtValue(node: unknown, key: string): unknown {
+  const v = (node as { value?: Record<string, { value?: unknown }> } | undefined)?.value;
+  return v?.[key]?.value;
+}
+
+/** 已损耗的耐久点数;读不到返回 null(与「没损耗」是两回事) */
+export function readDamage(item: ItemLike): number | null {
+  const comp = componentData(item, 'damage');
+  if (typeof comp === 'number') return comp;
+  const raw = nbtValue(item.nbt, 'Damage');
+  return typeof raw === 'number' ? raw : null;
+}
+
+/** 剩余耐久；不带耐久的物品返回 null。缺失 damage 组件或 NBT Damage 字段按零损耗处理。 */
+export function readDurability(item: ItemLike): Durability | null {
+  const max = maxDurabilityOf(item.name);
+  if (max === null) return null;
+  return { left: Math.max(0, max - (readDamage(item) ?? 0)), max };
+}
+
+/** 从 stored_enchantments 和 enchantments 读取附魔。 */
+export function readEnchants(item: ItemLike, registry?: EnchantRegistry | null): ItemEnchant[] {
+  const out: ItemEnchant[] = [];
+  for (const type of ['enchantments', 'stored_enchantments']) {
+    const data = componentData(item, type) as { enchantments?: Array<{ id?: unknown; level?: unknown }> } | undefined;
+    for (const e of data?.enchantments ?? []) {
+      const name = enchantName(e.id, registry);
+      if (name !== null && typeof e.level === 'number') out.push({ name, level: e.level });
+    }
+  }
+  if (out.length > 0) return out;
+  for (const key of ['Enchantments', 'StoredEnchantments']) {
+    const list = nbtValue(item.nbt, key) as { value?: Array<Record<string, { value?: unknown }>> } | undefined;
+    for (const e of list?.value ?? []) {
+      const name = enchantName(e.id?.value, registry);
+      const lvl = e.lvl?.value;
+      if (name !== null && typeof lvl === 'number') out.push({ name, level: lvl });
+    }
+  }
+  return out;
+}
+
+/** 附魔 id 可能是字符串(NBT 时代)或注册表序号(组件时代);查不出名字就不报这一条 */
+function enchantName(id: unknown, registry?: EnchantRegistry | null): string | null {
+  if (typeof id === 'string') return id.replace(/^minecraft:/, '');
+  if (typeof id !== 'number') return null;
+  return registry?.enchantments?.[id]?.name ?? null;
+}
+
+/**
+ * 读取药水内容的注册表序号；缺失时返回 null。
+ * 当前 minecraft-data 不含药水注册表，此处不翻译序号。
+ */
+export function readPotionId(item: ItemLike): number | null {
+  const data = componentData(item, 'potion_contents') as { potionId?: unknown } | undefined;
+  return typeof data?.potionId === 'number' ? data.potionId : null;
+}
+
+/** 一样能喝下去、但不给饱食度的东西 */
+interface Drinkable {
+  /** 回执里的量词说法:「喝了一桶奶」 */
+  label: string;
+  /** 喝完剩在包里的空容器物品 id */
+  empty: string;
+  /** 消耗后的效果说明。 */
+  effect: string;
+}
+
+/** 补充 foods 表未包含、但 Mineflayer consume() 支持的无饱食度饮品。 */
+export const DRINKABLES: Readonly<Record<string, Drinkable>> = {
+  milk_bucket: {
+    label: '一桶奶',
+    empty: 'bucket',
+    effect: '身上的状态效果被清光(增益也一起清掉)',
+  },
+};

package/src/worlds/minecraft/item-pick.ts

@@ -0,0 +1,67 @@
+/**
+ * 按物品的显示标签、英文附魔 ID 和数值等级做子串匹配。
+ * 同一挑选词可匹配多件物品，操作数量由 count 指定；未匹配时返回候选清单。
+ */
+import { roman, zhEnchant, zhName } from './names.ts';
+import { readEnchants, type EnchantRegistry, type ItemEnchant, type ItemLike } from './item-facts.ts';
+import { enchantSuffix } from './terrain.ts';
+
+export interface PickTarget {
+  name: string;
+  enchantments?: readonly ItemEnchant[];
+}
+
+export function pickLabel(it: PickTarget): string {
+  return `${zhName(it.name)}${enchantSuffix(it.enchantments)}`;
+}
+
+export function pickTargetOf(item: ItemLike, registry?: EnchantRegistry | null): PickTarget {
+  return { name: item.name, enchantments: readEnchants(item, registry) };
+}
+
+function normalize(s: string): string {
+  return s.toLowerCase().replace(/\s+/g, '');
+}
+
+function facets(it: PickTarget): string[] {
+  const out = [zhName(it.name), it.name, pickLabel(it)];
+  for (const e of it.enchantments ?? []) {
+    const zh = zhEnchant(e.name);
+    out.push(zh, `${zh}${roman(e.level)}`, `${zh}${e.level}`, e.name, `${e.name}${e.level}`);
+  }
+  return out;
+}
+
+/** 空挑选词不筛选。 */
+export function matchesPick(pick: string | undefined, it: PickTarget): boolean {
+  if (!pick) return true;
+  const q = normalize(pick);
+  return q.length > 0 && facets(it).some((f) => normalize(f).includes(q));
+}
+
+export function itemMatchesPick(
+  pick: string | undefined,
+  item: ItemLike,
+  registry?: EnchantRegistry | null,
+): boolean {
+  return pick ? matchesPick(pick, pickTargetOf(item, registry)) : true;
+}
+
+/** 无附魔时显示“没有附魔”。 */
+function pickFacts(it: PickTarget): string {
+  return enchantSuffix(it.enchantments).replace(/[（）]/g, '') || '没有附魔';
+}
+
+export function pickMissText(
+  where: string,
+  id: string,
+  pick: string,
+  sameId: readonly PickTarget[],
+): string {
+  return `${where}有 ${sameId.length} 件${zhName(id)},没有一件带「${pick}」:`
+    + `${sameId.map(pickFacts).join(' / ')}`;
+}
+
+export function pickedText(picked: readonly PickTarget[]): string {
+  return [...new Set(picked.map(pickLabel))].join('、');
+}

package/src/worlds/minecraft/level-dat.ts

@@ -0,0 +1,176 @@
+/**
+ * 读取存档 level.dat 的 NBT 元数据；同时支持 gzip 压缩和未压缩内容。
+ * 解析失败返回 null。存档元数据与下次启动的 server.properties 配置分别显示。
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { gunzipSync } from 'node:zlib';
+
+/** 存档元数据；缺失字段为 null。 */
+export interface LevelDatInfo {
+  /** 存档自己记的显示名,可能与目录名不同 */
+  levelName: string | null;
+  /** 上次游玩时刻，Unix 毫秒。 */
+  lastPlayed: number | null;
+  /** 世界种子;1.16+ 在 WorldGenSettings 下 */
+  seed: string | null;
+  /** 0=生存 1=创造 2=冒险 3=旁观 */
+  gameType: number | null;
+  /** 0=和平 1=简单 2=普通 3=困难 */
+  difficulty: number | null;
+  hardcore: boolean | null;
+  /** 存档 Version.Name 字段。 */
+  version: string | null;
+  /** 主世界生成器:flat / amplified / large_biomes / normal;认不出为 null */
+  generator: string | null;
+  /** 世界内时间(tick);/ 24000 即天数 */
+  dayTime: number | null;
+  /**
+   * Data/GameRules 的原始字符串值；null 表示读不到，空对象表示读到但没有规则。
+   * Paper/Bukkit 各维度单独存储，必须读取对应维度的 level.dat。
+   */
+  gameRules: Record<string, string> | null;
+}
+
+type NbtValue = number | bigint | string | NbtValue[] | { [key: string]: NbtValue };
+
+const TAG_END = 0;
+const TAG_BYTE = 1;
+const TAG_SHORT = 2;
+const TAG_INT = 3;
+const TAG_LONG = 4;
+const TAG_FLOAT = 5;
+const TAG_DOUBLE = 6;
+const TAG_BYTE_ARRAY = 7;
+const TAG_STRING = 8;
+const TAG_LIST = 9;
+const TAG_COMPOUND = 10;
+const TAG_INT_ARRAY = 11;
+const TAG_LONG_ARRAY = 12;
+
+class Cursor {
+  private i = 0;
+  constructor(private readonly buf: Buffer) {}
+
+  u8(): number {
+    if (this.i >= this.buf.length) throw new Error('nbt eof');
+    return this.buf[this.i++];
+  }
+  i16(): number { const v = this.buf.readInt16BE(this.i); this.i += 2; return v; }
+  i32(): number { const v = this.buf.readInt32BE(this.i); this.i += 4; return v; }
+  i64(): bigint { const v = this.buf.readBigInt64BE(this.i); this.i += 8; return v; }
+  f32(): number { const v = this.buf.readFloatBE(this.i); this.i += 4; return v; }
+  f64(): number { const v = this.buf.readDoubleBE(this.i); this.i += 8; return v; }
+  skip(n: number): void { this.i += n; }
+  str(): string {
+    const n = this.buf.readUInt16BE(this.i);
+    this.i += 2;
+    const s = this.buf.subarray(this.i, this.i + n).toString('utf8');
+    this.i += n;
+    return s;
+  }
+}
+
+function readPayload(c: Cursor, type: number): NbtValue {
+  switch (type) {
+    case TAG_BYTE: return c.u8();
+    case TAG_SHORT: return c.i16();
+    case TAG_INT: return c.i32();
+    case TAG_LONG: return c.i64();
+    case TAG_FLOAT: return c.f32();
+    case TAG_DOUBLE: return c.f64();
+    case TAG_BYTE_ARRAY: { const n = c.i32(); c.skip(n); return []; }
+    case TAG_STRING: return c.str();
+    case TAG_LIST: {
+      const inner = c.u8();
+      const n = c.i32();
+      const out: NbtValue[] = [];
+      for (let i = 0; i < n; i++) out.push(inner === TAG_END ? 0 : readPayload(c, inner));
+      return out;
+    }
+    case TAG_COMPOUND: return readCompound(c);
+    case TAG_INT_ARRAY: { const n = c.i32(); c.skip(n * 4); return []; }
+    case TAG_LONG_ARRAY: { const n = c.i32(); c.skip(n * 8); return []; }
+    default: throw new Error(`nbt type ${type}`);
+  }
+}
+
+function readCompound(c: Cursor): Record<string, NbtValue> {
+  const out: Record<string, NbtValue> = {};
+  for (;;) {
+    const type = c.u8();
+    if (type === TAG_END) return out;
+    const name = c.str();
+    out[name] = readPayload(c, type);
+  }
+}
+
+function obj(v: NbtValue | undefined): Record<string, NbtValue> | null {
+  return v !== undefined && typeof v === 'object' && !Array.isArray(v) ? v as Record<string, NbtValue> : null;
+}
+function num(v: NbtValue | undefined): number | null {
+  if (typeof v === 'number' && Number.isFinite(v)) return v;
+  if (typeof v === 'bigint') return Number(v);
+  return null;
+}
+function str(v: NbtValue | undefined): string | null {
+  return typeof v === 'string' ? v : null;
+}
+
+/** 生成器 → 界面词表用的短名。1.16+ 是 dimensions 下每个维度各自的 generator。 */
+function generatorOf(gen: Record<string, NbtValue> | null): string | null {
+  const overworld = obj(obj(gen?.dimensions)?.['minecraft:overworld']);
+  const generator = obj(overworld?.generator);
+  const type = str(generator?.type);
+  if (type === null) return null;
+  if (type.endsWith('flat')) return 'flat';
+  const settings = str(generator?.settings);
+  if (settings === null) return 'normal';
+  return settings.replace(/^minecraft:/, '');
+}
+
+/** 只保留 GameRules 中的字符串值。 */
+function gameRulesOf(rules: Record<string, NbtValue> | null): Record<string, string> | null {
+  if (!rules) return null;
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(rules)) {
+    if (typeof value === 'string') out[key] = value;
+  }
+  return out;
+}
+
+export function parseLevelDat(buf: Buffer): LevelDatInfo | null {
+  try {
+    const raw = buf.length >= 2 && buf[0] === 0x1f && buf[1] === 0x8b ? gunzipSync(buf) : buf;
+    const c = new Cursor(raw);
+    if (c.u8() !== TAG_COMPOUND) return null;
+    c.str();
+    const data = obj(readCompound(c).Data);
+    if (!data) return null;
+    const gen = obj(data.WorldGenSettings);
+    const seed = gen?.seed;
+    const hardcore = num(data.hardcore);
+    return {
+      levelName: str(data.LevelName),
+      lastPlayed: num(data.LastPlayed),
+      seed: typeof seed === 'bigint' ? seed.toString() : num(seed) !== null ? String(num(seed)) : null,
+      gameType: num(data.GameType),
+      difficulty: num(data.Difficulty),
+      hardcore: hardcore === null ? null : hardcore !== 0,
+      version: str(obj(data.Version)?.Name),
+      generator: generatorOf(gen),
+      dayTime: num(data.DayTime),
+      gameRules: gameRulesOf(obj(data.GameRules)),
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function readLevelDat(path: string): LevelDatInfo | null {
+  if (!existsSync(path)) return null;
+  try {
+    return parseLevelDat(readFileSync(path));
+  } catch {
+    return null;
+  }
+}

package/src/worlds/minecraft/log.ts

@@ -0,0 +1,132 @@
+/**
+ * Minecraft 日志保存到 data/runs/<run>/log.jsonl，area 为 worlds.minecraft。
+ * 引擎子进程的日志上下文补充轮次和工具调用 ID；环形缓冲供控制台按 seq 增量读取。
+ */
+import type { Logger, LogLevel } from '../../core/types.ts';
+import { nowIso, nullLogger } from '../../core/util.ts';
+
+type MinecraftLane =
+  | 'tool'
+  | 'event'
+  | 'task'
+  | 'skill'
+  | 'craft'
+  | 'inventory'
+  | 'path'
+  | 'body'
+  | 'reflex'
+  | 'combat'
+  | 'link'
+  | 'world';
+
+export const LANE_ZH: Record<MinecraftLane, string> = {
+  tool: '工具',
+  event: '投递',
+  task: '任务',
+  skill: '技能',
+  craft: '合成',
+  inventory: '物品',
+  path: '寻路',
+  body: '身体',
+  reflex: '反射',
+  combat: '战斗',
+  link: '连接',
+  world: '世界',
+};
+
+const LANE_LEVEL: Record<MinecraftLane, LogLevel> = {
+  tool: 'info',
+  event: 'info',
+  task: 'info',
+  skill: 'debug',
+  craft: 'debug',
+  inventory: 'debug',
+  path: 'debug',
+  body: 'trace',
+  reflex: 'info',
+  combat: 'info',
+  link: 'info',
+  world: 'info',
+};
+
+const EVENT_LEVEL: Record<string, LogLevel> = {
+  'craft/slot-in': 'trace',
+  'craft/click-out': 'trace',
+  'craft/items-in': 'trace',
+  'craft/place-out': 'trace',
+  'craft/grid-clear': 'trace',
+  'craft/result-slot': 'trace',
+  'craft/stateid-rewrite': 'trace',
+  'path/update': 'trace',
+  'reflex/drown-submerged': 'trace',
+  'reflex/drown-breath': 'trace',
+  'skill/dig-ground-wait': 'trace',
+  'link/spectate': 'debug',
+};
+
+export function laneLevel(lane: MinecraftLane, event: string): LogLevel {
+  return EVENT_LEVEL[`${lane}/${event}`] ?? LANE_LEVEL[lane];
+}
+
+interface MinecraftLogInput {
+  lane: MinecraftLane;
+  event: string;
+  msg: string;
+  /** 关联的任务号;没有归属的不填 */
+  taskId?: number;
+  durMs?: number;
+  data?: Record<string, unknown>;
+  /** 未指定时按日志类别和事件类型选择级别。 */
+  level?: LogLevel;
+}
+
+export interface MinecraftLogEntry extends MinecraftLogInput {
+  seq: number;
+  ts: string;
+}
+
+interface MinecraftLogOptions {
+  /** World 的 logger(区域 worlds.minecraft);不给就只进环形缓冲 */
+  log?: Logger;
+  timezone?: string;
+  /** 环形缓冲容量(控制台面板读它) */
+  ring?: number;
+}
+
+export class MinecraftLog {
+  private readonly log: Logger;
+  private readonly timezone: string;
+  private readonly capacity: number;
+  private ring: MinecraftLogEntry[] = [];
+  private seq = 0;
+
+  constructor(opts: MinecraftLogOptions = {}) {
+    this.log = opts.log ?? nullLogger();
+    this.timezone = opts.timezone ?? 'Asia/Shanghai';
+    this.capacity = opts.ring ?? 2_000;
+  }
+
+  write(input: MinecraftLogInput): void {
+    const entry: MinecraftLogEntry = { seq: ++this.seq, ts: nowIso(this.timezone), ...input };
+    this.ring.push(entry);
+    if (this.ring.length > this.capacity) this.ring.splice(0, this.ring.length - this.capacity);
+    this.log.child(input.lane).emit(input.level ?? laneLevel(input.lane, input.event), input.msg, {
+      event: input.event,
+      ...(input.taskId !== undefined ? { task: input.taskId } : {}),
+      ...(input.durMs !== undefined ? { durMs: input.durMs } : {}),
+      ...(input.data !== undefined ? { data: input.data } : {}),
+    });
+  }
+
+  /** 面板增量轮询:seq 大于 after 的那些 */
+  after(seq: number): MinecraftLogEntry[] {
+    return this.ring.filter((e) => e.seq > seq);
+  }
+
+  /** 清空缓冲;序号继续往下走,面板的 after 游标不会因清空而回头 */
+  clear(): string {
+    const had = this.ring.length;
+    this.ring = [];
+    return `面板缓冲已清空(${had} 条);落盘的运行日志不受影响`;
+  }
+}