企业官网建设流程全解析

1. 从“黑盒神话”到工程现实：Agent 框架到底卡在哪

过去一年多，我几乎把市面上叫得上名字的 Agent 框架都跑了一遍。从最早的 ReAct 循环手搓，到后来各种“开箱即用”的编排平台，再到最近半年密集出现的一批新范式项目，踩过的坑比写过的提示词还多。标题里说的“黑盒神话”，其实特别精准——很多框架在演示视频里无所不能，一旦落到真实业务里，就开始各种玄学失败：工具调用时好时坏、多轮对话记忆错乱、任务跑到一半直接agent execution terminated due to error，日志里还看不出到底哪一步崩的。

这篇文章想聊的，不是又一个“保姆级 Agent 入门教程”，而是站在一个真正把 Agent 往生产环境里塞过的工程视角，复盘主流框架的结构性问题，以及为什么“物理外化”这个听起来有点拗口的范式，正在成为越来越多团队的实际选择。如果你正在选型 Agent 框架、正在被 LLM 的不确定性折磨、或者单纯想搞清楚agent、llm、harness这几个词到底在工程上意味着什么，那这篇内容应该能帮你省下不少试错时间。

先说结论：Agent 框架的核心矛盾，从来不是“模型够不够聪明”，而是控制流到底掌握在谁手里。主流框架大多把控制流交给 LLM 自由发挥，美其名曰“自主决策”，实际就是把工程确定性押注在概率输出上。而“物理外化”范式做的事情，是把控制流从模型内部拽出来，变成外部代码里看得见、摸得着、可测试、可回滚的显式结构。这个转变，本质上和当年前端从 jQuery 一把梭到组件化、后端从大泥球到分层架构是同一种工程直觉。

1.1 主流 Agent 框架的三种典型形态

我把目前常见的 Agent 框架粗略分成三类，这个分类不是学术定义，纯粹是工程体感。

第一类是提示词驱动型，代表就是各种 ReAct、Plan-and-Execute 的实现。核心逻辑是给 LLM 一段系统提示，告诉它“你可以使用这些工具，请一步步思考”，然后模型输出什么，框架就解析什么。这类框架上手极快，几十行代码就能跑起来一个能查天气、能算数的 demo。但问题也在这里：整个执行路径完全由模型每次的输出决定，同样的输入跑十次，可能有三种不同的工具调用顺序，其中两次还失败了。你没法写单元测试，因为根本没有稳定的函数边界。

第二类是图编排型，把任务拆成节点和边，用状态机的方式组织。这类框架比第一类可控很多，至少执行路径是预先定义好的。但它的代价是灵活性下降，遇到需要动态决策的场景，你得提前把所有分支都画出来，画不全就漏。而且很多图编排框架的状态管理做得很重，一个简单任务要维护一大堆中间变量，调试的时候光看状态快照就头大。

第三类是多智能体协作型，让多个角色互相对话、分工。听起来很美好，实际跑起来经常变成“三个和尚没水喝”——角色之间互相甩锅，或者陷入无限循环的讨论。我见过最离谱的一次，两个 Agent 为了“谁来调用搜索工具”来回扯了十几轮，最后 token 烧完了任务还没开始。

1.2 为什么“自主决策”在生产环境里经常失灵

这里要讲一个很多人不愿意承认的事实：LLM 的自主决策能力，在开放域任务上被严重高估了。演示场景里任务边界清晰、工具数量少、失败成本低，模型随便发挥都能蒙对。但生产环境里，工具可能有几十个，每个工具有严格的参数约束，调用失败要重试，重试要幂等，还要考虑超时、限流、权限。这些工程约束，靠提示词是约束不住的。

我做过一个统计，在一个包含 12 个工具、平均任务步数 8 步的场景里，纯提示词驱动的 Agent 首次执行成功率大概在 40% 左右，加上重试能到 70%，但尾延迟非常难看。而把同样的任务用显式控制流重写之后，首次成功率直接拉到 90% 以上，因为每一步的输入输出都是代码保证的，模型只负责它真正擅长的部分——理解和生成自然语言。

这里的关键认知转变是：LLM 应该被当作一个能力组件，而不是决策主体。它擅长的是语义理解、内容生成、模糊匹配，不擅长的是状态管理、错误处理、流程控制。把后者交给代码，前者交给模型，这才是工程上合理的分工。

2. “物理外化”范式到底是什么：把控制流从模型里拽出来

