langgenius/dify
1
0
Fork 0
mirror of https://github.com/langgenius/dify.git synced 2026-08-24 12:32:54 -04:00
Code Issues 775 Packages Projects Releases 10 Wiki Activity

Proposal: Refactoring WorkflowCycleManager for Improved Maintainability #14088

New Issue
Closed
opened 2026-02-21 19:15:29 -05:00 by yindo · 0 comments
yindo commented 2026-02-21 19:15:29 -05:00
Owner
Copy Link
Copy Source

Originally created by @laipz8200 on GitHub (May 21, 2025).

Originally assigned to: @laipz8200 on GitHub.

Self Checks

  • I have searched for existing issues search for existing issues, including closed ones.
  • I confirm that I am using English to submit this report (我已阅读并同意 Language Policy).
  • [FOR CHINESE USERS] 请务必使用英文提交 Issue，否则会被关闭。谢谢！:)
  • Please do not modify this template :) and fill in all the required fields.

1. Is this request related to a challenge you're experiencing? Tell me about your story.

Executive Summary

This proposal is a part of #19429

This proposal outlines a refactoring plan to split the current WorkflowCycleManager class into two separate, independent classes with distinct responsibilities. The refactoring aims to improve code maintainability, adhere to the Single Responsibility Principle, and create a more modular architecture. Both classes will be used by the TaskPipeline component rather than depending on each other.

Problem Statement

The current WorkflowCycleManager class in core/workflow/workflow_cycle_manager.py has grown to handle two distinct responsibilities:

  1. Event Handling: Processing workflow events and updating the database state
  2. Response Conversion: Converting workflow events to stream responses for client consumption

This dual responsibility violates the Single Responsibility Principle, making the class:

  • Difficult to maintain as it continues to grow
  • Challenging to test due to mixed concerns
  • Less modular, with changes to one aspect potentially affecting the other
  • Harder for new developers to understand

Additionally, the response conversion logic is more closely related to application concerns than workflow state management, suggesting it belongs in the core/app directory.

Proposed Solution

We propose splitting the WorkflowCycleManager class into two separate, independent classes:

  1. WorkflowCycleManager (keep in core/workflow/workflow_cycle_manager.py)

    • Focus: Event handling and workflow state management
    • Responsibility: Process workflow events and update the database

  2. WorkflowResponseConverter (new class in core/app/workflow_response_converter.py)

    • Focus: Converting workflow events to stream responses
    • Responsibility: Transform workflow data into client-friendly response formats

Both classes will be used by the TaskPipeline component, which will coordinate between them as needed. This approach ensures a clean separation of concerns with no direct dependencies between the two classes.

Technical Details

Class Responsibilities

WorkflowCycleManager:

  • Handle workflow run lifecycle events (start, success, failure, etc.)
  • Manage node execution events
  • Update workflow execution state in the database
  • Maintain workflow execution repositories

WorkflowResponseConverter:

  • Convert workflow executions to stream responses
  • Format node executions for client consumption
  • Handle file extraction from outputs
  • Transform various workflow events into appropriate response objects

Method Distribution

Methods to remain in WorkflowCycleManager:

  • handle_workflow_run_start
  • handle_workflow_run_success
  • handle_workflow_run_partial_success
  • handle_workflow_run_failed
  • handle_node_execution_start
  • handle_workflow_node_execution_success
  • handle_workflow_node_execution_failed
  • handle_workflow_node_execution_retried
  • _get_workflow_execution_or_raise_error

Methods to move to WorkflowResponseConverter:

  • workflow_start_to_stream_response
  • workflow_finish_to_stream_response
  • workflow_node_start_to_stream_response
  • workflow_node_finish_to_stream_response
  • workflow_node_retry_to_stream_response
  • workflow_parallel_branch_start_to_stream_response
  • workflow_parallel_branch_finished_to_stream_response
  • workflow_iteration_start_to_stream_response
  • workflow_iteration_next_to_stream_response
  • workflow_iteration_completed_to_stream_response
  • workflow_loop_start_to_stream_response
  • workflow_loop_next_to_stream_response
  • workflow_loop_completed_to_stream_response
  • fetch_files_from_node_outputs
  • _fetch_files_from_variable_value
  • _get_file_var_from_value
  • handle_agent_log

