项目日志2：第二次进度总结

Cy_y_y

360人浏览 · 2026-04-30 14:30:45

Cy_y_y · 2026-04-30 14:30:45 发布

一、项目概述与目标

项目简介

本项目基于 xiaohongshu-mcp-python-master 源码开展二次开发，目标是构建一个可通过 MCP（Model Context Protocol）对接多类能力的系统，用于 AI 调度、内容创作以及平台操作与数据处理等场景。系统由多个模块组成，包括 AI Social Scheduler 调度核心和 xhs-content-generator-mcp 内容生成服务等。

技术架构

系统采用分层模块化架构，各层职责明确：

┌─────────────────────────────────────────────────────────────┐
│                      用户交互层                              │
│                   (FastAPI/Web/CLI)                         │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                       API 层                                │
│              (流式 API、RESTful API)                        │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                    图执行层                                  │
│          (LangGraph - 路由、节点编排、状态管理)               │
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Router     │  │    Graph     │  │   State     │     │
│  │   System     │→ │   Builder    │→ │   Manager   │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                     智能体层                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │ XHS Agent   │  │   Content    │  │   Publish    │     │
│  │             │  │   Agent     │  │   Agent      │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                    MCP 服务层                                │
│     (小红书浏览器自动化、图视频生成、内容生成服务)             │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                     平台适配层                               │
│                   (浏览器自动化/API调用)                       │
└─────────────────────────────────────────────────────────────┘

开发目标

搭建基础开发环境：配置 Python 环境、安装依赖、初始化项目结构
设计核心架构：基于 LangGraph 的分层模块化架构设计
实现基础组件：工作流引擎、路由系统、状态管理
开发内容生成服务：图片提示词生成、视频脚本/分镜生成
实现流式 API：支持实时进度展示
编写测试：确保核心功能的稳定性
系统集成与联调：各模块间的无缝协作

二、核心功能实现

1. AI Social Scheduler 调度核心

基于 LangGraph 的工作流引擎

LangGraph 是整个系统的核心，负责工作流的编排和状态管理。

状态管理设计：

使用 TypedDict 定义图状态，包含消息历史、任务信息、会话 ID 等
支持多轮交互和状态持久化
防止无限循环的迭代计数机制

图构建器实现：

动态构建 LangGraph，支持节点和边的灵活配置
集成子图作为节点，实现复杂工作流的模块化
支持条件路由，根据任务状态自动选择下一个节点

智能路由系统

路由系统采用混合策略，结合规则引擎和 LLM 分析：

支持的路由策略：

RULE_FIRST: 先尝试规则匹配，失败则使用LLM（推荐）
LLM_FIRST: 先使用LLM分析，失败则尝试规则
HYBRID: 同时使用规则和LLM，结合结果
LLM_ONLY: 只使用LLM
RULE_ONLY: 只使用规则

规则引擎：

基于关键词匹配和模式识别的快速路由
支持灵活的路由配置

意图分析器：

使用 LLM 进行复杂意图识别
Pydantic 模型约束 LLM 输出，确保结构化响应

流式 API 支持

使用 Server-Sent Events (SSE) 实现实时数据流：

SSE 协议实现：

正确配置 FastAPI 的 StreamingResponse
添加 Nginx 配置禁用缓冲
实现心跳机制保持连接活跃
添加错误处理和前端重连机制

流式执行器：

封装图执行并生成 SSE 事件
支持节点执行状态的实时推送
提供详细的事件类型和数据结构

小红书工作流子图

小红书工作流子图定义了完整的内容生成到发布流程：

工作流状态定义：

包含输入参数、中间状态和输出结果
支持内容生成、图片生成和发布三个主要步骤

节点函数实现：

内容生成节点：调用 XHSContentAgent 生成小红书内容大纲
图片生成节点：调用 XHSImageAgent 生成配图
发布节点：调用 XHSPublishAgent 发布到小红书

条件路由：

根据 should_publish 标志和前面步骤的执行结果，决定是否进入发布节点

2. xhs-content-generator-mcp 内容生成服务

图片提示词生成工具

功能：输入正文+人设，输出 2-4 条配图 prompt

实现：

读取提示词模板 lifestyle_image_prompts_prompt.txt
调用 LLM 生成 JSON 数组并解析归一化
提供 MCP 工具接口 generate_xhs_image_prompts

通用 JSON 提取工具

