企业官网建设流程全解析

光标停在一个一千多行的 Service 文件里，你想让 AI 解释一下某个函数在极端输入下为什么会抛异常。你把问题发出去，它却盯着文件头部的装饰器分析半天，甚至建议你去改另一个模块的代码。这种"答非所问"我遇到过太多次，一开始以为是模型不行，后来才意识到：问题不在模型，在于 context-mode 没设对。

context-mode，直译是"上下文模式"，在 AI 辅助编程和大模型应用开发里，简单说就是"决定模型在生成回复之前能看到哪些代码、以什么顺序和粒度看到它们"的一套策略。同一段代码，同一个 prompt，用全文模式喂和用聚焦模式喂，效果可以差出一个数量级。这篇文章不打算空谈概念，我直接拿自己折腾的一套 context-mode 模块来讲：它解决了什么、主流的模式有哪些、怎么从零实现，以及我踩过的几个坑。适合正在做内部 AI 编程助手、代码问答机器人、或者单纯想提升日常 AI 用码效率的工程师参考。

1. context-mode 到底在解决什么：上下文管理与任务失配的痛点

1.1 一个每天都在发生的"灵异事件"：AI 改错了别的文件

我最早天真地以为，AI 编码助手的效果上限取决于模型本身，后来发现真正拉胯的其实是上下文管理。举个例子：我维护了一个中型 Python 服务，120 个文件、3 万多行代码。某次我想让 AI 帮我重构订单状态机里的一个函数，为了让信息足够全，我把整个 services 层都粘进了对话。结果模型把"订单状态"的例子全部替换成了"用户状态"的注释，还在另一个文件里凭空加了几个无关的钩子。

问题出在哪？它看到了太多东西，注意力被无关代码稀释了。人也是一样，让你在五百页源码里找一个 bug，你也不会从目录页开始逐行扫。所以 context-mode 要解决的第一个问题，是给模型一个与任务匹配的视野：解释单个函数时，只给函数体、调用方、被调用的依赖；做跨文件重构时，再给接口定义和调用图；回答项目级问题时，给的是结构树和检索索引。视野不对，能力再强也发挥不出来。

1.2 上下文窗口的物理边界：128k 到底够不够

我刚开始设计上下文方案时，觉得 128k 窗口总够用了吧，但一算账就傻眼。主流模型标称 128k tokens，实际上能安全使用的远低于这个数：系统提示一般吃 500 到 2000，对话历史越积越多，输出还得预留大几千到一万多，真正留给代码的往往只剩一半。而代码的 token 消耗比想象中快得多，平均一行代码约 5 到 15 个 token，一个 1000 行的文件轻松破万。也就是说，一个 128k 窗口在留足输出和系统提示后，塞 10 到 20 个中等文件就到头了。

真实项目的体量呢？我那个 120 文件、3 万行的服务，纯源代码折算下来就有 40 到 60 万 token。哪怕只把和 main 分支强相关的文件全部加载，也动辄 5 万到 10 万。这不只是成本问题，还直接影响体验：token 数量翻倍，首 token 响应时间肉眼可见地拉长，工具一旦没了"即时感"，人就再也不愿意用了。所以"窗口够不够"从来不是硬性指标，而是策略问题——必须在有限的预算里做精确取舍。

1.3 核心认知：上下文质量远比数量重要

很多人遇到窗口不够的第一反应是"换更大的窗口"，但我大量测试后的结论是：上下文质量远比数量重要。我做过一次对比实验，同一个函数、同一个审查任务，分三组投喂：第一组只给目标文件，约 8k tokens；第二组加一个强相关依赖文件，约 12k tokens；第三组再加三个"看起来相关但并不重要"的文件，约 20k tokens。结果第三组的正确率不升反降，甚至还出现了两处虚构的 API 名称。

这和注意力机制的研究结论一致：无关信息会稀释 token 间的注意力权重，让模型更倾向于生成"看起来合理但实际错误"的内容。所以我把 context-mode 理解成一次"信息预算管理"——预算有限，必须花在刀刃上。没有银弹，只能在模式和场景之间寻找匹配，这也是下文要展开的核心。

2. 五种常用 context-mode：自动、全文、聚焦、滑窗与分层的取舍

2.1 自动模式：把判断交给信号与规则

自动模式是我日常使用时的默认选项。它不依赖用户手动指定范围，而是通过一组信号自动决定加载策略：当前光标所在文件、git diff 里改过的文件、文件最近修改时间、项目的模块结构，以及用户提问里出现的符号名称。简单实现甚至不需要模型参与推理，纯规则就能跑：如果问题里出现了具体函数名，走聚焦模式；如果带着 git diff，就按 diff 构建上下文；如果什么信号都没有，退回滑窗模式。

