AI 机器人 - 自定义工具

[Discourse]

本指南说明了如何在 Discourse AI 插件中创建、配置和集成自定义 AI 工具，使管理员能够通过用户定义的 JavaScript 函数来扩展机器人的功能。

所需用户级别：管理员

工具是可编程的功能，AI 机器人可以使用它们来执行特定任务或检索信息，而不仅仅是基于文本的响应。这些工具是脚本或集成，允许机器人与外部 API 交互、操作数据或执行附加功能以扩展其能力。

摘要

本文档涵盖：

• 创建新的自定义 AI 工具
• 配置工具参数和脚本
• 工具脚本可用的 API
• 将自定义工具与 AI 角色集成
• 测试和故障排除自定义工具

创建新的自定义 AI 工具

要创建新的 AI 工具：

1. 导航至管理面板 (Admin Panel) > 插件 (Plugins) > Discourse AI > 工具 (Tools)
2. 点击“新建工具”(New Tool)（您可以使用现有预设来了解各种选项）
3. 填写以下字段：
   • 名称 (Name)：向 LLM (大型语言模型) 展示的工具名称
   • 描述 (Description)：向 LLM 展示的工具描述
   • 摘要 (Summary)：工具为协助用户所做工作的简要说明（显示在详细信息中）
   • 参数 (Parameters)：定义工具作为向 LLM 展示时所需的输入
   • 脚本 (Script)：为您的工具提供动力的 JavaScript 代码
4. 点击“保存”(Save)

配置工具脚本

可用 API

您的工具脚本可以访问以下 API：

1. HTTP 请求：

   http.get(url, options)
   http.post(url, options)
   http.put(url, options)
   http.patch(url, options)
   http.delete(url, options)
   

   使用这些来与外部服务交互。您可以使用 options 来指定 HTTP 标头和主体 (body)：

   http.get(url, { headers: { "Authorization": "Bearer key" } })
   http.post(url, { headers: { "Content-Type": "application/json" }, body: { key: "value" } })
   http.patch(url, { headers: { "Authorization": "Bearer key" }, body: "some body" })
   http.delete(url, { headers: { "Authorization": "Bearer key" } })
   http.put(url, { headers: { "Authorization": "Bearer key" }, body: "some body" })
   

   所有 HTTP 方法都返回 { status: number, body: string }。

2. LLM (语言模型) 集成：

   llm.truncate(text, length)
   

   根据配置的 LLM 的分词器，将文本截断到指定的 token 长度。

   llm.generate(prompt, options)
   

   使用配置的 LLM 生成文本。提示 (prompt) 可以是简单的字符串，也可以是结构化对象，例如 { messages: [{ type: "system", content: "..." }, { type: "user", content: "..." }] }。选项包括 json: true 以请求并自动解析 JSON 输出，以及 temperature、top_p、max_tokens 和 stop_sequences。

3. 自定义上传集成 (RAG)

   index.search(query, { filenames: ["file.pdf"], limit: 10 })
   

   搜索附加到此工具的已索引 RAG 文档片段。按相关性排序返回 Array<{ fragment: string, metadata: string | null }>。默认限制为 10，最大为 200。

   index.getFile(filename)
   

   通过精确的文件名检索上传的 RAG 文件的完整内容。如果未找到文件，则返回完整文本或 null。

4. 上传支持

   upload.create(filename, base_64_content)
   

   创建新的上传项。返回 { id: number, url: string, short_url: string }。

   upload.getUrl(shortUrl)
   

   给定短 URL（例如 upload://12345），返回完整的 CDN 友好 URL。

   upload.getBase64(uploadIdOrShortUrl, maxPixels)
   

   获取现有上传项的 base64 编码内容。接受上传 ID（数字）或短 URL（字符串）。可选的 maxPixels 参数用于自动图像大小调整（默认值：10,000,000）。

5. 执行链控制

   chain.setCustomRaw(raw)
   

   设置机器人帖子的最终原始内容并停止工具执行链。这对于直接生成完整响应的工具（例如图像生成工具）非常有用。

