企业官网建设流程全解析

1. 从“context-mode”这个词说起：它到底指什么

第一次看到“context-mode”这个标题，很多人会愣一下——它不像“XX管理系统”“XX爬虫框架”那样一眼能看出用途。我最初接触这个词是在做对话系统上下文管理的时候，当时团队里有人提了一句“把上下文切成 context-mode 来管”，我才意识到它其实是一个描述“上下文处理模式”的抽象概念，而不是某个具体的库或工具。

简单来说，context-mode 指的是一套系统在处理“上下文”时所采用的策略和状态模型。这里的“上下文”可以是对话历史、请求链路中的元数据、渲染管线里的环境变量、甚至是编译器在解析代码时维护的作用域栈。而“mode”则强调：同一套系统在不同场景下，会切换不同的上下文处理方式，每种方式对应一种 mode。

它解决的核心问题是：当上下文变得又长又杂时，如何让系统知道“现在该看哪些信息、该忽略哪些信息、该以什么优先级去用这些信息”。举个大白话的例子——你在跟朋友聊天，聊到一半突然插进来一个电话，接完电话回来继续聊，你脑子里会自动把“电话内容”和“刚才的聊天”分开存放，不会把两件事混在一起。context-mode 干的就是这个“分开存放并按场景切换”的活。

适合谁来了解这个内容？三类人最需要：一是做对话式 AI 应用的开发者，上下文窗口管理直接决定回答质量；二是做前端状态管理或渲染管线的工程师，不同页面模式下的上下文隔离是常见痛点；三是做后端请求链路追踪的同学，一个请求穿过多个服务时，上下文如何传递和切换 mode 直接影响排查效率。

我写这篇东西，不是要给你一个标准答案，因为 context-mode 本身就不是一个标准化产品。我想做的是把我在几个实际项目里踩过的坑、总结出的模式分类方法、以及一套可复用的设计思路摊开来讲。你看完之后，应该能自己判断：我的项目该用哪种 context-mode，该怎么切分，该怎么避免上下文污染。

2. 上下文为什么需要“模式”：三种典型失控场景

在讲具体怎么做之前，得先把“为什么需要 mode”这件事说透。我见过太多项目一开始觉得“上下文嘛，一个全局变量存着就行了”，结果到后期改不动、测不了、查不出问题。下面这三种失控场景，你大概率至少遇到过一种。

2.1 场景一：对话历史无限增长导致“记忆过载”

做对话系统最直观的坑。用户跟机器人聊了五十轮，你把五十轮全塞进 prompt 里，token 直接爆炸。更麻烦的是，早期聊的内容可能跟当前问题完全无关，但模型还是会“分心”去参考那些旧信息，导致回答跑偏。

我实测过一个案例：用户先问“帮我写个 Python 排序”，聊了十轮之后又问“刚才那个排序的时间复杂度是多少”。如果上下文里混入了中间十轮关于“如何配置数据库”的讨论，模型有相当概率把数据库连接池的配置参数当成排序算法的参数来回答。这就是典型的上下文没有按 mode 隔离——所有历史平铺在一起，模型无法判断哪些该优先。

正确的做法是给上下文打上 mode 标签：mode=code_generation的轮次和mode=qa的轮次分开存放，当前问题属于哪个 mode，就只取该 mode 下最近 N 轮加上全局摘要。这样既控制了长度，又避免了跨 mode 干扰。

2.2 场景二：多服务链路中上下文“串味”

后端微服务架构里，一个请求从网关进来，经过鉴权、业务逻辑、数据访问、日志上报四五个环节。每个环节都需要一些上下文信息：用户 ID、租户 ID、请求追踪 ID、灰度标记等等。很多团队的做法是搞一个巨大的RequestContext对象，所有字段塞进去，一路透传。

问题出在：不同环节对上下文的读写权限和生命周期要求完全不同。鉴权环节写入的用户身份，业务逻辑只能读不能改；灰度标记在网关确定后，后续环节不应该再覆盖；而像“当前重试次数”这种字段，只在数据访问层有意义，不该污染到日志上报层。

