理解Trae：从系统消息、工具调用到协作模式

星月昭铭2026-03-24 11:07

最近，我越发想弄明白像 Trae 这类 AI 编程工具背后的工作原理。在网上搜了一圈，也没找到类似的深度解析文章，倒是见过一些分享各类编程软件 Prompt 的------可那些角色扮演的 Prompt 我知道，感觉各家都大同小异。

我真正好奇的是，为什么它只需我一句话，就能做到：精准定位代码、分析问题、编写新代码、修改现有文件，甚至处理更复杂的任务？这背后的机制是什么？

于是我心血来潮，做了一次有趣的尝试：让 Trae 里面的 AI 来教我它自己的工作原理。尽管我知道，搞懂这个对我的项目开发可能没有直接的帮助，但作为一个程序员，好奇心总是驱使我向前一步------而我恰好属于好奇心比较重的那类。

这便有了我之前写的那篇《"连续回答"是假的：揭秘 LLM 工具调用的真实执行流》（哈哈，其实那篇文章也是整合 AI 的回答而成的，现在有了 AI，自己动手打字都变少了）。之后，我又不断地向 Trae 里的 AI 提问，它不只是讲解，还直接"实战演示"给我看。甚至可以说，这篇文章的绝大部分内容，都是由它生成后，我再提炼、整合而来的。

我写这些，并非想要达成什么具体目标，纯粹是出于想了解一下。一方面满足自己的好奇心，另一方面也希望能帮助其他同样想知道"它到底是怎么工作的"的人。如果有不对的，还请指教（因为我也不知道AI的回答是不是真的完全符合他的工作原理，但是实际来看，应该是符合的）。

如果本文内容有任何表述不当或涉及侵权，还请务必联系我，我会第一时间进行处理。最后，容我真心推荐一下 Trae。在国内众多的同类编程工具中，它确实称得上良心好用。我自己也用这个Trae写了一个windows网络代理软件，目前在实际开发中也用上了，写的软件也给别人用了。

第一幕：环境构建 ------ 系统消息的持续注入

在每次对话中，Trae IDE都会持续向AI模型发送<system-reminder>消息。这是AI感知你工作环境的唯一信息来源。以下是一些关键类型的原始消息：

1. 文件打开事件 (当你在IDE中点击一个文件)

xml 复制代码 
<system-reminder>
The user opened the file in the IDE.
Path: /workspace/demo-project/src/main/java/com/example/service/UserServiceImpl.java
Line: 42
Line Content: `    public UserDTO getUserById(Long id) {`
</system-reminder>

解读 ：AI由此知道你在看UserServiceImpl.java的第42行，内容是一个方法的开始。

2. 文件变更通知 (当你或格式化工具保存文件)

xml 复制代码 
<system-reminder>
Note: /workspace/demo-project/src/main/java/com/example/controller/UserController.java was modified, either by the user or by a linter. This change was intentional, so make sure to take it into account as you proceed (ie. don't revert it unless the user asks you to). Don't tell the user this, since they are already aware. Here are the relevant changes (shown with line numbers):
(no diff available)
</system-reminder>

解读：这条消息至关重要。它告诉AI："文件已被外部修改，请注意，不要覆盖用户的更改。" 这保证了人机协作的安全性。

3. 终端状态 (每次对话开始或触发命令时检查)

xml 复制代码 
<system-reminder>
The maximum number of terminals is 5, and 0 have been created:
<available_terminal>
No available terminals. Running command will automatically create a new terminal.
</available_terminal>
<!-- ... 详细的终端使用规范 ... -->
</system-reminder>

解读：AI通过此消息了解当前可用的命令行终端情况，以及运行命令的规则（例如必须使用PowerShell，避免交互式命令）。

4. 工具调用结果 (任何工具执行后的返回)

xml 复制代码 
<toolcall_status>done</toolcall_status>
<toolcall_result>
Content from line 1 to line 50:
package com.example.controller;
// ... 文件实际内容 ...
</toolcall_result>

解读 ：这是Read工具执行后的返回。所有工具的执行结果都以这种格式嵌入到系统消息流中，成为后续AI决策的新上下文。

第二幕：单次任务的生命周期 ------ 以"搜索Controller"为例

让我们追踪一次最简单的"搜索"任务，查看完整的HTTP请求/响应序列。请记住，AI的"记忆"就存在于这个不断膨胀的messages数组中。

用户发起请求：在聊天框输入"帮我找一下项目里所有的Controller"。

第1次HTTP请求 (从用户到AI服务器)

json 复制代码 
{
  "messages": [
    // 历史消息1: 系统提示（包含上述所有环境信息）
    {
      "role": "system",
      "content": "<system-reminder>...</system-reminder>"
    },
    // 历史消息2: 用户当前的问题
    {
      "role": "user",
      "content": "帮我找一下项目里所有的Controller"
    }
  ],
  // IDE声明本会话可用的工具列表
  "tools": [
    {"type": "function", "function": {"name": "SearchCodebase"}},
    {"type": "function", "function": {"name": "Glob"}},
    {"type": "function", "function": {"name": "Grep"}}
    // ... 其他工具
  ]
}

第1次HTTP响应 (AI返回工具调用请求)

AI分析上下文后，决定先使用Glob工具进行文件名匹配。它返回的不是文本，而是一个工具调用指令。

json 复制代码 
{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": null, // 注意，此时没有文本回复
      "tool_calls": [{ // 包含了一个工具调用请求
        "id": "call_001",
        "type": "function",
        "function": {
          "name": "Glob", // 调用Glob工具
          "arguments": "{\"pattern\": \"*Controller.java\", \"path\": \"/workspace/demo-project\"}"
        }
      }]
    }
  }]
}

