企业官网建设流程全解析

如果你和我一样，几乎每个工作日上午都在命令行里和大模型来回提问，大概率撞见过这类让人抓狂的回答：明明已经切换到了另一个项目目录，模型却还在引用上一个仓库的文件名，甚至连上一个项目的技术栈都能混进来；又或者，对话稍微长一点，早先约好的输出格式和关键约束就会悄悄失效，模型开始自由发挥。我最初把这归咎于模型健忘，后来才想明白，问题出在“上下文”这三个字上——我们没有给它一个干净、稳定、和当前工作现场一致的上下文。为了收拾这个烂摊子，我写了这个小工具，名字就叫 context-mode。

老实说，context-mode 不是什么高深的框架，它就是一个管理上下文注入的命令行小工具。核心思路只有一句话：把上下文分成固定层，用显式命令切换、叠加和释放。下面这篇记录，就是我从踩坑到把它跑稳的全过程，希望能给同样被上下文污染折磨的人一些思路。我会把设计动机、实现细节、实测效果、踩坑链路都摊开来讲，不藏私。

1. 为什么一个“上下文开关”会变成独立工具

1.1 从一次翻车现场说起：上下文溢出毁了整段问答

先讲一个具体场景。某个下午，我在“某跨平台系统”里排查一个登录接口的鉴权问题，已经和模型来回聊了四五个版本，把旧拦截器、新网关、前端跳转逻辑都贴进了对话。后来同事喊我帮忙看另一个项目的前端样式问题，我直接在同一个终端会话里切到那个目录，继续问。结果模型给出的建议全部基于旧项目的代码结构和依赖，甚至建议我改一个根本不存在的样式变量。那一刻我意识到，对话上下文的惯性比我想象中顽固得多。

更隐蔽的问题在于上下文溢出。长会话进行到后半段，早期那些真正重要的约定——比如“不要修改公共工具函数”“错误码统一走ErrCode枚举”“代码注释必须写清楚为什么”——已经被几十轮无关的报错和试验性代码挤出了注意力范围。模型不是不遵守约定，而是根本快忘了它们存在。它回答得越来越像一台刚启动的机器：礼貌、泛化、充满“通常来说”，完全不像刚才那个状态良好的结对伙伴。

这种经验很多人应该都有。我最初也试图通过“把约定重复一遍”来补救，结果发现每次都要重新解释项目背景，烦，而且容易漏。于是我决定把“上下文供给”做成一个显式的、可以随时切换的工具。不要靠人脑记忆，也不靠模型猜，而是由工具负责把正确的内容放到正确的位置。

1.2 三个痛点：惯性、漂移与预算浪费

在动手写工具前，我先把自己日常使用模型的场景盘了一遍，最后归纳出三个无法靠“更聪明的提问”解决的痛点。

第一个痛点是上下文惯性。模型会沿用过往前置上下文回答新问题，而这种沿用在跨项目、跨任务时是非常有害的。第二个是上下文漂移。切换目录、切换分支之后，旧上下文仍然残留在会话里，模型对“当前你人在哪里、手上是什么任务”毫无概念。以前我只能在新提示词里手写“当前我们在 XX 项目里，请忽略上面所有内容”，很狼狈。第三个是预算浪费。模型服务的上下文窗口是有限的，而动态生成的日志、扫描结果、报错堆栈、无关代码片段，都在快速消耗窗口，真正重要的任务信息反而放不进去。

后来我又补充了另一个观察：不是所有上下文都同等重要。对于当前任务来说，核心是“项目到底是什么样、技术栈是什么、关键文档在哪、最近改了什么”。对一个常在多个仓库之间切换的开发者来说，手动在提示词里重新粘贴几百行文档是最烦的操作，而那恰恰是 context-mode 瞄准的场景。

1.3 为什么不做成“自动检测”？

有人会说，既然痛点这么明显，为什么不自动检测当前目录和分支，自动注入上下文？我试过。用目录名做自动绑定看似合理，但实际上你打开某个目录不一定代表要问那个项目，可能只是找一下文件顺便切过来的。自动检测出的“有用信息”经常不是当下真正需要的，比如它会塞进去一堆仓库里过时的设计稿说明。

