langgraph

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

LangGraph

Use this skill to design, implement, and debug LangGraph workflows with explicit state contracts, deterministic routing, and robust interrupt handling.

使用本技能可设计、实现和调试具备明确状态契约、确定性路由以及可靠中断处理机制的LangGraph工作流。

Quick Triage

快速分类判断

Use this skill when the task involves graph nodes/edges, conditional routing, checkpointing, thread state, or HITL interrupts.
Switch to
```
$langchain
```
when the task is mostly prompt/tool chain composition without graph-level orchestration.
Switch to
```
$ag-ui
```
when the task is protocol-level event synchronization with a frontend client.
Switch to
```
$copilotkit
```
when the task is CopilotKit provider/hooks/shared-state UI integration.

当任务涉及图节点/边、条件路由、检查点、线程状态或HITL中断时，使用本技能。
当任务主要是提示词/工具链组合，不涉及图级编排时，切换至
```
$langchain
```
技能。
当任务是与前端客户端进行协议级事件同步时，切换至
```
$ag-ui
```
技能。
当任务是CopilotKit提供者/钩子/共享状态UI集成时，切换至
```
$copilotkit
```
技能。

Workflow

工作流程

Define state schema first. Include only fields required for routing, retries, and outputs.
Define node contracts. Each node should have one clear responsibility and explicit input/output assumptions.
Define edges and routers. Map all normal, retry, and terminal paths before implementing node internals.
Add persistence strategy. Choose checkpointer configuration and thread identity contract early.
Add interrupt strategy. Define where human approvals occur and how resume payloads are parsed.
Compile and visualize. Validate graph shape before running large test scenarios.
Verify with scenario tests. Cover pass, retry, skip, and max-retry termination paths.

首先定义状态模式。仅包含路由、重试和输出所需的字段。
定义节点契约。每个节点应具备单一明确的职责，以及清晰的输入/输出预设。
定义边与路由规则。在实现节点内部逻辑前，先梳理所有正常、重试和终止路径。
添加持久化策略。尽早确定检查点配置和线程身份契约。
添加中断策略。定义人工审批的触发节点以及恢复负载的解析方式。
编译并可视化。在运行大规模测试场景前，先验证图的结构。
通过场景测试验证。覆盖通过、重试、跳过和最大重试次数终止等路径。

Default Patterns

默认模式

Keep routing predicates pure and side-effect free.
Keep node outputs explicit and minimal.
Use separate nodes for validation vs generation to reduce coupling.
Route by failure class (recoverable vs terminal) rather than generic “error”.

保持路由谓词纯净，无副作用。
保持节点输出明确且精简。
将验证与生成逻辑拆分为独立节点，以降低耦合度。
根据故障类型（可恢复/终止型）进行路由，而非笼统的“错误”。

Failure Modes

故障模式

Implicit state mutations causing routing drift.
Retry loops without cap or fallback exit.
Interrupt payload mismatch between backend and UI.
Missing thread/checkpoint identity causing non-reproducible flows.

隐式状态变更导致路由偏移。
无上限或无退出机制的重试循环。
后端与UI之间的中断负载不匹配。
缺少线程/检查点标识导致流程无法复现。

Reference Map

参考资源

Load only what is needed for the current subtask.

Graph design patterns:
```
references/graph-design-patterns.md
```
State and checkpoints:
```
references/state-and-checkpointing.md
```
HITL interrupts:
```
references/hitl-interrupts.md
```
Debugging playbook:
```
references/debugging-playbook.md
```

仅加载当前子任务所需的资源。

图设计模式：
```
references/graph-design-patterns.md
```
状态与检查点：
```
references/state-and-checkpointing.md
```
HITL中断：
```
references/hitl-interrupts.md
```
调试手册：
```
references/debugging-playbook.md
```