企业官网建设流程全解析

Agent 架构设计：先解决三个"没说出口的需求"，再谈技术选型

我接手企业内部研发 Agent 这个项目时，第一反应是兴奋。第二反应是，需求文档上只有一句话："做一个能帮研发提效的 Agent。"这种需求我见过太多次了——越宏大，越模糊，后期撕扯越凶。

做企业级研发 Agent，真正难的不是大模型调用，不是 LangChain 或 Dify 选型，而是把"提效"这个模糊的期望翻译成具体的场景、边界、评估标准和架构约束。我从需求梳理到整体架构落地，前后花了三个多月，中间推翻过两版设计，踩了不少坑。这篇就把从需求拆解到架构设计的完整链路拉一遍，重点讲清楚每个环节我为什么这么决策，以及哪些地方最容易翻车。

1. 先别急着画架构图：研发 Agent 的需求到底长什么样

大多数团队做 Agent 失败，不是技术不行，而是需求阶段偷了懒。研发 Agent 不是"加一个大模型聊天框"那么简单的功能，它的需求牵涉到研发流程的每个环节，每个环节对"智能"的容忍度完全不一样。如果不先把这些差异摸清楚，后面的架构设计就是空中楼阁。

1.1 需求方口中的"智能研发助手"往往不是一个东西

我去和业务方聊需求时，发现一个很有意思的情况。产品经理说，想要一个能自动写代码的助手；研发总监说，想要一个能自动化处理重复事务的助手；测试负责人说，想要一个能自动生成测试用例的助手；运维说，想要一个出了问题能自动排查的助手。

这些人嘴上说的是同一个词，心里想的完全是不同的产品。如果我把这些需求汇总成一个"无所不能的研发 Agent"，那基本就宣告项目要延期了。正确的做法是在需求阶段就把这些诉求拆开，识别出不同的使用场景和用户角色，然后分层匹配。架构设计必须能同时支撑"不同复杂度、不同风险等级、不同交互深度"的任务模式。有些场景适合全自动执行，有些场景必须人工审批后再执行，架构上就要预留这个控制开关。

1.2 从业务语言翻译成技术能力的三个维度

把业务需求翻译成技术能力，我有三个惯用的维度来收敛：任务类型、自动化程度、风险容忍度。任务类型决定了 Agent 的核心能力是什么。是自然语言理解主导的（比如问答、知识检索），还是规划决策主导的（比如多步任务拆解、代码生成），还是操作执行主导的（比如调用工具、修改文件、触发流水线）。自动化程度决定了交互设计。是单轮对话、多轮对话，还是人在环上的人工审批。风险容忍度决定了权限边界和审核机制。改动一行代码和触发生成环境发布，风险等级完全不同，必须给 Agent 设置不同层级的操作闸门。

我拿这三张表去和每一个需求方对齐，反复打磨之后，得到了一组相对明确的需求画像，这才具备进入架构设计的基本前提。

1.3 需求优先级排序：哪些能力必须自研，哪些可以接现成

第二件重要的事是需求排序。我当时列了一张"能力需求清单"，把所有业务方提到的能力都写上去，然后一个个过：哪些是刚需、哪些是伪需求、哪些现阶段必须自研、哪些可以调用外部能力先顶上。

一个典型的例子是代码补全。当时有需求方提出要支持 IDE 插件级别的实时代码补全。这个能力如果要自研，需要投入大量精力在 IDE 插件适配、上下文裁剪和延迟优化上，短期内根本做不完。但需求方真正想要的其实是"写代码更省力"。所以我的方案是先用现有的 AI 编程助手能力顶上，把自研精力集中在更核心的"研发流程自动化"上。这个决策虽然当时有人不理解，但后来验证是对的——先把真正有壁垒的流程规划能力做扎实，边界能力后面再慢慢补。

2. 研发 Agent 与普通自动化工具的本质区别：为什么必须重新设计架构

需求梳理清楚之后，团队里有人提了个很实在的问题：这些需求用脚本不是也能做吗？写个自动化工具，把代码审查、测试执行、发布触发的流程串起来，不也能解决大部分问题吗？为什么要搞得像个"智能体"？

这个问题的答案，直接决定了架构设计的走向。

2.1 从固定流程到动态规划：Agent 的核心不是"能对话"，而是"会变通"

