插件管理

插件用于扩展聊天流程、路由逻辑、统计能力和后台任务。管理员可以管理当前的插件启用状态和配置，但不能动态安装插件代码。

什么时候用

• 需要智能路由对话到不同模型/Agent时（如Hybrid Router）
• 需要统计Token使用情况时（如Token Counter）
• 需要事后分析对话内容时（如Hindsight Memory）
• 需要调试会话转储时（如Debug Conversation Dump）
• 需要查看插件钩子信息时
• 需要调整插件执行优先级时

你需要准备

• （管理员）只有管理员可以管理插件
• 插件代码已由平台管理员部署和加载（不能安装插件代码）

操作步骤

第 1 步：进入插件管理

左侧菜单 -> 插件管理。

页面显示：

• 搜索框：按插件名称或描述搜索
• 筛选器：筛选「已启用」或「已禁用」插件
• 排序：按「优先级」或「名称」排序
• 插件卡片网格

第 2 步：查看插件卡片

每个插件卡片显示：

• 插件名称
• 描述
• 版本和作者
• 当前状态（已启用/已禁用）
• 优先级
• 操作按钮：配置、查看钩子、启用/禁用

第 3 步：启用/禁用插件

在插件卡片上点击「启用」或「禁用」开关：

• 启用：插件按优先级参与执行
• 禁用：不再参与执行（但保留历史数据）

禁用插件不会删除历史数据。

第 4 步：配置插件

1. 在插件卡片上点击「配置」按钮，打开配置抽屉
2. 根据插件配置表单填写配置项
3. 点击「保存」

启用插件时，系统会自动填充缺失的默认值。

第 5 步：查看钩子信息

1. 在插件卡片上点击「查看钩子」按钮，打开钩子弹窗
2. 查看该插件声明关注的钩子
3. 了解每个钩子的触发时机

常见钩子：

• auth_completed：认证完成后
• before_llm_call：LLM调用前
• after_llm_response：LLM响应后
• before_tool_exec：工具执行前
• after_tool_exec：工具执行后
• response_sent：响应发送后

第 6 步：调整排序

在页面顶部的「排序」下拉框中选择：

• 优先级：按插件优先级数值排序，数值越小越早执行
• 名称：按插件名称字母序排序

第 7 步：查看插件系统任务

部分插件会声明定时任务，这些任务会作为系统任务出现：

左侧菜单 -> 定时任务 -> 「系统任务」标签页。

可以：

• 查看插件注册的系统任务
• 启用/禁用（部分任务可能不允许禁用）
• 查看执行历史

系统插件详解

Hybrid Router（混合路由）

这是什么

根据用户消息内容，自动路由到最合适的智能体。三层匹配机制依次执行，命中即停：

1. 关键词匹配（第一层）：检查用户消息是否命中智能体配置的精确关键词或正则表达式。命中即返回，不消耗 LLM 调用。适合"翻译""编程"等明确场景。
2. 语义匹配（第二层）：将用户消息和智能体描述转为向量，计算相似度。适合模糊但语义相关的请求。
3. LLM 决策（第三层）：让 LLM 从候选智能体中选择最合适的一个。适合前两层都无法确定的复杂场景。

角色选择优先级策略

当三方通过 OpenAI 协议调用时，可能在请求中自带 system 提示词。角色选择优先级策略决定了：平台智能体的提示词、三方自带的提示词、租户全局提示词，三者如何组合成最终发给 LLM 的系统提示词。

假设以下素材：

1. role_first（平台角色优先，默认）

用户绑定了"翻译助手"：

你是一个专业翻译，擅长中英互译

用户自定义上下文：这是一篇技术文档

你是 XX 公司的 AI 助手

智能体提示词打头，三方提示词被丢弃，租户全局追加到末尾

用户没绑定智能体：

请将以下内容翻译成英文

用户自定义上下文：这是一篇技术文档

你是 XX 公司的 AI 助手

三方提示词兜底，租户全局追加到末尾

用户没绑定智能体 + 三方也没带提示词：

