hg-agents/PLAN5.md

PLAN5: Flow 画布节点系统完整性方案

目标

对齐前后端功能，实现流中节点配置真实生效，新增循环/代码节点，双渠道(企微+Web)输入输出。

---

一、当前状态总结

后端已有且正常运行

能力	状态
DAG 图执行引擎 (FlowEngine)	✅ 完整
8种节点 Agent: trigger/llm/tool/mcp/wecom_notify/condition/rag/output	✅ 完整
13个工具函数 (文档/企微/任务/管理)	✅ 完整
企微全链路(回调→Agent→回复→通知)	✅ 完整
RAG知识库(Qdrant+OpenAI)	✅ 完整
MCP外部服务集成	✅ 完整
流CRUD + 发布/下架 + 执行记录	✅ 完整

前端已有但后端不处理的配置项 (需对齐)

前端配置项	后端Schema	后端Agent
LLM: max_tokens	❌ 缺失	❌ 未使用
LLM: context_length	❌ 缺失	❌ 未使用
LLM: memory_mode (none/short/long)	❌ 缺失	❌ 未使用
LLM: stream (流式输出)	❌ 缺失	❌ 未使用
LLM: tool_call (函数调用)	❌ 缺失	❌ 未使用
Tool: timeout	❌ 缺失	❌ 未使用
Tool: retry_count	❌ 缺失	❌ 未使用
Tool: error_handling	❌ 缺失	❌ 未使用
RAG: search_mode (vector/keyword/hybrid)	❌ 缺失	❌ 未使用
RAG: similarity_threshold	❌ 缺失	❌ 未使用
Trigger: channels (wecom/web)	❌ 缺失	❌ 未使用
Notify: channels (wecom/web)	❌ 缺失	❌ 未使用

缺失的关键能力

• 循环节点: 无重试/迭代/批量能力
• 代码执行节点: 无法运行自定义逻辑
• Web Chat入口: 只能通过企微触发
• Web通知: 只有企微通知，无Web推送

---

二、实施计划

P0: 前后端配置对齐 (最高优先级)

目标: 前端配置的所有参数在后端Schema和Agent中真实生效

2.1 后端 Schema 补齐

# 文件: backend/schemas/__init__.py

class TriggerNodeConfig(BaseModel):
    event_type: str = "text_message"
    channels: list[str] = ["wecom"]        # 新增: ["wecom", "web_chat"]
    callback_url: str = ""                  # 新增

class LLMNodeConfig(BaseModel):
    system_prompt: str = ""
    model: str = "gpt-4o-mini"
    temperature: float = 0.7
    agent_id: str = ""
    max_tokens: int = 2000                  # 新增
    context_length: int = 5                 # 新增
    memory_mode: str = "short_term"         # 新增: none/short_term/long_term
    stream: bool = True                     # 新增
    tool_call: bool = False                 # 新增

class ToolNodeConfig(BaseModel):
    tool_name: str = ""
    tool_type: str = ""                     # 新增: wecom_message/task_management/...
    tool_params: dict = {}                  # 补齐
    timeout: int = 30                       # 新增
    retry_count: int = 0                    # 新增
    error_handling: str = "throw"           # 新增: throw/default/skip

class MCPNodeConfig(BaseModel):
    mcp_server: str = ""
    tool_name: str = ""
    input_params: dict = {}                 # 新增
    timeout: int = 30                       # 新增
    response_parser: str = "json"           # 新增
    error_handling: str = "throw"           # 新增

class NotifyNodeConfig(BaseModel):           # 重命名: WeComNotifyNodeConfig -> NotifyNodeConfig
    channels: dict = {"wecom": True, "web": False}  # 新增
    message_template: str = ""
    web_template: str = ""                  # 新增
    target: str = ""
    message_type: str = "text"              # 新增: text/markdown/card
    async_send: bool = False                # 新增
    error_handling: str = "throw"           # 新增

class ConditionNodeConfig(BaseModel):
    condition: str = ""
    condition_type: str = "expression"      # 新增
    true_label: str = "是"                  # 新增
    false_label: str = "否"                 # 新增
    default_branch: str = "false"           # 新增

