23 · 上下文管理

不是你问得不够好，是 AI 看到的上下文不够多——也太多了。理解 Trae 上下文，是让 AI 精准工作的第一课。

01 为什么上下文管理这么重要

用过 Trae 的人都有过这样的体验：同一个问题，有时 AI 回答得堪称完美，有时却像是”没读过代码”一样胡说。区别往往不在问题本身，而在于AI 看到了什么。

Trae 的 AI 模型有一个”工作台”，它能看到的东西包括：当前打开的文件、项目中引用的代码、终端的输出、以及你通过 @-mention 主动喂给它的信息。这个”工作台”的大小是有上限的——就是所谓的上下文窗口（Context Window）。

上下文管理，本质上回答三个问题：

1. AI 目前看到了什么？（当前上下文的构成）
2. AI 还能看多少？（距离窗口上限还有多远）
3. 我该让它看什么、不看什么？（上下文质量控制）

这三个问题解决了，AI 的准确率会从”碰运气”变成”可预期”。

02 三种模式下的上下文差异

Trae 有三大模式：Chat、Builder、SOLO。它们背后虽然共享同一个 AI 引擎，但上下文策略完全不同。

Chat：你喂什么它吃什么

Chat 模式的上下文策略最简单直接：只有你主动引用给 AI 的内容才会进入上下文。通过 @-mention 系统，你可以引用文件、文件夹、终端输出、错误日志、甚至搜索引擎结果。

这种模式的心智模型是”工具箱”——你从工具箱里挑出需要的工具递给 AI，而不是让它自己翻箱倒柜。

你：帮我分析这个函数的性能瓶颈
@mention: src/utils/queryEngine.ts
AI：好的，让我看看 queryEngine.ts 中的逻辑...

Chat 模式下，AI 不会主动去读你没有引用的文件。这是好事也是坏事——好事是不会误读不相关的代码，坏事是你必须记得给它喂够信息。

Builder：AI 自己去翻文件

Builder 模式下，AI 拥有”翻文件”的权限。你给它一个描述（比如”帮我写一个用户注册的 API”），它会根据你的描述推断需要哪些文件，然后主动去读取。

Builder 的上下文策略是：

1. 读取你当前打开的文件
2. 根据 @-mention 引用读取指定文件
3. 自行决定还需要哪些文件，自动读取
4. 基于读取的内容生成代码

Builder 模式对上下文的管理更”激进”——它会在窗口允许的范围内尽量多读。这让它在大型项目中可能更快到达窗口上限。

SOLO：上下文像会话一样流动

SOLO（Coder / Builder）模式的上下文管理是最特殊的。SOLO 本质上是一个持续对话，上下文像”水流”一样流动：

• 每次 AI 回复都包含当前工作状态和下一步计划
• 项目结构始终在上下文中——AI 知道你项目里有哪些文件
• 对话式上下文扩展——你可以随时让 AI “回头看”某个文件
• 长对话中上下文会自然衰减——较早的内容可能被截断

SOLO 的心智模型是”结对编程伙伴”——这个伙伴一直在你身边，但你得时不时提醒它”还记得我们上周讨论的那个模块吗”。

03 模型上下文窗口速查表

不同模型有不同的上下文窗口大小。这是 Trae 中常见模型的对比：

注：Token 和汉字不是 1:1 关系。英文中 1 token ≈ 0.75 个单词；中文中 1 token ≈ 1.5-2 个汉字。以上为经验估算值。

200K tokens 听着很大，但实际中消耗得比你想象的快。一个中等复杂度的 React 组件文件（约 300 行）大概消耗 2000-3000 tokens。如果你引用 10 个这样的文件，加上对话历史，可能已经用掉了 40%-60% 的窗口。

关键认知：上下文窗口不是”能装多少数据”，而是”AI 能一次性关注多少信息”。超出的部分，AI 就像人一样——“忘掉了”。

04 上下文里面到底装了些什么

AI 的上下文不是只有你引用的代码。它由以下几部分组成：