自动模式的好处是不打扰用户，开发者在编辑器里自然地问问题就行。坏处是信号判断错误时，整个回答一开始就跑偏，而且用户很难看出哪里错了——界面上一片正常，但结果完全不对。我见过很多团队做自动模式只做一半，把"自动"等同于"全塞进去"，那其实是偷懒。真正的自动模式应该是一套完整的信号优先级系统，判断逻辑越透明，出问题时才越好排查。

2.2 全文模式：门槛最低，翻车也最多

全文模式就是把整个仓库或整个模块的代码全部塞给模型。对一个小工具、只有几个文件的项目来说，这是最简单可靠的方案：信息完整，不会出现"模型看不到某个定义"的抱怨。但项目一旦超过几万行，问题就接踵而至。第一，可用窗口塞不下，被迫截断；按行截断会把代码截成语法残废，模型对着半个函数猜，越猜越离谱。第二，就算硬塞进去了，模型推理速度变慢，还容易在无关信息里迷失。

我现在对全文模式立了一条规矩：只对 30 个文件以内、总代码不超过 2 万行的项目使用。超过这个体量，强制走聚焦、分层或者检索方案。为什么是 2 万行？按每行平均 10 个 token 估算，2 万行大约是 20 万 token，即便在 200k 窗口里也占到了九成以上，几乎没有给对话和输出留余地。超过这个线再玩全文，纯属给自己找不痛快。

2.3 聚焦模式：围绕锚点的强相关筛选

聚焦模式是我做代码审查和单点修改时的主力。思路是：给定一个锚点，比如当前文件、改动区域、目标函数，只把强相关的代码单元拉进上下文。强相关的定义我列了一个优先级清单：直接 import 的依赖、被当前函数调用的函数定义、调用当前函数的上游调用方、同一模块里的兄弟组件。

这套逻辑依赖静态分析，我通常用 tree-sitter 解析出符号表和调用关系，条件允许就再接一层 code graph。聚焦模式最省 token，回答也最贴题，代价是静态分析在动态语言上容易漏。Python 的鸭子类型、Ruby 的 metaprogramming，都会让调用关系分析产生误判。所以我坚持在聚焦模式后面再接一个文本检索的兜底：静态分析给不出依赖时，用 embedding 搜索相关代码块，两套机制一起上才能覆盖大多数情况。

2.4 滑窗模式：动态跟随光标的小窗口

滑窗模式最像 IDE 里"我当前能看到的代码"。它不加载整个文件，而是以光标或当前函数为中心，加载前后若干行，通常控制在几百行内。优势是极省 token、响应快，非常适合解释单行表达式、生成局部测试、补全函数实现这类贴近光标的轻量任务。劣势也明显：当模型需要参考窗口之外的类型定义或函数入口时，它只能靠猜。

我在自己工具里做了一点改进，管它叫"多级滑窗"：第一级是光标所在的 ±150 行；第二级是在这 300 行里做一次轻量扫描，如果出现未定义的标识符，自动把该标识符的定义页拉进来，相当于"按需扩窗"。这个改进让滑窗模式的可用性提升不少，代价是每次光标移动时都要做一次符号扫描，对索引速度要求更高，具体的优化手段放在第 3 章讲。

2.5 分层模式：先看地图，再放大到街道

分层模式是我最推荐用来处理跨文件重构的方案。它模仿人类工程师上手新项目的思路：第一层给项目结构树，包括目录层级、模块职责说明、README 摘要、git 状态；第二层给当前正在编辑的文件或本次要改的 diff；第三层再按需拉取被调用函数、接口定义、相关测试用例。

这样模型先在心里建起一张"地图"，再根据具体问题把某一个区域放大到街道级别，既不容易漏掉关键依赖，也不容易在细节里迷失。实现上需要一套"按需展开"的机制：用户或规则指定下一步要看哪个节点，系统才去加载对应文件内容。分层模式最灵活，但也最复杂，判断该展开哪一层本身就可能出错。不过对于跨文件重构、新项目答疑这类复杂任务，多花这点复杂度非常值。

2.6 五种模式横向对比

3. 从零实现一个 context-mode 模块：索引、打分、预算与增量更新

3.1 第一步：把仓库切成标准上下文单元

