cortico 0.1.0

package/src/worlds/minecraft/deaths.ts

@@ -0,0 +1,135 @@
+/**
+ * 持久化最近一次记录死亡的世界、死亡计数与近期死因。
+ * 每日计数以部署时区 06:00 为日界；记录不同世界的死亡时重置并覆盖原账本。
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { nowIso } from '../../core/util.ts';
+
+/** 死亡时刻、服务端死因原文与坐标；未获取死因时为 null。 */
+interface DeathFact {
+  at: string;
+  cause: string | null;
+  /** `维度:x,y,z`(floor 口径);读不到死亡点为 null */
+  cell: string | null;
+}
+
+interface DeathToll {
+  /** 账本属于哪个世界;换世界时整本重置 */
+  world: string;
+  /** `today` 所属的那一"天"(部署时区,YYYY-MM-DD);06:00 换日,见 dayKey */
+  day: string;
+  today: number;
+  total: number;
+  /** 近期死亡记录，用于计算同日同格死亡次数。 */
+  lastCauses: DeathFact[];
+}
+
+
+const LAST_CAUSES_CAP = 20;
+
+const EMPTY: DeathToll = { world: '', day: '', today: 0, total: 0, lastCauses: [] };
+
+const DAY_START_HOUR = 6;
+
+/**
+ * "今天"的键:部署时区 06:00 换日,凌晨那几个小时算前一天。
+ * 日期取自把时刻整体往回拨 6 小时之后的那一天。
+ */
+export function dayKey(timezone: string, at: Date = new Date()): string {
+  return nowIso(timezone, new Date(at.getTime() - DAY_START_HOUR * 3_600_000)).slice(0, 10);
+}
+
+/** 文件不存在、为空或格式错误时使用空记录。 */
+export function loadDeaths(file: string | null): DeathToll {
+  if (!file || !existsSync(file)) return { ...EMPTY };
+  let data: Partial<DeathToll>;
+  try {
+    data = JSON.parse(readFileSync(file, 'utf8')) as Partial<DeathToll>;
+  } catch {
+    return { ...EMPTY };
+  }
+  return {
+    world: typeof data.world === 'string' ? data.world : '',
+    day: typeof data.day === 'string' ? data.day : '',
+    today: typeof data.today === 'number' && data.today > 0 ? Math.floor(data.today) : 0,
+    total: typeof data.total === 'number' && data.total > 0 ? Math.floor(data.total) : 0,
+    lastCauses: Array.isArray(data.lastCauses)
+      ? data.lastCauses
+        .filter((f): f is DeathFact => !!f && typeof (f as DeathFact).at === 'string')
+        .map((f) => ({
+          at: f.at,
+          cause: typeof f.cause === 'string' ? f.cause : null,
+          cell: typeof f.cell === 'string' ? f.cell : null,
+        }))
+        .slice(-LAST_CAUSES_CAP)
+      : [],
+  };
+}
+
+/** 读数视图:跨过换日点的旧账本今天是 0,不必等下一次死亡才滚。 */
+export function tollOn(toll: DeathToll, day: string): { today: number; total: number } {
+  return { today: toll.day === day ? toll.today : 0, total: toll.total };
+}
+
+export class DeathBook {
+  private toll: DeathToll;
+
+  constructor(private readonly file: string | null, private readonly timezone: string) {
+    this.toll = loadDeaths(file);
+  }
+
+  /**
+   * 记录死亡后返回计数；世界改变时重置，跨日时 today 归零。
+   * hereToday 包含本次死亡；缺少死亡坐标时为 0。
+   */
+  record(
+    world: string,
+    at: Date = new Date(),
+    fact?: { cause?: string | null; cell?: string | null },
+  ): { today: number; total: number; hereToday: number } {
+    const day = dayKey(this.timezone, at);
+    if (this.toll.world !== world) this.toll = { world, day, today: 0, total: 0, lastCauses: [] };
+    if (this.toll.day !== day) this.toll = { ...this.toll, day, today: 0 };
+    const cell = fact?.cell ?? null;
+    const entry: DeathFact = { at: nowIso(this.timezone, at), cause: fact?.cause ?? null, cell };
+    const lastCauses = [...this.toll.lastCauses, entry].slice(-LAST_CAUSES_CAP);
+    this.toll = { ...this.toll, today: this.toll.today + 1, total: this.toll.total + 1, lastCauses };
+    this.save();
+    const hereToday = cell === null
+      ? 0
+      : lastCauses.filter((f) => f.cell === cell && dayKey(this.timezone, new Date(f.at)) === day).length;
+    return { today: this.toll.today, total: this.toll.total, hereToday };
+  }
+
+  /** 迟到的服务端死因仅补入 15 秒内尚无死因的最近一次死亡。 */
+  noteCause(cause: string, at: Date = new Date()): void {
+    const last = this.toll.lastCauses[this.toll.lastCauses.length - 1];
+    if (!last || last.cause !== null) return;
+    if (Math.abs(at.getTime() - new Date(last.at).getTime()) > 15_000) return;
+    last.cause = cause;
+    this.save();
+  }
+
+  count(at: Date = new Date()): { today: number; total: number } {
+    return tollOn(this.toll, dayKey(this.timezone, at));
+  }
+
+  stat(): string {
+    const { today, total } = this.count();
+    return total === 0 ? '(没死过)' : `今天 ${today} 次 / 累计 ${total} 次`;
+  }
+
+  clear(): string {
+    const { total } = this.count();
+    this.toll = { ...EMPTY, world: this.toll.world };
+    this.save();
+    return total === 0 ? '死亡账本本来就是空的' : `死亡账本已清空(原有 ${total} 次)`;
+  }
+
+  private save(): void {
+    if (!this.file) return;
+    mkdirSync(dirname(this.file), { recursive: true });
+    writeFileSync(this.file, `${JSON.stringify(this.toll)}\n`, 'utf8');
+  }
+}