┌─────────────────────────────────────┐
│         上下文窗口 (200K tokens)       │
├─────────────────────────────────────┤
│  ① 系统提示（System Prompt）~5%      │
│  ② 项目级指令（.traerules 等）~5%    │
│  ③ 对话历史（你和 AI 的聊天记录）~？% │
│  ④ 引用的文件内容                    │
│  ⑤ AI 正在生成的回复 ~10%            │
│  ⑥ 当前打开文件的元信息 ~2%          │
└─────────────────────────────────────┘

其中 ③ 对话历史是最容易被忽略的”吞 token 黑洞”。一次简单的问答（你问一句，AI 答一段）大约消耗 500-1500 tokens。如果你和 AI 来回聊了 50 轮，光对话历史可能已经吃掉 5 万-10 万 tokens。

这也是为什么”什么时候该开新会话”是一个核心决策——后面会专门讲。

05 大型项目的上下文策略

当你的项目达到几千个文件时，有一个残酷的事实你必须接受：AI 不可能看完你的整个项目。这不只是技术限制，从信息论的角度看，如果 AI 真的把项目所有代码都塞进上下文，它反而会”迷失”在细节中。

策略一：主动缩小焦点

不要指望 AI 自动知道该看什么。你需要在提问时明确范围：

❌ 差：这个项目有什么 bug？
✅ 好：在 src/modules/auth/loginValidator.ts 中，检查密码强度的逻辑是否有边界情况没处理？

策略二：使用 @-mention 精准引用

Trae 的 @-mention 是你最强大的上下文管理工具。输入 @ 后可以引用：

• 文件：@src/utils/db.ts —— 引用单个文件
• 文件夹：@src/modules/auth/ —— 引用整个目录（但要注意 token 用量）
• 终端：@Terminal —— 引用最近的终端输出
• 错误：@Errors —— 引用编辑器中的错误列表
• Web：@web 关键词 —— 引用搜索结果

最佳实践是引用恰好足够的文件，而不是能引用多少就引用多少。

@src/modules/payment/processor.ts @src/modules/payment/validator.ts @Terminal
帮我看看 processor.ts 第 45 行的报错是什么原因。

策略三：创建”上下文索引”文件

对于非常大的项目，可以在项目根目录保留一个 CONTEXT.md 或 AI_CONTEXT.md 文件，里面用简洁的语言描述：

# 项目上下文
 
## 项目架构
- 前端：React 18 + TypeScript，位于 /src/client
- 后端：Node.js + Express，位于 /src/server
- 数据库：PostgreSQL，ORM 使用 Prisma
 
## 关键模块
- /src/server/modules/auth：JWT 认证，使用 bcrypt 加密
- /src/server/modules/payment：对接 Stripe API
- /src/client/components/ui：通用 UI 组件库
 
## 编码规范
- 使用 ESLint + Prettier
- 组件文件使用 PascalCase 命名
- API 路由使用 kebab-case

当你开启新会话时，先 @mention 这个文件，AI 就能快速理解项目全貌，而不需要自己翻遍整个代码库。

06 .traeignore 与排除机制

并不是每个文件都应该喂给 AI。Trae 和 Trae CLI 支持类似 .gitignore 的排除机制，告诉 AI：这些文件你不要看。

.traeignore 文件

在项目根目录创建 .traeignore，写入不需要 AI 读取的文件模式：

# 不读取 node_modules
node_modules/
# 不读取构建产物
dist/
build/
out/
# 不读取日志文件
*.log
# 不读取锁定文件
package-lock.json
yarn.lock
# 不读取环境配置
.env
.env.local
# 不读取自动生成的文件
*.generated.*

为什么要排除文件

没有被 .traeignore 排除的文件，AI 可能会读取。特别是在 Builder 和 SOLO 模式下，AI 会根据自己的判断扫描文件。如果你不想让它看到测试数据目录或大型 JSON 文件，一定要在 .traeignore 中排除。

Tokens 总量参考

一个常见的项目中，各目录 token 消耗量大致如下：

