AI Agent IDE 入门与进阶

官方文档：https://docs.trae.ai/（国际版） / https://docs.trae.cn/（国内版）适用范围：TraeCode IDE（含 SOLO / IDE 两种模式）本文目标：把「一个 AI Agent IDE 到底该配什么、怎么配」讲成一棵可以按顺序爬的树

一分钟速览

Agent IDE 与 Tab 补全的根本差别是工作对象变了：你给它一个目标 + 一整套配置，它交回改完的工作区 + 证据，人的角色变成定需求、做决策、验收。
要配齐的是七块能力：模型、技能与命令、规则与记忆、索引与文档、MCP、插件市场、Hook。
规则是全量加载的（一进对话就全部占用上下文），技能是按需加载的（先只看 name/description，命中才读全文）——这决定了什么内容该写成规则、什么内容该写成技能。
版本差异：国内版配置目录是 ~/.trae-cn/，国际版是 ~/.trae/，项目级目录统一是 .trae/。
最进阶的一层是 Hook：PreToolUse 做校验拦截、PostToolUse 做自动格式化、Stop 做完成前验收；Hook 除 Notification 外都是阻塞的，一定要设 timeout。

零、先建立认知：AI Agent IDE 不是「更快的补全」

如果你只用过 Tab 补全，第一次打开 Agent IDE 会觉得"它怎么老是要读文件、跑命令、问我一堆问题"。这不是它啰嗦，而是工作对象变了：

代际	代表形态	你给它的输入	它交给你的产出	人的角色
第一代	代码补全（Copilot 式）	光标位置 + 当前文件	后面几行代码	写代码的人
第二代	对话式助手（Chat 式）	一段问题 + 粘贴的代码	解释 / 片段	写代码的人
第三代	Agent IDE（TraeCode 式）	一个目标 + 一整套配置	改完的工作区 + 证据	定需求、做决策、验收

第三代的关键差别在于，Agent 有能力自己去找上下文、自己调工具、自己验证结果。而这三件事各自都依赖配置：

自己找上下文 → 依赖索引与文档、规则与记忆、# 引用；
自己调工具 → 依赖模型（工具调用能力）、插件市场、MCP；
自己验证结果 → 依赖命令、技能、Hook。

所以「配好一个 Agent IDE」不是调几个开关，而是把上面这套能力装齐。本文按由浅入深的顺序过一遍：先逐个讲清楚每块能力，再讲它们怎么组合成一条工作流。

配置全景图（先看这张表，再看细节）

#	能力	解决什么问题	加载方式
1	模型	Agent 的"大脑"，决定能不能调工具、上下文多长	按次调用
2	技能与命令	把重复流程固化成可执行资产	技能按需、命令手动触发
3	规则与记忆	让 AI 一直记得"你是谁、这项目什么规矩"	规则全量注入、记忆按相关注入
4	索引与文档	让 Agent 在"看不到全貌"的项目里也能找对文件	构建索引后按需检索
5	MCP	给 Agent 装上"手脚"，能操作外部系统	调用时加载工具
6	插件市场	把 Skills / MCP / 连接器打成一个能力包，一次装齐	安装后常驻
7	Hook	在关键节点插入你自己的校验/注入/拦截	事件触发

版本差异：国内版配置目录是 ~/.trae-cn/，国际版是 ~/.trae/；项目级目录统一是 .trae/。下文统一用国内版的 ~/.trae-cn/，国际版请自行替换。

一个容易被忽略的层次关系：规则是全量加载的（一进对话就全部占用上下文），技能是按需加载的（先只看 name/description，命中才读全文）。这决定了「什么内容该写成规则、什么内容该写成技能」——后面第二节和第三节会反复用到这条判据。

还请注意第 6 项的位置：插件市场排在 MCP 之后，因为它不提供新能力，只是把技能、MCP、连接器这些现成零件打包分发——先理解零件，才看得懂包装。至于最"进阶"的 Hook，留到第七节压轴。

一、模型：Agent 的「大脑」

1.1 在哪里切换

在 AI 对话输入框的右下角点击当前模型名称，打开模型列表即可切换。鼠标悬浮到模型名上可以看它支持的能力（是否多模态、是否支持工具调用等）。

1.2 选型：别看排名，看这四个维度

内置模型列表会随版本和地区变化（部分系列在特定地区不可用），所以真正值得记的是选型的判据，而不是具体名字：

维度	什么时候重要	怎么判断
工具调用能力	只要你想让它读文件、跑命令、调 MCP，就必须有	不支持工具调用的模型会把 Agent 退化成纯聊天
上下文长度	大仓库检索、长文档集问答、长会话	界面展示的窗口大小；超长时注意成本会跳档计费
多模态	看设计稿、看报错截图、看 PDF 表格	需要"能读图"的模型 + 多模态入口
成本	长期跑 Agent 任务	输入 / 缓存读取 / 缓存写入 / 输出四档分别计价，按每百万 Token 计

一个实用策略是分层用模型：

探索/规划（读代码、拆任务、问设计问题）→ 用长上下文、推理强的；
批量执行（改文件、写测试、跑格式化）→ 用便宜、快、工具调用稳的；
兜底排错（卡住了、多次失败）→ 切回最强的再试一次。

1.3 配置自定义模型

内置模型不够用时可以自己接（比如公司内部网关、自建的 DeepSeek / Qwen / Ollama 代理）：

