1. 先聊聊context-mode到底是什么

1.1 我遇到的真实痛点：终端里一天要换十几个"身份"

如果你和我一样，日常工作是前后端通吃、偶尔还要管点服务器和脚本工具，那你一定遇到过这种场面：上午在/project/api底下写业务代码，下午切到/project/infra调容器编排，晚上又跑回/home/me/notes整理文档。这三个场景对终端的要求完全不同——前者需要自动进入对应的虚拟环境、加载本地调试变量；中间要切换到运维工具链、启用生产环境的快捷命令；后者干脆就是纯文本环境，连PS1提示符风格都想换个清爽的。

我最早的做法是手动 source 各种环境脚本，后来升级成几个独立的.env文件加上一堆 alias，再后来忍无可忍开始研究 direnv 这类目录感知工具。但用了段时间发现，目录感知只是"上下文"的一部分，它解决不了分支切换、项目冷热程度、当前是不是在跑长任务这类更细的信号。最直接的一个痛点：我在backend-service仓库里，但不同的 release 分支需要的构建参数都不一样，我可能连续刷了十几条git checkout，这时候工具该知道我要干嘛了。

于是就有了我自己写、一直在用的这套思路，我给它取名叫 context-mode。它不是某一个具体工具的名字，更像是一套"终端上下文感知模式"的实践方案，核心就一句话：把"当前环境是什么状态"这件事，变成工具的第一输入，而不是让用户反复手动交代。

1.2 context-mode的定义：把上下文变成工具的第一输入

你可以把 context-mode 理解成一个终端层面的"智能座舱"。它持续采集当前 shell 里的环境信号，比如所在目录、Git 分支、环境变量标记、最近执行过的命令类型，然后把这些信号汇总成一个"上下文指纹"，再用它去匹配一套预先定义好的行为配置。匹配上了，就自动加载对应的环境变量、别名、快捷键，甚至纠正你的PS1提示符格式；匹配不上，就老老实实回到默认模式，绝对不多管闲事。

这套逻辑其实和人脑的工作方式很像。举个例子：你走进一间摆满手术器械的房间，不需要谁提醒，你就知道这里不是咖啡厅——你会自动压低声音、找消过毒的位置站，这就是"上下文感知"。context-mode 想让终端也具备这种能力：知道你正在哪个 Git 仓库的哪个分支、知道你现在跑的命令大概率是调试还是部署，然后替你先把地毯铺好。

我在设计它的时候，认真参考过 direnv、autoenv、zsh-autoswitch-virtualenv 这些前辈的思路，但把它们都拆开重新想了一遍。direnv 只认目录，太单薄；autoenv 靠触发文件，太笨重；完全用 AI 猜意图又太没谱，延迟和误判我接受不了。所以最后我选了折中方案：把上下文建模成"信号 + 权重 + 档位"的三层结构，规则由我自己写，匹配由程序算。

1.3 它到底解决了什么，适合谁用

说人话，context-mode 适合这几类人：一是像我这样在一个终端里频繁横跳多个项目的开发者；二是需要把一堆临时 export 和 source 固化下来的运维或数据工程师；三是对"效率工具怎么设计"本身感兴趣、愿意折腾自己工作流的人。

它解决的三个核心问题分别是：

• 环境切换靠手，容易忘：人不是机器，切到生产仓库却忘了加载生产变量这种事太容易发生了。context-mode 按目录 + 分支 + 任务信号自动匹配，少一步算一步。
• 上下文信息藏在脑子里，不可复现：新同事加入项目，你嘴上说"哦你先 export 一下那三个变量"，实际上不如放一个 context 配置文件在仓库里来得实在。配置即文档，团队可共享。
• 终端交互体验一成不变：你在写日记和在紧急修服务的时候，希望看到的提示符颜色、显示的信息密度、可用的快捷键完全一样吗？我觉得不少人希望不一样，但没人愿意手动改配置。context-mode 可以把这部分也接管了。

接下来我详细讲讲这套模式里最难、也最有含金量的部分：信号采集和档位匹配。毕竟"感知上下文"的道理谁都会说，落地的时候全是细节。