实现 context-mode 的第一件事，是把整个仓库拆成可以单独调度和打分的"上下文单元"。我实践下来用两级粒度：文件级和符号级。文件级就是整个文件，理解简单、粒度粗，适合对整体做介绍；符号级是函数、类、宏定义这些 AST 节点，粒度细，能精确控制喂多少代码，但需要额外维护符号与文件、行号的映射关系。

切分时我强烈建议用 tree-sitter，不要用正则。tree-sitter 能稳定识别各语言的函数和类边界，即使代码格式不规整也能正确切分。如果没有 AST 能力，退而求其次可以用空行和缩进做启发式切分，对 Python 这类缩进敏感的语言效果尚可，对 JS、Java 就差点意思。切完之后我会建立一个符号映射表：符号名映射到所在文件、起止行号、依赖列表、被谁引用。这张表构建一次，之后靠文件修改时间做增量更新。这一步是整个模块的地基，地基没打好，后面的相关性和预算分配全是空中楼阁。

3.2 相关性打分：静态调用图优先，embedding 兜底

判断"哪些上下文单元该进窗口"时，我按优先级用三层方案。第一层是静态调用图：从锚点出发，沿 import 和函数调用做一到两跳的 BFS，命中即强相关，必定注入。第二层是文本检索：把用户问题做 embedding，在预建的 chunk 向量库里做相似度搜索，找出语义相关的符号和文件，用来兜底静态分析看不到的隐藏依赖。第三层是启发式信号：git diff、文件最近修改时间、同目录文件的血缘关系，用来微调权重。

这里有一条关键经验：千万别只依赖 embedding。embedding 在语义相近时很好用，但它不感知控制流，文件里所有代码在它看来都是平均地"相关"。而调用图能告诉你因果关系：A 调用了 B，B 出问题会影响 A。我遇到过不止一次，某个函数名和一个不相关的工具函数相似度极高，embedding 打分冲进前三，结果把 AI 带偏。后来我把静态调用图的权重固定调高，embedding 只作为补充，误报率才明显下降。

3.3 token 预算分配：给响应留出保命空间

预算分配看着简单，坑却最多。我目前的分配比例是：系统提示和任务描述占 10% 到 20%，核心上下文占 50% 到 60%，辅助上下文占 20% 到 30%，输出预留至少 10% 到 20%。这里的"输出预留"最容易被忽略，尤其是生成代码或长文档时，一旦预算被上下文吃干，模型会在生成中段被硬截断，你拿到的不再是完整代码，而是半截函数加一句"以下省略"。

计算 token 别用字符长度估算，字符数和 token 数差别很大。要么用 tiktoken 处理 OpenAI 系模型，要么用模型的 tokenizer 处理本地模型。我在项目里封装了一个 BudgetAllocator，输入任务类型和锚点，输出每个上下文单元允许占用的 token 上限。任务类型是重构时，给核心上下文多留；任务类型是问答时，给检索结果多留；任务类型是写长文档时，输出预留直接提到 30%。

3.4 增量更新与缓存：别让模式切换产生明显延迟

没有增量更新和缓存，context-mode 只能活在 Demo 里。我最早写过一版每次请求都全量重建索引的代码，在 120 文件的项目里，平均上下文构建耗时 200 毫秒以上，加上模型推理，整个工具慢到没人愿意用。后来的优化我拆成三层：第一层是索引层，文件保存时按 mtime 增量更新符号表和 embedding；第二层是向量层，embedding 按文件加版本号缓存到本地数据库，版本没变就不重算；第三层是上下文构建层，把"锚点加模式加预算"这几个关键参数做哈希，短时间内的重复请求直接复用上一次构建结果。

做完这三层优化，上下文构建阶段稳定降到了 30 毫秒以内，工具终于有了"顺手"的感觉。这一步很容易被忽略，但它决定你的工具是停留在玩具阶段，还是真正能进生产环境。

3.5 最小可运行示例与调用方式

下面是一个简化但能跑通思路的骨架，方便你复现整个调度流程：