进入 设置 > 模型，点击 添加模型；
选择 预设服务商 或 自定义模型：

路径	需要填	说明
预设服务商	服务商、配置方式（按量计费 / Coding Plan / Agent Plan）、模型、API 密钥	想用预置列表之外的版本，点「使用其他模型」直接填模型 ID
自定义模型	API 格式、自定义请求地址、模型 ID、鉴权信息	两种格式：`OpenAI Chat Completions`（兼容 `/v1/chat/completions`）、`Anthropic Messages`（兼容 `/v1/messages`）

接自建/代理服务时最容易踩的坑

API 格式别选错：OpenAI 兼容的服务（DeepSeek、OpenRouter、多数 Ollama 代理）选 Chat Completions；只有真正走 Anthropic 协议的服务才选 Messages。
模型 ID 必须写服务端认识的标识，不是界面上的显示名。
代理要支持工具调用（function calling），否则 Agent 只能聊天——这是自建网关最常见的隐形缺陷。

二、技能与命令：把流程固化成可执行资产

这两个功能经常被混着用，其实分工很清楚：

	命令（Command）	技能（Skill）
形态	一个 `.md` 文件 = 一段 Prompt 模板	一个目录 = `SKILL.md` + 脚本/模板/示例
触发	你手动输入 `/`	模型自己判断，也可以点名调用
加载	触发时才读入	扫 name/description，命中才读全文
适合	一次性、你说了算的动作	多步骤、有方法论、要带资源的工作流
举例	`/summarize-pr-info`	"TDD 开发流程"、"网页自动化测试规范"

一句话：命令是"快捷键"，技能是"说明书"。

技能是自动触发的：AI 会拿当前任务去比对各技能 description 里写的适用场景，命中就加载。当然你也可以直接点名，比如"用 codemap 技能总结一下这个分支的改动"。

2.1 命令：把常用 Prompt 变成 `/xxx`

存放位置

类型	目录	说明
项目命令	`<项目>/.trae/commands/`	仅当前项目生效，最多 3 层嵌套用于分类
全局命令	`~/.trae-cn/commands/`（`~/.trae/…`）	所有项目生效

项目命令的嵌套结构（第 4 层不会被识别）：

text

.trae/commands/
├── general-command.md
├── module-a/                     # 第 1 层
│   ├── command-a.md
│   └── submodule-a1/             # 第 2 层
│       └── command-a1.md
└── module-b/
    └── command-b.md

创建一个命令

进入 设置 > 技能与命令，在命令面板点击创建；
选择 全局 / 项目，输入命令名（建议用能说明功能的关键词，如 summarize-pr-info），确认后系统自动生成 {命令名}.md 并在编辑器打开；
填写三个字段：名称、描述、指令（--- 之下的正文，写清执行步骤、上下文来源、输出结构）；
保存。

示例 summarize-pr-info.md（对应设置面板里的「名称 / 描述 / 指令」三个字段，名称已按命令名自动填充）：

markdown

---
name: summarize-pr-info
description: 总结 PR 变更，输出结构化说明
---

查看当前 Pull Request 的代码变更，对比修改前后的代码，总结本次 PR 的主要变更。
输出内容：
1. 核心改动点
2. 主要修改的文件或模块
3. 关键逻辑变化或新增功能
4. 可能影响的功能或潜在风险

使用

在输入框输入 /，从 Commands 列表里选一个。SOLO Agent 还提供了内置命令：

内置命令	作用
`/plan`	调用"计划模式"，先出方案再动手
`/spec`	调用"规范模式"，先写清规格再实现

TraeCode CLI 里还有一组终端内置命令（/init 生成 AGENTS.md、/model 切模型、/mcp 管 MCP、/skills 看技能等），命令定义放在 .traecli/commands/。IDE 用户不必记，知道有这层对应关系即可。

2.2 技能：把方法论写成 Agent 能执行的说明书

结构

一个技能必须有一个 SKILL.md，其余文件按需添加：

text

skill-name/
├── SKILL.md        # 必须：核心指令
├── examples/       # 可选：输入/输出示例
├── templates/      # 可选：可复用模板
└── resources/      # 可选：参考文档、脚本、素材

SKILL.md 的最小格式：

markdown

---
name: 技能名称
description: 简要描述这个技能的功能和使用场景
---

# 技能名称

## 描述
描述这个技能的作用。

## 使用场景
描述触发这个技能的条件。

## 指令
清晰的分步说明，告诉智能体具体怎么做。

## 示例（可选）
输入/输出示例，展示预期效果。

description 是整个技能里最重要的一行

模型在任务开始前只会扫描所有技能的 name/description 来决定要不要加载全文。description 写得含糊，技能就永远不会被触发——你封装得再漂亮也是死代码。写的时候请把"什么任务场景下用它"写进去，而不是复述它"是什么"。

存放位置与类型

类型	目录（国内版 / 国际版）	适合放什么
全局技能	`~/.trae-cn/skills/`（`~/.trae/skills/`）	跨项目通用：代码风格、Git/CI 用法、输出结构偏好
项目技能	`<项目>/.trae/skills/`	项目专属：业务约束、内部术语、技术栈限制

TraeCode 也支持 Agent Skills 规范约定的 .agents/skills/ 目录：把它加进项目，智能体运行时会自动发现并加载其中的技能——这是跨 harness 通用的一种做法。