2. 方案选型的核心思路：为什么"感知上下文"比"手动配置"更靠谱

2.1 市面上的两种做法，和我为什么都不满意

先聊聊我在动手之前考察过的方案，这样你才能理解我为什么非要自己写一套。

第一种是目录绑定型，代表就是 direnv。它的逻辑非常直接：进入某个目录，自动加载目录下的.envrc文件里的 export 语句；离开目录，自动卸载。用了半年，我发现它有两个很现实的问题：一是它只认目录，不认分支。同一个仓库，我main分支和feature/xxx分支要用完全不同的配置，direnv 做不到；二是它只会 export，不会做更复杂的编排。我想让进入某个仓库时自动把PS1改成带服务名的样式，想在启动长任务前自动拉一下最新镜像，direnv 就不太顺了。当然你可以在.envrc里写一堆printf和别名绕过去，但那已经是在和框架搏斗了。

第二种是规则触发型，代表是 autoenv 和各类 shell 钩子脚本。它们让用户自己写进入/离开目录时执行的脚本。灵活度上去了，但维护成本也上来了：每个人写脚本的风格完全不一样，项目一多就成了无人敢动的定时炸弹。更麻烦的是，触发条件只有"目录变化"这一个维度，你想加一个"当命令前缀是 kubectl 时增强提示"这种动态维度，就得另写一套钩子，分裂感很重。

我需要的不是单纯的环境变量切换器，而是一个统一的上下文模型。我要它既能覆盖 direnv 的目录绑定场景，又能处理 Git 分支、当前任务类型、环境标记这些更细的信号，还要有统一的配置语法、可调试的匹配过程、能防止抖动误判的机制。

2.2 context-mode的信号采集：我选哪几个维度，为什么

决定自己写之后，第一个问题是：上下文到底由哪些信号构成？我系统地列了一遍当时能想到的所有信号源，大致有十几个，比如当前绝对路径、路径层级深度、Git 仓库名、当前分支、是否有未提交改动、环境变量里有没有CI标记、最近的 shell 历史命令关键词、今天第一次进入该目录还是第 N 次、后台有没有正在跑的进程、当前 shell 的 session 年龄，等等。

理论上信号越多模型越准，但工程上信号越多系统就越脆、越难以调试。我做了一个减法，最终只保留了五个核心信号维度：

1. 目录模式：基于正则或通配符的路径匹配，兼容符号链接解析后的真实路径。
2. Git 上下文：仓库名 + 当前分支 + 是否处于 merge/rebase 中间态。仓库名用字符串，分支用前缀匹配，中间态用布尔。
3. 环境标记：用户显式设置的特殊变量是否在环境中存在。比如CTXMODE_DEV=1这种，适合在 CI 或运维脚本里主动注入。
4. 热信号：最近一段时间内（默认 5 分钟）执行的命令类型计数。比如 kubectl 相关命令出现了 3 次，docker compose 命令出现 2 次，这表示你在做某种类型的运维工作。
5. 时间/频次信号：当前时间和进入目录的最小时间间隔。这个信号我犹豫了很久是否保留，最后还是留了，用来支持"早晨 9 点到 12 点默认进会议笔记模式"这种轻量场景。

我把信号做成了可插拔的模块，每个信号源只负责输出 "信号名 + 当前值 + 可信度"。可信度是用来处理数据抖动用的，比如"最近执行命令计数"这种信号天然是滞后的，可信度就要低一些，避免在命令执行的瞬间反复横跳。

2.3 档位匹配的打分逻辑：从信号到上下文档位

有了信号，下一步是把信号映射到配置好的行为档位。我在早期做过一个很蠢的版本：直接用 if-else 判断，每个档位写一堆if [[ "$PWD" == ... ]] && [[ "$GIT_BRANCH" == ... ]]。写到第 6 个档位的时候我就知道这条路走不下去了，因为档位之间会相互覆盖，判断顺序稍一变化结果就完全不同，调试全靠加 echo。

后来我换成了评分制，这也是 context-mode 最核心的东西。每个 context 档位在配置里声明它对哪些信号感兴趣，以及每个信号的权重。匹配时程序算出当前所有信号的快照，然后对每个候选项打分：

