cortico 0.1.0

package/src/worlds/minecraft/readouts.ts

@@ -0,0 +1,102 @@
+/**
+ * 三份只读读数的渲染:背包、队列、上次没成的几条。
+ *
+ * 全是**现读现报**,一个字都不改世界、不动队列。放在这里而不是 world.ts 里,是因为
+ * 这三份的输入都是纯数据(快照 / 队列状态 / 受阻账),单测直接喂结构就能跑。
+ *
+ * 措辞与别处同一份来源:背包清单走 `narrateInventory`,队列走 `renderQueue` ——
+ * 同一件事两处措辞不同,读起来就像两件事(README「一件事只说一遍」)。
+ */
+import type { QueueStatus, BlockedRecord } from './executor.ts';
+import { renderQueue } from './executor.ts';
+import type { GearPiece, GearSlot, WorldSnapshot } from './terrain.ts';
+import { enchantSuffix, narrateInventory } from './terrain.ts';
+import { zhName } from './names.ts';
+import { PLAYER_SLOTS } from './precheck.ts';
+
+const GEAR_SLOT_ZH: Record<GearSlot, string> = {
+  head: '头', chest: '胸', legs: '腿', feet: '脚', offhand: '副手',
+};
+const WORN_ORDER: readonly GearSlot[] = ['head', 'chest', 'legs', 'feet'];
+
+function gearPhrase(p: GearPiece): string {
+  const dura = p.durability ? ` ${p.durability.left}/${p.durability.max}` : '';
+  return `${GEAR_SLOT_ZH[p.slot]}${zhName(p.name)}${enchantSuffix(p.enchantments)}${dura}`;
+}
+
+/**
+ * 背包快照包括槽位占用、物品总量、手持和装备。
+ * 首次服务端同步前报告未同步，避免将初始空视图当成空背包。
+ */
+export function renderBagReadout(s: WorldSnapshot): string {
+  if (!s.invSynced) return '[背包] 物品栏还在从服务器同步,这份清单还没到。';
+  const used = s.inventory.length;
+  const held = s.heldItem ? `手里拿着${zhName(s.heldItem)}` : '手里空着';
+  const worn = WORN_ORDER
+    .map((slot) => s.equipment.find((p) => p.slot === slot))
+    .filter((p): p is GearPiece => p !== undefined);
+  const off = s.equipment.find((p) => p.slot === 'offhand');
+  const lines = [
+    `[背包] ${used}/${PLAYER_SLOTS} 格占着,空 ${PLAYER_SLOTS - used} 格。`,
+    used > 0 ? `包里:${narrateInventory(s.inventory)}。` : '包里什么都没有。',
+    `${held}。`,
+    worn.length > 0 ? `穿着:${worn.map(gearPhrase).join('、')}。` : '身上没穿护甲。',
+  ];
+  if (off) lines.push(`${gearPhrase(off)}。`);
+  return lines.join('\n');
+}
+
+/** 背包读数的指纹:一轮一答闸按它判「这一份读数变没变」(见 round.ts) */
+export function bagStamp(s: WorldSnapshot | null): string {
+  if (!s) return 'nobot';
+  if (!s.invSynced) return 'nosync';
+  return [
+    s.inventory.length,
+    [...s.inventory].map((i) => `${i.name}${enchantSuffix(i.enchantments)}×${i.count}`).sort().join(','),
+    s.heldItem ?? 'bare',
+    [...s.equipment].map((p) => `${p.slot}:${p.name}`).sort().join(','),
+  ].join('|');
+}
+
+/**
+ * 队列现状:在做的那件与它跑到第几步、排队的、最近一单的终态。
+ *
+ * 最近一单的终态是这份读数里唯一"过去时"的东西 —— 它正是「我刚才那一单到底怎么了」
+ * 这个问题的答案,而那条终态回执早被交接或后续事件挤出上下文了。
+ */
+export function renderQueueReadout(
+  q: QueueStatus,
+  last: { at: string; kind: string; text: string } | null,
+): string {
+  const lines = [`[队列] ${renderQueue(q)}`];
+  lines.push(last ? `[最近一单] ${last.at} ${last.text}` : '[最近一单] 这一场还没有跑完过任何一单。');
+  return lines.join('\n');
+}
+
+/** 队列读数的指纹。**不含时钟** —— 已跑多少秒每次都在变,进了指纹这道闸等于不存在 */
+export function queueStamp(q: QueueStatus, lastAt: number | null): string {
+  const r = q.running;
+  return [
+    r ? `${r.id}:${r.stepIndex}/${r.stepCount}:${r.count ? `${r.count.done}/${r.count.total}` : '-'}` : 'idle',
+    q.waiting.map((w) => w.id).join(','),
+    q.hold ?? '-',
+    lastAt ?? '-',
+  ].join('|');
+}
+
+/**
+ * 最近几条没做成的记录:时刻、任务、步、原文原因。
+ *
+ * 只搬账本上已有的字,一个字不改写、不归因、不给建议(worlds-report-facts)。
+ * 「同一类撞了几次」那件事另有头条在终态回执里报,这里不重复。
+ */
+export function renderBlockedReadout(records: readonly BlockedRecord[], clock: (ms: number) => string): string {
+  if (records.length === 0) return '[上次没成] 这一场还没有记到受阻的步。';
+  const lines = records.map((r) => `${clock(r.at)} ${r.task}${r.step ? ` ${r.step}` : ''}:${r.why}`);
+  return `[上次没成] 最近 ${records.length} 条(新的在前):\n${lines.join('\n')}`;
+}
+
+/** 受阻读数的指纹:最新那一条的时刻 + 条数,两者都没动就是同一份读数 */
+export function blockedStamp(records: readonly BlockedRecord[]): string {
+  return `${records.length}|${records[0]?.at ?? '-'}`;
+}

