企业官网建设流程全解析

1. 这个功能到底解决什么问题：从“答非所问”说起

1.1 没有上下文模式的AI助手像什么

我最近一直在打磨AI辅助编程工具里的一个功能，名字叫context-mode，翻译过来就是“上下文模式”。如果你用过AI写代码，大概率经历过这种场面：你让AI帮忙改一下登录页的表单校验，它却给你重写了一套全新的表单组件，还附赠了两个你没见过的依赖。你问它为什么这么改，它理直气壮地告诉你这是最佳实践。问题出在哪？不在于模型太笨，而在于它根本没看过你的项目全貌。它只看到了你贴在对话框里那几十行代码，却不知道你的团队已经封装了统一的校验工具库，不知道你的组件库里已经存在现成的表单封装，更不知道项目里跑测试时对依赖顺序极其敏感。

这种感觉很像什么呢？像一个临时被叫来顶班的同事，你只递给他一张写着“帮我把这个bug修了”的纸条，他既没看过项目说明文档，也没翻过工作日志，更不知道你隔壁工位那位老哥昨天刚重构了底层数据结构。他能做的只能是根据“纸条上那几句描述”加上自己的惯性理解去猜。大多数情况下，猜出来的东西在原则上没错，但落到具体项目里就是水土不服。

断断续续地踩了很多次坑之后，我越来越清楚地意识到：在AI辅助开发这件事上，回答问题本身不是瓶颈，上下文才是。AI辅助工具不缺模型能力，缺的是对当前项目、当前任务、当前代码状态的感知能力。context-mode这个功能想解决的，就是这个“AI看不见项目”的问题。

1.2 context-mode真正要做的事

把context-mode拆开看，它并不是什么玄学功能，而是一套非常具体的机制：在模型真正生成回答之前，系统先把必要的背景信息收集起来，组装成一个“上下文包”，连同你的问题一起送给模型。这个包里通常包含几种东西：当前打开的文件、项目目录结构、关键配置文件的片段、最近改动过的文件列表、编译报错或静态检查的诊断信息，甚至还包括你自己手动标定为“相关”的其他文件。

听起来不复杂对吧？但真正做起来的时候你会发现问题藏在细节里。上下文包的构建需要回答几个很现实的问题：应该采集哪些文件？采集多深？文件太大怎么截断？项目里有几百个文件，全都塞进上下文里显然不现实。所以context-mode在处理过程中其实做了三件事：采集、筛选、注入。采集解决“有哪些信息可用”的问题，筛选解决“哪些信息值得送”的问题，注入解决“用什么格式送模型才能理解”的问题。这三件事里面，采集最机械，注入有套路，真正难的是筛选。

我见过不少人一听到“上下文”就进入一种信息囤积心态，觉得给模型塞的信息越多越好。实际测试下来完全不是这样。信息过载反而会让模型抓不住重点，回答变得又长又空，甚至被无关细节带偏。context-mode做得好不好，很大程度上取决于能不能克制住“什么都往上堆”的冲动。好比你要给一个新同事介绍项目背景，不是让他把公司所有文档从头看一遍，而是根据他接下来要做的那个具体任务，挑出真正相关的三五份资料给他，效果最好。

这个功能适用的人群非常明确：正在重度使用AI辅助编程的开发者，尤其是维护中大型项目的人；还有那些自己动手封装AI工具、想把“上下文收集”做成标准能力的工程团队。如果你只是偶尔让AI写个独立函数，那context-mode对你来说可能感知不强；但如果你每天都在一个几万行代码的仓库里和AI协作，这就是一个能把“可用”变成“好用”的关键开关。

2. 核心机制拆解：上下文模式是怎么“看见”你的项目的

2.1 三种典型上下文来源

我在实际配置过程中，把上下文的来源分成了三大类，方便自己理解每一部分到底在提供什么信息。