import os from dataclasses import dataclass @dataclass class ContextUnit: name: str content: str token_count: int = 0 related_score: float = 0.0 class RepoIndex: """文件级 + 符号级索引，启动时构建，mtime 增量更新""" def __init__(self, repo_path: str): self.repo_path = repo_path self.file_index = {} # path -> (mtime, token_count) self.symbol_map = {} # symbol -> ContextUnit self.build_initial_index() def build_initial_index(self): # 用 tree-sitter 解析所有源文件，填充 symbol_map pass def is_dirty(self, path: str) -> bool: mtime = os.path.getmtime(path) old = self.file_index.get(path, (0, 0)) return mtime > old[0] class BudgetAllocator: def __init__(self, max_tokens: int): self.max_tokens = max_tokens self.output_reserve = int(max_tokens * 0.15) def trim(self, units: list[ContextUnit]) -> list[str]: units.sort(key=lambda x: -x.related_score) budget = self.max_tokens - self.output_reserve result = [] used = 0 for unit in units: if used + unit.token_count > budget: continue result.append(unit.content) used += unit.token_count return result class ContextBuilder: MODES = ("auto", "full", "focus", "slide", "layered") def __init__(self, repo_path: str, max_tokens: int = 8000): self.repo_path = repo_path self.max_tokens = max_tokens self.index = RepoIndex(repo_path) self.allocator = BudgetAllocator(max_tokens) def build_context(self, mode: str, anchor: dict) -> list[str]: if mode not in self.MODES: mode = "auto" if mode == "full": units = self._collect_full() elif mode == "focus": units = self._focus_by_symbol(anchor.get("symbol")) elif mode == "slide": units = self._slide_by_cursor(anchor.get("file"), anchor.get("line")) elif mode == "layered": units = self._layered_build(anchor) else: units = self._auto_dispatch(anchor) return self.allocator.trim(units) def _focus_by_symbol(self, symbol: str): units = [self.index.symbol_map[symbol]] # 沿调用图 BFS 一到两跳，追加相关单元 return units def _slide_by_cursor(self, file: str, line: int): # 加载 file 中 line±150 行，并按需拉取未定义符号的定义 return [] def _layered_build(self, anchor: dict): # 结构树 -> 当前文件/diff -> 按需展开 return [] def _auto_dispatch(self, anchor: dict): if anchor.get("diff"): return self._focus_by_symbol("diff") if anchor.get("symbol"): return self._focus_by_symbol(anchor["symbol"]) return self._slide_by_cursor(anchor.get("file"), anchor.get("line"))

骨架里的核心流转只有三步：拿到索引、模式分发、预算裁剪。在实际工程里，你还需要根据所用模型的 tokenizer 替换计数逻辑，不同模型的输出预留比例也完全不同，本地 7B 模型和 128k 商业模型在预算策略上的差异非常大。

4. 场景与模式匹配：本地工具里的三次调优记录

4.1 场景一：新项目答疑，从"塞不下"到"够精准"

我优先想聊的是新项目答疑这个场景。团队里新同事刚接手一个服务，第一句话通常是"帮我讲讲这个项目大概是怎么组织的"。最初我用全文模式硬塞，结果 3 万行代码根本进不了 32k 窗口，频繁截断之后，模型给出的项目介绍错得离谱，连模块职责都说反了。

后来我切成分层模式：先给项目结构树和模块职责摘要，占约 4k tokens；再把新同事当前打开的文件加进去，占 2k 左右；最后如果他追问某个模块，再用 embedding 检索相关代码块。实测下来，模型对新项目的描述准确率明显提升，新人也能更快定位到自己的改动范围。这个调优的核心是"先给骨架，再补血肉"。

4.2 场景二：PR 代码审查，按 diff 构建上下文

代码审查是聚焦模式的主场。早期我让 AI 审查整个 PR，把改动涉及的文件全部塞进去，模型经常被十几个文件的改动量吓到，只给出泛泛的"注意测试覆盖"这类废话。后来我改成按 diff 构建上下文：只取 PR 中每个文件的 diff hunk，再为每个 hunk 补齐被调用函数的定义和直接依赖，总预算控制在 16k tokens 以内。

效果非常明显：误报率降低，AI 给出的 review 意见开始落到具体行号和具体风险点上。我在流程里加了一个手动补充入口，审查者觉得 AI 漏了什么文件，可以一键把该文件追加进上下文。这个"允许人为干预"的设计很重要，因为 context-mode 再智能，也不可能永远猜对人脑中的关联关系。

4.3 场景三：跨文件重构，调用图两跳内全量注入

跨文件重构是目前最难处理的场景之一。我在重构一个老的支付模块时，涉及三个文件里的二十多处调用，用聚焦模式会漏上游调用方，用全文模式又塞太多无关模块。最后我采用的是分层加调用图的组合：第一层注入当前要改的文件和它的直接依赖，第二层沿着调用图往上追溯两跳，找出所有会受影响的上游调用方，第三层只加载这些调用方中与当前改动相关的函数体。