score = Σ(signal_match_i × weight_i)

signal_match_i的取值不是简单的 0 或 1，而是 0 到 1 之间的相似度。比如分支名配置的是feature/*，当前分支是feature/login，match 值就是 1；当前分支是fix/login，match 值可能是 0.4。这能避免"因为一个小分支名拼写不同就完全不匹配"的生硬问题。

得分最高的档位胜出，但有两个保护机制：一是最低阈值，默认 40 分，所有档位得分都低于阈值的，默认回落到default档位；二是优先级决胜，得分一样时按priority值从高到低排序，再不行按配置声明顺序。这两条规则让匹配行为完全可以预测，不会在多个档位之间来回抽风。

2.4 这里的关键取舍：克制比智能更重要

如果这篇文章只留一条设计经验，就是这句话：上下文感知工具最难的瓶颈不是怎么感知得更多，而是怎么克制地感知、稳定地输出。

我见过不少人做的类似项目，最后死于功能膨胀：又是 AI 意图识别、又是监听全局按键、又是读取日历判断你在不在开会。看起来很美，实际用起来每条都是误触发的来源。我今天早晨开视频会议，终端里不小心键入/meeting/notes目录，某个 AI 上下文引擎如果错误地识别成"进入专注模式"，把通知静音了，那我错过会议提醒反而更麻烦。

所以我在整个设计里有几条不变的原则：

• 规则必须显式：所有匹配规则写在配置文件里，不允许模型自动生成匹配规则。模型可以帮你建议，但最终规则要能被人审阅。
• 不改变用户输入：context-mode 只负责环境准备和环境展示，绝不拦截、改写、补全用户敲的命令，除非用户显式开启。避免引入不可预期的副作用。
• 降级透明：任何信号源出错时，丢掉的只是对应维度的分数，绝不抛异常、绝不阻塞 shell 启动。
• 性能预算明确：每次上下文检查的全部开销控制在 20ms 以内，超过预算宁可不查。

在这个基础上，我开始写具体的配置结构和实现。这部分的细节才是真正让 context-mode 从概念走向可用的关键，下一章我用一个真实的配置样例来拆解。

3. 动手实现：配置结构、权重与计算细节

3.1 配置文件先行：一个可以直接抄的YAML样例

我选 YAML 作为配置格式，理由很简单：有注释、有缩进结构、绝大多数开发者都认识，而且解析库到处都有。每个 context 档位的基本结构如下：

contexts: - name: backend-dev priority: 80 signals: path_match: ".*/services/(api|worker|scheduler)" branch_prefix: "feat/" has_env: "CTXMODE_BACKEND" signal_weights: path_match: 50 branch_prefix: 20 has_env: 30 env: NODE_ENV: "development" DEBUG: "app:*" aliases: - name: "devlog" target: "tail -f logs/backend.log" ps1: style: "color" left: "🐘 backend" pre_cmd: | echo "进入后端开发上下文"

注意上面这个例子里的signal_weights和signals是分开写的：signals声明"我对哪个信号感兴趣及匹配值怎么算"，signal_weights声明"这个信号对最终分数的影响有多大"。这样拆开的好处是：追加一个档位时，只需要写它关心哪些信号，不需要关心其他档位怎么配；调整一个信号的全局权重时，也不用逐档改。

实际跑起来之后，我会在调试模式看到类似这样的输出：

