Bedrock 工具扩展

Bedrock 当前提供的是 Adapter 内部的目录式 LSE Node.js 工具扩展。它适合在 packages/adapter-bedrock 源码树中增加工具，不是独立安装的通用插件 SDK，也没有成熟的第三方插件生态承诺。

需求

前置条件

Node.js 20 及以上、pnpm；
可运行的 BDS 与兼容 Legacy Script Engine Node.js 环境；
Alice 仓库源码；
能访问项目配置的 BDS 测试目录。

工具实现运行在 BDS 的 LSE Node.js 上，可以使用该运行时暴露的 mc、File、logger 等全局对象。不要按现代 LeviLamina 原生插件 manifest 编写此扩展。

架构

工具目录固定为：

packages/adapter-bedrock/src/tools/
└── <category>/
    └── <tool-name>/
        └── index.ts

构建后扫描器查找对应的 index.js，使用 require() 加载默认导出的无参类。该类必须实现 IToolModule：

interface IToolModule {
  metadata(): ToolMetadata
  execute(
    params: Record<string, any>,
    ctx: ToolContext,
  ): Promise<ResultEnvelope>
}

metadata() 提供名称、描述、分类、输入/输出 Schema 和执行提示；execute() 通过 ToolContext 访问玩家、世界、假人与事件发送能力。连接建立后，Adapter 以 register_tools 通知把所有已扫描工具发送给 Agent Core。

执行

1. 创建目录

例如新增只读工具：

packages/adapter-bedrock/src/tools/perception/example-ping/index.ts

2. 实现工具

import type {
  IToolModule,
  ToolMetadata,
  ToolContext,
  ResultEnvelope,
} from '../../../registry/tool-module.types.js'
 
export default class ExamplePingTool implements IToolModule {
  metadata(): ToolMetadata {
    return {
      name: 'example_ping',
      description: '返回 Bedrock Adapter 工具连通状态',
      category: 'perception',
      input_schema: {
        type: 'object',
        properties: {},
        required: [],
      },
      output_schema: {
        type: 'object',
        properties: { message: { type: 'string' } },
      },
      execution: { is_async: true },
    }
  }
 
  async execute(
    _params: Record<string, any>,
    ctx: ToolContext,
  ): Promise<ResultEnvelope> {
    return {
      success: true,
      data: { message: 'pong' },
      meta: { duration: ctx.getElapsedMs() },
    }
  }
}

注意导入路径保留 .js，与当前 TypeScript/NodeNext 输出约定一致。

3. 构建与部署

pnpm --filter @alice-mod/adapter-bedrock build

当前 build 会先运行 tsc，再运行 scripts/copy-to-bds.js。复制目标取决于本地项目配置；执行前先核对脚本和测试 BDS 路径，避免覆盖错误实例。

4. 验证

启动 BDS，确认日志出现工具目录扫描和 example_ping 注册记录。
确认 Adapter 与 Agent Core 完成握手。
在 Agent Core 当前工作区查看动态工具列表。
调用工具并验证返回 { success: true, data, meta }。

常见失败

现象	检查项
目录被扫描但模块跳过	是否默认导出无参 class；是否同时实现 `metadata` 与 `execute`
`MODULE_NOT_FOUND`	目录层级和 `.js` 导入后缀是否符合构建输出
工具已加载但 Agent Core 不可见	是否在工具扫描完成前连接；重连后检查 `register_tools` 通知
本地测试通过、BDS 失败	是否误用了普通 Node.js API 或目标 LSE 版本没有的游戏 API

稳定边界

IToolModule、目录扫描和 ToolContext 都是当前 Adapter 内部源码契约。它们可以随 Adapter 版本变化；分发扩展时应绑定明确的 Alice Bedrock Adapter 源码版本，并在真实 BDS/LSE 环境回归。

Java 附属模组 Agent Core 扩展点