企业官网建设流程全解析

这周我在一个遗留项目里调一个报错，改来改去花了大半个下午，最后发现根本不是业务逻辑的问题，而是我把 context-mode 调错了档位。AI 没看见某个变量其实就在同目录的兄弟文件里定义，它对着报错信息猜了三轮实现，每次给出的代码都“看上去很合理”，一跑就露馅。这个经历让我决定把 context-mode 这个平时很少人细想的开关单独拎出来讲一讲。

context-mode 说白了就是：和 AI 协作写代码时，你决定让它看到多少项目上下文，以及它的输出能作用到多大范围的控制方式。现在大部分编码助手、IDE 插件和命令行 AI 工具都有类似机制，有的直接叫 context mode，有的叫上下文来源、工作区范围、agent 权限，有的藏在@符号菜单背后。名字不统一，但底层的调节逻辑是通的：让 AI 既不会因为上下文太少而“瞎猜”，也不会因为上下文太多而被噪音带偏，同时还得管住 token 消耗和误改风险。

这篇文章不打算复读某款工具的官方文档。我会以 context-mode 为线索，把几个最核心的调节维度、我在实战中的换挡经验、一份可以直接抄走的配置模板，以及容易踩的边角坑都过一遍。适合已经接触过 AI 辅助编程、正想在稍微大一点的代码库里把它用顺手的开发者；如果你正好撞上“AI 答非所问”“AI 自作主张改了不该改的文件”这类问题，这篇应该能给你一个排查方向。

1. context-mode 的实质：AI 的工作边界长什么样

很多刚接触的人以为 context-mode 只是“选多少个文件塞进提示词”，实际用下来我发现它至少同时控制三件事：AI 能看到哪些文件、能记住多少信息、能改动哪些位置。这三件事合在一起，才构成 AI 在项目里的真实工作边界。

1.1 可见范围：决定 AI“浏览过哪些资料”

这是最直观的维度。最早一批编码助手只把编辑器当前打开的文件丢给模型，结果就是 AI 对项目的理解趋近于零，稍微涉及跨文件的改动就开始瞎编。后来大家学聪明了，开始按目录载入上下文，配置里写include: ["src/**"]，AI 就能把 src 下所有相关文件纳入视野。

再往后，出现了基于符号依赖的选取方式。它不是把整个目录扫一遍，而是跟着 import、调用关系走：我改OrderService.java时，AI 会把OrderRepository、PaymentGateway这类被它依赖的类一起拉进来，而不是把 java 目录下几千个文件全部塞进去。这个演进看起来理所当然，但真正用起来仍然要靠 context-mode 去画边界，因为“相关”的标准并不是固定的。

按我的使用习惯，可见范围大体分四档：

• 单文件模式：适合查一个函数的写法，或者处理完全孤立的工具函数。
• 模块模式：适合处理当前修改目录、以及被当前代码直接依赖的邻近文件。
• 全库模式：适合跨模块重构、全局搜索、架构分析。
• 工作区模式：除了读文件，还允许 AI 自己执行命令、修改多处文件、甚至参考 CI 运行结果。

这四档之间不是越宽越好。全库模式看起来很强，但在一个维护了三年的老项目里，AI 很容易被某个已经不用的旧模块带跑。可见范围本质上是信息的选择器，不是越多越聪明。

1.2 上下文配额：决定 AI 能“认真记住多少”

第二个维度是 token 预算。现在不少模型把上下文窗口做到了 128k、200k，甚至更高，但窗口大不等于有效。人一次能抓在手里的资料是有限的，模型也一样：当塞进来的内容远超有效注意力范围时，它会变得“均匀地不专注”。

我有个比较喜欢的比喻：AI 编码助手像一位外科医生，你得给他递器械，而不是把整间手术室的柜子全打开。器械摆太多，他反而找不到止血钳。上下文配额要管两件事：一是静态上限，也就是这次会话最多加载多少 token；二是超限时的淘汰策略，比如最老的对话先压缩、某个大文件先被弹出，还是对关键文件做摘要替换。摘要替换看起来聪明，但会牺牲精确性——摘要丢掉的细节，往往正是报错现场需要的信息。

1.3 行动范围：决定 AI 能“改哪些位置”

这一条很多用户会忽略，但它其实是最容易出事的维度。context-mode 真正要管的不仅是模型能“知道”多少，更是模型能“改”多少。你可以让 AI 读取整个仓库来理解架构，但只允许它修改某一个子目录下的文件。

我在团队项目里的做法是：涉及支付、数据库迁移、部署配置的目录一律设为只读；业务模块目录设为可写；锁文件和构建产物直接拉进黑名单。这样即使 AI 在分析时看过了全部代码，它真正能下手改的也只有我授权的范围。最小可写原则，比什么提示词约束都管用。

这三个维度合起来，才算完整描述了一个 AI 的工作环境。只看其中一个，都会在实战中遇到偏差。

2. 两次失败的排错，让我确认 context-mode 该这样切

