ArkPilot

主题

扩展开发 ​

ArkPilot 提供多种扩展方式，方便第三方插件或扩展包添加自定义工具、技能和上下文。

扩展方式概览 ​

方式适用场景复杂度
脚本工具（tools/）简单工具，快速开发⭐
JAR 扩展包（expansions/）多工具打包，功能丰富⭐⭐
插件 API 注册其他 Bukkit 插件集成⭐⭐⭐

方式一：脚本工具 ​

在 plugins/ArkPilot/tools/ 目录下创建脚本工具，零编译、热加载。

目录结构 ​

tools/
└── give-item/
    ├── manifest.yml    # 工具定义（必需）
    └── main.js         # 执行脚本（必需）

manifest.yml ​

yaml
# 工具名称（AI 调用时使用的函数名）
toolName: give_item
# 工具描述（告诉 AI 这个工具做什么）
description: "给予玩家指定物品和数量"
# 工具 key（可选，默认取目录名）
# key: give-item
# 参数定义（JSON Schema 格式）
parameters:
  type: object
  properties:
    item:
      type: string
      description: "物品 ID，如 diamond、iron_ingot"
    amount:
      type: integer
      description: "数量，默认 1"
      default: 1
  required: [item]

# 执行器配置
executor:
  # 入口文件
  entry: main.js
  # 执行类型（可选，默认按后缀推断）
  # javascript / python / process
  type: javascript
  # 超时（毫秒，可选）
  timeout: 5000

# 权限要求（可选）
# permission: "arkpilot.tool.give-item"
# 是否需要玩家确认（可选）
# requireConfirmation: false

脚本类型 ​

类型语言机制特点
javascriptJSGraalJS 内嵌执行可直接访问 Bukkit Java 对象
pythonPythonGraalPy 内嵌执行同上
process任意语言子进程 stdin/stdout JSON 通信语言无限制

使用脚本工具 ​

  1. 创建 tools/my-tool/manifest.yml 和脚本文件
  2. 执行 /ark reload
  3. 在助手配置的 tools.load 中添加工具 key：
yaml
tools:
  load:
    - execute-command
    - my-tool         # 新增

方式二：JAR 扩展包 ​

在 plugins/ArkPilot/expansions/ 目录下放置 JAR 扩展包。一个 JAR 可注册多个工具、技能和上下文提供者。

核心接口 ​

kotlin
// 扩展包基类
abstract class ArkPilotExpansion {
    abstract val id: String
    abstract val name: String

    // 启用时调用，在此注册工具/技能
    abstract fun onEnable(context: ExpansionContext)

    // 禁用时调用
    open fun onDisable() {}
}

// 工具定义
abstract class ExpansionTool {
    abstract val key: String
    abstract val toolName: String
    abstract val description: String
    abstract val parameters: String  // JSON Schema

    // 执行工具
    abstract fun execute(player: Player, params: Map<String, Any?>): String
}

// 注册上下文
interface ExpansionContext {
    val dataFolder: File
    fun registerTool(tool: ExpansionTool)
    fun registerSkill(key: String, markdown: String)
    fun registerContextProvider(id: String, provider: ContextProvider)
}

使用扩展包 ​

  1. 将 JAR 放入 expansions/ 目录
  2. 重启服务器或执行 /ark reload
  3. 在助手配置中启用扩展包注册的工具/技能

方式三：插件 API 注册 ​

其他 Bukkit 插件可通过 ArkPilotApi 注册工具和技能。

注册工具 ​

kotlin
import me.kzheart.arkpilot.api.ArkPilotApi

ArkPilotApi.registerTool("economy-balance", myAgentTool)

注册后在助手 tools.load 中添加 key 启用。

注册技能 ​

kotlin
ArkPilotApi.registerSkill("economy-guide", """
---
name: economy-guide
description: 经济系统使用指南
---

# 经济系统

## 查看余额
使用 /money 查看当前余额。
...
""".trimIndent())

注册上下文提供者 ​

向 Prompt Layer 4 注入场景上下文：

kotlin
ArkPilotApi.registerContextProvider("dungeon") { assistant, player ->
    val dungeon = DungeonPlugin.getCurrentDungeon(player)
    if (dungeon != null) {
        "Player is in dungeon: ${dungeon.name}, floor ${dungeon.floor}"
    } else {
        null  // 返回 null 不注入
    }
}

监听事件 ​

kotlin
// TabooLib 注解方式
@SubscribeEvent
fun onConversationEnd(event: ConversationEndEvent) {
    // 对话结束时的处理
}

// 回调注册方式
ArkPilotApi.onConversationEnd { event ->
    // ...
}

ArkPilotApi.onToolExecution { event ->
    // 工具执行时的处理
}

动态修改 Prompt ​

kotlin
ArkPilotApi.addBootstrapHook { assistant, player, files ->
    // 动态修改引导文件内容
    files.soul = files.soul + "\n\n额外的灵魂指引..."
}

工具来源与优先级 ​

所有方式注册的工具完全等同，用同样的 key 引用：

BUILTIN    → 代码内置工具
PLUGIN     → 其他插件通过 API 注册
EXTERNAL   → tools/ 脚本工具
EXPANSION  → expansions/ JAR 扩展包

安全注意事项 ​

WARNING

  • 脚本工具和扩展包拥有与插件相同的权限级别
  • 服主应审查所有第三方脚本和扩展包的安全性
  • 子进程模式的工具有超时强制终止和输出大小限制

ArkPilot — Minecraft AI Assistant Plugin