这台机器的 ~/.trae-cn/ 下就能看到两类目录，正好对应两种来源：

~/.trae-cn/skills/（全局技能目录）：本地安装的技能，如 frontend-skill、ppt-page；
~/.trae-cn/builtin_skills/ 与 ~/.trae-cn/builtin/（内置技能目录）：IDE 自带、按版本分发的技能，如 TRAE-code-review、TRAE-debugger、dynamic-ui。

创建与安装

技能有四种来源，按省事程度排：

方式	怎么做
让 AI 生成	直接说"帮我在 `.trae/skills/` 下建一个叫 xxx 的技能，它能做……"，AI 会写好 `SKILL.md`
手动创建	设置 > 技能与命令 > 技能 → 创建 → 选全局/项目 → 填技能名称、描述、指令。项目技能会自动生成 `.trae/skills/{skill_name}/SKILL.md`
导入外部技能	同一入口，上传 `SKILL.md` 或含 `SKILL.md` 的 `.zip`，系统会解析并自动填充名称 / 描述 / 指令
目录即安装	直接把技能目录放进 `.trae/skills/` 或 `~/.trae-cn/skills/`（也支持 `.agents/skills/`）

后两种是复用社区技能的主要途径。本机 ~/.trae-cn/skill-config.json 里就能看到这类来源记录，形如 {owner}/{repo}/{path}：

技能	来源
`web-design-guidelines`	`vercel-labs/agent-skills/web-design-guidelines`
`frontend-skill`	`openai/skills/frontend-skill`
`ppt-page`	`trae/ppt-page`

创建后可以用开关启用/禁用单个技能，被禁用的项目技能会记录进 skill-config.json。禁用的价值不只是省 Token——少一批无关描述参与扫描，模型更容易命中真正相关的技能。

项目技能还能一键「应用到全局」。一个简单的划分：跨项目都成立的写全局技能（代码风格、输出结构偏好），只在本项目成立的写项目技能（业务约束、内部术语）。

什么时候值得写一个技能

用这个三问来筛：

这件事会不会重复做？（一次性流程不值得沉淀）
它是不是多步骤、有固定顺序？（单步操作直接写成命令更轻）
它需不需要带资源？（模板、脚本、规范文档——需要就只能是技能）

三个都"是"，写技能；只中第 1 条，写命令就够了。

想深入了解技能生态的两个高质量样本，可以接着读本方向另外两篇： Matt Pocock Skills 的使用、Superpowers Skills 的使用。

三、规则与记忆：让 AI 一直记得你是谁、这是什么项目

区分这两者的最简说法：规则是你写给 AI 的硬性约束，记忆是 AI 帮你记住的软性偏好。

	规则（Rule）	记忆（Memory）
谁写	你（手写 Markdown）	你 + AI 自动维护
加载	进对话就全量注入	按相关性注入
适合	强约束：技术栈、命名、禁止事项	偏好：称呼、语言、你的习惯
代价	每条规则都持续占用上下文	相对轻
位置	全局 / 项目规则目录	全局 / 项目记忆文件

3.1 规则：全量加载的硬约束

两种作用范围

类型	目录（国内版 / 国际版）	生效范围
全局规则	`~/.trae-cn/rules`（IDE 文档也记作 `~/.trae/user_rules`）	本机所有项目
项目规则	`<项目>/.trae/rules/`	仅当前项目

目录名不好记就别记

全局规则的落盘目录在 IDE 文档与 CLI 文档中写法不一致（user_rules / rules），实际以你的版本生成的目录为准。日常完全可以在 设置 > 规则与记忆 > 规则 面板里增删，不必手改路径。项目规则则稳定在 .trae/rules/，直接手写文件也没问题。

项目规则的四种生效方式（必须会选）

这是规则里最容易配错的地方。创建时选择「应用方式」，IDE 会自动帮你改 alwaysApply：

应用方式	触发条件	自动写入的字段	典型用途
Always Apply	当前项目内所有对话	`alwaysApply: true`	团队硬约束：禁止直接改 main、必须用 pnpm
Apply to Specific Files	你在对话中引用的文件命中 `globs` 时	`alwaysApply: false` + `globs`	针对目录的约定：`src/*/.ts` 的代码风格
Apply Intelligently	模型按 `description` 判断相关性	`alwaysApply: false` + `description`	场景规则：写 React 组件测试时用
Apply Manually	你在对话里用 `#Rule` 显式引用	`alwaysApply: false`	低频、只在需要时拉出来的检查清单

对应的 frontmatter 长这样：

markdown

---
description: 编写 React 组件测试时使用
globs: src/**/*.test.tsx
alwaysApply: false
---

- 测试文件名与被测组件同名
- 优先用 Testing Library 的 getByRole，禁止 snapshot

写规则的纪律

规则最贵的成本是全量注入——每多一条，每次对话都要多付一次 Token，而且会稀释真正重要的约束。所以：

只写"必须/禁止"级别的硬约束，不写背景知识（背景知识放技能或文档集）；
写成可执行、可验证的句子："提交信息用 Conventional Commits" 比 "注意代码质量" 有用一百倍；
长内容外置：规则里只放一句"见 docs/architecture.md"，需要时让 Agent 自己读；
能合并就合并：项目里 10 个碎规则文件不如 3 个主题清晰的文件。

上量之前先自查

如果你发现自己写了 20 条 Always Apply 规则，先问一句：这些真的每轮对话都相关吗？大概率其中一半应该改成 Apply Intelligently 或降级成技能。