功能：从模型输出中提取第一个 JSON 对象/数组，处理常见 ```json fence

实现：

支持提取 JSON 对象和数组
处理代码围栏和不平衡括号
提供统一的提取结果格式

三、开发进度评估

已完成工作

AI Social Scheduler 调度核心：
- 基于 LangGraph 的工作流引擎实现
- 智能路由系统（规则引擎 + LLM 意图分析）
- 流式 API 支持（SSE 协议实现）
- 小红书工作流子图（内容生成 → 图片生成 → 发布）
xhs-content-generator-mcp 内容生成服务：
- 图片提示词生成工具（MCP tool 已注册）
- 视频脚本/分镜生成工具（MCP tool 已注册）
- 服务层封装与提示词模板落库
- 通用 JSON 提取工具
- 单元测试（mock）覆盖核心解析与最小结构校验

未完成工作

系统集成与联调：
- 与 xhs-image-mcp、xhs-video-mcp 的端到端联调
- 跨服务调用、参数对齐
- 异步任务化（特别是视频生成可能需要 task_id / 状态查询）
功能增强：
- 输出质量控制（更严格的 schema 校验、长度/敏感/合规规则）
- 异常分支测试（非 JSON、空数组、缺 scenes、截断等）
- CI/本地形成一条“无需密钥也能跑”的基础测试链路
性能与稳定性：
- 性能优化（响应时间、资源占用）
- 稳定性增强（错误处理、重试机制）
- 扩展性提升（支持更多平台和服务）

四、技术挑战与解决方案

LangGraph 版本兼容性

现象：安装依赖时出现版本冲突，LangGraph 与其他依赖包版本不兼容

原因分析：

LangGraph 作为新兴框架，版本更新频繁，API 变化较大
与 LangChain 等依赖包存在严格的版本依赖关系
不同版本的 API 接口存在显著差异，例如异步接口的变化

解决方案：

固定 LangGraph 版本为 0.3.0
确保 LangChain 版本与 LangGraph 兼容（0.2.x 系列）
使用 uv 包管理器管理依赖版本，解决冲突
在 pyproject.toml 中明确指定所有依赖版本

流式输出实现

现象：实现流式输出时，前端无法正确接收事件数据，连接经常中断

原因分析：

SSE 协议要求特定的响应格式和编码
FastAPI 的流式响应配置不正确
Nginx 代理会缓冲响应，导致实时性降低
缺少心跳机制，连接可能超时

解决方案：

正确配置 FastAPI 的 StreamingResponse
添加 Nginx 配置禁用缓冲
实现心跳机制保持连接活跃
添加错误处理和前端重连机制

状态管理与持久化

现象：工作流执行过程中状态丢失，无法恢复执行，多轮对话时上下文丢失

原因分析：

LangGraph 使用内存存储状态，服务重启后丢失
状态检查点机制配置不正确
多用户并发时状态混淆

解决方案：

配置 MemorySaver 作为检查点
实现基于 Redis 的状态持久化（待实现）
使用 thread_id 和 user_id 隔离不同用户的状态
添加状态变更日志，便于调试和问题定位

MCP 服务集成

现象：不同 MCP 服务之间的接口调用和参数传递存在差异

原因分析：

各服务的接口设计和参数定义不一致
服务间的依赖关系复杂
错误处理和异常传递机制不完善

解决方案：

统一 MCP 服务接口规范
实现服务间的参数映射和转换
建立统一的错误处理机制
添加服务健康检查和监控

五、预期完成后的任务

系统集成与联调

跨服务调用：
- 实现 xhs-content-generator-mcp 与 xhs-image-mcp、xhs-video-mcp 的无缝集成
- 统一参数传递和返回格式
- 建立服务间的依赖管理和版本控制
端到端测试：
- 构建完整的测试用例，覆盖所有核心流程
- 实现自动化测试脚本，确保系统稳定性
- 建立 CI/CD 流水线，实现持续集成和部署
监控与日志：
- 实现系统级监控，包括服务健康状态、响应时间、错误率等
- 建立统一的日志系统，便于问题定位和分析
- 实现告警机制，及时发现和处理系统异常

性能与稳定性优化

性能优化：
- 优化 LLM 调用，减少响应时间
- 实现缓存机制，避免重复计算
- 优化数据库查询和存储操作
- 实现负载均衡，提高系统并发处理能力
稳定性增强：
- 完善错误处理和重试机制
- 实现服务降级和熔断策略
- 加强系统安全防护，防止恶意攻击
- 建立灾备方案，确保系统高可用性
扩展性提升：
- 设计插件机制，支持新功能的快速集成
- 实现配置化管理，便于系统参数调整
- 支持多语言和多平台扩展
- 建立开放 API，便于第三方集成