工具开发概述

ChatAI Plugin 支持三种工具来源，本文档帮助你开发和扩展工具。

工具来源

来源	位置	说明
内置工具	src/mcp/tools/	核心功能，20个类别模块化组织
自定义 JS	data/tools/	用户脚本，热重载
外部 MCP	data/mcp-servers.json	npm 包或远程服务

工具定义格式

所有工具遵循统一的定义格式：

{
  // 工具名称（唯一标识）
  name: 'my_tool',
  
  // 工具描述（AI 可见）
  description: '工具功能描述',
  
  // 参数定义（JSON Schema 格式）
  inputSchema: {
    type: 'object',
    properties: {
      param1: {
        type: 'string',
        description: '参数描述'
      }
    },
    required: ['param1']
  },
  
  // 处理函数
  handler: async (args) => {
    // 实现逻辑
    return { result: '...' }
  }
}

上下文访问

内置工具通过 ToolContext 访问运行时上下文：

import { getBuiltinToolContext } from '../../mcp/BuiltinMcpServer.js'

handler: async (args) => {
  const ctx = getBuiltinToolContext()
  
  // 获取 Bot 实例
  const bot = ctx.getBot()
  
  // 获取消息事件
  const event = ctx.getEvent()
  const userId = event?.user_id
  const groupId = event?.group_id
  
  // 检查权限
  const isMaster = ctx.isMaster
  
  // 获取适配器信息
  const adapter = ctx.getAdapter()
  // { adapter: 'icqq'|'napcat'|'onebot', isNT: boolean, canAiVoice: boolean }
}

返回值格式

工具返回值会自动序列化：

// 简单文本
return { text: '结果文本' }

// 结构化数据
return { 
  success: true,
  data: { key: 'value' }
}

// 带额外信息
return {
  text: '当前时间: 14:30',
  datetime: '2024-12-15T06:30:00.000Z',
  timestamp: 1702622400000
}

// 错误
throw new Error('错误信息')

开发流程

1. 确定工具类型 - 内置/自定义/MCP
2. 定义接口 - 名称、描述、参数
3. 实现逻辑 - 编写执行函数
4. 测试验证 - 命令行或 API 测试
5. 部署使用 - 配置权限后启用

详细文档

• 内置工具 - 内置工具开发
• 自定义 JS 工具 - JS 工具开发
• MCP 服务器 - MCP 服务器接入
• 安全与权限 - 工具安全控制