package/src/worlds/minecraft/definition.ts

@@ -0,0 +1,18 @@
+import { join } from 'node:path';
+import type { WorldDefinition } from '../../world.ts';
+import { MINECRAFT_DEFAULTS, type MinecraftConfigSection } from './config.ts';
+import { MinecraftWorldProxy } from './proxy.ts';
+
+export const MINECRAFT: WorldDefinition<MinecraftConfigSection> = {
+  id: 'minecraft',
+  label: 'Minecraft',
+  defaults: () => structuredClone(MINECRAFT_DEFAULTS as unknown as MinecraftConfigSection),
+  // The child process isolates Mineflayer physics and pathfinding from the main loop.
+  create: (ctx) =>
+    new MinecraftWorldProxy({
+      cfg: ctx.cfg,
+      timezone: ctx.timezone,
+      botName: ctx.botName,
+      dataDir: ctx.dataDir,
+    }),
+};

package/src/worlds/minecraft/engine-child.ts

@@ -0,0 +1,274 @@
+/** Minecraft 引擎子进程入口。创建 World 并通过 IPC 接收配置和工具请求，向主进程转发事件及 Core 请求。 */
+import { createIpcLogger } from '../../core/ipc-logger.ts';
+import { withAnchors } from '../../core/log-context.ts';
+import { MinecraftWorld } from './world.ts';
+import type {
+  ChildToMain,
+  CognitionReply,
+  EngineInit,
+  EngineRequest,
+  HostRequest,
+  MainToChild,
+  StorageStat,
+} from './engine-ipc.ts';
+import type {
+  EventEnvelope,
+  EventStoreReader,
+  WorldHost,
+  Logger,
+  StoragePart,
+  DeferredRendered,
+} from '../../core/types.ts';
+
+function send(msg: ChildToMain): void {
+  process.send?.(msg);
+}
+
+const makeLogger = (area: string): Logger => createIpcLogger((note) => send({ t: 'note', note }), area);
+
+const log = makeLogger('');
+
+const HOST_RPC_TIMEOUT_MS = 10_000;
+/** 认知请求的 RPC 超时为 16 分钟。 */
+const COGNITION_RPC_TIMEOUT_MS = 16 * 60_000;
+let nextHostReqId = 1;
+const pendingHost = new Map<number, { resolve: (v: unknown) => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout> }>();
+
+function hostRpc(req: HostRequest, timeoutMs = HOST_RPC_TIMEOUT_MS): Promise<unknown> {
+  const id = nextHostReqId++;
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      pendingHost.delete(id);
+      reject(new Error(`主进程 ${timeoutMs / 1000}s 未回执宿主调用(${req.kind})`));
+    }, timeoutMs);
+    timer.unref?.();
+    pendingHost.set(id, { resolve, reject, timer });
+    send({ t: 'hreq', id, req });
+  });
+}
+
+/** 同步 Core 接口不能经异步 IPC 调用，使用时抛错。 */
+const unavailable = (what: string): never => {
+  throw new Error(`${what} 在子进程宿主里不可用`);
+};
+
+const store: EventStoreReader = {
+  get: () => unavailable('store.get'),
+  latestCursor: () => unavailable('store.latestCursor'),
+  range: () => unavailable('store.range'),
+  around: () => unavailable('store.around'),
+  grep: () => unavailable('store.grep'),
+};
+
+/** 按事件类型保存延迟渲染回调。 */
+const textRender = (render: () => DeferredRendered | null | Promise<DeferredRendered | null>) =>
+  async (): Promise<string | null> => {
+    const out = await render();
+    return out === null || typeof out === 'string' ? out : out.text;
+  };
+const deferredRenders = new Map<string, () => Promise<string | null>>();
+
+let cognitionOn = false;
+
+/** 跨进程请求失败返回含 error 的结果。 */
+const cognitionHost: NonNullable<WorldHost['cognition']> = {
+  request: async (req) => {
+    try {
+      return (await hostRpc({ kind: 'cognition', req }, COGNITION_RPC_TIMEOUT_MS)) as CognitionReply;
+    } catch (e) {
+      return { error: `后台思考没跑成:${e instanceof Error ? e.message : String(e)}` };
+    }
+  },
+};
+
+const host: WorldHost = {
+  pushEvent: (e, opts) => hostRpc({ kind: 'push', evt: e as Parameters<typeof host.pushEvent>[0] & { blobs?: undefined }, opts }) as Promise<EventEnvelope>,
+  pushDeferred: (e, opts) => {
+    deferredRenders.set(e.type, textRender(e.render));
+    send({
+      t: 'note',
+      note: {
+        kind: 'arm-deferred',
+        type: e.type,
+        ...(e.senderKey !== undefined ? { senderKey: e.senderKey } : {}),
+        ...(e.meta !== undefined ? { meta: e.meta } : {}),
+        ...(e.tags !== undefined ? { tags: e.tags } : {}),
+        ...(opts?.trigger !== undefined ? { trigger: opts.trigger } : {}),
+      },
+    });
+  },
+  store,
+  drainPendingEvents: () => hostRpc({ kind: 'drain' }) as Promise<EventEnvelope[]>,
+  modelFacts: {
+    model: () => unavailable('modelFacts.model'),
+    accepts: () => unavailable('modelFacts.accepts'),
+    contextWindow: () => unavailable('modelFacts.contextWindow'),
+  },
+  blob: () => unavailable('blob'),
+  reportUsage: (usage, opts) => send({ t: 'note', note: { kind: 'usage', usage, opts } }),
+  /** 能力随配置消息更新。 */
+  get cognition(): WorldHost['cognition'] {
+    return cognitionOn ? cognitionHost : undefined;
+  },
+  log,
+};
+
+let mod: MinecraftWorld | null = null;
+let cfg: EngineInit['cfg'] | null = null;
+let statusTimer: ReturnType<typeof setInterval> | null = null;
+let lastStatus = '';
+
+function applyCfg(target: Record<string, unknown>, next: Record<string, unknown>): void {
+  for (const [k, v] of Object.entries(next)) {
+    const cur = target[k];
+    if (v && typeof v === 'object' && !Array.isArray(v) && cur && typeof cur === 'object' && !Array.isArray(cur)) {
+      applyCfg(cur as Record<string, unknown>, v as Record<string, unknown>);
+    } else {
+      target[k] = v;
+    }
+  }
+}
+
+function storageStats(parts: StoragePart[]): StorageStat[] {
+  return parts.map((p) => {
+    let stat = '';
+    try {
+      stat = p.stat();
+    } catch {
+      stat = '(取不到)';
+    }
+    return {
+      key: p.key,
+      label: p.label,
+      kind: p.kind,
+      location: p.location,
+      danger: p.danger,
+      note: p.note,
+      order: p.order,
+      stat,
+    };
+  });
+}
+
+function pushStatus(): void {
+  if (!mod) return;
+  const decl = mod.console();
+  const note = {
+    kind: 'status' as const,
+    decl: { lamps: decl.lamps, badges: decl.badges, links: decl.links },
+    storage: storageStats(decl.storage ?? []),
+  };
+  const key = JSON.stringify(note);
+  if (key === lastStatus) return;
+  lastStatus = key;
+  send({ t: 'note', note });
+}
+
+async function handleRequest(req: EngineRequest): Promise<unknown> {
+  if (req.kind === 'init') {
+    if (mod) throw new Error('已经 init 过了');
+    cfg = req.init.cfg;
+    mod = new MinecraftWorld({
+      cfg,
+      timezone: req.init.timezone,
+      botName: req.init.botName,
+      ...(req.init.dataDir ? { dataDir: req.init.dataDir } : {}),
+    });
+    await mod.start(host);
+    statusTimer = setInterval(pushStatus, 1000);
+    statusTimer.unref?.();
+    return null;
+  }
+  if (req.kind === 'shutdown') {
+    if (statusTimer) clearInterval(statusTimer);
+    statusTimer = null;
+    await mod?.stop();
+    mod = null;
+    setImmediate(() => process.exit(0));
+    return null;
+  }
+  if (req.kind === 'render-deferred') {
+    /** 渲染失败返回 null。 */
+    const render = deferredRenders.get(req.type);
+    return render ? await render() : null;
+  }
+  if (!mod) throw new Error('Minecraft 引擎还没 init');
+  if (req.kind === 'tool') {
+    const tool = mod.tools().find((t) => t.name === req.name);
+    if (!tool) throw new Error(`未知工具「${req.name}」`);
+    return withAnchors({ sess: req.role, ...(req.callId ? { call: req.callId } : {}), ...(req.round !== null ? { round: req.round } : {}) }, () => tool.handler(req.args, {
+      role: req.role,
+      log,
+      ...(req.callId ? { callId: req.callId } : {}),
+      ...(req.round !== null ? { round: req.round } : {}),
+    }));
+  }
+  if (req.kind === 'storage-clear') {
+    const part = (mod.console().storage ?? []).find((p) => p.key === req.key);
+    if (!part) throw new Error(`未知存储部分: ${req.key}`);
+    return part.clear();
+  }
+  const invoke = mod.console().invoke;
+  if (!invoke) throw new Error('World 没有面板调用面');
+  return invoke(req.panel, req.method, req.args);
+}
+
+process.on('message', (msg: MainToChild) => {
+  if (msg.t === 'req') {
+    void Promise.resolve()
+      .then(() => handleRequest(msg.req))
+      .then(
+        (value) => send({ t: 'rep', id: msg.id, ok: true, value }),
+        (err: unknown) =>
+          send({ t: 'rep', id: msg.id, ok: false, error: err instanceof Error ? err.message : String(err) }),
+      );
+    return;
+  }
+  if (msg.t === 'hrep') {
+    const p = pendingHost.get(msg.id);
+    if (!p) return;
+    pendingHost.delete(msg.id);
+    clearTimeout(p.timer);
+    if (msg.ok) p.resolve(msg.value);
+    else p.reject(new Error(msg.error ?? '宿主调用失败'));
+    return;
+  }
+  const cast = msg.cast;
+  if (cast.kind === 'caps') {
+    cognitionOn = cast.cognition;
+    return;
+  }
+  if (cast.kind === 'config' && cfg) {
+    applyCfg(cfg as unknown as Record<string, unknown>, cast.cfg as unknown as Record<string, unknown>);
+  }
+});
+
+/** 父进程关闭时停止 World 及其管理的进程。 */
+process.on('disconnect', () => {
+  const m = mod;
+  if (!m) {
+    process.exit(0);
+  }
+  void m.stop().finally(() => process.exit(0));
+});
+
+/** 未处理的 Promise 拒绝只记录日志。 */
+process.on('unhandledRejection', (reason) => {
+  log.emit('error', '引擎子进程未处理的 Promise 拒绝(已忽略)', { event: 'unhandled-rejection', err: reason });
+});
+
+/** 致命异常先尝试停止 World；8 秒后强制退出。 */
+const FATAL_DRAIN_MS = 8_000;
+let dying = false;
+process.on('uncaughtException', (err) => {
+  log.emit('error', '引擎子进程未捕获异常', { event: 'uncaught-exception', err });
+  if (dying) return;
+  dying = true;
+  const m = mod;
+  mod = null;
+  if (!m) { process.exit(1); return; }
+  log.emit('warn', '引擎子进程收尾中(给服务端存档 8 秒)', { event: 'fatal-drain' });
+  const hard = setTimeout(() => process.exit(1), FATAL_DRAIN_MS);
+  hard.unref?.();
+  void m.stop().catch(() => undefined).finally(() => { clearTimeout(hard); process.exit(1); });
+});

