# 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 补齐
```python
# 文件: 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管理 (新建) |