第一类是显式引入的信息。这包括你手动打开的文件、你在对话里提到的文件路径、你粘贴进来的代码片段。这类信息最准确，因为是你主动指定的，但也最容易出问题——很多工具默认会把“当前打开的文件”塞进上下文，如果你同时开着七八个文件，它们全都会被收集进去，其中一半可能跟当前问题毫无关系。所以显式引入需要配合一个权重机制：当前正在编辑的文件优先级最高，其余打开的文件优先级递减。

第二类是项目静态信息。包括目录结构、依赖清单、构建配置、环境变量文件、路由表等等。这些信息的特点是“平时不觉得有用，缺了立刻出问题”。比如你让AI改某个接口的返回值格式，如果上下文包里缺少接口定义文件，AI可能会按照它记忆里的常见规范来改，结果跟你们团队自定义的响应封装格式对不上。静态信息的采集相对简单，因为目录和配置都是稳定的，甚至可以做缓存，但它占用的空间不小，必须做筛选。

第三类是动态运行信息。这包括当前出现的编译错误、测试失败输出、LSP诊断信息、最近一次git diff涉及的文件。这类信息时效性最强，也最能反映“此刻正在发生什么”。我之前遇到过一种情况：AI给出的修改建议本身是正确的，但它不知道这个文件里有三个地方正在同时被修改，结果它的建议跟另一个分支的改动直接冲突。把git status和最近的diff摘要放进上下文之后，这个问题就消失了。

三种信息来源侧重点不同，context-mode做得好的工具会把它们分层管理：静态信息走缓存，动态信息实时采集，显式信息由用户控制开关。我在配置时最大的感受是——如果你只能选一样放进上下文，优先选动态运行信息。因为静态信息模型多少能从训练数据里学到共性，而“你当前正卡在哪个报错上”这种信息，模型是没法凭空猜出来的。

2.2 上下文压缩与窗口管理

这里绕不开一个硬约束：模型的上下文窗口是有限的。窗口就好比一个人一次只能读这么多字，你硬塞给他一万页资料，他读到后面早就忘了前面写的是什么。当前主流模型的上下文窗口从几万token到几十万token不等，听起来很大，但代码不是自然语言，代码的token密度极高——一个只有几百行的文件，转成token可能就要三四千。一个中大型前端项目，光node_modules里的类型声明文件就有上百万行，全塞进去纯属做梦。

所以上下文压缩是context-mode的必修课。压缩不是简单地把文件截短，它有几种常用手段，我逐一试过，效果差异很明显：

第一种是按目录剪枝。项目里总有一些目录对当前任务毫无帮助，比如.git、node_modules、dist、coverage。黑名单把这些目录过滤掉，能砍掉百分之七八十的体积。第二种是按引用关系裁剪。如果你要改的是src/pages/Home.tsx，那么跟它有直接import关系的文件优先进入上下文，与它无引用的文件可以往后排。这种做法比较接近人的思维方式——就像你修东西的时候，优先看跟它直接连接的部件，而不是把整台机器拆散。第三种是按同一性原则选择。同一次会话里的连续问题，上下文可以增量复用，而不是每一轮都重新构建。

在窗口管理上还有个容易被忽略的参数：上下文预算。我自己的经验是，不要等上下文满了再处理，而是设定一个上限，比如总上下文只能用到窗口的六成，预留一部分给模型生成回答。否则模型读到后半段时前面的内容已经被截断了，它会给你一种“看起来全对但实际丢失了前半段关键信息”的假象。预算管理本质上是个资源分配问题，跟你配电脑内存差不多——不是越大越好，而是够用且不浪费。

2.3 参数与配置背后的考量

上手调context-mode时，你通常会遇到一堆配置项。我在不同工具里见过各种命名，但核心参数大同小异，下面这个表是我自己总结的对照参考：

你可能会问，为什么不直接把context.depth设成一个很大的数字，把所有目录都遍历一遍？我最初也这么干过，结果发现项目里有些深层目录又大又冷门，比如各种历史遗留的legacy目录，几万行代码永远没人动。它们被塞进上下文后，不仅占空间，还会干扰模型对当前代码风格的判断。深度限制配合黑名单，才是效率最高的组合。

