第一次在项目里写下context-mode这个名字的时候，我正同时维护着一套后端服务、一个数据管道脚本库和一个内部工具仓库。糟糕的是，这三个仓库的规范完全不同：一个用 gRPC 错误码，一个必须给每个任务写日志前缀，一个禁止用datetime.now()。每天切来切去，要么忘改命名风格，要么在 AI 助手里反复说明“我在哪个项目、用什么技术栈、注意什么约定”，非常消耗耐心。后来我把所有上下文打包成一个可以在运行时自动探测、自动加载的模块，命名就叫context-mode。
简单说，context-mode解决的是“工具不知道你身处什么环境”的问题。不管是命令行工具、代码编辑器、AI 编程助手还是笔记系统，如果它只能看到单个指令而看不到周围状态，就很难给出贴合当下场景的反馈。这篇文章不会停留在概念层面，我会从需求拆解、最小实现、场景扩展、参数调优和问题排查五个方面展开，里面所有代码和结构都是我实际在用的方案，可以直接复制过去改一改就能跑。
1. context-mode 到底解决什么问题
1.1 会话上下文丢失是隐形损耗
先想一个很常见的场景：你在终端里执行一条测试命令，这个命令本身没问题，但它不知道你此时在哪个仓库、哪个分支、运行环境是本地还是 CI，也不知道你上次调试到哪一步。类似的问题也出现在 AI 编程工具里——你问“为什么数据库连接超时”，如果不先声明“我在微服务 A 的订单模块，连接的是一个内部 Postgres 集群”，它很可能给你一个“统答案”，但这个答案不解决你的实际问题。
丢失上下文带来的损耗通常很隐蔽。它不是报错，不是崩溃，而是每次切换任务时多花的那 30 秒解释成本。一天切换 20 次就是 10 分钟，一周就接近一小时。这还不算注意力被打断的代价。context-mode的思路很简单：把那些每次都要重复说明的信息，固化成可以被自动发现、自动注入的结构化配置，让工具替你把这些事“记住”。
宏观来看，所有“上下文”本质上都是“当前状态的快照”。context-mode要做的就是快照的采集、存储和注入。采集靠探测目录结构、Git 元数据、环境变更甚至 shell 历史；存储采用分层配置；注入则发生在目标工具启动前。这样的设计让上下文不依赖某个特定客户端，也不污染某个特定进程，它是一层可以叠加在任意工具上的“环境状态”。
1.2 上下文模式的常见形态矩阵
context-mode不是一个只能固定实现的软件，它更像一种设计模式。我把自己见过的所有变体整理成过一张表，这张表也决定了后面的实现思路：
| 形态 | 输入端 | 输出端 | 典型工具 |
|---|---|---|---|
| 编辑器/IDE 上下文 | 项目目录、语言服务、打开的文件列表 | 编辑器配置、插件状态、任务定义 | VS Code、Neovim、Cursor 类工具 |
| AI 提示词上下文 | 仓库说明、代码规范、最近改动 | 系统提示词、few-shot 示例、指令前缀 | AI 编程助手、本地大模型包装器 |
| 命令行上下文 | 当前目录、Git 分支、历史命令、环境变量 | shell 提示符、命令别名、脚本参数 | bash、zsh、自建 CLI 工具 |
| 笔记/知识库上下文 | 文件路径、知识库标签、引用关系 | 模板字段、建议标签、相关笔记召回 | 双链笔记应用、本地知识库 |
这四个形态并不是互相独立的。比如我给 AI 助手准备提示词时，需要同时参考项目的.ctxrc描述、Git 状态和当前文件列表。这些信息就来自“上下文采集器”，而不是我自己手敲。后面我做的ctx工具，本质上就是把这张表的逻辑抽象成统一框架，再用插件的方式适配不同输出目标。
2. 从零实现一个最小可用的 context-mode
2.1 设计原则：目录优先、显式优先于隐式
在写第一版代码前，我给自己定了两条硬性原则。第一条是“目录优先”。无论什么形态的上下文，都应该优先从“当前所在的位置”推断信息。文件夹路径本身是非常高密度的信号：/repo/team/backend/payment-service其实已经暗示了团队归属、服务名称和技术栈范围。目录结构越规范，这种推断越可靠，所以默认把目录作为上下文推导的主键。
第二条是“显式优先于隐式”。虽然目录能推导很多东西，但推导终究有误差，必须给用户一个显式声明的入口。于是每个项目根目录下允许放一个.ctxrc文件，用简单键值对描述“这个项目到底是什么、有什么特殊约定”。系统解析顺序是：显式配置优先，隐藏规则兜底。如果.ctxrc明确写了project = "payment-service"，那就不会去猜目录名；如果没有声明，才从路径最后一段推导。
这里有一个容易被忽视的细节：上下文模式不应该只在单次指令内生效。它需要支持“会话惯性”，也就是一旦确认当前上下文，后续操作默认沿用，直到目录切换或者显式清除。很多初版设计把上下文做成了每次重新全量探测，这样不仅慢，还会让 AI 工具误以为你切换了项目。我的做法是维护一个轻量会话标记，由目录路径、Git 远程地址和启动时间组成，只有这三个因素都变化时才重新计算上下文。
2.2 核心代码骨架
为了实现这套逻辑，我写了一个最小可用的 Python 工具，命令名就叫ctx。它核心做的事只有三件：探测当前上下文、读取配置文件、输出上下文快照。下面这段代码是一个可以直接运行的骨架：
#!/usr/bin/env python3 """ctx: a minimal context-mode implementation.""" import json import os import subprocess from pathlib import Path from typing import Any, Dict, Optional CONFIG_NAMES = [".ctxrc", ".context.toml", "ctx.yaml"] def find_config(start_dir: Path) -> tuple[Optional[Path], Path]: """从当前目录向上查找配置文件，返回 (配置文件, 项目根目录)。""" current = start_dir.resolve() while True: for name in CONFIG_NAMES: candidate = current / name if candidate.is_file(): return candidate, current if current.parent == current: return None, start_dir.resolve() current = current.parent def detect_environment(project_root: Path) -> Dict[str, Any]: """收集环境信号：git 分支、最近提交、工具链版本。""" signals = {} git_dir = project_root / ".git" if git_dir.exists(): branch = subprocess.run( ["git", "-C", str(project_root), "branch", "--show-current"], capture_output=True, text=True, ).stdout.strip() signals["git_branch"] = branch signals["git_root"] = str(project_root) return signals def load_tree(path: Path) -> Dict[str, str]: """读取目录树的轻量描述，用于提示词注入。""" entries = sorted(path.iterdir()) files = [e.name for e in entries if e.is_file()][:50] dirs = [e.name for e in entries if e.is_dir()][:30] return {"files": ",".join(files), "dirs": ",".join(dirs)} def load_inline_config(path: Optional[Path]) -> Dict[str, str]: """解析 .ctxrc：只实现最简单的 key = value 格式。""" if not path: return {} result = {} with open(path, "r", encoding="utf-8") as f: for raw_line in f: line = raw_line.strip() if not line or line.startswith("#"): continue if "=" not in line: continue key, value = line.split("=", 1) result[key.strip()] = value.strip() return result def build_context() -> Dict[str, Any]: """组合上下文快照：项目根、配置、环境信号、目录森林。""" cwd = Path.cwd() config_path, project_root = find_config(cwd) inline = load_inline_config(config_path) signals = detect_environment(project_root) tree = load_tree(project_root) return { "project_root": str(project_root), "config_source": str(config_path) if config_path else None, "inline": inline, "signals": signals, "tree": tree, } if __name__ == "__main__": print(json.dumps(build_context(), indent=2, ensure_ascii=False))这段代码虽然简陋，但已经把context-mode的三个基本操作都走通了：find_config负责向上查找到项目根目录，detect_environment负责采集 Git 状态，load_inline_config负责加载显式声明。运行后，它输出的 JSON 就是一份“当前上下文快照”。我会把这个快照交给 AI 工具、shell 脚本或者编辑器任务，从而实现上下文注入。
实际部署时，我建议给ctx增加一个--format=prompt参数，输出结果不再是 JSON，而是适合放进系统提示词的纯文本。比如“你在 payment-service 项目中，技术栈是 Go+Postgres，Git 分支是 feature/payment-fix，仓库一级目录包括 cmd、internal、deploy”。这种文本形式对大模型更友好，也更容易调试。
2.3 配置文件的优先级与继承
配置文件写多了之后，很容易出现“全局配置把项目配置覆盖掉”的灾难。比如用户在家目录~/.config/context-mode/global.toml里声明了“所有 Python 项目统一使用 pytest”，而某个仓库的.ctxrc却明确要求“必须用 unittest”，最终生效的结果应该以项目为准。
我实现的优先级从低到高是：默认值 < 全局配置 < 用户配置 < 项目配置 < 内联参数。默认值内置于代码，比如超时时间 5 秒；全局配置放在/etc或者安装目录，适合企业统一规范；用户配置放在~/.config/context-mode/，适合个人偏好；项目配置放在根目录.ctxrc，是团队约定；内联参数就是命令行里的--set key=value，临时覆盖任何配置文件。
继承机制采用合并而不是替换。也就是说，项目配置里没有声明的键，会向上回退到用户配置取默认值；但一旦项目配置声明了，全局配置就不能再改。这样做的好处是：每个项目只需要写差异化部分，不用把全量配置复制一遍。比如团队规范文件里有三十条规则，某个微型工具仓库只想额外声明“无部署流程”，它只需要写那一条，其他规则自动从上层继承。
3. 在真实场景里扩展 context-mode
3.1 AI 编程助手：让每个仓库携带自己的开发约定
context-mode对 AI 编程助手帮助最大，甚至我觉得这是第一个值得优先落地的场景。很多人用 AI 写代码时最大的痛点不是模型能力不够，而是模型不知道项目里已经存在的约定。比如你问它“这段 SQL 查询怎么优化”，它给出了通用思路，但你们的规范是“所有 SQL 必须经过 repository 层封装，不能直接写在 service 层”。如果你不在提示词里反复强调，模型很难记住。
我现在的做法是把ctx集成到 AI 辅助工具的启动流程中。工具启动时先运行ctx --format=prompt，把生成的文本注入到“项目级指令”里，然后再开始对话。.ctxrc里我会记录一些描述性字段：
# 项目级 .ctxrc project = "payment-api" stack = "python3.12, fastapi, postgres15, redis7" # 重点约定 conventions = [ "所有数据库异常统一抛出 DatabaseError，由全局异常中间件处理", "接口返回格式使用 {code, message, data} 包裹", "禁止直接修改分表字段，需要走迁移脚本", ]有了这些预设，AI 的回复质量和一致性明显提升。最明显的体验是：以前每开一个新对话都要花三四句话交代背景，现在自动加载后可以直接问问题。而且这个上下文是跟着目录走的，我从payment-api切到>[decay] enabled = true half_life_days = 5 [lock] cooldown_seconds = 60
我强烈建议在产品化的时候把调参入口暴露出来。不同团队的切换频率差异很大，单仓团队几乎不需要冷却时间，而平台组的工程师可能在十分钟内横跨八个仓库，没有冷却时间就会让上下文缓存形同虚设。
5. 常见问题与排查实录
5.1 症状与根因的快速速查表
任何工具用久了都会暴露问题，context-mode也不例外。我总结过一张速查表，排查时先对照症状，再顺着根因去修，效率比漫无目的看日志高很多。
| 症状 | 大概率根因 | 修复方向 |
|---|---|---|
| 切到新项目，AI 还在说上一个项目的规范 | Git 远程地址变化，但缓存没有失效 | 检查缓存键是否包含 git remote，必要时强制清理 |
| 配置文件写了但没生效 | 大小写或者扩展名不一致，.ctxrc文件名被过滤 | 用ctx --debug确认实际加载路径 |
| 上下文总被全局配置覆盖 | 项目配置的优先级计算有 bug，合并顺序颠倒 | 检查项目根目录识别是否成功 |
| 系统提示词过长，AI 开始忽略后半段 | 注入的上下文超过了模型注意力上限 | 用--max-tokens截断，或者把长文档改为引用路径 |
| Git 历史记录导致状态漂移 | 命令历史推断被当成当前精确状态 | 压低历史推断的权重，提高显式配置置信度 |
.ctxrc被误提交到公共仓库 | 缺少 ignore 规则 | 在.gitignore中加入敏感配置类文件，并完善密钥模板 |
看到.ctxrc被误提交这一条，我多说一句。上下文文件里经常会有技术栈、内部服务名、数据库标识这些信息，虽然不一定都是秘密，但尽量别把带密钥的内容写进去。我的做法是上下文文件只写“哪里能找到密钥”的路径，密钥本身从环境变量加载，两边彻底分离。
5.2 调试三件套：dry-run、show 和 audit
排查上下文问题，最怕的就是“黑盒”。状态是经过层层合并、衰减、覆盖之后才注入目标工具的，如果中间环节看不到，出了问题就无从下手。我给ctx专门加了三个调试子命令，这也算是我最想分享的实操经验。
第一个是ctx --dry-run，只执行采集和加载流程，但不出任何效果，把所有中间结果打印出来。适合改造一个新工具前，先检查上下文能拿到什么。第二个是ctx --show，显示最终生效的上下文快照，注意这是经过优先级合并、衰减后的结果，也就是目标工具真正看到的内容。如果--show的结果和你的预期不符，那问题出在配置逻辑，而不是工具调用。第三个是ctx --audit，它会在输出中额外列出“每条配置的来源文件、原始优先级、衰减后的权重”，相当于一个“上下文来源审计表”。比如你看到某条规范实际生效时已经衰减到 0.3，就能立刻明白为什么 AI 不太听这段指令，是时候更新状态了。
这三件套的调试手法对普通脚本也适用。我建议所有接入context-mode的脚本都至少先跑一遍--dry-run，确认看到的上下文字段符合预期再继续。脚本如果直接去读生产环境字段，一旦字段为 None，很容易出现不可预期的行为，而 dry-run 能提前暴露出这些空值。
5.3 小心泄漏你的提示词与密钥
关于安全，这里想提三个真实的坑。第一，上下文文件里不要直接写 API Key 或数据库密码。因为上下文快照经常会被打印到调试日志、被 AI 工具读取、被粘贴到对话里。一旦密钥进入这些渠道，就等于公开了。我会把敏感信息替换成env:PAYMENT_DB_PASSWORD这样的占位符，目标工具在注入时从进程环境变量里读取真实值。
第二，不要无意识地暴露出内部路径。上下文快照一旦导出，目录结构、仓库名称、内部包名都会被记录。做演示或者贴 issue 时，最好用ctx --redact把内部路径脱敏，替换成/internal/project。我见过有人截图时忘了打码，直接把整个仓库的目录树漏了出去。
第三，AI 工具返回的内容能被记录成日志，但前提是系统提示词本身不包含敏感数据。上下文模式的价值是“让 AI 更懂项目”，但懂到内部数据库地址就够了，不应该下一步就把它引向连接内网的细节。最好的边界是：上下文只描述“行为和规则”，不描述“凭据和通道”。
写在最后的一点个人经验
我最初写context-mode只是为了让 AI 编程助手少问几句“你在哪个项目”，没想到最后它成了我所有开发流程的隐形基础设施。终端提示符、AI 对话、脚本参数、笔记模板，全都由同一套上下文驱动。边界把控则是我踩过坑后总结出来的：上下文应该默认“少而精”，只注入影响行为的内容，而不是把所有能探测到的信息一股脑塞进去。给系统提示词瘦身，比给模型增加参数预算更有效。
你如果也想在自己的工作流里引入这套思路，我建议从最小的一步开始，先写一个能输出 JSON 快照的ctx脚本，然后接到终端提示符上，观察一天。你会很快感受到“工具知道我在哪”和“工具不知道我在哪”的巨大差别。之后再考虑扩展 AI 提示词注入、项目级配置文件、衰减调优这些进阶机制，一次只加一层，每次都能稳定可控地看到效果。