node_modules/        → 500万+ tokens（必须排除！）
dist/                → 50万+ tokens（应该排除）
src/                 → 5万-30万 tokens（核心代码）
tests/               → 2万-10万 tokens（按需引用）
docs/                → 1万-5万 tokens（按需引用）

一眼就能看出：不排除 node_modules 的话，AI 的整个上下文窗口都不够装一个条目。

07 对话长度的权衡：续聊还是新开

这是最经常被问到的问题：一个会话能聊多久？什么时候该开新会话？

长会话的好处

• AI 记得之前的讨论内容，不用重复背景
• 上下文连续，工作流不间断
• 适合”逐步推进”的工作（先设计、再实现、再重构）

长会话的代价

• 对话历史吃掉大量 token，留给代码的余量变小
• AI 对早期内容的关注度衰减（“注意力稀释”）
• AI 回复变慢（处理更长的上下文需要更多计算）

决策矩阵

经验法则

当你发现 AI 的回复开始变”水”、记不住你几分钟前说过的话、或者觉得 AI 在”猜”而不是”读”代码——这就是该开新会话的信号。

开新会话不等于从头开始。你可以：

1. 把关键背景信息整理成一段话，在新会话中作为第一句话
2. 引用 CONTEXT.md 文件快速恢复项目认知
3. 把上一轮对话中 AI 给出的重要结论复制粘贴过来

08 上下文质量比数量更重要

很多人的直觉是”给 AI 的信息越多越好”。事实恰恰相反：高质量的少量上下文，远胜于低质量的大量上下文。

什么造就了”高质量”上下文

1. 相关性：每个被引用的文件都直接相关
2. 完整性：相关文件引用完整，不遗漏关键部分
3. 简洁性：只引需要的部分，不引整篇文档
4. 结构性：信息有组织，AI 能快速定位

常见的低质量上下文

❌ 把整个 utils/ 目录 @ 给 AI，让它找 bug
   → AI 要扫描几十个不相关的工具函数，浪费窗口

❌ 在一个 500 行的大文件里说"这里有个问题"
   → AI 不知道该看哪里，需要仔细阅读整个文件

❌ 连续 30 轮对话后再问一个新的复杂问题
   → AI 的大部分注意力被对话历史占据

提升上下文质量的技巧

技巧 1：先说明背景，再问问题

✅ 先给结论：
@src/modules/payment/processor.ts
这个文件处理 Stripe 支付回调。第 80-120 行的签名验证逻辑，
有一个边缘情况没覆盖——当 Stripe 返回超时时的处理。
你能帮我加上吗？

技巧 2：使用行号精确定位

✅ 精确到行：
@src/modules/payment/processor.ts
第 45 行的 try-catch 没有捕获 NetworkError，
导致超时场景下会抛出未处理异常。

技巧 3：拆分大请求

不要一次问 AI 做十件事。分成多个小请求，每次聚焦一个主题：

❌ 一次性：帮我加用户注册、登录、重置密码、邮箱验证
✅ 分步骤：①先写注册接口 ②再写登录 ③然后是重置密码 ④最后加邮箱验证

09 Token 效率：每一分钱都花在刀刃上

Token 不只是技术指标，也直接关联成本（如果你使用付费 API）和响应速度。

Token 消耗速算

省 Token 实操指南

1. 不要引用整个测试文件——如果只是想问测试框架配置，只引用配置文件
2. 使用 @web 搜索而非上传文档——让 AI 直接从网上获取公开信息
3. 避免在对话中粘贴大段日志——引用 @Terminal 比粘贴更高效
4. 及时开新会话——对话历史是最大的隐性 token 消耗
5. 删除无意义的对话轮次——如果问了”你好”之类的废话，AI 也会记住

一个实战对比

场景：想了解项目中 Stripe 支付集成的完整流程。

❌ 低效做法：
@src/modules/payment/ (整个目录，5 个文件，约 1500 行)
"帮我梳理整个 Stripe 支付流程"
→ 消耗约 15000 tokens，AI 却可能因为信息过载忽略关键部分

