将edu-rpa-system的文档导入功能集成到deer-flow右侧工作区的完整分析和实施指南

本项目包含4份核心文档，按阅读顺序如下：

• 用途：5分钟速览、文件清单、快速步骤
• 适合：快速了解项目规模和方向
• 篇幅：短（2页）

• 用途：两个项目的架构分析、集成方案对比、技术决策
• 适合：技术主管、架构师决策
• 篇幅：中（10页）

• 用途：每个文件具体如何修改，含完整代码示例
• 适合：开发人员实施
• 篇幅：长（20页）

• 用途：每个文件的修改点详细说明，带检查点
• 适合：开发人员逐项检查
• 篇幅：最长（30页，检查表格式）

---

• deer-flow 是一个AI研究助手，可以在右侧工作区展示研究过程
• edu-rpa-system 是一个教育RPA系统，有成熟的文档导入和解析功能
• 目标：将文档导入集成到deer-flow中，充分利用两个项目的优势

推荐方案：深集成（方案B）

指标	数值
文件修改数	15个（后端3+前端7+新增5）
代码改动量	约800行（新增400+修改400）
实施时间	12-18小时
技术难度	中等
风险等级	低

✅ 用户在Chat中发送"导入文件"请求 ✅ 右侧工作区实时显示导入进度（0-100%） ✅ 完成后预览提取的结构化数据 ✅ 支持复制和下载结果 ✅ 与现有"研究"功能并行运行

---

• 🔄 SSE实时流（比轮询更优雅）
• 📦 Zustand状态管理（简单高效）
• 🎨 组件库完善（UI组件复用）
• 📱 响应式布局（自适应右侧面板）
• 🔗 LangGraph Agent框架（多agent协作）

• 📚 文件验证逻辑（完整的格式和大小检查）
• 🔄 Mineru集成（DOCX/PDF转Markdown）
• 🤖 LLM解析（使用LangGraph生成JSON）
• 📈 进度追踪（ImportTask数据模型）

• 🚀 SSE实时 + Agent框架 = 更好的用户体验
• 🎯 独立的ImportDoc状态 = 与现有功能不冲突
• 🔀 右侧面板共享 = 界面简洁统一
• 📨 消息流集成 = 所有信息都可追溯

---

• 框架：Next.js 15, React 19
• 状态管理：Zustand
• UI组件：Ant Design, Radix UI
• 动画：Framer Motion
• 类型：TypeScript
• 新增：File Upload, Progress Display, Data Preview

• 框架：FastAPI
• Agent框架：LangGraph
• 异步：原生async/await (SSE流)
• 模型：Claude/OpenAI (可配置)
• 新增：DocumentImporter Agent, Upload Endpoint

---

• Python 3.9+
• Node.js 18+
• pip和npm包管理
• Git版本控制

# 1. 读一遍QUICK_START.md (5分钟)
# 2. 按INTEGRATION_GUIDE.md实施代码改动 (3小时)
# 3. 按IMPLEMENTATION_CHECKLIST.md逐项检查 (1小时)
# 4. 运行测试验证 (1小时)
# 5. 提交PR进行审查 (30分钟)

---

✅ 新增：backend/src/agents/document_importer.py
  - 定义DocumentImportState类
  - 实现upload/parse/extract/complete四个节点
  - 构建完整的LangGraph

📝 修改：backend/src/agents/coordinator.py
  - 在route_to_agent中添加导入关键词识别
  - 路由到document_importer (只需5行)

📝 修改：backend/src/api/routers/chat.py
  - 添加POST /api/chat/upload-document端点
  - 文件保存和返回document_id (只需20行)

✅ 新增：web/src/core/documents/types.ts
  - 定义ImportDoc interface
  - 完整的类型系统 (~30行)

📝 修改：web/src/core/store/store.ts
  - 添加importDocument相关状态
  - 实现appendImportDoc/updateImportDoc等方法 (+40行)

✅ 新增：web/src/app/chat/components/file-upload-panel.tsx
  - 拖拽上传UI组件
  - 文件验证和上传逻辑 (~120行)

✅ 新增：web/src/app/chat/components/document-import-block.tsx
  - 右侧工作区导入面板
  - 数据预览、文件信息、操作按钮 (~200行)

📝 修改：web/src/app/chat/main.tsx
  - 导入DocumentImportBlock
  - 修改双列布局逻辑 (+10行)

📝 修改：web/src/core/messages/merge-message.ts
  - 处理document_import工具调用事件
  - 更新Store进度 (+30行)

📝 修改：web/src/app/chat/components/research-activities-block.tsx
  - 添加DocumentImportToolCall组件
  - 消息流中显示导入卡片 (+80行)

---

用户输入"导入文件" (Chat)
    ↓
Coordinator判断意图
    ↓
Router → document_importer agent
    ↓
Agent工作流
  1. upload_and_parse_node - 验证并解析
  2. extract_content_node - 提取结构化内容
  3. structure_data_node - 使用LLM生成JSON
    ↓