package/src/worlds/minecraft/engine-ipc.ts

@@ -0,0 +1,98 @@
+/**
+ * Minecraft 引擎子进程运行 Mineflayer、寻路、执行器和 World 心跳。
+ * 主进程转发工具、面板及宿主调用；子进程上报日志、事件和状态缓存。
+ */
+import type { LogNote } from '../../core/ipc-logger.ts';
+import type {
+  CognitionRequest, CognitionResult, EventEnvelope, EventTag, LLMUsage, WorldConsoleDecl,
+  PushOptions, TriggerMode,
+} from '../../core/types.ts';
+import type { MinecraftConfigSection } from './config.ts';
+
+/** 构造引擎子进程 World 的一次性参数。 */
+export interface EngineInit {
+  timezone: string;
+  botName: string;
+  /** 账本目录 data/;null = 只在内存 */
+  dataDir: string | null;
+  cfg: MinecraftConfigSection;
+}
+
+/** 主 → 子:要回执的请求 */
+export type EngineRequest =
+  | { kind: 'init'; init: EngineInit }
+  /** 主进程传入的轮序号；未知时为 null。 */
+  | {
+      kind: 'tool'; name: string; args: Record<string, unknown>; role: string;
+      callId: string | null; round: number | null;
+    }
+  | { kind: 'panel'; panel: string; method: string; args: unknown[] }
+  | { kind: 'storage-clear'; key: string }
+  /** 投递时调用子进程登记的渲染回调；null 表示不生成事件正文。 */
+  | { kind: 'render-deferred'; type: string }
+  | { kind: 'shutdown' };
+
+/** 主 → 子:单向投递 */
+export type EngineCast =
+  /** x-hot 配置快照(整段替换值,不换对象身份) */
+  | { kind: 'config'; cfg: MinecraftConfigSection }
+  /** 主进程可选宿主能力的当前状态；子进程据此提供或移除对应句柄。 */
+  | { kind: 'caps'; cognition: boolean };
+
+/** StoragePart 的可序列化描述(stat 现值随状态推送,clear 走请求) */
+export interface StorageStat {
+  key: string;
+  label: string;
+  kind: 'disk' | 'memory';
+  location?: string;
+  danger?: boolean;
+  note?: string;
+  order?: number;
+  stat: string;
+}
+
+/** 子 → 主:单向通知 */
+export type EngineNote =
+  | LogNote
+  | { kind: 'usage'; usage: LLMUsage; opts?: Parameters<import('../../core/types.ts').WorldHost['reportUsage']>[1] }
+  /** 渲染回调保存在子进程；主进程登记待投递项，投递时发送 render-deferred 请求。 */
+  | {
+      kind: 'arm-deferred';
+      type: string;
+      senderKey?: string;
+      meta?: Record<string, unknown>;
+      tags?: readonly EventTag[];
+      trigger?: TriggerMode;
+    }
+  | {
+      kind: 'status';
+      decl: Pick<WorldConsoleDecl, 'lamps' | 'badges' | 'links'>;
+      storage: StorageStat[];
+    };
+
+/** 子进程调用宿主并等待结果。跨进程 drain 仅支持读取本 World 来源的事件。 */
+export type HostRequest =
+  | {
+      kind: 'push';
+      evt: Omit<EventEnvelope, 'cursor' | 'origin'> & { origin?: EventEnvelope['origin'] };
+      opts?: PushOptions;
+    }
+  | { kind: 'drain' }
+  /**
+   * 主进程按 World 声明的工具名校验 req.tools。
+   * 宿主能力不可用时，error 以 COGNITION_ABSENT 开头。
+   */
+  | { kind: 'cognition'; req: CognitionRequest };
+
+/** host.cognition.request 的跨进程返回值。 */
+export type CognitionReply = CognitionResult;
+
+export type MainToChild =
+  | { t: 'req'; id: number; req: EngineRequest }
+  | { t: 'hrep'; id: number; ok: boolean; value?: unknown; error?: string }
+  | { t: 'cast'; cast: EngineCast };
+
+export type ChildToMain =
+  | { t: 'rep'; id: number; ok: boolean; value?: unknown; error?: string }
+  | { t: 'hreq'; id: number; req: HostRequest }
+  | { t: 'note'; note: EngineNote };

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

