state-flow-visualizer
分析和可视化 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
- State Flow Diagrams - Generate Mermaid flowcharts showing node-to-state-key relationships
- Key Tracing - Track a specific state key through all read/write operations
- Dependency Analysis - Show which nodes depend on outputs from other nodes
- Orphan Detection - Find state keys that are written but never read (or vice versa)
- 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)
TiCPipelineStateTypedDict structureBaseLLMNodeandBaseDeterministicNodepatterns- 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:
- Which node should write
extracted_rates - Whether that node's layer executes before layer 6
- 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.