hg-agents/PLAN.md

Enterprise AI Platform - 开发规划

基于对 backend、frontend 全部代码和 ENTERPRISE_PLAN.md 的详细审查 日期: 2026-05-11

---

一、项目现状总览

1.1 整体评估

维度	完成度	说明
后端 CRUD API	80%	路由完整，但多个模块是 Mock/Stub 实现
Agent 功能	20%	Agent 框架有了，但工具全是 [模拟] 占位返回
流编排引擎	30%	框架完整，但所有节点类型都返回 Mock 数据
前端页面	40%	页面骨架都在，但大量只有展示/空白页，缺少交互表单
MCP 集成	50%	注册管理完整，但在流引擎中是 Mock
RAG	0%	仅有 Mock 节点，无真实 embedding/向量存储
企微集成	60%	回调+发送骨架存在，但工具是 Mock

1.2 后端模块功能矩阵

模块	文件	列表	创建	更新	删除	详情	真实度
Auth	modules/auth/router.py	-	✅ login	-	-	✅ me	真实
Org/部门	modules/org/router.py	✅	✅	✅	✅	-	真实
Org/用户	modules/org/router.py	✅	✅	✅	-	✅	真实
RBAC/角色	modules/rbac/router.py	✅	✅	✅	✅	✅	真实
RBAC/权限	modules/rbac/router.py	✅	-	-	-	-	真实
Task	modules/task/router.py	✅	✅	✅	-	✅	真实
Flow	modules/flow_engine/	✅	✅	✅	✅	✅	半真实 (引擎内节点 Mock)
Agent	modules/agent_manager/	✅	✅ chat	-	-	✅ history	半真实 (工具 Mock)
MCP	modules/mcp_registry/	✅	✅	✅	✅	✅	真实
Document	modules/document/	-	✅ upload	-	✅	✅ parse	半真实 (文档解析无真实库)
Monitor	modules/monitor/router.py	✅	-	-	-	✅ dashboard	真实 (但依赖真实数据)
WeCom	modules/wecom/router.py	-	✅ 回调	-	-	✅ config	半真实 (工具 Mock)
Notification	modules/notification/	✅ 模板	✅	-	✅	-	真实 (WebSocket)
Audit	modules/audit/router.py	✅ 分页	-	-	-	-	真实
System	modules/system/	✅ 指标	-	-	-	✅ health	真实

1.3 前端页面功能矩阵

页面	路由	文件	展示列表	创建表单	编辑	删除	问题
登录	/login	Login.vue	-	✅	-	-	正常
工作台	/user/dashboard	Dashboard.vue	✅	-	-	-	基础展示
员工监控	/user/monitor/employees	EmployeeList.vue	✅	-	-	-	仅列表，无操作
工作看板	/user/monitor/:id/dashboard	WorkDashboard.vue	✅	-	-	-	可能跳空白页
AI分析	/user/monitor/:id/analysis	AIAnalysis.vue	✅	-	-	-	依赖LLM，可能空白
任务列表	/user/task/list	TaskList.vue	✅	-	-	-	仅列表
任务详情	/user/task/:id	TaskDetail.vue	✅	-	-	-	可能空白页
智能体	/user/agent/list	AgentList.vue	✅	-	-	-	仅展示4个类型
智能体对话	/user/agent/chat/:type	AgentChat.vue	-	-	-	-	基础聊天
文档管理	/user/document/manager	DocumentManager.vue	-	✅ 上传	-	-	功能不全
企微配置	/user/wecom/config	BotConfig.vue	-	-	-	-	展示配置
通知中心	/user/notification/center	NotificationCenter.vue	-	-	-	-	基础
控制台	/admin	Dashboard.vue	✅	-	-	-	同工作台
部门管理	/admin/org/departments	DepartmentTree.vue	✅	-	-	-	仅树状展示
人员管理	/admin/org/users	UserList.vue	✅	-	-	-	仅列表
角色管理	/admin/role/list	RoleList.vue	✅	-	-	-	仅列表
权限配置	/admin/role/:id/permissions	PermissionConfig.vue	-	-	-	-	可能空白页
流列表	/admin/flow/list	FlowList.vue	✅	-	-	-	仅列表
流编辑器	/admin/flow/editor	FlowEditor.vue	-	-	-	-	基础SVG画布，非拖拽
流市场	/admin/flow/market	FlowMarket.vue	✅	-	-	-	仅列表
创建任务	/admin/task/create	TaskCreate.vue	-	✅	-	-	跳空白页
审计日志	/admin/audit	AuditLog.vue	✅	-	-	-	基础列表
系统监控	/admin/system/monitor	SystemMonitor.vue	✅	-	-	-	基础展示

---

二、核心问题详解

2.1 Agent 全部是 Mock

agentscope_integration/tools/ 下的工具函数全部返回模拟字符串：

# document_tools.py
def parse_document(file_path, file_type="auto"):
    return f"[模拟] 已解析文档 {file_path} (类型: {file_type})"

