dag-best-practices

HomeRail DAG 最佳实践

一句话原则：先统一事实，再分头检查，最后只按证据下结论。

DO

• 先建立唯一事实源。用 seed 节点拿到代码、版本、输入参数和外部证据，再把同一份事实交给所有下游节点。
• 让每个节点只回答一个清晰问题，例如源码是否干净、构建是否通过、运行时是否健康、数据是否保留。
• 让节点真的检查事实。该跑命令就跑命令，该读文件就读文件，该查 API 就查 API，不要只复述提示词。
• 让节点输出结构化 handoff。至少包含结论、证据、缺口、阻塞原因；失败时给出可行动的修复方向。
• 让 fan-in 节点只做裁决。它可以汇总和判断，但不应该重新做所有检查，也不应该替上游补证据。
• 把 hard gate 和 advisory 分开。必须通过的检查失败就阻塞；参考意见只能提示风险，不能替代证据。
• 把运行环境差异当成默认存在。宿主机、容器、本地、远端、CI 看到的路径、网络、权限、工具链可能都不同。
• 把会改变运行时的动作放在 DAG 外或明确隔离。部署、迁移、重启服务这类动作不要破坏正在执行 DAG 的基础设施。
• 给长期状态留 baseline。涉及升级、迁移、用户数据、配置和历史记录时，先记录基准，再用后续运行对比。
• 留下可复查的证据。每次运行都应该能回答：看了什么、跑了什么、结果是什么、为什么通过或阻塞。
• 用小 smoke 验证流程，用真实任务验证能力。快速 smoke 证明线路能通，真实模型和真实命令才证明任务完成质量。
• 使用执行环境真的能访问的地址、路径和凭证。给容器节点的输入，要从容器视角验证可用。

DO NOT

• 不要让节点各自使用不同事实源。版本不一致时，后面的汇总没有意义。
• 不要把模糊自然语言当成节点间协议。节点间传递要用结构化字段，不要靠读聊天猜含义。
• 不要让一个节点承担太多职责。职责越混，失败原因越难定位。
• 不要把没输出结果的节点算作成功。没有 handoff 就是缺证据。
• 不要自动补 handoff 后继续判通过。自动补只能说明节点没有按契约完成。
• 不要让 fan-in 节点靠感觉补全缺失信息。缺少证据就阻塞，而不是猜测通过。
• 不要把参考意见当成硬结论。LLM review、人工建议、摘要和 smoke 都不能替代 hard gate 的实际证据。
• 不要把快速跑通说成完整完成。smoke 是线路检查，不是质量证明。
• 不要默认所有环境都一样。宿主机能访问，不代表容器能访问；本机能跑，不代表 CI 能跑。
• 不要只保存最终结论，不保存过程证据。没有过程，结论无法复查。
• 不要隐藏不确定性。没查到、没权限、环境不可达、证据不足，都应该明确写进结果。
• 不要把 token、本机路径、私有地址、临时目录写死在可复用模板里。需要这些值时，通过运行参数或环境配置传入。

快速检查

• 有没有唯一事实源？
• 每个节点的问题是否足够单一？
• 每个节点是否会产生结构化 handoff？
• fan-in 是否只基于 handoff 和 evidence 下结论？
• hard gate 和 advisory 是否分清？
• smoke 和真实验证是否分清？
• 运行环境的网络、路径、权限是否从执行节点视角验证过？
• 失败时是否能直接看出原因和下一步？