Java 附属模组

Java 侧当前真实扩展入口是 Fabric 自定义 entrypoint alice-mod:plugin，入口类必须实现 io.alice.mod.adapter.api.AliceToolPlugin。

需求

前置条件

Java 21；
与 Alice Mod 当前源码一致的 Minecraft、Fabric Loader、Fabric API 与 Carpet；
一个可构建的 Fabric 模组工程；
本地 Alice Mod 源码或已构建 JAR。

Alice Mod 当前没有可验证的公共 Maven 仓库或已发布 API 坐标。请勿使用旧文档中的 maven.alice-mod.io、io.alice:alice-mod-api 或 io.alice:alice-mod。开发时应使用仓库内工程依赖，或把本地构建 JAR 作为 modCompileOnly / modLocalRuntime 文件依赖。

架构

Alice Mod 初始化时扫描 alice-mod:plugin，实例化 AliceToolPlugin，再调用：

void registerTools(ToolRegistrar registrar, AliceServiceAccess services);

注册阶段只能声明工具。Minecraft Server 此时尚未启动，不能访问世界或假人。需要运行时能力时，把 AliceServiceAccess 保存到工具对象中，在 AliceTool.invoke() 中使用。

公开工具契约为：

public interface AliceTool {
    String name();
    String description();
    Map<String, Object> parameterSchema();
    ToolResult invoke(Map<String, Object> args);
}

工具名应使用全局唯一的 snake_case。同名冲突会被记录并跳过；ToolRegistrar 在插件初始化结束后失效。

执行

1. 配置本地依赖

若附属模组位于 Alice 仓库外，可先构建 Alice Mod，再用本地文件依赖：

repositories {
    mavenCentral()
    maven { url = uri("https://maven.fabricmc.net/") }
}
 
dependencies {
    modCompileOnly files("libs/alice-mod-local.jar")
    modLocalRuntime files("libs/alice-mod-local.jar")
}

把你刚从 packages/adapter-java/build/libs/ 构建的 JAR 复制到附属模组的 libs/。版本必须与目标服务端实际安装版本一致。

若附属模组就在同一个 Gradle 组合构建中，也可使用项目依赖；具体写法由该组合构建的 settings.gradle 决定，不应伪造发布坐标。

2. 声明入口

在附属模组的 fabric.mod.json 中添加：

{
  "schemaVersion": 1,
  "id": "example-alice-tools",
  "version": "1.0.0",
  "entrypoints": {
    "alice-mod:plugin": ["com.example.ExampleAlicePlugin"]
  },
  "depends": {
    "alice-mod": "*",
    "fabricloader": ">=0.16.0",
    "minecraft": ">=1.21",
    "java": ">=21"
  }
}

alice-mod:plugin 是工具发现入口；不要把普通 main entrypoint 当作替代。

3. 注册最小工具

package com.example;
 
import io.alice.mod.adapter.api.AliceTool;
import io.alice.mod.adapter.api.AliceToolPlugin;
import io.alice.mod.adapter.api.ToolRegistrar;
import io.alice.mod.adapter.api.ToolResult;
import io.alice.mod.adapter.api.service.AliceServiceAccess;
import java.util.Map;
 
public final class ExampleAlicePlugin implements AliceToolPlugin {
    @Override
    public void registerTools(ToolRegistrar registrar, AliceServiceAccess services) {
        registrar.register(new AliceTool() {
            public String name() { return "example_ping"; }
            public String description() { return "返回附属模组连通状态"; }
            public Map<String, Object> parameterSchema() {
                return Map.of("type", "object", "properties", Map.of());
            }
            public ToolResult invoke(Map<String, Object> args) {
                return ToolResult.ok("pong");
            }
        });
    }
}

4. 构建与验证

cd packages/adapter-java
.\gradlew.bat test
.\gradlew.bat remapJar

将 Alice Mod、附属模组、Fabric API 和 Carpet 放入同一测试实例的 mods/。启动世界后检查日志中 Plugin initialized 与 Plugin registered tool: example_ping，再确认 Agent Core 当前工作区出现该工具。

常见失败

现象	检查项
插件未发现	`fabric.mod.json` 的 key 是否精确为 `alice-mod:plugin`；入口类是否有无参构造方法
编译找不到 API	本地 JAR 是否来自当前源码并包含 `io.alice.mod.adapter.api`
注册时访问世界失败	把世界访问移到 `invoke()`，注册阶段只保存服务引用
工具未出现	工具名是否冲突；检查 Alice Mod 与 Agent Core 的连接和重新注册日志

源码架构 Bedrock 工具扩展