发布时间：2026-08-31
标签：AI Agent｜工程实践｜架构设计｜Planner｜Reviewer

---

上一篇，我把 Repo Doctor 的需求拆成了八个槽。

八个槽填满了，但它们是"零件"，不是"机器"。

接下来要回答的问题是：这些零件该怎么连起来？

我不想要一张"看起来很专业"的架构图——网上那种画满几十个节点的图，我见过太多，也踩过太多坑。

我想要的，是每一个节点都能回答一个问题：没有它，会怎样？

---

系列导航

• 上一篇：AI Agent 工程实践（37）：需求分析——一个 Agent 项目到底应该怎么拆
• 下一篇：AI Agent 工程实践（39）：第一次实现——先做一个最小 Agent

---

问题背景

这是第五阶段的第三篇，也是"定义问题 → 拆需求 → 画架构"三步曲的最后一步。

先说一个反常识的观点：架构设计的重点，从来不是"图本身"，而是"每个节点的取舍理由"。 一张架构图里，如果某个节点你只能说"大家都这么画"或者"这很先进"，那它大概率是不该存在的。

Agent 架构尤其如此。因为 Agent 的每一个节点，都在消耗 Token、增加延迟、扩大失败面。多一个节点，不只是多一段代码，而是多一个会出错的地方。

很多人画 Agent 架构图，习惯"从网上的参考图里抄节点"——别人有 Planner，我也画一个；别人有 Memory，我也加一个。这种"抄出来的架构"有两个致命问题：

1. 你不知道它为什么存在，所以出了问题你不知道该往哪里查。
2. 你不知道它该多轻多重——画了 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
不知道查到哪算完	草率下结论 / 无限烧 Token	Planner
没人验证结论	幻觉成灾，错得理直气壮	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-Agent，Token 翻倍、编排延迟上升、失败面从 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(tool="grep", args=state.query_keyword)
    if state.need_more_evidence():
        return Action(tool="read_file", args=state.pending[0])
    return Action(tool="done")

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(reject=True, reason=f"无证据支撑: {claim}")
    return Verdict(accept=True)

注意 reviewer 的最后三行——它是硬约束，不是"建议"。证据链闭不上，就回炉。这就是 Reviewer 节点的全部意义。

再给一个"节点职责自检表"，用来判断你的架构里每个节点该不该存在：

# 节点自检表：回答不上来就删掉这个节点
node_checklist:
  - 没有它会怎样？        # 必须答出一个具体后果
  - 它回答的问题是什么？    # 一句话说清职责
  - 它是最轻的实现吗？     # 一个函数能解决就别上独立服务
  - 它和邻居的边界清楚吗？  # 职责不能重叠（Planner 不该顺便做审查）

---

设计权衡

候选方案	优点	缺点	为什么不选
裸 Agent（无架构）	最快能跑	任务串味、无终点、幻觉无把关	三个致命问题无法接受
抄网上的完整架构	看起来全	无法判断问题出在哪个节点	别人的答案不是你的推理
四节点架构	分工清晰、有终点、有把关	多几个节点多些成本	每个节点都能回答"缺了会怎样"
一步到位拆 Multi-Agent	职责最清晰	Token 翻倍、失败面×4、当前规模用不上	提前优化，收益撑不起成本

最后一行的"不选理由"值得单独说：过早拆 Multi-Agent，是 Agent 项目最常见的过度工程之一。 你会在第 48 篇看到，即便是到了 V2 阶段，我也只抽了一个 Reviewer 节点，而没有拆成真正的多 Agent。

---

常见误区（FAQ）

Q1：架构图里的节点越多越好吗？
恰恰相反。每个节点都是成本（Token、延迟、失败面）。判断标准只有一条：没有它会怎样？ 答不上来的节点，就是过度设计。

Q2：Task Router 会不会很重？
不会，它应该是最轻的节点。多数情况下一个分类 Prompt、甚至几条规则就能完成。它存在的意义是"分流"，不是"理解"。

Q3：Planner 和 LangGraph 里的规划节点一样吗？
思想一样，都是"决定下一步"。区别在于：LangGraph 的规划由你预置的边和条件路由表达，Repo Doctor 的 Planner 是动态生成下一步。后者的自主性更强，调试也更难（这正是第 41-42 篇要解决的问题）。

Q4：Reviewer 会不会让 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 篇。