Pavo AI Agent v2.3 技术深度解析MCP Server Memory RAG 可视化管线的工程实践开源地址https://github.com/yanzhao77/pavo-ai-agent | MIT 协议一、项目背景Pavo AI Agent 是一个开源的多智能体视频分镜生成平台。输入一段自然语言故事系统通过 7 个 AI Agent 协作自动输出完整的逐镜头分镜脚本支持对接 AI 视频模型生成视频。v1.0 完成了核心管线v2.0 引入了 MCP Server。v2.3 是至今最大的一次架构升级新增了三个核心模块MCP Server 完整层— 12 个 Tools / 5 个 Resources / 2 个 PromptsAgent Memory RAG 知识库— 个性化创作记忆 影视专业知识注入Workflow 可视化— SVG 管线图实时展示 7 Agent 执行状态本文从工程实践角度深度解析这三个模块的设计思路和实现细节。二、MCP Server 层让 AI 工具能看见Pavo2.1 为什么是 MCPMCP (Model Context Protocol) 由 Anthropic 主导定义了 AI 模型与外部工具的标准化交互接口。类比 USB-C 为硬件外设提供的统一接口MCP 为 AI 应用提供了统一的工具集成标准。在 v2.3 中Pavo MCP Server 作为一个独立 Python 进程运行通过 stdio/SSE 与 MCP 客户端通信通过数据库 Session 直接读取数据。2.2 模块结构backend/mcp_server/ ├── main.py # 入口12 个 Tools / 5 个 Resources / 2 个 Prompts ├── models/mcp_schemas.py # MCPToolResult MCPError 统一格式 ├── memory/ # Memory 存储 Embedding 重要性评分 ├── rag/ # RAG 检索 Re-ranker 知识库构建 ├── middleware/memory_middleware.py # 透明上下文注入三级降级 ├── tools/memory_tools.py # 4 个 Memory Tool └── adapter/project_adapter.py # 桥接现有 ProjectService2.3 核心代码实现统一返回格式是所有 MCP Tool 的基础classMCPToolResult(BaseModel):success:booldata:dict|list|NoneNoneerror:MCPError|NoneNoneclassmethoddefok(cls,dataNone)-MCPToolResult:returncls(successTrue,datadata)classmethoddeffail(cls,code:str,message)-MCPToolResult:returncls(successFalse,errorMCPError(codecode,messagemessage))MCP Server 注册 Tools精简示例server.list_tools()asyncdeflist_tools():return[{name:pavo_create_project,description:创建项目并启动 Agent 管线,inputSchema:{type:object,properties:{input:{type:string,description:故事创意文本},context:{type:object,description:系统内部使用},},required:[input]}},# ... 共 12 个 Tools]Memory Middleware 透明注入是 v2.3 的核心架构创新classMemoryMiddleware:asyncdefpre_process(self,tool_name:str,arguments:dict)-dict:拦截 Tool 调用自动注入用户历史记忆user_idarguments.get(user_id,)ifnotuser_id:returnargumentstry:memoriesawaitstore.search_memory(user_id,tool_name,limit3)arguments[context][memory]{items:memories}exceptMemoryUnavailableError:# 级别 1 降级记录日志继续执行passreturnarguments2.4 12 个工具总览类别工具说明优先级项目pavo_create_project创建项目并启动管线P0项目pavo_get_project获取项目完整数据P0项目pavo_list_projects获取项目列表P1分镜pavo_generate_storyboard重新生成模块P0视频pavo_render_video触发视频渲染P1视频pavo_get_video_status查询视频状态P1导出pavo_export_project导出项目P1认证pavo_auth_login获取 TokenP1记忆pavo_save_memory保存用户偏好P0记忆pavo_search_memory检索历史记忆P0记忆pavo_list_memories列出记忆P1记忆pavo_delete_memory删除记忆P12.5 Cursor 集成配置{mcpServers:{pavo:{command:python,args:[-m,mcp_server.main],env:{AGNES_API_KEY:sk-xxx,DATABASE_URL:postgresqlasyncpg://...}}}}三、Agent Memory RAG 系统让 AI 记住用户并注入专业知识3.1 双层记忆架构Layer 1: Session Memory (短期) ┌─────────────────────────────────────┐ │ Redis · TTL 30 分钟 · 滑动窗口刷新 │ │ 对话历史 · 当前上下文 · 临时状态 │ └──────────────┬──────────────────────┘ │ 会话结束 → 自动提取重要信息 ▼ Layer 2: User Memory (长期) ┌─────────────────────────────────────┐ │ PostgreSQL pgvector (1536 维) │ │ 6 种类型style/character/scene/ │ │ preference/story_arc/feedback│ │ 重要性评分 自动清理 │ └─────────────────────────────────────┘3.2 重要性评分策略记忆并非同等重要。v2.3 实现了三种来源的评分策略classImportanceStrategy:staticmethoddeffrom_user_saved()-float:用户主动保存 → 高重要性 0.9return0.9staticmethoddeffrom_auto_extracted(mentions,recency_days)-float:自动提取 → min(0.3 mentions*0.1 - recency*0.01, 0.8)returnmin(0.3mentions*0.1-recency_days*0.01,0.8)staticmethoddeffrom_feedback_derived(rating:str)-float:反馈衍生 → 好评 0.7 / 差评 0.2return0.7ifratingupelse0.2低重要性记忆 0.2超过 30 天未访问自动清理。3.3 RAG 影视知识库知识库包含60 条影视专业知识覆盖 6 大类类别条目数示例内容镜头语言15景别定义、运镜方式、构图规则电影语法10180 度规则、视线匹配经典案例10经典电影分镜分析叙事结构8三幕剧、起承转合类型模板7爱情/悬疑/动作片分镜模式BGM 与音效10各种情绪的配乐建议检索 Pipeline用户输入 → RAGQueryBuilder → Embedding (1536维) → pgvector ANN (IVFFlat索引) → Re-ranker (category匹配 priority加权) → Context Injector → Agent Prompt注入目标Storyboard Agent 为主强制注入Character/Scene Agent 为辅相关性 0.7 时注入。3.4 ORM 数据模型classUserMemoryORM(Base):__tablename__user_memoriesidColumn(UUID,primary_keyTrue)user_idColumn(String(64),indexTrue)memory_typeColumn(String(32))# style/character/...contentColumn(JSON)# 记忆内容结构化embeddingColumn(JSON)# 1536 维向量importanceColumn(Float,default0.5)# 重要性评分sourceColumn(String(32))# 来源tagsColumn(JSON)# 标签created_atColumn(DateTime)updated_atColumn(DateTime)accessed_atColumn(DateTime)四、Workflow 可视化从文本日志到 SVG 管线图4.1 设计思路v2.3 之前Agent 管线的执行状态通过文本日志展示[Planner] Analyzing story... ✓ [Character] Generating characters... ✓信息密度低缺乏直观性。v2.3 的 WorkflowVisualizer 组件用 SVG 管线图替代。4.2 技术选型方案优点缺点选择理由纯 SVG CSS轻量、可控、无额外依赖需手写布局拓扑固定7 节点线性无需动态布局React Flow功能强大、拖拽编辑包体积大项目不需要交互编辑ECharts图表丰富过重数据可视化为主结论纯 SVG 方案最适合——7 个节点线性 DAG布局固定轻量可维护。4.3 组件结构WorkflowVisualizer ├── PipelineGraph # SVG 管线图 贝塞尔曲线连线 │ └── AgentNode × 7 # 状态色编码节点 ├── AgentDetailPanel # 点击弹窗输入/输出/耗时/错误 └── TimelineView # 横向条形图各 Agent 耗时比例状态色映射状态颜色图标CSS 实现idle#9CA3AF 灰色○background 静态running#3B82F6 蓝色◉CSS animation spincompleted#10B981 绿色✓background 静态failed#EF4444 红色✗CSS animation shakeskipped#D1D5DB 浅灰—opacity 0.5五、工程实践总结5.1 架构演进v1.0: FastAPI 7 Agents Next.js —— 核心管线 v2.0: MCP Server (8 Tools) —— 标准化接口 v2.3: Memory RAG MCP 扩展 —— 智能增强 Workflow 可视化 —— 体验提升5.2 关键设计原则向后兼容新功能不破坏现有 API非侵入集成Memory Middleware 对 Tool handler 零侵入可观测性6 项 Middleware 指标 5 个性能基准场景可控降级Memory/RAG 不可用时不影响核心功能5.3 统计数据指标数值对比 v1.0后端源文件259MCP Tools1212数据库表63测试用例1616种子知识6060GitHub Stars期待你的 ⭐—六、快速体验gitclone https://github.com/yanzhao77/pavo-ai-agent.gitcdpavo-ai-agentcp.env.example .env# 设置 AGNES_API_KEYdockercompose up-dpostgres redis miniocdbackendpipinstall-rrequirements.txt python-muvicorn app.main:app--reload--port8000# 新终端启动 MCP Servercdbackendpython-mmcp_server.main# 新终端启动前端cdfrontendnpminstallnpmrun dev项目地址https://github.com/yanzhao77/pavo-ai-agent如果本文对你有帮助欢迎 ⭐ Star 支持