工具本地执行 ：Trae IDE在本地 执行这个Glob搜索，得到结果。

第2次HTTP请求 (携带工具结果再次询问AI)

IDE将工具执行结果作为一条新消息，连同所有历史上下文，再次发送给AI。

json 复制代码 
{
  "messages": [
    {"role": "system", "content": "<system-reminder>...</system-reminder>"},
    {"role": "user", "content": "帮我找一下项目里所有的Controller"},
    { // 新增：AI刚才的工具调用请求
      "role": "assistant",
      "content": null,
      "tool_calls": [{"id": "call_001", ...}]
    },
    { // 新增：工具执行的结果
      "role": "tool",
      "tool_call_id": "call_001",
      "content": "[\"/workspace/demo-project/src/main/java/com/example/controller/UserController.java\", \"/workspace/demo-project/src/main/java/com/example/controller/OrderController.java\"]"
    }
  ],
  "tools": [...]
}

第2次HTTP响应 (AI生成最终答案)

此时，AI的上下文中包含了"搜索结果"，因此它可以生成最终的自然语言回复。

json 复制代码 
{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "找到了！项目中有以下Controller文件：\n1. `UserController.java`\n2. `OrderController.java`\n\n你可以点击路径直接打开文件。", // 基于工具结果的文本回复
      "tool_calls": null // 本次回复不需要再调用工具
    }
  }]
}

关键结论 ：一次简单的交互，可能包含多次 HTTP请求。"连续性"的魔法在于，每次请求的messages数组都完整包含了之前发生的所有事情（用户输入、AI回复、工具调用及结果）。AI模型只是这个"不断滚动的上下文"的处理器。

第三幕：核心工具的原理解析

在Trae的架构中，所有"操作"行为，最终都转化为对一系列本地工具的调用。理解每个工具的JSON Schema和其行为边界，是理解AI如何工作的关键。以下是对所有核心工具的逐一拆解：

1. 文件操作类工具

a) Read：精确的代码"阅读器"

json 复制代码 
{
  "tool": "Read",
  "parameters": {
    "file_path": "/workspace/project/src/service/UserService.java", // 必须是绝对路径
    "limit": 50,  // 读取行数（1-1000）
    "offset": 1   // 从第几行开始读（可选）
  }
}
  • 工作原理：在本地执行文件IO，读取指定文件的指定行数内容，将文本返回给AI作为上下文。
  • 关键点 ：AI在修改（SearchReplace）文件前，必须 先调用Read来获取文件的精确当前状态，以构造正确的old_str。

b) Write：文件的"创建者"与"覆写者"

