企业官网建设流程全解析

做 Agent 的人大概都经历过同一个场面：演示环节行云流水，用户问一句、模型答一句，台下鼓掌；真上线跑一周才发现，问题压根不在模型这一层——用户找不到入口，业务系统叫不动它，它想主动找个人更是无从下手。Agent-Reach 要补的就是这段总被忽略的"最后一公里"：让 Agent 从"能回答"变成"够得着、叫得到、找得上人"。

我把它定义成一套独立的触达接入层。朝上，它给 Agent 一个统一的身份和会话入口；朝下，它把网页、站内信、邮件、工单、内部沟通工具、开放接口这些形态各异的通道抽象成同一种信封；中间，它负责路由、去重、重试、限流和全链路埋点。核心关键词其实就三个：可达性、统一信封、可观测。这三个词看着平淡，但真做起来，每一个背后都有一堆参数要算、一堆坑要踩。

这篇内容适合三类人：正在把 Agent 往业务里塞的后端和平台同学；做客服、运营、消息系统的同学；以及被"消息重复""会话串号""半夜告警"折磨过的运维同学。代码给的是能直接改的骨架，思路讲的是我为什么这么选。新手也能看，因为我会把每个专业词都用生活里的场景解释一遍；老手可以直接跳到第 3、5 章看参数和排查表。

1. Agent-Reach 到底在解决什么问题

1.1 三个断点：入口断、路由断、回流断

把 Agent 上线，最常见的失败不是"答得不好"，而是"根本没人问到它"。我把这类失败拆成三个断点，分别对应链路的头、中、尾。

入口断。用户在你的页面上提问，消息落到了一个临时的前端状态里，刷新就没了；或者客服在工单系统里回复，Agent 完全不知道这条工单存在。Agent 没有一个被外部系统"叫到"的固定地址，谁能找到它、用什么格式找它，全靠各个业务自己约定，最后变成七八套写法。

路由断。消息进来了，但不知道该给哪个 Agent 处理。是售前咨询还是售后工单？是英文还是中文？是普通提问还是需要人工兜底的投诉？没有一层统一的路由，业务代码里就会长出一堆 if-else，每加一个场景就改一次主流程，改到最后没人敢动。

回流断。Agent 处理完了，结果回不去。用户那边显示"处理中"，其实早就答完了；或者答完了却回写到错误的会话里，A 用户的答案飘到了 B 用户的屏幕上。这类问题最要命，因为它不报错，只是安静地错。

我试过一个偷懒的做法：把这三件事全塞进业务服务里，谁要用谁自己写。结果是三个业务各写了一遍重试逻辑，重试参数还不一样，其中一个用了固定间隔 1 秒重试 10 次，直接把下游打挂。从那之后我就认定了，触达这件事必须单独抽一层出来，因为它是跨业务的公共契约，不该由任何一个业务私自定义。

1.2 四类典型场景，看看你踩在哪一类

不同团队对"触达"的诉求差别很大，我把它归成四类，你对号入座一下，后面的设计取舍会更好理解。

我做内部助手的时候踩过一个坑：一开始没做身份映射，同事在沟通工具里的昵称和工号系统里的姓名对不上，导致 Agent 拿不到正确的权限，一个同事查到了本不该看到的排班表。后来加了一层身份映射表，把通道侧的 ID、内部工号、角色三者绑在一起，这类问题才算根治。这一步不难，但一定要在设计初期就留位置，后补会很痛。

主动触达型的坑更隐蔽。我们做过一个异常提醒的 Agent，规则写得太宽，同一个问题在十分钟内推了四十多条，同事直接把机器人禁言了。后来加了"同一实体 + 同一问题类型"的窗口聚合，十分钟内只推一条，并在消息里带上"共 N 次"的计数，体验才回来。

1.3 为什么我坚持把它做成独立一层

有人会问，多一层不就多一次跳转、多一份延迟吗？这话对，但收益更大。独立一层的第一个好处是契约收敛：所有外部系统只需要认识一种信封格式，加新通道时改的是适配器，不是业务主流程。第二个好处是故障隔离：通道侧超时、限流、抖动，被这一层挡住，不会顺着调用链把业务服务拖死。第三个好处是能力复用：去重、限流、埋点、审计这些事，做一次全业务都能用。

代价我也说清楚：链路多了一跳，大概多 5 到 20 毫秒；多了一份配置要维护；出问题时定位的环节变多了。所以我会配套做三件事来抵消——把这一层做成无状态可水平扩展的服务、把全链路 trace id 打通、把配置做成热加载避免重启。这三件事做完，多出来的这一层基本就是净赚。