更重要的是，自动注入不可预测。开发者没法向模型解释“这次为什么加了这些上下文”，因为工具自己也没有给出一份可审计的清单。所以 context-mode 从一开始就选择了“显式进入、显式退出”：模式切换是有意图的，是有迹可循的。你明确告诉工具当前处于哪个上下文，工具再把这层上下文完整地交给模型。宁可多一次命令输入，也不要不可控的自动注入。

2. context-mode 的设计骨架：分层上下文与显式切换

2.1 四层上下文的职责划分

我把上下文分成四个固定层，每个层解决不同的问题。这个是整个设计的地基，后面所有组装、切换、释放逻辑都建立在它上面。

这四层的关系，可以类比成浏览器开发者工具里的样式层叠。base 就像用户代理样式，是默认底子；project 像页面自己的样式表，决定了大部分表现；task 像内联样式，权重更高；session 则是临时覆盖，只在当前会话生效。因为有固定的覆盖顺序，模型最终看到的上下文就是一层一层叠加后的结果，不会混乱。

这四层的职责边界一定要清楚。我见过一些工具试图把所有东西塞进“项目上下文”一层，结果上下文变得臃肿且不可控。把系统约定放到 base 层之后，不管切到哪个项目，模型的输出格式和边界约束都稳定；把任务描述单独拎出来之后，模型在回答具体问题时能直接引用任务验收标准，而不是从仓库文档里大海捞针。

2.2 一份 YAML 配置管住所有模式

模式的定义我用了 YAML 文件，放在每个仓库的.contextmode/config.yml里。这样项目成员可以共享同一套上下文配置，新人进来后跑一条初始化命令就能拥有与老手一致的“项目理解”。

配置大致长这样：

modes: backend: project: backend-svc docs: - README.md - docs/auth-flow.md build: true tools: - repo_status - recent_commits budget: 3000 frontend: project: web-console docs: - README.md - src/router.md budget: 2500

docs是静态声明的关键文档列表；tools是动态命令，执行后会生成一段文本并被注入；budget是这一层模式的 token 预算上限。为什么用 YAML 而不是直接在代码里写死？因为我发现每个项目需要的上下文差异太大了。后端项目要注入鉴权流程和数据库模型，前端项目要注入路由约定和组件库风格，用一个固定的模板去套所有项目会非常笨拙。把配置放在仓库里，每个人都可以根据自己熟悉的领域微调，也可以让工具从仓库历史里自动补充。

配置文件的解析不用做得复杂，能识别列表、映射和简单的变量展开就够了。我最初想把变量展开做成完整的表达式引擎，后来发现那是过度设计，因为实际用到的变量只有repo_root、branch、head_sha这几个。保持配置文件的简单，才能让它成为团队都能看懂的东西。

2.3 切换指令与“进入即生效”

context-mode 的命令行交互我最终收敛成三组操作：cm enter、cm attach、cm exit。

cm enter backend进入 backend 模式，工具会立即按照配置组装上下文，生成一份当前上下文快照，并提示“已注入多少 token”。cm attach issue-1832是挂载一个任务上下文，把任务描述、相关文件、验收标准追加到当前模式的 task 层。cm exit则退出当前模式，同时把 session 层彻底清空。

“进入即生效”是这个工具交互设计里的关键。也就是说，模式切换的瞬间，下一轮模型的输入就已经变成新模式下的上下文了。你不用再等下一次提问时才被动感知变化。我给你一个直观例子：

$ cm enter backend [context-mode] backend context loaded, budget=3000 [context-mode] layers: base(500) project(1800) task(700)

看到这个输出，你就能确认工具到底往对话里加了什么，什么优先级，占了多少预算。这就解决了自动注入“黑盒”的问题。

一个非常重要的配套动作是：切换模式后，如果模型会话里已经有上一轮历史，你应该先发起一条新的对话指令或者清空当前会话历史。因为 context-mode 负责的是“下一次提问时的背景”，但它不会替你抹掉已经存在的旧对话记录。这个坑我踩过几次，后面会专门讲。

3. 核心实现：上下文组装、token 预算与增量更新

3.1 三路信息源如何合并成一份干净上下文

context-mode 组装上下文时，信息来源主要有三路：静态声明、动态命令、缓存快照。静态声明是配置文件里的docs等字段，内容稳定；动态命令是运行repo_status、recent_commits这类工具获得的实时输出；缓存快照是上一次组装时生成的摘要文件，避免每次提问都重新对项目做全量分析。

