用于AI编码智能体的图谱工程：上下文、合同与修复机制
合同驱动的智能体图谱给一名开发者带来的启示：范围明确的上下文、确定性的验证、有针对性的修复，以及何时额外的计算成本是合理的。
来源: Graph Engineering for AI Coding Agents: Beyond Prompt Loops
“图工程”近来备受关注，大多数解释都集中在图、节点和有向无环图上。这些内容固然重要，但并未回答真正值得探讨的问题：为什么人工智能编程工具突然就需要图工程了呢？
一位曾使用过 Claude Code 及后来的 Codex 等工具数月的开发者发现了一个规律。大多数编程任务失败并非因为模型无法编写代码，而是因为长时间运行的工作流逐渐失去了结构。上下文不同步、需求被遗忘、输出结果难以验证，而当出现问题时，最简单的解决办法往往是重新启动整个任务。
这一观察促使人们提出了一个名为 ContractGraph 的小型研究框架。以下内容将阐述该框架的理念、其成功之处与不足之处。它并非为与现有框架竞争而设计，也不绑定于特定模型。其目标更为具体：能否设计出一种工作流程，使得每一步都有明确的目标、清晰的契约，以及确定性的方法来判断该步骤是否真正完成？
其结果是一种基于契约的图结构，通过独立的任务、明确的验证以及有针对性的修复来执行研究工作流程，而非依赖一个庞大的提示词。最初的实现是针对研究智能体的，但这些核心理念同样适用于编码智能体、文档处理流程、评估系统，以及任何需要多个人工智能驱动的步骤来产生可验证结果的流程。需要注意的是，这只是某位实践者的实验，因此所得结论属于经验总结，并非经过测量的基准数据。
图工程的意义
图工程是指将复杂的人工智能工作流程拆分为小的执行单元，并通过明确的规则将它们连接起来的方法。经过图工程设计的系统通常会整合多个执行单元、明确的路由机制、共享状态、验证功能以及稳定的协调机制。
每个节点只承担一项职责。边负责决定下一步操作。在整个工作流中共享的状态会传递信息，而验证阶段则负责判断是继续执行、重新尝试、修复错误还是停止。
设计背后的两个问题
开发者原本以为大部分时间会花在节点、边以及执行流程上，却发现这些并非最困难的部分。有两个问题不断浮现。
第一：AI智能体应被允许将哪些信息视为真实？第二，当它完成任务后：如何判断其输出确实符合要求？
测试的长时间运行的工作流越多，就越明显地发现这些问题比图结构本身更为重要。如果智能体从错误的信息出发，或者最终没有可靠的方法来验证自己的工作，它就只会将错误从一个节点传递到另一个节点。这两个问题最终被定义为上下文和契约。上下文决定了智能体可以被允许相信什么，而契约则规定了它必须产出什么。该框架中的其他所有内容都依赖于这两个概念。
作为构建块的上下文与契约
图结构并非最难的部分。真正的挑战在于确保每个节点在开始时都拥有正确的信息，并且在工作流继续进行之前能产出可验证的结果。
上下文。智能体不应看到所有信息。每个节点仅能获取其可信的资料，例如用户需求、项目约束、已验证的文档，或是来自前序节点的已确认结果。
契约。每个节点都需要明确界定其必须交付的内容。当某项结果未达到契约要求时，工作流不能继续推进，而应检查输出、修复出问题的环节，或停止执行。
简而言之，上下文决定了智能体可以相信什么，而契约则规定了它必须交付什么。一旦这两项边界明确，该图结构就更容易被理解。每个节点都有明确的功能、单一的真相来源、可量化的输出，以及在进入下一步之前的确定性判断机制。
从创意到可执行的图结构
既然上下文与流程已被分开，接下来的问题就是如何让它们构成一个可运行的工作流。我们的目标并非为研究、编码或文档生成分别硬编码独立的流程图。相反，工作流应从问题本身动态生成，而非依据预定义的路径。首先需要完成两个步骤。
第一步是构建上下文。并非每个文件或文档都值得同等信任，因此工作流会整合出一个标准上下文：即所有节点均可依赖的经过验证的权威信息源。其原始材料因任务而异，比如项目文档、用户需求、代码、设计文档或其他被认为可靠的输入内容。
第二步是构建合同。它并非仅用文字描述任务，而是生成一份结构化的合同，明确每个阶段需要产出什么、各节点之间如何相互依赖，以及在执行前必须验证哪些内容。
当这两部分都准备就绪后，工作流就会被编译。这个初始化阶段不会执行任何操作，其职责仅为规划。通过这一阶段会生成执行图、每个节点的上下文包、可重用的清单与共享技能，以及根据合同确定的执行顺序，而无需固定的顺序设定。
之后的执行过程十分简单。每个节点仅接收其对应的上下文包，完成分配给它的任务，经过确定的验证流程，保存通过验证的结果后再将控制权传递下去。如果验证失败，只需修复受影响的节点即可继续执行，无需从头开始。
因此，该图的结构源自初始提供的上下文与契约，而非固定的实现方式。同一套编译流程可以用于构建研究、编码、文档编写或完全不同的工作流，而无需改变运行时环境。
在更大和更小的模型上测试
设计框架仅是工作的一半。更棘手的问题是，当工作流规模大到足以暴露其缺陷时，这种架构是否依然能够正常运行。
最初的实验在 Claude Code 中使用了规模更大的工作流，其中包含动态生成的执行节点、嵌套的规划阶段以及漫长的研究任务。虽然质量相当出色，但完成整个工作流需要大量的模型计算资源。
这引出了一个后续问题：在规模更小、成本更低的模型上，同样的图结构是否仍能实现可靠的工作流？第二次实验采用了学习计划生成工作流，通过OpenCode和Big Pickle来执行，而非使用前沿模型。其机制保持不变：工作流被动态编译，生成专用节点，每个阶段都会经过确定性验证，出现故障时会在必要时进行修复，最终结果仍来自同一流程。
实验的目的并非比较模型或选出最优者，而是探究可靠性在多大程度上源自执行架构而非模型本身的能力。令人惊讶的是，最大的问题并非模型故障，而是工作流故障，正因如此，图结构设计才显得如此重要。
出现故障的环节
该实验并未表明图结构设计能够防止故障发生，反而显示它能让故障更加显而易见。
在此过程中出现了各种问题：不完整的元数据、缺失的证据、未解决的引用、重复的内容、无效的生命周期状态、错误的追踪信息，甚至纯粹的编码问题。这些都不是图结构设计导致的，而是长期运行的人工智能工作流中本就可能出现的故障。
变化在于每个故障都有明确的位置。不再将整个运行过程视为一次失败的执行，而是可以找到违反约定的具体节点，仅修复该节点，再次进行确定性验证，然后从该节点继续运行。由于所有成功的阶段都已被验证并保存，工作流的其余部分依然保持完好。
这改变了开发者对这项技术的看法。它并非让模型变得更聪明的方法，而是让错误变得局部化、可观察且可修复的手段。该图谱虽不能消除错误，但能为每个错误定位具体位置。
为何验证必须具有确定性
模型可以十分肯定地宣称某项任务已完成，但这并不代表它确实如此。语言模型在推理、总结和决策方面表现优异，但它们无法可靠地判断工作流程是否满足了自身要求。
正因如此，ContractGraph中的每个节点都会经过一次确定的检查。无需再向另一个模型寻求对结果的看法。该工作流程会检测客观条件：架构是否包含所有必需的字段？依赖关系是否已满足？所需的输出结果是否存在，且引用是否有效？该节点是否履行了其合约所承诺的所有内容？这些都不是主观判断，每项结果仅有“真”或“假”两种可能。
这种分离被证明是该框架中最有价值的理念之一。模型负责推理，而确定性验证则负责确认。模型可以声称自己的工作已完成，但只有确定性验证器才能证明某个必需字段缺失。
为何多此一举也能带来回报
甚至在开展这项实验之前，开发者就已经将人工智能编程工具视为一个小团队，而非单一的助手。Claude Code、Codex和OpenCode同时处理同一个代码库中的不同部分其实很常见。
但这引发了意想不到的问题：这些工具可能最终需要修改相同的文件或依赖相同的实现方式，若缺乏协调，就有可能覆盖掉其他工具的工作成果，或使之前所做的假设失效。
解决办法很简单：每项任务都有指定的负责人。如果某个工具负责代码库的某部分，其他工具在负责人允许之前不得触碰那些文件。在每个重要步骤之后添加验证环节，这样许多冲突就永远不会出现在代码库中。
其中的权衡显而易见。这种开发方式需要远远更多的计算资源，因为每次验证、重试、修复和协调步骤都会增加工作量，而让单个模型在单次对话中完成功能开发则无需如此。然而最终结果却有所不同。无需反复修复先前修复措施带来的问题，工作流程变得更加可预测，而且以这种方式开发的功能几乎不需要再做修改，因为每个阶段都会在进入下一阶段之前得到验证。
图引擎并非每个提示都应该使用的工具，对于小的改动来说纯粹是浪费资源。但对于规模较大的功能、复杂的实现或多智能体协作任务，额外的成本能带来比简单推理更有价值的东西——那就是确定性。
真正的成本是什么
切勿将此视为图工程是万能解决方案的论断。准备上下文、生成契约、编译图结构、进行验证、修复问题以及聚合数据，每一项都会增加额外的模型调用次数和计算资源消耗。与单一提示词相比，这样的工作流程无疑成本更高。
早期对前沿模型的实验虽然取得了优异成果，但却消耗了大量计算资源，这成为人们开始测试规模更小、成本更低的模型的主要原因。由此得出的结论是：图工程并不能减少计算量，它只是重新分配计算资源。系统不再将计算资源用于反复处理模型退化问题、重启失败的工作流程或修复下游错误，而是提前将其用于规划、验证以及故障隔离。
这改变了优化目标。图工程并非旨在实现最廉价的执行方式，而是追求最可预测的执行结果。某次OpenCode运行消耗了海量计算资源，这一数据不应被视作该方法成本低廉的证明。事实上，它恰恰表明了相反的情况——因为图工程刻意投入更多计算力，以实现故障隔离、可审计性、可恢复性以及更高的可靠性。这种权衡是否合理完全取决于具体问题。
何时值得采用
并非所有的AI工作流都需要图工程。对于SQL查询、小型函数或简单的UI调整，一个编写良好的提示语通常就足够了；而添加契约、验证层和执行图只会让事情变得更慢、更复杂。
当失败的成本高于额外计算的成本时，它就开始发挥作用。这适用于长期研究、大规模特征处理、多智能体工作流、对安全性要求较高的系统、企业自动化，以及任何需要确保输出可验证且可复现的流程。工作流的步骤越多，明确的协调机制就越重要。
其中的核心理念并非关乎智能。在流程复杂的情况下，合理的结构能让其更易于跟踪、检查、恢复和扩展。这一理念也远未成熟——基于依赖关系的执行、更智能的调度、资源优化、部分图的重编译以及智能体之间更丰富的协调机制都仍有待探索。简而言之：用提示词来完成任务，用图结构设计来构建系统。
总结
最初，人们期望学习图论相关知识。但实际上，这项练习教会的是边界设定、验证机制与协调方法。图本身并非关键，重要的是每一步都要有明确的目标，要限制智能体所能相信的信息范围，明确它必须输出的内容，并在继续下一步之前证明任务已完成。
这并非构建人工智能系统的唯一方法，也并非所有工作流程都需要如此严格的结构。但对于复杂、耗时或涉及多智能体的任务，图论方法能为打造更易预测、更易发展的系统提供实用路径。
如果非要记住一句话，那就记下这个流程：提示词阐述需求，上下文确定智能体可视为事实的信息，契约明确交付成果，而图则作为证明任务已完成的机制。
在本次实验进行时，ContractGraph仍在发展中，其代码仓库也尚未发布，因为需要先简化其架构。如需更全面的了解该主题，可搜索通用的图计算工程指南，因为本文仅介绍一个框架，并非整个领域的内容。
相关阅读
- 2026年AI编码代理如何重塑开发者的工作方式 — AI编码代理已从自动补全功能发展到能够完成完整任务。文中涵盖了采用情况数据、上下文工程、类型化代码、验证机制以及MCP技术，还分析了这些变化对初级和高级开发者的影响。