[ctxmode] 扫描信号: path=/home/me/proj/services/api [ctxmode] path_match(*/services/(api|worker|scheduler)) = 1.0 × 50 [ctxmode] branch_prefix(feat/*) = 0.9 × 20 [ctxmode] has_env(CTXMODE_BACKEND) = 0.0 × 30 [ctxmode] 档位 backend-dev 得分 = 50 + 18 + 0 = 68 (阈值 40) [ctxmode] 生效: backend-dev

这条调试输出相当于把工具的判断过程完全摊开给人看。档位生效得莫名其妙的时候，第一件事就是看这个日志，而不是猜。这个设计我强烈建议你也保留，因为上下文感知工具的调试体验，本质上就是可解释性。

3.2 权重怎么设：我的一次完整计算过程

权重设置是整个配置里最劝退新手的部分，因为它既不能全靠拍脑袋，也没有绝对正确的标准答案。我分享一次真实的调参过程，你感受一下思路。

假设我有三个档位需要共存：backend-dev、ops-deploy、docs。它们在某些目录下会发生信号重叠。比如我在/project/services/api目录下，同时git分支是feat/xxx，最近跑过两条kubectl命令。这时候三个候选都有理由生效：目录像后端开发、命令像运维部署、分支名像功能开发，很模糊。

我第一步是给每个档位定一个"一票必中"的信号。对backend-dev来说，path_match是最强信号，只要落在 API 服务目录里，权重给到 60。对ops-deploy来说，最近 5 分钟执行过kubectl/helm相关命令是最强信号，权重给到 70——因为一个正在敲 kubectl 的人，哪怕他人在 API 目录里，也大概率是在做部署相关的操作而不是写业务代码。对docs来说，path_match匹配到docs/或notes/目录是强信号，权重给到 75。

第二步是处理中等信号。分支前缀feat/*给backend-dev加 20，给docs加 5——因为功能分支很少会去写文档。has_env给ops-deploy加 15，因为如果用户在部署服务器上显式注入了运维环境变量，这是个很可靠的信号。

第三步就是算数。当上述场景同时出现时：

backend-dev = 60(路径) + 20(分支) + 0 = 80 ops-deploy = 0(路径不匹配) + 0(分支不匹配) + 70(命令热信号) + 15(环境标记) = 85 docs = 0(路径不匹配) + 5(分支) + 0 = 5

最终ops-deploy赢。这个结果是合理的：人在 API 仓库里敲 kubectl，大概率是在做发布或排查，而不是写接口。但如果你觉得"只要进了 API 目录就该是后端开发，不管敲什么命令"，那就把backend-dev的path_match权重提高到 85，让路径的直接相关性压过命令热信号。权重的本质，就是你对"哪个信号更可靠"的主观判断，把它显式数字化而已。

3.3 缓存与TTL：别让感知变成延迟

如果说打分是 context-mode 的大脑，缓存就是它的脊髓反射。没有缓存的版本我实际用过一周，结果非常酸爽：每次cd都要重新扫描目录、解析 Git 状态、统计命令历史，整体耗时多的时候能到 300 到 500 毫秒。在快速的终端操作里这种延迟体感极其明显，整个 shell 像泡在糖浆里。

我的优化思路分两层：

第一层是信号缓存。把目录扫描结果和 Git 状态结果缓存起来，缓存键是目录 +.git/HEAD文件内容 + 目录 mtime 的组合指纹。指纹没变，直接用缓存；指纹变了才重新解析。这条优化把 90% 的重复扫描干掉了，因为绝大多数时候你连续敲命令，目录内容和 Git 状态根本没变过。

第二层是结果缓存。上一步算出的"最佳档位 + 生效时间"会缓存一段时间，这个时间我默认设 60 秒。60 秒内的重复请求不再重算打分，直接返回结果。你可能担心：那如果我 60 秒内既跑了 kubectl 又想切回写代码，context-mode 会不会反应不过来？实测下来这个概率很低，因为人不会在几秒内切换任务性质；而且我把"命令热信号"的统计窗口放宽到了 5 分钟，本来就允许一定滞后。

真正需要即时响应的场景，我给了一个手动刷新快捷键，绑定ctrl-r强制跳过缓存重算。这个设计比无限缩短 TTL 更科学，因为工具永远不应该比使用者更急。

3.4 触发机制的核心：怎么避免热切换抖动

热切换抖动是这类工具最恶性的 bug，字面意思表现就是：档位在 A 和 B 之间反复横跳，每次切换都触发环境重置、别名重载、提示符闪烁，终端根本没法用。我第一版就踩了这个坑，现在把我的解决办法完整说一下。

抖动产生的根源，是信号本身在持续变化，而档位切换的判定太敏感。比如我配置了"分支前缀为feature/*时匹配feat-dev档"，正常情况没问题。但如果我为了提交代码临时建了一个分支叫tmp/ci-fix，然后又立刻删除回到原分支，删除瞬间 Git 触发了一次HEAD变化，context-mode 就会从feat-dev切到default，紧接着又切回来。两次切换可能就发生在 1 秒内，弹跳效果非常酸爽。

我的防抖策略是三层：

1. 指纹门卫：不管是目录变化、分支变化还是时间到达，先计算当前完整指纹，和"当前已生效档位"的指纹比对。相同直接忽略，不触发任何动作。这能挡住大部分无效重算。
2. 冷却窗口：档位切换完成后，进入 10 秒冷却期。冷却期内即使信号指出另一个档位得分更高，也不会立即切换，只会打一条日志："检测到候选档位 ops-deploy，但当前处于冷却窗口，未执行切换"。冷却期结束后如果有连续 3 次检查都指向新档位，才真正切换。
3. 稳定计数：新档位必须连续命中 3 次才会生效。这个次数对应大约 30 到 60 秒的观察期，取决于检查频率。临时抖动会被这个机制吞掉。

这三层下来，我用了三个月，几乎没有再遇到过肉眼可见的档位弹跳。唯一的代价是档位切换变得有点"迟钝"，但实际操作中你根本感知不到，因为你不会在 30 秒内反复横跳任务类型。如果真有人这么干，那手动刷新快捷键就是为这种情况准备的。

4. 接入实战与效果观测

4.1 把context-mode接进终端：四步实操

配置设计得再漂亮，接不进日常 shell 就是白搭。我把整个接入过程拆成四步，每一步都附上可以直接用的脚本。我默认你的 shell 是 zsh，bash 用户把语法换成export和PROMPT_COMMAND即可。

第一步：安装 context-mode 核心脚本。我把它做成一个绿色二进制 + 一组 shell 函数。将二进制放在~/.local/bin/ctxmode，然后写一个加载文件~/.ctxmode/init.zsh：

# ~/.ctxmode/init.zsh autoload -Uz add-zsh-hook _ctxmode_prompt() { # 用异步子进程评估上下文，避免阻塞 shell 输入 ~/.local/bin/ctxmode eval --shell zsh --async > /tmp/ctxmode_last.env # 读取评估结果 [[ -f /tmp/ctxmode_last.env ]] && source /tmp/ctxmode_last.env } _ctxmode_preexec() { # 每次执行命令前记录命令类型，用于热信号采集 ~/.local/bin/ctxmode note --cmd "$1" --dir "$PWD" --async } add-zsh-hook precmd _ctxmode_prompt add-zsh-hook preexec _ctxmode_preexec

这里有个关键细节：评估过程我用--async丢到子进程执行，不阻塞当前 shell 的precmd钩子。否则每次命令执行完都等一次上下文评估，终端响应性会被拖垮。异步的结果会写入一个临时文件，下一条命令执行前 source 进去。这意味着环境变量切换最多延迟一条命令的时间，体感上是完全同步的。

第二步：准备配置文件。我把上一章的 YAML 样例写进~/.ctxmode/config.yaml，然后运行：

ctxmode validate --config ~/.ctxmode/config.yaml

这个命令会检查每个档位的信号声明是否合法、权重是否超过阈值、有没有配了重复的 name。别小看这一步，我有一次写嵌套语法错误，少了两个空格，调试了一下午。

第三步：在.zshrc里 source init 脚本：

# ~/.zshrc [[ -f ~/.ctxmode/init.zsh ]] && source ~/.ctxmode/init.zsh

第四步：验证接入。新开一个终端窗口，跑ctxmode status，应该能看到当前档位、匹配到的信号列表和总分。如果显示的是default且没有任何信号被采集，大概率是配置文件路径写错了或者信号正则没匹配上。跑ctxmode debug --once可以强制单次评估并打印完整判断过程。

这套接入流程从安装到验证大约五分钟，主要时间花在写配置上。如果你此前没有任何上下文管理工具，我建议先只配一个目录约束的信号，跑通了再加分支和命令热信号。先让系统动起来，再让系统聪明起来。

4.2 实测数据：不同场景下的开关效果

我在三台机器上各用了一个多月，这里给一组真实观测数据供你参考。

第一台是主力开发机，跑的是前后端混合项目。接入前我每天大概要手动执行 15 到 20 次环境和别名切换，有时候忘了切换到导致跑错配置，平均一周会出两三次低级事故。接入后，目录和分支信号覆盖了 98% 的切换场景，手动切换降到每周两次左右。最明显的变化是提示符：在backend-dev档位下，右侧会显示当前服务名和最新日志目录；切到ops-deploy档位后自动变成简洁的白色提示符，去掉无关信息。视觉判断成本一下就低了。

第二台是家里的 NAS 兼实验服务器，跑的是各类容器和服务。这台机器上 command 热信号优势体现得最明显。我经常在/opt/docker目录下既写配置又执行docker compose命令，以前需要手动区分"编辑模式"和"操作模式"，现在 context-mode 会根据最近命令历史自动切。比如连续敲了三条docker compose up相关命令后，它会自动把COMPOSE_PROJECT_NAME、DOCKER_HOST这些变量补上，并加载 deploy 专用的别名。实测下来，相关的长命令输入速度提高不少，主要是省去了来回 export 的思考时间。

第三台是配置最弱的旧笔记本，2 核 4G 内存。这台机器主要验证性能底线。在接入缓存和指纹门卫之后，ctxmode note --async的 p50 开销稳定在 5ms 左右，ctxmode eval --async的 p50 在 18ms 左右。由于都是异步执行，对正常打字输入完全没有可感知的阻塞。唯一有感的场景是冷启动时第一次cd进大仓库，Git 状态解析会稍微多花一点时间，但也就是几十毫秒的事。

4.3 我踩过的坑：三件差点让我弃坑的事

这套方案不是一蹴而就的，中间有几个坑差点让我直接放弃，分享出来帮你避开。

第一个坑是zsh hook 顺序冲突。我很早之前就在.zshrc里注册过一个自定义 precmd 钩子用来显示 Git 分支持续时间，接入 context-mode 后又注册了一个，结果发现有时候我的提示符会被 context-mode 的异步环境覆盖回去。排查到最后发现是 hook 注册顺序问题，zsh 多个 precmd 钩子执行顺序遵循后进先出。解决办法是在 init.zsh 里明确调用add-zsh-hook -d precmd _ctxmode_prompt先卸载再注册，把 context-mode 的执行顺序固定到第一位。

第二个坑是Git 仓库嵌套导致的误判。我用的是 monorepo 结构，子目录里又各自存在.git目录，git status的搜索往上找到的仓库顶层和实际的心智预期不一致。踩到这个坑的时候，context-mode 的分支前缀匹配结果完全混乱，一会儿显示 master 一会儿显示 feature/xxx。后来我把 Git 信号采集改成：从当前目录逐级向上找最近的那个.git目录，同时限制搜索深度不超过 10 层，问题才解决。

第三个坑是关于热信号的误采集。我最初对"最近执行命令类型"的统计是拿用户 shell 历史文件来做的，结果发现非常不靠谱——因为历史文件有写入延迟、有多终端并发写入时的纠结、还有可能包含敏感信息。后来我改成通过 preexec 钩子实时记录命令到本地内存和一个小型 SQLite 文件，彻底甩开了对历史文件的依赖。顺带还获得了一个好处：可以对命令热信号做精确到秒的时间衰减，而不是依赖历史文件的时间戳近似值。

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

5.1 context-mode不生效，先查这三处

每次有人问我"context-mode 为啥没反应"，我的第一反应都是让他们检查三个点，命中率大概在八成以上。

第一处是hook 有没有真的被加载。很多人把 init.zsh 写进了.zshrc，但新开的 shell 是 login shell，加载的是.zprofile或.login而不是.zshrc。验证方式很简单，在终端里跑whence -w _ctxmode_prompt，如果输出_ctxmode_prompt: function说明加载成功，否则就是加载链路没打通。

第二处是配置文件的边界问题。YAML 里path_match写的是正则，很多人忽略锚点，比如写了.*/services/api，结果连/services/apidocs这种目录也匹配上了。这个不是不生效的问题，而是"过生效"的问题，表现比完全不生效更难排查。建议一开始就在调试日志里看path_match的实际值，不要靠肉眼猜。

第三处是档位分数没达到阈值。默认阈值 40，如果你的信号权重总和低于 40，或者只有一个信号但权重设了 30，那永远不会有档位生效。这个我用一个隐藏命令做了保险：ctxmode doctor会列出所有档位的最大可能得分，凡是低于阈值的直接标红警告。当时上线这个功能，是因为我自己第三次踩了同样的坑。

5.2 目录识别错乱怎么办

目录错乱分两种情况，处理手段完全不同。

一种是正则写太宽导致的错乱，比如前面说的apidocs误匹配。解决思路是把路径匹配从"后缀包含"改成"路径段精确匹配"，我后来的配置里新增了一个path_segment信号类型，它会把路径按/切分成段，要求完整路径中必须有一个/services/api这样的父子结构连续段才命中。看起来比正则更笨，实际用起来误判率低得多。

另一种是符号链接导致的路径不一致。你通过/home/user/link-to-proj进入项目，但解析后的真实路径是/mnt/data/proj，而配置文件里写的是/home/user/proj。这个问题我在 macOS 和 Linux 上都遇到过，最终统一处理方式：信号采集阶段先跑一次realpath标准化，配置里的path_match也默认按标准化后的路径匹配。代价是每次cd会多一次realpath系统调用，但换来的准确性完全值得。

5.3 系统负载高？多半是采集逻辑写得太笨

如果你的机器出现莫名奇妙的 CPU 占用或者磁盘 IO 暴涨，不要把锅甩给"上下文感知"，大概率是你的采集实现有性能问题。我总结过三个最常见的元凶。

第一，反复 spawn 外部命令。如果每次信号采集都跑一遍完整的git status，而这个git status要遍历整个仓库，几百毫秒就没了。而且多个信号源如果各自独立 spawn 子进程，并发叠加更可怕。我在实现里统一用一个批量采集的接口，一次调用把 Git 状态、路径解析、环境变量全部拉回来，再分发到各信号源做计算。

第二，缓存没有生效。典型表现是即使你站在原地不动、Git 头也没变化，信号缓存还是每次重新扫目录。检查方式是在调试模式看日志里有没有[cache] hit和[cache] miss的比例，如果 miss 率超过 20%，说明你的缓存键设计有问题，比如把不稳定的命令热信号混进了指纹，导致指纹几乎每次都变。这是设计 bug，不是玄学。

第三，文件系统监听过度使用。我最初想做得更"实时"，用了 inotify 监听目录变化，结果发现监听大目录时内核内存和 CPU 消耗都上来了。后来放弃了全实时监听，改用"命令执行前检查 + 60 秒 TTL"的折中方案，性能一下就稳了。我的经验是：终端的上下文变化频率本来就不高，没必要追求毫秒级感知，轮询 + 缓存已经足够。

5.4 一份排查速查表

为了让你少走弯路，我把这段时间收集到的典型问题整理成一份速查表。这张表我打印出来贴在了显示器边上，有段时间调试效率提升明显。

排查的总体思路就一条：看 debug 日志，不要瞎猜。我把ctxmode debug --once命令的优先级提到了最高，遇到任何异常先跑它，输出里除了最终结果还有每个信号的值和计算过程，基本上一眼就能定位问题出在信号采集、还是权重分配、还是缓存逻辑上。

最后再分享一个小技巧：如果你在调试期实在拿不准权重怎么配，可以把环境变量CTXMODE_EXPLAIN设成1，这样每次档位生效时都会自动打出一条带详细解释的日志。等你对自己的场景有感觉了，再关掉这个开关。无论你是刚接触上下文感知的初学者，还是准备参考这套思路改进自己工具链的老手，我希望你带走的核心经验只有一条：上下文不是玄学，它是一组可以度量、可以调试、可以显式控制的信号组合。

我后来在这个模式上还做了些扩展，比如把档位配置做成可以按 Git remote 自动拉取的团队共享文件，以及在 CI 里跑一次"配置 lint"来防止团队成员的配置互相打架。但那些都是后话了，先把基础版本用起来、用顺了，比什么都强。