ArkPilot

主题

Tool 工具系统 ​

Tool 是 AI 助手的能力层——代码注册的可执行函数。AI 通过 tool_call 调用工具来执行实际操作。

Tool vs Skill ​

Tool（工具）Skill（技能）
本质可执行代码纯 Markdown 文档
作用赋予 AI 执行能力教 AI 怎么做事
注册方式代码注册到 ToolRegistry放在 skills/ 目录
在助手配置中tools.loadskills.load

两者完全解耦。Tool 不需要对应的 Skill 也能工作；Skill 可以引用多个 Tool。

内置工具 ​

始终可用 ​

工具 Key名称说明
skill-readskill_read按需读取技能文档，始终自动注入

按 memory.enabled 自动注入 ​

工具 Key名称说明
memory-readmemory_read读取记忆分类或搜索关键词
memory-writememory_write添加/删除记忆条目

需在 tools.load 中声明 ​

工具 Key名称说明
execute-commandexecute_command执行服务器命令
call-agentcall_agent调用其他助手
validate-blueprintvalidate_blueprint校验蓝图 JSON
build-blueprintbuild_blueprint执行蓝图建造

execute-command 详解 ​

最常用的工具，支持两种模式：

  • player 模式：以玩家身份执行，受 Bukkit 权限限制
  • console 模式：以服务器后台权限执行，需通过白名单检查
yaml
# 助手配置中的命令白名单
executeCommand:
  whitelist:
    - "tp"        # 允许以 console 权限执行 tp 命令
    - "give"
    - "weather"
  blockChaining: true   # 阻止 && || ; 等链式操作符

安全提示

白名单只影响 console 模式。不在白名单中的命令仍然可以 player 模式执行（受玩家自身权限限制）。

call-agent 详解 ​

允许助手 A 调用助手 B。例如建筑助手调用蓝图生成器：

Builder → call_agent(agent: "blueprint-generator", message: "生成一个 7x7 小木屋蓝图")

超时由 config.yml 的 callAgent.timeoutSeconds 控制。

工具加载规则 ​

1. 始终注入：skill-read
2. memory.enabled=true → 自动注入：memory-read, memory-write
3. tools.load 中声明的工具
4. 按玩家权限过滤

工具确认机制 ​

标记了 requireConfirmation = true 的工具执行前需要玩家确认。玩家会看到：

请求执行 执行命令: [✓ 确认] [✗ 取消]

确认请求 30 秒后自动过期。

工具显示配置 ​

在 config.yml 的 toolDisplay 中控制工具调用在聊天中的显示：

yaml
toolDisplay:
  defaults:
    showInChat: true     # 默认显示
    showArgs: false      # 默认不显示参数
  overrides:
    memory-read:
      showInChat: false  # 隐藏记忆读取提示
    execute-command:
      displayName: "执行命令"
      showInChat: true
      showArgs: true     # 显示命令参数

外部工具扩展 ​

方式一：脚本工具（tools/ 目录） ​

在 plugins/ArkPilot/tools/ 目录下创建脚本工具：

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

支持的脚本类型：

类型语言机制
javascriptJSGraalJS 内嵌执行
pythonPythonGraalPy 内嵌执行
process任意子进程 stdin/stdout JSON 通信

方式二：JAR 扩展包（expansions/ 目录） ​

参见扩展开发。

方式三：其他插件 API 注册 ​

kotlin
ArkPilotApi.registerTool("my-tool", myAgentTool)

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

工具来源层级 ​

所有来源注册后完全等同，用同样的 key 引用：

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

ArkPilot — Minecraft AI Assistant Plugin