yeow-api 0.2.115 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "yeow-api",
-    "version": "0.2.115",
+    "version": "0.3.0",
     "description": "Yeow API",
     "type": "module",
     "main": "./src/index.ts",

package/src/block.ts

@@ -3,6 +3,11 @@ import type { TaskOptions } from './task.js';
 import { Location } from './location.js';
 import type { ItemStack } from './item.js';
 import { Material } from './material.js';
+import { Inventory } from './inventory.js';
+import {
+  getBlock as pdcGet, setBlock as pdcSet, hasBlock as pdcHas, removeBlock as pdcRemove,
+  keysBlock as pdcKeys, getAllBlock as pdcGetAll,
+} from './pdc.js';
 
 /** 方块状态（Minecraft 原版键值对枚举，值统一为字符串）。 */
 export interface BlockState {
@@ -81,4 +86,54 @@ export class Block {
     if (tool) p.item = tool;
     return call<boolean>('block.breakNaturally', p, options);
   }
+
+  // ── PDC（方块持久数据；需要 location） ──
+
+  private requirePos(): { world: string; x: number; y: number; z: number } {
+    const pos = this.pos;
+    if (!pos) throw new Error('block has no location (create with world.getBlock)');
+    return pos;
+  }
+
+  /** 容器方块的内容物（Chest / Furnace / Hopper / Barrel 等 Container；需要 location；非容器方块抛错）。 */
+  getInventory(): Inventory {
+    const { world, x, y, z } = this.requirePos();
+    return Inventory.ofBlock(world, x, y, z);
+  }
+
+  /** 读取并 JSON 反序列化（无值返回 null；旧数据非 JSON 时原样返回字符串）。 */
+  getPdc<T = unknown>(key: string, options?: TaskOptions): Promise<T | null> {
+    const { world, x, y, z } = this.requirePos();
+    return pdcGet(world, x, y, z, key, options);
+  }
+
+  /** 任意可 JSON 序列化的值自动序列化后写入。 */
+  setPdc(key: string, value: unknown, options?: TaskOptions): Promise<boolean> {
+    const { world, x, y, z } = this.requirePos();
+    return pdcSet(world, x, y, z, key, value, options);
+  }
+
+  /** 键是否存在。 */
+  hasPdc(key: string, options?: TaskOptions): Promise<boolean> {
+    const { world, x, y, z } = this.requirePos();
+    return pdcHas(world, x, y, z, key, options);
+  }
+
+  /** 移除键。 */
+  removePdc(key: string, options?: TaskOptions): Promise<boolean> {
+    const { world, x, y, z } = this.requirePos();
+    return pdcRemove(world, x, y, z, key, options);
+  }
+
+  /** 全部键（完整 key 格式，含命名空间）。 */
+  keysPdc(options?: TaskOptions): Promise<string[]> {
+    const { world, x, y, z } = this.requirePos();
+    return pdcKeys(world, x, y, z, options);
+  }
+
+  /** 全量读取本插件命名空间的键值（每个值 JSON 反序列化）。 */
+  getAllPdc(options?: TaskOptions): Promise<Record<string, unknown>> {
+    const { world, x, y, z } = this.requirePos();
+    return pdcGetAll(world, x, y, z, options);
+  }
 }

package/src/command.ts

@@ -8,11 +8,6 @@ import { permissionPayload } from './permission.js';
 /** 命令发送者：玩家为真正的 `Player` 对象（异步 `sendMessage` 等全部方法）；控制台为字符串 `'CONSOLE'`。 */
 export type CommandSender = Player | 'CONSOLE';
 