与 `AGENTS.md` / `CLAUDE.md` 的关系

TraeCode 也兼容生态里通用的约定文件。CLI 侧明确支持把项目根目录的 AGENTS.md 作为项目记忆/指令文件（可以用 /init 生成默认结构），下级目录的 AGENTS.md 只在读取该目录文件时才加入上下文。

这给了一个很实用的迁移技巧：你为 Claude Code / Codex 写的 CLAUDE.md、AGENTS.md 不会白写，TraeCode 也能读到；反过来，把 .trae/rules/ 里的核心约束同步一份到 AGENTS.md，可以让同一套约定在不同 harness 之间复用。

3.2 记忆：AI 自己维护的偏好

两类记忆与存储位置

类型	生效范围	存储位置
全局记忆	本机所有项目	`~/.trae-cn/memory/user_profile.md`
项目记忆	仅当前项目	`~/.trae-cn/memory/projects/{project_path}/project_memory.md`

记忆数据只存在本地，不能跨设备同步。

开启与手动管理

设置 > 规则与记忆 > 记忆，打开「记忆」开关；
在 全局 / 项目 页签点击「用户记忆」或「项目记忆」区域，编辑器会直接打开对应的 .md 文件；
像写笔记一样增删改，保存即可生效。

让 AI 自己管

你想要的效果	直接说
新建记忆	"记住我偏好用中文回答" / "记住这个项目用 pnpm 不用 npm"
更新记忆	"以后叫我 David"
删除记忆	"删除关于我称呼的那条记忆"

AI 也会主动识别有价值的偏好并自动创建/更新记忆。

记忆里不该出现什么

官方明确列出三类不会被自动保存的内容：一次性临时指令、模糊不确定的偏好、敏感信息（密码、隐私）。最后一条请务必守住——记忆是明文 Markdown 存在本地的，不要往里塞密钥。

一个健康的记忆文件应该很短。如果它变成了几百行，说明该拆了：稳定的硬约束搬去规则，成体系的方法论搬去技能，只留真正的"个人偏好"在记忆里。

四、索引与文档：给 Agent 一座图书馆

模型看不到你的整个仓库。Agent IDE 解决这个问题的办法只有一个：先建索引，让"找对文件"变成一个可检索的问题。

4.1 工作区代码索引

进 设置 > 索引与文档 > 工作区，在「代码索引管理」处点 Build。

关键点	说明
自动构建	文件数 ≤ 5000 的项目，打开时自动构建
手动构建	文件数 > 5000 时，若想要准确的项目级回答，需要手动触发
忽略文件	可配置忽略规则，把文件完全排除在索引之外——既提升召回质量，也保护敏感数据
没建好的表现	用 `#Workspace` / `#Folder` 提问时，回答会提示「索引构建中 / 索引暂未构建」

索引直接决定 #Workspace 和 #Folder 的效果：没索引，AI 就是在闭着眼睛摸文件。

4.2 文档集（`#Doc`）：把外部资料变成可检索上下文

在 设置 > 索引与文档 > 文档集 点击「添加文档集」，支持两种方式：

方式	行为
通过 URL	以入口 URL 为起点，抓取同站点、同级路径或子路径下、最多 3 次跳转内的页面
通过本地文件	上传你自己的文档（规范、手册、笔记）

关于隐私，官方给出的机制值得记住：建索引时文档会被传输到服务器做矢量化，但不读取、不存储文档数据；矢量化完成后文档与矢量数据都会从服务器删除，返回本地存储；在 TraeCode 里删除文档集，本地数据同步删除。

4.3 `#` 引用：上下文工程的日常操作

在输入框输入 #，或点输入框左下角的 # 图标，就能精确指定上下文：

类型	适用场景
`#Code`	只需要某个函数/类
`#File`	需要整份文件
`#Folder`	需求涉及某个目录下多个文件（依赖索引）
`#Workspace`	让 AI 从整个项目里自己找相关内容（依赖索引）
`#Doc`	引用个人文档集 / 外部文档
`#Problems`	让 AI 分析「问题」页签里的诊断信息
`#Web`	联网搜索或读取网页
`#Rule`	显式引用某条项目规则
`#Past Chats`	引用历史对话

上下文工程只有一句话

给对的文件，而不是更多文件。 每次在 # 里多勾一个无关目录，都是在给模型增加噪声、给自己增加账单。Agent 越强，"少而准"的收益越明显。

五、MCP：给 Agent 装上「手脚」

5.1 MCP 是什么，以及它和技能的分工

MCP（Model Context Protocol）是一套让 Agent 调用外部工具的协议。可以理解成"AI 世界的 USB-C"：只要对端实现了 MCP Server，TraeCode 就能把它当成一组可调用的工具。

它和技能的关系，官方有一个非常清楚的例子：

技能告诉 Agent「怎么完成」任务，MCP Server 提供「能调用的工具」。比如：TraeCode 通过 Playwright MCP Server 获得页面操作能力；而对应的技能负责约定测试工程结构、页面对象模型（POM）规范、用例编写与执行流程。

也就是说：MCP 是能力，技能是用法。 只有 MCP，Agent 会乱用工具；只有技能，Agent 没工具可用。

5.2 添加 MCP Server