传统自动化工具的本质是"流程固定、步骤预设"。你告诉它第一步做什么、第二步做什么，它按部就班执行。好处是稳定、可控、容易理解；坏处是遇到需求之外的状况就抓瞎，一旦流程发生变化，就要改代码重新发布。

研发场景恰恰充满了不确定性。同一个需求，代码评审发现的问题可能完全不同；同一个报错信息，背后的原因每次都不一样。这些东西没法穷举成固定规则，所以传统自动化工具只能覆盖那些高度标准化的场景，剩下的大量灵活工作还是得靠人。

Agent 的核心价值恰恰在于它是目标导向而不是流程导向。你给它一个目标，比如"帮我查一下线上这个报错的原因"，它能自己拆解步骤：先查日志、再定位异常堆栈、然后搜索关联代码、最后给出可能的根因。每走一步，它根据上一步的结果决定下一步干什么。这才是 Agent 和普通自动化工具有本质区别的地方——动态规划能力。

2.2 先统一概念：Agent、Skill、Tool、Harness 到底怎么分工

概念不统一，架构就开始混乱。我在设计前先把团队的概念模型对齐了，这样才能聊到同一个频道上。

• Agent（智能体）：核心决策单元，负责任务理解、步骤规划、调用决策。
• Skill（技能）：面向特定场景的能力打包，一个 Skill 内部可以包含多个步骤、多个 LLM 调用和工具调用。
• Tool（工具）：原子操作的最小单元，比如"执行一个 Shell 命令""调用一个 API""读取一个文件"。
• Harness（执行框架/容器）：Agent 运行时的执行环境，负责管理上下文、调用 LLM、执行工具、处理异常、控制循环。

把这几个概念分清楚之后，团队里的讨论效率高了很多。后来我看到网上有人问"harness 和 agent 的区别""skill 和 agent 的区别"，其实本质都是概念混淆——Agent 是大脑，Harness 是身体，Skill 是动作模式，Tool 是肌肉。

2.3 一个反直觉的架构原则：Agent 越"薄"越好用

很多团队做 Agent 喜欢把逻辑全塞进"智能体"里，觉得这样才显得聪明。我的经验恰恰相反：Agent 本体应该尽量保持轻薄。所有可以被规则化、被固定的流程逻辑，尽量下沉到 Skill 和 Tool 层用确定性的代码去实现；Agent 只处理那些真正需要实时推理和决策的部分。

原因很简单：大模型的推理存在不确定性，同一个问题每次生成的步骤可能都不一样，这在研发场景里是个很大的隐患。如果让 Agent 用自然语言去描述每一步操作，然后自己执行自然语言描述的步骤，任何一个环节的理解偏差都可能让整个流程跑偏。相比之下，把确定的逻辑写成代码，让 Agent 在这个框架里做决策，既保留了灵活性，又大幅提升了稳定性。当时团队有人不理解，说这样不够"Agent"。后来跑通了第一个端到端场景，大家才意识到这个设计是对的。

3. 从需求到架构的映射：我的整体分层方案

前面说了那么多"为什么"，现在聊"怎么做"。我最终落地的架构是标准的分层设计，每一层只做一件事，层与层之间通过明确的接口通信。这样设计的好处是，出问题时能快速定位，替换或升级某一层时不会影响其他层。

3.1 接入层：先想清楚用户从哪个口子进来

接入层是用户与 Agent 交互的入口。我在设计时没有把它做成单一入口，而是根据前面需求梳理时的场景差异做了三个入口。

第一是 IM 对话入口。这个是使用门槛最低的入口，用户在企业 IM 里直接 @ Agent 提问，适合碎片化问答、知识检索、轻量级任务。第二是研发平台嵌入式入口。在代码仓库、流水线、项目管理页面嵌入 Agent 入口，用户在具体研发场景里能上下文感知地触达。第三是 API 入口。给自动化脚本和其他系统调用用的，适合批量性、程序化的任务。

这里特别要提醒一点：入口多不是问题，但不同入口背后的 Agent 实例应该是同一个后端。如果每个入口都单独开发一套交互逻辑和状态管理，后面维护成本高得吓人。所以我在接入层只做协议转换和会话管理，业务逻辑全部下沉到后面的编排层。

3.2 决策编排层：Agent 的"大脑"是怎么工作的

这是整个架构的核心，也是我花心思最多的部分。决策编排层主要包括四个模块：意图理解模块、规划模块、上下文管理模块、工具调用模块。

