1. 从“上下文模式”这个命名说起：它到底在解决什么问题
第一次看到“context-mode”这个词，很多人会下意识地把它当成某个框架里的配置项，或者某个库的开关参数。但如果你真的在工程里跟“上下文”打过交道，就会明白这个词背后藏着的是一类非常具体、非常磨人的问题：同一段逻辑，在不同上下文里需要表现出不同的行为，而你又不想把这份差异硬编码到每一个调用点。
举个最直白的例子。假设你在做一个文本处理工具，同一个“截断”操作，在“摘要生成”场景下你希望它保留开头和结尾、丢掉中间；在“日志采样”场景下你希望它保留最近的若干条；在“对话历史压缩”场景下你希望它按轮次成对保留。这三个需求本质上都是“截断”，但上下文不同，策略就不同。如果你在每个调用点写 if-else，代码会迅速膨胀成一团乱麻；如果你把它抽象成一个统一的“上下文模式”机制，调用方只需要声明“我现在处于哪种模式”，具体行为由模式自己决定。
这就是 context-mode 这类设计思路的核心价值：把“在什么场景下做什么事”这件事，从散落各处的条件判断，收敛成一个可命名、可切换、可组合的模式集合。它不是一个具体的库名，而是一种架构取向。你可以用类实现它，可以用策略模式实现它，也可以用一张配置表加一个分发函数实现它。关键不在于用什么技术，而在于你有没有意识到“上下文”本身应该成为一等公民。
这篇文章适合几类人看：一是正在做多场景复用逻辑、被 if-else 折磨的开发者；二是想理解“策略模式”“状态模式”在真实项目里怎么落地的人；三是对“上下文感知”这类设计思想感兴趣、想找一个具体切入点的人。我会从命名背后的意图讲起，拆到实现层面的取舍，再补上我在实际项目里踩过的坑和验证过的做法。全文不依赖任何特定框架，思路可以直接迁移到你手上的语言和项目里。
2. 拆解 context-mode 的语义层次：上下文、模式、以及两者的耦合方式
2.1 “上下文”在工程语境里到底指什么
很多人把“上下文”理解得太窄，以为就是函数调用栈或者线程本地变量。但在 context-mode 这个命名里，上下文的含义要宽得多。它至少包含三个层次：
- 调用上下文：谁在调用、从哪个入口进来、当前处于请求生命周期的哪个阶段。
- 数据上下文：当前处理的数据有什么特征，比如长度、类型、来源、置信度。
- 业务上下文：当前处于哪个业务场景，比如“首次加载”“增量更新”“补偿重试”。
这三层上下文往往同时存在，而且互相影响。一个典型的坑是：只根据调用上下文选模式，忽略了数据上下文，结果同一模式下遇到超长输入就崩了。我在一个文本摘要项目里就遇到过这种情况——模式选的是“保留首尾”，但输入是一段没有明显段落结构的连续文本，首尾截断直接把语义切碎了。后来补了一条规则：数据上下文中如果检测到“无段落边界”，就自动降级到“按句子边界截断”。这条规则不是写在调用点的，而是写在模式内部的，调用方完全无感。
所以理解 context-mode 的第一步，是承认上下文是多维的，而且模式的选择逻辑应该能同时消费这些维度。
2.2 “模式”不是简单的枚举，而是行为契约
把模式理解成 enum 是最容易犯的错误。Mode.SUMMARY、Mode.LOG、Mode.DIALOG这样定义本身没问题，问题在于如果你只把它当枚举用，那模式内部的行为还是散落的。真正的“模式”应该是一个行为契约：它声明“在这个模式下，输入会被如何对待、输出会满足什么不变量、边界情况如何处理”。
用生活化的类比：模式就像餐厅里的“套餐”。你点套餐 A，不是说你只能吃 A 里的某一道菜，而是说厨房会按照 A 的规则来组合、分量、上菜顺序。套餐是一个契约，不是一个标签。同理，context-mode 里的模式应该封装完整的处理逻辑，而不是只做一个 switch 的 case 值。
我在实现时会强制每个模式实现三个方法：accepts(context)判断是否适用、transform(input, context)执行核心逻辑、validate(output)校验输出是否满足契约。这三个方法把“能不能用”“怎么用”“用得对不对”分开，后续排查问题时定位非常快。
2.3 耦合方式决定了架构的灵活度
上下文和模式之间怎么关联，是 context-mode 设计里最关键的决策。常见的有三种耦合方式：
| 耦合方式 | 做法 | 优点 | 缺点 |
|---|---|---|---|
| 调用方显式指定 | 调用时传入 mode 参数 | 简单直观，可控性强 | 调用方需要了解所有模式 |
| 上下文自动推导 | 根据 context 特征自动选模式 | 调用方无感，复用性好 | 推导逻辑复杂，调试困难 |
| 混合式 | 默认自动推导，允许显式覆盖 | 兼顾灵活与便利 | 需要处理优先级和冲突 |
我个人的经验是：内部工具用自动推导，对外 API 用显式指定，混合式留给需要渐进迁移的老系统。原因很简单——自动推导的调试成本很高，一旦选错模式，排查链路会拉得很长；而对外 API 如果强制调用方理解所有模式，接入成本又太高。混合式看起来最美，但优先级规则如果没设计好，会出现“我明明指定了模式却被覆盖”这种让人抓狂的问题。
3. 落地一套 context-mode 机制：从接口设计到分发逻辑
3.1 先定义契约，再写实现
不管你用什么语言，我建议的第一步都是把模式契约写成接口或抽象类。以 Python 为例，一个最小可用的契约大概长这样：
from abc import ABC, abstractmethod class ContextMode(ABC): @abstractmethod def accepts(self, context: dict) -> bool: """判断当前上下文是否适用本模式""" ... @abstractmethod def transform(self, payload, context: dict): """执行核心处理逻辑""" ... @abstractmethod def validate(self, output, context: dict) -> bool: """校验输出是否满足本模式的契约""" ...这三个方法看起来简单，但每一个都有讲究。accepts里不要写太复杂的逻辑，它应该是一个快速判断，复杂判断放到模式选择器里。transform是纯函数最好，不要在里面改全局状态，否则模式之间会互相污染。validate很多人会省略，但它是你后续做灰度、做回滚时的安全网——没有它，你根本不知道新模式有没有破坏原有契约。
3.2 模式选择器的设计：优先级、回退与冲突解决
模式选择器是 context-mode 的大脑。它的输入是上下文，输出是选中的模式。设计时我建议遵循三条规则：
- 显式优先于隐式：如果调用方指定了模式，除非该模式明确拒绝当前上下文，否则不覆盖。
- 具体优先于通用：越具体的模式优先级越高，通用模式作为兜底。
- 必须有兜底：无论上下文多奇怪，都要有一个默认模式接住，绝不能抛“无可用模式”这种错。
实现上可以用一个有序列表加遍历：
class ModeSelector: def __init__(self, modes): # modes 按优先级从高到低排列 self.modes = modes def select(self, context, explicit_mode=None): if explicit_mode and explicit_mode.accepts(context): return explicit_mode for mode in self.modes: if mode.accepts(context): return mode raise RuntimeError("no fallback mode configured")这里有个容易忽略的点：explicit_mode.accepts(context)这个判断不能省。我见过有人直接if explicit_mode: return explicit_mode，结果调用方指定了一个不适用于当前数据的模式，处理出来的结果完全不对。显式指定是“意图”，但意图也要经过契约校验。
3.3 上下文采集：别等到用的时候才发现缺字段
上下文采集最忌讳的是“用到什么才采什么”。正确的做法是在请求入口处一次性采集完整上下文，后续所有模式共享同一份。这样做的原因有两个：一是避免重复计算，二是保证同一请求内上下文一致，不会出现“模式 A 看到的上下文和模式 B 看到的不一样”这种诡异问题。
我通常会把上下文分成两类字段：稳定字段（请求 ID、入口来源、时间戳）和派生字段（数据长度、段落数、语言类型）。稳定字段直接采集，派生字段按需计算但缓存起来。派生字段的计算要幂等，因为不同模式可能都会读它。
提示：上下文里不要放可变对象引用。我踩过一次坑，某个模式在 transform 里修改了上下文里的一个 list，导致后续模式读到的上下文被污染，排查了大半天。后来改成上下文只读，需要修改就 copy 一份。
4. 真实场景里的模式设计：三个可复用的落地案例
4.1 文本截断场景：首尾保留、句子边界与轮次成对
回到开头提到的文本截断。我把它拆成三个模式：
- HeadTailMode：保留前 N 个字符和后 M 个字符，中间用省略标记。适用于摘要预览。
- SentenceBoundaryMode：按句子边界截断，保证不切断句子。适用于需要语义完整的场景。
- TurnPairMode：按对话轮次成对保留，保证 user/assistant 成对出现。适用于对话历史压缩。
这三个模式的accepts逻辑分别是：HeadTailMode 接受任何上下文但优先级最低；SentenceBoundaryMode 要求上下文里有has_sentence_boundary=True；TurnPairMode 要求上下文里有is_dialog=True且turn_count已知。
实测下来，这套设计最大的好处是新增场景时不用改调用方。后来产品要加一个“按段落截断”的需求，我只加了一个 ParagraphMode，把它插到优先级列表的合适位置，调用方一行代码没动。
4.2 日志采样场景：按级别、按频率、按关键路径
日志采样是另一个典型的多上下文场景。同一个“采样”动作，在错误日志上要全量保留，在调试日志上要按频率采样，在关键路径日志上要按 trace 关联采样。这三个需求对应三个模式：
| 模式 | 触发上下文 | 采样策略 | 输出特征 |
|---|---|---|---|
| ErrorFullMode | level >= ERROR | 全量保留 | 不丢任何一条 |
| FrequencyMode | level == DEBUG | 每 N 条保留 1 条 | 均匀稀疏 |
| TraceAwareMode | 有 trace_id | 同 trace 全保留或全丢弃 | 链路完整 |
这里的关键是 TraceAwareMode 的accepts要检查 trace_id 是否存在，而 FrequencyMode 要检查采样率配置是否加载。如果配置没加载就选 FrequencyMode，会退化成全量，反而失去采样意义。所以我在accepts里加了一条：sampling_rate is not None。
4.3 配置合并场景：默认值、环境覆盖与用户自定义
配置合并是 context-mode 思路的另一个好落点。同一个配置项，来源可能是默认值、环境变量、用户配置文件、命令行参数。合并顺序不同，结果就不同。我把它设计成模式链：
- DefaultMode：加载内置默认值。
- EnvOverrideMode：用环境变量覆盖。
- UserConfigMode：用用户配置覆盖。
- CliOverrideMode：用命令行参数覆盖。
每个模式的transform都是“在当前结果上叠加自己的层”，accepts则检查对应来源是否存在。这样合并逻辑就是一条链，顺序即优先级，非常直观。而且新增来源（比如远程配置中心）只需要加一个模式，插到链的合适位置即可。
5. 踩坑记录：那些让 context-mode 从优雅变灾难的细节
5.1 模式爆炸：当模式数量超过维护能力
我见过一个项目，context-mode 设计得很“优雅”，结果模式数量膨胀到四十多个，每个模式只处理一种极窄的场景。最后没人敢改，因为改一个模式不知道会影响哪些调用方。这是典型的过度设计。
我的经验是：模式数量控制在 5 到 8 个之间，超过就说明抽象层次有问题。如果确实有很多细分场景，应该用“模式 + 参数”的方式，而不是“一个场景一个模式”。比如截断场景，不要为“保留前 100 字”“保留前 200 字”各建一个模式，而是建一个 HeadTailMode，把 N 和 M 作为参数传入。
5.2 上下文缺失时的静默降级
静默降级是另一个大坑。当上下文缺少某个字段时，模式选择器如果直接跳过该模式、选下一个，调用方完全感知不到。结果就是：你以为在用 SentenceBoundaryMode，实际上因为has_sentence_boundary没采集到，悄悄降级到了 HeadTailMode，输出质量下降但没人发现。
我的做法是：降级必须留痕。每次发生降级，都往上下文里写一条degraded_from记录，并在日志里打 warn。这样后续排查时能一眼看出“这次输出质量差是因为降级了”。
5.3 模式之间的隐式依赖
模式之间如果有隐式依赖，会非常难排查。比如 TurnPairMode 依赖上下文里的turn_count，而turn_count是另一个模式在 transform 时算出来的。这就形成了隐式依赖：如果那个模式没先执行，TurnPairMode 就会拿到 None。
解决办法是：所有派生字段在上下文采集阶段就算好，不要留到模式执行时算。模式之间应该只共享上下文，不共享中间状态。如果实在需要共享，就显式声明依赖，并在选择器里做拓扑排序。
5.4 测试策略：每个模式独立测，组合场景抽样测
测试上我建议分两层：每个模式独立单元测试，覆盖 accepts/transform/validate 的正常和边界情况；组合场景用抽样测试，随机生成上下文，验证选择器选出的模式符合预期。第二层测试能抓到很多“单个模式没问题但组合起来选错”的 bug。
注意：组合测试的随机种子要固定，否则每次跑结果不一样，没法复现。我一般会把种子和上下文一起打进日志。
6. 性能与可观测性：让 context-mode 在生产环境可运维
6.1 模式选择的耗时控制
模式选择本身应该是轻量操作。如果accepts里做了重计算，整个请求的延迟会被拖累。我的做法是：accepts只做字段存在性和简单比较，复杂判断放到transform里。实测下来，8 个模式的选择耗时在微秒级，完全可以忽略。
如果模式数量确实多，可以用索引优化：按上下文的关键字段建倒排索引，先缩小候选集再遍历。但这是模式超过 20 个才需要考虑的优化，大多数项目用不上。
6.2 埋点：记录选中模式、降级次数、输出校验结果
生产环境里，context-mode 的可观测性至少要有三个指标：
- 模式分布：每个模式被选中的次数，用来发现“某个模式从来没被选中”这种死代码。
- 降级次数：降级发生的频率，用来发现上下文采集缺失。
- 校验失败率：
validate返回 False 的比例，用来发现模式实现有 bug。
这三个指标我一般用计数器实现，定期上报。有一次就是靠“降级次数突增”发现上游改了数据格式，导致某个上下文字段采集不到。
6.3 灰度与回滚：新模式上线怎么保证安全
新模式上线最怕的是“一上线就全量生效，出问题影响所有请求”。我的做法是：新模式先以低优先级插入，只对特定上下文生效；观察一段时间后，再逐步提高优先级。回滚时只需要把优先级调回去，不用改代码。
具体实现可以在选择器里加一个“模式权重”配置，权重为 0 的模式直接跳过。这样灰度就是改配置，回滚也是改配置，非常灵活。
7. 从 context-mode 延伸出去：这套思路还能用在哪
context-mode 的本质是“把场景差异收敛成可命名的模式”，这个思路的适用范围远不止文本处理和日志采样。我在几个不同类型的项目里都用过类似的设计：
- API 版本兼容：不同版本的请求走不同的兼容模式，新版本逻辑不变，老版本走兼容层。
- 多租户配置：不同租户走不同的配额和限流模式，租户上下文决定模式选择。
- 数据导出：不同导出格式走不同的序列化模式，格式上下文决定模式。
- 告警降噪：不同告警级别走不同的聚合模式，级别上下文决定聚合窗口。
这些场景的共同点是：同一份核心逻辑，在不同上下文下需要不同的外围行为。只要符合这个特征，context-mode 的思路就能用上。
最后分享一个我在实际项目里总结的小技巧：模式命名用“场景 + 行为”的格式，不要用“模式 A”“模式 B”。比如DialogTurnPairMode比Mode3好得多，因为半年后你回来看代码，光看名字就知道它是干什么的。命名这件事，在模式数量少的时候看不出价值，一旦超过五个，好名字能省下大量翻代码的时间。
这套机制我从第一次实现到现在，前后迭代了三四版，最大的体会是：不要一开始就追求完美抽象。先把最痛的那个场景抽出来，跑通，再逐步把其他场景往里收。一上来就设计一个大而全的模式体系，大概率会过度设计，最后维护不动。小步迭代，让模式数量随着真实需求增长，才是可持续的做法。