没有 mode 概念的时候，经常出现 A 服务把某个字段改了，B 服务读到脏数据，排查半天发现是上下文被意外覆盖。我见过最离谱的一次：日志上报模块为了记录“请求耗时”，往上下文里写了一个startTime字段，结果业务逻辑里恰好也有个同名字段用于计算超时，两边打架，导致超时判断全部失效。

2.3 场景三：前端渲染管线中“环境上下文”泄漏

前端做服务端渲染或同构渲染时，上下文管理是重灾区。同一个组件，在服务端渲染时拿到的上下文（比如请求头、cookie、初始数据）和客户端 hydration 时的上下文完全不同。如果没有明确的 mode 切换机制，很容易出现“服务端渲染出的 HTML 和客户端首次渲染不一致”的经典报错。

我踩过的一个具体坑：在服务端渲染模式下，组件从上下文里读了一个window.innerWidth的替代值（服务端没有 window，用了默认值 1024），客户端 hydration 时真实宽度是 375，两边渲染结果不一致，React 直接抛 hydration mismatch。根因就是没有区分 server-mode 和 client-mode 的上下文来源，组件代码里混用了两套逻辑。

这三个场景的共同点是：上下文本身没有错，错在没有给上下文定义清晰的模式边界。接下来我讲怎么设计这套模式体系。

3. 设计一套 context-mode 体系：从分类到落地

设计 context-mode 体系，核心就三件事：分类、隔离、切换。分类决定有哪些 mode，隔离决定 mode 之间怎么不打架，切换决定什么时候用哪个 mode。我按这个顺序讲，每一步都给可操作的方案。

3.1 第一步：按“生命周期”和“作用域”给上下文分类

不要一上来就按业务功能分，那样会越分越乱。我推荐用两个维度来切：生命周期（这个上下文活多久）和作用域（这个上下文谁能看见）。

这张表是我在三个项目里反复调整后稳定下来的分类。关键点是：一个上下文对象只属于一个 mode，不要搞“既是请求级又是全局级”的模糊地带。如果某个字段确实需要跨 mode 共享，那就把它提升为独立的global-mode，而不是让它同时挂在两个 mode 下。

分类做完之后，给每个 mode 定义清楚三件事：谁可以写、谁可以读、什么时候销毁。比如request-mode的规则是：网关可以写用户身份，业务服务只读；请求结束时统一销毁。session-mode的规则是：对话管理器可读写，其他服务只读；会话超时后销毁。

3.2 第二步：用“上下文栈”实现 mode 隔离

分类只是纸面上的，真正落地需要数据结构支撑。我试过几种方案，最后觉得上下文栈最直观也最好用。

思路很简单：维护一个栈结构，栈里每个元素是一个{mode, data}的元组。当前活跃的 mode 在栈顶，读取上下文时从栈顶往下找，找到第一个匹配的 mode 就返回。写入时只能写到栈顶 mode 或者显式指定的 mode。

class ContextStack: def __init__(self): self._stack = [] def push(self, mode, data=None): self._stack.append({"mode": mode, "data": data or {}}) def pop(self, mode): if self._stack and self._stack[-1]["mode"] == mode: return self._stack.pop() raise ValueError(f"Mode mismatch: expected {mode}") def get(self, key, mode=None): for frame in reversed(self._stack): if mode and frame["mode"] != mode: continue if key in frame["data"]: return frame["data"][key] return None def set(self, key, value, mode=None): target_mode = mode or self._stack[-1]["mode"] for frame in reversed(self._stack): if frame["mode"] == target_mode: frame["data"][key] = value return raise ValueError(f"Mode {target_mode} not found in stack")

这个栈结构的好处是：mode 的进入和退出天然对应栈的 push 和 pop。比如一个请求进来，先 pushrequest-mode；进入对话处理，再 pushsession-mode；调用外部服务前，pushtrace-mode。处理完依次 pop，上下文自动清理，不会泄漏到下一个请求。

