企业官网建设流程全解析

六层架构解剖图：一个生产级 Agent 的完整剖面

网上讲 Agent 的教程，十个有九个只教你"调个 API 就完事"。但一个能上线的 Agent，底层是六层堆起来的山。这一节我把整座山解剖给你看，每一层是什么、干什么、对应课程哪几章，一次讲透。

本文导航

• 为什么是六层
• 总纲：六层架构全景图
• 第一层：模型接入层
• 第二层：工具系统层
• 第三层：上下文引擎层
• 第四层：安全权限层
• 第五层：编排层
• 第六层：可观测性层
• 这张图就是课程地图
• 小结
• 下节预告

上一节我们用操作系统的思维重新认识了 Agent：工具是系统调用、权限是访问控制、上下文是内存、编排是调度。这一节我把这台"微缩操作系统"从纵向剖开——它到底由哪几层堆起来？

答案是六层。这六层是我做了不少 Agent 项目之后，回头抽象出来的稳定骨架。不是学术概念，是实战打出来的。很多教程爱讲"Agent = LLM + 工具 + 循环"这种三件套，够用，但不够撑起一个生产级系统。生产级意味着：能跑、敢跑、跑不崩、跑了还有据可查。这四点，正好对应六层里后四层。

为什么是六层

先给你这根通读全文的脊椎骨——六层架构全景图：

从下往上，就是一次"模型坐到用户面前"的数据之旅。下面我逐层拆，并顺手标注每一层对应课程的哪几章——这张图同时也是你的课程地图。

第一层：模型接入层

最底下一层，负责"跟模型说话"。它要搞定三件事：

1. 协议统一：不管后面接的是 DeepSeek、Qwen 还是本地 vLLM，全部走 OpenAI 兼容协议，换模型只换base_url和 Key，零改业务代码
2. 传输细节：流式（SSE）、超时、连接池、自动重试（遇到 5xx 或限流要退避重试）
3. 统一返回：把各家的返回差异抹平成同一个结构，上层不用关心底层是哪个模型

# 第一层示意：一个薄薄的模型客户端封装classLLMClient:def__init__(self,base_url,api_key,model):self.client=openai.OpenAI(base_url=base_url,# 换模型只改这里api_key=api_key,timeout=60.0,)self.model=modeldefchat(self,messages,tools=None,stream=True):# ...组装请求、处理流式分片、处理重试...returnresponse# 统一结构返回给上层

⚠️ 这一层最容易踩的坑是重试写不好：不区分"限流(429)“和"服务错误(5xx)”，或者不接退避（backoff），一抖就直接崩。第 3 章协议内幕 + 第 19 节重试设计都在啃这块。

第二层：工具系统层

第二层给模型"手"（对应第 9 章工具集）。核心是注册表 + 执行器：

• 注册表：把一个个普通函数描述成toolsJSON（函数名、参数 schema、说明），告诉模型"你有哪些工具可以用"
• 执行器：当模型返回tool_calls时，把参数解析出来、安全调用真实函数、把结果转成tool角色的消息塞回对话

# 第二层示意：注册表 + 执行器classToolRegistry:def__init__(self):self._tools={}# name -> callabledefregister(self,func,schema):self._tools[schema["name"]]=(func,schema)defto_openai_spec(self):return[sfor_,sinself._tools.values()]defexecute(self,name,arguments):func,_=self._tools[name]returnfunc(**arguments)# 真实执行，结果回填

第二层的灵魂是工具要有明确的成功/失败返回——不要抛裸异常，要么返回结构化错误给模型看，要么返回"请重试"。这样模型才知道自己失败了、还能怎么调整。

第三层：上下文引擎层

第三层给模型"记忆"（对应第 11 章上下文工程）。它的职责是：让模型在有限窗口里，看到它最该看的东西。

• 管理 messages 列表的增删、截断
• 装不下时做摘要压缩，或从向量库做 RAG 检索
• 把工具结果、系统提示、历史对话、外部检索结果，按正确顺序拼装成一次请求

# 第三层示意：负责"拼装这一轮要发出的 messages"defbuild_request_messages(task,history,tool_results,memory):msgs=[{"role":"system","content":SYSTEM_PROMPT},{"role":"system","content":f"[相关工作区]{memory.retrieve(task)}"},# 历史（可能已被截断/摘要）*history.visible(),# 最近的工具执行结果*tool_results,]returnmsgs

这一层做不好，常见症状：上下文越来越长越来越贵、模型"忘了"早期约束、或者被垃圾信息带偏。它是性价比和效果的双重杠杆，值得花整章（第 11 章）打磨。

第四层：安全权限层