json 复制代码 
{
  "tool": "Write",
  "parameters": {
    "file_path": "/workspace/project/.trae/documents/plan.md",
    "content": "# 完整的计划文档内容..." // 将完全覆盖目标文件
  }
}
  • 工作原理 ：创建新文件，或完全覆写已存在的文件。这是一个"全有或全无"的操作。
  • 与SearchReplace的区别 ：Write用于生成全新文档（如计划、规格书）或大规模重写；SearchReplace用于局部精确修改。

c) SearchReplace：精确的"外科手术刀"

json 复制代码 
{
  "tool": "SearchReplace",
  "parameters": {
    "file_path": "/workspace/project/src/controller/UserController.java",
    "old_str": "    public List<User> getUsers() {\n        return service.findAll();\n    }", // 必须与源文件完全一致
    "new_str": "    public ResponseEntity<List<UserDTO>> getUsers() {\n        List<User> users = service.findAll();\n        return ResponseEntity.ok(mapper.toDto(users));\n    }"
  }
}
  • 工作原理 ：在文件中精确查找 与old_str匹配的连续代码块，并将其替换为new_str。只替换第一次匹配。
  • 核心限制 ：old_str必须一字不差 （包括空格、缩进、换行）。这是AI修改代码的最主要且最安全的方式。
2. 代码搜索类工具

a) SearchCodebase：语义化"探索引擎"

json 复制代码 
{
  "tool": "SearchCodebase",
  "parameters": {
    "information_request": "用户登录认证的相关逻辑", // 自然语言描述搜索意图
    "target_directories": ["/workspace/project/src"] // 可选，限定搜索目录
  }
}
  • 工作原理 ：基于预先构建的代码索引（如向量数据库），理解搜索请求的语义，返回相关的代码片段和文件路径。适用于"这个功能是怎么实现的？"这类高层级探索。
  • 优点：理解意图，无需精确关键词。

b) Glob：基于文件名的"模式匹配器"

json 复制代码 
{
  "tool": "Glob",
  "parameters": {
    "pattern": "*Controller.java", // 通配符模式
    "path": "/workspace/project/src" // 搜索根目录
  }
}
  • 工作原理：在文件系统上进行快速遍历，匹配符合通配符模式的文件名。适用于"找到所有Controller文件"这类明确的目标搜索。
  • 优点：速度快，结果精确。

c) Grep：基于内容的"正则表达式扫描器"

json 复制代码 
{
  "tool": "Grep",
  "parameters": {
    "regex": "@PostMapping.*login", // 正则表达式
    "path": "/workspace/project/src" // 搜索路径
  }
}
  • 工作原理 ：使用正则表达式在所有文件中搜索匹配的文本内容。适用于查找特定的代码模式、API路径或日志格式。
  • 优点：功能强大，可进行深度模式匹配。
3. 进程与交互类工具

a) RunCommand：终端的"执行代理"

json 复制代码 
{
  "tool": "RunCommand",
  "parameters": {
    "command": "mvn clean test -Dtest=UserServiceTest",
    "blocking": true, // true:等待命令完成；false:异步执行
    "requires_approval": false, // true:会弹窗让用户确认
    "command_type": "short_running_process",
    "target_terminal": "new" // 或指定已有终端ID
  }
}
  • 工作原理 ：在IDE创建或指定的PowerShell终端中执行命令。blocking: true时，会等待命令执行完毕并返回输出；blocking: false用于启动长期运行的服务（如Web服务器）。
  • 关键机制 ：通过AskUserQuestion工具实现requires_approval: true时的用户确认流程。

b) AskUserQuestion：决策的"交互点"

json 复制代码 
{
  "tool": "AskUserQuestion",
  "parameters": {
    "questions": [{
      "question": "发现冲突，请选择处理方式：",
      "header": "冲突解决",
      "multiSelect": false,
      "options": [
        {"label": "覆盖", "description": "用新代码覆盖现有代码"},
        {"label": "跳过", "description": "保留现有代码，跳过此修改"},
        {"label": "手动合并", "description": "弹出差异让我手动决定"}
      ]
    }]
  }
}
  • 工作原理 ：在IDE界面弹出对话框，将选择权交还给用户。用户的选择会作为toolcall_result返回给AI，直接影响后续执行路径。这是实现关键决策点人机交互的核心。
4. 任务与代理管理类工具

a) TodoWrite：会话内的"任务看板"