“物理外化”这个词是我在跟几个做 Agent 基础设施的朋友聊天时逐渐形成的共识，它对应的英文大概是externalized control flow或者explicit orchestration。核心思想一句话：Agent 的执行逻辑，应该以代码的形式存在于模型之外，而不是以提示词的形式存在于模型之内。

2.1 一个生活化类比：从“口头指挥”到“流程图”

想象你要教一个新人做菜。第一种方式是你站在旁边口头指挥：“先切菜，对，切细一点，然后热锅，油温差不多了放葱姜……”这种方式下，新人每一步都要等你指令，你不在他就卡住，而且你稍微说快一点他就手忙脚乱。这就是提示词驱动型 Agent 的现状。

第二种方式是你给他一份标准作业流程，上面写清楚每一步做什么、什么条件进入下一步、异常情况怎么处理。他照着做，遇到流程里没写的情况再来问你。这就是“物理外化”——流程是显式的、可复用的、可审计的，人的介入只发生在真正需要判断的节点。

2.2 物理外化的四个工程特征

我总结下来，一个真正物理外化的 Agent 系统，通常具备这四个特征。

第一，控制流用代码表达，不用提示词表达。什么时候调用哪个工具、调用失败怎么办、什么条件下循环、什么条件下终止，这些全部写在代码里。模型只负责在单个节点内做它该做的事，比如从用户输入里抽取参数、判断一段文本的情感倾向、生成一段总结。

第二，状态管理显式化。整个任务的中间状态存在一个明确的数据结构里，每一步的输入输出都记录在案。这样出问题的时候，你可以直接看状态快照，知道是哪一步的哪个字段不对，而不是对着一堆对话历史猜。

第三，工具调用有严格的契约。每个工具都有明确的输入 schema 和输出 schema，调用前校验参数，调用后校验结果。模型生成的参数如果不合法，在进入工具之前就被拦截，而不是让工具抛一个莫名其妙的异常。

第四，可测试、可回放。因为控制流是代码，你可以给每个节点写单元测试，可以用录制的真实数据回放整个流程。这在纯提示词驱动的框架里几乎做不到。

2.3 和harness概念的关系

最近harness和agent的区别被讨论得很多。我的理解是，harness更偏向“测试与评估基础设施”，而物理外化是一种“架构范式”。两者有交集：一个物理外化的 Agent 系统，天然更容易被 harness 覆盖，因为它的行为是确定的、可断言的。但物理外化本身不限于测试，它是一整套关于如何组织 Agent 逻辑的工程方法论。

3. 落地物理外化：从框架选型到代码结构的完整实操

聊完理念，接下来是硬核部分。这一章我会用一个具体的任务场景，把物理外化的落地过程拆开讲。场景选一个中等复杂度的：从一段非结构化的用户反馈里，提取问题类型、严重程度、涉及产品模块，然后根据规则决定是自动回复还是转人工，自动回复的话生成回复内容。这个场景足够典型，涉及信息抽取、规则判断、内容生成三类操作。

3.1 框架选型：为什么我最终放弃了重型编排框架

先说选型结论。我试过用图编排框架来实现这个场景，也试过纯代码手写，最后的选择是轻量状态机 + 显式函数调用，没有用任何重型 Agent 框架。原因有三个。

一是调试成本。图编排框架的抽象层太厚，一个简单的条件分支要配置半天，出问题的时候报错信息藏在框架内部，得翻源码才能定位。手写代码虽然看起来“原始”，但每一步都在我自己的调用栈里，断点想打哪打哪。

二是依赖风险。很多 Agent 框架迭代极快，今天能跑的代码明天升级就挂，API 说改就改。生产系统经不起这种折腾。手写代码的依赖只有 LLM SDK 和几个基础库，稳定得多。

三是性能。重型框架为了通用性，往往有大量中间层和序列化开销。我这个场景对延迟敏感，手写代码可以把不必要的开销全砍掉。

当然，这不是说框架一无是处。如果你的场景非常标准，框架能帮你省不少事。但一旦场景有特殊性，框架的抽象就会变成负担。我的建议是：先用最朴素的代码把流程跑通，等真的遇到重复劳动了，再考虑抽象。

3.2 状态结构设计：整个系统的骨架

物理外化的第一步，是定义清楚状态结构。这个结构是整个系统的骨架，所有节点读写它，所有日志围绕它。我的设计大概是这样：

