Tool 工具系统

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

Tool vs Skill

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

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

内置工具

始终可用

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

按 memory.enabled 自动注入

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

需在 tools.load 中声明

工具 Key	名称	说明
execute-command	execute_command	执行服务器命令
call-agent	call_agent	调用其他助手

execute-command 详解

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

• player 模式：以玩家身份执行，受 Bukkit 权限限制
• console 模式：以服务器后台权限执行，需通过白名单检查

# 助手配置中的命令白名单
executeCommand:
  whitelist:
    - "tp"        # 允许以 console 权限执行 tp 命令
    - "give"
    - "weather"
  blockChaining: true   # 阻止 && || ; 等链式操作符

安全提示

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

call-agent 详解

允许助手 A 调用助手 B。例如：

助手 A → call_agent(agent: "assistant-b", message: "帮我完成这个任务")

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

工具加载规则

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

工具确认机制

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

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

确认请求 30 秒后自动过期。确认/取消操作会触发 ToolConfirmResponseEvent，请求发出时触发 ToolConfirmRequestEvent。

工具执行事件

每次工具调用时会触发事件，方便扩展包监听和统计：

事件	时机
ToolExecutionStartEvent	工具开始执行（含 toolName、params）
ToolExecutionEndEvent	工具执行结束（含 success、durationMs）

工具显示配置

在 interaction.yml 的 toolDisplay 中自定义工具在 ActionBar 中的显示名称：

toolDisplay:
  overrides:
    execute-command:
      displayName: "执行命令"

外部工具扩展

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

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

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

支持的脚本类型：

类型	语言	机制
javascript	JS	GraalJS 内嵌执行
python	Python	GraalPy 内嵌执行
process	任意	子进程 stdin/stdout JSON 通信

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

参见扩展开发。

方式三：其他插件 API 注册

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

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

工具来源层级

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

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