意图理解模块负责把用户输入转化为结构化指令。比如用户说"帮我查一下订单服务最近一小时内的错误日志"，它需要提取出查询对象（订单服务）、时间范围（一小时）、日志类型（错误日志）这些关键要素。规划模块负责把任务拆解成多步执行计划，产出的每一步都要绑定具体的 Skill 或 Tool。上下文管理模块负责维护整个会话过程中的状态，包括历史消息、中间结果、用户偏好等。工具调用模块负责实际执行规划中的每一步，并处理不同工具间的数据传递和错误恢复。

这四个模块里，上下文管理是最容易出问题的，后面我会专门讲坑。规划模块的设计上，我坚持"简单优先"——能用硬编码流程解决的坚决不靠模型规划。在架构上预留了"流程模板"和"自由规划"两种模式，前者先用到稳定场景上，后者是演进方向。

3.3 工具执行层：集成边界划在哪，直接决定后续改造成本

工具执行层承载了 Agent 调用外部系统能力的所有逻辑。研发场景下，Agent 主要需要这些工具能力：代码操作类（读取、创建、修改代码文件）、命令行执行类（执行 Shell 命令、运行测试）、DevOps 集成类（触发流水线、查询部署状态、获取日志）、知识库检索类（搜索内部文档、历史工单、代码注释）。以及沟通通知类（在 IM 里发送消息、创建任务提醒）。

每个工具都被包装成统一的接口格式，包含名称、描述、输入输出参数、执行方式，这样 Agent 才能通过统一的规范去选择并调用工具。接口设计上不能把每个系统的差异直接暴露给 Agent，而是要做一层"工具适配器"。把 GitLab 的 API、Jenkins 的 API、内部文档库的 API 都适配成同一套接口，上层感知不到具体系统的差异。

这里还有一个关键决策，与需求阶段的"权限安全"直接相关。工具执行层里我加了一个审批网关。所有高风险操作（比如触发生产环境发布、删除文件、修改权限）都必须经过审批网关，审批通过后才真正执行。这一步不是技术问题，是信任问题——如果 Agent 连安全边界都无法保证，业务方根本不敢把核心流程交给它。

3.4 数据反馈与评估层：没有度量体系的 Agent 就是黑盒

很多 Agent 项目跑着跑着就废了，根本原因是说不清楚 Agent 到底有没有用。所以我从架构一开始就设计了数据反馈与评估层，让 Agent 的每一次执行都可度量、可评估、可复盘。

评估分两层。第一层是执行层评估：每次工具调用的耗时、成功率、错误类型、需要人工介入的次数。第二层是结果层评估：任务完成率、用户留存率、用户手动修正频率、真实关闭率（任务真正完成而不是用户放弃）。有了这些数据，团队可以构建 Agent 的"效能基线"，持续追踪优化。

除了评估维度，反馈层还要负责数据回流和标注入库。Agent 执行过程中的成功案例和失败案例都会被记录下来，经过人工筛选后沉淀为新的评测集和训练样本。这个数据闭环是 Agent 持续变聪明的关键——不把反馈数据用起来，Agent 就永远停留在初始版本。

4. 架构落地中的关键转角与排坑记录

架构图只是第一步，真正的挑战是落地过程中那些想不到的"程序崩溃"。我选出五个绕不过去的坑，每个都是拿实际代价换来的，强烈建议你们设计时早点考虑。

4.1 上下文管理：低成本对话背后，暗藏高成本的 Token 开销

研发任务往往需要多轮交互，Agent 需要记住用户说过什么、已经做过什么。如果架构上不做任何状态管理，Agent 就会在每一步都"忘事"，任务根本跑不完。但如果每一步都把完整历史全量发给大模型，成本又高得离谱。

我的应对方案是分层上下文管理。短期会话状态存在内存里，实时更新最近几轮的关键信息。中期任务状态存在独立的存储中，比如任务 ID、当前执行步骤、中间产物路径。长期偏好和配置信息存在配置中心里，覆盖用户的个性化偏好。每一次请求，上下文管理器只把当前任务相关的信息打包给大模型，而不是把所有历史无脑塞进去。

为了控制 Token 消耗，我还设计了自动摘要机制：当一个会话的上下文快达到上限时，自动总结前面的内容，用摘要替代原始对话。这套机制落地后，成本直接降了一半多。

4.2 工具调用的稳定性：一次失败的调用比没调用更可怕