注意：栈的深度要设上限，我一般限制在 8 层以内。超过 8 层说明 mode 设计太碎，需要合并。

3.3 第三步：mode 切换的触发时机与优先级规则

有了栈结构，接下来要定“什么时候 push 新 mode、什么时候 pop”。我总结了几条触发规则，按优先级从高到低：

1. 请求边界触发：HTTP 请求进入时 pushrequest-mode，响应返回时 pop。这是最外层的 mode，必须最先建立、最后销毁。
2. 会话边界触发：识别到对话 session ID 时 pushsession-mode，session 结束时 pop。注意 session-mode 可能跨多个 request-mode，所以它应该 push 在 request-mode 之上，但生命周期由 session 管理器控制。
3. 外部调用触发：发起 RPC 或 HTTP 调用前 pushtrace-mode，调用返回后 pop。trace-mode 里只放追踪 ID 和超时配置，不放业务数据。
4. 渲染阶段触发：服务端渲染开始前 pushrender-mode，渲染完成后 pop。客户端 hydration 时用同样的 mode 名但不同的数据源。

优先级规则的核心是：内层 mode 可以读外层 mode 的数据，外层不能读内层。比如trace-mode可以读request-mode里的用户 ID 用于日志，但request-mode不能读trace-mode里的重试次数。这条规则保证了上下文不会反向污染。

4. 实战：在对话系统中落地 context-mode

前面讲的是通用设计，这一章我拿对话系统做具体例子，因为这是 context-mode 价值最明显、坑也最多的场景。我会把完整的落地步骤、参数计算、以及我踩过的坑都摊开。

4.1 对话上下文的 mode 划分与 token 预算分配

对话系统里，我一般分四个 mode：

• system-mode：系统提示词、角色设定、安全规则。生命周期是整个会话，只读。
• session-mode：对话历史摘要、用户偏好、已确认的事实。生命周期是会话，可读写。
• turn-mode：当前轮次的用户输入、检索到的文档片段。生命周期是单轮，用完即弃。
• tool-mode：工具调用的参数和返回结果。生命周期是单次工具调用。

token 预算怎么分？我实测下来比较稳的比例是：system-mode 占 15%，session-mode 占 35%，turn-mode 占 40%，tool-mode 占 10%。假设模型上下文窗口是 8K token，那 system 给 1200，session 给 2800，turn 给 3200，tool 给 800。

这个比例不是拍脑袋来的。system 提示词一般 500-800 token 够用，留 1200 是给多轮对话中动态追加的安全规则。session 摘要每轮压缩后控制在 200 token 以内，2800 可以存 14 轮摘要。turn-mode 里检索文档片段通常 3-5 篇，每篇 500 token 左右，3200 刚好。tool-mode 的返回结果往往很长，但只需要保留关键字段，800 足够。

提示：这个预算是动态的。如果当前轮次没有工具调用，tool-mode 的 800 token 可以临时借给 turn-mode 用于放更多检索片段。我一般用一个简单的预算管理器来动态调配。

4.2 会话摘要的压缩策略：什么时候压、压到什么程度

session-mode 里的对话历史不能无限存，必须压缩。压缩策略我试过三种，最后稳定用滑动窗口 + 分层摘要。

滑动窗口：保留最近 5 轮完整对话，这 5 轮不压缩，直接放 session-mode。为什么是 5 轮？因为大多数追问都发生在 3 轮以内，5 轮覆盖了 95% 的指代消解需求。

分层摘要：5 轮之前的对话，按每 5 轮一组做摘要。第一层摘要保留关键实体和结论，第二层摘要只保留主题标签。比如：

第一层摘要（每5轮）： - 用户询问了Python排序算法，确认使用快速排序，时间复杂度O(nlogn) - 用户切换到数据库配置问题，确认使用PostgreSQL，连接池大小20 第二层摘要（每25轮）： - 主题：算法咨询、数据库配置