2. 整体架构设计：把触达拆成四个可替换的部件

2.1 身份与会话：给 Agent 一个门牌号

先说身份。Agent 需要一个稳定的标识，我用的是三层结构：tenant（租户或业务线）、agent（具体哪个 Agent）、channel_user（通道侧的用户标识）。三者拼起来才是一次会话的唯一键。为什么不只用channel_user？因为同一个人在不同业务线里的权限完全不同，同一套身份直接复用会串权限。

会话的设计更讲究。我见过两种做法：一种是"一条消息一次会话"，简单但没法多轮；另一种是"永久会话"，上下文越滚越长，最后把模型的上下文窗口撑爆。我的做法是滑动过期 + 分段摘要：会话在最后一次交互后保留 30 分钟，中间每 10 轮做一次摘要压缩，把历史压成一段结构化文本塞进系统提示里。30 分钟这个数不是拍脑袋来的——我看过线上数据，客服场景里超过 30 分钟还接着上一句问的用户不到 4%，为这 4% 一直保留全量上下文，成本划不来。

注意：会话键里千万不要放时间戳之类的变量，否则每次请求都会生成新会话，多轮对话直接失效。这个错误我在两个项目里都见过，排查起来非常费时间，因为日志里每条记录看起来都正常。

2.2 路由与编排：消息进来之后发生了什么

一条消息进到 Agent-Reach 之后，会依次经过五个动作：校验、归一、匹配、执行、回写。我把它叫五段式流水线，每一段的职责单一，方便单独替换和单独压测。

• 校验：签名、时间戳、来源白名单、体量上限。体量上限我一般设 256 KB，超过的直接拒绝，防止有人拿大文件来打内存。
• 归一：把不同通道的原始报文转成统一信封，补上缺失的字段，统一时间格式为毫秒时间戳。
• 匹配：按路由表找目标 Agent。路由表支持四种匹配维度，优先级从高到低是精确会话、精确用户、规则表达式、默认兜底。
• 执行：调用 Agent，带超时、带重试、带熔断。
• 回写：把结果按原通道格式化后送回，同时写一份审计记录。

这里有个设计上的取舍我想强调：编排逻辑不要下沉到通道适配器里。我见过有人在适配器里写了"如果消息里带投诉两个字就转人工"这种判断，结果换了一个通道之后规则就失效了。规则应该集中在路由层，适配器只负责格式转换，这个边界守住了，后面加通道基本不用改逻辑。

2.3 通道适配与统一信封：为什么死磕一种格式

统一信封是整套设计里最值钱的部分。它的价值不在于好看，而在于让上游和下游可以独立演进。通道那边改了接口字段，只要适配器把映射改一下，Agent 侧一行代码都不用动。

我的信封里保留这些字段：消息 ID、会话键、租户、来源通道、发送者、接收者、内容类型、内容体、附件列表、语言、时间戳、幂等键、扩展字段。字段不多，但每一个都有明确的产生方和消费方。其中幂等键由入口生成，规则是"通道 + 通道侧消息 ID"的哈希，这样同一条消息无论重投多少次，键都一样，去重就能生效。

提示：扩展字段一定要保留，而且要用可序列化的结构。真实业务里总有一些通道特有的东西，比如消息是否被引用、是否有话题分组，硬塞进固定字段会让信封越来越脏。

2.4 存储与状态：上下文到底放哪

这个问题我纠结了很久。放内存最快，但服务一重启就全丢；放关系库最稳，但每轮对话读写两次，QPS 一上来就是瓶颈；放缓存最合适，但要接受它可能丢。我最终的组合是：热数据放缓存，冷数据落库，中间用异步写入衔接。

具体来说，会话上下文、路由缓存、去重键放缓存，设置合理的过期时间；审计记录、消息全文、执行结果异步落到关系库或对象存储，允许有秒级延迟。这样热路径只有一次缓存读和一次缓存写，延迟能压到几毫秒；冷路径异步做，不影响主流程。代价是极端情况下可能丢掉最后几条审计记录，对业务来说可以接受，因为审计本身不是实时的。

数据保留策略也要在第一天就定。我一般的做法是：消息全文保留 7 天，审计摘要保留 180 天，会话上下文保留 30 分钟。这三个数字直接影响存储成本，别等到磁盘告警了才想起来清理。

3. 核心实现细节：搭一个最小可用版本

3.1 目录结构与依赖选型

我把服务拆成四层目录，职责一目了然。