方式	路径	说明
从市场添加	设置 > MCP > 添加 > 从市场添加	社区热门 Server，填配置即可
手动添加	设置 > MCP > 添加 > 手动添加	自建或市场里没有的
项目级	`<项目>/.trae/mcp.json`	需要先在设置 > MCP 打开「启用项目级 MCP」开关

标记为 Local 的 Server 需要本地已装 npx 或 uvx。

5.3 配置：两种传输方式

stdio（本地进程，通过 stdin/stdout 通信）

json

{
  "mcpServers": {
    "mcp_name": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "API_Key": "value" }
    }
  }
}

字段	必填	说明
`command`	是	必须在 PATH 中，或用完整路径；命令中不能含空格，否则解析失败
`args`	否	参数数组，每项为字符串
`env`	否	传给 MCP Server 的环境变量，值必须为字符串

HTTP（远程服务）

json

{
  "mcpServers": {
    "mcp_name": {
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer xxxx-xxxxxxx" }
    }
  }
}

超时配置（stdio 放在 env，HTTP 放在 headers）：

json

{
  "START_MCP_TIMEOUT_MS": "60000",
  "RUN_MCP_TIMEOUT_MS": "60000"
}

变量引用：目前支持 ${workspaceFolder}，启动时自动替换为当前项目路径——这让你可以把 mcp.json 提交进仓库而不写死绝对路径。

5.4 安全与排错

项目级 MCP 有真实风险：.trae/mcp.json 会随仓库被 clone 下来，等于"别人可以往你的 Agent 里塞工具"。只对可信仓库开启，这也是官方把它做成默认关闭 + 需确认的原因。
依赖本地运行时：Local Server 报错先查 npx / uvx / Node 版本是否存在。
密钥走 env/headers，不要提交进仓库。
权限最小化：不是每个任务都需要所有 MCP，能停的就停。

5.5 一个完整案例：Playwright MCP 做网页验证

这是最能体现"Agent 从写代码到验代码闭环"的场景。配置好后，Agent 能拿到一批页面操作工具，例如：

能力类别	代表工具
导航与读取	`playwright_navigate`、`playwright_get_visible_text`、`playwright_get_visible_html`
交互	`playwright_click`、`playwright_fill`、`playwright_select`、`playwright_hover`、`playwright_press_key`、`playwright_drag`
断言与调试	`playwright_screenshot`、`playwright_console_logs`、`playwright_expect_response`、`playwright_assert_response`
HTTP	`playwright_get/post/put/patch/delete`
代码生成	`start_codegen_session` / `end_codegen_session`（把操作录成测试文件）

配套的技能才是关键：让它知道你们的测试工程目录长什么样、POM 怎么写、用例命名规则是什么。MCP 给手，技能给脑。

六、插件市场：把上面的能力打成一个包

技能（第二节）和 MCP（第五节）单独配都可行，但你要一个个装、一个个授权、一个个记位置。插件市场解决的是"把配好的一整套一次装齐"。

在 TraeCode 里，Agent 插件（Plugin）是一个"能力包"：它可以把一整套面向 Agent 的能力打包成一个可授权、可开关的单元。

插件里可能打包的东西	装完之后的效果
Skills	多了一套现成的流程说明书，不用自己拷 `SKILL.md`
MCP Server	多了一批可调用的工具
连接器（Connector）	通过 OAuth 等授权接上外部服务，密钥不用你硬编码
可执行二进制（Binaries）	自带 CLI，不用你全局安装

6.1 一个插件里到底装了什么

以官方市场里的一个真实插件（飞书）为例，它的清单精简后大致长这样：

json

{
  "name": "lark",
  "version": "1.0.5",
  "skills": "./skills/",          // 打包进来的技能目录
  "apps": "./.app.json",
  "connector": "./connector.json", // 需要 OAuth 授权的外部服务
  "binaries": [
    { "name": "lark-cli", "path": "bin/lark-cli", "executable": true }
  ],
  "interface": {
    "displayName": "飞书",
    "category": "Productivity",
    "capabilities": ["Interactive", "Read", "Write"]
  }
}

读这张清单能学到几个设计要点：

它自带可执行文件（binaries）——所以不需要你全局装 CLI；
它自带技能（skills）——装完就多了一套流程，不需要手动拷 SKILL.md；
它通过连接器拿凭证（connector + env 里的占位符）——所以密钥不用你硬编码进去；
它可以被单独启停——user_enabled 控制，禁用后能力整体下线。

这也解释了插件和前面讲的技能、MCP 是什么关系：插件是"打包盒"，技能和 MCP 是它往里装的东西。 你自己单独配技能和 MCP 完全可行，插件只是把「配好的一套」变成一次安装。

6.2 安装与启停

流程：在插件市场找到插件 → 安装 → 若涉及第三方服务，按提示完成授权 → 之后在插件详情页可以随时启用、禁用或卸载（禁用后该插件的能力整体下线）。

支持按任务勾选插件的客户端，还会让你在开始对话前挑选本次要用的插件，并且可以多选。这里建议不必全开：这既是权限管理（用不到的服务就别授权），也是上下文管理（工具越多，模型越容易分心）。

装插件时会弹安全警示面板，需要你确认后才启用。这是有意设计的：Agent 插件能改文件、能执行命令，等同于给了一个陌生人一把家里的钥匙，值得多点一次。

入口以你的客户端为准

插件市场与插件的具体入口在不同客户端（TraeCode IDE、TraeWork 桌面版/网页版等）略有差异，能力与配置项基本一致，以你界面上的提示为准。