压缩触发时机：当 session-mode 的 token 占用超过预算的 80% 时触发压缩。压缩时从最旧的完整对话开始，每 5 轮合并成一条第一层摘要；当第一层摘要超过 10 条时，再合并成第二层摘要。

我踩过的一个坑：早期我让模型自己决定什么时候压缩，结果模型倾向于“不压缩”，因为压缩会丢失信息。后来改成硬性阈值触发，到 80% 必须压，模型只负责生成摘要内容，不负责决定是否压缩。这样稳定多了。

4.3 工具调用上下文的隔离：避免参数污染对话历史

工具调用是 context-mode 最容易出问题的地方。我见过一个典型 bug：用户问“北京天气怎么样”，系统调用天气 API 返回了 JSON，这个 JSON 被塞进了对话历史。下一轮用户问“那上海呢”，模型看到历史里的 JSON，直接把北京的天气数据改了个城市名就返回了，根本没有真正调用 API。

根因就是工具返回结果没有隔离在 tool-mode 里，而是混进了 session-mode。正确做法是：工具调用的原始返回只存在 tool-mode，session-mode 里只存“工具调用摘要”，比如“已查询北京天气，结果：晴，25度”。摘要由系统生成，不直接把 JSON 塞进去。

def handle_tool_call(tool_name, params, context_stack): context_stack.push("tool-mode", {"tool": tool_name, "params": params}) try: raw_result = call_tool(tool_name, params) context_stack.set("raw_result", raw_result, mode="tool-mode") summary = summarize_tool_result(tool_name, raw_result) context_stack.set("last_tool_summary", summary, mode="session-mode") return summary finally: context_stack.pop("tool-mode")

这样 tool-mode 在调用结束后立即 pop，原始结果不会进入下一轮。session-mode 里只有摘要，模型不会误把原始数据当事实。

5. 踩坑记录：那些让我熬夜排查的 context-mode 问题

这一章不讲理论，只讲我实际踩过的坑和排查过程。每个坑都附上根因和修复方案，你遇到类似问题时可以对照着查。

5.1 坑一：mode 栈 pop 顺序错误导致上下文泄漏

现象：压测时发现，A 用户的请求偶尔会读到 B 用户的会话数据。概率很低，大概万分之一，但一旦出现就是严重的数据泄漏。

排查过程：先查了 session 存储，确认 key 是按用户 ID 隔离的，没问题。然后加日志追踪 context stack 的 push/pop 记录，发现异常请求的栈在某个时刻深度是 3，正常应该是 2。也就是说，有一个 mode 没有被正确 pop。

继续追，发现是异常处理分支的问题。当工具调用超时时，代码走了except分支直接返回错误响应，但finally块里的pop("tool-mode")因为异常类型不匹配被跳过了。栈里残留的 tool-mode 一直留到下一个请求，而下一个请求恰好复用了同一个协程，就串了。

修复：把所有 mode 的 pop 操作统一放到最外层的finally里，用栈深度做校验。请求结束时检查栈深度是否回到初始值，不是就强制清空并打警告日志。

def handle_request(request): initial_depth = context_stack.depth() try: context_stack.push("request-mode", extract_request_context(request)) # ... 业务逻辑 finally: while context_stack.depth() > initial_depth: frame = context_stack.pop_any() logger.warning(f"Leaked mode: {frame['mode']}")

这个坑的教训是：不要在每个业务分支里单独 pop，统一在最外层兜底。

5.2 坑二：session-mode 跨请求复用时的并发写冲突

现象：同一个用户快速连续发两条消息，第二条消息的回复里丢失了第一条消息的上下文。用户感知就是“机器人失忆了”。

排查过程：session-mode 是跨请求的，存在 Redis 里。两个请求几乎同时到达，都读取了同一份 session 数据，各自修改后写回，后写的覆盖了先写的。典型的 read-modify-write 竞态。