这三路信息会按照一个固定顺序拼接成最终文本：

1. base 层：系统约定
2. project 层的静态文档
3. project 层的动态仓库状态
4. task 层的附件内容
5. session 层的临时说明

排序的原理是，把最具体、与当前问题最相关的信息放在离用户最近的位置。你有没有观察过一个现象：你把任务描述放在对话最后，模型往往对这段内容的记忆最清晰。这是因为在生成回答时，靠近问题语句的内容往往拥有更高的“注意力权重”。所以 task 层的内容永远在最终组装阶段被放到用户提问的前一句位置，而不是和 project 层混在一起。

组装完成之后，工具会计算这段文本占用的 token 数，并显示出来。如果总预算超了，就启动裁剪逻辑。裁剪逻辑不是简单地从尾部截断，而是按优先级从低到高递减，这一点后面会展开。

3.2 token 预算：先保任务描述，再裁项目文档

token 预算分配是让 context-mode 真正可用的关键。我一开始不设预算，结果模型经常在长文档被截断后断章取义。后来我模仿服务端的限制做了预算表，默认参考如下：

这五个数字不是拍脑袋定的。它们的比例参考了实际测试：系统约定必须足够覆盖输出约束，但超过 800 token 就是浪费；项目文档可以多一些，因为它是模型理解仓库的基础；任务描述是当前问题的核心，优先级最高，所以要给足；缓冲则是给 token 统计误差留的余量。

裁剪顺序也很重要。我采取的顺序是：先裁动态状态，再裁项目文档，最后才是任务描述。原因是动态状态虽然看起来有用，但大多是可以从实时输出里重新生成的，去掉一部分不影响大局；项目文档要从长文档中截取关键段落；任务描述和当前问题的相关度最高，动它代价最大。预算裁剪的时候，工具会在最终上下文里插入一个简短的说明，告诉模型“以下文档因预算限制被截断，请谨慎使用”，这比直接静默截断要健康得多。

token 统计要用一个可靠的开源 tokenizer 来做，而不是按字数估算。代码里每个符号、空白符和换行都会消耗 token，中文字符的切分逻辑也和英文不同。我最初用简单的字符数除 4 来估算，结果偏差很大，导致模型被截断。

3.3 增量更新：别每次提问都扫一遍全仓库

context-mode 最早一版是个很莽的实现：每次提问前都全量扫描一次仓库，把所有相关文件读一遍。结果是提问间隔从 1 秒变成 8 秒，而且模型回答质量并没有因此变好，因为塞进去的东西太杂了。为了提速，我改成了增量更新方案。

增量更新的核心思路是：只有变更过的内容才重新生成摘要。我监听项目目录里的文件变化事件，发生修改的文件会被标记并重新生成摘要；同时，仓库的版本状态变化才触发repo_status的输出刷新。缓存的 key 由一个组合值生成：模式名 + 文档列表 + 仓库版本状态 + 缓存文件修改时间。

这样日常提问时，工具只需要读几份缓存摘要，等待时间可以忽略；只有在跨项目切换、或者仓库改动被检测到时，它才会重新做一轮全量扫描。这个方案后来被证明是效率提升最大的改进，比调 token 预算更明显。缓存目录我放在了系统临时目录下，避免污染仓库状态，也避免了被版本管理工具误伤。

4. 实际跑起来：日常问答与跨项目切换的完整演示

4.1 初始化一个可用的模式目录

说再多设计，不如看一次实际操作。假设我新接手一个仓库，第一步是初始化 context-mode：

$ cm init --root . created .contextmode/config.yml

然后编辑配置文件，把backend和frontend两个模式定义好。定义完执行cm enter backend，工具会输出组装后的上下文规模和分层信息。这一步非常有用，因为它能在正式提问前暴露问题：如果项目文档太多，就会在预算表里看到 project 层超预算，你就有机会调整配置，而不是等到模型回答问题时才后悔。

我把初始化流程设计成“配置优先、显式确认”的节奏，就是为了让开发者在输入任何问题之前就掌握上下文的全貌。这个阶段看起来多花了几秒钟，实际上省的是后面大量来回纠正的时间。

4.2 同一句话，注入前后的回答差距

为了直观对比，我用同一句话做了一组最简单的测试。问题是：“这个接口的鉴权应该加在哪一层？”