七、Hook：在关键节点插上你自己的逻辑

Hook 是这套体系里最"进阶"的一层：它让 Agent 的执行流程变得可编程。

7.1 六个事件与生命周期

事件	触发时机	主要用途
`SessionStart`	创建 Session 后、第一次对话前	初始化环境、注入环境变量或补充上下文
`UserPromptSubmit`	用户发送 Query 后、Agent 开始处理前	拦截不允许的请求，或附加上下文
`PreToolUse`	Agent 发起工具调用后、实际执行前	校验、拦截、改参数、要求用户确认
`PostToolUse`	工具调用执行完成后	检查执行结果，向模型附加上下文
`Stop`	Agent 完成输出、准备结束当前 Query 时	验收产出；不达标可阻断停止让 Agent 继续干
`Notification`	等待用户确认时 / 任务完成时（异步，不阻塞）	发送通知

text

Session 创建
   ↓ SessionStart          ← 注入环境变量与上下文
   ↓ UserPromptSubmit      ← 拦截非法请求 / 附加上下文
   ↓ PreToolUse            ← 校验、拦截、改参数、要确认
   ↓ [工具执行]
   ↓ PostToolUse           ← 检查结果 / 追加反馈
   ↑______（还有工具调用则回到 PreToolUse）
   ↓ Stop                  ← 验收，不达标可阻断继续
Notification（异步旁路）

7.2 配置文件位置

类型	路径	作用范围
全局 Hook	`~/.trae-cn/hooks.json`（`~/.trae/hooks.json`）	本机当前用户的所有工作区
项目 Hook	`<项目>/.trae/hooks.json`	仅当前项目/工作区

TraeCode 还会读取 Claude Code 的 Hook 配置（~/.claude/settings.json、项目级 .claude/settings.json / settings.local.json）。多个配置文件共存时会合并执行——这意味着你为 Claude Code 写好的 Hook 可以零改动迁移过来。

7.3 配置格式

json