json 复制代码 
{
  "tool": "TodoWrite",
  "parameters": {
    "todos": [
      {"id": "task1", "content": "分析旧认证逻辑", "status": "completed", "priority": "high"},
      {"id": "task2", "content": "设计JWT生成方案", "status": "in_progress", "priority": "high"},
      {"id": "task3", "content": "实现登录接口", "status": "pending", "priority": "medium"}
    ]
  }
}
  • 工作原理 ：更新AI本次对话内部的系统提示，而非创建物理文件。用于AI在复杂任务中自我管理和跟踪进度。清单内容会在后续的系统消息中持续提醒AI。
  • 重要区别 ：这是一个内存状态工具，其"数据"仅存在于当前对话的上下文中。

b) Task：启动"专家子代理"

json 复制代码 
{
  "tool": "Task",
  "parameters": {
    "description": "分析架构依赖",
    "query": "找出模块A与模块B之间的所有接口调用和数据传递关系",
    "subagent_type": "search",
    "response_language": "中文"
  }
}
  • 工作原理 ：主AI（与你对话的）启动一个专门的"搜索子代理"。该子代理会独立、深入地进行多轮语义搜索和分析，最终将一份整合报告返回给主AI。这是处理"帮我分析这个庞大模块"等复杂探索性任务的高级策略。
5. 通知类工具

NotifyUser

  • 作用 ：在/plan或/spec模式中，当AI完成计划或规格文档的撰写后，调用此工具来通知用户"文档已生成，请审阅"。这标志着AI从"设计模式"切换到等待用户确认的"审批状态"。

工具调用流程总结

将所有工具串联起来，一个复杂的代码重构任务可能遵循以下协议序列：

  1. 探索 (Task -> 子代理使用 SearchCodebase/Glob/Read)：理解代码现状。
  2. 设计 (Write)：生成 .trae/documents/xxx-plan.md。
  3. 通知 (NotifyUser)：等待用户确认。
  4. 规划 (TodoWrite)：创建内部任务清单。
  5. 执行 (循环：Read -> AskUserQuestion(如需) -> SearchReplace -> RunCommand(运行测试))：逐步修改代码并验证。
  6. 交付 ：所有TodoWrite中的任务状态变为completed，AI给出完成总结。

核心结论 ：Trae的"智能"并非魔法，而是大语言模型的推理决策能力 与这一整套精细定义、各司其职的本地工具集精密协作的结果。AI扮演了"调度中心"和"策略大脑"的角色，而工具集则是其可靠且高效的"执行肢体"。

第四幕：复杂模式的协议实现 (/plan 与 /spec)

/plan和/spec不是玄学，而是触发了另一套结构化的协议流程。

1. /plan 模式的工作流

当用户输入/plan 重构用户认证模块：

  1. 模式识别 ：AI识别到/plan前缀，进入"规划模式"。

  2. 生成计划文档 ：AI的核心任务变为生成一份计划。它会调用Write工具。

    json 复制代码 
    {
  "tool": "Write",
  "parameters": {
    "file_path": "/workspace/demo-project/.trae/documents/refactor-auth-plan.md",
    "content": "# 重构用户认证模块计划\n\n## 1. 目标\n...\n## 2. 步骤\n..."
  }
}

  3. 通知用户 ：生成后，AI会通过特定方式（如调用NotifyUser）告知用户计划已生成，等待审阅。

  4. 切换与执行 ：用户确认后，AI内部状态切换回执行模式 。此时，它会读取自己刚写的计划文件，将其转化为TodoWrite清单，并开始逐步调用SearchReplace、Write等工具执行。

2. /spec 模式的工作流
/spec是/plan的超级升级版，用于超大型项目。流程类似，但产出物是一组 规格文档。

用户输入/spec 设计全新的待办事项微服务。

  1. AI创建目录：/.trae/specs/new-todo-service/

  2. AI依次创建三个核心文件：

    • spec.md (功能规格说明书)：包含Why, What Changes, ADDED/MODIFIED/REMOVED Requirements。
    json 复制代码 
    {"tool": "Write", "parameters": {"file_path": ".../spec.md", "content": "# 待办事项微服务 Spec\n\n## Why\n..."}}
    • tasks.md (任务分解清单)：详细的任务列表，包含依赖关系。
    • checklist.md (验收检查清单)。

  3. 用户与AI基于这些文档进行多轮评审和修改（通过Read和SearchReplace/Write）。

  4. 最终确认后，AI依据tasks.md，像/plan模式一样驱动执行。