Class Relationship

The WorkflowCycleManager and WorkflowResponseConverter will be independent classes with no direct dependencies on each other. Both will be used by the TaskPipeline component, which will coordinate between them as needed.

classDiagram
    class TaskPipeline {
        -workflow_cycle_manager
        -workflow_response_converter
        +process_workflow_events()
        +generate_responses()
    }
    
    class WorkflowCycleManager {
        -application_generate_entity
        -workflow_system_variables
        -workflow_execution_repository
        -workflow_node_execution_repository
        +handle_workflow_run_start()
        +handle_workflow_run_success()
        +handle_workflow_run_partial_success()
        +handle_workflow_run_failed()
        +handle_node_execution_start()
        +handle_workflow_node_execution_success()
        +handle_workflow_node_execution_failed()
        +handle_workflow_node_execution_retried()
        -_get_workflow_execution_or_raise_error()
    }
    
    class WorkflowResponseConverter {
        -application_generate_entity
        +workflow_start_to_stream_response()
        +workflow_finish_to_stream_response()
        +workflow_node_start_to_stream_response()
        +workflow_node_finish_to_stream_response()
        +workflow_node_retry_to_stream_response()
        +workflow_parallel_branch_start_to_stream_response()
        +workflow_parallel_branch_finished_to_stream_response()
        +workflow_iteration_start_to_stream_response()
        +workflow_iteration_next_to_stream_response()
        +workflow_iteration_completed_to_stream_response()
        +workflow_loop_start_to_stream_response()
        +workflow_loop_next_to_stream_response()
        +workflow_loop_completed_to_stream_response()
        +fetch_files_from_node_outputs()
        -_fetch_files_from_variable_value()
        -_get_file_var_from_value()
        +handle_agent_log()
    }
    
    TaskPipeline --> WorkflowCycleManager : uses
    TaskPipeline --> WorkflowResponseConverter : uses

Implementation Plan

The refactoring will be implemented in the following phases:

Phase 1: Create the New Class

  1. Create the new WorkflowResponseConverter class in core/app/workflow_response_converter.py
  2. Implement the constructor with necessary dependencies
  3. Add required imports

Phase 2: Move Methods

  1. Move all response conversion methods to the new class
  2. Update method signatures and dependencies as needed
  3. Ensure all file-related utility methods are moved
  4. Update internal references within the moved methods

Phase 3: Update WorkflowCycleManager

  1. Remove the moved methods
  2. Remove any references to response conversion
  3. Update imports

Phase 4: Update TaskPipeline

  1. Add a reference to both WorkflowCycleManager and WorkflowResponseConverter
  2. Update the code to use the appropriate class for each responsibility
  3. Ensure proper coordination between the two classes

Phase 5: Testing

  1. Write unit tests for both classes
  2. Ensure all existing functionality works as expected
  3. Verify that the refactoring doesn't introduce any regressions

Phase 6: Documentation

  1. Update documentation to reflect the new class structure
  2. Add comments explaining the relationship between the classes and TaskPipeline

Benefits

  1. Improved Code Organization:

    • Each class has a clear, single responsibility
    • Code is more modular and easier to understand
    • Response conversion logic is placed in the appropriate module

  2. Enhanced Maintainability:

    • Changes to response formats won't affect workflow state management
    • Changes to workflow state management won't affect response formats
    • Easier to extend either aspect independently

  3. Better Testability:

    • Each class can be tested in isolation
    • Mocking dependencies becomes simpler
    • Test coverage can be more focused

  4. Adherence to Design Principles:

    • Follows the Single Responsibility Principle
    • Improves separation of concerns
    • Creates a more modular architecture with independent components

  5. Flexibility:

    • The TaskPipeline can use either class independently as needed
    • No direct dependencies between the classes makes them more reusable

2. Additional context or comments

No response

3. Can you help us with this feature?

  • I am interested in contributing to this feature.