package/src/worlds/minecraft/round.ts

@@ -0,0 +1,26 @@
+/**
+ * 同一轮、同一工具且读数指纹相同的重复查询返回简短回执；状态变化时重新完整回答。
+ * 指纹排除时钟字段，避免经过时间造成虚假的状态变化。
+ * 主循环的 round 经代理 IPC 原样传入子进程的 ctx.round；缺少轮号时每次正常回答。
+ */
+import type { ToolCallContext } from '../../core/types.ts';
+
+export function roundTokenOf(ctx: ToolCallContext | undefined): number | null {
+  if (!ctx) return null;
+  if (typeof ctx.round === 'number') return ctx.round;
+  return null;
+}
+
+export const REPEATED_QUERY_RECEIPT = '这轮已经答过了,答案不会变,先看上一条。';
+
+export class RoundOnceGate {
+  private readonly last = new Map<string, { round: number; stamp: string }>();
+
+  answered(tool: string, round: number | null, stamp: string): boolean {
+    if (round === null) return true;
+    const prev = this.last.get(tool);
+    if (prev && prev.round === round && prev.stamp === stamp) return false;
+    this.last.set(tool, { round, stamp });
+    return true;
+  }
+}

package/src/worlds/minecraft/search-observation.ts

@@ -0,0 +1,92 @@
+export type FindKind = 'block' | 'entity';
+
+export interface SearchScope {
+  connectionGeneration: number;
+  realm: string;
+  dimension: string;
+}
+
+interface ObservedFindHit {
+  kind: FindKind;
+  target: string;
+  what: string;
+  at: [number, number, number];
+  observedAt: number;
+}
+
+interface AgedFindHit extends ObservedFindHit {
+  ageMs: number;
+}
+
+const HISTORY_TTL_MS = 15 * 60_000;
+const HISTORY_LIMIT = 128;
+
+function canonicalFindTarget(target: string): string {
+  return target.trim().toLowerCase().replace(/^minecraft:/, '');
+}
+
+function scopeKey(scope: SearchScope): string {
+  return `${scope.connectionGeneration}\0${scope.realm}\0${scope.dimension}`;
+}
+
+function observationKey(scope: SearchScope, target: string, kind: FindKind): string {
+  return `${scopeKey(scope)}\0${kind}\0${canonicalFindTarget(target)}`;
+}
+
+/** Recent sightings are process-local evidence and never survive a connection or dimension boundary. */
+export class FindObservationCache {
+  private entries = new Map<string, ObservedFindHit>();
+  private activeScope: string | null = null;
+
+  constructor(
+    private readonly ttlMs = HISTORY_TTL_MS,
+    private readonly limit = HISTORY_LIMIT,
+  ) {}
+
+  sync(scope: SearchScope): void {
+    const next = scopeKey(scope);
+    if (this.activeScope !== null && this.activeScope !== next) this.entries.clear();
+    this.activeScope = next;
+  }
+
+  remember(
+    scope: SearchScope,
+    hit: Omit<ObservedFindHit, 'observedAt' | 'target'> & { target: string; observedAt?: number },
+  ): void {
+    this.sync(scope);
+    const observedAt = hit.observedAt ?? Date.now();
+    this.purge(observedAt);
+    const key = observationKey(scope, hit.target, hit.kind);
+    this.entries.delete(key);
+    this.entries.set(key, { ...hit, target: canonicalFindTarget(hit.target), observedAt });
+    while (this.entries.size > this.limit) this.entries.delete(this.entries.keys().next().value!);
+  }
+
+  recall(
+    scope: SearchScope,
+    target: string,
+    kind: FindKind,
+    now = Date.now(),
+  ): AgedFindHit | null {
+    this.sync(scope);
+    this.purge(now);
+    const key = observationKey(scope, target, kind);
+    const hit = this.entries.get(key);
+    if (!hit) return null;
+    this.entries.delete(key);
+    this.entries.set(key, hit);
+    return { ...hit, ageMs: Math.max(0, now - hit.observedAt) };
+  }
+
+  clear(): void {
+    this.entries.clear();
+    this.activeScope = null;
+  }
+
+  private purge(now: number): void {
+    for (const [key, hit] of this.entries) {
+      if (now - hit.observedAt > this.ttlMs) this.entries.delete(key);
+    }
+  }
+}
+