模式本质 ：/plan和/spec是通过特定指令触发的、预定义的自动化工作流模板。它们将大型任务标准化为"生成设计文档 -> 确认 -> 按文档执行"的流程，极大地降低了复杂任务中的歧义和返工风险。

总结：Trae架构原理全景图

通过以上原始的协议数据流分析，我们可以勾勒出Trae的核心工作原理图：

复制代码 
      +-----------------------------+
      |         开发者 (你)          |
      +-------------+---------------+
                    | 输入指令 / 打开文件
      +-------------v---------------+       +-----------------------+
      |        Trae IDE (本地)       |       |   AI 模型服务 (远程)  |
      |                             |       |                       |
      | 1. 监听环境变化             |       |                       |
      |   - 文件开关 -> 生成系统消息  |       |                       |
      |   - 工具执行                |       | 3. 接收包含完整上下文   |
      |                             |<------|   的`messages`数组     |
      | 2. 组装上下文`messages`数组  |       |                       |
      |   (历史 + 系统消息 + 工具结果) |       | 4. 分析并返回决策       |
      |                             |------>|   (文本 或 工具调用请求) |
      | 5. 执行工具/渲染回复         |       |                       |
      |   - 本地调用Glob/Read/Replace|       +-----------------------+
      |   - 运行终端命令            |
      |   - 弹出确认对话框          |
      +-----------------------------+

数据流核心：
*   **上下文驱动**：AI的每一次"思考"，都基于IDE提供的、包含一切历史信息的`messages`数组。
*   **工具抽象**：AI的所有实际操作（读、写、搜索、运行）都转化为对本地**工具函数**的调用。
*   **工作流模板**：`/plan`和`/spec`是建立在上两者之上的、更高阶的**自动化脚本流程**。

最终，Trae的"智能"是一个组合体：**大语言模型的推理能力 + 丰富的本地上下文感知 + 强大的本地工具集 + 结构化的协作流程**。理解这些底层协议，能帮助我们更精准、高效地驾驭这个强大的伙伴，将其能力发挥到极致。
相关推荐
weitingfu29 分钟前
Excel VBA 入门到精通（十）：实战项目——自动化报表系统开发
ai·信息可视化·自动化·excel·vba·office·报表系统
_oP_i32 分钟前
Vibe coding介绍
ai
醇氧33 分钟前
用 CC Switch (cc-sw) 配置 Claude Code 接入 阿里云百炼 (Dashscope)
人工智能·学习·阿里云·ai·云计算
阿洛学长34 分钟前
2026年最佳AI提示词合集：ChatGPT、Claude、Gemini 提示词大全
人工智能·ai·chatgpt·ai作画
拾薪2 小时前
Brainstorming - 流程控制架构分析
ai·架构·superpower·brainstorming
余人于RenYu6 小时前
Claude + Figma MCP
前端·ui·ai·figma
小小李程序员9 小时前
Langchain4j工具调用获取不到ThreadLocal
java·后端·ai
孟健9 小时前
Hermes 接入 Kimi K2.6 实测：SOTA 代码能力，但有两个真实痛点
ai编程
CodeCaptain11 小时前
【六】OpenClaw 从 TUI 切换到 Web 端完整方案
ubuntu·ai·openclaw
热门推荐
012026年4月技术前沿：AI大模型爆发、智能体革命与量子安全新纪元02GitHub 镜像站点03一周AI热点速览（2026.03.31-04.06）：GPT-6曝光、谷歌开源Gemma 4、资本狂飙与模型军备竞赛04GPT-6核心能力解析及与现有主流大模型对比05基于 Docker 部署 Hermes Agent 并接入飞书机器人的完整指南06零成本！Ollama本地部署国产大模型全指南（支持Kimi-K2.5/GLM-5/Qwen，新手秒上手）07免费！不限量！用opencode接入英伟达（NVIDIA）大模型，轻松打造你的 AI 编程助手08CodeBuddy与WorkBuddy深度对比：腾讯两款AI工具差异及实操指南09LLM Wiki：让大模型替你打理知识库的完整指南10AI Weekly | 2026年4月第二周 · GitHub热门项目与AI发展趋势深度解析