SSE消息流推送（实时）
  - tool_calls: {id, name: "document_import", ...}
  - tool_call_result: {status: "uploading", progress: 0}
  - tool_call_result: {status: "parsing", progress: 30}
  - tool_call_result: {status: "completed", data: {...}}
    ↓
前端mergeMessage处理每个事件
    ↓
Store.updateImportDoc更新状态
    ↓
React自动重渲染
  - 消息列表：显示DocumentImportCard
  - DocumentImportCard：显示进度、状态
    ↓
用户点击"查看"
    ↓
openImport() 打开右侧工作区
    ↓
DocumentImportBlock显示
  - 数据预览 (JSON格式)
  - 文件信息 (名字、类型、进度)
  - 操作按钮 (复制、下载)

---

用户：
  💬 "帮我导入这个Excel文件，提取课程信息"

系统：
  📝 识别导入意图
  📂 显示文件上传面板

用户：
  📁 拖拽或点击选择文件 (teaching_plan.xlsx)

系统：
  ⬆️ 上传文件到后端
  📊 显示上传进度（0% → 100%）

系统（后台）：
  ✓ 接收文件
  ✓ 转换为Markdown
  ✓ 提取章节
  ✓ 使用LLM解析
  ✓ 生成JSON

系统（前端）：
  ⏳ 显示处理中 (parsing → extracting)
  🎉 处理完成，显示进度100%

右侧工作区：
  📋 显示提取的数据
  - 课程列表
  - 学分分配
  - 毕业要求

用户操作：
  📋 数据预览 → JSON格式显示
  📋 文件信息 → 上传时间等
  💾 复制 → 复制到剪贴板
  📥 下载 → 保存为json文件

---

• 文件上传（支持PDF, Word, Excel）
• 进度实时显示（0-100%）
• 数据预览和操作（复制、下载）
• 右侧工作区切换（导入↔研究）

• 50MB文件上传稳定
• Store更新响应 < 100ms
• 无内存泄漏

• 不支持的文件类型拒绝
• 文件过大提示
• 上传失败重试
• 网络中断恢复

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

---

• 创建DocumentImporterAgent (1.5小时)
• 修改Coordinator路由 (0.5小时)
• 添加API端点 (1小时)
• 后端测试 (1小时)

• 定义类型系统 (0.5小时)
• Store扩展 (1小时)
• UI组件开发 (3小时)
• 消息处理集成 (1.5小时)
• 前端测试和调试 (2.5小时)

• 端到端测试 (1.5小时)
• 性能优化 (1小时)
• 代码审查 (1小时)
• 文档编写 (1.5小时)

---

• LangGraph官方文档
• Zustand状态管理
• Next.js文件上传

• deer-flow源码
• edu-rpa-system源码

• 消息流设计：见merge-message.ts的事件处理逻辑
• Agent设计：见backend/src/agents/下的各个Agent
• UI设计：见research-activities-block.tsx的卡片样式

---

• 使用TypeScript严格模式
• 添加JSDoc注释
• 遵循现有命名规范
• 单位测试覆盖率 > 80%

1. 创建feature分支：git checkout -b feature/document-import
2. 按INTEGRATION_GUIDE.md实施代码
3. 运行npm run type-check和npm run build
4. 提交PR并申请代码审查
5. 合并到main分支

---

Q: 为什么不复用edu-rpa-system的整个导入系统？ A: 因为deer-flow的架构不同（SSE vs Celery），复用组件经验更好。

Q: 能否同时进行多个导入？ A: 可以。右侧面板同一时刻显示一个，但Store中可存储多个importDoc。

Q: 刷新页面会丢失数据吗？ A: 是的，因为用的是内存Map。需要持久化的话可改为IndexedDB或数据库。

Q: 如何处理大文件？ A: 当前支持50MB。更大的文件可考虑分块上传或Web Worker。

---

指标	数值
新增代码行数	~400
修改代码行数	~400
总代码改动	~800
修改文件数	15
新增文件数	5
修改文件数	10
预计开发时间	12-18小时
预计测试时间	3-4小时
总预计时间	15-22小时

---

所有以下条件都必须满足：

• TypeScript零错误（npm run type-check）
• 构建成功（npm run build）
• 所有功能测试通过
• 代码审查通过
• 文档完整
• 无breaking changes

---

同deer-flow项目保持一致

---

• 技术支持：见各文档中的Q&A部分
• 问题提交：GitHub Issues
• 代码审查：GitHub Pull Requests

---

README_INTEGRATION.md  ← 你在这里
│
├─→ QUICK_START.md              (5分钟速览)
├─→ ANALYSIS_SUMMARY.md         (架构和决策)
├─→ INTEGRATION_GUIDE.md        (实施参考)
└─→ IMPLEMENTATION_CHECKLIST.md (逐项检查)

---

状态：✅ 文档完整，建议采用 版本：1.0 最后更新：2024-11-16

准备开始？ 👉 先读 QUICK_START.md！