from dataclasses import dataclass, field from typing import Optional, Literal from enum import Enum class Severity(Enum): LOW = "low" MEDIUM = "medium" HIGH = "high" class Route(Enum): AUTO_REPLY = "auto_reply" HUMAN = "human" @dataclass class FeedbackState: raw_input: str issue_type: Optional[str] = None severity: Optional[Severity] = None product_module: Optional[str] = None route: Optional[Route] = None reply_content: Optional[str] = None error: Optional[str] = None step_history: list = field(default_factory=list)

这个结构有几个设计要点。step_history记录每一步的执行情况，方便回放和排查。所有字段都有明确的类型，Optional表示可能为空。error字段单独拎出来，任何一步出错都写到这里，而不是抛异常中断整个流程——因为很多错误是可以降级处理的。

实操心得：状态结构不要设计得太“聪明”。我见过有人把状态设计成嵌套很深的树，结果每次读写都要写一堆路径访问代码，调试的时候打印出来一大坨。扁平化、字段少、类型明确，是更好的选择。

3.3 节点实现：每个函数只做一件事

状态定义好之后，每个处理步骤就是一个函数，输入是状态，输出是修改后的状态。这种写法看起来笨，但好处是每个函数都可以单独测试。

信息抽取节点：

def extract_info(state: FeedbackState, llm_client) -> FeedbackState: prompt = f"""从以下用户反馈中提取信息，以 JSON 格式返回： 反馈内容：{state.raw_input} 需要提取： - issue_type: 问题类型，从 [功能异常, 性能问题, 界面问题, 咨询建议] 中选择 - severity: 严重程度，从 [low, medium, high] 中选择 - product_module: 涉及的产品模块名称 只返回 JSON，不要其他内容。""" try: response = llm_client.complete(prompt, temperature=0) parsed = json.loads(response) state.issue_type = parsed.get("issue_type") state.severity = Severity(parsed.get("severity", "low")) state.product_module = parsed.get("product_module") state.step_history.append({"step": "extract_info", "status": "ok"}) except Exception as e: state.error = f"extract_info failed: {e}" state.step_history.append({"step": "extract_info", "status": "error", "detail": str(e)}) return state

这里有几个关键点。temperature=0是为了让抽取结果尽量稳定，虽然不能保证完全确定，但比默认值好很多。JSON 解析放在 try 里，因为模型偶尔会返回带 markdown 代码块的 JSON，或者干脆返回一段解释文字。出错不抛异常，而是写进state.error，让后续节点决定怎么处理。

路由判断节点：

def decide_route(state: FeedbackState) -> FeedbackState: if state.error: state.route = Route.HUMAN state.step_history.append({"step": "decide_route", "status": "fallback_to_human"}) return state if state.severity == Severity.HIGH: state.route = Route.HUMAN elif state.issue_type == "咨询建议": state.route = Route.AUTO_REPLY else: state.route = Route.AUTO_REPLY state.step_history.append({"step": "decide_route", "status": "ok", "route": state.route.value}) return state

注意这里的逻辑：任何前置步骤出错，直接转人工。这是物理外化的一个重要原则——错误处理是显式的、有明确策略的，而不是指望模型自己“意识到出错了然后重试”。

3.4 主流程编排：代码就是文档

最后把所有节点串起来：

def process_feedback(raw_input: str, llm_client) -> FeedbackState: state = FeedbackState(raw_input=raw_input) state = extract_info(state, llm_client) state = decide_route(state) if state.route == Route.AUTO_REPLY: state = generate_reply(state, llm_client) return state

这个主流程短到可以一眼看完，但它完整表达了整个系统的行为。任何人接手这个代码，五分钟就能理解系统在干什么。这就是物理外化的价值——代码本身就是最好的文档，不需要额外的流程图来补充说明。

3.5 参数选择与性能考量

几个实操中的参数选择，值得单独说一下。

温度设置：抽取类任务用temperature=0，生成类任务用0.3到0.7。抽取要的是稳定，生成要的是多样性。这个区分很重要，我见过有人所有调用都用默认温度，结果抽取结果飘忽不定。

超时与重试：LLM 调用必须设超时，我一般设 15 到 30 秒。重试策略上，抽取类任务重试 2 次，生成类任务重试 1 次。重试时把温度调低，增加稳定性。

并发控制：如果任务量大，要注意 LLM API 的并发限制。我一般用一个简单的信号量控制并发数，避免触发限流。

缓存：对于重复的输入，可以在抽取节点加一层缓存。我实测下来，用户反馈里有大概 15% 是重复或高度相似的，缓存能省下这部分调用。

4. 常见问题与排查技巧实录

这一章是我踩坑最多的地方，整理成速查表，希望能帮你少走弯路。

4.1 典型问题速查表

