刚开始把一个内部工具重构到能按场景自动调整行为时，我并没有意识到自己其实是在做一套“context-mode”（上下文模式）机制。当时只是觉得代码里到处是if (is.edit.page)、if (current.project === 'xxx')这种判断太难受：新功能每加一个入口，就得在所有相关地方补一遍条件；改一处状态，还不知道哪个模块会跟着抽风。后来我狠下心把“当前处于什么场景”这个信息从散落的临时变量里拎出来，做成一个显式的运行模式，整套系统的逻辑才第一次变得可预测。
这篇文章就围绕 context-mode 的设计思路和落地过程展开，聊几个我在项目里真正遇到的问题：上下文到底怎么建模、自动切换的边界怎么控制、脏数据和过期上下文如何排查，以及引入了上下文模式之后怎么把性能损失压到可以忽略。适合正在做工具类应用、多窗口/多项目工作台、或者想给既有系统增加“场景感知”能力的开发者。内容不绑定特定语言，核心思路通用，我会给出可运行的最小代码骨架。
1. context-mode 想解决的真实痛点：状态漂移与决策分散
1.1 没有上下文模式的世界是怎么崩掉的
我接手那个内部工作台工具时，系统已经能同时处理“浏览资料”、“编辑文档”、“查看监控”三种任务。初版功能简单，每个页面各自为政，倒也没出大问题。后来用户希望界面能更聪明一点：在编辑文档时，快捷键组要变成文档编辑模式；切到监控页时，右上角应该自动出现告警列表；在浏览资料时，底部状态栏要显示当前项目的上下文信息。
一开始这些需求都能“打补丁”实现：给编辑页加一个window.isEditing = true，给监控页挂个onShow回调，在主界面检测焦点变化后挨个通知。但随着页面从三个涨到九个，代码里的跨页状态越来越多。某天我加了一个新的“生成日报”功能，发现除了页面前端需要知道当前在哪个项目下，后端接口也要知道，命令行快捷键也要知道，连统一的侧边栏导航都要根据当前语境展示不同菜单。
于是出现了经典的“状态漂移”：同一个事实（用户当前在项目A的编辑模式），竟然有六个模块各自维护了一份副本。有人改了主界面的项目下拉框，但右侧面板里的项目上下文还是旧的；有人把快捷键组挂到了全局，结果在浏览资料时按 Ctrl+S 居然把缓存笔记覆盖了。这种乱象的本质，不是某行代码写错了，而是没有任何一个位置拥有“当前上下文”的定义权——系统根本不知道自己身处哪个场景。
1.2 context-mode 的核心理念：让“当前场景”变成一等公民
后来我读了一些关于上下文感知设计的资料，又对比了几个开源工作台工具的架构，意识到正确做法不是继续打补丁，而是把“当前处于什么模式、处于什么上下文”显式地建模为一等对象，让所有模块向同一个来源查询，而不是各自猜测。
打个比方：以前这套系统像一屋子人各看各的日历，约会议时互相问“你觉得今天是几号”；引入 context-mode 之后，门口挂了一个所有人都能看见的大日历，任何人需要日期都去瞟一眼。单个模块不再需要维护“当前场景”的副本，只负责响应上下文变化即可。
具体到设计上，context-mode 由三部分组成：
- 上下文源（Context Source）：负责产生“当前场景”的原始信号，比如当前激活的页面、当前选中的项目、当前鼠标悬停的面板、当前的时间段。
- 上下文管理器（Context Manager）：负责接收信号、计算最终上下文，并将其广播给订阅方。它是系统内唯一的权威来源。
- 模式映射层（Mode Mapper）：负责把“上下文”翻译成具体行为，比如显示哪些菜单、绑定哪些快捷键、使用哪个主题、加载哪组插件。
这样拆分之后，决策链路从“每个页面自行判断”变成“统一上下文 -> 统一模式映射 -> 各模块消费”，横向扩展新场景时不需要再串改老模块。
1.3 适用场景与效益边界
不是所有项目都需要 context-mode。我在调研时也走过一段弯路，试图把团队里一个很简单的表单工具也套上这套模式，结果代码量翻了一倍，收益却很有限。所以我后来总结了一张适用性对照表，用于快速判断一个系统需不需要引入 context-mode：
| 场景特征 | 适合引入 context-mode | 不适合强行引入 |
|---|---|---|
| 交互入口数量 | 多个入口频繁切换（页面/面板/模式） | 单一固定流程，切换极少 |
| 状态依赖复杂度 | 多个模块都依赖“当前场景” | 只有一两个模块关心场景 |
| 行为差异程度 | 不同场景下 UI、快捷键、数据源差异大 | 场景之间行为几乎相同 |
| 扩展预期 | 未来会持续增加新场景 | 功能边界基本冻结 |
如果你发现代码里已经出现三处以上重复的场景判断，或者每次新增页面都要去改五六个模块的联动逻辑，那么 context-mode 的介入价值就非常明显。反过来，如果系统很小、切换场景极少，强行抽象反而会把简单问题复杂化。我个人的经验是：在第二次出现“跨模块都需要知道当前场景”的需求时开始引入，不要更早，也不要更晚。
2. 上下文建模：用什么数据结构承载“当前在哪”
2.1 重新定义上下文的最小结构
在设计 context-mode 时，第一个问题是：“当前场景”到底该包含哪些信息？很多人会把上下文直接等价于页面名，稍微负责一点再加上一个项目 ID。但实际用下来，上下文应该是多个维度的组合，维度之间有优先级，有归属关系，也有生命周期。
我最终采用的数据结构分为三层：
- 场景标识（scene）：最宏观的维度，表示用户当前正在做哪类事情。比如
browsing（浏览）、editing（编辑）、reviewing（审查）。它通常由当前激活的主面板类型决定。 - 对象标识（subject）：表示当前作用的业务对象，比如项目 ID、文档 ID、任务 ID。它回答的是一个更具体的问题：在浏览什么、在编辑什么。
- 附加状态（modifier）：表示一些辅助性状态，比如“键盘捕获中”“侧栏展开中”“离线模式”。它用于细化场景，但不构成主维度。
这三个维度合在一起，就构成了一个最小但完整的上下文描述。写成 TypeScript 接口大概是这个样子：
export type Scene = 'browsing' | 'editing' | 'reviewing'; export interface ContextState { scene: Scene; subjectId?: string; // 可以是 projectId / docId / taskId subjectType?: 'project' | 'doc' | 'task'; modifiers: Set<string>; // e.g. 'keyboard-captured', 'sidebar-open' updatedAt: number; }之所以要拆成三层而不是一个扁平对象，是因为不同模块关心不同粒度的信息。快捷键管理器主要关心scene + modifiers，面包屑导航关心subjectType + subjectId，数据面板关心subjectId。如果上下文是一坨扁平字段，订阅方拿到变化通知后还得自己 diff；拆成带层级的结构之后，可以针对性地做精确订阅，性能好的同时也更好推理。
2.2 上下文优先级：多个信号冲突时听谁的
context-mode 最容易踩的坑，就是上下文信号源之间互相矛盾。举一个真实场景：用户主面板停留在“浏览资料”页面，但弹出的 modal 对话框里正在编辑文档标题。这时候当前场景到底是browsing还是editing？如果监听信号只按“触发先后顺序”来覆盖，这取决于哪个事件晚到，逻辑完全不可预测。
我给上下文管理器加了一套优先级规则，用来在信号冲突时做仲裁：
- 模态层 > 主面板层 > 侧边面板层：弹出的 modal 承载的是用户当下最高优先级交互，所以 modal 持有
scene的覆盖权；如果 modal 关闭，上下文自动回落到主面板对应的场景。 - 显式用户操作 > 被动焦点变化：用户通过点按切换项目，属于显式意图，应覆盖由 hover 或焦点漂移产生的信号。
- 对象标识跟随场景走：
subjectId不是独立信号，而是由场景信号携带。比如场景确定为editing时，subjectId必须同时指向正在编辑的文档；如果用户切换了场景，旧subjectId应被清空，避免出现“正在浏览资料目录，但上下文对象却是某个文档”的错位。
这套优先级仲裁是在上下文管理器内部的 reducer 中实现的。信号进入管理器后不是直接覆盖当前状态，而是先经过仲裁函数，合并出一个新的合法状态，再广播出去。
2.3 显式切换、自动感知和混合策略
确定好数据结构之后，下一步是设计“上下文何时被更新”。我见过三种实践，按粗糙程度从低到高排：
- 显式切换：开发者在关键操作点手工调用
contextManager.set(...)。好处是意图明确，坏处是到处埋点、易漏；适合场景分支极少的系统。 - 自动感知：监听路由变化、焦点变化、鼠标位置等信号，自动推导上下文。好处是无侵入、体验流畅，坏处是容易误判，需要一套可靠的仲裁机制兜底。
- 混合策略：主信号（页面切换、项目切换）用显式埋点，辅助信号（modal 弹出、键盘捕获）用自动感知，两者经优先级仲裁后合并。
我强烈推荐第三种。纯自动感知在上线前看着很酷，真正跑起来后你会发现永远有边界情况：鼠标停在某个面板边缘，焦点来回跳；路由参数变化了但界面还没重渲染；用户从一个页面平移到另一个页面，中间经过若干空白状态。把核心链路做成显式切换，把辅助状态做成自动感知，系统既可控又不至于全手埋。
2.4 一个最小的上下文管理器实现骨架
为了让概念更具体，下面给一个极简的实现骨架，它省略了具体框架的绑定，核心逻辑在任何前端或桌面端项目中都能迁移：
type Listener = (ctx: ContextState) => void; class ContextManager { private current: ContextState = { scene: 'browsing', modifiers: new Set(), updatedAt: 0 }; private listeners = new Set<Listener>(); private signals: ContextState[] = []; // 待仲裁的真实信号 setSignal(signal: ContextState) { this.signals.push(signal); const next = this.arbitrate(this.signals, this.current); if (next !== this.current) { this.current = next; this.emit(); } } private arbitrate(signals: ContextState[], prev: ContextState): ContextState { // 按既定优先级规则排序取最高，详见上文 2.2 节 const dominant = signals.sort((a, b) => priority(b) - priority(a))[0]; if (dominant) { return { ...dominant, modifiers: new Set(dominant.modifiers), updatedAt: Date.now(), }; } return prev; } subscribe(fn: Listener) { this.listeners.add(fn); fn(this.current); return () => this.listeners.delete(fn); } private emit() { this.listeners.forEach(fn => fn(this.current)); } }骨架里最关键的是arbitrate这个函数。它在真实项目里会长很多，因为要处理“哪些信号的优先级相同”“何时应该忽略某个信号”“何时应该保留旧上下文而非覆盖”等细节。但核心原则不变：上下文状态的变更必须经过一个收敛的仲裁函数，不能由信号源直接写入。
3. 落地实录：我给某工作台工具加上 context-mode
3.1 场景设定与改造目标
我业余维护着一个用于聚合多项目信息的小工作台（以下称“模拟项目X”），它在同一个窗口里同时展示项目列表、文档预览、任务看板和监控图表。改造前，四个区域各自维护内部状态，窗口顶部的全局菜单只有一个静态结构。用户抱怨最多的是三个问题：
- 在任务看板模式下，全局菜单里依然能看到“文档编辑”相关的操作，操作列表完全没有场景感。
- 从项目A切换到项目B时，文档预览区偶尔还会显示项目A的文档，数据切换明显滞后。
- 键盘快捷键只有一套全局方案，在预览文档时按下 Ctrl+K 会弹出命令面板，但用户本意是想快速搜索当前项目下的文件。
这三个问题恰好分别对应 UI 差异化、数据一致性和快捷键响应差异，是 context-mode 最典型的表达场景。我给自己定的改造目标是：全局菜单、文档预览区和快捷键绑定三处行为，都根据当前上下文自动调整；切换项目后所有区域在一轮事件循环内完成刷新。
3.2 关键设计：把“项目上下文”从路由状态中拆出来
第一个直觉是直接用当前路由参数作为上下文来源，因为工作台本身就是单页应用，路由里确实有项目 ID。但我在联调时发现，路由并不能完整表达上下文：用户可以停在文档预览区而不切换路由，也可能在同一个路由地址下通过内部面板切换浏览对象。如果硬把上下文挂到路由上，就得在路由上加一堆本末倒置的参数。
最终我用一个独立的ContextStore（基于上一节的管理器扩展）来维护当前上下文，路由只是其中一个信号源，而不是唯一来源。项目切换时，项目列表组件调用setSignal，上下文管理器更新subjectId并广播。文档预览区、任务看板、全局菜单各自订阅自己关心的片段，而不是整个上下文对象。
这里我特别做了一件事：把订阅粒度细化。文档预览区只订阅subjectId和scene === 'editing'，任务看板只订阅subjectId和scene === 'reviewing'，这样某个区域收到更新通知时，必然是因为发生了一件和自己相关的事，避免所有区域因为一次上下文变化全部重渲染。
3.3 模式映射表的实现策略
上下文状态确定之后，剩下的问题是如何把ContextState翻译成具体行为。我选择维护一张多级映射表，而不是在每个组件里写if：
const modeTable: Record<Scene, { menuLayout: MenuItem[]; shortcutGroups: string[]; theme?: string; }> = { browsing: { menuLayout: ['项目总览', '资料库', '监控台'], shortcutGroups: ['nav', 'search'], }, editing: { menuLayout: ['文档结构', '版本记录', '导出'], shortcutGroups: ['doc-edit', 'search-in-doc'], }, reviewing: { menuLayout: ['任务列表', '告警配置', '日报生成'], shortcutGroups: ['review', 'quick-report'], }, };这个映射表的好处是所有场景差异集中在一张静态配置里。要新增一个场景，只需要在Scene类型里加一个值，再补一行映射表；所有依赖它的组件在subscribe回调里自动适配新值。旧代码里的if (ctx.scene === 'editing')仍然成立，但没有一个组件需要为了新增场景去改自己的假设。
快捷键部分我单独做了一层封装：快捷键注册的时候不是直接注册到全局，而是注册到指定的shortcutGroup，运行时由 context-mode 决定当前激活哪个组。用户按下 Ctrl+K 时，命令面板的候选项列表也会根据subjectId过滤，只显示当前项目下的文件。
3.4 实际效果与剩余问题
上线后效果很直观：全局菜单在三种场景下展示的项目完全不同，用户找操作的效率明显提高；项目切换后文档预览区基本可以在一个事件循环内刷新干净，之前那种“旧项目文档残留”的处理只剩极少数边界情况。快捷键误触率也降下来了，因为大部分快捷键在浏览模式下直接不注册，也就不会出现“想搜项目文件结果打开了全局命令面板”的错位。
但同步也暴露了一个新问题：上下文频繁变化时，订阅方会收到大量通知。比如用户从一个项目切到另一个项目，subjectId变化一次，scene可能不变；但如果切到编辑模式再切回浏览，modifiers里键盘捕获标记反复增删，会导致绑定快捷键的模块反复注册和注销。这块最终需要靠更精细的 diff 订阅和事件节流来解决，我会在第五章展开。
4. 踩坑记录：上下文过期、脏数据与模式抖动
4.1 上下文过期的典型场景与根因
context-mode 上线后遇到的第一个严重 bug，是上下文“过期”：用户停留在文档预览区很久，期间项目在后台被另一个窗口删除了，前台工作台并不知道，仍在用旧subjectId发请求，结果把删除动作又重复执行了一次，产生脏数据。
根因并不复杂：上下文管理器只知道subjectId是什么，不知道这个 ID 在业务层是否仍然有效。我最初的设计把“上下文”和“业务真实状态”完全脱钩，导致上下文可以指向一个已不存在的对象。
修复方案分两层：
- 在
setSignal进入仲裁前，增加一个有效性校验层，调用业务接口确认subjectId是否仍然存在。 - 订阅到对象删除事件时，上下文管理器主动清空对应的
subjectId，而不是等待下一次信号覆盖。
这里我吃了一个教训：上下文管理器不只是状态存储，它还需要业务侧的反向约束。不能让上下文变成一面只能照见过去的镜子。
4.2 脏数据通过上下文泄漏的排查链路
另一个更隐蔽的问题是脏数据泄漏。用户在编辑文档时，不小心在页面上做了某个操作，触发了一个subjectId为 A 的请求；随后快速切到项目 B，上下文已经更新为 B，但那个异步请求的响应回来之后，由于回调函数捕获的是旧的上下文闭包，把 A 的文档内容写进了当前页面，导致项目 B 的预览区显示项目 A 的内容。
这种问题在传统代码里很难捉，因为回调逻辑本身没错，错的是它关联了已经过期的上下文。我花了整整两个晚上定位，最后锁定的链路是：
- 复现操作序列：编辑文档A -> 立即切换项目B -> 观察预览区内容。
- 在异步请求的 then 回调里打点，打印响应数据里的
subjectId和当前全局subjectId，发现两者不一致。 - 追查请求发起处的参数绑定：请求确实携带了 A，但回调写入的目标位置是在项目B的 DOM 容器里。
修复方式是在请求回调写入前增加一层上下文校验：如果响应中的subjectId与当前上下文中的subjectId不一致，则放弃写入。那个“旧请求返回覆盖新界面”的核心机制，就是给每个异步响应盖上上下文戳，让数据与场景强绑定。
4.3 模式抖动：自动感知信号打架
第三个坑是模式抖动。自动感知焦点变化时，鼠标快速划过侧边栏和主内容区之间的缝隙，场景会在browsing和editing之间反复跳变，导致全局菜单闪烁、快捷键组反复注册注销。
问题出在我把“鼠标悬停到编辑区”当作editing信号的触发源，但悬停并不等于用户真正在编辑。后来我把自动感知的触发条件改成稳定驻留：鼠标在某个区域停留超过 120 毫秒，且该区域发生了点击或键盘事件，才认为场景发生了变化。焦点信号的仲裁优先级也做了降级处理，低于显式操作触发的切换。
4.4 上下文追踪：崩溃现场要能定位到来源
排查上述几个问题时我意识到，context-mode 系统需要配套可观测性。为此我在上下文管理器里增加了一个环形缓冲日志，记录每次上下文变化的来源信号、时间戳和触发组件。一旦用户反馈异常，我可以直接导出最近几十次上下文跳变记录，像看回放一样定位是在哪一步发生了错误覆盖。
这个设计成本很低，收益却极高。现在模拟项目X 的每次上下文变化都会留下轨迹，出问题时不用靠猜，直接把记录拉出来看就行。如果你打算在现有系统里引入 context-mode，强烈建议第一天就把这个日志埋上，等出问题再补就晚了。
4.5 为上下文规则补充回归测试
上下文逻辑是系统的“中枢神经”，它的改动影响面远超普通组件。因此我为核心逻辑补了三类回归测试：
- 仲裁规则测试：给一组矛盾信号，断言仲裁出的上下文是否符合优先级规则。
- 状态机迁移测试：列举所有合法的状态迁移路径，断言不会出现非法组合（比如
editing场景却没有subjectId）。 - 订阅隔离测试：确保订阅方只收到自己关心的上下文片段，避免无效渲染。
这些测试本质上是在保护“上下文规则”不被后续迭代无意破坏。实测下来，补完这三类测试之后，我再改上下文相关的代码，心理压力小了很多。
5. 性能调优与可观测性：让 context-mode 长期可用
5.1 上下文解析的成本构成
把 context-mode 当成长期架构来运营时，必须认真考虑性能。很多人误以为“一个上下文对象而已，能有多大开销”，但实际成本集中在三处：
- 信号产生阶段：监听焦点、路由、鼠标事件本身是高频事件，若不节流，信号风暴会拖慢主线程。
- 仲裁计算阶段：仲裁函数里如果挂载了业务校验请求（检查
subjectId是否存在），每次切换都会等待网络往返。 - 订阅广播阶段：所有订阅方在每次上下文变化后执行的回调，这个开销与订阅方数量、回调复杂度成正比。
以模拟项目X 为例，最糟糕的情况是快速切换项目时，上下文管理器在一秒内被触发了 20 多次信号变更，导致所有订阅方同时重绘。界面直接肉眼可见地卡顿。
5.2 三项优化措施：微任务合并、增量订阅和异步校验
针对上面的成本结构，我做了三项优化：
第一，微任务合并。在setSignal方法中不再同步更新状态，而是把更新计划 push 到微任务队列，等当前宏任务完成后统一合并再广播。这样一秒钟内的 20 次信号变更会被合并成一次或两次真正的更新。
async flushUpdates() { if (this.flushing) return; this.flushing = true; try { // 等当前宏任务执行完，再进入微任务合并 await Promise.resolve(); // 合并信号，触发一轮仲裁 if (this.pendingSignals.length > 0) { // ... } } finally { this.flushing = false; } }第二，增量订阅。订阅方不再默认收全量上下文，而是声明自己关心哪些字段。上下文管理器在广播前做一次浅比较，只对发生了变化且属于订阅方关心的字段推送通知。这个改动把大部分无关重绘直接挡在门外。
第三，异步校验离线化。检查subjectId是否有效等业务校验不再阻塞仲裁流程，而是放入一个单独的校验队列异步执行。上下文先乐观更新，用户界面立即响应；校验失败后再回滚或标注失效。这样切换项目时不会出现卡顿等待。
5.3 上下文 Trace：记录每一次跳变
可观测性设计不仅要记录，还要方便检索。我在环形日志基础上加了一个简单的 Trace 结构，记录每个信号源产生的上下文快照。每个快照包括signalSource（哪个组件触发的）、signalType（显式切换/自动感知/异步校验）、prevSummary和nextSummary。
当用户反馈“切换项目后界面显示不对”时，我导出的轨迹可能是这样的：
10:00:01.123 显式切换 ProjectSwitcher prev: {browsing, projA} -> next: {editing, docX} 10:00:01.148 自动感知 ModalLayer prev: {editing, docX} -> next: {editing, docX, modal:create} 10:00:01.502 校验回滚 AsyncValidator prev: {editing, docX} -> next: {browsing, null}这种回放能力在定位“上下文被某个隐藏组件悄悄覆盖”时尤其好用。有一次一个侧边栏小组件在渲染时偷偷调用了setSignal，导致项目切换永远晚一步，我靠日志一眼就锁定了它的调用栈。
5.4 处理长尾场景和模式优先级反转
context-mode 跑久之后，长尾场景才是最花时间的。最典型的是“模态层叠加模态层”：弹出一个新建文档对话框，对话框里又有一个设置弹层，两层模态同时存在时谁的场景权重更高？我的处理方案是给模态定义权重常量，叠加时按权重取最高；关闭时重新计算剩余模态的权重，让上下文平滑回落。
另一个是优先级反转：用户在主区域选择了项目A，弹窗操作后关闭，这时旧信号（项目A）如果还留在信号队列里，会和新信号（项目B）打架。我在setSignal的合并逻辑里加入了信号代次（sequence），只有晚到达的信号才能覆盖同优先级的旧信号，杜绝了这种“幽灵信号”问题。
这些细节单个看都不复杂，但累积起来决定了系统在复杂交互下的稳定程度。如果你要在一个多窗口或多面板的系统中长期使用 context-mode，建议在早期就把“信号代次”和“模态权重”这两件事定下来，否则后续每加一个交互入口都可能在上下文仲裁上出小岔子。
6. 写在最后：关于 context-mode 的几点体会
如果让我用一个词概括 context-mode 的核心价值，我会说“收敛”——把分散在系统各处的场景判断收到一个统一源头。你不再需要猜测某个模块为什么在某个时刻表现异常，因为所有行为都由同一条上下文链路驱动；新增场景时也不用像缝补丁一样到处修改老逻辑，只需要新增一条映射。
但要记住：context-mode 不是银弹。它解决的是“多场景、多入口、多模块联动”的问题，如果你的系统只有一个固定工作流，硬上这套架构反而增加理解成本。在我自己的后续项目里，我会先用三个问题做前置判断：有多少个场景？有多少个模块依赖场景？场景切换的频次有多高？三个答案都明确指向“需要”，才值得引入。
最后分享两个小技巧：第一，上下文的订阅回调里不要做重的组件初始化，尽量只做数据更新，真正的初始化和销毁放到模式级别的生命周期钩子里，否则模式切换时会有明显卡顿。第二，就算第一版完全没有可观测性需求，也建议先把上下文变化日志写出来，因为它几乎是排查所有 context-mode 问题的唯一线索。我在模拟项目X 早期没埋日志，后来补的时候花了一天时间；如果你在第一天就顺手加上，后续排查会轻松很多。
