state-flow-visualizer

majiayu000 的头像作者 majiayu000

分析和可视化 LangGraph 管道中的状态流。在调试状态突变、跟踪节点之间的数据流、识别孤立状态键、检测读/写依赖性或生成状态转换的美人鱼图时使用。触发诸如“可视化状态流”、“跟踪状态键”、“哪些节点接触 X”、“状态依赖性”、“调试状态突变”、“孤立状态键”、“状态流程图”等短语。

📖 中文导读:分析和可视化 LangGraph 管道中的状态流。在调试状态突变、跟踪节点之间的数据流、识别孤立状态键、检测读/写依赖性或生成状态转换的美人鱼图时使用。触发诸如“可视化状态流”、“跟踪状态键”、“哪些节点接触 X”、“状态依赖性”、“调试状态突变”、“孤立状态键”、“状态流程图”等短语。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: state-flow-visualizer description: Analyze and visualize state flow in LangGraph pipelines. Use when debugging state mutations, tracing data flow between nodes, identifying orphan state keys, detecting read/write dependencies, or generating Mermaid diagrams of state transitions. Triggers on phrases like "visualize state flow", "trace state key", "which nodes touch X", "state dependencies", "debug state mutation", "orphan state keys", "state flow diagram".

State Flow Visualizer

Analyze LangGraph state mutations and generate visual representations of data flow between nodes.

Capabilities

  1. State Flow Diagrams - Generate Mermaid flowcharts showing node-to-state-key relationships
  2. Key Tracing - Track a specific state key through all read/write operations
  3. Dependency Analysis - Show which nodes depend on outputs from other nodes
  4. Orphan Detection - Find state keys that are written but never read (or vice versa)
  5. Layer Analysis - Visualize state flow within and between layers

Quick Start

Run the analyzer on a LangGraph nodes directory:

python scripts/analyze_state_flow.py /path/to/src/langgraph/nodes

Generate a Mermaid diagram:

python scripts/analyze_state_flow.py /path/to/src/langgraph/nodes --output mermaid

Trace a specific key:

python scripts/analyze_state_flow.py /path/to/src/langgraph/nodes --trace extracted_rates

Output Formats

Mermaid Diagram

flowchart LR
    subgraph Layer2["Layer 2: File Intelligence"]
        mrf_expert[mrf_expert]
    end
    subgraph State
        mrf_structures([mrf_structures])
        provider_reference_maps([provider_reference_maps])
    end
    mrf_expert -->|writes| mrf_structures
    mrf_expert -->|writes| provider_reference_maps
    rate_extractor -->|reads| provider_reference_maps

JSON Report

{
  "nodes": [...],
  "state_keys": [...],
  "reads": [...],
  "writes": [...],
  "orphans": {"written_never_read": [], "read_never_written": []},
  "dependencies": [...]
}

Integration with TiC Pipeline

For TiC-specific analysis, the tool understands:

  • Layer organization (layer0-layer8)
  • TiCPipelineState TypedDict structure
  • BaseLLMNode and BaseDeterministicNode patterns
  • State update patterns via update_layer_status()

Commands

Command Description
--output mermaid Generate Mermaid flowchart
--output json Generate JSON analysis report
--output summary Human-readable summary (default)
--trace KEY Trace specific state key through pipeline
--layer N Filter to specific layer
--detect-orphans Find unused state keys
--detect-cycles Find circular dependencies

Interpreting Results

Healthy Patterns

  • Each state key has at least one writer and one reader
  • Writers execute before readers (layer ordering)
  • No circular dependencies within a layer

Warning Signs

  • Orphan writes: State key populated but never used downstream
  • Orphan reads: Node expects state key that no node populates
  • Cross-layer cycles: Later layer writes key read by earlier layer
  • Shadow writes: Multiple nodes write same key (potential race condition)

Troubleshooting Common Issues

"extracted_rates is empty at layer 6"

Run: python scripts/analyze_state_flow.py . --trace extracted_rates

Look for:

  1. Which node should write extracted_rates
  2. Whether that node's layer executes before layer 6
  3. Whether the writing node has error handling that silently returns []

"State key not found in analysis"

The key may be:

  • Dynamically constructed (e.g., state.get(f"{prefix}_rates"))
  • Set in initial state factory, not by a node
  • Populated by external process

Check state.py for initial state values.