Originally created by @laipz8200 on GitHub (May 21, 2025). Originally assigned to: @laipz8200 on GitHub. ### Self Checks - [x] I have searched for existing issues [search for existing issues](https://github.com/langgenius/dify/issues), including closed ones. - [x] I confirm that I am using English to submit this report (我已阅读并同意 [Language Policy](https://github.com/langgenius/dify/issues/1542)). - [x] [FOR CHINESE USERS] 请务必使用英文提交 Issue，否则会被关闭。谢谢！:) - [x] Please do not modify this template :) and fill in all the required fields. ### 1. Is this request related to a challenge you're experiencing? Tell me about your story. ## Executive Summary This proposal is a part of #19429 This proposal outlines a refactoring plan to split the current `WorkflowCycleManager` class into two separate, independent classes with distinct responsibilities. The refactoring aims to improve code maintainability, adhere to the Single Responsibility Principle, and create a more modular architecture. Both classes will be used by the `TaskPipeline` component rather than depending on each other. ## Problem Statement The current `WorkflowCycleManager` class in `core/workflow/workflow_cycle_manager.py` has grown to handle two distinct responsibilities: 1. **Event Handling**: Processing workflow events and updating the database state 2. **Response Conversion**: Converting workflow events to stream responses for client consumption This dual responsibility violates the Single Responsibility Principle, making the class: - Difficult to maintain as it continues to grow - Challenging to test due to mixed concerns - Less modular, with changes to one aspect potentially affecting the other - Harder for new developers to understand Additionally, the response conversion logic is more closely related to application concerns than workflow state management, suggesting it belongs in the `core/app` directory. ## Proposed Solution We propose splitting the `WorkflowCycleManager` class into two separate, independent classes: 1. **WorkflowCycleManager** (keep in `core/workflow/workflow_cycle_manager.py`) - Focus: Event handling and workflow state management - Responsibility: Process workflow events and update the database 2. **WorkflowResponseConverter** (new class in `core/app/workflow_response_converter.py`) - Focus: Converting workflow events to stream responses - Responsibility: Transform workflow data into client-friendly response formats Both classes will be used by the `TaskPipeline` component, which will coordinate between them as needed. This approach ensures a clean separation of concerns with no direct dependencies between the two classes. ## Technical Details ### Class Responsibilities **WorkflowCycleManager**: - Handle workflow run lifecycle events (start, success, failure, etc.) - Manage node execution events - Update workflow execution state in the database - Maintain workflow execution repositories **WorkflowResponseConverter**: - Convert workflow executions to stream responses - Format node executions for client consumption - Handle file extraction from outputs - Transform various workflow events into appropriate response objects ### Method Distribution **Methods to remain in WorkflowCycleManager**: - `handle_workflow_run_start` - `handle_workflow_run_success` - `handle_workflow_run_partial_success` - `handle_workflow_run_failed` - `handle_node_execution_start` - `handle_workflow_node_execution_success` - `handle_workflow_node_execution_failed` - `handle_workflow_node_execution_retried` - `_get_workflow_execution_or_raise_error` **Methods to move to WorkflowResponseConverter**: - `workflow_start_to_stream_response` - `workflow_finish_to_stream_response` - `workflow_node_start_to_stream_response` - `workflow_node_finish_to_stream_response` - `workflow_node_retry_to_stream_response` - `workflow_parallel_branch_start_to_stream_response` - `workflow_parallel_branch_finished_to_stream_response` - `workflow_iteration_start_to_stream_response` - `workflow_iteration_next_to_stream_response` - `workflow_iteration_completed_to_stream_response` - `workflow_loop_start_to_stream_response` - `workflow_loop_next_to_stream_response` - `workflow_loop_completed_to_stream_response` - `fetch_files_from_node_outputs` - `_fetch_files_from_variable_value` - `_get_file_var_from_value` - `handle_agent_log` ### Class Relationship The `WorkflowCycleManager` and `WorkflowResponseConverter` will be independent classes with no direct dependencies on each other. Both will be used by the `TaskPipeline` component, which will coordinate between them as needed. ```mermaid classDiagram class TaskPipeline { -workflow_cycle_manager -workflow_response_converter +process_workflow_events() +generate_responses() } class WorkflowCycleManager { -application_generate_entity -workflow_system_variables -workflow_execution_repository -workflow_node_execution_repository +handle_workflow_run_start() +handle_workflow_run_success() +handle_workflow_run_partial_success() +handle_workflow_run_failed() +handle_node_execution_start() +handle_workflow_node_execution_success() +handle_workflow_node_execution_failed() +handle_workflow_node_execution_retried() -_get_workflow_execution_or_raise_error() } class WorkflowResponseConverter { -application_generate_entity +workflow_start_to_stream_response() +workflow_finish_to_stream_response() +workflow_node_start_to_stream_response() +workflow_node_finish_to_stream_response() +workflow_node_retry_to_stream_response() +workflow_parallel_branch_start_to_stream_response() +workflow_parallel_branch_finished_to_stream_response() +workflow_iteration_start_to_stream_response() +workflow_iteration_next_to_stream_response() +workflow_iteration_completed_to_stream_response() +workflow_loop_start_to_stream_response() +workflow_loop_next_to_stream_response() +workflow_loop_completed_to_stream_response() +fetch_files_from_node_outputs() -_fetch_files_from_variable_value() -_get_file_var_from_value() +handle_agent_log() } TaskPipeline --> WorkflowCycleManager : uses TaskPipeline --> WorkflowResponseConverter : uses ``` ## Implementation Plan The refactoring will be implemented in the following phases: ### Phase 1: Create the New Class 1. Create the new `WorkflowResponseConverter` class in `core/app/workflow_response_converter.py` 2. Implement the constructor with necessary dependencies 3. Add required imports ### Phase 2: Move Methods 1. Move all response conversion methods to the new class 2. Update method signatures and dependencies as needed 3. Ensure all file-related utility methods are moved 4. Update internal references within the moved methods ### Phase 3: Update WorkflowCycleManager 1. Remove the moved methods 2. Remove any references to response conversion 3. Update imports ### Phase 4: Update TaskPipeline 1. Add a reference to both `WorkflowCycleManager` and `WorkflowResponseConverter` 2. Update the code to use the appropriate class for each responsibility 3. Ensure proper coordination between the two classes ### Phase 5: Testing 1. Write unit tests for both classes 2. Ensure all existing functionality works as expected 3. Verify that the refactoring doesn't introduce any regressions ### Phase 6: Documentation 1. Update documentation to reflect the new class structure 2. Add comments explaining the relationship between the classes and TaskPipeline ## Benefits 1. **Improved Code Organization**: - Each class has a clear, single responsibility - Code is more modular and easier to understand - Response conversion logic is placed in the appropriate module 2. **Enhanced Maintainability**: - Changes to response formats won't affect workflow state management - Changes to workflow state management won't affect response formats - Easier to extend either aspect independently 3. **Better Testability**: - Each class can be tested in isolation - Mocking dependencies becomes simpler - Test coverage can be more focused 4. **Adherence to Design Principles**: - Follows the Single Responsibility Principle - Improves separation of concerns - Creates a more modular architecture with independent components 5. **Flexibility**: - The TaskPipeline can use either class independently as needed - No direct dependencies between the classes makes them more reusable ### 2. Additional context or comments _No response_ ### 3. Can you help us with this feature? - [x] I am interested in contributing to this feature.
yindo added the 💪 enhancement label 2026-02-21 19:15:29 -05:00
yindo closed this issue 2026-02-21 19:15:30 -05:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
Knowledge Pipeline
Proposal
WIP
cloud
dependencies
feat:webapp
good first issue
outdated
performance
pull-request
Mirrored from GitHub Pull Request
 python:uv
refactor
size:L
stale
status: accepting prs
status: blocked
status: in discussion
stt & tts
vulnerablity
web
wont-fix
🌊 feat:workflow
🌚 invalid
🐞 bug
👻 feat:rag
💪 enhancement
📚 documentation
🔨 feat:tools
🙋‍♂️ question
🙏 help wanted
🤔 cant-reproduce
🤖 feat:agent
No Label 💪 enhancement
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: langgenius/dify#14088
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?