1. 从“上下文模式”这个命名说起它到底在解决什么问题第一次看到“context-mode”这个词很多人会下意识觉得它是个抽象概念甚至怀疑它是不是又一个被过度包装的技术名词。但如果你真正在工程一线待过尤其是在做对话系统、状态机、或者任何需要“记住当前处境”的模块时就会明白这个词背后藏着一个非常具体、非常痛的工程问题同一段逻辑在不同上下文里应该表现出不同的行为而传统写法往往把上下文判断散落在代码各处最后变成一团乱麻。我最早接触类似概念是在做一个多轮交互的客服机器人项目时。当时的需求听起来很简单用户说“我要退货”机器人要追问订单号用户说“查一下物流”机器人要直接给轨迹。但真正写起来代码里到处都是if (state returning)、if (lastIntent logistics)这样的判断。每加一个场景就要在十几个地方补条件分支改一处漏三处测试用例越写越像天书。后来团队里有人提出能不能把“当前处于什么模式”这件事抽出来让业务逻辑只关心“在这个模式下该做什么”而不是“现在是不是这个模式”。这就是 context-mode 这个思路的起点。所以这篇内容我想把 context-mode 当作一个工程模式来拆解而不是某个具体框架的 API 说明。它适合谁看如果你正在做以下任何一件事这篇都值得你花时间写对话系统、工作流引擎、游戏 AI 状态管理发现条件判断越写越乱做前端页面同一个组件在“编辑态”“预览态”“只读态”下行为差异大靠 props 传得满天飞设计后端服务同一套接口在不同租户、不同权限、不同业务阶段下要走不同分支或者你只是单纯好奇为什么有些项目的代码读起来像流水账有些却像一份清晰的说明书。我会从核心原理、模式设计、落地步骤、踩坑经验几个角度展开尽量把“为什么这么设计”讲透而不是只丢一堆代码。文中涉及的具体实现我会用通用伪代码和 TypeScript 风格示例你可以直接映射到自己熟悉的语言里。提示context-mode 不是某个库的专利它是一种组织代码的思维方式。你可以用类、用闭包、用状态机、用策略模式去实现它重点在于“把上下文判断收敛到一处把行为差异暴露成显式契约”。2. 拆开 context-mode 的内核上下文、模式、以及两者如何绑定2.1 上下文不是“全局变量”而是一份可追溯的快照很多人一听到“上下文”第一反应是搞一个全局对象哪里需要哪里读。这是最容易踩的坑。全局可变状态会让调试变成噩梦你永远不知道是谁在什么时候改了它。context-mode 里的“上下文”更准确的定位是一份在特定时刻被冻结的快照它描述的是“当前这次交互所处的环境”。这份快照里通常包含几类信息信息类别典型内容作用会话标识sessionId、用户标识区分不同交互主体历史轨迹最近若干轮意图、关键实体决定当前该进入哪个模式环境约束权限等级、租户配置、设备类型限制可用行为范围业务阶段订单状态、流程节点驱动模式切换临时标记是否已确认、是否超时处理边界情况关键在于这份快照应该是只读的。模式切换时由专门的“上下文管理器”生成新快照而不是在原对象上改来改去。这样做的好处是任何一次行为异常你都可以把当时的快照打印出来完整复现问题现场。我在实际项目里养成了一个习惯每个模式处理函数的入口第一件事就是把上下文快照的摘要打到日志里。后来线上出问题排查时间从平均两小时降到了二十分钟。2.2 模式是“行为契约”不是简单的枚举值另一个常见误解是把模式当成一个字符串枚举mode editing | preview。枚举本身没错但如果模式只停留在枚举层面业务代码里还是会出现大量switch (mode)那和之前的 if-else 没有本质区别。context-mode 里的“模式”应该被定义成一份行为契约。也就是说每个模式明确声明在这个模式下哪些操作是允许的、哪些是禁止的、每个操作的具体实现是什么。用 TypeScript 的接口来描述大概是这样interface ContextMode { name: string; canHandle(action: Action, ctx: ContextSnapshot): boolean; handle(action: Action, ctx: ContextSnapshot): Result; onEnter?(ctx: ContextSnapshot): void; onExit?(ctx: ContextSnapshot): void; }这样一来新增一个模式就是新增一个实现类而不是在原有代码里到处插分支。这符合开闭原则对扩展开放对修改关闭。我见过一个团队把退货流程从三种模式扩展到七种因为一开始就用了这种契约式设计扩展时只加了四个文件核心调度代码一行没动。2.3 绑定关系谁来决定“当前该用哪个模式”上下文和模式都定义好了接下来最关键的问题是谁来负责根据上下文选择模式这个角色叫“模式解析器”或“调度器”。它的职责非常单一读取上下文快照按优先级依次询问每个模式“你能不能处理当前情况”第一个返回 true 的模式胜出。这里有个设计细节值得展开优先级顺序怎么定我的经验是越具体、越受限的模式优先级越高。比如“退货-等待订单号”模式比“通用问答”模式更具体就应该排在前面。如果反过来通用模式先匹配上了具体模式永远没机会执行。这个顺序通常写在一个配置数组里而不是硬编码在逻辑中方便调整和测试。const modeRegistry: ContextMode[] [ new ReturnAwaitingOrderMode(), // 最具体 new ReturnConfirmMode(), new LogisticsQueryMode(), new GeneralChatMode(), // 兜底 ]; function resolveMode(ctx: ContextSnapshot): ContextMode { for (const mode of modeRegistry) { if (mode.canHandle(ctx.currentAction, ctx)) { return mode; } } return fallbackMode; }这段代码看起来简单但它把“模式选择”这件事从业务逻辑里彻底剥离了。业务开发者只需要关心“我这个模式内部怎么处理”不需要关心“什么时候会轮到我”。这种关注点分离是 context-mode 最核心的价值。3. 落地一套 context-mode从目录结构到状态流转的完整实操3.1 目录怎么组织让模式自己“住”在自己的文件夹里很多项目失败不是因为思路不对而是因为文件组织混乱导致后来的人根本找不到某个模式的定义在哪。我推荐的做法是每个模式一个独立目录目录里放这个模式的处理逻辑、测试、以及它自己的局部配置。src/ context/ snapshot.ts // 上下文快照类型与创建函数 resolver.ts // 模式解析器 registry.ts // 模式注册表 modes/ return-awaiting-order/ index.ts // 模式实现 handler.ts // 具体业务处理 handler.test.ts // 单元测试 config.ts // 该模式的局部配置 logistics-query/ index.ts handler.ts handler.test.ts general-chat/ index.ts handler.ts这样组织的好处非常明显当你要修改“退货等待订单号”这个模式时所有相关代码都在一个文件夹里不会误伤其他模式。测试也可以按模式独立运行CI 里可以只跑受影响模式的测试加快反馈速度。我在一个中型项目里推行这套结构后新成员上手时间从一周缩短到两天因为他们只需要看懂自己负责的那一个模式文件夹。3.2 上下文快照的创建入口处一次性完成上下文快照应该在请求进入系统的最外层创建而不是在每个模式内部临时拼凑。具体来说在 HTTP 请求进入、消息队列消费、或者前端路由切换时由统一的“上下文构建器”生成快照。function buildSnapshot(input: RawInput, history: HistoryStore): ContextSnapshot { const recentIntents history.getRecentIntents(input.sessionId, 5); const entities extractEntities(input.text); const permissions permissionService.get(input.userId); return Object.freeze({ sessionId: input.sessionId, userId: input.userId, currentAction: { type: input.actionType, payload: input.payload }, recentIntents, entities, permissions, timestamp: Date.now(), }); }注意Object.freeze这一行。它强制快照不可变任何试图修改的操作都会在开发阶段就报错而不是等到线上出现诡异 bug 才发现。这个习惯我强烈建议你养成成本极低收益极高。3.3 模式切换的触发时机显式声明不要隐式跳转模式之间怎么切换最忌讳的是在模式 A 的处理函数里直接new ModeB()然后调用。这样模式之间形成硬依赖画出来的依赖图是一团乱麻。正确做法是模式处理函数只返回一个“切换意图”由调度器统一执行切换。interface ModeResult { output: string; nextModeHint?: string; // 建议切换到哪个模式 nextContextPatch?: PartialContextSnapshot; // 需要更新的上下文字段 } function dispatch(action: Action, ctx: ContextSnapshot): ModeResult { const mode resolveMode(ctx); const result mode.handle(action, ctx); if (result.nextModeHint) { const newCtx applyPatch(ctx, result.nextContextPatch); return dispatch(action, newCtx); // 或者交给外层循环处理 } return result; }这种“返回意图、统一调度”的方式让模式切换路径变得可追踪。你可以在调度器里加日志记录每一次切换的 from、to、原因形成一条完整的流转链路。线上排查“为什么用户被带到了错误模式”时这条链路就是救命稻草。3.4 一个完整的最小示例退货流程的三段模式为了让你有直观感受我用退货流程串一遍。假设有三个模式ReturnAskOrder询问订单号、ReturnConfirm确认退货、ReturnDone完成。class ReturnAskOrder implements ContextMode { name return-ask-order; canHandle(action: Action, ctx: ContextSnapshot) { return ctx.recentIntents.includes(return) !ctx.entities.orderId; } handle(action: Action, ctx: ContextSnapshot): ModeResult { const orderId extractOrderId(action.payload.text); if (!orderId) { return { output: 请提供您的订单号格式如 OD123456。 }; } return { output: 确认对订单 ${orderId} 发起退货吗, nextModeHint: return-confirm, nextContextPatch: { entities: { ...ctx.entities, orderId } }, }; } }ReturnConfirm模式收到“是”就进入ReturnDone收到“否”就回到ReturnAskOrder并清空订单号。整个流程里没有任何一处写if (mode xxx)每个模式只关心自己的输入输出。新增一个“退货原因收集”模式只需要在ReturnConfirm和ReturnDone之间插入改一处nextModeHint即可。4. 那些文档不会告诉你的坑context-mode 实战避坑清单4.1 坑一上下文快照越做越大最后变成“什么都有”刚开始用 context-mode 时很容易产生一种冲动既然快照是统一入口那我把所有可能需要的数据都塞进去吧。结果快照膨胀到几十个字段创建一次要查五张表性能急剧下降而且大部分字段在大部分模式下根本用不到。我的经验是快照只放“决定模式选择”和“模式切换时需要传递”的最小集合。具体业务数据由模式内部按需去查。比如订单详情不需要放进快照模式处理时用订单号查一次即可。判断标准很简单如果某个字段只在一个模式里用到它就不该进快照。4.2 坑二模式优先级顺序写错导致“兜底模式”永远先命中前面提过优先级要“越具体越靠前”但实际写的时候很容易搞反。我踩过一次典型的坑把“通用问答”模式放在了数组第一位结果所有请求都被它拦截后面的退货、物流模式形同虚设。更麻烦的是通用模式也能给出看似合理的回答所以测试时没发现异常上线后才发现业务逻辑根本没走到。排查这类问题的方法在解析器里加一行调试日志打印“本次命中模式名”和“被跳过的模式名列表”。如果发现某个模式从未出现在命中记录里就要检查它的canHandle条件是否被前面的模式覆盖了。4.3 坑三模式内部直接修改上下文破坏不可变性虽然快照用了Object.freeze但嵌套对象如果没冻结还是能被改。比如ctx.entities.orderId xxx这种操作在浅冻结下不会报错但会污染快照导致后续模式读到脏数据。解决方案是深冻结或者干脆约定模式内部永远不修改ctx需要变更就通过nextContextPatch返回。我后来在团队里定了一条硬规矩代码评审时看到任何对ctx.的赋值操作直接打回。配合 ESLint 规则禁止对参数重新赋值基本杜绝了这类问题。4.4 坑四模式切换形成死循环模式 A 建议切到 BB 又建议切回 A如果没有终止条件调度器就会无限循环。这种情况在“确认-取消-再确认”这类交互里特别容易出现。防御手段有两个一是调度器设置最大切换次数比如 5 次超过就强制进入兜底模式并记录告警二是每个模式在返回nextModeHint时必须同时返回一个“切换理由”调度器检查理由是否与上一次相同相同则拒绝切换。const MAX_SWITCH 5; let switchCount 0; let lastReason ; while (result.nextModeHint switchCount MAX_SWITCH) { if (result.switchReason lastReason) { logger.warn(检测到重复切换理由终止循环); break; } lastReason result.switchReason; // ... 执行切换 switchCount; }4.5 坑五测试只测单个模式不测切换链路单元测试覆盖每个模式的handle很容易但真正出问题的地方往往是模式之间的衔接。比如 A 模式输出的nextContextPatch字段名写错B 模式读不到导致行为异常。这类问题单测发现不了。我的做法是为每条主要业务流程写“链路测试”从初始上下文开始模拟一系列用户输入断言最终输出和经过的模式序列。这种测试写起来稍麻烦但一旦有了重构模式时信心会强很多。下面是一个链路测试的示意test(退货流程完整链路, () { let ctx buildSnapshot({ text: 我要退货, sessionId: s1 }, emptyHistory); const visited: string[] []; let output ; for (const input of [我要退货, OD123456, 是]) { const mode resolveMode(ctx); visited.push(mode.name); const result mode.handle({ type: text, payload: { text: input } }, ctx); output result.output; ctx applyPatch(ctx, result.nextContextPatch); } expect(visited).toEqual([return-ask-order, return-confirm, return-done]); expect(output).toContain(退货成功); });5. 把 context-mode 用对地方适用边界与替代方案对比5.1 什么时候该用什么时候不该用context-mode 不是银弹。它最适合的场景是行为分支多、分支之间有明显状态流转、且分支逻辑相对独立。典型如对话系统、工作流引擎、表单多步骤填写、游戏 AI 行为树。但如果你的场景只是简单的两三个 if-else比如“用户是否登录”决定显示不同按钮那引入 context-mode 就是过度设计。判断标准当你发现同一个条件判断在超过三个地方重复出现或者新增一个分支需要改动超过五个文件时才值得考虑引入。另外如果分支之间共享大量逻辑只是少量差异那用策略模式或简单的参数化配置可能更轻量。context-mode 的代价是每个模式都要写一套完整的契约实现模式数量多时文件数会膨胀。我一般建议模式数量控制在 15 个以内超过就要考虑分层或合并。5.2 和状态机、策略模式、责任链的区别很多人会问这不就是状态机吗确实有重叠但侧重点不同。状态机强调“状态之间的转移条件”通常转移逻辑集中在一张转移表里context-mode 强调“每个模式自己的行为封装”转移只是模式处理的一个副产品。状态机适合状态少、转移规则明确的场景context-mode 适合状态多、每个状态内部逻辑复杂的场景。和策略模式相比策略模式通常是一次性选择策略后不再切换而 context-mode 的核心是动态切换。和责任链相比责任链是依次尝试直到某个处理器接手context-mode 是解析出唯一模式后由它全权处理。三者可以结合使用比如在某个模式内部再用策略模式处理子分支。方案核心关注点适合场景切换能力状态机状态转移条件状态少、规则明确强集中管理策略模式算法可替换一次性选择弱通常不切换责任链依次尝试处理过滤器、审批流中单向传递context-mode模式行为封装分支多、逻辑复杂强动态解析5.3 性能考量解析器的开销可以忽略吗模式解析器每次都要遍历模式列表调用每个模式的canHandle。如果模式有几十个且canHandle里有复杂计算确实可能成为瓶颈。优化手段有两个一是给模式打标签先用标签做粗筛再在候选集里细判二是缓存解析结果如果上下文快照的关键字段没变直接复用上次的模式选择。不过根据我的实测在模式数量少于 20 个、canHandle只做简单字段判断的情况下解析耗时通常在微秒级相对于一次网络请求或数据库查询完全可以忽略。不要过早优化先把结构理清楚真遇到性能问题再针对性处理。6. 从能跑到好用几个让 context-mode 更稳的工程习惯6.1 给每个模式加“自描述”让日志会说话每个模式实现里加一个describe()方法返回这个模式的用途、进入条件、退出条件的简短说明。调度器在每次命中模式时把这段描述打进日志。这样线上日志读起来就像一份流程说明而不是一堆类名。describe() { return 退货-询问订单号当用户表达退货意图但未提供订单号时进入提供有效订单号后切换到确认模式。; }这个习惯看起来不起眼但在跨团队协作时价值巨大。运维同学看日志就能大致判断流程走到哪一步不需要每次都拉开发来解读。6.2 用配置驱动模式注册而不是硬编码数组模式注册表如果写死在代码里每次增删模式都要改代码、重新编译。更好的做法是用配置文件声明模式列表和优先级代码启动时读取配置动态注册。这样调整优先级、临时禁用某个模式都不需要发版。modes: - name: return-ask-order enabled: true priority: 10 - name: return-confirm enabled: true priority: 20 - name: general-chat enabled: true priority: 999注意优先级数字越小越靠前。把兜底模式设成 999新增模式只要给个中间值就能插进去不用动其他配置。6.3 为模式切换埋点用数据驱动优化每次模式切换都上报一条埋点from、to、触发动作、耗时。积累一段时间后你可以分析出哪些切换路径最频繁、哪些模式几乎没被用到、哪些切换耗时异常。这些数据是优化流程的直接依据。我曾经通过埋点发现某个确认模式有 30% 的请求在超时后重复进入后来加了幂等判断问题迎刃而解。6.4 版本化上下文快照结构上下文快照的字段会随着业务演进而变化。如果快照被持久化比如存到数据库用于恢复会话字段变更就会带来兼容问题。建议给快照加一个version字段读取旧版本快照时走迁移函数升级到当前版本。这个习惯在需要断点续传或异步处理的场景里尤其重要。function migrateSnapshot(raw: any): ContextSnapshot { if (raw.version 1) { raw.entities raw.entities || {}; raw.version 2; } return raw as ContextSnapshot; }7. 一个真实项目的演进记录从 if-else 泥潭到模式化重构最后分享一段我亲身经历的重构过程希望能给你一些参考。项目是一个内部工单系统最初所有状态判断都堆在一个两千行的handleMessage函数里。每次加一种工单类型就要在那个函数里加分支代码评审时没人愿意看测试覆盖率长期低于 40%。重构分三步走。第一步先把所有if (state xxx)的分支抽成独立函数函数签名统一为(action, ctx) result这一步不改变行为只是物理拆分。第二步定义ContextMode接口把抽出来的函数包装成模式类实现canHandle和handle。第三步引入解析器和注册表删掉原来的大函数改为调度器驱动。整个过程持续了三周期间系统一直保持可发布状态。重构后最直观的变化新增一种工单类型从平均改动 8 个文件降到 2 个文件新建模式目录 注册配置代码评审时间从半天降到一小时线上因状态判断错误导致的工单从每月十几起降到零。当然代价也有文件数量增加了新人需要先理解模式契约才能上手。但综合来看收益远大于成本。如果你正在犹豫要不要做类似重构我的建议是先别急着全量改。挑一个分支最多、最常出问题的流程做试点跑通后再逐步推广。context-mode 的价值不在于它多高深而在于它把混乱的隐式判断变成了显式的、可测试的、可追踪的结构。这一点在项目规模变大之后会越来越明显。 
长河君 · 2026/10/20 19:39:45 · 阅读 1.2k context-mode工程模式：从if-else泥潭到可维护的状态管理
1. 从“上下文模式”这个命名说起它到底在解决什么问题第一次看到“context-mode”这个词很多人会下意识觉得它是个抽象概念甚至怀疑它是不是又一个被过度包装的技术名词。但如果你真正在工程一线待过尤其是在做对话系统、状态机、或者任何需要“记住当前处境”的模块时就会明白这个词背后藏着一个非常具体、非常痛的工程问题同一段逻辑在不同上下文里应该表现出不同的行为而传统写法往往把上下文判断散落在代码各处最后变成一团乱麻。我最早接触类似概念是在做一个多轮交互的客服机器人项目时。当时的需求听起来很简单用户说“我要退货”机器人要追问订单号用户说“查一下物流”机器人要直接给轨迹。但真正写起来代码里到处都是if (state returning)、if (lastIntent logistics)这样的判断。每加一个场景就要在十几个地方补条件分支改一处漏三处测试用例越写越像天书。后来团队里有人提出能不能把“当前处于什么模式”这件事抽出来让业务逻辑只关心“在这个模式下该做什么”而不是“现在是不是这个模式”。这就是 context-mode 这个思路的起点。所以这篇内容我想把 context-mode 当作一个工程模式来拆解而不是某个具体框架的 API 说明。它适合谁看如果你正在做以下任何一件事这篇都值得你花时间写对话系统、工作流引擎、游戏 AI 状态管理发现条件判断越写越乱做前端页面同一个组件在“编辑态”“预览态”“只读态”下行为差异大靠 props 传得满天飞设计后端服务同一套接口在不同租户、不同权限、不同业务阶段下要走不同分支或者你只是单纯好奇为什么有些项目的代码读起来像流水账有些却像一份清晰的说明书。我会从核心原理、模式设计、落地步骤、踩坑经验几个角度展开尽量把“为什么这么设计”讲透而不是只丢一堆代码。文中涉及的具体实现我会用通用伪代码和 TypeScript 风格示例你可以直接映射到自己熟悉的语言里。提示context-mode 不是某个库的专利它是一种组织代码的思维方式。你可以用类、用闭包、用状态机、用策略模式去实现它重点在于“把上下文判断收敛到一处把行为差异暴露成显式契约”。2. 拆开 context-mode 的内核上下文、模式、以及两者如何绑定2.1 上下文不是“全局变量”而是一份可追溯的快照很多人一听到“上下文”第一反应是搞一个全局对象哪里需要哪里读。这是最容易踩的坑。全局可变状态会让调试变成噩梦你永远不知道是谁在什么时候改了它。context-mode 里的“上下文”更准确的定位是一份在特定时刻被冻结的快照它描述的是“当前这次交互所处的环境”。这份快照里通常包含几类信息信息类别典型内容作用会话标识sessionId、用户标识区分不同交互主体历史轨迹最近若干轮意图、关键实体决定当前该进入哪个模式环境约束权限等级、租户配置、设备类型限制可用行为范围业务阶段订单状态、流程节点驱动模式切换临时标记是否已确认、是否超时处理边界情况关键在于这份快照应该是只读的。模式切换时由专门的“上下文管理器”生成新快照而不是在原对象上改来改去。这样做的好处是任何一次行为异常你都可以把当时的快照打印出来完整复现问题现场。我在实际项目里养成了一个习惯每个模式处理函数的入口第一件事就是把上下文快照的摘要打到日志里。后来线上出问题排查时间从平均两小时降到了二十分钟。2.2 模式是“行为契约”不是简单的枚举值另一个常见误解是把模式当成一个字符串枚举mode editing | preview。枚举本身没错但如果模式只停留在枚举层面业务代码里还是会出现大量switch (mode)那和之前的 if-else 没有本质区别。context-mode 里的“模式”应该被定义成一份行为契约。也就是说每个模式明确声明在这个模式下哪些操作是允许的、哪些是禁止的、每个操作的具体实现是什么。用 TypeScript 的接口来描述大概是这样interface ContextMode { name: string; canHandle(action: Action, ctx: ContextSnapshot): boolean; handle(action: Action, ctx: ContextSnapshot): Result; onEnter?(ctx: ContextSnapshot): void; onExit?(ctx: ContextSnapshot): void; }这样一来新增一个模式就是新增一个实现类而不是在原有代码里到处插分支。这符合开闭原则对扩展开放对修改关闭。我见过一个团队把退货流程从三种模式扩展到七种因为一开始就用了这种契约式设计扩展时只加了四个文件核心调度代码一行没动。2.3 绑定关系谁来决定“当前该用哪个模式”上下文和模式都定义好了接下来最关键的问题是谁来负责根据上下文选择模式这个角色叫“模式解析器”或“调度器”。它的职责非常单一读取上下文快照按优先级依次询问每个模式“你能不能处理当前情况”第一个返回 true 的模式胜出。这里有个设计细节值得展开优先级顺序怎么定我的经验是越具体、越受限的模式优先级越高。比如“退货-等待订单号”模式比“通用问答”模式更具体就应该排在前面。如果反过来通用模式先匹配上了具体模式永远没机会执行。这个顺序通常写在一个配置数组里而不是硬编码在逻辑中方便调整和测试。const modeRegistry: ContextMode[] [ new ReturnAwaitingOrderMode(), // 最具体 new ReturnConfirmMode(), new LogisticsQueryMode(), new GeneralChatMode(), // 兜底 ]; function resolveMode(ctx: ContextSnapshot): ContextMode { for (const mode of modeRegistry) { if (mode.canHandle(ctx.currentAction, ctx)) { return mode; } } return fallbackMode; }这段代码看起来简单但它把“模式选择”这件事从业务逻辑里彻底剥离了。业务开发者只需要关心“我这个模式内部怎么处理”不需要关心“什么时候会轮到我”。这种关注点分离是 context-mode 最核心的价值。3. 落地一套 context-mode从目录结构到状态流转的完整实操3.1 目录怎么组织让模式自己“住”在自己的文件夹里很多项目失败不是因为思路不对而是因为文件组织混乱导致后来的人根本找不到某个模式的定义在哪。我推荐的做法是每个模式一个独立目录目录里放这个模式的处理逻辑、测试、以及它自己的局部配置。src/ context/ snapshot.ts // 上下文快照类型与创建函数 resolver.ts // 模式解析器 registry.ts // 模式注册表 modes/ return-awaiting-order/ index.ts // 模式实现 handler.ts // 具体业务处理 handler.test.ts // 单元测试 config.ts // 该模式的局部配置 logistics-query/ index.ts handler.ts handler.test.ts general-chat/ index.ts handler.ts这样组织的好处非常明显当你要修改“退货等待订单号”这个模式时所有相关代码都在一个文件夹里不会误伤其他模式。测试也可以按模式独立运行CI 里可以只跑受影响模式的测试加快反馈速度。我在一个中型项目里推行这套结构后新成员上手时间从一周缩短到两天因为他们只需要看懂自己负责的那一个模式文件夹。3.2 上下文快照的创建入口处一次性完成上下文快照应该在请求进入系统的最外层创建而不是在每个模式内部临时拼凑。具体来说在 HTTP 请求进入、消息队列消费、或者前端路由切换时由统一的“上下文构建器”生成快照。function buildSnapshot(input: RawInput, history: HistoryStore): ContextSnapshot { const recentIntents history.getRecentIntents(input.sessionId, 5); const entities extractEntities(input.text); const permissions permissionService.get(input.userId); return Object.freeze({ sessionId: input.sessionId, userId: input.userId, currentAction: { type: input.actionType, payload: input.payload }, recentIntents, entities, permissions, timestamp: Date.now(), }); }注意Object.freeze这一行。它强制快照不可变任何试图修改的操作都会在开发阶段就报错而不是等到线上出现诡异 bug 才发现。这个习惯我强烈建议你养成成本极低收益极高。3.3 模式切换的触发时机显式声明不要隐式跳转模式之间怎么切换最忌讳的是在模式 A 的处理函数里直接new ModeB()然后调用。这样模式之间形成硬依赖画出来的依赖图是一团乱麻。正确做法是模式处理函数只返回一个“切换意图”由调度器统一执行切换。interface ModeResult { output: string; nextModeHint?: string; // 建议切换到哪个模式 nextContextPatch?: PartialContextSnapshot; // 需要更新的上下文字段 } function dispatch(action: Action, ctx: ContextSnapshot): ModeResult { const mode resolveMode(ctx); const result mode.handle(action, ctx); if (result.nextModeHint) { const newCtx applyPatch(ctx, result.nextContextPatch); return dispatch(action, newCtx); // 或者交给外层循环处理 } return result; }这种“返回意图、统一调度”的方式让模式切换路径变得可追踪。你可以在调度器里加日志记录每一次切换的 from、to、原因形成一条完整的流转链路。线上排查“为什么用户被带到了错误模式”时这条链路就是救命稻草。3.4 一个完整的最小示例退货流程的三段模式为了让你有直观感受我用退货流程串一遍。假设有三个模式ReturnAskOrder询问订单号、ReturnConfirm确认退货、ReturnDone完成。class ReturnAskOrder implements ContextMode { name return-ask-order; canHandle(action: Action, ctx: ContextSnapshot) { return ctx.recentIntents.includes(return) !ctx.entities.orderId; } handle(action: Action, ctx: ContextSnapshot): ModeResult { const orderId extractOrderId(action.payload.text); if (!orderId) { return { output: 请提供您的订单号格式如 OD123456。 }; } return { output: 确认对订单 ${orderId} 发起退货吗, nextModeHint: return-confirm, nextContextPatch: { entities: { ...ctx.entities, orderId } }, }; } }ReturnConfirm模式收到“是”就进入ReturnDone收到“否”就回到ReturnAskOrder并清空订单号。整个流程里没有任何一处写if (mode xxx)每个模式只关心自己的输入输出。新增一个“退货原因收集”模式只需要在ReturnConfirm和ReturnDone之间插入改一处nextModeHint即可。4. 那些文档不会告诉你的坑context-mode 实战避坑清单4.1 坑一上下文快照越做越大最后变成“什么都有”刚开始用 context-mode 时很容易产生一种冲动既然快照是统一入口那我把所有可能需要的数据都塞进去吧。结果快照膨胀到几十个字段创建一次要查五张表性能急剧下降而且大部分字段在大部分模式下根本用不到。我的经验是快照只放“决定模式选择”和“模式切换时需要传递”的最小集合。具体业务数据由模式内部按需去查。比如订单详情不需要放进快照模式处理时用订单号查一次即可。判断标准很简单如果某个字段只在一个模式里用到它就不该进快照。4.2 坑二模式优先级顺序写错导致“兜底模式”永远先命中前面提过优先级要“越具体越靠前”但实际写的时候很容易搞反。我踩过一次典型的坑把“通用问答”模式放在了数组第一位结果所有请求都被它拦截后面的退货、物流模式形同虚设。更麻烦的是通用模式也能给出看似合理的回答所以测试时没发现异常上线后才发现业务逻辑根本没走到。排查这类问题的方法在解析器里加一行调试日志打印“本次命中模式名”和“被跳过的模式名列表”。如果发现某个模式从未出现在命中记录里就要检查它的canHandle条件是否被前面的模式覆盖了。4.3 坑三模式内部直接修改上下文破坏不可变性虽然快照用了Object.freeze但嵌套对象如果没冻结还是能被改。比如ctx.entities.orderId xxx这种操作在浅冻结下不会报错但会污染快照导致后续模式读到脏数据。解决方案是深冻结或者干脆约定模式内部永远不修改ctx需要变更就通过nextContextPatch返回。我后来在团队里定了一条硬规矩代码评审时看到任何对ctx.的赋值操作直接打回。配合 ESLint 规则禁止对参数重新赋值基本杜绝了这类问题。4.4 坑四模式切换形成死循环模式 A 建议切到 BB 又建议切回 A如果没有终止条件调度器就会无限循环。这种情况在“确认-取消-再确认”这类交互里特别容易出现。防御手段有两个一是调度器设置最大切换次数比如 5 次超过就强制进入兜底模式并记录告警二是每个模式在返回nextModeHint时必须同时返回一个“切换理由”调度器检查理由是否与上一次相同相同则拒绝切换。const MAX_SWITCH 5; let switchCount 0; let lastReason ; while (result.nextModeHint switchCount MAX_SWITCH) { if (result.switchReason lastReason) { logger.warn(检测到重复切换理由终止循环); break; } lastReason result.switchReason; // ... 执行切换 switchCount; }4.5 坑五测试只测单个模式不测切换链路单元测试覆盖每个模式的handle很容易但真正出问题的地方往往是模式之间的衔接。比如 A 模式输出的nextContextPatch字段名写错B 模式读不到导致行为异常。这类问题单测发现不了。我的做法是为每条主要业务流程写“链路测试”从初始上下文开始模拟一系列用户输入断言最终输出和经过的模式序列。这种测试写起来稍麻烦但一旦有了重构模式时信心会强很多。下面是一个链路测试的示意test(退货流程完整链路, () { let ctx buildSnapshot({ text: 我要退货, sessionId: s1 }, emptyHistory); const visited: string[] []; let output ; for (const input of [我要退货, OD123456, 是]) { const mode resolveMode(ctx); visited.push(mode.name); const result mode.handle({ type: text, payload: { text: input } }, ctx); output result.output; ctx applyPatch(ctx, result.nextContextPatch); } expect(visited).toEqual([return-ask-order, return-confirm, return-done]); expect(output).toContain(退货成功); });5. 把 context-mode 用对地方适用边界与替代方案对比5.1 什么时候该用什么时候不该用context-mode 不是银弹。它最适合的场景是行为分支多、分支之间有明显状态流转、且分支逻辑相对独立。典型如对话系统、工作流引擎、表单多步骤填写、游戏 AI 行为树。但如果你的场景只是简单的两三个 if-else比如“用户是否登录”决定显示不同按钮那引入 context-mode 就是过度设计。判断标准当你发现同一个条件判断在超过三个地方重复出现或者新增一个分支需要改动超过五个文件时才值得考虑引入。另外如果分支之间共享大量逻辑只是少量差异那用策略模式或简单的参数化配置可能更轻量。context-mode 的代价是每个模式都要写一套完整的契约实现模式数量多时文件数会膨胀。我一般建议模式数量控制在 15 个以内超过就要考虑分层或合并。5.2 和状态机、策略模式、责任链的区别很多人会问这不就是状态机吗确实有重叠但侧重点不同。状态机强调“状态之间的转移条件”通常转移逻辑集中在一张转移表里context-mode 强调“每个模式自己的行为封装”转移只是模式处理的一个副产品。状态机适合状态少、转移规则明确的场景context-mode 适合状态多、每个状态内部逻辑复杂的场景。和策略模式相比策略模式通常是一次性选择策略后不再切换而 context-mode 的核心是动态切换。和责任链相比责任链是依次尝试直到某个处理器接手context-mode 是解析出唯一模式后由它全权处理。三者可以结合使用比如在某个模式内部再用策略模式处理子分支。方案核心关注点适合场景切换能力状态机状态转移条件状态少、规则明确强集中管理策略模式算法可替换一次性选择弱通常不切换责任链依次尝试处理过滤器、审批流中单向传递context-mode模式行为封装分支多、逻辑复杂强动态解析5.3 性能考量解析器的开销可以忽略吗模式解析器每次都要遍历模式列表调用每个模式的canHandle。如果模式有几十个且canHandle里有复杂计算确实可能成为瓶颈。优化手段有两个一是给模式打标签先用标签做粗筛再在候选集里细判二是缓存解析结果如果上下文快照的关键字段没变直接复用上次的模式选择。不过根据我的实测在模式数量少于 20 个、canHandle只做简单字段判断的情况下解析耗时通常在微秒级相对于一次网络请求或数据库查询完全可以忽略。不要过早优化先把结构理清楚真遇到性能问题再针对性处理。6. 从能跑到好用几个让 context-mode 更稳的工程习惯6.1 给每个模式加“自描述”让日志会说话每个模式实现里加一个describe()方法返回这个模式的用途、进入条件、退出条件的简短说明。调度器在每次命中模式时把这段描述打进日志。这样线上日志读起来就像一份流程说明而不是一堆类名。describe() { return 退货-询问订单号当用户表达退货意图但未提供订单号时进入提供有效订单号后切换到确认模式。; }这个习惯看起来不起眼但在跨团队协作时价值巨大。运维同学看日志就能大致判断流程走到哪一步不需要每次都拉开发来解读。6.2 用配置驱动模式注册而不是硬编码数组模式注册表如果写死在代码里每次增删模式都要改代码、重新编译。更好的做法是用配置文件声明模式列表和优先级代码启动时读取配置动态注册。这样调整优先级、临时禁用某个模式都不需要发版。modes: - name: return-ask-order enabled: true priority: 10 - name: return-confirm enabled: true priority: 20 - name: general-chat enabled: true priority: 999注意优先级数字越小越靠前。把兜底模式设成 999新增模式只要给个中间值就能插进去不用动其他配置。6.3 为模式切换埋点用数据驱动优化每次模式切换都上报一条埋点from、to、触发动作、耗时。积累一段时间后你可以分析出哪些切换路径最频繁、哪些模式几乎没被用到、哪些切换耗时异常。这些数据是优化流程的直接依据。我曾经通过埋点发现某个确认模式有 30% 的请求在超时后重复进入后来加了幂等判断问题迎刃而解。6.4 版本化上下文快照结构上下文快照的字段会随着业务演进而变化。如果快照被持久化比如存到数据库用于恢复会话字段变更就会带来兼容问题。建议给快照加一个version字段读取旧版本快照时走迁移函数升级到当前版本。这个习惯在需要断点续传或异步处理的场景里尤其重要。function migrateSnapshot(raw: any): ContextSnapshot { if (raw.version 1) { raw.entities raw.entities || {}; raw.version 2; } return raw as ContextSnapshot; }7. 一个真实项目的演进记录从 if-else 泥潭到模式化重构最后分享一段我亲身经历的重构过程希望能给你一些参考。项目是一个内部工单系统最初所有状态判断都堆在一个两千行的handleMessage函数里。每次加一种工单类型就要在那个函数里加分支代码评审时没人愿意看测试覆盖率长期低于 40%。重构分三步走。第一步先把所有if (state xxx)的分支抽成独立函数函数签名统一为(action, ctx) result这一步不改变行为只是物理拆分。第二步定义ContextMode接口把抽出来的函数包装成模式类实现canHandle和handle。第三步引入解析器和注册表删掉原来的大函数改为调度器驱动。整个过程持续了三周期间系统一直保持可发布状态。重构后最直观的变化新增一种工单类型从平均改动 8 个文件降到 2 个文件新建模式目录 注册配置代码评审时间从半天降到一小时线上因状态判断错误导致的工单从每月十几起降到零。当然代价也有文件数量增加了新人需要先理解模式契约才能上手。但综合来看收益远大于成本。如果你正在犹豫要不要做类似重构我的建议是先别急着全量改。挑一个分支最多、最常出问题的流程做试点跑通后再逐步推广。context-mode 的价值不在于它多高深而在于它把混乱的隐式判断变成了显式的、可测试的、可追踪的结构。这一点在项目规模变大之后会越来越明显。