✅ 高效做法：
@src/modules/payment/processor.ts (入口文件，200 行)
"这个文件是 Stripe 支付的入口，帮我梳理调用了哪些模块"
→ 消耗约 2000 tokens，AI 准确聚焦

10 心智模型：把上下文想象成”舞台聚光灯”

一个有用的类比：AI 的上下文窗口就是一束舞台聚光灯。

• 光束范围 = 上下文窗口大小（200K tokens）
• 被照亮的部分 = AI 当前关注的信息
• 光束之外 = AI 完全不知道的信息
• 你 = 灯光师，决定光束打在哪里

作为灯光师，你的工作不是”把舞台全部照亮”——你的工作是把光束准确打在正在演出的演员身上。

当你引用一个文件，就是在把光束移向那里。当你开启新会话，相当于切了一个新舞台（旧舞台上的布景不再影响新演出）。当你使用 @-mention 引用文件夹，相当于扩大了光束——但同时光芒会变弱（每个文件得到的注意力变少）。

灯光太窄（只引用 1 个文件）
    → AI 信息不足，可能答错
灯光太宽（引用整个项目）
    → AI 注意力分散，错过关键细节
灯光精准（引用直接相关的 2-3 个文件）
    → AI 信息充分，回复质量最高

11 实战工作流：一个完整的上下文管理示例

让我们用一个实际场景来串联所有概念。

场景：在一个全栈电商项目中，支付模块的测试一直失败。

第一步：开新会话

之前的对话和支付模块无关，所以开一个新会话，避免上下文污染。

第二步：提供顶层上下文

@CONTEXT.md
我在 /src/modules/payment/checkout.ts 遇到了测试失败，
之前支付模块一直工作正常，最近改了订单状态机之后出的问题。

第三步：精准引用相关文件

@src/modules/payment/checkout.ts @src/modules/order/stateMachine.ts @Terminal
checkout.ts 的第 120 行调用 stateMachine.ts 的 transition 方法时报错。
终端里是测试失败的堆栈信息，帮我分析原因。

这里只引用了三个文件：

• 支付入口（checkout.ts）
• 最近修改的状态机（stateMachine.ts）
• 终端报错输出

没有引用无关的数据库模型、UI 组件、配置文件。

第四步：根据 AI 答复继续深挖

AI 定位到问题后，可能需要再引用状态机测试文件：

@src/modules/order/stateMachine.test.ts
测试中是不是没覆盖 'paid' → 'shipped' 这个状态转换？

第五步：修完后开新会话做下一件事

这个 bug 修完了，开新会话去做下个任务。

12 上下文管理检查清单

最后，一个可以贴在桌上的快速检查清单：

启动新任务前：
☐ 上一个任务是否已结束？→ 开新会话
☐ 会话是否超过 20 轮？→ 考虑开新会话
☐ AI 最近的回答是否变差？→ 检查上下文是否饱和

提问前：
☐ 我引用的每个文件都是必要的吗？
☐ 有没有遗漏关键文件？
☐ 能用行号精确定位吗？
☐ 背景说明是否足够？

管理上下文时：
☐ 项目中是否配置了 .traeignore？
☐ node_modules 和 build 产物是否排除了？
☐ 是否需要创建 CONTEXT.md 给 AI 看？
☐ 是否可以用 @web 代替上传文档？

效率检查：
☐ 引用的文件总行数是否在合理范围？
☐ 对话中是否有可以删除的无意义对话？
☐ 是否把大任务拆成了小步骤？

总结

上下文管理是使用 Trae 最重要的元技能——它不直接写代码，但它决定了 AI 写出来的代码好不好。

记住：AI 的能力上限是模型决定的，但你能不能把它的能力用出来，取决于你怎么管理上下文。一个好的灯光师，能让同样的演员呈现出完全不同的演出效果。

下一篇：24 · 提示词工程

本文是 Trae 深度教程系列的第 23 篇。系列目录：01 · 什么是 Trae → 02 · 安装与配置 → … → 23 · 上下文管理