这样的上下文组织方式和重构任务的真实依赖关系是吻合的。AI 拿到的不再是"三个文件的所有代码"，而是"改动点加调用影响面"的最小完备集。那次重构里，AI 提前指出一个我漏掉的兼容性问题：某个上游模块在异常分支里直接访问了旧字段名。这就是调用图两跳的价值。

4.4 可复用的配置参数速查表

补充一句：不要为了追求"信息全"把每个模式的预算都拉到窗口极限。我实测下来，窗口利用率在 60% 到 70% 左右时，回答质量和响应速度的平衡点最好。一旦超过 85%，速度和稳定性都会明显下降，收益却几乎为零。

5. 容易翻车的四个地方：相关性误判、快照过期、性能与输出挤占

5.1 翻车之一：文件名相似把 AI 带偏

有一次我问 AI 改订单状态机的一个函数，embedding 检索出来的结果里，某个工具函数因为名字里带着"order_status"相关字样，相似度打分冲得很高，被当成了强相关文件注入上下文。结果 AI 在这个工具函数上做了大量无意义的"改进"，浪费了一轮又一轮对话。

教训是：相关性排序不能只看语义相似度，必须结合静态调用关系加权。名字像不代表逻辑相关，真正的强相关是"当前改动符号被它调用"或者"它调用了当前改动符号"。我在评分公式里把调用图命中项的基础权重设成普通检索命中项的三倍以上，这类误判才明显减少。如果你也在做 context-mode，建议给相似度和调用关系分别打分，不要混合成一个分数。

5.2 翻车之二：缓存快照与磁盘代码脱节

上下文构建的速度优化依赖缓存，但缓存有个致命问题：快照过期。有一次 AI 基于旧版本的文件内容给了重构建议，而磁盘上的代码早在我上一次提问后就被我改了。AI 建议的"新增参数"在最新代码里已经有了，还建议把某一段已经删掉的代码重新加回来，看着特别像模型在胡说。

后来我在所有上下文单元上挂了版本号，来源是文件的 mtime 或 git hash。文件一旦变化，相关的符号级单元立即失效，embedding 缓存也按版本号重新计算。这个机制尤其重要，因为开发场景里文件是高频变化的，不做版本绑定，缓存带来的效率提升会反噬成正确性问题。

5.3 翻车之三：上下文构建吃掉太多响应时间

我在做第一版工具时，把索引构建和 embedding 计算全部放在请求路径里。在 120 文件的项目上，一次聚焦模式的上下文构建要扫全量符号表和向量库，平均耗时超过 200 毫秒。对聊天工具来说这个数字尚可接受，但对编辑器内联问答来说，等 200 毫秒再开始生成，就已经等于"卡了"。

我做的优化前面提过：索引进程常驻，文件变更走事件驱动更新，embedding 做磁盘缓存，上下文构建结果按参数哈希复用。优化后把构建耗时压到 30 毫秒以内。这里我还有一个体会：把"上下文构建耗时"做成指标面板挂在调试页上，比什么都管用。哪个模式慢、哪次检索慢，一眼就能看到，不用靠猜。

5.4 翻车之四：输出预算被挤压到截断

最后一个坑是输出预算被挤压。有一回我让 AI 为一个模块生成完整的使用文档，上下文里塞了大量示例代码，token 预算占到了窗口上限的 95%。结果模型生成到一半被硬截断，文档后半部分全丢，还触发了一次报错。

那次之后我在 BudgetAllocator 里把输出预留从固定比例改成了按任务类型动态调整：代码生成、长文档类任务，输出预留直接设到 30% 到 40%；短问答和解释类任务，再压缩到 10% 到 15%。另外，我给上层接口加了一个字段：如果任务类型没有显式指定，默认按 20% 预留。这个数字来自我的实测经验，可以当作起点，再根据你的模型和使用习惯微调。

最后说点个人体会

折腾了大半年 context-mode，我最深的感受是，它本质上是把"上下文窗口"这个物理限制，转化为一套可管理的工程策略。不是模型越大越好，也不是窗口越长越好，而是让模型在正确的时机看到正确范围的信息。我自己从最初的全文模式一路踩坑，最后稳定在"分层 + 聚焦为主，自动模式为辅"的组合上。最后分享一个实用小技巧：给 context-mode 加一个开关面板，调试时把"本次任务喂了哪些文件、每个文件占了多少 token、相关性分数是多少"打印到日志里。很多上下文问题根本不用猜，日志一拉出来，谁占了大头、谁不该进来，一目了然。这个习惯帮我省下的排查时间，比任何模型调参都多。