必须用Kahn算法做拓扑排序，禁用DFS递归；状态更新须用atomic.Value深拷贝map；环检测需在加载阶段完成并返回具体路径；节点注册为强制契约，未注册即panic。
别自己写 DAG 调度器，除非你只跑 5 个节点、不跨进程、不重试、不查状态——否则你会在 toposort 栈溢出、atomic.Value 误用、循环检测报错不具体这三件事上反复崩溃。
拓扑排序必须用 Kahn 算法，不是 DFS
AI 工作流常有上百节点，DFS 递归做拓扑排序极易栈溢出；Kahn 算法用入度表 + 队列，天然适合并发调度。错误写法是 toposort(node, visited) 递归调用；正确做法是维护 indegree map[string]int 和 queue []string，每次 pop 入度为 0 的节点，更新其下游入度。
常见错误现象：
- 任务数一过 20，
runtime: goroutine stack exceeds 1GB limit直接 panic - DFS 回溯路径没清空，导致环检测漏报或重复报
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 初始化时遍历所有边，统计每个节点的入度
- 把所有入度为 0 的节点塞进
queue，用sync.Pool复用 slice 减少 GC 压力 - 每执行完一个节点，遍历其
outgoing边，对每个下游节点执行indegree[dst]--，若减到 0 就 push 进队列 - 加
context.Context控制整个调度生命周期，避免卡死
节点状态不能存全局 map，得用 atomic.Value
并发执行多个任务时，map[string]NodeStatus 直接读写会 panic。必须用 atomic.Value 包一层：
var statusStore atomic.Value
statusStore.Store(make(map[string]NodeStatus))
// 更新时：
old := statusStore.Load().(map[string]NodeStatus)
new := make(map[string]NodeStatus)
for k, v := range old {
new[k] = v
}
new["task-a"] = NodeStatus{State: "running"}
statusStore.Store(new)
漏掉 copy 这一步，所有 goroutine 共享同一底层数组，状态就乱了。性能影响明显：未 copy 的写操作在高并发下会导致 fatal error: concurrent map writes；copy 后虽有内存拷贝开销，但稳定可控。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
使用场景：
- 需要支持人工干预（如跳过、重试）时，状态必须强一致
- 状态要导出给 HTTP 接口查询，不能靠锁阻塞读
- 节点重启后需从持久化层恢复状态，
atomic.Value是唯一能安全替换整张 map 的方式
循环检测必须在加载阶段完成，且报错要带路径
DAG 加载时就要跑一遍环检测，运行时再检等于埋雷。检测逻辑不是“有没有环”，而是“哪条边导致环”。Eino 报错是：cycle detected: node 'validate' → 'enrich' → 'validate'；而网上抄来的代码只报 graph has cycle，你得手动 trace 一百个边。
实现要点：
- 用 DFS 记录当前路径
path []string，遇到已访问节点且该节点在 path 中，就拼出完整环路字符串 - 不要复用拓扑排序的 Kahn 逻辑来检测环——它只能告诉你“有环”，无法定位
- 检测失败时，直接
panic(fmt.Errorf("cycle detected: %s", cyclePath))，不提供 fallback - YAML 或 JSON 加载后、
engine.Run()前，必须调用Validate()方法
注册节点必须显式声明，否则 panic 是默认行为
像 engine.Register("llm_call", &LLMNode{}) 这种注册不是可选配置，是强制契约。Goflow 和 Eino 都会在 workflow.Load() 时遍历所有节点类型，发现未注册的 Type 就直接 panic。
这不是 bug，是防错设计——避免 YAML 里写错名字却静默跳过。你写 type: "llm_invoke" 却没注册，它不会尝试 fallback，而是立刻崩给你看。
容易踩的坑：
- 忘记在
init()函数里注册，测试时用硬编码 struct 没问题，一换 YAML 就挂 - 注册名大小写不一致，比如 YAML 写
type: "SendEmail"，代码注册的是"sendemail" - 注册了两次同名节点，第二次覆盖第一次，但旧实例还在内存里，状态错乱
真正难的从来不是怎么连边，而是怎么让失败的任务能被人工看见、能断点续跑、能在超时后自动降级——这些都压在状态持久化和边条件上，而不是拓扑排序本身。