agent-reach/ app/ api/ # 入口，只做参数绑定和调用编排 core/ envelope.py # 统一信封定义与校验 router.py # 路由表匹配 executor.py # 执行、重试、熔断 idempotent.py # 去重 channels/ # 各通道适配器，一个通道一个文件 web.py ticket.py mail.py infra/ cache.py db.py metrics.py

选型上我偏保守：Web 框架用一个轻量的异步框架就够了，关键是异步，因为触达层的大量时间花在等待下游上，同步模型会把线程池吃干。缓存用一个成熟的内存型存储，关系库用常见的开源库，指标上报直接对接通用监控体系。我不太建议在这层引入复杂的工作流引擎，除非你的编排真的到了几十个分支的规模——大多数团队根本用不上，反而增加运维负担。

3.2 统一信封的设计与代码

信封我用数据类来写，字段固定，校验集中在一个方法里。这样任何通道进来，只要转换成功就能往下走。

from dataclasses import dataclass, field from typing import Any @dataclass class Envelope: msg_id: str # 全局唯一，入口生成 session_key: str # 会话键：tenant:agent:channel_user tenant: str channel: str sender: str receiver: str content_type: str # text / markdown / file content: str attachments: list = field(default_factory=list) lang: str = "zh" ts: int = 0 # 毫秒时间戳 idem_key: str = "" extra: dict = field(default_factory=dict) MAX_BODY = 256 * 1024 def validate(self): if not self.msg_id or not self.session_key: raise ValueError("missing_identity") if len(self.content.encode("utf-8")) > self.MAX_BODY: raise ValueError("body_too_large") if not self.idem_key: self.idem_key = f"{self.channel}:{self.msg_id}" if self.ts == 0: raise ValueError("missing_timestamp") return self

这段代码看着简单，但每一行都有来历。MAX_BODY用字节数而不是字符数，是因为中文字符占多个字节，用字符数判断会漏掉大报文；idem_key在缺失时自动补，是为了兼容那些还没升级的旧通道；时间戳必须由入口填，不允许下游自己取当前时间，否则重试之后时间就漂了，跨系统的顺序判断会乱。

3.3 路由表的匹配规则与优先级

路由匹配我设计成四档优先级，命中即返回，不再往下走。这个设计的关键是可预测：任何一条消息，你能一眼看出它会被哪条规则接住。

routes: - id: vip-session priority: 100 match: { session_key: "t1:sales:vip_8821" } target: sales_agent_v2 - id: user-level priority: 80 match: { tenant: "t1", sender: "u_10086" } target: sales_agent_v1 - id: rule-based priority: 50 match: { expr: "lang == 'zh' and '退款' in content" } target: aftersale_agent - id: fallback priority: 0 match: {} target: default_agent

优先级之间的间隔我留得比较大，是为了以后插入新档位时不用改老配置。规则表达式那一档要格外小心，我吃过一次亏：规则里写了'退款' in content，结果有个用户问"退款流程是什么"，被直接路由到了售后 Agent，而售后 Agent 只处理已购订单，答了一堆无关内容。后来改成"意图分类 + 关键词"双条件，误路由率从 7% 降到了 1% 以内。

3.4 幂等、重试与超时：参数是算出来的，不是猜的

这三个参数决定系统的"脾气"，我把计算过程写出来，你可以照着套。

超时预算。假设对外承诺的首响时间是 3 秒，那预算得这么切：入口校验 50 毫秒，归一 10 毫秒，路由 10 毫秒，限流与去重检查 30 毫秒，Agent 执行 2200 毫秒，回写 200 毫秒，剩余 500 毫秒留给网络抖动和排队。所以 Agent 侧的硬超时设 2200 毫秒，不是随便写的 5 秒——如果设 5 秒，端到端必然突破承诺，用户早就走了。

重试策略。只对幂等且可重试的失败重试，比如网络超时、下游返回 5xx。公式是：

delay_n = min(base * 2^n, cap) + random(0, jitter_ms) base = 200ms, cap = 2000ms, jitter_ms = 200

也就是 200、400、800、1600、2000……最多重试 3 次。为什么加抖动？因为不加抖动的话，一批同时失败的消息会在同一时刻再次涌向下游，形成二次冲击。为什么最多 3 次？因为第 4 次重试时，用户早就超时离开了，重试只是在浪费资源。

去重窗口。幂等键的过期时间必须大于"最大可能重试窗口"。上面算下来最大窗口约 200+400+800+1600+2000 ≈ 5 秒，加上排队和调度，我取1 小时。这个数字看起来大得离谱，但你要考虑到上游可能自己也在重试，而且有些通道的消息会延迟投递。1 小时的成本很低，一条键也就几十字节，但漏掉的重复消息会让用户体验直接崩掉。