还有一个容易踩的坑是符号链接。有些项目里会通过软链把公共包链接进node_modules，遍历时如果不处理符号链接，会形成循环引用，轻则重复采集，重则导致遍历超时。好的context-mode实现都会自动记录已访问的目录路径，遇到符号链接直接跳过。

3. 实操过程：从零配置一套可用的context-mode

3.1 先看功能入口与核心参数配置

到这里我们进入动手环节。我是在一个实际的前端项目里做的配置，这个项目叫dashboard-web，一个中后台管理系统，代码量在五万行左右，典型的React + TypeScript技术栈。整个配置过程大概花了一个下午，但真正让我调通核心逻辑的，是把这个过程拆成三步。

第一步是熟悉你的工具提供的context-mode入口。不同工具的入口形式不一样，有的是命令行参数，有的是配置文件，有的是编辑器插件提供的一排开关。我用的工具支持一份runtime.config.yaml配置文件，核心配置段长这样：

context: enabled: true strategy: smart max_depth: 4 window_ratio: 0.6 blacklist: - node_modules - dist - coverage - .git whitelist: - src/config/api.ts - src/types/models.d.ts freshness: 30 cache: true

先别急着复制，每个字段我都解释一下，因为不理解清楚就套用，后面出了问题你都不知道该从哪里排查。enabled是功能的开关；strategy选择上下文采集用哪种策略，smart模式下系统会根据当前工作区的文件变更、打开文件、搜索结果自动决定采集内容；max_depth控制遍历目录的最深层级，4层对绝大多数项目够用，如果你的项目结构比较扁平，甚至可以改成3；window_ratio指上下文最多占用模型窗口的六成，剩下的四成留给回答生成；blacklist是黑名单，这里面的目录直接不碰；whitelist是白名单，在这个列表里的文件无论是否被自动筛选命中，都会被纳入上下文，我用它来保证接口定义和类型模型这类全局依赖一定在场；freshness是动态信息的刷新间隔，30秒一次对日常编码够用；cache开启后，目录结构和静态配置等内容会做磁盘缓存，下次启动时不必重新扫一遍。

第二步是确认你的工具是否支持手动修改上下文包。现在很多工具都提供“查看这次回答使用了哪些上下文”的面板，这一步非常关键。没有这个能力，你就等于闭着眼睛调参，永远不知道模型到底看到了什么。我强烈建议你在正式使用前先开一个调试会话，把上下文面板打开，确认三个问题：当前打开了哪些文件被自动收集了？项目目录结构收集了几层？这次会话里实际注入模型的是哪些内容？这三个问题能覆盖绝大多数配置错误的排查方向。

3.2 核心采集逻辑：一段可以直接改着用的代码

如果你不想只用现成的工具配置，而是想自己实现一套上下文采集逻辑，我也把核心代码整理出来了。下面这个实现是一个简化版，但结构是完整的，可以直接跑起来看效果。