package/src/worlds/minecraft/server-config.ts

@@ -0,0 +1,467 @@
+/** 读取和写入 server.properties，列出存档及其 level.dat 元数据。生成参数仅用于生成区块，不重新生成已有区块。 */
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync, type Dirent } from 'node:fs';
+import { join } from 'node:path';
+import { readLevelDat, type LevelDatInfo } from './level-dat.ts';
+import { offlineUuid } from './client-launch.ts';
+
+export const GAMEMODES = ['survival', 'creative', 'adventure', 'spectator'] as const;
+export const DIFFICULTIES = ['peaceful', 'easy', 'normal', 'hard'] as const;
+const LEVEL_TYPES = [
+  'minecraft:normal',
+  'minecraft:flat',
+  'minecraft:large_biomes',
+  'minecraft:amplified',
+  'minecraft:single_biome_surface',
+] as const;
+
+type Gamemode = (typeof GAMEMODES)[number];
+export type Difficulty = (typeof DIFFICULTIES)[number];
+export type LevelType = (typeof LEVEL_TYPES)[number];
+
+export const LEVEL_TYPE_LABELS: ReadonlyArray<{ value: LevelType; label: string; note: string }> = [
+  { value: 'minecraft:normal', label: '默认', note: '原版地形' },
+  { value: 'minecraft:flat', label: '超平坦', note: '按生成器细则逐层铺;不填就是原版那三层' },
+  { value: 'minecraft:large_biomes', label: '大型生物群系', note: '同样的地形,群系尺度放大' },
+  { value: 'minecraft:amplified', label: '放大化', note: '极端高山地形,吃性能' },
+  {
+    value: 'minecraft:single_biome_surface',
+    label: '单一生物群系',
+    note: '整个世界一个群系,群系名写在生成器细则里({"biome":"minecraft:desert"})',
+  },
+];
+
+export function levelTypeLabel(type: LevelType): string {
+  return LEVEL_TYPE_LABELS.find((t) => t.value === type)?.label ?? type;
+}
+
+/** 超平坦预设的方块层和结构参数。 */
+export const FLAT_PRESETS: ReadonlyArray<{ id: string; label: string; note: string; json: string }> = [
+  {
+    id: 'classic',
+    label: '经典平坦',
+    note: '基岩 + 2 层泥土 + 草方块,平原群系',
+    json: '{"layers":[{"block":"minecraft:bedrock","height":1},{"block":"minecraft:dirt","height":2},'
+      + '{"block":"minecraft:grass_block","height":1}],"biome":"minecraft:plains"}',
+  },
+  {
+    id: 'void',
+    label: '虚空',
+    note: '只有一层空气,出生点一小块平台',
+    json: '{"layers":[{"block":"minecraft:air","height":1}],"biome":"minecraft:the_void"}',
+  },
+  {
+    id: 'tunnelers',
+    label: '隧道世界',
+    note: '基岩 + 230 层石头,整个世界都是可挖的岩层',
+    json: '{"layers":[{"block":"minecraft:bedrock","height":1},{"block":"minecraft:stone","height":230}],'
+      + '"biome":"minecraft:windswept_hills"}',
+  },
+  {
+    id: 'minable',
+    label: '可挖平坦',
+    note: '基岩 + 59 层石头 + 泥土草皮:地表是平的,底下有矿脉',
+    json: '{"layers":[{"block":"minecraft:bedrock","height":1},{"block":"minecraft:stone","height":59},'
+      + '{"block":"minecraft:dirt","height":3},{"block":"minecraft:grass_block","height":1}],'
+      + '"biome":"minecraft:plains"}',
+  },
+];
+
+export interface GameSettings {
+  gamemode: Gamemode;
+  difficulty: Difficulty;
+  hardcore: boolean;
+  pvp: boolean;
+  spawnMonsters: boolean;
+  levelSeed: string;
+  /** 当前存档目录名 */
+  levelName: string;
+  levelType: LevelType;
+  /** 生成器细则(超平坦层配方 / 单群系名);空 = 该类型的默认 */
+  generatorSettings: string;
+  /** 村庄、神殿、要塞这些结构 */
+  generateStructures: boolean;
+  allowNether: boolean;
+  /** 出生点保护半径(格);0 = 不保护 */
+  spawnProtection: number;
+  viewDistance: number;
+  simulationDistance: number;
+  /** 世界边界半径(格) */
+  maxWorldSize: number;
+}
+
+export interface WorldInfo {
+  name: string;
+  generated: boolean;
+  modified: string | null;
+  sizeBytes: number;
+  /** 已生成的附属维度:nether / the_end */
+  dimensions: string[];
+  info: LevelDatInfo | null;
+}
+
+/** 一行 properties:注释与空行原样留着 */
+type Line = { kind: 'raw'; text: string } | { kind: 'pair'; key: string; value: string };
+
+export function parseProperties(text: string): Line[] {
+  return text.split(/\r?\n/).map((line) => {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#') || trimmed.startsWith('!')) return { kind: 'raw', text: line };
+    const eq = line.indexOf('=');
+    if (eq < 0) return { kind: 'raw', text: line };
+    return { kind: 'pair', key: line.slice(0, eq).trim(), value: line.slice(eq + 1) };
+  });
+}
+
+export function stringifyProperties(lines: Line[]): string {
+  return lines.map((l) => (l.kind === 'raw' ? l.text : `${l.key}=${l.value}`)).join('\n');
+}
+
+export function readProperty(lines: Line[], key: string): string | null {
+  for (const l of lines) if (l.kind === 'pair' && l.key === key) return l.value;
+  return null;
+}
+
+/** 就地改;没有这个键就追加在末尾 */
+export function writeProperty(lines: Line[], key: string, value: string): Line[] {
+  const escaped = value.replace(/\\/g, '\\\\').replace(/[\r\n]/g, ' ');
+  let hit = false;
+  const out = lines.map((l) => {
+    if (l.kind === 'pair' && l.key === key) { hit = true; return { kind: 'pair' as const, key, value: escaped }; }
+    return l;
+  });
+  if (!hit) out.push({ kind: 'pair', key, value: escaped });
+  return out;
+}
+
+function pickEnum<T extends string>(raw: string | null, allowed: readonly T[], fallback: T): T {
+  const v = (raw ?? '').trim().toLowerCase();
+  return (allowed as readonly string[]).includes(v) ? (v as T) : fallback;
+}
+
+function pickBool(raw: string | null, fallback: boolean): boolean {
+  const v = (raw ?? '').trim().toLowerCase();
+  if (v === 'true') return true;
+  if (v === 'false') return false;
+  return fallback;
+}
+
+function pickInt(raw: string | null, fallback: number, lo: number, hi: number): number {
+  const n = Number.parseInt((raw ?? '').trim(), 10);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.min(hi, Math.max(lo, n));
+}
+
+/** 1.19 之前 level-type 是不带命名空间的短名(flat / largeBiomes);两种写法都收 */
+function pickLevelType(raw: string | null): LevelType {
+  const v = (raw ?? '').trim();
+  const short = v.includes(':') ? v.slice(v.indexOf(':') + 1) : v;
+  const id = `minecraft:${short.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase()}`;
+  const legacy: Record<string, LevelType> = { 'minecraft:default': 'minecraft:normal' };
+  const resolved = legacy[id] ?? id;
+  return (LEVEL_TYPES as readonly string[]).includes(resolved) ? (resolved as LevelType) : 'minecraft:normal';
+}
+
+export function settingsFrom(lines: Line[]): GameSettings {
+  return {
+    gamemode: pickEnum(readProperty(lines, 'gamemode'), GAMEMODES, 'survival'),
+    difficulty: pickEnum(readProperty(lines, 'difficulty'), DIFFICULTIES, 'easy'),
+    hardcore: pickBool(readProperty(lines, 'hardcore'), false),
+    pvp: pickBool(readProperty(lines, 'pvp'), true),
+    spawnMonsters: pickBool(readProperty(lines, 'spawn-monsters'), true),
+    levelSeed: (readProperty(lines, 'level-seed') ?? '').trim(),
+    levelName: (readProperty(lines, 'level-name') ?? 'world').trim() || 'world',
+    levelType: pickLevelType(readProperty(lines, 'level-type')),
+    generatorSettings: (readProperty(lines, 'generator-settings') ?? '').trim(),
+    generateStructures: pickBool(readProperty(lines, 'generate-structures'), true),
+    allowNether: pickBool(readProperty(lines, 'allow-nether'), true),
+    spawnProtection: pickInt(readProperty(lines, 'spawn-protection'), 16, 0, 512),
+    viewDistance: pickInt(readProperty(lines, 'view-distance'), 10, 2, 32),
+    simulationDistance: pickInt(readProperty(lines, 'simulation-distance'), 10, 2, 32),
+    maxWorldSize: pickInt(readProperty(lines, 'max-world-size'), 29_999_984, 1, 29_999_984),
+  };
+}
+
+export function applySettings(lines: Line[], patch: Partial<GameSettings>): Line[] {
+  let out = lines;
+  const set = (key: string, value: string | number | boolean | undefined): void => {
+    if (value !== undefined) out = writeProperty(out, key, String(value));
+  };
+  set('gamemode', patch.gamemode);
+  set('difficulty', patch.difficulty);
+  set('hardcore', patch.hardcore);
+  set('pvp', patch.pvp);
+  set('spawn-monsters', patch.spawnMonsters);
+  set('level-seed', patch.levelSeed);
+  set('level-name', patch.levelName);
+  set('level-type', patch.levelType);
+  set('generator-settings', patch.generatorSettings);
+  set('generate-structures', patch.generateStructures);
+  set('allow-nether', patch.allowNether);
+  set('spawn-protection', patch.spawnProtection);
+  set('view-distance', patch.viewDistance);
+  set('simulation-distance', patch.simulationDistance);
+  set('max-world-size', patch.maxWorldSize);
+  return out;
+}
+
+/** 存档名用作目录名;拒绝路径分隔符、相对路径和 Windows 保留名称。 */
+export function validWorldName(name: string): string | null {
+  const n = name.trim();
+  if (!n) return '存档名不能为空';
+  if (n.length > 64) return '存档名太长(最多 64 字)';
+  if (/[\\/:*?"<>|]/.test(n)) return '存档名里不能有 \\ / : * ? " < > |';
+  if (n === '.' || n === '..') return '这个名字不能用';
+  return null;
+}
+
+export function validGeneratorSettings(text: string): string | null {
+  const t = text.trim();
+  if (!t) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(t);
+  } catch (err) {
+    return `生成器细则不是合法 JSON: ${(err as Error).message}`;
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    return '生成器细则要是一个 JSON 对象(如 {"layers":[…],"biome":"…"})';
+  }
+  return null;
+}
+
+/** Paper/Bukkit 把下界与末地拆成独立目录,它们不是可选的存档 */
+const DIMENSION_SUFFIX = /_(nether|the_end)$/;
+
+const sizeCache = new Map<string, { stamp: number; size: number }>();
+
+function dirSize(dir: string, budget: { left: number }): number {
+  let total = 0;
+  let entries: Dirent[];
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return 0;
+  }
+  for (const entry of entries) {
+    if (budget.left-- <= 0) return total;
+    const abs = join(dir, entry.name);
+    if (entry.isDirectory()) total += dirSize(abs, budget);
+    else {
+      try { total += statSync(abs).size; } catch {  }
+    }
+  }
+  return total;
+}
+
+function worldSize(serverDir: string, name: string, stamp: number): number {
+  const key = join(serverDir, name);
+  const hit = sizeCache.get(key);
+  if (hit && hit.stamp === stamp) return hit.size;
+  const budget = { left: 200_000 };
+  let size = dirSize(key, budget);
+  for (const suffix of ['_nether', '_the_end']) {
+    const dim = join(serverDir, `${name}${suffix}`);
+    if (existsSync(dim)) size += dirSize(dim, budget);
+  }
+  sizeCache.set(key, { stamp, size });
+  return size;
+}
+
+/** serverDir 下的存档目录:有 level.dat 的算已生成,最近活跃的排在前面 */
+export function listWorlds(serverDir: string, current: string): WorldInfo[] {
+  const found = new Map<string, WorldInfo>();
+  if (serverDir && existsSync(serverDir)) {
+    const names = new Set<string>();
+    for (const entry of readdirSync(serverDir, { withFileTypes: true })) {
+      if (entry.isDirectory()) names.add(entry.name);
+    }
+    for (const name of names) {
+      if (DIMENSION_SUFFIX.test(name)) continue;
+      const dat = join(serverDir, name, 'level.dat');
+      if (!existsSync(dat)) continue;
+      const mtime = statSync(dat).mtimeMs;
+      const info = readLevelDat(dat);
+      found.set(name, {
+        name,
+        generated: true,
+        /** 优先使用 LastPlayed；缺失时使用 level.dat 的修改时间。 */
+        modified: new Date(info?.lastPlayed || mtime).toISOString(),
+        sizeBytes: worldSize(serverDir, name, mtime),
+        dimensions: ['nether', 'the_end'].filter((d) => names.has(`${name}_${d}`)),
+        info,
+      });
+    }
+  }
+  if (current && !found.has(current)) {
+    found.set(current, {
+      name: current, generated: false, modified: null, sizeBytes: 0, dimensions: [], info: null,
+    });
+  }
+  return [...found.values()].sort((a, b) => {
+    const at = a.modified ? Date.parse(a.modified) : -1;
+    const bt = b.modified ? Date.parse(b.modified) : -1;
+    return bt - at || a.name.localeCompare(b.name);
+  });
+}
+
+function propertiesPath(serverDir: string): string {
+  return join(serverDir, 'server.properties');
+}
+
+export function loadProperties(serverDir: string): Line[] {
+  const file = propertiesPath(serverDir);
+  return existsSync(file) ? parseProperties(readFileSync(file, 'utf8')) : [];
+}
+
+export function saveProperties(serverDir: string, lines: Line[]): void {
+  writeFileSync(propertiesPath(serverDir), stringifyProperties(lines), 'utf8');
+}
+
+/** 存档身份决定目标、路标和施工绑定所属的 realm。 */
+export interface WorldIdentity {
+  key: string;
+  local: boolean;
+}
+
+export function worldIdentityOf(serverDir: string, address: string): WorldIdentity {
+  if (serverDir && existsSync(serverDir)) {
+    try {
+      const name = settingsFrom(loadProperties(serverDir)).levelName;
+      if (name) return { key: name, local: true };
+    } catch { /* 配置缺损:退回地址 */ }
+  }
+  return { key: address, local: false };
+}
+
+/** 环境提示词中的存档或服务器身份。 */
+export function worldEnvLine(world: WorldIdentity): string {
+  return world.local ? `当前存档:「${world.key}」` : `当前服务器:${world.key}`;
+}
+
+// ---------------------------------------------------------------------------
+// 权限与作弊:ops.json 与那几项决定"谁能下命令"的 properties
+// ---------------------------------------------------------------------------
+
+/** 写入 ops.json 中的操作员权限；运行中另发送 op/deop 指令。 */
+export interface AccessSettings {
+  opPermissionLevel: number;
+  /** 命令方块能不能用 */
+  enableCommandBlock: boolean;
+  /** 创造/旁观之外的飞行不被踢 */
+  allowFlight: boolean;
+  /** online-mode=true 时服务器会验证账户，离线账户无法通过验证。 */
+  onlineMode: boolean;
+  /** 开启白名单时，账户还需列入白名单。 */
+  whiteList: boolean;
+}
+
+export function accessFrom(lines: Line[]): AccessSettings {
+  return {
+    opPermissionLevel: pickInt(readProperty(lines, 'op-permission-level'), 4, 1, 4),
+    enableCommandBlock: pickBool(readProperty(lines, 'enable-command-block'), false),
+    allowFlight: pickBool(readProperty(lines, 'allow-flight'), false),
+    onlineMode: pickBool(readProperty(lines, 'online-mode'), true),
+    whiteList: pickBool(readProperty(lines, 'white-list'), false),
+  };
+}
+
+export function applyAccess(lines: Line[], patch: Partial<AccessSettings>): Line[] {
+  let out = lines;
+  const set = (key: string, value: string | number | boolean | undefined): void => {
+    if (value !== undefined) out = writeProperty(out, key, String(value));
+  };
+  set('op-permission-level', patch.opPermissionLevel);
+  set('enable-command-block', patch.enableCommandBlock);
+  set('allow-flight', patch.allowFlight);
+  set('online-mode', patch.onlineMode);
+  set('white-list', patch.whiteList);
+  return out;
+}
+
+interface OpEntry {
+  uuid: string;
+  name: string;
+  level: number;
+  bypassesPlayerLimit: boolean;
+}
+
+function opsPath(serverDir: string): string {
+  return join(serverDir, 'ops.json');
+}
+
+export function readOps(serverDir: string): OpEntry[] {
+  const file = opsPath(serverDir);
+  if (!serverDir || !existsSync(file)) return [];
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(file, 'utf8'));
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter((e): e is OpEntry => typeof e === 'object' && e !== null && 'name' in e);
+  } catch {
+    return [];
+  }
+}
+
+export function writeOps(serverDir: string, ops: OpEntry[]): void {
+  writeFileSync(opsPath(serverDir), `${JSON.stringify(ops, null, 2)}\n`, 'utf8');
+}
+
+/** 优先采用 usercache.json 中的 UUID；缺失时按区分大小写的账户名计算离线 UUID。 */
+export function resolveUuid(serverDir: string, name: string): string {
+  const file = join(serverDir, 'usercache.json');
+  if (serverDir && existsSync(file)) {
+    try {
+      const parsed: unknown = JSON.parse(readFileSync(file, 'utf8'));
+      if (Array.isArray(parsed)) {
+        const hit = parsed.find(
+          (e) => typeof e === 'object' && e !== null && (e as { name?: unknown }).name === name,
+        ) as { uuid?: unknown } | undefined;
+        if (typeof hit?.uuid === 'string') return hit.uuid;
+      }
+    } catch {
+      /* 缓存读坏了就算离线 UUID */
+    }
+  }
+  return offlineUuid(name);
+}
+
+/** 名单里已有这个名字的那条(按 uuid 或原样的名字认) */
+function findOp(ops: OpEntry[], name: string, uuid: string): OpEntry | undefined {
+  return ops.find((e) => e.uuid === uuid || e.name === name);
+}
+
+export function isOp(ops: OpEntry[], serverDir: string, name: string): OpEntry | undefined {
+  return findOp(ops, name, resolveUuid(serverDir, name));
+}
+
+export function grantOp(
+  ops: OpEntry[], serverDir: string, name: string, level = 4,
+): { ops: OpEntry[]; changed: boolean } {
+  const uuid = resolveUuid(serverDir, name);
+  const hit = findOp(ops, name, uuid);
+  if (hit) {
+    if (hit.level >= level) return { ops, changed: false };
+    return { ops: ops.map((e) => (e === hit ? { ...e, level } : e)), changed: true };
+  }
+  return { ops: [...ops, { uuid, name, level, bypassesPlayerLimit: false }], changed: true };
+}
+
+export function revokeOp(ops: OpEntry[], serverDir: string, name: string): { ops: OpEntry[]; changed: boolean } {
+  const uuid = resolveUuid(serverDir, name);
+  const rest = ops.filter((e) => e.uuid !== uuid && e.name !== name);
+  return { ops: rest, changed: rest.length !== ops.length };
+}
+
+/** 仅在服务器停止时直接修改这些文件。 */
+export function ensureOps(serverDir: string, names: readonly string[], level = 4): string[] {
+  if (!serverDir || !existsSync(serverDir)) return [];
+  let ops = readOps(serverDir);
+  const added: string[] = [];
+  for (const name of names) {
+    if (!name.trim()) continue;
+    const next = grantOp(ops, serverDir, name, level);
+    if (next.changed) added.push(name);
+    ops = next.ops;
+  }
+  if (added.length) writeOps(serverDir, ops);
+  return added;
+}