发布时间2026-08-31标签AI Agent工程实践架构设计PlannerReviewer上一篇我把 Repo Doctor 的需求拆成了八个槽。八个槽填满了但它们是零件不是机器。接下来要回答的问题是这些零件该怎么连起来我不想要一张看起来很专业的架构图——网上那种画满几十个节点的图我见过太多也踩过太多坑。我想要的是每一个节点都能回答一个问题没有它会怎样系列导航上一篇AI Agent 工程实践37需求分析——一个 Agent 项目到底应该怎么拆下一篇AI Agent 工程实践39第一次实现——先做一个最小 Agent问题背景这是第五阶段的第三篇也是定义问题 → 拆需求 → 画架构三步曲的最后一步。先说一个反常识的观点架构设计的重点从来不是图本身而是每个节点的取舍理由。一张架构图里如果某个节点你只能说大家都这么画或者这很先进那它大概率是不该存在的。Agent 架构尤其如此。因为 Agent 的每一个节点都在消耗 Token、增加延迟、扩大失败面。多一个节点不只是多一段代码而是多一个会出错的地方。很多人画 Agent 架构图习惯从网上的参考图里抄节点——别人有 Planner我也画一个别人有 Memory我也加一个。这种抄出来的架构有两个致命问题你不知道它为什么存在所以出了问题你不知道该往哪里查。你不知道它该多轻多重——画了 10 个节点其实 3 个就够或者画了 3 个其实少了 1 个关键节点。所以这篇我不画最终架构而是画第一步架构——Repo Doctor v0 该有的最少的节点然后逐个讲清为什么必须有它。错误尝试第一次尝试无架构裸跑我最开始想的是无架构一个 LLM 一堆工具直接让它自由发挥。结构就像这样用户问一句我把工具列表丢给 LLM它想调哪个调哪个想调几次调几次最后吐个答案。这个裸 Agent模式写起来确实快跑起来也确实能出结果。但很快暴露三个致命问题第一没有分工。三种任务——定位 bug、解释代码、PR review——全挤在同一个自由发挥里导致它经常该定位的时候去解释该审查的时候去定位。第二没有终点。因为没有查够了吗的判断它要么读一两个文件就草率下结论要么读几十个文件停不下来Token 烧到爆。第三没有把关。LLM 会幻觉会证据不足就自信地编。没有一道关卡去验证你的结论真的有文件支撑吗它编错了你都不知道。第二次尝试抄网上的架构图第一次失败后我换了另一个极端直接抄一张网上的标准 Agent 架构图。那张图上有Router、Planner、Executor、Memory、Reflection、Evaluator、Guardrail……十几个节点看起来特别完整。结果呢跑起来之后我发现自己根本无法判断问题出在哪个节点——因为我根本不知道这些节点各自解决什么问题、边界在哪。加了 Reflection 节点Agent 反而更慢了加了 Evaluator它输出的评估和最终结论互相矛盾。抄来的架构是别人的答案不是你的推理。你需要的不是一张看起来很全的图而是一张每个节点都能回答为什么的图。关键观察沿着三个问题我逐个问自己缺了会怎样于是三个节点应运而生问题缺了会怎样解决方案任务不分流三种任务互相干扰输出跑偏Task Router不知道查到哪算完草率下结论 / 无限烧 TokenPlanner没人验证结论幻觉成灾错得理直气壮Reviewer核心洞察架构图不是越复杂越好每个节点都要能回答没有它会怎样——答不上来的节点就不该存在。而反过来也正是这个缺了会怎样的追问让我在第四步做了个反直觉的决定现在不上 Multi-Agent。这个决定值得多说几句。因为既然有 Task Router、Planner、Reviewer 三个角色为什么不干脆拆成三个 Agent——这是几乎所有第一次看到这个架构的人都会问的问题。答案是角色node和 Agent 不是一回事拆不拆要看成本账这笔账会在第 48 篇完整算这里先给结论当前规模下拆的收益职责清晰撑不起成本Token 翻倍、延迟上升、失败面×3。最终方案Repo Doctor v0 架构先给出完整架构再逐节点讲为什么。为什么需要 Task Router因为三种任务定位/解释/审查的路径完全不同定位 bug 要现象→反查解释代码要直接读→讲清PR review 要diff→lint→test。把它们塞进一个 Prompt 里让 LLM 自己切换它会串味。Task Router 就是第一道分流闸先判断用户意图属于哪类再走对应的处理逻辑。这个节点极轻——甚至一个分类 Prompt 或规则就能做但它决定了整个下游的走向。判断标准如果你只有一个任务类型Task Router 可以直接删掉一旦有两种以上、且路径不同它就必须存在。为什么需要 Planner因为定位 bug是多步调查不是一步问答。Planner 的职责是基于当前 State已读什么、已知什么决定下一步查什么。它的价值在于给调查一个终点意识——查够了就停没查够就继续。这也是 Agent 的自主性真正发生的地方。Planner 不是预置的固定步骤而是动态生成下一步这正是 Repo Doctor 区别于 Workflow 的核心第 47 篇会反过来讨论什么时候这种动态不值得。判断标准如果任务是一步到位的问→答不需要 Planner一旦需要多步调查、且每步依赖上一步结果Planner 就必须存在。为什么需要 Reviewer因为 LLM 会幻觉。Analyzer 综合了证据、下了结论但综合这一步本身就可能出错——它可能忽略反例、可能把不相关的文件硬扯进来、可能证据不够就自信地编。Reviewer 是一道独立关卡你的结论每一句都要能回溯到具体的文件行。对不上就打回 Planner 重新查。这是证据链闭合的硬约束也是 Agent 敢上生产的前提之一。判断标准如果你的 Agent 输出用于决策/生产而你又无法忍受幻觉Reviewer 就该存在——它是幻觉的最后一道闸。为什么现在不上 Multi-Agent这是本篇最重要的一个不做什么的决定。有人会问Task Router、Planner、Analyzer、Reviewer这不是四个角色吗为什么不干脆拆成四个 Agent答案是成本账现在只有 6 个工具、3 种任务、单仓库。拆成 Multi-AgentToken 翻倍、编排延迟上升、失败面从 1 变 4而收益——职责清晰——在这么小的规模下几乎体现不出来。这些角色现在是节点不是Agent。它们共享同一个模型调用上下文只是逻辑上分工。等哪一天单 Agent 的职责冲突真的到了拆开的收益超过编排成本再拆——那是第 48 篇的事。第二张图四个节点的职责边界视角发布提示可用 draw.io 重画成正式图与 Mermaid 图形成双图组合┌─────────────┐ │ Task Router │ 只回答这是什么任务→ 走哪条路 └──────┬──────┘ │ ┌──────▼──────┐ │ Planner │ 只回答下一步查什么查够了没 └──────┬──────┘ │ ┌──────▼──────┐ │ Analyzer │ 只回答这些证据能综合出什么结论 └──────┬──────┘ │ ┌──────▼──────┐ │ Reviewer │ 只回答结论每句都有文件行支撑吗 └──────┬──────┘ │ 不通过 → 打回 Planner红色回旋 │ 通过 → 输出 ▼ Result(结论证据) 记住这四个是节点共享上下文 不是四个 Agent各自独立——拆不拆看第 48 篇的成本账。代码或配置示例架构不能只画图得落到能跑的骨架上。下面是 Repo Doctor v0 的节点骨架伪代码展示分工而非完整实现# repo_doctor/v0/nodes.py —— 每个节点一个函数职责单一 def task_router(query: str) - str: 分流定位 / 解释 / 审查 return classify(query) # - bug_locate | code_explain | pr_review def planner(state: State) - Action: 基于当前状态决定下一步查什么 if not state.hypothesis: return Action(toolgrep, argsstate.query_keyword) if state.need_more_evidence(): return Action(toolread_file, argsstate.pending[0]) return Action(tooldone) def analyzer(state: State) - Conclusion: 综合证据形成结论 return synthesize(state.clues, state.files_read) def reviewer(conclusion: Conclusion, state: State) - Verdict: 验证结论的每一条都能回溯到文件行吗 for claim in conclusion.claims: if claim not in state.evidence_map: return Verdict(rejectTrue, reasonf无证据支撑: {claim}) return Verdict(acceptTrue)注意reviewer的最后三行——它是硬约束不是建议。证据链闭不上就回炉。这就是 Reviewer 节点的全部意义。再给一个节点职责自检表用来判断你的架构里每个节点该不该存在# 节点自检表回答不上来就删掉这个节点 node_checklist: - 没有它会怎样 # 必须答出一个具体后果 - 它回答的问题是什么 # 一句话说清职责 - 它是最轻的实现吗 # 一个函数能解决就别上独立服务 - 它和邻居的边界清楚吗 # 职责不能重叠Planner 不该顺便做审查设计权衡候选方案优点缺点为什么不选裸 Agent无架构最快能跑任务串味、无终点、幻觉无把关三个致命问题无法接受抄网上的完整架构看起来全无法判断问题出在哪个节点别人的答案不是你的推理四节点架构分工清晰、有终点、有把关多几个节点多些成本每个节点都能回答缺了会怎样一步到位拆 Multi-Agent职责最清晰Token 翻倍、失败面×4、当前规模用不上提前优化收益撑不起成本最后一行的不选理由值得单独说过早拆 Multi-Agent是 Agent 项目最常见的过度工程之一。你会在第 48 篇看到即便是到了 V2 阶段我也只抽了一个 Reviewer 节点而没有拆成真正的多 Agent。常见误区FAQQ1架构图里的节点越多越好吗恰恰相反。每个节点都是成本Token、延迟、失败面。判断标准只有一条没有它会怎样答不上来的节点就是过度设计。Q2Task Router 会不会很重不会它应该是最轻的节点。多数情况下一个分类 Prompt、甚至几条规则就能完成。它存在的意义是分流不是理解。Q3Planner 和 LangGraph 里的规划节点一样吗思想一样都是决定下一步。区别在于LangGraph 的规划由你预置的边和条件路由表达Repo Doctor 的 Planner 是动态生成下一步。后者的自主性更强调试也更难这正是第 41-42 篇要解决的问题。Q4Reviewer 会不会让 Agent 变慢很多会有一点但值得。Reviewer 通常用轻量模型或规则实现检查结论里的文件名是否真的在证据链里成本远低于它拦下的幻觉损失。Q5什么时候才应该从节点升级成 Agent当职责冲突到了单 Agent 无法承受的程度——比如 Planner 和 Reviewer 在同一上下文里互相干扰、导致状态混乱。这个临界点第 48 篇用四本账Token/Latency/Complexity/Failure Surface来算。总结✅ 架构设计的核心不是图是每个节点的取舍理由。✅ 三个节点各司其职Task Router 分流、Planner 定终点、Reviewer 把关。✅ 铁律答不上没有它会怎样的节点就不该存在。✅ 现在不上 Multi-Agent因为规模撑不起成本——节点 ≠ Agent。✅ 架构落成每个节点一个函数的骨架下一篇动手实现最小版本。参考资料Anthropic《Building Effective Agents》的 Workflow vs Agent 边界 → 为什么引用为节点而非 Agent的决策提供了理论依据。LangGraph 的 node 设计 → 为什么引用每个节点一个函数的分工方式直接借鉴自它的 StateGraph 模型。系列导航上一篇AI Agent 工程实践37需求分析——一个 Agent 项目到底应该怎么拆下一篇AI Agent 工程实践39第一次实现——先做一个最小 Agent本文是 [AI Agent 工程实践] 系列的第 38 篇。