import { promises as fs } from "fs"; import path from "path"; interface ContextOptions { root: string; blacklist: string[]; whitelist: string[]; maxDepth: number; maxFileSize: number; // 单文件最大字节数 } async function collectContextFiles(options: ContextOptions): Promise<string[]> { const { root, blacklist, whitelist, maxDepth, maxFileSize } = options; const results = new Set<string>(); // 白名单文件直接纳入，不参与遍历判断 for (const file of whitelist) { const absPath = path.join(root, file); if (await isFileValid(absPath, maxFileSize)) { results.add(absPath); } } const walk = async (dir: string, depth: number) => { if (depth > maxDepth) return; let entries; try { entries = await fs.readdir(dir, { withFileTypes: true }); } catch { return; // 目录不可读时直接跳过 } for (const entry of entries) { const fullPath = path.join(dir, entry.name); // 跳过符号链接，防止循环引用 const stat = await fs.lstat(fullPath); if (stat.isSymbolicLink()) continue; if (entry.isDirectory()) { if (blacklist.includes(entry.name)) continue; await walk(fullPath, depth + 1); } else if (entry.isFile()) { if (shouldIgnoreFile(entry.name)) continue; if (stat.size > maxFileSize) continue; const content = await fs.readFile(fullPath, "utf-8"); // token估算：中文约1.5字符/token，英文约3.5字符/token const estimatedTokens = Math.ceil(content.length / 3); if (estimatedTokens > 6000) continue; results.add(fullPath); } } }; await walk(root, 0); return Array.from(results); } function shouldIgnoreFile(name: string): boolean { const ignorePatterns = [ /^\.env.*/, /\.(png|jpe?g|gif|svg|ico)$/, /\.(lock)$/, /-lock\.json$/, /\.test\./, ]; return ignorePatterns.some((pattern) => pattern.test(name)); }

这段代码有几个设计点，值得你关注。首先是黑名单优先于遍历。遇到node_modules这种目录时，直接在目录层就切断，而不是进入之后再逐个文件判断，这个顺序能省下大量无意义的文件系统调用。其次是符号链接直接跳过。前面我提过符号链接可能造成循环引用，所以在拿到每个entry后第一件事就是lstat判断链接类型。

然后是单文件大小和token估算。我设了一个maxFileSize限制，超过2MB的文件不进上下文，同时用字符串长度除以3来粗估token量。这个估算方式不精确，但对于快速筛选已经够用。最后是测试文件与资源文件的过滤。.test.文件在单元测试时很有用，但大多数对话场景下并不需要测试代码参与，所以我在shouldIgnoreFile里把它们排除掉了。图片字体类的二进制文件更不能进上下文，因为它们只会变成乱码。

你拿这段代码跑一遍，会发现结果里有一个问题：它只返回了文件路径列表，并没有真正生成“上下文包”。在实际工程里，还需要把每个文件读出来、加上路径标题、拼成分隔文本，这一步通常叫renderContext。你可以根据自己的模型格式来写这个渲染器，不同模型对不同格式的敏感度不一样，但基本结构是“路径标注 + 代码块 + 分隔符”的组合。

3.3 效果实测：同一问题在不同模式下的对比

配置完成之后，我做了一组对照实验。实验对象是我项目里的一个真实任务：修复src/pages/UserList.tsx里一个数据导出的功能，这个功能调用了utils/exporter.ts里的工具函数，但导出的Excel文件列头顺序跟产品需求不一致。

我在三种模式下分别提问，问题完全一样：“请修复UserList里导出功能列头顺序不正确的问题，列头应按姓名、部门、入职时间排列。”

第一个模式是完全不带上下文，只把UserList.tsx里导出相关的那段函数粘贴给模型。结果模型给出了一个独立的修改建议，它能正确调整列头数组的顺序，但它在依赖注入的地方引入了新的写法，跟项目里现有的useMemo风格完全不统一。我如果直接采用，还需要额外改两处配套代码。

第二个模式是带上了当前文件但没开context-mode。模型能看到完整文件了，但它不知道exporter.ts里面已经提供了一个排序参数，结果它提出在组件内自定义排序逻辑。这个建议本身没错误，但它重新造了一个已经存在的轮子。

第三个模式是开启context-mode之后。系统自动收集了UserList.tsx、utils/exporter.ts、types/User.ts、以及最近一次git diff涉及的两个文件。模型直接指出“exporter的exportExcel方法已经接收columns参数，只需在调用处传入正确顺序即可，无需改动工具函数内部逻辑”。这个回答精准命中问题，改动量只有一行。

三个模式的对比结果很容易用表格说明：

这个实验结果符合我对context-mode的预期：它不能替你做技术决策，但它能把“做决策需要的信息”摆到模型面前。模型的能力没有变，变的是它看到的“世界”变完整了。

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

4.1 典型问题速查表

调context-mode的过程不是一帆风顺的，我整理了实际使用中最常见的几个问题，做成一个速查表，方便你遇到问题时快速定位。

我遇到最多的是第一个问题。某次我改了项目的目录结构，把一个公共组件从src/components移到了packages/ui，但配置文件里白名单还写着旧的路径。结果上下文面板里能看到那个路径的文件已经不存在了，系统还是把它当成有效的上下文文件送进模型，模型就根据这个“幽灵文件”给出了让人摸不着头脑的回答。白名单是好东西，但一定要跟项目事实保持一致，否则它会造成比自动采集更严重的误导。

4.2 上下文污染与清理策略

上下文污染是context-mode使用中最隐蔽的问题。所谓污染，就是上下文里混入了不该出现的信息，它们不一定会导致报错，但会让模型的注意力被分散。我遇到过几种典型的污染场景，在这里逐一复盘。

第一种是缓存目录里的旧代码。很多编译工做会生成dist或build目录，如果你的黑名单漏掉了它们，采集逻辑就会把编译后的产物当成源码送进上下文。编译产物跟源码差异很大，变量名可能经过混淆，注释全部丢失，模型读了之后风格完全跑偏。排查方法是看上下文面板里有没有不是src下的非预期文件，有就说明黑名单漏了。

第二种是日志文件和临时文件。编辑器目录里常有.vscode设置，项目根目录下可能有*.log。这些文件单个不大，但日志里经常夹杂着堆栈信息和绝对路径，模型读多了会学着用你本机的绝对路径写代码。这类信息对项目没有价值，应该在过滤规则里一并排除。

第三种是跨会话上下文残留。有些工具会保留历史会话的上下文片段，新问题进来时会带上之前对话的内容。这本来是个特性，但如果上一个问题已经解决，残留的旧上下文反而会干扰新问题的回答。我的习惯是：每换一个任务域，就主动清理会话或重开一个会话，让上下文包保持“当前任务相关性”。

清理策略上，除了定时清缓存外，我还习惯在配置文件里维护一份“敏感文件清单”。比如本地环境变量.env.local，里面可能有数据库地址和密钥，这些内容绝对不能出现在上下文里。之前见过有人把包含明文密码的.env文件送进了上下文，虽然只是发给了本地模型，但风险意识不能放松。任何可能含密钥、口令、个人信息的内容，都应该进黑名单。

4.3 一个值得记录的排查案例

最后分享一个比较有代表性的排查过程，过程不复杂，但思路值得参考。

现象是：我让模型修改src/utils/format.ts里的日期格式化逻辑，但模型给出的建议里频繁出现moment库的用法。而我们的项目里根本没有安装moment，日期处理统一用的是dayjs。问题很明显：模型的回答跟项目事实脱节了。我下意识以为是上下文没包含到依赖信息，于是开了上下文面板检查，发现package.json确实在上下文包里。那就奇怪了，明明依赖清单就在模型眼前，它为什么还要用moment？

接着往下查，我发现采集逻辑处理文件时是按目录遍历顺序拼接的。某个旧版本文档被放在docs/history/目录下，里面有一段示例代码用的是moment恰好排在前面。模型读到依赖清单之后又读到了这段过期文档，就学着用了moment。这不是模型的问题，是采集顺序导致的上下文“局部占优”效应。

解决方案挺简单：把docs/history/目录加入黑名单，同时在采集逻辑里对目录做个优先级标记，src下的代码文件永远排在文档类文件之前。改完之后再提问，模型立刻回到dayjs的方案，而且引用的API都能对应上项目真实版本。这个案例对我最大的启发是：context-mode不是“把所有信息丢给模型”就完了，信息的编排顺序和来源优先级，跟信息本身一样重要。

回头再看整个context-mode的调优过程，我最大的心得就是——它本质上是一个预算管理工具。你给模型的不是尽可能多的信息，而是更合适的信息。配置这东西没有放之四海而皆准的模板，每个项目的目录结构、技术栈、团队习惯都不一样。你唯一能依赖的，是先把上下文面板打开，老老实实看一次模型到底看到了什么，然后基于事实去调整黑名单、白名单和优先级顺序。把这一步做扎实了，context-mode才算真正在你手底下跑通。