class RAGNodeConfig(BaseModel):
    knowledge_base: str = ""
    top_k: int = 5
    search_mode: str = "hybrid"             # 新增: vector/keyword/hybrid
    similarity_threshold: float = 0.7       # 新增
    result_sort: str = "similarity"         # 新增
    include_metadata: bool = True           # 新增

class OutputNodeConfig(BaseModel):
    format: str = "text"
    output_template: str = ""               # 新增
    indent: int = 2                         # 新增
    encoding: str = "utf-8"                 # 新增
    truncate: bool = False                  # 新增
    max_length: int = 2000                  # 新增

class LoopNodeConfig(BaseModel):             # 新增节点
    loop_type: str = "fixed"               # fixed/count/list
    max_iterations: int = 10
    count: int = 3
    iterator_variable: str = "item"

class CodeNodeConfig(BaseModel):            # 新增节点
    language: str = "python"               # python/javascript
    code: str = ""
    timeout: int = 30
    sandbox: bool = True

2.2 后端 Agent 补齐

文件: backend/modules/flow_engine/engine.py

LLMNodeAgent: 使用 max_tokens, stream, tool_call
ToolNodeAgent: 使用 timeout, retry_count, error_handling
RAGNodeAgent: 使用 search_mode, similarity_threshold
NotifyAgent: 检测 channels.web 做 WebSocket 推送
LoopNodeAgent: 新增
CodeNodeAgent: 新增

P1: 双渠道支持

目标: 流同时支持企业微信和网页聊天触发，通知也支持双渠道

3.1 Web Chat API

POST /api/chat/sessions/{session_id}/message
POST /api/chat/sessions                (创建会话)
GET  /api/chat/sessions                (会话列表)

3.2 WebSocket 通知推送

backend/websocket_manager.py: 新增
- 用户连接管理
- 按用户推送通知

3.3 前端 Web Chat 页面

frontend/src/views/chat/ChatWidget.vue: 新增
- 浮动聊天窗口
- WebSocket 实时接收
- 流选择

P2: 新增节点类型

目标: 新增循环节点和代码执行节点

4.1 循环节点 (Loop)

• 固定次数循环、条件循环、遍历列表
• 两个出口: loop_body(继续), loop_done(完成)
• 安全上限: max_iterations 防止死循环
• 引擎需要支持回边

4.2 代码执行节点 (Code)

• Python/JavaScript 沙箱执行
• subprocess 隔离 + 超时控制
• stdin/stdout 输入输出

P3: FlowEngine 改造

目标: 支持循环节点回边

1. traverse() 中 visited 集合改为 per-branch 而非全局
2. 循环节点特殊处理: 检测 loop_done 条件
3. 执行超时和安全限制

---

三、实施顺序

1. P0-1: 后端 Schema 补齐 (schemas/init.py) — 10分钟
2. P0-2: 后端 Agent 补齐 (engine.py) — 15分钟
3. P0-3: 路由注册新节点类型 (router.py) — 5分钟
4. P1-1: Notify 节点双渠道改造 + WebSocket — 15分钟
5. P1-2: Web Chat API + 路由 — 10分钟
6. P1-3: 前端 ChatWidget + 通知接收 — 10分钟
7. P2-1: Loop Node (前端配置+后端Agent) — 10分钟
8. P2-2: Code Node (前端配置+后端Agent) — 10分钟
9. P3: FlowEngine 循环回边支持 — 10分钟
10. 更新前端 FlowEditor: 新节点类型 + 配置对齐 — 5分钟

---

四、前端文件清单

文件	内容
FlowEditor.vue	新增 loop/code 节点类型、trigger 改 channels
node-configs/LoopConfig.vue	循环配置
node-configs/CodeConfig.vue	代码执行配置
node-configs/NotifyConfig.vue	双渠道通知配置
node-configs/TriggerConfig.vue	双渠道触发配置
chat/ChatWidget.vue	Web Chat 入口

五、后端文件清单

文件	内容
schemas/init.py	补齐所有Config Schema + 新增Loop/Code
flow_engine/engine.py	补齐Agent实现 + LoopNodeAgent + CodeNodeAgent + 引擎回边
flow_engine/router.py	注册新节点类型
chat/router.py	Web Chat API (新建)
websocket_manager.py	WebSocket管理 (新建)