工具调用是 Agent 和外部系统交互的桥梁，也是最容易出错的地方。我见过最典型的问题：Agent 在执行 Shell 命令时，正常输出和错误输出混在一起，导致它错误地判断命令执行成功了；某个工具 API 临时不可用，Agent 没有自动重试机制，结果整个任务流程就中断了。

工具调用的架构设计必须包含明确的超时控制、重试策略、降级方案和失败归因逻辑。一个工具调用失败后，Agent 要能区分是工具本身的问题还是环境的问题，前者重试，后者换方案。此外，建议为每个工具增加幂等设计，确保重复执行不会造成副作用；为关键工具增加 Mock 模式，方便在测试环境调试流程而不影响真实系统。

4.3 权限与安全边界：不是技术选项，而是业务的准入许可

研发 Agent 的权限边界，比普通软件系统更复杂。因为它不仅拥有信息访问权，还拥有操作执行权。在技术架构上，通常是按"角色-权限-资源"的模型来控制。比如某个 Agent 实例只允许在测试环境操作，只允许访问代码仓库的特定分支，只允许触发非生产环境的流水线。

但比技术实现更重要的问题是权限申请的流程。如果权限管得过严，Agent 什么也做不了，价值无法体现；如果权限给得太宽，业务方不敢用。所以我把权限模型设计成了"最小够用"原则。先让 Agent 跑通只读类和测试类任务，积累信任后逐步放开更高风险的操作权限。同时所有操作全程留痕，方便审计回溯。

4.4 评估体系：没有评测，就没有优化

研发 Agent 的迭代优化，必须建立在可量化的评估之上。没有评测机制的 Agent 项目，后期一定会陷入"感觉回答质量提升了，但又说不出哪里提升了"的混沌状态。

我落地了一个三层评测体系。第一层是离线评测，用固定的测试集跑批量任务，对比不同模型、不同参数的输出差异。这个层面主要解决 "模型选型和提示词调优" 的问题。第二层是线上灰度评测，小流量放给真实用户使用，采集执行数据和用户反馈。第三层是回归评测，每次更新之后，用历史积累的问题集验证没有被"改坏"的能力。

因为有了这套评估体系，后续每次模型升级、提示词调整、工具逻辑优化，我都能用数据说明"到底变好了没有"。

4.5 稳定性压测：Agent 不是跑通就行，要能扛得住并发

最后还有一个很容易被忽略的坑——并发和压测。研发 Agent 一旦接入团队，使用频率会很快上来。如果底层架构没有做好并发处理，会出现 Redis 连接池耗尽、LLM 调用限流、任务队列堆积等问题。

我当时是在压测中发现问题并解决的。架构上一定要带上异步任务队列+水平扩展的能力，避免在每轮对话中都做大量的同步等待；对 LLM 调用层做限流和排队；数据库和缓存扛不住热点时进行垂直拆表、水平分片。最好在开发环境提前跑一遍压测脚本，把请求峰值时的资源消耗算清楚，而不是等到生产环境爆了再补救。

5. 技术选型背后的真实理由：Model、框架与存储的取舍

好的架构不只是一个框架或一堆工具的组合，而是在每个选择上都有"为什么"的决策过程。我按模块逐个拆下选型逻辑和取舍。

5.1 模型选型：大模型不是越强越好，而是越"合适"越好

模型选型是研发 Agent 的第一个关键决策点。我当时评估了三个方向：通用大模型（如 DeepSeek、GPT 等）、编程垂直模型（如 DeepSeek-Coder 等）、微调定制模型。

对于研发 Agent，我最终采用了多个模型分工，而非单一大模型包打天下的思路。规划决策部分用通用大模型，负责理解需求、拆解步骤；代码生成部分用垂直模型，代码的理解和生成质量明显更优；轻量任务（比如标题生成、文本摘要）用更便宜的小模型，降低成本。复杂的多步推理任务再调更强的模型，形成"按需调度"的经济型模型策略。

5.2 框架选型：要不要用现成的 Agent 框架

工程界关于"要不要用 LangChain 之类的 Agent 框架"争论很久了。我的观点是：早期可以用于快速验证，但不要把它放在核心链路里。

原因是框架抽象层会掩盖太多的系统行为，一旦出了问题，你需要花大量时间排查到底是框架的哪一层出了问题。研发 Agent 的场景需要高可控性，每一步执行、每一次上下文组装、每一个错误处理都必须可观测、可干预。所以我反过来做了个决定：核心流程自研，把框架能力当作参考实现。这样微调空间更大，排查问题也更快。

