🔔 事件：在 Open WebUI 中使用 __event_emitter__ 和 __event_call__

Open WebUI 的插件架构不仅仅是处理输入和产生输出——它还关乎与 UI 和用户的实时交互通信。为了让您的工具 (Tools)、函数 (Functions) 和 Pipes 更加动态，Open WebUI 通过 __event_emitter__ 和 __event_call__ 辅助工具提供了一个内置的事件系统。

本指南解释了什么是事件、如何从代码中触发它们，以及您可以使用的完整事件类型目录（不仅仅是 "input"）。

---

🌊 什么是事件？

事件 (Events) 是从后端代码（工具或函数）发送到 Web UI 的实时通知或交互式请求。它们允许您更新聊天、显示通知、请求确认、运行 UI 流程等。

• 事件使用 __event_emitter__ 辅助工具发送单向更新，或者当您需要用户输入或响应（例如确认、输入等）时使用 __event_call__。

比喻： 把事件想象成您的插件可以触发的推送通知和模态对话框，使聊天体验更加丰富和互动。

---

🧰 基本用法

发送事件

您可以通过调用以下代码，在工具或函数的任何位置触发事件：

await __event_emitter__(
    {
        "type": "status",  # 请参阅下面的事件类型列表
        "data": {
            "description": "处理已开始！",
            "done": False,
            "hidden": False,
        },
    }
)

您不需要手动添加 chat_id 或 message_id 等字段——这些由 Open WebUI 自动处理。

交互式事件

当您需要暂停执行直到用户响应时（例如确认/取消对话框、代码执行或输入），请使用 __event_call__：

result = await __event_call__(
    {
        "type": "input",  # 或者 "confirmation", "execute"
        "data": {
            "title": "请输入您的密码",
            "message": "此操作需要密码",
            "placeholder": "在此输入密码",
        },
    }
)

# result 将包含用户的输入值

---

📜 事件有效负载结构 (Payload Structure)

当您发出或调用事件时，基本结构为：

{
  "type": "event_type",   // 请参阅下面的完整列表
  "data": { ... }         // 特定于事件的有效负载
}

大多数情况下，您只需设置 "type" 和 "data"。Open WebUI 会自动填充路由。

---

🗂 事件类型完整列表

下面是所有支持的事件 type 值的综合表格，以及它们的预期效果和数据结构。（这是基于对 Open WebUI 事件处理逻辑的最新分析。）

类型 (type)	何时使用	数据有效负载结构（示例）
status	显示消息的状态更新/历史记录	{description: ..., done: bool, hidden: bool}
chat:completion	提供聊天完成结果	（自定义，请参阅 Open WebUI 内部机制）
chat:message:delta, message	向当前消息追加内容	{content: "要追加的文本"}
chat:message, replace	完全替换当前消息内容	{content: "替换文本"}
chat:message:files, files	设置或覆盖消息文件（用于上传、输出）	{files: [...]}
chat:title	设置（或更新）聊天会话标题	主题字符串 或 {title: ...}
chat:tags	更新聊天的标签集	标签数组或对象
source, citation	添加来源/引用，或代码执行结果	对于代码：请参阅下方
notification	在 UI 中显示通知 ("toast")	{type: "info" 或 "success" 或 "error" 或 "warning", content: "..."}
confirmation (需要 __event_call__)	请求确认（确定/取消对话框）	{title: "...", message: "..."}
input (需要 __event_call__)	请求简单的用户输入（“输入框”对话框）	{title: "...", message: "...", placeholder: "...", value: ...}
execute (需要 __event_call__)	请求用户端执行代码并返回结果	{code: "...javascript 代码..."}

---

source 或 citation (以及代码执行)

添加参考/引用：

await __event_emitter__(
    {
        "type": "source",  # 或 "citation"
        "data": {
            # Open WebUI 来源 (引用) 对象
        }
    }
)

对于代码执行（跟踪执行状态）：

await __event_emitter__(
    {
        "type": "source",
        "data": {
            # Open WebUI 代码来源 (引用) 对象
        }
    }
)