第四层是"闸门"（对应第 10 章安全权限）。它管两件事：哪些工具能碰、哪些命令能跑。

• 权限白名单：默认拒绝、显式放行
• 危险操作拦截：拒绝rm -rf、sudo、脱离工作区的路径写入
• 参数校验：用 pydantic 校验所有工具入参，防止模型吐出畸形参数

# 第四层示意：兜底的权限闸门defguard(tool_name,args):iftool_namenotinALLOWED_TOOLS:raisePermissionError("工具未授权")iftool_name=="write_file":abspath=os.path.abspath(args["path"])ifnotabspath.startswith(WORKSPACE):raisePermissionError("禁止写工作区之外")returnpydantic_validators[tool_name].validate(args)# 参数强校验

生产级 Agent 和玩具 Agent 的分水岭，就在这一层。上不了线、不敢放手让它跑的项目，八成是这层没做好。后面第 10 章我会带你把权限模型、危险命令拦截、降级策略全部实现一遍。

第五层：编排层

第五层是"大脑的中枢"（对应第 8 章 Agent Loop、第 12 章子 Agent）。它决定什么时候思考、什么时候行动、什么时候停。

• 维护 Agent Loop 主循环：思考 → 调工具 → 看结果 → 再思考
• 处理终止条件：max_iters、模型喊停、超时熔断
• 在多 Agent 场景下做调度编排（对应操作系统的进程调度）

# 第五层示意：Agent Loop 主循环（核心中的核心）defrun(self,task):messages=self.ctx.build(task)foriinrange(self.max_iters):# 缰绳resp=self.llm.chat(messages,self.tools.spec())ifresp.finish:# 模型给出最终答案returnresp.content result=self.tools.execute(*resp.tool_call)self.permission.guard(*resp.tool_call)# 过闸messages=self.ctx.append(messages,resp,result)returnself.fallback()# 超时兜底

这条循环，就是整个课程的"主心骨"。你在第 8 章（DeepPilot v0.3）会把上面这段从零手写出来，并且补上流式、异常、重试、计量等所有生产细节。

第六层：可观测性层

最后一层（对应第 7 章调用留痕、以及贯穿全课的"五条铁律"）负责让系统被看见。别小看它，你前面为 Agent 花的每一分钱、踩的每一个坑，都得靠这层捞出来。

• 每次模型调用留痕：base_url/端口、Key 末 6 位、模型名、输入输出长度、起止时间、耗时
• 原始 prompt 落盘（方便日后追溯、复现、分析）
• 日志按月分割、控制台 + 文件双输出、保留 12 个月
• 退出时打印量化总结：输入输出 token 的最大/最小/平均、耗时统计

# 第六层示意：留痕核心（课程的"五条铁律"之一）@dataclassclassCallRecord:ts_start:datetime ts_end:datetime base_url:strmodel:strinput_len:int# 提示词 + 文件字节output_len:intcost_ms:float# 每次调用都记录，App 结束时统一打印汇总

没有这一层，你只是一个"在烧钱但看不见账本"的盲人。有了它，你能回答：平均一次调用多快？哪个环节最贵？输入长度和速度到底是什么关系？——这些都是可以拿一句提示词分析的硬数据。

这张图就是课程地图

把六层往回对照，你会发现整门课 80 篇就是按这六层纵向铺开的（再加上开篇的认知和收尾的商业）：

看懂这张总纲，你心里就有了一张进度图：每写一篇，你知道自己在填哪一层、补的是哪块拼图。这就是"造系统"和"堆代码"最大的区别——前者心里有地图，后者走一步算一步。

小结

1. 生产级 Agent 是六层堆起来的，不是"LLM + 工具 + 循环"三件套那么简单。
2. 六层从下到上：模型接入 → 工具系统 → 上下文引擎 → 安全权限 → 编排 → 可观测性，一层承载一层。
3. 安全权限层是分水岭：能不能放心上线、敢不敢放手跑，就看这层做没做好。
4. 可观测性层是账本：无留痕 = 盲人烧钱，有留痕才能分析、复现、优化。
5. 这张六层图就是课程地图，每篇文章都能定位到具体某一层。

下节预告

讲了这么多层架构，你要是不亲手跑一次"模型说了一句人话"的瞬间，前面的理论都是纸上谈兵。下一节我们来点真格的——五分钟体验：你的第一个 DeepSeek 回合。我直接甩给你一个能一键运行的 uv 单文件，让你亲眼看到 deepseek-flash 回你第一句话。那种"它真开口了"的实感，比任何理论都顶用。

如果觉得本文对你有帮助，欢迎点赞、收藏、关注三连！
本系列持续更新中，80篇硬核实战，关注不迷路~