6. Secrets 管理

   secrets.get(alias)
   

   返回绑定到给定别名的凭据值。别名在工具的 Secret 契约配置中定义，并在管理面板中绑定到 AI 密钥 (AI Secrets)。如果别名未声明、未绑定或凭据缺失，则会抛出错误。

   const apiKey = secrets.get("my_api_key");
   

7. Discourse 集成

   工具可以直接与 Discourse 数据交互：

   discourse.baseUrl              // 站点的基础 URL
   discourse.search(params)       // 执行 Discourse 搜索
   discourse.getPost(post_id)     // 获取帖子详情（包括原始内容）
   discourse.getTopic(topic_id)   // 获取主题详情（标签、分类等）
   discourse.getUser(id_or_username)  // 获取用户详情
   discourse.createTopic(params)  // 创建新主题
   discourse.createPost(params)   // 创建新帖子/回复
   discourse.editPost(post_id, raw, options)    // 编辑帖子内容
   discourse.editTopic(topic_id, updates, options) // 编辑主题属性（标签、分类、可见性）
   discourse.createChatMessage(params) // 发送聊天消息
   discourse.createStagedUser(params)  // 创建预注册用户
   discourse.getAgent(name)       // 获取另一个 AI 代理（具有 respondTo 方法）
   discourse.updateAgent(name, updates) // 更新 AI 代理的配置
   discourse.getCustomField(type, id, key)      // 读取帖子/主题/用户上的自定义字段
   discourse.setCustomField(type, id, key, value) // 在帖子/主题/用户上设置自定义字段
   

8. Context 对象

   context 对象提供有关工具运行位置的信息：

   • 机器人对话上下文： context.post_id, context.topic_id, context.private_message, context.participants, context.username, context.user_id
   • 聊天上下文： context.message_id, context.channel_id, context.username
   • 自动化上下文： context.post_id, context.topic_id, context.username, context.user_id, context.feature_name, context.feature_context
   • 通用属性： context.site_url, context.site_title, context.site_description

所需函数

您的脚本必须实现：

• invoke(params)：工具被调用时执行的主函数

它可以选择实现：

• details()：返回一个字符串（可以包含基本 HTML）来描述工具的执行情况，显示在聊天界面中
• customSystemMessage()：在提示组装期间调用（不在工具调用期间）。返回一个字符串，该字符串将被追加到系统提示中，或者返回 null/undefined 以跳过。可以访问 context、discourse 和 index 对象。

示例脚本：

function invoke(params) {
  let result = http.get("https://api.example.com/data?query=" + params.query);
  return JSON.parse(result.body);
}

function details() {
  return "Fetched data from Example API";
}

限制和安全

• 执行超时： 默认超时时间为 2000 毫秒的脚本处理时间。计时器在外部 HTTP 请求 (http.*) 和 LLM 调用 (llm.generate) 期间暂停，因此只有脚本自身的处理时间才会计入。
• 内存： 最大 10MB V8 堆限制
• HTTP 请求： 每个工具执行最多 20 个请求
• 沙箱环境： 脚本在受限的 V8 JavaScript 环境中运行（通过 MiniRacer）。无法访问浏览器全局变量、宿主文件系统或服务器端库。网络请求通过 Discourse 后端代理。

测试您的工具

您应该测试构建的任何工具，以确保提供给 LLM 的结果符合您的预期。

将工具与 AI 角色集成

要将您的自定义工具添加到 AI 角色：

1. 进入管理面板 (Admin Panel) > 插件 (Plugins) > Discourse AI > 角色 (Personas)
2. 编辑现有角色或创建新角色
3. 在“工具”(Tools) 部分，您将看到您的自定义工具与内置工具一起列出
4. 选择您的自定义工具以将其添加到角色中

启用自定义工具

一旦您将自定义工具提供给 LLM，它就可以使用它来增强对话。

故障排除

如果您的工具没有按预期工作：

1. 使用测试界面确保它对您的输入表现符合预期。
2. 确保您的用户组在 ai_bot_debugging_allowed_groups 中。该组的成员可以完全访问机器人转录记录；您可以在那里查看 AI 日志。
3. 如果发生任何意外情况，请访问 https://SITENAME/logs 检查错误。

附加资源

Discourse AI - AI bot

AI bot - Agents