def format_correction(content, format_rules="standard"):
    return f"[模拟] 已按 {format_rules} 规则修正格式:\n{content[:200]}..."

# wecom_tools.py
def send_notification(to_user, message, msg_type="text"):
    return f"通知已发送至 {to_user}: {message}"

Agent 框架（ReActAgent + Toolkit）本身是完整的，但注册的工具没有真正执行任何操作。

2.2 流编排引擎节点全部是 Mock

modules/flow_engine/engine.py 中定义的节点类型：

节点类型	代理类	实际行为
trigger	PassThroughAgent	✅ 透传（正确）
llm	LLMNodeAgent	✅ 真实调用 LLM
tool	ToolNodeAgent	❌ 返回固定字符串
mcp	MCPNodeAgent	❌ 返回固定字符串
wecom_notify	WeComNotifyAgent	❌ 返回固定字符串
condition	ConditionNodeAgent	❌ 全透传，无分支逻辑
rag	RAGNodeAgent	❌ 返回固定字符串
output	OutputNodeAgent	✅ 透传（正确）

结论：流编排引擎只能跑纯 LLM 链（trigger → llm → llm → output），任何涉及工具/MCP/RAG/条件分支的节点都是假的。

2.3 没有 RAG/知识库

• RAGNodeAgent 返回 [RAG检索] 已从知识库检索相关内容。
• 没有引入 embedding 模型
• 没有向量数据库（如 Chroma/Milvus/PGVector）
• 没有文档切分/索引流程
• 上传的文档只被物理存储，没有被 embedding 化

2.4 文档管理：只是文件存储，非 RAG

上传的文件存储在 uploads/ 目录，解析只做了简单的文本读取（支持 .txt/.md/.py/.json 等文本格式），PDF/Word/Excel 只返回一个占位字符串：

elif ext == ".pdf":
    content = f"[PDF文档解析] 文件: {found_filename}"

2.5 前端大量页面只有骨架

• 员工列表：只有表格展示，没有创建/编辑/操作的按钮和弹窗
• 角色管理：只有列表展示
• 部门管理：只有树状展示
• 流编辑器：只有基础 SVG 画布，不是真正的拖拽编辑器
• 任务创建：跳转到空白页
• 权限配置：可能空白页

---

三、与 ENTERPRISE_PLAN.md 的差距

原规划	当前状态	差距
Dify-like 可视化流编排	SVG 画布骨架，无拖拽交互	需要完整的拖拽节点编辑器
员工 AI 助手	Agent 框架有，工具 Mock	需要真实工具实现
管理者分析助手	Agent 框架有，无工具	需要数据库查询工具
任务管理助手	Agent 框架有，无工具	需要任务 CRUD 工具
文档处理助手	Agent 框架有，工具 Mock	需要真实文档解析库
RAG 知识库	无	需要从零实现
企微深度集成	回调框架有，消息发送 Mock	需要真实企业微信 API
MCP 服务编排	注册管理有，流中 Mock	需要真实 MCP 客户端调用
双 RBAC	已实现 ✅	无需改进
审计日志	已实现 ✅	无需改进
Docker 部署	已实现 ✅	端口冲突已修复
数据看板	基础展示	需要 ECharts 丰富图表

---

四、开发任务排期

P0 - 核心可用（让已有功能正常工作）

#	任务	优先级	预估	说明
1	修复前端空白页	🔴 P0	2天	TaskCreate.vue、PermissionConfig.vue、WorkDashboard.vue、TaskDetail.vue 等页面表单和详情展示
2	前端增删改操作表单	🔴 P0	3天	为员工列表、角色管理、部门管理、流列表、任务列表等页面补齐创建/编辑/删除弹窗和表单
3	Agent 工具真实化	🔴 P0	3天	document_tools.py 接入 python-docx/PyPDF2 等真实库；wecom_tools.py 接入真实企微API
4	流引擎节点真实化	🔴 P0	3天	ToolNodeAgent 调用真实 Toolkit；ConditionNodeAgent 实现分支；WeComNotifyAgent 真实推送

P1 - 关键能力（补齐核心功能缺口）

#	任务	优先级	预估	说明
5	Word/PDF 真实解析	🟡 P1	2天	引入 python-docx、PyPDF2/pdfplumber，替换 Mock
6	RAG 知识库	🟡 P1	5天	引入 embedding 模型 + PGVector 向量存储；实现文档切分/索引/检索；RAGNodeAgent 真实查询
7	流编辑器拖拽交互	🟡 P1	5天	FlowEditor.vue 使用 vue-flow 实现真正的拖拽节点编辑器（已有依赖 @vue-flow/core）
8	MCP 真实调用	🟡 P1	2天	MCPNodeAgent 通过 agentscope HttpStatefulClient 真实调用 MCP 服务

P2 - 体验完善（让产品可交付）

