插件管理
插件用于扩展聊天流程、路由逻辑、统计能力和后台任务。管理员可以管理当前的插件启用状态和配置，但不能动态安装插件代码。
什么时候用
- 需要智能路由对话到不同模型/Agent时（如Hybrid Router）
- 需要统计Token使用情况时（如Token Counter）
- 需要事后分析对话内容时（如Hindsight Memory）
- 需要调试会话转储时（如Debug Conversation Dump）
- 需要查看插件钩子信息时
- 需要调整插件执行优先级时
你需要准备
- （管理员）只有管理员可以管理插件
- 插件代码已由平台管理员部署和加载（不能安装插件代码）
操作步骤
第 1 步：进入插件管理
左侧菜单 -> 插件管理。
页面显示：
- 搜索框：按插件名称或描述搜索
- 筛选器：筛选「已启用」或「已禁用」插件
- 排序：按「优先级」或「名称」排序
- 插件卡片网格
第 2 步：查看插件卡片
每个插件卡片显示：
- 插件名称
- 描述
- 版本和作者
- 当前状态（已启用/已禁用）
- 优先级
- 操作按钮：配置、查看钩子、启用/禁用
第 3 步：启用/禁用插件
在插件卡片上点击「启用」或「禁用」开关：
- 启用：插件按优先级参与执行
- 禁用：不再参与执行（但保留历史数据）
禁用插件不会删除历史数据。
第 4 步：配置插件
- 在插件卡片上点击「配置」按钮，打开配置抽屉
- 根据插件配置表单填写配置项
- 点击「保存」
启用插件时，系统会自动填充缺失的默认值。
第 5 步：查看钩子信息
- 在插件卡片上点击「查看钩子」按钮，打开钩子弹窗
- 查看该插件声明关注的钩子
- 了解每个钩子的触发时机
常见钩子：
auth_completed：认证完成后before_llm_call：LLM调用前after_llm_response：LLM响应后before_tool_exec：工具执行前after_tool_exec：工具执行后response_sent：响应发送后
第 6 步：调整排序
在页面顶部的「排序」下拉框中选择：
- 优先级：按插件优先级数值排序，数值越小越早执行
- 名称：按插件名称字母序排序
第 7 步：查看插件系统任务
部分插件会声明定时任务，这些任务会作为系统任务出现：
左侧菜单 -> 定时任务 -> 「系统任务」标签页。
可以：
- 查看插件注册的系统任务
- 启用/禁用（部分任务可能不允许禁用）
- 查看执行历史
常见插件举例
Hybrid Router
关键词、正则、语义混合路由，根据用户消息自动路由到合适的模型或Agent。
Token Counter
Token统计，跟踪对话的Token使用情况，支持按用户维度统计。
Hindsight Memory
事后分析，对对话内容进行事后总结和记忆提取。
Debug Conversation Dump
调试会话转储，将会话详细信息转储用于调试。
实际插件列表以界面显示为准。
怎么验证成功了
- 启用插件后，插件卡片状态变为「已启用」
- 配置插件后，再次打开配置抽屉能看到保存的配置
- 插件功能正常工作（如Token Counter能正确统计）
- 插件声明的系统任务出现在「系统任务」标签页中
常见问题
为什么看不到某个插件
插件代码由平台管理员部署，不能安装新插件。如果需要某个插件，请联系平台管理员。
启用插件后没效果
检查：
- 插件确实已启用
- 插件配置是否正确
- 插件优先级是否合适
- 系统日志中是否有插件执行错误
可以修改插件优先级吗
当前版本中，插件优先级由插件代码声明，管理员不能修改。如需调整，请联系平台管理员。
禁用插件后数据会丢失吗
不会。禁用插件仅停止后续执行，历史数据仍保留。
插件配置保存成功但行为没变化
可能是插件配置变更处理失败。请查看系统日志中的提示信息。
深入
核心概念
插件由平台加载
插件代码位于平台，由后端启动时自动加载。
租户管理员不能通过控制台上传、安装或卸载插件代码。可以管理的是当前租户维度：启用、禁用、配置、访问插件数据。
插件元信息
插件元信息包含：
- 名称
- 描述
- 版本
- 作者
- 优先级
- 感兴趣的钩子
- 默认启用标记
- 配置schema
启用判定
插件是否启用取决于插件名是否出现在 plugin_config 字典中。例如 hybrid_router 和 token_counter 出现在字典中即表示已启用。
配置schema
插件用config_schema描述前端表单。每个配置项包含：
- 配置键
- 表单标签
- 控件类型
- 默认值
- 说明
- 可选项
- 依赖条件
启用插件时，后端会按schema填充缺失默认值。
生命周期
| 阶段 | 触发时机 | 异常行为 |
|---|---|---|
| 全局启动 | 服务启动 | 单插件失败不阻塞其它插件 |
| 全局关闭 | 服务关闭 | 记录错误 |
| 租户启用 | 从禁用变启用 | 异常冒泡 |
| 租户禁用 | 从启用变禁用 | 异常冒泡 |
| 配置变更 | 已启用插件修改配置 | 异常静默忽略并记录warning |
禁用插件不应删除历史数据。
钩子分类
插件钩子分为三类：
- ChatHook：用于聊天流程
- EmbeddingHook：用于嵌入流程
- 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。
已有插件
| 插件 | 说明 |
|---|---|
| debug_conversation_dump | 调试会话转储 |
| hybrid_router | 关键词、正则、语义混合路由 |
| token_counter | Token统计 |
| hindsight | 事后分析 |
实际列表以界面显示为准。
权限边界
| 操作 | 租户 admin | 平台管理员 |
|---|---|---|
| 查看可用插件 | 可以 | 可以 |
| 查看本租户插件状态 | 可以 | 可以 |
| 启用本租户插件 | 可以 | 可以 |
| 禁用本租户插件 | 可以 | 可以 |
| 修改本租户配置 | 可以 | 可以 |
| 动态安装插件代码 | 不可以 | 不通过租户控制台 |
| 动态卸载插件代码 | 不可以 | 不通过租户控制台 |
| 访问未启用插件数据 | 不可以，403 | 也应先启用 |
| 访问不存在插件 | 404 | 404 |
| 查看其它租户配置 | 不可以 | 可按平台权限处理 |
| 管理插件系统任务 | 配置本租户启停 | 可维护系统任务 |
插件启停只影响当前租户。
注意事项
- default_enabled=true不等于已启用；最终看tenant.plugin_config
- 修改配置时传enabled=false会禁用插件
- 禁用后历史数据仍保留
- 配置保存成功但行为没变化，可能是配置变更处理失败
- 插件数据接口403通常表示插件未启用
- 插件数据接口404可能是插件不存在或path没有handler
- 插件不能运行时增减，新增代码需要重启服务
- 插件任务出现在系统任务中是自动注册结果
- 钩子执行顺序由priority决定，不是启用顺序
- Chat请求可能被插件抛出的HTTPException拒绝
排错速查
| 症状 | 可能原因 |
|---|---|
| 插件列表缺少插件 | 后端未加载 |
| 租户状态未启用 | plugin_config无插件名 |
| 启用返回404 | 插件名错误 |
| 启用失败 | on_tenant_enable异常 |
| 禁用失败 | on_tenant_disable异常 |
| 配置无效果 | on_config_changed异常 |
| 数据接口403 | 插件未启用 |
| 数据接口404 | handler不存在 |
| Chat被拒绝 | 插件抛HTTPException |
| 插件任务没出现 | 启动注册失败或未声明 |
| 任务不能禁用 | allow_tenant_disable=false |