5.3 存储与缓存设计：会话、状态、知识库需要不同存储方案

研发 Agent 的存储需求是多样化的，我用了一套组合方案来应对。

会话与任务状态放在 Redis 和 MySQL 中。Redis 处理高频读写和短期会话状态，MySQL 存持久化任务记录。上下文快照放在对象存储中，因为上下文数据量大、结构松散，且适合用低成本的存储方案。向量数据库用于知识库检索。内部文档、历史工单等非结构化数据需要 embedding 后存入向量库，支撑语义检索。日志全部走标准日志采集中间件，统一沉淀到日志平台里，方便追踪全链路。

特别要说明的是 Redis 的缓存设计。研发 Agent 会高频查询代码仓库信息，比如获取项目结构、读取 README、查询分支列表。这些请求如果每次都打到后端仓库系统，既慢又容易被限流。我就在 Redis 里为高频查询加了一层缓存，并设计了合适的过期和更新策略，效果立竿见影。

5.4 评测体系建设：从人工看效果，到自动化跑分

评测体系的工程化是很多团队最容易忽略的部分。一开始，团队是在小范围里人工看 Agent 的回答好不好，后来人越来越多了，人工看效果根本忙不过来。然后我搭建了一个自动化的评测平台：把历史积累的典型问题按规则整理成评测集，写入标准答案和评分标准。每次 Agent 更新后，自动跑一遍评测集，生成分数报告。

评测分数具体用来指导什么呢？第一个明确作用是在 Prompt 调整时看涨跌；第二个作用是在多个候选模型之间做选择对比；第三个作用是生成回归报告，版本迭代时倒推哪些能力变弱了。这套平台建设好后，Agent 的迭代速度明显加快，因为再也不用靠"感觉"做决策了。

6. 落地路径：从最能体现价值且风险可控的场景切入

架构设计做完，最大的问题变成了：从哪里开始"切"？是做一个大而全的 Agent，还是从一个很小的场景先跑起来？我的选择是后者。

6.1 场景选择优先级：不是看哪个“智能”，而是看哪个“可度量”

很多团队选择第一个场景时，会选那些看起来很炫酷的功能，比如"自动写代码"。但在企业场景里，第一个落地场景最重要的标准是可度量、风险可控、使用频率高。如果第一炮就打不响，业务方就很难再信任 Agent。

三个参考原则是：高频（团队每天都在做的）、低风险（失败后影响面小）、反馈快（做完后立刻能知道效果）。基于这个标准，我当时推荐的第一批场景是：知识库问答、代码仓库信息查询、自动化测试辅助、发布前检查单生成。

6.2 冷启动的架构平滑演进：不要为第一版做过度设计

第一版做的时候，不用把上面的架构全部实现。我建议先做垂直切片：从接入层到工具执行层，全链路打通一个最简单的场景。等验证完可行性后，再逐步扩大场景覆盖，把更多的组件模块补齐。

演进路线要清晰：阶段一是单场景闭环，先跑通一个高频场景，验证架构核心链路；阶段二是多场景并行，沉淀通用编排能力，验证框架复用性；阶段三是跨场景协同， Agents 开始跨任务调度，验证多 Agent 协作机制。最后才是全流程智能，覆盖研发全生命周期。

6.3 组织层面：Agent 项目能不能成，取决于"有没有人管"

最后说一个很多人忽略但非常重要的点：Agent 项目不能只靠技术团队。它需要业务方深度参与，需要有一个长期维护的运营团队。Agent 的流程规则、权限策略、反馈标注、效益分析，都需要有人持续跟进。如果把这个项目定位成"一次性交付"，那大概率是失败的。

我这边是拉了一个虚拟团队，包含产品、研发、测试和运维四个角色，产品负责梳理场景和评估规则，研发负责模型和框架开发，测试负责评测集建设，运维负责部署和监控。这个团队推动下来，项目才真正步入了正轨。

在整套架构设计里，技术组件是可替换的，但架构的骨架和决策逻辑需要稳定。无论未来大模型换成了哪个版本，框架换成了哪个更流行的方案，只要分层清晰、边界明确、数据闭环持续运转，这个 Agent 系统就能持续迭代下去。关于这一点，我在实际落地中感受最深的是：架构设计的本质不是"把先进技术堆上去"，而是在不确定性中建立起足够稳的框架，让所有角色都能在这个框架里有序协作。