3.5 可观测性埋点：出问题时你能看见什么

这一层不做埋点，等于闭着眼睛开车。我埋三类点：日志、指标、链路。

日志用结构化格式，每条必须带 trace id、msg id、session key、tenant、channel、阶段名、耗时。五个字段一个都不能省，因为排查时你往往只知道其中一个。指标我关注四个：入口 QPS、路由命中率、执行耗时分布（P50/P95/P99）、失败率按错误码分类。链路追踪把一次请求经过的所有环节串起来，尤其是跨服务调用，这是定位"到底卡在哪一跳"的唯一手段。

提示：P99 比平均值重要得多。我们有一次线上问题是平均耗时 180 毫秒，看着很健康，但 P99 到了 8 秒，原因是千分之五的请求命中了没建索引的查询。只看平均值的话，这个问题永远发现不了。

4. 实操过程：把一条消息送到 Agent 手里

4.1 本地起服务与最小验证

本地验证我一般从命令行直接打信封，不接任何真实通道，先把执行链路跑通。

curl -X POST http://localhost:8080/v1/reach \ -H "Content-Type: application/json" \ -H "X-Signature: <sig>" \ -d '{ "msg_id": "m_20240101_0001", "session_key": "t1:sales:u_10086", "tenant": "t1", "channel": "web", "sender": "u_10086", "receiver": "sales_agent_v2", "content_type": "text", "content": "我这个订单什么时候能到", "ts": 1704067200000 }'

第一次跑通之后，我会立刻做三件验证：重复投递同一条 msg_id，确认只执行一次；把 Agent 侧的超时降到 100 毫秒，确认重试按预期退避；故意发一条 300 KB 的消息，确认被拒绝并返回明确的错误码。这三条过了，说明去重、重试、体量控制都活着，比写十个单测都管用。

4.2 接入第一个真实通道

接通道的顺序我建议从最简单的那个开始，通常是站内信或者测试用的网页入口。原因是通道越简单，你能越快暴露信封转换的问题，而不是被通道自己的鉴权、回执、格式问题干扰。

接通道的步骤基本固定：第一步，在通道侧配置回调地址，指向我们的入口；第二步，写适配器，实现"原始报文到信封"和"结果到通道报文"两个方向的转换；第三步，处理通道特有的回执机制，有些通道要求你在几秒内返回一个成功码，这时候千万不能等 Agent 执行完再返回，要先回执、后异步处理；第四步，跑一遍回归，重点看附件和特殊字符。

注意：先回执后处理这个模式一定要配上去重和状态机，否则用户看到"已收到"但实际执行失败了，会反复追问，反而制造更多消息。我的做法是回执里带上一个查询地址，用户能在那里看到真实状态。

4.3 压力测试与容量估算

容量我不靠感觉，靠算。单实例的吞吐大概这么估：假设异步框架下单实例能撑 200 个并发在途请求，平均处理耗时 300 毫秒，那么理论 QPS ≈ 200 / 0.3 ≈ 667。但实际要留水位，按 60% 算，就是单实例 400 QPS。

然后看峰值需求。假设日活用户 5 万，集中在晚 8 点到 10 点，峰值系数按 5 倍算，日总请求 15 万次，两个小时里占比 60%，也就是 9 万次，平均 12.5 QPS，峰值再乘 3 就是 37.5 QPS。这么一算，两台实例绰绰有余。但我仍然会部署四台，原因是一台要留着做滚动发布，一台要扛实例故障，多出来的成本远低于半夜被告警叫醒的成本。

压测我关注三个指标：在目标 QPS 下 P99 是否还在预算内、错误率是否保持在千分之一以下、下游被调用的速率是否触发了限流。前两个是给自己看的，第三个是给下游看的——很多人压测只盯着自己，结果把下游压挂了，这种事故比自挂更难看。

4.4 灰度上线与回滚预案

上线我按"影子、白名单、小流量、全量"四步走。影子阶段只复制流量不真正回写，用来验证转换和路由的正确性；白名单阶段挑一两个内部用户真跑；小流量按 5% 放开，观察 24 小时；没问题再全量。

回滚预案必须在上线前写好，包括一个开关能瞬间把流量切回旧链路，以及一份"哪些数据需要人工补"的清单。我见过最狼狈的情况是上线出问题想回滚，结果发现新链路已经写了一批会话状态，回滚后旧链路不认识这些状态，导致一部分用户对话接不上。所以状态格式要么向后兼容，要么在灰度期双写。

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

