Graph Engineering：从线性 Loop 到有向图的进化实践探讨

目录引言第一章先认清现状——你已经有半个 Graph 了第二章Graph Engineering 的好处、代价与推荐场景2.1 好处2.2 代价好处的另一面2.3 推荐使用场景第三章要新增 / 改造什么对照 Loop 的四件套第四章落地方案分 4 步从小到大4.1 第 1 步把状态机数据结构从数组改成图4.2 第 2 步实现三种图特有的流转能力4.3 第 3 步护栏适配图结构关键安全点4.4 第 4 步可视化Graph 的天然优势第五章一个务实的建议——现在需要做 Graph 吗总结前两篇小马聊了Harness Engineering给 AI 套马具、不乱跑和Loop Engineering让 AI 在轨道上自己跑完全程。这一篇再往前推一步当流程不再是一条直线而是要分叉、并行、按情况走不同路的时候就轮到Graph Engineering图工程上场了。引言在上一篇《从Harness Engineering到Loop Engineering的演进实践方法论》里小马把mydemoPro的工作流从每步都要人推的线性流程升级成了自主循环、失败自愈、只在关口找人的 Loop。用下来很爽——大部分变更AI 自己就从评审一路跑到归档了。但跑着跑着小马又冒出个新念头为什么单测、代码规范检查、安全扫描非得一个一个排队跑它们互不依赖明明可以同时跑啊。还有——改一行文案的小需求凭什么也要走和改核心逻辑一样长的全流程这两个念头线性的 Loop 都满足不了因为 Loop 本质是一条线。要解决就得把工作流从直线升级成有向图——这就是这一篇的主角Graph Engineering。先说结论免得你担心又要推倒重来Loop 其实已经是一张退化的图了一条主链 一条失败回边。所以 Graph Engineering 不是从零再来而是把这张图长出更多结构分支、并行、条件路由、汇合。第一章先认清现状——你已经有半个 Graph 了Loop 的状态机本质上就是一张图只是目前是最简单的形态当前Loop一条主链 一条回边 评审 → 提案 → 写码 → 测试 → 部署 → 归档 ▲______|测试失败回退写码Graph Engineering 要做的是让这张图长出更多结构目标Graph分支 / 并行 / 条件路由 / 汇合 ┌─→ [单测] ─┐ 写码 ─→ (并行分发) ├─→ [规范检查] ├─→ (汇合) ─→ 部署 └─→ [安全扫描] ┘ │条件路由 简单变更? ──是──→ 直接归档 └─否──→ 走完整链一句话从一条线到一张网这就是 Graph 相对 Loop 的进化。第二章Graph Engineering 的好处、代价与推荐场景2.1 好处相比 Loop 的一条线走到底把工作流建模成有向图带来这些能力好处具体是什么Loop单链做不到的地方1. 并行提速一步之后同时跑多个互不依赖的任务如同时跑单测 / 规范检查 / 安全扫描全过才汇合单链只能串行一个个等慢2. 条件路由分支按变更类型 / 结果走不同路径如简单文案改动直接归档跳过重流程单链所有变更走同一条全流程小改也得走完3. 多路径复用同一节点不同来源都能汇聚到同一步骤如多种检查都汇到部署单链结构僵硬复用靠硬编码顺序4. 天然可视化图能直接渲染成流程图实时高亮当前节点 / 走过路径 / 卡点单链可视化价值低就一条线5. 多 Agent 编排不同节点交给不同专长的 Agent图负责调度它们的协作与汇合单链难以表达谁做哪段、如何并行协作6. 结构即文档节点 边本身就是流程的声明式描述改流程 改图不改控制逻辑单链改流程往往要动代码顺序一句话Graph 的核心好处是“表达力和并行度”——它能描述 Loop 无法表达的分支、并行、汇合、多 Agent 协作。2.2 代价好处的另一面任何增强都有成本Graph 也不例外代价说明复杂度上升节点 边 条件 并行 汇合比一条直线难写难调护栏更难做图可能有多条回边防环、并行卡点裁决、失败传播都要额外处理否则更容易跑飞调试变难并行 / 分支让到底走了哪条路不如单链一目了然过度工程风险如果流程本来就是线性的上图纯属自找麻烦2.3 推荐使用场景该用 Graph 的信号出现任一即值得考虑✅有互不依赖、可并行的步骤比如单测、规范检查、安全扫描、类型检查可以同时跑——并行能明显提速。✅不同变更要走不同路径比如改一行文案想跳过完整评审直接归档改核心逻辑才走全流程——需要条件路由。✅多 Agent 分工协作前端 Agent、后端 Agent、测试 Agent 各做一段并汇合——图天然适合编排。✅流程会频繁调整希望改流程 改配置边表而非改代码。✅需要流程可视化 / 可观测想在面板上看清每次跑的实际路径。不该用 Graph、Loop 就够的信号❌ 绝大多数变更是评审→写码→测试→归档的固定线性流程。❌ 步骤之间强依赖、无法并行后一步必须等前一步结果。❌ 单人 / 单 Agent 开发没有多方协作编排需求。❌ 团队规模小、追求轻量不想引入图的复杂度和外部框架。第三章要新增 / 改造什么对照 Loop 的四件套如果你已经按上一篇搭好了 Loop 的四件套技能包驱动 状态机脚本 护栏规则 复用已有能力升级到 Graph 只需扩展其中两件技能包和护栏规则基本复用组件现状Loop升级为 Graph 要做什么状态机脚本线性阶段数组 单回边改成图定义节点 边 条件核心改造点契约文档描述线性阶段增加图的节点 / 边 / 路由规则定义驱动技能包阶段→能力委派表基本复用补如何走分支 / 并行的说明护栏规则卡点 / 上限 / 护栏基本复用补并行节点的卡点如何裁决第四章落地方案分 4 步从小到大4.1 第 1 步把状态机数据结构从数组改成图Loop 里阶段通常是一个有序数组阶段 [评审, 写码, 测试, ...]一条线走下来。Graph 的第一步就是把它改成显式的「节点表 边表」# 节点每个是一个可执行阶段NODES{评审:{gate:None},写码:{gate:写代码前审批},单测:{gate:None},规范检查:{gate:None},安全扫描:{gate:None},部署:{gate:部署前审批,optional:True},归档:{gate:提交前审批},}# 边从哪个节点、在什么条件下、去哪个些节点EDGES[{from:评审,when:通过,to:提案},{from:写码,when:通过,to:[单测,规范检查,安全扫描]},# 并行分发{from:单测,when:失败,to:写码},# 回边{join:[单测,规范检查,安全扫描],when:全部通过,to:部署},# 汇合]这一步是 Graph Engineering 的核心——用节点 边取代线性顺序一切分支 / 并行 / 循环都由边表描述。之后要改流程改这张表就行不用动控制逻辑。4.2 第 2 步实现三种图特有的流转能力线性状态机没有、图才需要的三样能力含义实现要点条件路由分支一个节点后按条件走不同路径边上加条件如简单变更 → 直接归档并行分发 / 汇合一个节点后同时触发多个节点全通过才汇合记录并行组状态汇合节点等所有分支通过才前进循环回边失败回退Loop 已有复用现有的失败回退表泛化成边表里的回边4.3 第 3 步护栏适配图结构关键安全点图比线性复杂护栏要跟上否则更容易跑飞防环失控图可能有多条回边 → 全局最大步数上限必须保留且要检测非预期环A→B→A 无限转。并行卡点裁决并行分支里若有节点需要人工放行如安全扫描要定义并行组里任一卡点未放行 → 整组阻塞。汇合的失败传播并行分支只要有一个失败汇合点应判定失败并触发对应回退而不是傻等。一句话图越灵活护栏越要收紧。表达力和安全性要同步升级否则灵活就变成失控。4.4 第 4 步可视化Graph 的天然优势图结构可以直接渲染成流程图如 Mermaid接到你已有的可观测面板实时高亮当前在哪个节点标出走过的路径、回退的次数、卡在哪个汇合点这是 Graph 相比 Loop 的一个直观增值——线性流程画出来就一条线没啥好看的图画出来一眼就能看清这次跑批走了哪条路。第五章一个务实的建议——现在需要做 Graph 吗聊了这么多好处小马还是得泼盆冷水大多数项目现在还不需要做完整的 Graph。判断很简单对照第二章 2.3 的信号如果你的变更绝大多数是评审→写码→测试→归档的固定线性流程、步骤之间强依赖没法并行、又是单人开发——那Loop 就够了别为了图而图。mydemoPro目前就是这种情况所以小马也还没把它升级成完整的 Graph。但这不代表什么都不做。更稳的路径是备而不用何时推进建议动作现在保持 Loop别为了图而图打地基可选随时先把状态机里的阶段数组悄悄重构成节点 边表结构行为不变把图的底子留好出现分支 / 并行 / 多 Agent 需求时再开启第四章第 2 步的分支 / 并行能力——此时升级成本很低想接入成熟框架时可评估 LangGraph 等图编排框架但会引入外部依赖与纯标准库轻量脚本的风格不同需权衡核心原则一句话先把数据结构留成图可扩展的样子需求来了再点亮不一次到位。总结把三篇串起来看其实是一条清晰的进化线阶段解决什么工作流形态HarnessAI 会不会乱写—约束地基LoopAI 每一步都要人推一条线单链状态机Graph流程要分叉、并行、多 Agent 协作一张网有向图三句话带走什么是 Graph把工作流从一条线升级成一张有向图支持分支、并行、条件路由、汇合。为什么用 Graph并行提速 按需分流 多 Agent 编排 可视化——线性流程给不了的表达力。要不要现在做多数线性场景 Loop 就够先把数据结构留成图可扩展的样子需求来了再点亮。最后照例送一句心法Harness 让 AI 不越界Loop 让 AI 自己跑完一条线Graph 让 AI 在一张网里分工协作——表达力越强护栏越要收紧。Graph 也没有标准框架都是按需进化的。理解了它和 Loop 的关系你就知道不必一步到位先把地基留好等真需求来了从单链长成网其实很自然。不懂的、想交流的还是老规矩可以联系小马哈。这是继 Harness、Loop 之后的第三篇建议三篇连起来看。