You are a helpful assistant.

你是 XX 公司的 AI 助手

全空时回退到默认兜底串

2. tenant_only（仅用租户配置）

不管用户绑没绑定智能体，都一样：

你是 XX 公司的 AI 助手

只保留租户全局，智能体提示词和三方提示词全部丢弃

3. external_first（三方提示词优先）

用户绑定了"翻译助手" + 三方带了提示词：

请将以下内容翻译成英文

用户自定义上下文：这是一篇技术文档

你是 XX 公司的 AI 助手

三方提示词赢，智能体提示词被完全忽略

用户绑定了"翻译助手" + 三方没带提示词：

你是一个专业翻译，擅长中英互译

用户自定义上下文：这是一篇技术文档

你是 XX 公司的 AI 助手

三方没带时才降级用智能体提示词

用户没绑定智能体 + 三方带了提示词：

请将以下内容翻译成英文

用户自定义上下文：这是一篇技术文档

你是 XX 公司的 AI 助手

用户没绑定智能体 + 三方也没带提示词：

You are a helpful assistant.

你是 XX 公司的 AI 助手

4. merge（合并模式）

用户绑定了"翻译助手"：

你是一个专业翻译，擅长中英互译

[补充上下文] 客户端补充上下文：请将以下内容翻译成英文

用户自定义上下文：这是一篇技术文档

你是 XX 公司的 AI 助手

智能体提示词打头，三方提示词降级为"[补充上下文]"标签拼接，全部保留

用户没绑定智能体：

[补充上下文] 客户端补充上下文：请将以下内容翻译成英文

用户自定义上下文：这是一篇技术文档

你是 XX 公司的 AI 助手

没有智能体提示词，只有三方补充上下文 + 自定义上下文

用户没绑定智能体 + 三方也没带提示词：

You are a helpful assistant.

你是 XX 公司的 AI 助手

5. strict（严格模式）

用户绑定了"翻译助手"：

你是一个专业翻译，擅长中英互译

用户自定义上下文：这是一篇技术文档

你是 XX 公司的 AI 助手

只用智能体提示词，三方提示词被忽略

用户没绑定智能体：

请求被拒绝，返回 400 错误：
"严格角色模式下未匹配到任何角色，请检查路由配置"

没匹配到智能体直接拒绝，不让请求通过

一句话总结各策略的设计意图：

什么时候该用什么策略

• role_first（默认）：大多数场景。平台智能体优先，三方作为兜底。适合你信任自己的智能体配置，但也要兼容三方不带智能体的请求。
• tenant_only：只用租户全局配置，忽略一切智能体和三方提示词。适合统一管控、不允许任何角色差异的场景。
• external_first：三方提示词优先。适合你主要作为"透传"平台，让调用方决定角色行为。
• merge：全都要。智能体提示词打头，三方提示词作为补充上下文。适合需要同时保留平台角色和三方上下文的场景。
• strict：必须有平台智能体，没有就拒绝。适合严格要求"未配置智能体不允许对话"的管控场景。

Token Counter（Token 统计）

这是什么

记录每次 LLM 调用的 Token 用量，支持每日限额熔断与多重 fallback 策略。禁用后停止统计与限额检查。

核心功能

• Token 计量：优先使用 LLM 返回的 usage 数据；LLM 未返回时，使用 tiktoken 本地计算；tiktoken 不可用时，按字符数估算（÷4）。
• 推理 Token 统计：可单独统计推理 Token（如 o1 系列模型的 reasoning tokens）。
• 每日限额熔断：可设置租户级每日 Token 上限，超限返回 429。用户级设置优先于租户级。
• 数据持久化：每次调用的 Token 用量写入数据库，支持按用户、模型、时间维度查询统计。

配置项

Hindsight Memory（事后记忆）

这是什么

对对话内容进行事后总结和记忆提取，在后续对话中注入相关记忆，提升多轮对话的连贯性。

核心功能

• 记忆提取：对话结束后，自动总结关键信息并存入记忆库。
• 记忆注入：后续对话时，自动检索相关记忆并注入上下文。
• 记忆库管理：支持按用户、智能体、工作空间维度隔离记忆。