修复：给 session-mode 的写操作加分布式锁，锁的粒度是 session ID。同时把 session 数据改成“追加式”而非“覆盖式”——对话历史用 Redis List 存储，每次追加新轮次，而不是读取整个列表再写回。

def append_turn(session_id, turn): lock_key = f"session_lock:{session_id}" with redis.lock(lock_key, timeout=5): redis.rpush(f"session_turns:{session_id}", serialize(turn)) redis.expire(f"session_turns:{session_id}", 3600)

注意：锁超时设 5 秒，因为 session 写操作很轻量。如果 5 秒还没写完，说明有更严重的问题，让锁自动释放比死等更好。

5.3 坑三：render-mode 下服务端与客户端上下文不一致

现象：React 服务端渲染的页面，客户端 hydration 时报Text content did not match。刷新几次偶尔正常，大部分时候报错。

排查过程：对比服务端和客户端的渲染输出，发现差异在一个时间戳字段。服务端渲染时用了Date.now()，客户端 hydration 时又调了一次Date.now()，两次时间不同，渲染结果自然不同。

修复：把时间戳这类“非确定性”数据从 render-mode 的上下文中剥离，改为在服务端渲染时生成一个固定值，通过render-mode的初始数据传给客户端，客户端 hydration 时直接读这个固定值，不再重新计算。

// 服务端 contextStack.push('render-mode', { timestamp: Date.now(), // 只算一次 userAgent: req.headers['user-agent'] }); // 客户端 hydration const renderContext = window.__RENDER_CONTEXT__; // 直接用 renderContext.timestamp，不重新计算

这个坑的本质是：render-mode 的上下文必须是确定性的，任何在服务端和客户端会算出不同结果的逻辑，都不能放在 render-mode 里。

6. 让 context-mode 可观测：日志、指标与调试技巧

context-mode 体系建好之后，如果不可观测，出了问题还是抓瞎。这一章讲怎么给 context-mode 加日志、加指标，以及几个我常用的调试技巧。

6.1 给每个 mode 打上追踪标签

最基础的一步：每次 push mode 时，生成一个唯一的mode_trace_id，格式是{request_id}-{mode_name}-{sequence}。这个 ID 会出现在该 mode 生命周期内的所有日志里。

比如请求 ID 是req-abc，第一次 push request-mode 时 trace ID 是req-abc-request-1，push session-mode 时是req-abc-session-2。这样在日志系统里搜req-abc，就能看到完整的 mode 切换链路。

日志格式我一般用结构化日志：

{ "timestamp": "2024-01-15T10:30:00Z", "level": "INFO", "mode_trace_id": "req-abc-session-2", "mode": "session-mode", "action": "push", "stack_depth": 2, "data_keys": ["session_id", "user_id"] }

关键是data_keys字段——只记录 key 不记录 value，避免敏感信息进日志。排查时如果需要看具体值，再用 trace ID 去专门的上下文快照存储里查。

6.2 关键指标：mode 深度、切换频率、上下文命中率

光有日志不够，还需要指标来做趋势监控。我重点盯三个指标：

mode 栈深度：正常请求的栈深度应该在 2-4 之间。如果 P99 超过 6，说明 mode 设计太碎或者有泄漏。我设的告警阈值是：深度大于 6 的请求占比超过 1% 就告警。

mode 切换频率：单位时间内 push/pop 的次数。切换太频繁说明 mode 边界划得不合理，比如把本该属于同一个 mode 的逻辑拆成了两个。我一般要求单请求内切换次数不超过 10 次。

上下文命中率：get操作成功返回值的比例。如果命中率低于 80%，说明很多代码在查不存在的 key，要么是 mode 分类有问题，要么是写入逻辑有遗漏。

6.3 本地调试：把上下文栈 dump 出来看

开发阶段最实用的技巧：在关键断点处把整个上下文栈 dump 成可读格式。我写了一个dump_stack方法，输出类似这样：