4.2 三个我踩过的深坑

第一个坑：过度信任模型的 JSON 输出。早期我直接json.loads(response)，结果模型偶尔返回带解释文字的 JSON，直接抛异常。后来改成先用正则提取 JSON 部分，再解析，容错率高了很多。再后来干脆用支持结构化输出的 API，从源头保证格式。

第二个坑：把重试逻辑写在提示词里。我曾经在提示词里写“如果调用失败请重试”，结果模型确实“重试”了，但它只是在文本里说“我重试一下”，并没有真的重新调用工具。重试必须写在代码里，模型没有真正的执行能力。

第三个坑：忽略 token 消耗。物理外化之后，每个节点独立调用 LLM，token 消耗反而可能比一次性大提示词更高。我后来加了一个 token 统计，发现抽取节点因为要传完整反馈内容，消耗最大。优化方法是先做一次轻量预处理，把明显无关的内容截掉，再送进抽取节点。

4.3 独家避坑技巧

分享几个文档里不会写、但实际很有用的技巧。

技巧一：给每个节点加“降级路径”。不是所有节点都必须成功。抽取节点失败，可以用规则兜底；生成节点失败，可以用模板兜底。降级路径让系统在部分组件故障时仍能提供基本服务。

技巧二：用真实数据做回放测试。收集一批真实用户反馈，录下每个节点的输入输出，然后写一个回放脚本，每次改代码都跑一遍，对比结果变化。这比写单元测试更贴近真实场景。

技巧三：日志里记录模型原始输出。不要只记录解析后的结果，原始输出也要存。排查问题时，原始输出往往能告诉你模型到底“想”干什么。

技巧四：控制单次上下文长度。物理外化之后，每个节点的上下文可以独立控制。抽取节点只需要反馈内容，不需要历史对话；生成节点需要反馈内容和抽取结果，不需要原始对话历史。按需传递，能显著降低 token 消耗和延迟。

5. 物理外化的边界与未来演进

聊了这么多物理外化的好处，也得说说它的边界。不是所有场景都适合物理外化。如果你的任务非常简单，比如就是单轮问答，那直接调 LLM 就行，没必要搞一套状态机。如果任务高度开放，比如创意写作、头脑风暴，那显式控制流反而会限制模型的发挥。

物理外化最适合的场景，是任务流程相对固定、但每个步骤需要语义理解能力的场景。客服工单处理、文档信息抽取、代码审查辅助、数据分析报告生成，这些都属于这一类。它们的共同点是：流程可以画出来，但每一步的判断需要“理解”而不是“计算”。

5.1 和提示词工程、上下文工程的关系

有人可能会问，物理外化是不是就不需要提示词工程了？恰恰相反，物理外化让提示词工程变得更聚焦。以前你要在一个大提示词里同时处理流程控制、工具选择、参数生成、错误处理，提示词又长又难维护。物理外化之后，每个节点的提示词只关注一件事，可以打磨得更精细。上下文工程也是同理，每个节点需要什么上下文，是显式决定的，不用靠模型自己从一大堆信息里挑。

5.2 一个值得关注的演进方向：混合范式

我最近在尝试一种混合范式：外层物理外化，内层保留一定的模型自主性。具体来说，主流程用显式代码控制，但在某些复杂节点内部，允许模型做有限度的自主决策。比如在“问题分类”节点，如果模型对分类结果置信度低，可以触发一个内部的澄清子流程，让模型自己决定问用户什么问题。这种“外显内隐”的结构，兼顾了工程确定性和模型灵活性，是我目前比较看好的方向。

5.3 给正在选型的团队的建议

如果你正在为团队选型 Agent 框架，我的建议是：先想清楚你的控制流复杂度。如果流程简单、步骤少，直接用轻量方案，别上重型框架。如果流程复杂、需要多人协作维护，那物理外化的显式结构会帮你大忙。选型的时候，重点看框架能不能让你方便地表达控制流、能不能方便地调试、能不能方便地替换组件。那些把一切都封装起来、只暴露一个run()方法的框架，短期省事，长期是债。

我在实际项目里最大的体会是：Agent 工程的难点，从来不是让模型变聪明，而是让系统变可靠。模型的能力在快速进步，但工程可靠性只能靠架构设计来保证。物理外化不是银弹，但它提供了一条让 Agent 从 demo 走向生产的可行路径。踩过足够多的坑之后，你会越来越倾向于把不确定性关进笼子里，让代码做代码该做的事，让模型做模型擅长的事。这个边界划清楚了，很多问题自然就消失了。