没有使用 context-mode 时，模型的回答非常“通用”，它给出的建议几乎适用于任何技术栈：先给你列举常见的鉴权位置，然后说“具体取决于你的架构设计”。这种回答不能说错，但放在一个真实项目的排查现场，等于没说。你真正需要的不是方案指南，而是“这个仓库里的鉴权应该怎么加”。

使用 context-mode 之后，工具的 project 层注入了仓库结构文档和认证明细文档，task 层注入了当前接口的文件路径和调用链，模型直接给出了一个明确结论：应该加在网关的鉴权过滤器里，并引用了仓库中现有的拦截器类名和方法位置。这已经不像是通用模型的回答，更像是一个熟悉这个仓库的同事在说话。

我整理了一个快速对比表：

这个差异是所有模型提示工程里都在追求的目标，context-mode 做的事情很简单，就是把“上下文供给”从手工粘贴变成了自动化流程。

4.3 跨项目切换：从 backend 到 frontend 的实测

跨项目切换是我最看重的场景。流程和前面一样，先cm enter frontend，然后按约定发起一条新会话，再问新问题。

我把同一个问题“登录失败后前端应该把用户带到哪个页面？”丢给模型。在 frontend 模式下，模型基于 web-console 的 README 和路由文档回答，会提到登录失败路由和密码重置页面，并引用对应组件文件。整个回答完全没有受到 backend 会话里那些接口鉴权讨论的影响。

这个测试看起来很基础，但它验证了一件事：把上下文按模式隔离，效果是显著的。如果你只是简单地在同一个会话里改几行系统提示词，模型仍然能看到之前所有的对话历史。context-mode 不能替代会话历史的清理，所以它在跨项目切换时其实是一个组合策略：工具负责注入准确的当前上下文，人负责在切换时清空历史。两者配合，才能做到干净切换。

5. 踩过的坑与排查链路：重复注入、缓存失效与预算超支

5.1 同一个上下文被重复注入的根因

工具上线后不久，我遇到一个诡异问题：模型在一个很简单的 bug 排查里反复提到同一个类文件，就像上下文里出现了重复片段。我原本以为是模型的问题，后来排查发现是 context-mode 自己的问题。

原因很简单：backend 模式的 project 文档里声明了docs/auth-flow.md，而我在某个 issue 的 task 附件里又挂载了同一份文件。两份来源都进了上下文，导致模型看到两份几乎完全一样的内容，回答时就显得“啰嗦”。解决方式是在组装时对每个来源片段做内容指纹去重，而不是简单按路径去重。如果两份内容相似度超过一个阈值，只保留优先级高的那份。这个修复之后，重复问题彻底消失。

这个坑的启示是：上下文组装的每一层都会从多个来源收集内容，人的记忆容易忽略“同一份文档可能出现在两个层”。工具必须显式做去重，否则模型就被迫阅读重复内容，既浪费预算又干扰回答。

5.2 旧摘要顶替新代码：缓存 key 设计失误

第二个坑更加隐蔽。有一天我改完一个函数的签名，再让模型基于当前代码给出建议，它仍然按照旧签名回答。这是典型的“旧摘要顶替新代码”现象。

排查链路是这样的：我第一时间怀疑是模型缓存，重发一次提问后仍然复现。接着检查 context-mode 的缓存目录，发现repo_status的输出还是旧的。问题定位在缓存的 key 设计上：我当时用了“模式名 + 文档列表 + 仓库版本状态”作为 key，看起来没错，但仓库的 HEAD 值没有变，因为我只是改了工作区文件，还没有提交。也就是说，HEAD 不能作为工作区内容的唯一版本号。

修复方式是把缓存 key 换成“模式名 + 文档清单 + 工作区变更摘要的哈希”，并在每次组装前快速比对摘要哈希。这样只要有任何文件改动，摘要哈希就会变，缓存自然失效。这个改动让我重新认识到：工具理解“项目当前状态”，不能只看版本管理状态，还要看工作区有没有未提交的改动。

5.3 token 估算偏差：模型报错才追回来的教训

第三个坑发生在预算调得很紧的时候。我把一个模式的 budget 设成 3900 token，结果模型第一次调用就报上下文超长，这让我一度怀疑是资源限制判断错误。排查之后发现，开源 tokenizer 和模型服务端的统计逻辑不完全一致，加上我在组装时多塞了几个换行符和格式转义符，实际消耗比估算高出了大概 15%。

