Gemini Manifold 插件开发哲学

概览

源码位于 plugins/pipes/gemini_mainfold/gemini_manifold.py，作为 Open WebUI 的 Pipe 插件，主要负责把前端的请求转化成 Google Gemini/Vertex AI 的调用，并将结果通过 AsyncGenerator 回流给前端。
插件采用了 Valves + UserValves 的配置模式、异步事件与状态汇报、细粒度日志、文件缓存与上传中间件，以及统一响应处理器，充分体现了 Open WebUI 通用插件的开发模式。

Pipe 类（入口）
- pipes 方法注册可选模型，缓存模型列表并仅在配置变更时刷新。
- pipe 方法为每个请求建立 Google GenAI 客户端、EventEmitter 与 FilesAPIManager，构建 GeminiContentBuilder，并统一把返回值交给 _unified_response_processor。
GeminiContentBuilder（请求构建）
- 解析 Open WebUI 消息、引用历史、文件上传、YouTube/Markdown 媒体等内容，并通过 UploadStatusManager 与 FilesAPIManager 协作，确保上传进度可视。
FilesAPIManager（文件缓存+上传）
- 采用 xxHash 内容地址、热/暖/冷路径、自定义锁、 TTL 缓存等手段防止重复上传，同时会在发生错误时用 FilesAPIError 抛出并告知前端。
EventEmitter + UploadStatusManager（状态反馈）
- 抽象 Toast/Status/Completion 的交互，按需异步发送，赋予前端实时反馈能力，避免阻塞主流程。
统一响应处理与后置处理
- _unified_response_processor 兼容流式/一次性响应，调用 _process_part、_disable_special_tags 保护前端，再在 _do_post_processing 发出 usage、grounding 等数据。

配置层叠与安全：Valves 提供 admin 默认，UserValves 允许用户按需覆盖。USER_MUST_PROVIDE_AUTH_CONFIG + AUTH_WHITELIST 确保敏感场景必须使用各自凭证。
异步状态与进度可视：所有上传/调用都在 EventEmitter 中报告 toast/status，UploadStatusManager 用 queue 追踪并呈现进度，流式响应直接产出 choices chunk 与 [DONE]，前端无需额外猜测。
功能可拓展性：基于 Functions.get_function_by_id 检查 filter、依据 features/toggle 开启 Search、Code Execution、URL Context、Maps grounding，体现 Open WebUI 组件可组合的插件模型。
文件与资源复用：FilesAPIManager 通过 deterministic name、缓存、stateless GET，提高效率；生成图片也回写到 Open WebUI 的 Files 模型，为前端提供可持久化的 URL。
透明日志与错误可控：自定义 loguru handler（截断 payload）、统一的异常类、对 SDK 错误的 toast+error emission、对特殊 tag 的 ZWS 处理，确保插件运行时的状态始终可追踪并兼容前端。
统一流程：全链路从 request -> builder -> client -> response processor -> post-processing，严格对齐 Open WebUI pipe+filter 结构，便于扩展和维护。

详细的代码示例与使用场景请参见 docs/gemini_manifold_plugin_examples.md，包括：