讲理论可能还不够直观，我说两个自己实际翻车的例子。这两次错误方向完全相反，但最后都指向同一个结论：换挡比换模型重要。

2.1 失败一：全量上下文，AI 开始顺着错误的因果关系“圆谎”

当时遇到的问题是订单支付状态那边偶现同步异常。我图省事，直接把 context-mode 开到全库级别，还把自动文件发现也打开，想着“反正 AI 能自己找相关代码，肯定比我手动点名强”。

结果 AI 给出的分析是：“可能是异步加载导致的初始化顺序问题，建议在启动阶段增加依赖预检”。这套解释非常漂亮，逻辑上能自洽，代码也写得很规整。但提交上去之后，同事一查就发现它根本没有读取models/transaction.py这个关键文件，整个分析建立在另一个相似模块的错误假设上。

原因后来很清楚：全库模式下上下文塞进了太多不相关的数据，AI 的注意力被各种看似相关的信息分散，它为了给你一个“能自圆其说”的答案，会顺着最像样的线索编下去。全库模式不是不行，但要给它更明确的任务边界和文件边界，否则它会把代码库当成一本侦探小说，自己脑补剧情。

2.2 失败二：最小上下文，AI 开始“猜”缺失的部分

另一次是排查PAYMENT_CLIENT_ID在线上环境一直没有生效的问题。我这次学乖了，把模式调成单文件模式，只把报错的那段代码交给了 AI。结果更离谱：AI 没看到settings.load()这个全局加载入口，也没看到.env.example里对支付参数的说明，于是自作主张在代码里补了一段os.getenv("PAYMENT_CLIENT_ID", "test_client")的默认值。

这段代码在本地跑得好好的，因为测试环境确实能对上；到了生产环境就变成静默失败，因为默认值把真实配置盖掉了。这是最小上下文最典型的坑：AI 在信息不足时，不会老老实实说“我看不到”，它会基于概率补全一个最合理的实现。补全出来的东西，恰好就是你最不想要的隐性 bug。

2.3 复盘结论：不是 AI 变笨，而是换挡没换对

连续两次失败之后，我把上下文范围收敛到一个精确集合：读取models/transaction.py、config/settings.py、.env.example三个地方，写入范围只允许app/services/payment/下的文件。结果不到二十分钟，AI 就定位到问题出在配置加载顺序上：模块 A 在配置模块 init 之前就被 import，导致支付参数读进去的是空值。

这次的教训非常明确：排错类任务需要的不是全库扫描，而是“最小必要上下文”。多少叫“必要”？至少要覆盖三个点——出问题的那段代码、它依赖的关键函数或常量、以及这些依赖的最终定义位置。手动指定这个集合，比让 AI 自己漫游要可靠得多。

3. 我日常用的 context-mode 配置模板与切换命令

不同工具对 context-mode 的暴露方式差异很大，有的在 IDE 侧边栏，有的在配置文件里，有的只能通过命令行参数临时指定。但背后的配置项基本能对上。下面这套是我根据自己的使用习惯整理的模板，字段名可能和你用的工具不完全一致，照着语义翻译过去就行。

3.1 项目级配置文件

我通常会在仓库根目录放一个.context-mode.yaml，把默认行为定下来，省得每次开新会话都要重新交代。

# .context-mode.yaml mode: focused read: max_tokens: 24000 include: - "app/modules/payment/**/*.py" - "app/common/utils.py" exclude: - "**/tests/**" - "migrations/archive/**" follow_imports: true write: rules: - path: "app/modules/payment/**/*.py" allow: true - path: "**/*.lock" allow: false - path: "config/*.yml" allow: false default: read_only compact: auto_compact_threshold: 0.9 strategy: recency

几个字段说下我的考虑。max_tokens: 24000不是随便定的，它刚好能容纳一个中等模块的核心文件集，又不会大到让模型注意力涣散。follow_imports: true开启后，AI 会自动把当前文件 import 的邻近模块拉进来，这种“轻量追踪”比全库扫描精准得多。write.rules里我把 config 和锁文件都设成只读，因为这两个地方一旦被 AI 乱改，后面很难在 review 时发现。

3.2 会话内换挡的命令

配置文件解决的是默认值，真正高频使用的是会话内的即时切换。我把常用的几条命令整理成了类似下面这样：

# 查看当前上下文状态 ctx-mode --status # 切换到 focused 模式，并手动补充相关文件 ctx-mode --set focused --include app/services/payment --depth 2 # 切换到 project 模式，排除 legacy 目录 ctx-mode --set project --exclude "legacy/**" # 临时允许写一个文件 ctx-mode --allow-write docker-compose.yml

--status输出类似这样：

