Graph Engineering 出现的背景
2026 年 7 月，Graph Engineering 成为 Agent 圈的新说法。它没有引入新的图结构：状态机、CI DAG、LangGraph、AutoGen GraphFlow 都已支持节点、边、条件分支和循环。这个词受到关注，是因为 Agent 的使用方式发生了变化。
早期 Agent 多数只处理短任务。给定目标、工具和验证器，一个 Agent 可在“发现 → 计划 → 执行 → 验证”的闭环内迭代(LOOP)。随着 Agent 开始参与代码改造、研究、运营和跨系统操作，任务中出现了独立的检查分支、不同工具权限、人工审批、长时间运行和恢复需求。如果执行路径只存在于一段对话中，系统难以审查、调试和复现。
Graph Engineering 将执行路径、状态交接和控制规则从模型的临时上下文中分离，并写成可运行、可观测、可修改的图。
这里有两种经常混用的图：
- 工作图（work graph）：一次任务如何完成。节点是分析、实现、测试、审批或工具调用；边表示依赖、分支、回流与状态传递。
- 改进图（improvement graph）：系统如何长期调整。节点是指标、评估、策略、审计和人工决策；边表示谁能设定目标、谁可否决变更、哪些数据不能被优化过程改写。
工作图描述任务的执行过程，改进图用于检查系统持续优化后是否仍按设定目标运行。区分这两个层次有助于界定 Graph Engineering 的适用范围和演进方向。
Loop 是图中的基本执行单元
Loop Engineering 定义一个闭环的完成条件、验证器返回的证据、失败回流方式、最大重试次数和停止条件。例如，类型检查失败后将错误输出交给修复节点，再执行类型检查，就是一个 Loop。
Graph Engineering 定义多个闭环和确定性步骤的协作关系：哪些节点可以并行，哪些结果必须汇合，哪个节点能写文件，哪个操作必须经过人工确认。一条“验证失败 → 修复 → 再验证”的回边就是图中的 Loop；图为多个 Loop 定义边界和协调关系。
将 Graph 限定为 DAG 会遗漏实际需求。DAG 适合构建、测试、制品发布等依赖稳定且只向前推进的流程。Agent 工作流还需要条件分支、驳回、重试、暂停、恢复等回边，因此更接近状态机。
单一职责任务可优先使用 Loop。任务出现独立专业角色、并行扇出后汇合、差异化的工具和模型、需要审计的条件分支，或者一个验证器承担过多检查时，可以拆成 Graph 的节点。
Graph 编排提供的能力
“多个 Agent 互相对话”不能保证可靠性。图式编排提供四类能力。
隔离上下文和职责。 研究、实现、审阅如果共享同一上下文，审阅节点会读取产出过程中的原始材料和先前判断，独立性会受影响。拆分节点后，写作节点只消费结构化研究结果，审阅节点只消费产物和验收标准。节点边界也限定了上下文、提示词和工具集。
管理并行与汇合。 受影响包的测试、类型检查和视觉回归可以并行；发布前的汇总必须等待关键检查完成。显式边可以控制并发、预算和取消传播。
将状态作为可交接的事实。 模型对话适合记录推理过程，但不适合作为跨节点的唯一协议。固定 commit、lockfile、测试产物、失败分类和审批结论应进入共享状态，并具有版本和所有者。
在运行时设置治理点。 图可以在某条边上设置权限检查、人工审批、预算阈值、审计记录和恢复检查点。编排代码可读不表示运行安全；运行时需要限制、暂停、恢复和记录执行，图的拓扑才能用于治理。
用组件库 PR 说明工作图
以组件库 Button 的改造为例。任务除了修改代码，还要确定影响范围、运行多类检查、处理失败并决定是否创建 Preview。图中的重点是各节点的输入、输出和权限边界。
图：检查节点基于同一代码快照运行；失败证据作为状态传回修复节点；真实外部副作用排在独立验证和人工确认之后。
这张图包含五个基础约束：
- 固定输入：commit 与 lockfile 被固定，避免并行检查读取到不同工作区状态。
- 先确定范围：先分析影响包和路由，再选择测试集合，减少不必要的全仓执行。
- 仅并行独立分支：只在节点之间没有输入输出依赖时并发，汇总节点等待规定的结果。
- 回流附带证据：修复节点接收截图、堆栈、基线版本和受影响路由，避免根据模糊结论重新判断。
- 区分副作用权限：在 worktree 内修改代码与部署 Preview、发布包、合并主分支属于不同权限区。
图表达控制流，不要求每个节点都使用 Agent。解析 diff、去重、格式检查、依赖计算等确定性工作，普通函数通常更快、成本更低且更容易测试。Agent 适合需要语义判断或规划的节点。
节点契约
“视觉回归已完成”不能让下游安全地继续执行。下游至少需要知道运行的基线、受影响路由、差异数量、阈值、报告位置和失败类型。这些字段构成节点契约。
图：输入、输出、失败类型和运行参数共同定义一个可重放节点。
一个适合运行时处理的契约通常包含：
- 输入快照、配置和工具版本；
- 机器可读取的结果，以及日志、截图等产物引用；
- 可重试、配置错误、需要人工判断等失败分类；
- 幂等键，避免恢复后重复更新 snapshot、重复评论 PR 或重复发布；
- 超时、重试上限、取消策略和状态所有者。
契约使汇总节点能够拒绝不完整结果，也使恢复逻辑只重跑失效节点。将上一轮的聊天摘要复制给下一个 Agent，不能提供这些运行语义。
沿边设置权限、验证和失败处理
图只能表示一条风险路径；阻断动作需要在节点和边中定义。设计时需要写入以下三类控制。
跨节点的数据也需要权限控制
只读分析节点没有写权限，但其“修复建议”可能被下游写入节点直接执行。权限可随数据流扩大，因此需要同时检查工具调用权限和跨节点的输入资格。
图：从只读区进入受限写区、再进入外部副作用区时，都要满足明确条件；不可逆动作需要人工审批。
可以将节点分为只读、受限写入和外部副作用三个区。跨区时要求结构化输入、独立验证或审批令牌。发布 npm、合并主分支、删除资源等不可逆操作，不能由上游自然语言直接触发。提示词中的“请谨慎执行”不能构成权限控制。
验证需要独立来源
实现节点的自评可以提供线索，却不能作为唯一验收。前端任务已有大量确定性验证：tsc、eslint、单元测试、Playwright、构建产物校验。应优先让这些检查独立执行。changelog 是否准确、改动是否构成 breaking change 等语义判断，再交给独立审阅节点或人工确认。
多个 Agent 投票也不能替代独立验证。若节点读取同一份上下文、使用相似模型和提示词，结论会具有强相关性。增加投票数不能修正共享前提导致的错误。
汇聚规则处理检查失败
并发的收益取决于汇聚规则。九个检查通过、一个超时后，系统是继续等待、立即终止、标记待确认，还是复用已有结果，需要在设计阶段确定。
图：单测和类型检查属于关键分支；bundle size 需要完整报告；视觉回归可带着“待确认”状态进入人工检查。
类型检查或关键单测失败时，通常应取消后续高成本分支；bundle size 分析可能需要完整报告才能归因；视觉差异往往需要人眼确认，适合传递为待确认状态。检查点、幂等键和重试上限可以防止超时恢复后全量重跑或重复产生副作用。
改进图管理长期变化
工作图管理一次执行，改进图管理系统如何改变自身。改进图用于处理四类结构性问题。
指标脱钩。 如果只优化工单关闭率，系统可以通过缩短回复、阻止追问或过早标记解决来提高数值，却降低续费和满意度。对代码 Agent 而言，只追求完成率可能诱导它跳过昂贵检查、规避复杂任务或选择风险更高的工具。
执行环无法评估目标合理性。 快速执行环不能判断自己的目标是否合理。评测分数提高不自动说明线上质量提高；需要由另一个节奏更慢、职责不同的环来修改阈值和评估目标。
局部指标的冲突。 延迟、成本、覆盖率和安全性可能相互影响。每个局部环在自己的仪表盘上表现良好，整体系统仍可能恶化。
测量衰减。 线上分布、数据定义和日志链路会变化。评测集和自动化指标若不接受独立审计，可能在内部保持一致，却逐渐失去与真实结果的关联。
每个重要优化指标都需要放入更大的约束网络：
- 优化指标说明当前要改善什么，例如任务成功率、延迟或成本；
- 反向指标监视优化带来的副作用，例如错误率、回滚率和人工升级率；
- 目标所有者决定阈值由谁修改、何时生效，避免快速执行环自行降低门槛；
- **锚点（anchor）**提供优化过程不能改写的外部参照，例如保留评测集、线上回滚记录、人工抽检和真实用户结果。
锚点不接受被优化过程的修改，可用于检查内部指标是否仍然代表外部结果。缺少锚点时，所有节点可能显示通过，但验证依据可能是同一套已经过期的规则。
运行时治理的发展方向
节点和边的表达能力并不新。后续差异不只取决于“模型能否自动画图”，还可能体现在以下几个方向。
受约束的动态拓扑
静态图适合稳定流水线，但探索、故障排查和大规模改造的实际路径并不固定。模型会在运行中提出新节点、调整检查范围或选择修复分支。运行时需要允许这种动态性，同时限制可创建的节点类型、可访问的工具、预算和最大深度。需要解决的问题是允许 Agent 扩展图，同时限制图的生成范围。
可追溯工件作为状态
多节点系统的可靠性受状态质量影响。后续平台需要把代码版本、工具调用、测试产物、决策依据和审批记录保留为可寻址的工件，并建立清晰的数据血缘。这样可以追踪“哪个结论基于哪份代码和测试”“一次恢复是否复用了过期产物”“某个策略变更影响了哪些任务”。
调度中的成本、风险与时效
当前编排常将并行用于加速。实际调度需要考虑模型价格、工具配额、上下文长度、失败概率、风险等级和截止时间。低风险分支可使用较便宜的模型并行处理；触及生产环境的分支应使用更严格的工具权限与审批；关键分支失败后应优先取消无价值的后续工作。图运行时将承担工作流调度器和策略引擎的部分职责。
将评估纳入图节点
长期运行的 Agent 不能只依据单次任务是否成功调整策略。离线评测、线上抽样、回滚、人工复核和异常检测需要形成不同节奏的反馈环。快速环处理每次执行，慢速环检查评测是否漂移、阈值是否应变化、自动化范围是否应收缩或扩大。评估和治理节点可以与执行节点使用同样清晰的接口和审计记录。
人工修改共享状态
对高风险任务，人工还可在修改共享状态、指定恢复分支、冻结某个目标、标记某类失败不可自动重试，以及更新策略版本时介入。运行时能够暂停并显示可理解的状态时，人工可以在错误扩大前改变路径。
这些方向依赖持久化状态、检查点、权限隔离、取消传播、可观测性和审计等基础设施。缺少这些能力时，增加编排脚本会使长对话更难排查。
适合使用 Loop 的任务
Graph 有状态存储、序列化、调度、监控和恢复成本。以下情况通常不值得升级：
- 一个 Agent 加上明确完成条件和验证器即可完成的局部修改；
- 只需短期轮询 CI 或状态页的任务；
- 依赖关系尚未摸清的探索任务，此时固化拓扑会放大错误假设；
- 发布、迁移、对外消息等高风险操作，分析可以进入图，执行保留给独立审批；
- 解析 diff、去重、格式校验等确定性工作，直接使用函数更合适。
是否值得成图，可以用两个问题筛选：任务是否存在真实的依赖或并行分支；每个阶段能否交付可独立验证的结果。两个答案都为“是”时，图同时具备调度价值与收敛基础。
先在一段流程中使用图
可从现有 PR 流程截取一段窄图，例如“影响分析 → 实现 → 并行确定性检查 → 汇总 → 人工确认”。实施时先完成四件事：
- 复用现有 CI，让 Agent 调用或解释
tsc、eslint、Playwright 的结果，不重新发明验证。 - 在增加节点前定义退出条件、汇聚规则、预算和重试上限。
- 为每个节点记录代码版本、输入、产物、权限决策和失败日志，使一次运行可以复现和审查。
- 将一次任务的工作图与长期优化的改进图分开，为关键指标配置反向指标、锚点和人工所有者。
Graph Engineering 要求将 Agent 的路径、状态、权限和评估关系作为工程对象处理。工作图定义一次执行的控制和恢复方式；改进图用于检查长期优化是否仍对应外部结果。运行时需要可靠地连接这两类图。
参考资料
- Eigent：Graph Engineering for AI Agents: Beyond Single Feedback Loops：https://www.eigent.ai/blog/graph-engineering-ai-agents
- AI Builder Club：Graph Engineering Guide (2026)：https://www.aibuilderclub.com/blog/graph-engineering-guide-2026
- AI Builder Club：Graph Engineering vs Loop Engineering：https://www.aibuilderclub.com/blog/graph-engineering-vs-loop-engineering
- AI Builder Club：Graph vs Loop: Which Should Your Agent Use?：https://www.aibuilderclub.com/blog/agent-graph-vs-loop-when-to-use
- AI Builder Club：Is Graph Engineering Just LangGraph?：https://www.aibuilderclub.com/blog/is-graph-engineering-just-langgraph
- LangGraph Docs：Workflows and agents：https://docs.langchain.com/oss/javascript/langgraph/workflows-agents
- Microsoft AutoGen：GraphFlow (Workflows)：https://microsoft.github.io/autogen/stable/user-guide/agentchat-user-guide/graph-flow.html
- GitHub Actions：Workflow syntax：https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idneeds
- XState Docs：https://stately.ai/docs/xstate