Debug Conversation Dump（调试会话转储）

这是什么

将会话详细信息（消息、上下文、插件数据等）转储用于调试。开发排查问题时使用，生产环境建议禁用。

实际插件列表以界面显示为准。

怎么验证成功了

1. 启用插件后，插件卡片状态变为「已启用」
2. 配置插件后，再次打开配置抽屉能看到保存的配置
3. 插件功能正常工作（如Token Counter能正确统计）
4. 插件声明的系统任务出现在「系统任务」标签页中

常见问题

为什么看不到某个插件

插件代码由平台管理员部署，不能安装新插件。如果需要某个插件，请联系平台管理员。

启用插件后没效果

检查：

• 插件确实已启用
• 插件配置是否正确
• 插件优先级是否合适
• 系统日志中是否有插件执行错误

可以修改插件优先级吗

当前版本中，插件优先级由插件代码声明，管理员不能修改。如需调整，请联系平台管理员。

禁用插件后数据会丢失吗

不会。禁用插件仅停止后续执行，历史数据仍保留。

插件配置保存成功但行为没变化

可能是插件配置变更处理失败。请查看系统日志中的提示信息。

深入

核心概念

插件由平台加载

插件代码位于平台，由后端启动时自动加载。

租户管理员不能通过控制台上传、安装或卸载插件代码。可以管理的是当前租户维度：启用、禁用、配置、访问插件数据。

插件元信息

插件元信息包含：

• 名称
• 描述
• 版本
• 作者
• 优先级
• 感兴趣的钩子
• 默认启用标记
• 配置schema

启用判定

插件是否启用取决于插件名是否出现在 plugin_config 字典中。例如 hybrid_router 和 token_counter 出现在字典中即表示已启用。

配置schema

插件用config_schema描述前端表单。每个配置项包含：

• 配置键
• 表单标签
• 控件类型
• 默认值
• 说明
• 可选项
• 依赖条件

启用插件时，后端会按schema填充缺失默认值。

生命周期

禁用插件不应删除历史数据。

钩子分类

插件钩子分为三类：

1. ChatHook：用于聊天流程
2. EmbeddingHook：用于嵌入流程
3. ImageGenerationHook：用于图像生成流程

常见ChatHook：

• auth_completed：认证完成后
• config_loaded：配置加载完成后
• before_llm_call：LLM调用前
• after_llm_response：LLM响应后
• before_tool_exec：工具执行前
• after_tool_exec：工具执行后
• input_message_saved：输入消息保存后
• output_message_saved：输出消息保存后
• response_sent：响应发送后

执行顺序

插件按priority排序，数值越小越早执行。执行时会检查插件是否在当前租户启用。

插件抛出HTTPException时会继续向外抛出。

插件数据代理

插件可以提供数据代理接口，支持GET、PUT、POST、DELETE操作。访问前会确认当前租户已启用该插件。

插件定时任务

插件可以声明定时任务模板，服务启动时会注册为系统任务，任务类型为plugin_task，配置包含plugin_name和task_identifier。

已有插件

实际列表以界面显示为准。

权限边界

插件启停只影响当前租户。

注意事项

• default_enabled=true不等于已启用；最终看tenant.plugin_config
• 修改配置时传enabled=false会禁用插件
• 禁用后历史数据仍保留
• 配置保存成功但行为没变化，可能是配置变更处理失败
• 插件数据接口403通常表示插件未启用
• 插件数据接口404可能是插件不存在或path没有handler
• 插件不能运行时增减，新增代码需要重启服务
• 插件任务出现在系统任务中是自动注册结果
• 钩子执行顺序由priority决定，不是启用顺序
• Chat请求可能被插件抛出的HTTPException拒绝

排错速查

• 插件定时任务会出现在系统任务中，详见配置定时任务
• 部分通知功能可能需要插件支持，详见配置通知渠道
• 部分工作空间功能可能需要插件支持，详见工作空间协作