current context-mode: focused read scope : 23 files / 14.6k tokens write scope : app/services/payment/** last reload : 12:41:07

这条命令的价值在于强制自己确认当前 AI 的工作边界。我后来形成了个肌肉记忆：每换一个任务类型，先跑一次ctx-mode --set，再开始对话。如果 AI 连续两次给出“我觉得可能是……”而不是“根据 XX 文件的 XX 定义”，我就知道该看看是不是上下文没给够。

3.3 四个常用组合

除了上面的配置模板，我实际工作中沉淀出了四套固定组合。它们不一定是某个工具自带的名字，但经过我反复测试，覆盖了绝大多数日常场景。

• 写新函数：单文件模式，只给当前文件，AI 速度快、不会乱改别处。
• 修 bug：focused 模式，必给报错点 + 直接依赖 + 配置定义，任务结束后立刻切回。
• 小模块重构：balanced 模式，让 AI 看整个模块和邻接模块，但只允许改目标目录。
• 跨模块大重构：project 模式，必须配合 write 白名单，并且建议开一个独立会话，别跟日常迭代混在一起。

4. 用了半年后最容易踩的四个边角问题

把 context-mode 用熟练之后，你还会遇到一些不容易察觉的坑。这些坑不是“配置错了”那么简单，更像是使用习惯和工具机制之间的摩擦。

4.1 读写权限与用户预期不符

最常见的问题是 AI“说没改过，但 diff 里全是它的痕迹”。有些工具会把“读取”和“写入”混在一起，你给了它读文件的权利，它顺手就把文件改了。尤其是在全库模式下，AI 为了修一个逻辑问题，可能同时帮你格式化了好几个无辜的文件。

解决方法是把 write 规则写死，并且养成跑完看 diff 的习惯。我见过同事把**/*.env设成可写，结果 AI 在分析配置时悄悄把一个环境变量从true改成了"true"，字符串和布尔值的问题，跑了两天才发现。

4.2 上下文缓存过期

很多工具会把读过的文件缓存一段时间，避免重复计费。这个机制本身没问题，但它有个副作用：AI 看到的可能是五分钟前的旧版本。如果你正在一个人频繁改文件、再让 AI 分析，很容易出现“AI 对着旧代码给建议”的诡异情况。

我的处理方式很土：每次大改完，明确在对话里说一句“请重新读取当前磁盘上的 XXX 文件”；或者直接把上下文模式切到 single-file 再切回来，强制刷新缓存。有些工具提供/refresh或类似命令，有就用，没有就手动点名。

4.3 两个会话共用一套上下文

还有个容易忽略的问题：多个会话共享项目级配置文件，但每个会话自己的对话历史是独立的。假设会话 A 里已经讨论清楚“订单状态字段现在统一用字符串”，会话 B 由于没有这段历史，可能还会按照旧的布尔逻辑来写代码。

我在实际工作中会把“结论型信息”写进项目里的AGENTS.md或CLAUDE.md这类协作文档，而不是指望每个会话都自己重新读一遍代码。这样无论哪个 context-mode 打开，AI 都能在一开始就看到这些约定。上下文模式决定的是“AI 能看多少”，而协作文档决定的是“AI 最先看到什么”。

4.4 CI 里不可复现的结果

本地跑得好好的 AI 修复，推到 CI 上就变得不可复现，这是最磨人的问题。原因是本地有交互式会话、有手动补充的上下文文件、有你顺手改过的未提交内容；CI 里只有一个干净 checkout，AI 拿不到你本地那些隐含信息。

对应办法是让 CI 侧的调用尽量只依赖显式上下文：固定好配置文件路径、固定好接受输入的目录、把max_tokens和写入规则都写进参数里，不要让执行环境自己猜。凡是那种“我在本地明明没问题”的 AI 修复，十有八九是上下文在本地和 CI 两端不对齐。

5. 我看到的 context-mode 两个演进方向

用了半年多，我能明显感觉到这类功能正在从“手动换挡”走向“自动识别”。先说第一个方向：从文件列表走向符号关系图。现在的 context-mode 大多是按目录、按文件名组织上下文，但好的上下文其实应该按符号依赖来组织。AI 在改OrderService时应该自动带动OrderRepository和PaymentGateway，而不是把整个 services 目录全塞进来。我注意到几个主流编辑器已经在往这个方向做，文件系统还是那套文件系统，但背后的选取逻辑已经从“路径匹配”变成了“依赖图”。

第二个方向是从静态快照走向动态订阅。早期 context-mode 是一次性把文件快照丢给模型；现在部分工具开始支持让 AI 订阅文件系统变更，你保存一个文件，它就自动更新自己手里的相关上下文。配合 linter 和测试结果动态调整上下文，AI 能更接近“真正在项目里工作”的状态。以后我估计会看到更少的模式切换按钮，更多的自动上下文管理——手动切档是过渡期的习惯，但理解这三个维度的调节逻辑，什么时候都不会过时。

按我个人这几周的使用心得，最实用的动作不是研究某个工具的高级参数，而是每次开工前用ctx-mode --status看一眼当前 AI 的工作边界。知道它能看到什么、能改什么，再开始干活，整体效率真的会不一样。