5.1 消息重复、丢失、乱序怎么快速定位

重复。先看幂等键有没有落到上游手里。我遇到过的原因有三种：上游没传 msg_id 导致每次都生成新的；幂等键在缓存里被提前淘汰；并发场景下"检查再写入"不是原子的。第三种最隐蔽，解法是把检查和写入合并成一个原子操作，而不是分两步做。

丢失。丢失通常发生在"先回执后处理"的模式里：回执发了，异步任务因为队列满被拒了。排查方法是给异步任务加落盘缓冲，并且监控队列长度和拒绝数。这两个指标一涨，说明处理能力跟不上了，不是丢消息本身的问题，是容量问题。

乱序。同一个会话的两条消息，后发的先到了。原因通常是重试导致的——第一条失败了在退避，第二条直接成功。解法是在会话维度加一个单调递增的序号，Agent 侧遇到乱序时按序号缓冲或者丢弃过期请求。我给的建议是按序号缓冲窗口设 3 秒，超过就直接放行，避免为了顺序把延迟拖长。

5.2 超时与级联：几种典型表现

超时最怕的不是超时本身，而是级联。表现是这样的：下游变慢，我们的请求占住并发槽，新请求排队，排队时间计入超时，于是更多请求超时，并发槽被占得更满。这个过程几十秒内就能把整个服务拖死。

破解手段有三个，缺一不可。并发隔离：给每个下游分配独立的并发额度，一个下游慢不影响其他下游。熔断：连续失败到阈值（我用 20 次里失败 10 次）就快速失败，隔 30 秒后放一个请求试探。超时必须逐层递减：上游给我们的预算是 2 秒，我们给下游的就只能是 1.5 秒，绝不能出现下游超时比上游还长的情况，那样上游先超时了，我们的重试全是无用功。

5.3 会话串号的几种隐蔽原因

会话串号是最难查的一类问题，因为日志里每条记录都"看起来对"。我遇到过三种原因。

第一种，会话键的拼接顺序不一致。有的地方写tenant:agent:user，有的地方写tenant:user:agent，结果同一个人被拆成了两个会话。解法是把拼接逻辑封装成一个函数，全项目只允许调这个函数，禁止手写字符串。

第二种，缓存键和会话键混用。有人图省事，直接用会话键当缓存键，但缓存里有别的业务也在用同一套键空间，前缀一撞就串了。解法是所有缓存键加业务前缀。

第三种，多租户环境下的默认值。某个租户没传 tenant，代码里用了默认值t1，于是这个租户的数据全落到了 t1 名下。解法是 tenant 缺失直接拒绝，不给默认值。这个原则我在所有涉及隔离的字段上都用——隔离字段不允许有默认值。

5.4 常见问题速查表

6. 上线后我总结的几条经验

6.1 设计期的最该守住的三个边界

第一条，适配器不许有业务逻辑。适配器的唯一职责是格式转换和回执。一旦你在里面写了判断，后面每加一个通道就要复制一遍判断，维护成本是指数增长的。

第二条，超时与重试必须集中配置，不许散落在业务代码里。我见过同一个服务里三个模块用了三套重试参数，出问题时谁也说不清到底重试了几次。集中配置还有一个好处是能按下游分别调整，某个下游特别慢，单独给它放宽，不影响其他。

第三条，隔离字段必须显式传递。tenant、agent、channel 这三个字段，任何一层都不允许用默认值兜底。少一个就报错，这是代价最小、收益最大的防御手段。

6.2 运维阶段的两个习惯

给每个告警配一条排查手册。告警响了，值班同学能照着手册在五分钟内定位到大致方向，而不是从日志第一条开始翻。手册不用长，三五行就够：看哪个指标、查哪张表、大概率是什么原因。

每周做一次失败样本复盘。我会把一周内的失败请求按错误码抽样出来，人工看一百条。这个习惯帮我抓到了好几个自动化监控抓不到的问题，比如某类特殊字符在某个通道里会被截断，错误率只有万分之几，但影响的是真实用户。指标看趋势，样本看真相，两件事都得做。

最后分享一个我自己一直在用的小技巧：在信封的扩展字段里，永远塞一个trace_hint，内容是入口侧的最简上下文，比如"来自工单 8821 的第三次追问"。它不参与任何逻辑判断，纯粹是给排查用的。出了问题的时候，这一句话经常比翻十分钟日志还有用。