#	任务	优先级	预估	说明
9	数据看板可视化	🟢 P2	2天	Dashboard 使用 ECharts（已引入）展示用户/任务/流统计数据
10	企微 OAuth 登录	🟢 P2	1天	企微扫码登录替代纯用户名密码
11	Agent 多模型配置	🟢 P2	1天	前端增加 LLM 配置页面，支持切换模型、API Key
12	任务列表/智能体列表操作	🟢 P2	1天	任务列表增加编辑/删除操作；智能体列表增加配置入口

---

五、各任务详细说明

5.1 修复前端空白页

问题文件：

• TaskCreate.vue - 创建任务跳空白页，需要补全表单（标题、内容、负责人、优先级、截止日期）
• PermissionConfig.vue - 权限配置页空白，需要权限列表的 checkbox 配置
• WorkDashboard.vue - 工作看板空白，需要展示员工统计数据
• TaskDetail.vue - 任务详情空白，需要展示任务完整信息

目标：4 个页面全部有可用的 UI 和数据展示。

5.2 前端增删改操作表单

需要补齐表单的页面：

• EmployeeList.vue - 点击员工弹出编辑抽屉（信息、角色分配）
• RoleList.vue - 创建/编辑角色弹窗
• DepartmentTree.vue - 右键菜单：新增/编辑/删除部门
• FlowList.vue - 操作列：编辑/删除/发布/下架按钮
• TaskList.vue - 操作列：编辑/删除/推送企微按钮

5.3 Agent 工具真实化

document_tools.py 改造：

# 改为真实实现
def parse_document(file_path, file_type="auto"):
    if file_type == "pdf" or file_path.endswith(".pdf"):
        import pdfplumber
        with pdfplumber.open(file_path) as pdf:
            return "\n".join(page.extract_text() for page in pdf.pages)
    if file_type == "word" or file_path.endswith((".docx", ".doc")):
        from docx import Document
        doc = Document(file_path)
        return "\n".join(p.text for p in doc.paragraphs)
    ...

wecom_tools.py 改造：接入 settings.WECOM_CORP_ID 和 settings.WECOM_APP_SECRET 真实调用企微 API。

5.4 流引擎节点真实化

• ToolNodeAgent：创建时读取 tool_name，注册真实工具函数到 Toolkit
• ConditionNodeAgent：使用 LLM 判断条件表达式是否匹配
• WeComNotifyAgent：调用企微 API 真实发送消息
• MCPNodeAgent：通过 agentscope_runtime 的 MCP client 真实调用

5.5 RAG 知识库

技术方案：

• Embedding 模型：支持 OpenAI text-embedding-3-small 或本地模型
• 向量存储：PGVector（PostgreSQL 扩展，复用现有 postgres）
• 文档处理：docx/pdfplumber 提取文本 → 切分为 chunks → embedding → 存入 PGVector
• 检索：用户查询 → embedding → PGVector 相似度搜索 → 返回 top_k → 注入 LLM 上下文

新增依赖：

pgvector
langchain-text-splitters  # 或自写 chunk 切分

5.6 流编辑器拖拽交互

当前 FlowEditor.vue 使用基础 SVG 画布，但项目已引入 @vue-flow/core、@vue-flow/background、@vue-flow/controls、@vue-flow/minimap。

改造方向：

• 使用 VueFlow 替代当前 SVG 画布
• 实现侧边栏拖拽节点类型（trigger/llm/tool/mcp/rag/wecom_notify/condition/output）
• 节点之间连线创建 edge
• 每个节点可双击编辑配置（如 LLM 的 system_prompt）
• 保存按钮将 nodes+edges 序列化为后端 API 格式

---

六、技术债务记录

#	问题	位置	影响
1	passlib 已弃用，已改为 bcrypt 直调	modules/auth/router.py	✅ 已修复
2	docker-compose.yml 中 postgres 端口从 5432 改为 5431	docker-compose.yml	✅ 已修复
3	init-db/01-init.sql 中密码哈希是无效的（已更新）	init-db/01-init.sql	✅ 已修复
4	bcrypt 未锁定版本（已在 requirements.txt 中移除 passlib）	backend/requirements.txt	✅ 已修复
5	audit.py 中 model_validate 应改为 from_orm 或用 from_attributes	modules/audit/router.py:57	低优先级
6	uuid.uuid4() 在 document_tools.py 和 wecom_tools.py 中重复定义同名函数	两个文件	中优先级
7	FlowEditor.vue 中 visibleEdges 类型守卫问题	FlowEditor.vue:184	✅ 已修复

---

七、建议执行顺序

Week 1: P0 #1 #2 → 前端所有页面可交互（增删改查正常）
Week 2: P0 #3 #4 → Agent 和流编排能真正工作
Week 3: P1 #5 #6 → 文档真实解析 + RAG 知识库
Week 4: P1 #7    → 流编辑器完整拖拽交互
Week 5: P1 #8    → MCP 真实集成
Week 6: P2 #9-#12 → 数据看板 + 体验完善