[Stack Depth: 3] ├── [0] request-mode (age: 120ms) │ ├── request_id: req-abc │ ├── user_id: u-123 │ └── tenant_id: t-456 ├── [1] session-mode (age: 80ms) │ ├── session_id: s-789 │ └── turn_count: 5 └── [2] tool-mode (age: 10ms) <-- current ├── tool: weather_api └── params: {city: "beijing"}

这个 dump 在排查“为什么读不到某个值”时特别有用——一眼就能看出目标 key 在不在栈里、在哪个 mode 里、当前 mode 是不是栈顶。

我一般只在 debug 日志级别下开启 dump，生产环境关闭，因为 dump 本身有性能开销，而且可能包含敏感数据。

7. 几个容易混淆的边界问题

最后聊几个我在技术群里被问得最多的边界问题。这些问题没有标准答案，我给出我的做法和理由，你可以根据自己的场景调整。

7.1 context-mode 和依赖注入有什么区别

有人觉得 context-mode 就是依赖注入的变体。我的理解是：依赖注入解决的是“对象怎么拿到它需要的依赖”，context-mode 解决的是“依赖在不同场景下该用哪一份”。依赖注入是静态的、启动时确定的；context-mode 是动态的、运行时切换的。

举个例子：数据库连接池通过依赖注入传给 Repository，这是 DI。但同一个 Repository 在“读主库”和“读从库”两种模式下该用哪个连接，这是 context-mode 要管的。两者配合使用，不冲突。

7.2 mode 的数量控制在多少合适

我见过有人设计了 20 多个 mode，结果维护成本极高，新人根本记不住。我的经验是：核心 mode 控制在 5-8 个，超过这个数就要考虑合并。

合并的原则是：如果两个 mode 的生命周期完全一致、读写权限也一致，就合并成一个。比如auth-mode和user-mode，如果都是请求级、都是网关写业务读，那就合并成request-mode下的不同字段，不必单独建 mode。

7.3 异步任务中 context-mode 怎么传递

异步任务（比如消息队列消费、定时任务）没有 HTTP 请求边界，context-mode 的建立和销毁需要手动管理。我的做法是：在任务入口处显式 push 一个task-mode，任务结束时 pop。如果任务内部发起了 RPC 调用，再 pushtrace-mode。

关键是不要依赖框架自动传递上下文。异步框架的上下文传播机制各不相同，有的用 ThreadLocal，有的用协程上下文，混用容易出问题。我一般要求异步任务的入口代码显式建立 context stack，不依赖隐式传递。

提示：如果异步任务会跨进程（比如通过消息队列），context-mode 需要序列化后随消息一起传递。我通常只序列化trace-mode和request-mode的关键字段，session-mode 不跨进程，由接收方根据 session ID 重新加载。

7.4 上下文数据该存内存还是存外部存储

这取决于 mode 的生命周期。turn-mode和tool-mode生命周期极短，存内存即可。request-mode也是内存，请求结束就销毁。session-mode和global-mode需要跨请求甚至跨服务，必须存外部存储（Redis、数据库等）。

我踩过的一个坑：早期把 session-mode 也放内存，结果服务重启后所有会话丢失。后来改成 Redis 存储，同时加了一层本地缓存（Caffeine）来减少 Redis 访问。本地缓存的过期时间设 30 秒，比 Redis 的 1 小时短很多，保证最终一致性。

8. 我个人的几条经验总结

写到这里，该讲的原理、步骤、坑都讲得差不多了。最后分享几条我在多个项目里反复验证过的经验，不算什么高深理论，但确实帮我省了很多时间。

第一条：先画 mode 边界图再写代码。我现在的习惯是，任何涉及上下文管理的模块，先在白板上画出 mode 的层级关系和切换时机，确认没有循环依赖、没有跨层写入，再动手写。这个习惯让我少写了至少 30% 的返工代码。

第二条：mode 的命名要带生命周期后缀。比如request-mode、session-mode、global-mode，一看名字就知道活多久。不要用user-context、>