Trae 上下文系统：@files、@folders、@workspace 详解

为什么上下文如此重要

你有没有这样的体验：在 AI IDE 里问一个问题，AI 给了你一段看起来很对但完全不适合你项目的代码？

问题不在 AI 的能力，而在于你给它的上下文不够。AI 不是不聪明，它只是”看不见”你的代码。

没有上下文：
你：帮我写一个用户认证函数
AI：（写了一个通用的 JWT 认证）← 可能和你项目完全不搭

有上下文：
你：@files:src/middleware/auth.ts 帮我优化这个认证函数
AI：（基于你现有代码改进）← 精准匹配你的项目

Trae 提供了一套完整的上下文引用机制，从单个文件到整个项目，粒度由你控制。

@files：引用单个文件

@files 是最基础也最常用的引用方式。输入 @ 后选择 files，搜索你要引用的文件：

@files:src/utils/request.ts 这个请求封装有什么问题？

同时引用多个文件也没问题：

@files:src/api/user.ts @files:src/types/user.d.ts
帮我检查 API 层和类型定义是否一致

场景	示例
代码审查	`@files:src/hooks/useAuth.ts 这个 Hook 有内存泄漏风险吗？`
Bug 修复	`@files:src/pages/Login.tsx 登录页提交后没跳转，帮我排查`
代码解释	`@files:src/lib/encryption.ts 解释一下这个加密逻辑`
重构建议	`@files:src/utils/helpers.ts 这个文件太大了，帮我拆分`

小技巧：文件路径支持模糊搜索，输入关键词就能快速定位。如果文件太大超出上下文窗口，Trae 会自动截断并提示。

@folders：引用整个目录

当问题涉及一个功能模块时，逐个引用文件太麻烦。@folders 让你一次性把整个目录丢给 AI：

@folders:src/components 这些组件的命名规范统一吗？

假设你的项目有这样的结构：

src/features/auth/
├── components/
│   ├── LoginForm.tsx
│   └── RegisterForm.tsx
├── hooks/
│   └── useAuth.ts
├── api/
│   └── authApi.ts
└── types/
    └── auth.d.ts

你可以直接引用整个模块：

@folders:src/features/auth
帮我审查整个认证模块的架构设计，有没有改进空间？

注意：目录文件过多会消耗大量上下文窗口。node_modules、.git 等会被自动忽略。建议引用功能模块级别的目录，别直接丢 src/。

@workspace：全项目上下文

@workspace 不是把所有文件塞给 AI，而是通过语义索引智能检索相关内容：

@workspace 的处理流程：
1. Trae 对项目建立语义索引
2. 你提问时，根据问题检索相关文件
3. 只把相关文件作为上下文传给 AI

@workspace 项目中哪里处理了用户权限校验？
@workspace 找出所有直接操作 DOM 的地方，我想统一用 ref

场景	示例
全局搜索	`@workspace 项目中哪里用到了 localStorage？`
架构理解	`@workspace 帮我梳理一下数据流向`
依赖分析	`@workspace 哪些模块依赖了 userStore？`
规范检查	`@workspace 有没有地方没用 try-catch 包裹异步请求？`

@code：引用代码片段

不需要引用整个文件？@code 让你精确到代码片段级别。在编辑器中选中代码，然后在 Chat 中引用：

// 选中以下代码后引用
@code
const handleSubmit = async (data: FormData) => {
  const res = await fetch('/api/submit', {
    method: 'POST',
    body: JSON.stringify(data)
  })
  return res.json()
}

// 提问：这个提交函数缺少错误处理，帮我补上

维度	@files	@code
粒度	整个文件	选中的代码片段
上下文消耗	较大	很小
适用场景	需要完整文件上下文	只关注特定逻辑

@web：引用网页内容

@web 让你把网页内容作为上下文。参考文档、Issue、Stack Overflow 时特别好用：

@web:https://docs.astro.build/en/guides/content-collections/
帮我按照这个文档的规范重构我的内容集合配置