解决方案分两步。第一步，预算统一预留 20% 缓冲，不设到极限；第二步，每次模型调用后，工具会读取服务端返回的用量信息，把它反馈到缓存里，让下一次组装自动把预算压一点。这本质上是把静态预算变成了带反馈的动态调节。经过这个修复，超长报错基本消失，剩余偏差也被缓冲层消化掉了。

这个教训告诉我，任何“本地估算上下文长度”的做法都需要对实际服务端逻辑做校准，不能盲目相信估算结果。即使校准过，也必须有缓冲机制托底。

5.4 切换太频繁导致上下文残留

最后一个坑是最高频的。几个小时内快速进出多个模式，模型会把前一个模式的代码风格带入新任务。比如我在 backend 模式里聊了一堆错误码规范，切到 frontend 模式问一个组件样式问题时，它突然开始建议我用错误码枚举来管理样式变量，非常跳跃。

根因很清晰：session 层只在进入时写入，没有在退出时清理。我后来规定cm exit时必须把 session 层彻底丢弃，并且输出一条提示：“已退出 backend，session 层已清理”。同时，在enter一个新模式之前，工具会检测当前是否存在未退出的旧模式，并自动执行一次旧模式的清理动作。这个“退出即清理”的约定，让切换变得可信可控。

这也解释了为什么日常生活中切换模式后的残留问题是“人很难感知”的：它不像代码错误那样报错，而是让模型的回答风格在悄悄漂移。只有依赖强制清理，才能从根本上避免。

6. 值得继续扩展的方向：从手动模式走向上下文路由中枢

6.1 自动推荐模式：建议而非强制切换

用了一段时间后，我明显感觉“手动 enter”还是有一点点负担，于是试过完全自动切换。结果发现自动切换的误判率不低，比如你在 backend 目录下只是临时翻一下前端路由文件，工具就切到 frontend 模式了，反而打断了当前的上下文。

后来我改成了一个折中方案：基于当前目录、分支、最近编辑过的文件，给出一句模式推荐，比如“当前目录匹配 backend 模式，是否切换？”需要开发者一键确认。这个交互模式很像编辑器里的快速修复建议——把判断权最终保留给人，但让机器提供足够便捷的提示。这样既保留了显式切换的确定性，又降低了操作成本。

6.2 任务层接入检索：预算不够用时的降级策略

当任务层需要摄取的内容超出预算，最自然的做法是让任务层变成一个检索入口。在模式定义文件里可以加一个检索字段，工具会从仓库里找到相关代码片段，以摘要形式注入任务层。这样就不用把整份文件塞进上下文，只保留和当前问题直接相关的部分。

这里有一个容易忽略的细节：如果仓库还没有建立索引，不要直接报错。你应该降级为关键词搜索，找到粗匹配的文件路径，再读文件的开头几行作为摘要。降级方案的体验远好于让工具直接失败。实际上，检索和关键词搜索的精度差异，只在非常编码密集的任务里才显得明显，日常问答用降级方案也能获得足够好的效果。

6.3 把模式导出为标准 JSON，供其他工具复用

模式切换的产物其实不只是一个命令行提示。每一份组装好的上下文，都可以序列化成标准 JSON 文件，包含各层来源、预算、文档摘要、动态状态、任务附件列表。这个 JSON 可以被 IDE 插件、CI 机器人、代码审查助手复用，保证整个工作流里的不同工具看到的是同一个“项目现场”。

举个例子，我可以让代码审查机器人在合并请求前，加载同一个任务层上下文和项目文档，那么它针对代码风格、接口兼容性、迁移规则给出的意见，就会比“裸审查”贴切得多。这件事我目前只做了一个可用的原型，离完整产品还有距离，但它是我认为 context-mode 最值得深入的方向——从一个开发者的本地工具，变成整个团队共享的上下文中枢。

最后分享一个小技巧：我把cm enter和cm exit封装进了 shell 函数，跟随终端多窗口会话的窗口名自动执行。窗口名是backend时自动进入 backend 模式，切到另一个窗口就自动退出并清空 session 层。配合 context-mode 后，我基本不再手动粘贴项目说明，整天的提问质量明显稳定。上下文这件事，不应当靠人脑记忆，也不该靠运气，而是一个需要被认真对待的工程问题。