@@ -0,0 +1,132 @@
+/** 实体元数据字段位置取自 registry.entitiesByName 的 metadataKeys。 */
+
+interface NamedStack { name?: string }
+
+interface FactEntity {
+  name?: string;
+  metadata?: unknown[];
+}
+
+interface FactBot {
+  entity?: { uuid?: string } | null;
+  /** 登录时玩家 UUID 优先取 bot.player，其次取实体或协议客户端。 */
+  player?: { uuid?: string } | null;
+  _client?: { uuid?: string } | null;
+  inventory?: { slots?: Array<NamedStack | null | undefined> };
+  registry?: {
+    entitiesByName?: Record<string, { metadataKeys?: string[] } | undefined>;
+  };
+}
+
+function metaOf(bot: FactBot, entity: FactEntity, key: string): unknown {
+  const name = entity.name;
+  if (!name) return undefined;
+  const keys = bot.registry?.entitiesByName?.[name]?.metadataKeys ?? [];
+  const at = keys.indexOf(key);
+  return at >= 0 ? entity.metadata?.[at] : undefined;
+}
+
+/** 可驯服实体与对应道具。消耗道具只能证明使用发生，驯服结果须读取主人元数据。 */
+export const TAME_ITEMS: Readonly<Record<string, readonly string[]>> = {
+  wolf: ['bone'],
+  cat: ['cod', 'salmon'],
+  ocelot: ['cod', 'salmon'],
+  parrot: ['wheat_seeds', 'beetroot_seeds', 'melon_seeds', 'pumpkin_seeds', 'torchflower_seeds', 'pitcher_pod'],
+};
+
+/** 繁殖交互使用的实体与食物表；物品消耗不作为幼体出生的证明。 */
+export const FEED_ITEMS: Readonly<Record<string, readonly string[]>> = {
+  cow: ['wheat'],
+  mooshroom: ['wheat'],
+  sheep: ['wheat'],
+  goat: ['wheat'],
+  pig: ['carrot', 'potato', 'beetroot'],
+  rabbit: ['carrot', 'golden_carrot', 'dandelion'],
+  chicken: ['wheat_seeds', 'beetroot_seeds', 'melon_seeds', 'pumpkin_seeds', 'torchflower_seeds', 'pitcher_pod'],
+  // 1.20.5 起狼的食物是 #wolf_food 物品标签:全部生熟肉(含腐肉)+全部鱼类
+  wolf: ['beef', 'porkchop', 'chicken', 'mutton', 'rabbit', 'cooked_beef', 'cooked_porkchop', 'cooked_chicken', 'cooked_mutton', 'cooked_rabbit', 'rotten_flesh', 'cod', 'salmon', 'cooked_cod', 'cooked_salmon', 'tropical_fish', 'pufferfish'],
+  cat: ['cod', 'salmon', 'tropical_fish', 'pufferfish'],
+  horse: ['golden_carrot', 'golden_apple', 'hay_block'],
+  donkey: ['golden_carrot', 'golden_apple', 'hay_block'],
+  llama: ['hay_block'],
+  armadillo: ['spider_eye'],
+  panda: ['bamboo'],
+  turtle: ['seagrass'],
+  fox: ['sweet_berries', 'glow_berries'],
+  bee: ['dandelion', 'poppy', 'sunflower'],
+  frog: ['slime_ball'],
+  sniffer: ['torchflower_seeds'],
+  camel: ['cactus'],
+  strider: ['warped_fungus'],
+  hoglin: ['crimson_fungus'],
+  axolotl: ['tropical_fish_bucket'],
+};
+
+/** 这只活物现在的主人 UUID;没被驯服/读不到元数据返回 null。 */
+export function readTamedBy(bot: FactBot, entity: FactEntity): string | null {
+  const raw = metaOf(bot, entity, 'owneruuid');
+  // 协议把"没有主人"编成缺席的 optional;不同版本的 protodef 分别给 undefined/null/''
+  if (raw === undefined || raw === null || raw === '') return null;
+  if (typeof raw === 'string') return raw;
+  // OptionalUUID 有时解成 { present, value } 或者裸的 UUID 对象
+  const obj = raw as { value?: unknown; present?: unknown };
+  if (obj.present === false) return null;
+  const inner = obj.value ?? raw;
+  return typeof inner === 'string' && inner !== '' ? inner : null;
+}
+
+/**
+ * 主人 UUID 与当前玩家一致时返回 true；缺少任一身份时返回 false。
+ * 登录阶段 bot.entity.uuid 可能缺失，优先使用 bot.player.uuid，并保留实体与协议客户端来源。
+ */
+export function tamedByMe(bot: FactBot, entity: FactEntity): boolean {
+  const owner = readTamedBy(bot, entity);
+  const me = bot.player?.uuid ?? bot.entity?.uuid ?? bot._client?.uuid;
+  return owner !== null && typeof me === 'string' && me !== '' && owner === me;
+}
+
+/** TamableAnimal flags 的 0x01 位表示坐下；缺少该字段时返回 null。 */
+export function readSitting(bot: FactBot, entity: FactEntity): boolean | null {
+  const raw = metaOf(bot, entity, 'flags');
+  if (typeof raw !== 'number') return null;
+  return (raw & 0x01) !== 0;
+}
+
+/** 猪和炽足兽读取 saddle；马科读取 flags 的 0x04 位。字段不可用时返回 null。 */
+export function readSaddled(bot: FactBot, entity: FactEntity): boolean | null {
+  const direct = metaOf(bot, entity, 'saddle');
+  if (typeof direct === 'boolean') return direct;
+  if (typeof direct === 'number') return direct !== 0;
+  if (entity.name === 'horse' || entity.name === 'donkey' || entity.name === 'mule') {
+    const flags = metaOf(bot, entity, 'flags');
+    return typeof flags === 'number' ? (flags & 0x04) !== 0 : null;
+  }
+  return null;
+}
+
+/** 马科的「驯服」位:'flags' 的 0x02。不是马科或读不到返回 null。 */
+export function readHorseTamed(bot: FactBot, entity: FactEntity): boolean | null {
+  if (entity.name !== 'horse' && entity.name !== 'donkey' && entity.name !== 'mule') return null;
+  const flags = metaOf(bot, entity, 'flags');
+  return typeof flags === 'number' ? (flags & 0x02) !== 0 : null;
+}
+
+/** 羊毛元数据的低四位是颜色,第五位(0x10)是"剪过了"。 */
+const WOOL_COLORS = [
+  'white', 'orange', 'magenta', 'light_blue', 'yellow', 'lime', 'pink', 'gray',
+  'light_gray', 'cyan', 'purple', 'blue', 'brown', 'green', 'red', 'black',
+] as const;
+
+/** 染料 item 名 → 颜色名;不是染料返回 null。 */
+export function dyeColorOf(item: string | null | undefined): string | null {
+  if (!item || !item.endsWith('_dye')) return null;
+  const color = item.slice(0, -'_dye'.length);
+  return (WOOL_COLORS as readonly string[]).includes(color) ? color : null;
+}
+
+/** 这只羊现在的颜色;读不到返回 null。 */
+export function readSheepColor(bot: FactBot, entity: FactEntity): string | null {
+  const raw = metaOf(bot, entity, 'wool');
+  if (typeof raw !== 'number') return null;
+  return WOOL_COLORS[raw & 0x0f] ?? null;
+}