@web:https://react.dev/reference/react/useEffect
我的 useEffect 用法对吗？对照官方文档帮我检查

注意：网页需要可公开访问，登录后才能看的页面无法引用。长网页会被截断，建议引用具体页面。

图片上传：截图与设计稿

Trae 支持直接上传图片作为上下文，前端开发中非常实用：

截图还原：上传 UI 截图 → “帮我用 Tailwind CSS 还原这个界面”
Bug 截图：上传报错截图 → “这个错误怎么解决？”
设计稿实现：上传 Figma 导出图 → “按照这个设计稿写组件”

上传方式：点击输入框的图片按钮、拖拽图片、或 Cmd + V 粘贴剪贴板截图。

最强用法是图片 + 代码引用结合：

[上传设计稿截图]
@files:src/components/Header.tsx
按照截图的设计更新这个 Header 组件

AI 既能看到目标效果，又能看到现有代码，改起来又快又准。

三级上下文策略：file → folder → workspace

什么时候用哪个？记住这个决策流程：

你的问题涉及几个文件？
│
├── 1-2 个文件 → @files（精确打击，消耗低，精度最高）
│
├── 一个目录下的多个文件 → @folders（模块扫描，消耗中等）
│
└── 不确定 / 跨多个目录 → @workspace（全局检索，智能控制消耗）

原则很简单：能用小范围解决的，就不要用大范围。上下文越精确，AI 的回答质量越高。

上下文窗口限制与优化

AI 模型的上下文窗口有限，即使支持 128K 你也不应该无脑塞满。

内容类型	大约 Token 消耗
200 行代码文件	1,500 - 3,000 tokens
中等目录（10 个文件）	15,000 - 30,000 tokens
@workspace 检索结果	5,000 - 20,000 tokens
一张截图	1,000 - 5,000 tokens
对话历史（10 轮）	5,000 - 15,000 tokens

优化建议：

话题切换时开新对话，避免历史消息占用上下文
精确引用优先：能用 @code 就不用 @files，能用 @files 就不用 @folders
只引用和问题直接相关的内容
善用 .traeignore 配置忽略文件：

# .traeignore 示例
node_modules/
dist/
build/
*.min.js
*.map
coverage/
.next/

与 Cursor、Windsurf 上下文系统对比

三款主流 AI IDE 都有上下文引用机制，实现方式和体验各有不同：

功能	Trae	Cursor	Windsurf
单文件引用	`@files`	`@file`	`@file`
目录引用	`@folders`	`@folder`	`@folder`
全项目引用	`@workspace`	`@codebase`	`@codebase`
代码片段	`@code`	选中自动关联	`@selection`
网页引用	`@web`	`@web`	不支持
图片上传	支持	支持	支持
文档引用	`@docs`	`@docs`	`@docs`
Git 引用	`@git`	`@git`	不支持
终端引用	`@terminal`	`@terminal`	`@terminal`
索引方式	语义索引	语义索引 + 关键词	Cascade 流式索引
免费额度	完全免费	有限制	有限制

各自的优势：

Trae：免费无限制，上下文引用类型丰富，@web 支持好
Cursor：@codebase 检索质量高，.cursorrules 深度定制
Windsurf：Cascade 自动收集上下文，不需要手动引用

预算有限 → Trae（完全免费）
追求检索精度 → Cursor（@codebase 最成熟）
喜欢自动化 → Windsurf（Cascade 自动收集上下文）

总结

Trae 的上下文系统给了你从精确到宽泛的完整控制能力。记住三级策略：先 @files，再 @folders，最后 @workspace。花 5 秒钟选对上下文，能帮你省 5 分钟改 AI 的输出。

上下文是 AI 编程的燃料。给对了燃料，AI 就是涡轮增压；给错了燃料，AI 就是一台空转的发动机。学会精确投喂上下文，是从”用 AI”到”用好 AI”的关键一步。

加载中...