-/** 判断发送者是否为玩家（非 'CONSOLE' 即玩家）。 */
-export function isPlayer(sender: CommandSender): sender is Player {
-  return sender !== 'CONSOLE';
-}
-
 export interface CommandPayload {
   readonly sender: CommandSender;
   readonly args: string[];
@@ -84,11 +79,23 @@ export function registerCommand(name: string, options: CommandOptions, taskOptio
         } else {
           const result = completerFn(sender, data.args);
           if (result && typeof result.then === 'function') {
-            $send('task', {
-              type: 'command.tabComplete',
-              params: { callbackId: compCbId, completions: [] },
-              cb: '',
-            });
+            // 异步 completer：await 结果后再回传（原实现立即发空补全、Promise 结果被丢弃）
+            (result as Promise<string[]>).then(
+              (list) => {
+                $send('task', {
+                  type: 'command.tabComplete',
+                  params: { callbackId: compCbId, completions: list || [] },
+                  cb: '',
+                });
+              },
+              () => {
+                $send('task', {
+                  type: 'command.tabComplete',
+                  params: { callbackId: compCbId, completions: [] },
+                  cb: '',
+                });
+              },
+            );
           } else {
             $send('task', {
               type: 'command.tabComplete',

package/src/core.ts

@@ -1,11 +1,14 @@
 /// <reference path="global.d.ts" />
+/// <reference path="yeow-dev.d.ts" />
 
-export { call } from './task.js';
+export { call, callBatch, postBatch } from './task.js';
+export type { BatchTask } from './task.js';
 export { Location } from './location.js';
 export { Player } from './player.js';
 export { World } from './world.js';
 export { Chunk, ChunkSnapshot, ChunkTopSnapshot } from './chunk.js';
 export type { ChunkData } from './chunk.js';
+export type { WorldBorderInfo } from './world.js';
 export { Entity, LivingEntity } from './entity.js';
 export type { BoundingBox } from './entity.js';
 export { Block } from './block.js';
@@ -54,15 +57,18 @@ export { path } from './path.js';
 export { listen, respond, close, request, requestSync } from './http.js';
 export type { RespondOptions } from './http.js';
 export { logError } from './log-error.js';
-export { InstanceId, GUIHandle, BossBarHandle, InventoryHandle } from './instance-id.js';
-export type { ItemStack } from './item.js';
+export { InstanceId, BossBarHandle, InventoryHandle } from './instance-id.js';
+export { ItemStack } from './item.js';
+export type { ItemMeta, PotionEffectData, AttributeModifierData } from './item.js';
 export type { PotionEffect } from './potion.js';
 export { addPotionEffect, removePotionEffect, clearPotionEffects, getActivePotionEffects } from './potion.js';
 export { playSound, stopSound, stopAllSounds } from './sound.js';
 export type { ParticleOptions } from './particle.js';
 export { spawnParticle } from './particle.js';
-export { get as pdcGet, set as pdcSet, has as pdcHas, remove as pdcRemove, keys as pdcKeys,
-    getBlock as pdcGetBlock, setBlock as pdcSetBlock, hasBlock as pdcHasBlock, removeBlock as pdcRemoveBlock } from './pdc.js';
+export { get as pdcGet, set as pdcSet, has as pdcHas, remove as pdcRemove, keys as pdcKeys, getAll as pdcGetAll,
+    getRaw as pdcGetRaw, setRaw as pdcSetRaw, getAllRaw as pdcGetAllRaw,
+    getBlock as pdcGetBlock, setBlock as pdcSetBlock, hasBlock as pdcHasBlock, removeBlock as pdcRemoveBlock,
+    keysBlock as pdcKeysBlock, getAllBlock as pdcGetAllBlock, getBlockRaw as pdcGetBlockRaw, setBlockRaw as pdcSetBlockRaw, getAllBlockRaw as pdcGetAllBlockRaw } from './pdc.js';
 export { createBossBar, destroy as destroyBossBar,
     setTitle as setBossBarTitle, setProgress as setBossBarProgress,
     setColor as setBossBarColor, setStyle as setBossBarStyle,
@@ -70,8 +76,6 @@ export { createBossBar, destroy as destroyBossBar,
     removePlayer as removeBossBarPlayer, removeAll as removeAllBossBarPlayers,
     addFlag as addBossBarFlag, removeFlag as removeBossBarFlag } from './bossbar.js';
 export type { BossBarOptions } from './bossbar.js';
-export { createGUI, destroy as destroyGUI, open as openGUI,
-    close as closeGUI, setItem as setGUIItem, fill as fillGUI, clear as clearGUI } from './gui.js';
 export type { AdvancementProgress } from './advancement.js';
 export { grant as grantAdvancement, revoke as revokeAdvancement,
     getProgress as getAdvancementProgress, awardCriteria, revokeCriteria } from './advancement.js';

package/src/entity.ts

@@ -86,6 +86,30 @@ export class Entity {
   removeSync(options?: TaskOptions): void { call('entity.remove', { uuid: this.uuid }, options); }
   teleport(loc: Location, options?: TaskOptions): Promise<void> { return post('entity.teleport', { uuid: this.uuid, ...loc.toObject() }, options); }
   teleportSync(loc: Location, options?: TaskOptions): void { call('entity.teleport', { uuid: this.uuid, ...loc.toObject() }, options); }
+
+  // ── 基础补齐（2026-08-13） ──
+
+  /** 速度向量 { x, y, z }（方块/秒）。 */
+  get velocity(): { x: number; y: number; z: number } { return call<{ x: number; y: number; z: number }>('entity.getVelocity', { uuid: this.uuid }); }
+  set velocity(v: { x: number; y: number; z: number }) { call('entity.setVelocity', { uuid: this.uuid, x: v.x, y: v.y, z: v.z }); }
+  getVelocity(options?: TaskOptions): Promise<{ x: number; y: number; z: number }> { return post('entity.getVelocity', { uuid: this.uuid }, options); }
+  setVelocity(v: { x: number; y: number; z: number }, options?: TaskOptions): Promise<void> { return post('entity.setVelocity', { uuid: this.uuid, x: v.x, y: v.y, z: v.z }, options); }
+
+  /** 着火刻数（0 = 未着火）。 */
+  get fireTicks(): number { return call<number>('entity.getFireTicks', { uuid: this.uuid }); }
+  set fireTicks(v: number) { call('entity.setFireTicks', { uuid: this.uuid, value: v }); }
+  getFireTicks(options?: TaskOptions): Promise<number> { return post<number>('entity.getFireTicks', { uuid: this.uuid }, options); }
+  setFireTicks(v: number, options?: TaskOptions): Promise<void> { return post('entity.setFireTicks', { uuid: this.uuid, value: v }, options); }
+
+  /** 已存活刻数。 */
+  get ticksLived(): number { return call<number>('entity.getTicksLived', { uuid: this.uuid }); }
+  set ticksLived(v: number) { call('entity.setTicksLived', { uuid: this.uuid, value: v }); }
+  getTicksLived(options?: TaskOptions): Promise<number> { return post<number>('entity.getTicksLived', { uuid: this.uuid }, options); }
+  setTicksLived(v: number, options?: TaskOptions): Promise<void> { return post('entity.setTicksLived', { uuid: this.uuid, value: v }, options); }
+
+  /** 是否在地面上。 */
+  get isOnGround(): boolean { return call<boolean>('entity.isOnGround', { uuid: this.uuid }); }
+  isOnGroundAsync(options?: TaskOptions): Promise<boolean> { return post<boolean>('entity.isOnGround', { uuid: this.uuid }, options); }
 }
 
 export class LivingEntity extends Entity {
@@ -99,4 +123,23 @@ export class LivingEntity extends Entity {
 
   get isDead(): boolean { return call<boolean>('entity.isDead', { uuid: this.uuid }); }
   isDeadAsync(options?: TaskOptions): Promise<boolean> { return post<boolean>('entity.isDead', { uuid: this.uuid }, options); }
+
+  /** 施加伤害（可带伤害来源实体 uuid）。 */
+  damage(amount: number, damager?: string, options?: TaskOptions): Promise<void> {
+    return post('entity.damage', { uuid: this.uuid, amount, damager }, options);
+  }
+  damageSync(amount: number, damager?: string, options?: TaskOptions): void {
+    call('entity.damage', { uuid: this.uuid, amount, damager }, options);
+  }
+
+  /**
+   * 设置 AI 目标（**不保证必然生效**——取决于实体类型/寻路能力）。
+   * 目标为实体（targetUuid）或位置（world+x+y+z，可带 speed）。
+   */
+  setTarget(target: { targetUuid: string } | { world: string; x: number; y: number; z: number; speed?: number }, options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('entity.setTarget', { uuid: this.uuid, ...target }, options);
+  }
+  setTargetSync(target: { targetUuid: string } | { world: string; x: number; y: number; z: number; speed?: number }, options?: TaskOptions): boolean {
+    return call<boolean>('entity.setTarget', { uuid: this.uuid, ...target }, options);
+  }
 }

package/src/event.ts

@@ -149,6 +149,8 @@ export interface InventoryOpenEvent {
 export interface InventoryCloseEvent {
   player: Player;
   inventoryType: string;
+  /** 若关闭的是 Yeow 自定义 Inventory（Inventory.create 创建）：该 Inventory 的句柄 id（inventory.toString()）；否则缺省。 */
+  inventoryId?: string;
   cancelled?: boolean;
 }
 export interface ServerPingEvent {
@@ -286,6 +288,8 @@ export interface InventoryClickEvent {
   isShiftClick: boolean;
   clickedItem: ItemData | null;
   cursorItem: ItemData | null;
+  /** 若点击发生在 Yeow 自定义 Inventory（Inventory.create 创建）：该 Inventory 的句柄 id（inventory.toString()）；否则缺省。 */
+  inventoryId?: string;
   cancelled?: boolean;
 }
 interface ItemData {
@@ -368,6 +372,8 @@ function adaptEvent<K extends keyof EventMap>(type: K, data: RawEvent): EventMap
     'playerBucketEmpty', 'playerExpChange', 'playerLevelChange',
     'playerGameModeChange', 'foodLevelChange', 'blockBreak',
     'blockPlace', 'inventoryOpen', 'inventoryClose',
+    'playerAdvancementDone', 'playerToggleSneak', 'playerToggleFlight',
+    'inventoryClick', 'playerResourcePackStatus',
   ] as K[];
   if (hasPlayer.includes(type) && data.player) {
     wrap.player = Player.getSync(data.player as string);

package/src/global.d.ts

@@ -59,10 +59,7 @@ declare global {
     | undefined;
 }
 
-// yeow-dev：构建期虚拟模块（由 Yeow 构建器按 importer 所属依赖项注入命名空间）。
-// 插件未安装 yeow-dev 时此声明生效；类型与实际构建行为一致。
-declare module 'yeow-dev' {
-  export function getAssetsPath(path: string): string;
-}
-
 export {};
+
+// yeow-dev 备选声明见同目录 yeow-dev.d.ts（ambient，非模块文件）——
+// 插件未安装 yeow-dev（构建期虚拟模块）时生效；已安装时以 yeow-dev 包内类型为准。

package/src/instance-id.ts

@@ -1,4 +1,7 @@
 let _seq = 0;
+// 每个插件 QuickJS 上下文独立（模块级变量彼此隔离）；随机种子保证
+// 跨插件/跨 Worker 生成的 id 全局唯一——id 是不透明句柄，不携带任何业务信息。
+const _seed = Math.random().toString(36).slice(2, 12);
 const _gcQueue: string[] = [];
 const _gcReg = typeof FinalizationRegistry !== 'undefined'
   ? new FinalizationRegistry<string>((raw: string) => { _gcQueue.push(raw); })
@@ -9,8 +12,8 @@ export class InstanceId {
   readonly _raw: string;
   readonly _managed: boolean;
 
-  constructor(prefix: string) {
-    this._raw = prefix + '_' + (++_seq);
+  constructor() {
+    this._raw = _seed + '_' + (++_seq);
     this._managed = true;
     _gcReg?.register(this, this._raw);
   }
@@ -25,6 +28,5 @@ export class InstanceId {
   toString(): string { return this._raw; }
 }
 
-export class GUIHandle extends InstanceId { constructor() { super('gui'); } }
-export class BossBarHandle extends InstanceId { constructor() { super('boss'); } }
-export class InventoryHandle extends InstanceId { constructor() { super('inv'); } }
+export class BossBarHandle extends InstanceId {}
+export class InventoryHandle extends InstanceId {}

package/src/inventory.ts

@@ -1,42 +1,174 @@
 import { call, post } from './task.js';
 import type { TaskOptions } from './task.js';
+import type { ItemStack } from './item.js';
+import { InstanceId } from './instance-id.js';
 
-interface ItemData {
-  type: string;
-  amount: number;
-}
-
+/**
+ * Inventory —— 统一容器抽象，三种持有者：
+ * - **玩家物品栏**：`player.inventory`
+ * - **容器方块**（Chest / Furnace / Hopper / Barrel / Dispenser / Dropper / BrewingStand 等）：`block.getInventory()`
+ * - **自定义 Inventory**（自定义箱子界面，原 GUI）：`Inventory.create(size, title)`
+ *
+ * ```js
+ * // 玩家
+ * await player.inventory.setItem(0, ItemStack.create('minecraft:diamond'));
+ * // 容器方块（需方块有 location）
+ * const chest = await world.getBlock(x, y, z);
+ * await chest.getInventory().getItem(0);
+ * // 自定义 Inventory
+ * const inv = await Inventory.create(27, '<gold>Shop</gold>');
+ * await inv.open(player.uuid);
+ * eventOn('inventoryClick', (e) => {
+ *   if (e.inventoryId === inv.toString()) { handleClick(e); }
+ * });
+ * await inv.destroy();
+ * ```
+ */
 export class Inventory {
-  constructor(private readonly uuid: string) {}
+  /** 寻址方式：'player' | 'block' | 'custom'。 */
+  private readonly kind: 'player' | 'block' | 'custom';
+  /** 玩家寻址：uuid。 */
+  private readonly uuid?: string;
+  /** 方块寻址：世界坐标。 */
+  private readonly block?: { world: string; x: number; y: number; z: number };
+  /** 自定义寻址：句柄 id。 */
+  private readonly id?: string;
+
+  private constructor(kind: 'player' | 'block' | 'custom', uuid?: string, block?: { world: string; x: number; y: number; z: number }, id?: string) {
+    this.kind = kind;
+    this.uuid = uuid;
+    this.block = block;
+    this.id = id;
+  }
+
+  /** 玩家物品栏（等价于 `new Inventory('player', uuid)`，通常经 `player.inventory` 获取）。 */
+  static ofPlayer(uuid: string): Inventory {
+    return new Inventory('player', uuid);
+  }
+
+  /** 容器方块（需方块有 location；通常经 `block.getInventory()` 获取）。 */
+  static ofBlock(world: string, x: number, y: number, z: number): Inventory {
+    return new Inventory('block', undefined, { world, x, y, z });
+  }
+
+  /** 创建自定义 Inventory（size 为槽位数，须为 9 的倍数：9/18/27/36/45/54；title 支持 MiniMessage）。 */
+  static async create(size: number, title: string, options?: TaskOptions): Promise<Inventory> {
+    const h = new InstanceId();
+    await post('inventory.create', { id: h.toString(), size, title }, options);
+    return new Inventory('custom', undefined, undefined, h.toString());
+  }
+
+  /** 自定义 Inventory 的句柄 id（与 inventoryClick/Close 事件的 `inventoryId` 字段一致）。 */
+  toString(): string {
+    return this.id ?? '';
+  }
 
-  getItem(slot: number, options?: TaskOptions): Promise<ItemData | null> {
-    return post<ItemData | null>('inventory.getItem', { uuid: this.uuid, slot }, options);
+  /** 持有者类型：'PLAYER' | 'CUSTOM' | 方块实体类型名（如 'CHEST'）。 */
+  getType(options?: TaskOptions): Promise<string> {
+    return post<string>('inventory.getType', this.address(), options);
   }
-  getItemSync(slot: number, options?: TaskOptions): ItemData | null {
-    return call<ItemData | null>('inventory.getItem', { uuid: this.uuid, slot }, options);
+
+  /** 容器槽位数。 */
+  getSize(options?: TaskOptions): Promise<number> {
+    return post<number>('inventory.getSize', this.address(), options);
   }
-  setItem(slot: number, itemType: string, amount?: number, options?: TaskOptions): Promise<void> {
-    return post('inventory.setItem', { uuid: this.uuid, slot, itemType, amount }, options);
+
+  /** 全槽位快照数组（空槽为 null，长度 = 容器槽位数）。 */
+  getContents(options?: TaskOptions): Promise<(ItemStack | null)[]> {
+    return post<(ItemStack | null)[]>('inventory.getContents', this.address(), options);
   }
-  setItemSync(slot: number, itemType: string, amount?: number, options?: TaskOptions): void {
-    call('inventory.setItem', { uuid: this.uuid, slot, itemType, amount }, options);
+  getContentsSync(options?: TaskOptions): (ItemStack | null)[] {
+    return call<(ItemStack | null)[]>('inventory.getContents', this.address(), options);
   }
-  addItem(itemType: string, amount?: number, options?: TaskOptions): Promise<void> {
-    return post('inventory.addItem', { uuid: this.uuid, itemType, amount }, options);
+
+  /** 整容器写入（items 长度可与容器不匹配：短数组只写前段，长数组忽略超出；null 清空对应槽位）。 */
+  setContents(items: (ItemStack | null)[], options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('inventory.setContents', { ...this.address(), items }, options);
   }
-  addItemSync(itemType: string, amount?: number, options?: TaskOptions): void {
-    call('inventory.addItem', { uuid: this.uuid, itemType, amount }, options);
+  setContentsSync(items: (ItemStack | null)[], options?: TaskOptions): boolean {
+    return call<boolean>('inventory.setContents', { ...this.address(), items }, options);
   }
-  removeItem(itemType: string, amount?: number, options?: TaskOptions): Promise<void> {
-    return post('inventory.removeItem', { uuid: this.uuid, itemType, amount }, options);
+
+  /** 读取槽位物品快照（含 meta；空槽返回 null）。 */
+  getItem(slot: number, options?: TaskOptions): Promise<ItemStack | null> {
+    return post<ItemStack | null>('inventory.getItem', { ...this.address(), slot }, options);
   }
-  removeItemSync(itemType: string, amount?: number, options?: TaskOptions): void {
-    call('inventory.removeItem', { uuid: this.uuid, itemType, amount }, options);
+  getItemSync(slot: number, options?: TaskOptions): ItemStack | null {
+    return call<ItemStack | null>('inventory.getItem', { ...this.address(), slot }, options);
   }
-  clear(slot?: number, options?: TaskOptions): Promise<void> {
-    return post('inventory.clear', { uuid: this.uuid, slot }, options);
+
+  /** 设置槽位（完整 ItemStack 含 meta；传 null 清空槽位）。 */
+  setItem(slot: number, item: ItemStack | null, options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('inventory.setItem', { ...this.address(), slot, item }, options);
+  }
+  setItemSync(slot: number, item: ItemStack | null, options?: TaskOptions): boolean {
+    return call<boolean>('inventory.setItem', { ...this.address(), slot, item }, options);
+  }
+
+  /** 批量设置多个槽位（分页/布局用）；item 传 null 清空对应槽位。 */
+  setItems(slots: number[], item: ItemStack | null, options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('inventory.setItems', { ...this.address(), slots, item }, options);
+  }
+
+  /** 用同一物品填充全部槽位。 */
+  fill(item: ItemStack, options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('inventory.fill', { ...this.address(), item }, options);
   }
-  clearSync(slot?: number, options?: TaskOptions): void {
-    call('inventory.clear', { uuid: this.uuid, slot }, options);
+
+  /** 添加物品到空位：返回**未放入数量**（0 = 全部放入；玩家物品栏溢出部分掉落在地上，同样返回 0）。 */
+  addItem(item: ItemStack, options?: TaskOptions): Promise<number> {
+    return post<number>('inventory.addItem', { ...this.address(), item }, options);
+  }
+  addItemSync(item: ItemStack, options?: TaskOptions): number {
+    return call<number>('inventory.addItem', { ...this.address(), item }, options);
+  }
+
+  /** 移除指定物品（按类型 + meta 匹配，amount 默认 1）。返回**未移除数量**（0 = 全部移除成功）。 */
+  removeItem(item: ItemStack, options?: TaskOptions): Promise<number> {
+    return post<number>('inventory.removeItem', { ...this.address(), item }, options);
+  }
+  removeItemSync(item: ItemStack, options?: TaskOptions): number {
+    return call<number>('inventory.removeItem', { ...this.address(), item }, options);
+  }
+
+  /** 清空（slot 可选，不传清空全部）。 */
+  clear(slot?: number, options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('inventory.clear', { ...this.address(), slot }, options);
+  }
+  clearSync(slot?: number, options?: TaskOptions): boolean {
+    return call<boolean>('inventory.clear', { ...this.address(), slot }, options);
+  }
+
+  // ── 自定义 Inventory 专属 ─────────────────────────────────────────
+
+  /** 为玩家打开（自定义 Inventory）。 */
+  open(uuid: string, options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('inventory.open', { ...this.address(), uuid }, options);
+  }
+
+  /** 关闭所有查看者（自定义 Inventory）。 */
+  close(options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('inventory.close', this.address(), options);
+  }
+
+  /** 仅关闭指定玩家（自定义 Inventory）。 */
+  closePlayer(uuid: string, options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('inventory.closePlayer', { ...this.address(), uuid }, options);
+  }
+
+  /** 当前查看者 uuid 列表（自定义 Inventory）。 */
+  getViewers(options?: TaskOptions): Promise<string[]> {
+    return post<string[]>('inventory.getViewers', this.address(), options);
+  }
+
+  /** 销毁并关闭所有查看者（自定义 Inventory）。 */
+  destroy(options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('inventory.destroy', this.address(), options);
+  }
+
+  private address(): Record<string, unknown> {
+    if (this.kind === 'player') return { uuid: this.uuid };
+    if (this.kind === 'block') return { ...this.block! };
+    return { id: this.id };
   }
 }

package/src/item.ts

@@ -1,13 +1,63 @@
+/**
+ * ItemStack：物品纯数据描述符（值语义，快照——不绑定真实物品）。
+ *
+ * meta 字段设计（2026-08-13 扩展）：
+ * - 遵循 Paper / Mojang 现行行为；字段名避开已废弃的 Java 方法名（如不叫 setDamage 语义）
+ * - 全部字段可选；运行时不支持的字段静默忽略（跨版本兼容）
+ * - 文本字段（displayName/lore）支持 MiniMessage
+ */
+
+/** 自定义药水效果（PotionMeta）。 */
+export interface PotionEffectData {
+  type: string;              // 药水效果名（如 'speed' / 'SPEED'，不区分大小写）
+  duration?: number;         // 刻（默认 200）
+  amplifier?: number;        // 等级（默认 0）
+  ambient?: boolean;         // 是否环境粒子（信标样式，默认 false）
+  particles?: boolean;       // 是否显示粒子（默认 true）
+}
+
+/** 属性修饰符（AttributeModifier）。 */
+export interface AttributeModifierData {
+  attribute: string;         // Bukkit Attribute 枚举名（如 'ATTACK_DAMAGE' / 'MOVEMENT_SPEED'）
+  amount: number;
+  operation: 'ADD_NUMBER' | 'ADD_SCALED_AMOUNT' | 'MULTIPLY_SCALED_1';
+  slot?: string;             // 适用槽位：mainhand / offhand / feet / legs / chest / head / body / any（默认 any）
+}
+
+export interface ItemMeta {
+  displayName?: string;                    // MiniMessage
+  lore?: string[];                         // 每行 MiniMessage
+  customModelData?: number;
+  unbreakable?: boolean;
+  hideTooltip?: boolean;
+  enchantments?: Record<string, number>;   // 附魔 key（如 'minecraft:sharpness'）→ 等级
+  itemFlags?: string[];                    // ItemFlag 枚举名（如 'HIDE_ATTRIBUTES'）
+  damage?: number;                         // 耐久损伤值
+  color?: string | { r: number; g: number; b: number };  // 皮革盔甲染色 / 自定义药水颜色（'#RRGGBB' 或 rgb 对象）
+  potionEffects?: PotionEffectData[];      // 自定义药水效果（仅药水类物品生效）
+  skullOwner?: string;                     // 玩家头颅：玩家名 / UUID / base64 纹理值
+  attributeModifiers?: AttributeModifierData[];
+}
+
 export interface ItemStack {
   type: string;
   amount?: number;
-  meta?: {
-    displayName?: string;
-    lore?: string[];
-    customModelData?: number;
-    unbreakable?: boolean;
-    hideTooltip?: boolean;
-    enchantments?: Record<string, number>;
-    itemFlags?: string[];
-  };
+  meta?: ItemMeta;
+}
+
+export namespace ItemStack {
+  /** 构造物品（便利函数，等价于手写 `{ type, amount, meta }`）。 */
+  export function create(type: string, amount = 1, meta?: ItemMeta): ItemStack {
+    return meta ? { type, amount, meta } : { type, amount };
+  }
+
+  /** 深拷贝（快照语义：修改副本不影响原对象）。 */
+  export function clone(item: ItemStack): ItemStack {
+    return JSON.parse(JSON.stringify(item)) as ItemStack;
+  }
+
+  /** 深度相等（序列化比较）。 */
+  export function equals(a: ItemStack, b: ItemStack): boolean {
+    return JSON.stringify(a) === JSON.stringify(b);
+  }
 }

package/src/pdc.ts

@@ -1,31 +1,85 @@
 import { post } from './task.js';
 import type { TaskOptions } from './task.js';
 
-export function get(uuid: string, key: string, options?: TaskOptions): Promise<string | null> {
+// ══════════════════════════════════════════════════════════════════
+// PDC：基于字符串的 K-V 存储。set/get 自动 JSON 序列化/反序列化——
+// 开发者无需手写 JSON.stringify / JSON.parse（旧数据非 JSON 时 get 原样返回）。
+// getRaw/setRaw 提供底层字符串读写（跨版本/跨语言数据交换用）。
+// key 规则：无冒号的裸 key 使用**插件命名空间**（跨插件互不冲突）；
+// 显式命名空间用 `ns:key`（如 `myplugin:score`）。
+// ══════════════════════════════════════════════════════════════════
+
+// ── 底层（raw 字符串） ────────────────────────────────────────────
+
+/** 读取原始字符串（无值返回 null）。 */
+export function getRaw(uuid: string, key: string, options?: TaskOptions): Promise<string | null> {
   return post<string | null>('pdc.get', { uuid, key }, options);
 }
 
-export function set(uuid: string, key: string, value: string, options?: TaskOptions): Promise<boolean> {
+/** 写入原始字符串。 */
+export function setRaw(uuid: string, key: string, value: string, options?: TaskOptions): Promise<boolean> {
   return post<boolean>('pdc.set', { uuid, key, value }, options);
 }
 
+/** 键是否存在。 */
 export function has(uuid: string, key: string, options?: TaskOptions): Promise<boolean> {
   return post<boolean>('pdc.has', { uuid, key }, options);
 }
 
+/** 移除键。 */
 export function remove(uuid: string, key: string, options?: TaskOptions): Promise<boolean> {
   return post<boolean>('pdc.remove', { uuid, key }, options);
 }
 
+/** 全部键（完整 key 格式，含命名空间）。 */
 export function keys(uuid: string, options?: TaskOptions): Promise<string[]> {
   return post<string[]>('pdc.keys', { uuid }, options);
 }
 
-export function getBlock(world: string, x: number, y: number, z: number, key: string, options?: TaskOptions): Promise<string | null> {
+/** 全量读取本插件命名空间的键值（value 为原始字符串）。 */
+export function getAllRaw(uuid: string, options?: TaskOptions): Promise<Record<string, string>> {
+  return post<Record<string, string>>('pdc.getAll', { uuid }, options);
+}
+
+// ── 推荐：JSON 自动序列化 ─────────────────────────────────────────
+
+/** 读取并 JSON 反序列化（无值返回 null；旧数据非 JSON 时原样返回字符串）。 */
+export async function get<T = unknown>(uuid: string, key: string, options?: TaskOptions): Promise<T | null> {
+  const raw = await getRaw(uuid, key, options);
+  if (raw == null) return null;
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    return raw as unknown as T;
+  }
+}
+
+/** 任意可 JSON 序列化的值自动序列化后写入。 */
+export function set(uuid: string, key: string, value: unknown, options?: TaskOptions): Promise<boolean> {
+  return setRaw(uuid, key, JSON.stringify(value), options);
+}
+
+/** 全量读取本插件命名空间的键值（每个值 JSON 反序列化；非 JSON 值原样保留）。 */
+export async function getAll(uuid: string, options?: TaskOptions): Promise<Record<string, unknown>> {
+  const raw = await getAllRaw(uuid, options);
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(raw)) {
+    try {
+      out[k] = JSON.parse(v);
+    } catch {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+// ── Block 变体（世界坐标） ────────────────────────────────────────
+
+export function getBlockRaw(world: string, x: number, y: number, z: number, key: string, options?: TaskOptions): Promise<string | null> {
   return post<string | null>('pdc.get', { world, x, y, z, key }, options);
 }
 
-export function setBlock(world: string, x: number, y: number, z: number, key: string, value: string, options?: TaskOptions): Promise<boolean> {
+export function setBlockRaw(world: string, x: number, y: number, z: number, key: string, value: string, options?: TaskOptions): Promise<boolean> {
   return post<boolean>('pdc.set', { world, x, y, z, key, value }, options);
 }
 
@@ -36,3 +90,38 @@ export function hasBlock(world: string, x: number, y: number, z: number, key: st
 export function removeBlock(world: string, x: number, y: number, z: number, key: string, options?: TaskOptions): Promise<boolean> {
   return post<boolean>('pdc.remove', { world, x, y, z, key }, options);
 }
+
+export function keysBlock(world: string, x: number, y: number, z: number, options?: TaskOptions): Promise<string[]> {
+  return post<string[]>('pdc.keys', { world, x, y, z }, options);
+}
+
+export function getAllBlockRaw(world: string, x: number, y: number, z: number, options?: TaskOptions): Promise<Record<string, string>> {
+  return post<Record<string, string>>('pdc.getAll', { world, x, y, z }, options);
+}
+
+export async function getBlock<T = unknown>(world: string, x: number, y: number, z: number, key: string, options?: TaskOptions): Promise<T | null> {
+  const raw = await getBlockRaw(world, x, y, z, key, options);
+  if (raw == null) return null;
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    return raw as unknown as T;
+  }
+}
+
+export function setBlock(world: string, x: number, y: number, z: number, key: string, value: unknown, options?: TaskOptions): Promise<boolean> {
+  return setBlockRaw(world, x, y, z, key, JSON.stringify(value), options);
+}
+
+export async function getAllBlock(world: string, x: number, y: number, z: number, options?: TaskOptions): Promise<Record<string, unknown>> {
+  const raw = await getAllBlockRaw(world, x, y, z, options);
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(raw)) {
+    try {
+      out[k] = JSON.parse(v);
+    } catch {
+      out[k] = v;
+    }
+  }
+  return out;
+}

package/src/player.ts

@@ -4,6 +4,11 @@ import { Location, LocationData } from './location.js';
 import type { ItemStack } from './item.js';
 import type { Message } from './message.js';
 import type { Permission } from './permission.js';
+import { Inventory } from './inventory.js';
+import {
+  get as pdcGet, set as pdcSet, has as pdcHas, remove as pdcRemove,
+  keys as pdcKeys, getAll as pdcGetAll,
+} from './pdc.js';
 
 interface PlayerData {
   uuid: string;
@@ -29,6 +34,11 @@ export class Player {
 
   get name(): string { return this._name ?? ''; }
 
+  /** 玩家物品栏（统一 Inventory 容器抽象）。 */
+  get inventory(): Inventory {
+    return Inventory.ofPlayer(this.uuid);
+  }
+
   get ping(): number { return call<number>('player.getPing', { uuid: this.uuid }); }
   getPing(options?: TaskOptions): Promise<number> { return post<number>('player.getPing', { uuid: this.uuid }, options); }
 
@@ -138,10 +148,10 @@ export class Player {
   giveExpSync(amount: number, options?: TaskOptions): void { call('player.giveExp', { uuid: this.uuid, amount }, options); }
   /** 检查权限（经 Yeow 权限检查：`permissionCheck` 事件优先，无处理时回退 Bukkit）。node 可为权限节点对象。 */
   hasPermission(node: string | Permission, options?: TaskOptions): Promise<boolean> {
-    return post<boolean>('player.hasPermission', { uuid: this.uuid, permission: typeof node === 'string' ? node : { node: node.node } }, options);
+    return post<boolean>('player.hasPermission', { uuid: this.uuid, permission: typeof node === 'string' ? { node } : { node: node.node } }, options);
   }
   hasPermissionSync(node: string | Permission, options?: TaskOptions): boolean {
-    return call<boolean>('player.hasPermission', { uuid: this.uuid, permission: typeof node === 'string' ? node : { node: node.node } }, options);
+    return call<boolean>('player.hasPermission', { uuid: this.uuid, permission: typeof node === 'string' ? { node } : { node: node.node } }, options);
   }
   /** 以玩家身份执行命令（**不含 `/` 前缀**，如 `say hi`；前缀会自动剥离；与服务器 `dispatchCommand`（控制台）相对）。 */
   performCommand(cmd: string, options?: TaskOptions): Promise<boolean> {
@@ -164,4 +174,75 @@ export class Player {
   getItemInMainHandSync(options?: TaskOptions): ItemStack | null { return call<ItemStack | null>('player.getItemInMainHand', { uuid: this.uuid }, options); }
   getItemInOffHand(options?: TaskOptions): Promise<ItemStack | null> { return post<ItemStack | null>('player.getItemInOffHand', { uuid: this.uuid }, options); }
   getItemInOffHandSync(options?: TaskOptions): ItemStack | null { return call<ItemStack | null>('player.getItemInOffHand', { uuid: this.uuid }, options); }
+
+  /** 设置主手物品（完整 ItemStack 含 meta；传 null 清空）。 */
+  setItemInMainHand(item: ItemStack | null, options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('player.setItemInMainHand', { uuid: this.uuid, item }, options);
+  }
+  setItemInMainHandSync(item: ItemStack | null, options?: TaskOptions): boolean {
+    return call<boolean>('player.setItemInMainHand', { uuid: this.uuid, item }, options);
+  }
+  /** 设置副手物品（完整 ItemStack 含 meta；传 null 清空）。 */
+  setItemInOffHand(item: ItemStack | null, options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('player.setItemInOffHand', { uuid: this.uuid, item }, options);
+  }
+  setItemInOffHandSync(item: ItemStack | null, options?: TaskOptions): boolean {
+    return call<boolean>('player.setItemInOffHand', { uuid: this.uuid, item }, options);
+  }
+
+  /** 设置 Tab 列表 header/footer（MiniMessage；传 null 清空对应栏）。 */
+  sendTabHeader(header: string | null, footer: string | null, options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('player.sendTabHeader', { uuid: this.uuid, header, footer }, options);
+  }
+  sendTabHeaderSync(header: string | null, footer: string | null, options?: TaskOptions): boolean {
+    return call<boolean>('player.sendTabHeader', { uuid: this.uuid, header, footer }, options);
+  }
+
+  /** 设置 Tab 列表显示名（传 null 恢复默认）。 */
+  setPlayerListName(name: string | null, options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('player.setPlayerListName', { uuid: this.uuid, name }, options);
+  }
+  setPlayerListNameSync(name: string | null, options?: TaskOptions): boolean {
+    return call<boolean>('player.setPlayerListName', { uuid: this.uuid, name }, options);
+  }
+
+  /** 设置客户端世界边界（传 null 重置为服务端边界；centerX/centerZ 可选，指定边界中心）。 */
+  setBorder(size: number | null, centerX?: number, centerZ?: number, options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('player.setBorder', { uuid: this.uuid, size, centerX, centerZ }, options);
+  }
+  setBorderSync(size: number | null, centerX?: number, centerZ?: number, options?: TaskOptions): boolean {
+    return call<boolean>('player.setBorder', { uuid: this.uuid, size, centerX, centerZ }, options);
+  }
+
+  // ── PDC（玩家持久数据） ──
+
+  /** 读取并 JSON 反序列化（无值返回 null；旧数据非 JSON 时原样返回字符串）。 */
+  getPdc<T = unknown>(key: string, options?: TaskOptions): Promise<T | null> {
+    return pdcGet(this.uuid, key, options);
+  }
+
+  /** 任意可 JSON 序列化的值自动序列化后写入。 */
+  setPdc(key: string, value: unknown, options?: TaskOptions): Promise<boolean> {
+    return pdcSet(this.uuid, key, value, options);
+  }
+
+  /** 键是否存在。 */
+  hasPdc(key: string, options?: TaskOptions): Promise<boolean> {
+    return pdcHas(this.uuid, key, options);
+  }
+
+  /** 移除键。 */
+  removePdc(key: string, options?: TaskOptions): Promise<boolean> {
+    return pdcRemove(this.uuid, key, options);
+  }
+
+  /** 全部键（完整 key 格式，含命名空间）。 */
+  keysPdc(options?: TaskOptions): Promise<string[]> {
+    return pdcKeys(this.uuid, options);
+  }
+
+  /** 全量读取本插件命名空间的键值（每个值 JSON 反序列化）。 */
+  getAllPdc(options?: TaskOptions): Promise<Record<string, unknown>> {
+    return pdcGetAll(this.uuid, options);
+  }
 }

package/src/scoreboard.ts

@@ -39,6 +39,11 @@ export function deleteBoard(id: string, options?: TaskOptions): Promise<void> {
 
 // ── Objectives ──
 
+/**
+ * 创建计分项。⚠️ **Folia 平台限制**：Folia 不支持注册新 objective（registerNewObjective
+ * 抛 UnsupportedOperationException）——在 Folia 上本调用会 reject（错误消息含
+ * "Folia does not support creating new objectives"）；已存在的 objective 会更新 displayName 后返回。
+ */
 export function createObjective(name: string, criteria: string, displayName: string, board?: string, options?: TaskOptions): Promise<ObjectiveInfo> {
   return post<ObjectiveInfo>('scoreboard.createObjective', { name, criteria, displayName, ...boardParam(board) }, options);
 }
@@ -69,6 +74,10 @@ export function resetScore(objective: string, entry: string, board?: string, opt
 
 // ── Teams ──
 
+/**
+ * 创建队伍。⚠️ **Folia 平台限制**：Folia 不支持注册新 team（registerNewTeam 抛
+ * UnsupportedOperationException）——在 Folia 上本调用会 reject；已存在的 team 返回其信息。
+ */
 export function createTeam(name: string, board?: string, options?: TaskOptions): Promise<void> {
   return post('scoreboard.createTeam', { name, ...boardParam(board) }, options);
 }

package/src/task.ts

@@ -47,6 +47,53 @@ export function call<T = unknown>(
   applyOptions(pld, options);
   const r = $send('task', pld);
   if (r == null) return undefined as T;
-  if ((r as any)?.err) throw new Error((r as any).err);
+  if ((r as any)?.err) {
+    // 与 post() 对齐的错误上下文（type/task/Java 堆栈），2026-08-13 审计修复
+    const errObj = r as any;
+    const msg = errObj.type ? `[${errObj.type}] ${errObj.err}` : errObj.err;
+    const e = new Error(msg);
+    if (errObj.stack) {
+      e.stack += '\n    --- runtime executer error(for reference) ---\n' + errObj.stack;
+    }
+    (e as any).javaType = errObj.type || null;
+    (e as any).taskType = errObj.task || null;
+    throw e;
+  }
   return r as T;
 }
+
+// ══════════════════════════════════════════════════════════════════
+// 批量任务：一次提交任务数组，结果按原顺序返回（逐个独立执行，无原子性）。
+// 依赖包可基于此构造自己的批量优化（如批量发物品、批量写方块）。
+// ══════════════════════════════════════════════════════════════════
+
+export interface BatchTask {
+  type: string;
+  params?: Record<string, unknown>;
+  priority?: 'high' | 'normal' | 'low';
+}
+
+/** 同步批量：阻塞直到全部任务完成，返回结果数组（顺序对应 tasks；单个任务失败时对应项为 `{err}` 对象）。 */
+export function callBatch(tasks: BatchTask[]): unknown[] {
+  if (tasks.length === 0) return [];
+  const r = $send('task', { tasks });
+  if (r == null) return [];
+  if ((r as any)?.err) throw new Error((r as any).err);
+  return r as unknown[];
+}
+
+/** 异步批量：全部任务完成后 Promise resolve 结果数组（顺序对应 tasks；单个任务失败时对应项为 `{err}` 对象）。 */
+export function postBatch<T = unknown>(tasks: BatchTask[]): Promise<T[]> {
+  return new Promise((resolve, reject) => {
+    if (tasks.length === 0) { resolve([] as T[]); return; }
+    const cbId = _registerCallback((result: any) => {
+      if (result?.err) {
+        const msg = result.type ? `[${result.type}] ${result.err}` : result.err;
+        reject(new Error(msg));
+      } else {
+        resolve(result as T[]);
+      }
+    });
+    $send('task', { tasks, cb: cbId });
+  });
+}

package/src/world.ts

@@ -9,6 +9,17 @@ interface WorldData {
   name: string;
 }
 
+/** 世界边界快照。 */
+export interface WorldBorderInfo {
+  centerX: number;
+  centerZ: number;
+  size: number;
+  damageAmount: number;
+  damageBuffer: number;
+  warningDistance: number;
+  warningTime: number;
+}
+
 export class World {
   static get(name: string, options?: TaskOptions): Promise<World | null> {
     return post<WorldData>('world.get', { name }, options).then((d) => (d ? new World(d.name) : null));
@@ -46,6 +57,60 @@ export class World {
   getHighestBlockYSync(x: number, z: number, options?: TaskOptions): number {
     return call<number>('world.getHighestBlockY', { world: this.name, x, z }, options);
   }
+
+  // ── 世界信息（2026-08-13） ──
+
+  /** 世界种子。 */
+  get seed(): number { return call<number>('world.getSeed', { world: this.name }); }
+  getSeed(options?: TaskOptions): Promise<number> { return post<number>('world.getSeed', { world: this.name }, options); }
+
+  /** 环境：NORMAL / NETHER / THE_END。 */
+  get environment(): string { return call<string>('world.getEnvironment', { world: this.name }); }
+  getEnvironment(options?: TaskOptions): Promise<string> { return post<string>('world.getEnvironment', { world: this.name }, options); }
+
+  /** 世界类型（可能返回 null——平台不支持时）。 */
+  get worldType(): string | null { return call<string | null>('world.getWorldType', { world: this.name }); }
+  getWorldType(options?: TaskOptions): Promise<string | null> { return post<string | null>('world.getWorldType', { world: this.name }, options); }
+
+  /** 全部游戏规则名。 */
+  get gameRules(): string[] { return call<string[]>('world.getGameRules', { world: this.name }); }
+  getGameRules(options?: TaskOptions): Promise<string[]> { return post<string[]>('world.getGameRules', { world: this.name }, options); }
+
+  // ── WorldBorder（2026-08-13） ──
+
+  /** 世界边界快照。 */
+  get border(): WorldBorderInfo {
+    return call<WorldBorderInfo>('world.getBorder', { world: this.name });
+  }
+  getBorder(options?: TaskOptions): Promise<WorldBorderInfo> {
+    return post<WorldBorderInfo>('world.getBorder', { world: this.name }, options);
+  }
+  /** 边界中心。 */
+  setBorderCenter(x: number, z: number, options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('world.setBorderCenter', { world: this.name, x, z }, options);
+  }
+  setBorderCenterSync(x: number, z: number, options?: TaskOptions): boolean {
+    return call<boolean>('world.setBorderCenter', { world: this.name, x, z }, options);
+  }
+  /** 边界半径（方块）。 */
+  setBorderSize(size: number, options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('world.setBorderSize', { world: this.name, size }, options);
+  }
+  setBorderSizeSync(size: number, options?: TaskOptions): boolean {
+    return call<boolean>('world.setBorderSize', { world: this.name, size }, options);
+  }
+  /** 边界伤害（amount 每秒伤害；buffer 无伤缓冲距离）。 */
+  setBorderDamage(amount?: number, buffer?: number, options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('world.setBorderDamage', { world: this.name, amount, buffer }, options);
+  }
+  /** 边界警告（distance 方块距离；time 秒）。 */
+  setBorderWarning(distance?: number, time?: number, options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('world.setBorderWarning', { world: this.name, distance, time }, options);
+  }
+  /** 边界平滑移动（from → to，seconds 秒）。 */
+  setBorderMoving(from: number, to: number, seconds: number, options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('world.setBorderMoving', { world: this.name, from, to, seconds }, options);
+  }
   getChunkAt(x: number, z: number, options?: TaskOptions): Promise<Chunk> {
     return post<ChunkData>('world.getChunkAt', { world: this.name, x, z }, options).then((d) => Chunk.from(d));
   }

package/src/yeow-dev.d.ts

@@ -0,0 +1,7 @@
+// 备选声明：插件**未安装** yeow-dev（构建期虚拟模块）时提供 getAssetsPath 类型。
+// 注意：本文件必须为**非模块**（无 import/export）——ambient `declare module` 在
+// 模块文件中会被视为模块增强（需要先 import 才生效），独立使用报 Cannot find module。
+// 已安装 yeow-dev 时以 node_modules/yeow-dev/index.d.ts 为准（内容一致）。
+declare module 'yeow-dev' {
+  export function getAssetsPath(path: string): string;
+}

package/src/gui.ts

@@ -1,34 +0,0 @@
-import { post } from './task.js';
-import type { TaskOptions } from './task.js';
-import { GUIHandle } from './instance-id.js';
-import type { ItemStack } from './item.js';
-
-export async function createGUI(size: number, title: string, options?: TaskOptions): Promise<GUIHandle> {
-  const h = new GUIHandle();
-  await post('gui.create', { id: h.toString(), size, title }, options);
-  return h;
-}
-
-export function destroy(id: GUIHandle, options?: TaskOptions): Promise<void> {
-  return post('gui.destroy', { id: id.toString() }, options);
-}
-
-export function open(id: GUIHandle, uuid: string, options?: TaskOptions): Promise<void> {
-  return post('gui.open', { id: id.toString(), uuid }, options);
-}
-
-export function close(id: GUIHandle, options?: TaskOptions): Promise<void> {
-  return post('gui.close', { id: id.toString() }, options);
-}
-
-export function setItem(id: GUIHandle, slot: number, item: ItemStack, options?: TaskOptions): Promise<void> {
-  return post('gui.setItem', { id: id.toString(), slot, item }, options);
-}
-
-export function fill(id: GUIHandle, item: ItemStack, options?: TaskOptions): Promise<void> {
-  return post('gui.fill', { id: id.toString(), item }, options);
-}
-
-export function clear(id: GUIHandle, options?: TaskOptions): Promise<void> {
-  return post('gui.clear', { id: id.toString() }, options);
-}