把循环画成图：learn-harness-engineering Project 08 图工程实战指南（从 Loop 到 Graph）

【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载本篇是 learn-harness-engineering 课程中「图工程Graph Engineering」入门项目Project 08的完整实战指南。你将把上一项目P07构建的 maker-checker 循环显式化为「节点 边 共享状态 路由规则」四要素构成的图并通过三次递进实验依次加入并行 fan-out/fan-in、条件回滚边与人工审批节点。读完本文你将掌握把任何单 Agent 循环拆解为可观测、可定位故障、可局部修复的执行图的方法论与落地步骤并能对照仓库中的 LangGraph 参考实现验证你的graph.md是否与真实执行一一对应。为什么循环长到一定程度就会自己变成图Project 08 是整个课程的转折点从「Loop」过渡到「Graph」。在 P07 中你构建的是一个 maker-checker 循环——实现、验证、反馈、再实现——所有决策都发生在一个 Agent 的上下文窗口内部。而本项目的核心动作只有一句话把隐藏在循环内部的结构显式写出来——节点、边、共享状态、路由规则逐字逐句落成文档。Lecture 14 给出了理解这件事的最佳坐标系工程命名是逐层叠加的而不是相互替换的——Prompt Engineering 塑造指令Context Engineering 塑造信息Loop Engineering 塑造运行时Graph Engineering 塑造系统。到了图这一层prompt、context、loop 全部存活每个节点携带自己的 prompt、自己的上下文、自己的工具、自己的记忆、自己的小循环图只负责决定节点之间如何连接。当某个任务需要专业化分工、并行、共享状态、验证与恢复时它就不再是一个循环而是一张图。把图拆到最简只有四个部件部件职责典型形态Node节点一个有明确职责的工作单元确定性代码跑测试、算覆盖率、模型调用生成文档、工具调用git commit、完整 Agent自带循环、能用工具、失败自愈Edge边工作如何在节点之间交接顺序、并行A 后 B/C 同时启动、条件测试过走左、失败走右、失败重试、回滚验证失败退回三步前的实现节点Shared State共享状态节点之间传递的数据包需求、研究笔记、代码版本、测试结果、评审结论全部写入同一个共享工作区Routing Rules路由规则决定执行下一步去哪图的控制流用最朴素的 if-then 语言书写Lecture 14 里还有一句对整个项目最有指导意义的话——「循环有很多可以原谅的空间图强迫你承认你的工作流中有多少部分其实从未被建模。」循环是把决策推迟一个 Agent 扛下所有工作卡住了再说图是把决策提前谁拥有什么、任务如何相互依赖、某个失败回退到哪里都必须事先声明。用更直白的话说循环把问题藏在循环里图把问题写在纸上。前者适合探索后者适合生产。本项目体验的正是这一转变过程。准备分支、共享状态与工具参照 Project 07 项目指南 完成 P07 后开始以下准备起点使用你在 P07 完成的仓库或任何你能反复运行的 Agent 工作流。创建三条分支p08-explicit-graph、p08-parallel、p08-human-in-the-loop三次实验各占一条互不污染。准备state.md作为共享状态文件需求、进度、验证结果全部写入其中。这就是整张图的「公共工作台」——图与循环的本质区别之一就在这里图层的节点不共享上下文只通过一份共享状态交接。工具方面需要 Claude Code 或 Codex、Git以及一个文本编辑器或绘图工具。记住原文档的提醒画图不是为了好看而是为了把结构写清楚——手写的graph.md和mermaid图都完全可以。实验 1把 Loop 画成显式图切到p08-explicit-graph分支这是三次实验中打地基的一步。① 列出所有节点把 P07 maker-checker 循环的每一步写成一个节点。对每个节点明确四件事它的职责、它的输入、它的输出、它是 Agent 还是确定性代码。② 画出所有边列出节点之间的每条边并标出两类特殊边——条件边验证通过/失败各走哪条路径回滚边失败时回到哪个节点。③ 写共享状态显式列出状态字段需求、代码、测试结果、评审结论以及每个字段由谁读、由谁写。④ 写路由规则用最朴素的 if-then 语言写出「下一步去哪」例如if verify passed → merge node if verify failed → implement node if implement node lacks information → research node⑤ 汇总成graph.md把以上内容组织成一份文档——一张 mermaid 图 节点表格 路由规则。⑥ 回答一个关键问题画完之后找出至少一条原本隐式的边——一条曾经藏在 Agent 上下文里、连你自己都不知道它存在的决策路径。这是整个实验的灵魂图的价值不是把已知流程画漂亮而是把未知的决策路径逼到纸面上。Lecture 14 的练习与 Project 08 的要求完全一致——画完graph.md后自问有没有一条边是隐式的、以前藏在 Agent 的上下文里实验 1 的对照模板Lecture 14 的六步构建法为了让画图不走样Lecture 14 的「从零构建你的第一张图」提供了六步标准流程与实验 1 的清单一一对应可以当作graph.md的写作模板Step 1定义共享状态。先在概念上分层图这一层只共享状态节点上下文是私有的。单体内 Agent 只有一个上下文长跑之后会被自己的转录淹没图把上下文切成一块块每个节点一块——循环是节点的私有财产图是它们交接的公共长椅。同时要声明每个字段的合并方式并发节点写同一字段时是覆盖、追加还是求和这不是框架特性而是你在画图时写进graph.md的规则state { requirements: text, # 由 research 节点写入 code: text, # 由 implement 节点写入 review: pass | fail, # 由 verify 节点写入 attempts: number, # 每次失败 1并发写入时按 sum 合并 }Step 2列出节点——每个节点都是一个完整 Agent自带小循环。这是图与工作流最根本的分野工作流节点是函数图节点是携带自己小循环的 Agent。节点读取共享状态、在自己的私有上下文里干活、再把结果写回共享状态。特别注意 verify 行单体内 Agent 的「评审」仍在同一上下文里运行等于自我评审在图里verify 必须拿到完全新鲜的上下文——它看不到 implement 的推理过程只能看到共享状态里的code。上下文隔离不是副作用而是设计本身。Step 3连接边。先铺确定性主干research → implement → verify → merge → end。Step 4写路由规则最重要的一步。verify 不直接连 merge而是连到一个决策——它决定执行下一步去哪。路由规则返回节点名让整张图从哪来、到哪去一目了然当前节点条件下一节点verifyreview passmergeverifyreview failimplementStep 5挂检查点。图与一次性脚本最大的区别之一是每步之后状态都被持久化进程死了可以从检查点续跑而不是从头再来你还可以在 merge 前暂停、等待人工审批——这正是 P07 里「人工评审」在图上的样子checkpoint on(graph, every_step) # 每步之后保存状态 graph.pause_before(merge) # 合并前停下等待审批Step 6运行图。每次运行传一个 thread id检查点靠它区分不同次运行run(graph, entry{requirements: fix the login page bug}, threadsession-1)对照检验你手写的graph.md是蓝图引擎里的代码是蓝图的可执行程序两者应当一一对应。如果对不上——要么图错了要么代码错了。这正是「图把问题写在纸上」的含义以前这种错位没人看得见现在一眼就能看出。实验 2添加并行 Fan-out / Fan-in 节点切到p08-parallel分支。单循环只有一条主干道而图可以把互不依赖的部分真正并行起来。① 选一个可并行点找到任务中能拆成两个独立部分的位置。原文档给了三类典型例子把实现拆成两个独立模块两个 Agent 并行编写把验证拆成两路独立评审一路跑测试与 lint一路做代码评审指令不同、关注点不同把研究拆成两个方向两个 Agent 各探一条线索。② 写 fan-out 规则在共享状态里记录「本任务被拆成 N 个并行子任务」每个子任务有独立上下文和独立节点。③ 写 fan-in 规则所有子任务完成后由谁来合并结果合并标准是什么例如两路评审都通过才合并还是只要一路通过即可这对应 Lecture 14 Step 1 中声明的字段合并规则——并发写同一字段时是覆盖、追加还是求和必须在graph.md里事先写死而不是让框架替你默认。④ 用 worktree 做物理隔离每个并行子任务在自己的 git worktree 里运行。这是回到 Lecture 13 讲过的 Worktree 原语——两个 Agent 写同一个文件就是两个工程师不商量就提交到同一行的噩梦。git worktree让每个 Agent 在自己的目录、自己的分支上干活物理上碰不到彼此的 checkout。但 Lecture 13 的警告依然成立worktree 消除的是机械性文件冲突你的评审带宽仍然是天花板——你能同时监督多少个并行 Agent才决定你能跑多少个 worktree。⑤ 运行一次并记录记下并行前后的 wall-clock 时间、token 消耗、结果质量。并行真的更快吗还是协调成本吃掉了节省下来的时间这就是 Lecture 14 引用的「编排税Orchestration Tax」启动一个 Agent 很便宜关闭它的循环很昂贵——检查它带回什么、与别的 Agent 改动的东西对账那个「别人」就是你而且只有一个你。你的判断力是串行资源加节点优化的是从来不是瓶颈的部分。实验 3添加回滚边与人工审批节点切到p08-human-in-the-loop分支。原文档明确这是三次实验中最重要的一个你要往图里加两类节点。① 条件回滚边给 verify 节点加一条「部分通过」路径——不是把整个结果弹回 implement 节点而是带着具体反馈回到制造问题的那个节点。例如测试全部通过、但代码评审发现需求被理解错了就回滚到 research 节点而不是 implement 节点。这要求你的共享状态记录「问题发生在哪一层」。这正是图相对循环的结构性优势循环里回滚靠 Agent「记得」该回去藏在上下文里图里回滚是一条画出来的边指向明确的层。Lecture 14 的四要素中回滚正是 Edge 可以表达的四种语义之一验证失败退回三跳之前的实现节点。② 人工审批节点Human-in-the-loop在 merge 节点之前插入一个人工节点。执行到这里停下来等你在state.md里写下「approved」或「rejected」。审批节点可以带超时规则N 小时内无响应自动拒绝或自动升级。这一步对应 Lecture 14 Step 5 的graph.pause_before(merge)——图在合并前暂停等待人类的点头。注意图与工作流的区别在这里收束一张图可以同时容纳工作流节点确定性代码、Agent 节点模型驱动与人工节点审批/评审图是容纳三者的容器。③ 写中断格式审批请求必须写清楚四件事——发生了什么、改了什么、为什么需要人类、批准或拒绝的后果是什么。一个写不清楚的审批请求本身就是 Lecture 11 所说的可观测性缺失图越复杂越需要看清每个节点在干什么。④ 至少跑 2 个完整周期每个周期都走到人工审批节点由你亲自批准或拒绝一次。记录两个问题你的审批决策与 verify 节点的判断一致吗审批节点有没有拦住 verify 节点没拦住的东西后一个问题直接呼应 Lecture 09 的教训——为什么 verify 节点必须独立于 implement 节点在图里这从 prompt 问题变成了结构问题法官与被告共用一个大脑结构上就注定无法独立裁判。如何衡量结果原文档给出了一张完整的对照测量表三次实验各看五类指标指标实验 1显式图实验 2并行实验 3人机协作结构可见性找到了多少条隐式边共享状态能否支撑并行子任务回滚边能否精确定位问题所在层失败定位失败时能否直接指出是哪条边错了并行子任务失败时能否定位是哪一条审批被拒绝时能否说出问题在哪个层协作成本画图花了多少时间并行节省的时间 vs 协调成本等待审批的时间 vs 被拦下的问题价值可观测性每一步在干什么现在看得见了吗每个并行子任务的状态可见吗审批请求写得够清楚吗可靠性图描述与真实执行一致吗fan-in 合并标准可靠吗超时/升级规则真的会触发吗测量时注意 Lecture 14 的冷水提醒看到「图工程带来 18% 准确率、−85% 成本」这类营销数字时要追问原始出处——图工程不是银弹拓扑结构本身也不是承重墙真正承重的是可重放性、可观测性与可恢复性这些工程能力。交付物清单graph.md实验 1 的完整图描述mermaid 图 节点表格 边表格 共享状态字段 路由规则实验 1 找到的隐式边清单至少一条实验 2 的 fan-out/fan-in 规则 一次并行运行记录时间/成本/质量对比实验 3 的回滚边规则、审批节点格式 2 轮人机协作记录最终复盘从循环走向图你的工作方式改变了什么哪些任务值得画成图哪些不值得关于「哪些值得画成图」Lecture 14 给出五条判定标准满足至少三条再动手任务可分解为相互独立的子工作单元能并行存在分支或回滚路径「测试失败回哪」「信息不足回哪」值得显式声明中间状态值得保存能在检查点暂停续跑而不是从零重启结果可以被显式验证每个节点都有可自动检查的完成定义协调收益 协调成本并行省下的时间超过图与共享状态的额外开销。「复杂」不等于「步骤多」一条 20 步的线性流水线不需要图那是工作流或脚本一个只有 5 个节点、但真有回滚、并行与审批的结构才需要图。决定因素不是规模而是分支与回滚的存在与否。参考实现与相关课程如果你想把实验 1 的graph.md变成可运行程序仓库提供了完整的 LangGraph 参考实现maker_checker_graph.py。它把 Lecture 14 的六步构建法一字不落地落成了代码——GraphState定义共享状态requirements/code/review/attempts四个字段、research/implement/verify/merge四个节点、route_after_verify路由函数实现条件回滚、MemorySaver()检查点、thread_idsession-1区分运行。对照阅读时你会认出它只是把你在graph.md里画的东西翻译成了可执行程序。节点内部的模型调用是占位的call_model抛NotImplementedError接入你自己的模型提供商即可运行。与本项目直接相关的课程还有Lecture 14 — From Single Loops to Graph Engineering本项目的主讲课程四要素、六步构建法、graph vs workflow 的完整辨析Lecture 13 — From Manual Prompting to Autonomous Loops你的循环是图里的一个节点本项目展开的是该节点的内部结构其中 Worktree、Generator/Evaluator 分离等原语是并行实验的直接依据Lecture 09 — Why Agents Declare Victory Too Early为什么 verify 节点必须独立于 implement 节点——在图里这是结构问题而非 prompt 问题Lecture 11 — Why Observability Belongs Inside the Harness图越复杂越需要看清每个节点在做什么。最后回到 Project 08 贯穿始终的那句结论作为你完成三次实验后的验收标准图不是发明它是循环在足够复杂之后自然变成的样子。你在实验 1 找到的隐式边、在实验 2 付出的协调成本、在实验 3 亲手按下的一次次批准与拒绝——这三样东西加起来就是「把问题从循环里搬到纸上」的全部意义。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐从 Loop 到 Graph用 Project 08 把你的工作流显式画成一张图learn-harness-engineering 实战从 Loop 到 Graph用 Project 08 把你的工作流显式画成一张图learn harness engineering 实战 本篇实战指南围绕Learn Harness Engineering 项目 08把工作流画成图——从单循环到图工程的第一步实战Learn Harness Engineering 项目 08把工作流画成图——从单循环到图工程的第一步实战 本教程是 Learn Harness Engin用 learn-harness-engineering 项目把 Agent 工作流画成图从 Maker-Checker Loop 到 Graph Engineering 的三步实战用 learn harness engineering 项目把 Agent 工作流画成图从 Maker Checker Loop 到 Graph Engine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考