{
  "version": 1,
  "hooks": {
    "<EventName>": [
      {
        "matcher": "<ToolPattern>",
        "loop_limit": 5,
        "hooks": [
          {
            "type": "command",
            "command": "<shell command>",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

字段说明：

层级	字段	必填	说明
顶层	`version`	否	schema 版本，默认 `1`，当前仅支持 `1`
顶层	`hooks`	是	事件名 → Hook 组列表的映射
Hook 组	`matcher`	否	正则匹配工具名（如 `Edit
Hook 组	`loop_limit`	否	循环上限，`loop_count ≥ loop_limit` 时跳过该组。仅对 `Stop` 有效，默认 `5`
Hook 组	`hooks`	是	该组下要执行的 Hook 列表
Hook 定义	`type`	否	默认 `command`，当前仅支持 `command`
Hook 定义	`command`	是	要执行的 Shell 命令
Hook 定义	`timeout`	否	超时秒数，默认 `30`

7.4 输入输出：Hook 到底怎么和 Agent 对话

Hook 通过 stdin 收 JSON、stdout 吐结果、退出码控行为。stdin 的通用字段：

json

{
  "session_id": "string",
  "cwd": "/path/to/workspace",
  "hook_event_name": "PreToolUse",
  "workspace_roots": ["/path/to/workspace"]
}

stdout 有两种格式：

输出	效果
纯文本	内容作为附加上下文给模型。仅 `SessionStart` 和 `UserPromptSubmit` 支持
JSON	结构化控制流程，例如 `{"continue": false, "stopReason": "..."}` 让 Agent 停止

这就是为什么"往会话里注入一段开场白"这种需求只写一句 echo 就够了——它是纯文本输出，会被当作上下文附加。

7.5 五个实战范式

① 上下文注入（本仓库真实在用）

本项目的全局 Hook 就是一个极简例子——[hooks.json](file:///Users/jason/.trae-cn/hooks.json) 里用 SessionStart 把一段引导文本打进会话：

json

{
  "version": 1,
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo 'You have superpowers. Superpowers teach you new skills and capabilities. Before any task, check whether a matching skill exists. If one matches, you MUST use it. These are mandatory workflows, not suggestions.'",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

它做的事只有一件：每次开新会话，先告诉 Agent "你有一套技能，动手前必须先查、命中必须用"。这条正是 Superpowers Skills 的使用里讲的"引导层"落地方案 A。

② 安全护栏（PreToolUse）

json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.trae-cn/hooks/guard.py",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

guard.py 从 stdin 读到工具参数后，可以拒绝高危命令（如 rm -rf /）、保护 .env，或对特定操作要求二次确认。

③ 自动格式化（PostToolUse）

matcher: "Edit|Write"，命令里跑 prettier --write/gofmt，让 AI 每次改完文件就自动被格式化——省掉一整轮"你格式错了"的往复。

④ 完成前验收（Stop）

Stop 是最有杠杆的一个事件：Agent 说"我做完了"时触发你的脚本（跑测试、跑 lint），不通过就返回阻断，让 Agent 自己回去接着改。配合 loop_limit 可以防止无限循环。

⑤ 通知（Notification）

异步、不阻塞。适合长任务跑完时推一条消息到 IM 或系统通知。

用 Hook 前先想清楚代价

Hook 是阻塞的（除 Notification）：命令卡住，你的对话就卡住。一定要设 timeout。
它是可执行的任意 Shell：只运行自己信任的脚本，不要从不可信仓库加载项目级 Hook。
不要把重活放进去：Hook 适合"校验、注入、转发"，不适合跑几分钟的全量测试。

八、把它们串起来：一次完整的配置与使用

假设你要在一个已有仓库里加一个新功能。把上面的能力按顺序用一遍，链路是这样的：

阶段	用到的能力	具体动作
开场	Hook	`SessionStart` 注入引导：先查技能再动手
定规矩	规则	项目 `.trae/rules/` 写死技术栈与禁止事项；个人偏好交给记忆
找上下文	索引与文档	手动 Build 一次索引；把团队规范作为文档集，用 `#Doc` 引用
换脑子	模型	规划用长上下文模型；批量执行切便宜快的模型
走流程	技能	命中「TDD 开发」「代码评审」等技能，按既定方法论执行
手动动作	命令	`/summarize-pr-info`、`/plan`、`/spec`
拿工具	MCP	接 Playwright MCP 做页面验证
一次装齐	插件市场	装所需 Agent 插件（Skills + MCP + 连接器一并到位）并完成授权
兜底	Hook	`PreToolUse` 拦高危命令、`PostToolUse` 自动格式化、`Stop` 跑验收

速查表：能力 → 一句话 → 放哪儿

能力	一句话记住	最常用的落点
模型	不会调工具的模型等于聊天机器人	设置 > 模型
技能	模型自己会想起来翻的说明书	`.trae/skills/`
命令	你说了算的快捷键	`.trae/commands/`
规则	全量注入的硬约束，越少越好	`.trae/rules/`
记忆	AI 帮你记的偏好，别放密钥	`memory/user_profile.md`
索引/文档	先建索引，AI 才能"看得见"项目	设置 > 索引与文档
MCP	给 Agent 装手脚	设置 > MCP / `.trae/mcp.json`
插件市场	把上面的能力打包一次装齐	左侧插件市场
Hook	事件驱动的自动化与护栏	`.trae/hooks.json`

九、上手清单

第一天（把基础跑通）

切换一次模型，感受不同模型在同一个任务上的差别；
建一次工作区索引，试着用 #Workspace 问"这个项目的入口在哪"；
写一条项目规则（一条就够，比如提交信息规范），观察它是否被遵守；
建一个最简命令，把一段你天天重复打的 Prompt 变成 /xxx。

第一周（把重复劳动固化）

从技能市场装 1–2 个技能，观察它什么时候被触发；
把你的一个多步骤流程写成技能，重点打磨 description；
接一个 MCP（推荐从 Playwright 或你日常用的服务开始），配合技能一起用；
打开记忆，让 AI 记住 2–3 条你的真实偏好；
装一个 Agent 插件，体验"一次授权、能力一次装齐"的路径。

长期（把它变成工程资产）

给项目配 PreToolUse 护栏与 PostToolUse 格式化；
用 Stop 做"完成前验收"，把"我觉得做完了"变成"测试证明做完了"；
定期清理：删掉不再命中的技能、合并琐碎规则、给记忆瘦身。

一条贯穿全文的主线：规则约束行为，技能沉淀方法，命令复用话术，MCP 提供能力，插件负责打包，Hook 守住底线，索引与文档提供视野。 配好这七样，Agent IDE 才真正从"会写代码的工具"变成"能交付结果的工程伙伴"。

常见问题（FAQ）

AI Agent IDE 和 Copilot 这类补全工具有什么区别？

根本区别是工作对象变了：补全工具（第一代）的输入是光标位置 + 当前文件，产出是后面几行代码；Agent IDE 的输入是一个目标 + 一整套配置，产出是改完的工作区 + 证据。第三代的关键差别在于 Agent 有能力自己去找上下文、自己调工具、自己验证结果。而这三件事各自都依赖配置，所以配好一个 Agent IDE 不是调几个开关，而是把这套能力装齐。

技能（Skill）和命令（Command）有什么区别？

命令是你手动输入 / 触发的一段 Prompt 模板（一个 .md 文件），技能是模型自己判断、也可以点名调用的多步骤工作流（一个含 SKILL.md 的目录）。两者的加载方式也不同：命令触发时才读入，技能是扫 name/description、命中才读全文。一句话概括：命令是「快捷键」，技能是「说明书」。

规则（Rule）和记忆（Memory）有什么区别？

规则是你写给 AI 的硬性约束、进对话就全量注入，记忆是 AI 帮你记住的软性偏好、按相关性注入。规则最贵的成本就是全量注入——每多一条，每次对话都要多付一次 Token，所以只该写「必须/禁止」级别的硬约束；记忆则相对轻，但它是明文 Markdown 存在本地的，不要往里塞密钥。

MCP 和技能是什么关系？

MCP 是能力，技能是用法——技能告诉 Agent「怎么完成」任务，MCP Server 提供「能调用的工具」。只有 MCP，Agent 会乱用工具；只有技能，Agent 没工具可用。举个具体例子：TraeCode 通过 Playwright MCP Server 获得页面操作能力，而对应的技能负责约定测试工程结构、POM 规范、用例编写与执行流程。

为什么我写好的技能一直不被触发？

技能不被触发通常是因为 description 写得含糊：模型在任务开始前只会扫描所有技能的 name/description 来决定要不要加载全文，命中才读全文，所以含糊的 description 会让技能永远不被触发。写的时候要把「什么任务场景下用它」写进去，而不是复述它「是什么」。

项目级 MCP 有什么风险？

项目级 MCP 有真实风险：.trae/mcp.json 会随仓库被 clone 下来，等于「别人可以往你的 Agent 里塞工具」，这也是官方把它做成默认关闭 + 需确认的原因。所以只对可信仓库开启，密钥要走 env/headers、不要提交进仓库，并且能停的 MCP 就停。

AI Agent IDE 入门与进阶 ​

零、先建立认知：AI Agent IDE 不是「更快的补全」 ​

配置全景图（先看这张表，再看细节） ​

一、模型：Agent 的「大脑」 ​

1.1 在哪里切换 ​

1.2 选型：别看排名，看这四个维度 ​

1.3 配置自定义模型 ​

二、技能与命令：把流程固化成可执行资产 ​

2.1 命令：把常用 Prompt 变成 /xxx ​

存放位置 ​

创建一个命令 ​

使用 ​

2.2 技能：把方法论写成 Agent 能执行的说明书 ​

结构 ​

存放位置与类型 ​

创建与安装 ​

什么时候值得写一个技能 ​

三、规则与记忆：让 AI 一直记得你是谁、这是什么项目 ​

3.1 规则：全量加载的硬约束 ​

两种作用范围 ​

项目规则的四种生效方式（必须会选） ​

写规则的纪律 ​

与 AGENTS.md / CLAUDE.md 的关系 ​

3.2 记忆：AI 自己维护的偏好 ​

两类记忆与存储位置 ​

开启与手动管理 ​

让 AI 自己管 ​

四、索引与文档：给 Agent 一座图书馆 ​

4.1 工作区代码索引 ​

4.2 文档集（#Doc）：把外部资料变成可检索上下文 ​

4.3 # 引用：上下文工程的日常操作 ​

五、MCP：给 Agent 装上「手脚」 ​

5.1 MCP 是什么，以及它和技能的分工 ​

5.2 添加 MCP Server ​

5.3 配置：两种传输方式 ​

5.4 安全与排错 ​

5.5 一个完整案例：Playwright MCP 做网页验证 ​

六、插件市场：把上面的能力打成一个包 ​

6.1 一个插件里到底装了什么 ​

6.2 安装与启停 ​

七、Hook：在关键节点插上你自己的逻辑 ​

7.1 六个事件与生命周期 ​

7.2 配置文件位置 ​

7.3 配置格式 ​

7.4 输入输出：Hook 到底怎么和 Agent 对话 ​

7.5 五个实战范式 ​

八、把它们串起来：一次完整的配置与使用 ​

速查表：能力 → 一句话 → 放哪儿 ​

九、上手清单 ​

常见问题（FAQ） ​

AI Agent IDE 和 Copilot 这类补全工具有什么区别？ ​

技能（Skill）和命令（Command）有什么区别？ ​

规则（Rule）和记忆（Memory）有什么区别？ ​

MCP 和技能是什么关系？ ​

为什么我写好的技能一直不被触发？ ​

项目级 MCP 有什么风险？ ​

参考文档 ​

AI Agent IDE 入门与进阶

零、先建立认知：AI Agent IDE 不是「更快的补全」

配置全景图（先看这张表，再看细节）

一、模型：Agent 的「大脑」

1.1 在哪里切换

1.2 选型：别看排名，看这四个维度

1.3 配置自定义模型

二、技能与命令：把流程固化成可执行资产

2.1 命令：把常用 Prompt 变成 `/xxx`

存放位置

创建一个命令

使用

2.2 技能：把方法论写成 Agent 能执行的说明书

结构

存放位置与类型

创建与安装

什么时候值得写一个技能

三、规则与记忆：让 AI 一直记得你是谁、这是什么项目

3.1 规则：全量加载的硬约束

两种作用范围

项目规则的四种生效方式（必须会选）

写规则的纪律

与 `AGENTS.md` / `CLAUDE.md` 的关系

3.2 记忆：AI 自己维护的偏好

两类记忆与存储位置

开启与手动管理

让 AI 自己管

四、索引与文档：给 Agent 一座图书馆

4.1 工作区代码索引

4.2 文档集（`#Doc`）：把外部资料变成可检索上下文

4.3 `#` 引用：上下文工程的日常操作

五、MCP：给 Agent 装上「手脚」

5.1 MCP 是什么，以及它和技能的分工

5.2 添加 MCP Server

5.3 配置：两种传输方式

5.4 安全与排错

5.5 一个完整案例：Playwright MCP 做网页验证

六、插件市场：把上面的能力打成一个包

6.1 一个插件里到底装了什么

6.2 安装与启停

七、Hook：在关键节点插上你自己的逻辑

7.1 六个事件与生命周期

7.2 配置文件位置

7.3 配置格式

7.4 输入输出：Hook 到底怎么和 Agent 对话

7.5 五个实战范式

八、把它们串起来：一次完整的配置与使用

速查表：能力 → 一句话 → 放哪儿

九、上手清单

常见问题（FAQ）

AI Agent IDE 和 Copilot 这类补全工具有什么区别？

技能（Skill）和命令（Command）有什么区别？

规则（Rule）和记忆（Memory）有什么区别？

MCP 和技能是什么关系？

为什么我写好的技能一直不被触发？

项目级 MCP 有什么风险？

参考文档