TraeCode

01 学习交流群

知识库之外，我们还建了「主流 Agent 入门交流群」。

进群和大家一起交流主流 Agent 的使用方法、适用场景和入门实践，分享不同工具的上手经验、工作流与真实案例，也会同步专题最新更新和实战资料。

扫码加入，一起找到适合自己的 Agent，真正用起来。

02 学前须知

本教程配套代码素材：https://gitee.com/geektime-geekbang_admin/ai-tutorial-material/tree/master/traecode-materials

03 认识TraeCode

第一章 认识 TraeCode

1.1 什么是 TraeCode？能做什么？

TraeCode 是一款深度融合 AI 能力的开发工具，覆盖从代码编写、项目理解、调试运行到变更管理的完整开发流程。它的核心思路是：你用自然语言描述需求，AI 智能体理解代码仓库、读取和修改文件、执行命令、生成和评审代码，帮你完成繁琐的开发任务，让你专注于更有价值的创造性工作。

一句话概括：TraeCode 让 AI 不只是补全代码，而是参与需求拆解、代码生成、问题排查、重构优化和变更管理等真实开发环节。

1.2 TRAE 产品矩阵一览

TRAE 企业版提供四类产品，适应不同使用习惯：

1.3 各产品适合什么场景？

1.4 为什么本教程以 CLI 为主线？

• 贴近终端开发流程：从理解需求、修改代码、运行测试到评审变更，都能在终端连续完成。
• 可自动化：支持非交互模式，能融入脚本和 CI 流程，这是 CLI 的杀手锏。
• 学习成本低：一条命令安装，开箱即用。
• 核心能力覆盖最全：代码理解、修改、测试、Git、MCP、插件、技能、自定义命令——CLI 都能玩转。

提示：TraeCode CLI 目前仅 TRAE 企业版旗舰版套餐 可用，且默认使用 Max 模式，请注意用量消耗。本教程假设你已具备相应账号权限。

04 安装与初始化

第二章 安装与初始化（多操作系统详解）

本章手把手带你完成安装。文字步骤尽量写清楚，让你光看文字就能操作。

2.1 系统要求

安装前，请确认设备满足以下要求：

此外，你的电脑需要有可用的终端环境和可用的 TRAE 账号权限。

本教程以 TraeCode CLI 2.0（当前最新版本）为准。

2.2 macOS 安装

第 1 步：打开终端

• 方式一：按 Command + 空格 打开「聚焦搜索」，输入 终端 或 Terminal，回车打开。
• 方式二：打开「访达」→ 顶部菜单「前往」→「实用工具」→ 双击「终端」。

第 2 步：执行安装脚本

在终端窗口中，粘贴下面这一行命令并回车：

sh -c "$(curl -fsSL https://trae.cn/trae-cli/install_v2.sh)"

脚本会自动下载并安装最新版 TraeCode CLI。过程中可能提示输入密码（你的 Mac 登录密码，输入时不会显示字符，属正常现象）。

第 3 步：验证安装

安装完成后，在终端执行：

traecli --version

如果输出类似 traecli version 2.x.x 的版本号，说明安装成功，可以跳到 2.6 节登录。

如果提示 command not found: traecli：说明可执行文件所在目录不在 PATH 中。CLI 通常安装到 ~/.local/bin，手动把它加进 PATH：

echo 'export PATH=~/.local/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

如果你用的是 bash 而非 zsh，把上面两行里的 .zshrc 换成 .bash_profile。

2.3 Linux 安装

第 1 步：打开终端

• Ubuntu/Debian：按 Ctrl + Alt + T 打开终端。
• 其他发行版：在应用列表中搜索「Terminal」或「终端」。

第 2 步：执行安装脚本

sh -c "$(curl -fsSL https://trae.cn/trae-cli/install_v2.sh)"

如果系统提示缺少 curl，先装一下：

sudo apt update && sudo apt install -y curl

第 3 步：验证安装

traecli --version

看到版本号即成功。若提示 command not found，把 ~/.local/bin 加入 PATH：

echo 'export PATH=~/.local/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

2.4 Windows WSL2 安装（Windows 用户推荐）

TraeCode 官方建议 Windows 用户优先使用 WSL2，因为能获得接近原生 Linux 的开发体验。本节带你从零配置。

第 1 步：确认 Windows 版本

按 Win + R，输入 winver 回车。需为 Windows 10（版本 2004+）或 Windows 11。若版本过低，先更新系统。

第 2 步：安装 WSL2 与 Ubuntu

以管理员身份打开 PowerShell：右键点击「开始」菜单 → 选择「Windows PowerShell（管理员）」或「终端（管理员）」。

执行：

wsl --install -d Ubuntu

这会一次性安装 WSL2 虚拟机平台和一个 Ubuntu 发行版。安装完成后重启电脑。

重启后，Ubuntu 会自动弹出窗口（或从开始菜单点开「Ubuntu」），首次启动会让你设置一个 Linux 用户名和密码。密码输入时不显示字符，这是正常的，设好并记住。

第 3 步：进入 WSL 终端

以后打开 WSL 的方式：

• 方式一：开始菜单搜索「Ubuntu」并打开。
• 方式二：在 PowerShell 或 Windows Terminal 里输入 wsl 回车。

进入后，提示符会变成类似 用户名@电脑名:~$，说明你已在 Linux 环境中。

第 4 步：在 WSL 中安装 TraeCode CLI

在 WSL 终端中执行（和 Linux 一样的脚本）：

sudo apt update && sudo apt install -y curl
sh -c "$(curl -fsSL https://trae.cn/trae-cli/install_v2.sh)"

第 5 步：验证安装

traecli --version

看到版本号即成功。若 command not found，同样把 ~/.local/bin 加入 PATH：

echo 'export PATH=~/.local/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

小贴士：在 WSL 中，你的 Windows C 盘挂在 /mnt/c。建议把项目放在 WSL 原生目录（如 ~ 下），性能比放在 /mnt/c 更好。

2.5 Windows PowerShell 原生安装

如果你不想用 WSL2，也可以在 Windows 原生环境安装。

第 1 步：打开 PowerShell

按 Win + S 打开搜索，输入 PowerShell，点击「Windows PowerShell」打开（普通权限即可，无需管理员）。

第 2 步：执行安装脚本

在 PowerShell 窗口中粘贴并回车：

irm https://trae.cn/trae-cli/install_v2.ps1 | iex

脚本会自动下载安装。

第 3 步：安装 VC 运行库（如需要）

如果安装后提示 TraeCode CLI 自带的 Ripgrep 不可用，需要额外安装 Visual C++ Redistributable（VC 运行库）：

• 打开浏览器访问 微软官方下载页
• 下载 vc_redist.x64.exe 并双击安装

第 4 步：验证安装

关闭并重新打开 PowerShell（让 PATH 生效），执行：

traecli --version

看到版本号即成功。

第 5 步：完成沙箱初始化（首次启动时）

首次运行 traecli 时，Windows 原生版会按界面提示引导你完成沙箱初始化，按提示操作即可。沙箱用于在受限环境中执行命令，降低误操作风险。

2.6 首次启动与登录

安装完成后，我们来启动并登录。

第 1 步：进入一个项目目录

随便选一个文件夹（可以先用一个已有项目，或新建一个）：

# macOS / Linux / WSL2
cd ~/Desktop/my-project

# Windows PowerShell
cd $env:USERPROFILE\Desktop\my-project

如果目录不存在，先用 mkdir my-project && cd my-project（macOS/Linux/WSL2）或 New-Item -ItemType Directory my-project; cd my-project（PowerShell）创建。

第 2 步：启动 TraeCode CLI

traecli

启动后你会进入交互式 TUI（终端图形界面），底部有一个输入框。

第 3 步：登录

首次打开时，TUI 会自动引导你登录。登录界面支持：

• 账号登录：用你的 TRAE 企业账号。
• 自定义域登录：如果你的组织使用自定义 API 域名，按提示填写。

在输入框随便发一句话（比如「你好」），首次会唤起登录页面，按网页提示完成授权，然后返回 CLI 即可开始使用。

查看 / 退出登录状态（在终端中执行）：

traecli login status   # 查看登录状态
traecli logout          # 退出登录

自动化场景用 PAT 登录（无需交互，适合 CI）：

# 交互输入，不把真实 token 写进 shell 历史
stty -echo
IFS= read -r TRAECLI_PERSONAL_ACCESS_TOKEN
stty echo
export TRAECLI_PERSONAL_ACCESS_TOKEN
traecli login --with-trae-pat

如果组织用自定义 API 域名，再加一个环境变量：

export TRAECLI_HOST="https://api.example.com"
# 交互输入，不把真实 token 写进 shell 历史
stty -echo
IFS= read -r TRAECLI_PERSONAL_ACCESS_TOKEN
stty echo
export TRAECLI_PERSONAL_ACCESS_TOKEN
traecli login --with-trae-pat

PAT 是可选自动化路线。Windows 请使用 Read-Host -AsSecureString 后在当前进程设置变量；不要在命令行字面写入真实 token。主线使用交互登录即可。

2.7 升级方式

TraeCode CLI 支持两种升级方式：

• 自动升级：启动 CLI 后，若当前版本非最新，会自动开始升级并在界面右下角提示状态。
• 手动升级：在终端执行：

traecli update

至此，你已经装好并登录了 TraeCode CLI。下一章我们先用一个现成项目练手，熟悉基本交互。

05 初体验

3.1 启动与核对环境

在一个独立练习目录运行 traecli，先输入 /status，核对当前目录、模型与权限。也可 traecli --cd "/实际项目路径"，其中路径先替换。Enter 发送，Shift+Enter 换行；不生效时查看 /help 或 /terminal-setup。

3.2 第一次只做调查

选择一个自己了解的小项目，要求助手说明入口、主要模块、依赖和测试命令，并为结论给出文件位置。此阶段使用只读权限，明确不运行未知安装脚本。对照目录和源码核查答案，未找到测试时应如实报告，不编造命令。

3.3 文件引用与命令输入

输入 @ 后从列表选择实际存在的文件，追问某个函数的输入、输出和调用方。不要照抄示例中的 src/main.py，当前项目可能没有它。

CLI 2.0 的输入框支持以 ! 进入 Shell 命令模式，例如 !pwd（PowerShell 环境可用 !Get-Location）；它会执行真实命令。先读命令与当前目录，别把查看环境变量变成打印全部凭据。自然语言请求执行命令同样受实际权限约束。

3.4 先掌握少量斜杠命令

先用 /status 检查，再用 /new 开始另一项小调查。旧文档中的 /clear、--resume、--session-id 不作为本课程 2.0 的必需入口；当前会话恢复使用已在 2.0 文档列出的 /resume。

3.5 图片和恢复后的验收

支持图片输入的终端可用 Cmd+V／Ctrl+V 粘贴截图，先遮挡敏感内容。识别小票后先给出拟录入字段，由你核对金额和日期，不直接写入真实账本。

恢复会话后先重新检查 git status、目录和现有测试。会话记忆不是当前文件状态；/fork 也不自动创建 Git worktree。试验回退先在副本进行：2.0 文档的 /rewind 会回退对话与工作区，使用前先保存要保留的改动，之后检查 diff。

3.6 信任目录

首次打开项目可能询问信任。项目配置、规则和 Hook 可影响执行行为，陌生仓库先检查这些文件。下一章从自己的新项目开始，固定账本接口后再让助手实施。

参考：2.0 基础用法、2.0 斜杠命令。

06 实战项目启动-家庭账本

第四章 实战项目启动——搭建「家庭账本」

从本章开始，我们用一个贯穿后续所有章节的项目来学习。

4.1 项目背景与需求

项目名称：家庭账本（Family Ledger）

目标：一个命令行记账小工具，用 Python 编写，支持：

1. 记录每一笔收支（金额、分类、备注、日期）
2. 按分类统计支出占比
3. 生成月度收支报表
4. 数据存到本地 SQLite 数据库

为什么选这个项目？

• 贴近生活，做完真能用。
• 涵盖文件读写、数据库、数据处理、测试、Git 等核心知识点。
• 复杂度适中，能持续加功能，适合逐步学习。

4.2 用 CLI 创建项目骨架

第 1 步：创建项目目录并初始化 Git

# macOS / Linux / WSL2
mkdir -p ~/projects/family-ledger && cd ~/projects/family-ledger
git init -b main

# Windows PowerShell
New-Item -ItemType Directory -Force -Path projects\family-ledger
cd projects\family-ledger
git init -b main

Git 在所有操作系统的命令一致。如果你还没装 Git：macOS 装完 Xcode Command Line Tools 就有（xcode-select --install）；Linux 用 sudo apt install -y git；Windows 去 git-scm.com 下载安装。

第 2 步：启动 CLI，让它帮你设计目录结构

traecli

在输入框发送：

我要用 Python 做一个命令行家庭记账工具，叫 family-ledger。
功能包括：记录收支、按分类统计、月度报表、数据存 SQLite。
请帮我设计项目目录结构，并说明每个文件/目录的职责。

CLI 会给出一个结构方案，比如：

family-ledger/
├── src/
│   ├── __init__.py
│   ├── models.py        # 数据模型
│   ├── storage.py       # SQLite 存储层
│   ├── ledger.py        # 记账核心逻辑
│   ├── stats.py         # 分类统计
│   ├── report.py        # 月度报表
│   └── cli_app.py       # 命令行入口
├── tests/               # 单元测试
├── data/                # 数据库文件存放
├── requirements.txt     # 依赖
├── README.md            # 项目说明
└── .gitignore           # Git 忽略规则

4.3 养成开发规范

好习惯从第一天开始。我们先把规范文件建好。

第 1 步：创建 .gitignore

让 CLI 帮你生成：

帮我生成一个适合 Python 项目的 .gitignore，要忽略虚拟环境、__pycache__、SQLite 数据库文件等。

CLI 会创建文件。重点确认这几行在 .gitignore 里（数据文件不入版本库）：

__pycache__/
*.pyc
.venv/
venv/
data/*.db
data/*.sqlite

第 2 步：写 README.md

帮我写一个 README.md，介绍 family-ledger 是什么、有什么功能、如何安装运行。

第 3 步：约定 commit message 规范

我们采用 Conventional Commits（约定式提交），格式：

<type>: <description>

常见 type：feat（新功能）、fix（修 bug）、docs（文档）、refactor（重构）、test（测试）、chore（杂项）。

例如：feat: 新增记账录入功能、fix: 修复金额计算精度问题。

你可以让 CLI 帮你记下这个规范——下一章我们会用 AGENTS.md 把它沉淀进项目（见第八章详细讲）。

4.4 让 CLI 写第一行代码

先把本课 ledger-starter 的 README、fixture 和 tests 复制到自己的项目；卡住时可对照 ledger-reference。

第 1 步：创建 Python 虚拟环境

# macOS / Linux / WSL2
python3 -m venv .venv
source .venv/bin/activate

# Windows PowerShell
py -m venv .venv
.\.venv\Scripts\Activate.ps1

如果 PowerShell 提示「无法加载脚本，因为在此系统上禁止运行脚本」，先执行一次：Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned，再重试激活。

激活后，命令行提示符前面会出现 (.venv)，说明你已在虚拟环境中。后续所有 Python / pip 命令都在这个环境里跑。

第 2 步：让 CLI 实现「记账录入」功能

在 CLI 里发送：

帮我实现 src/ledger.py 和 src/storage.py。
storage.py 用 SQLite 存储，entries 表字段：id、amount_cents（整数分）、type（收入/支出）、category、date、note。输入金额为元，用 Decimal 从字符串换算；不要先用浮点存储再中途迁移。
ledger.py 实现输入校验和收支规则；补齐 src/cli_app.py，入口 python -m src.cli_app，全局 --data 默认 data/ledger.db，add 接受 --amount、--type、--category、--date、--note，list 列出账目。参考 exercise-assets/ledger-starter 中的固定契约，不随生成结果改接口。
请给出完整代码。

CLI 会读取（或创建）这两个文件并写入代码。

第 3 步：人工审查 CLI 生成的代码

养成习惯：不要盲目接受 AI 的输出。CLI 每次修改文件都会显示 diff（改动对比），你要：

1. 看它改了哪些文件、加了哪些行。
2. 理解逻辑：表结构对不对？金额用什么类型存？日期格式是否统一？
3. 发现问题就追问让 CLI 改，比如「金额应该用整数分存储，避免浮点精度问题，请修改」。

4.5 从函数到可操作的入口

使用已激活环境中的 python，第一次在全新的 data/ledger.db 运行以下命令；已有个人数据时改用独立实验路径：

python -m src.cli_app --data data/ledger.db add --amount 8000 --type 收入 --category 工资 --date 2026-09-01
python -m src.cli_app --data data/ledger.db add --amount 35 --type 支出 --category 餐饮 --date 2026-09-02
python -m src.cli_app --data data/ledger.db add --amount 12 --type 支出 --category 交通 --date 2026-09-03
python -m src.cli_app --data data/ledger.db list

预期三条数据，amount_cents 分别为 800000、3500、1200。下一章 summary/report --month 2026-09 的期望收入为 800000 分，支出 4700 分，结余 795300 分；完成该阶段后运行 python -m unittest discover -s tests -v。每章先确认入口存在且前一阶段测试通过，再增加功能。

4.6 第一次提交

功能写好、审查通过后，提交第一个 commit。

帮我把暂存区的文件提交了，提交信息符合 Conventional Commits 规范，描述这次新增了记账存储功能。

CLI 会执行 git add 和 git commit。你也可以手动操作，对比一下 CLI 生成 的 message 和你自己写的：

# 手动方式（所有 OS 通用）
git add .
git commit -m "feat: 新增记账录入与 SQLite 存储功能"

提交后查看历史确认：

git log --oneline

应该能看到刚才的提交记录。

到此，「家庭账本」有了骨架和第一个功能。下一章我们继续加功能，在实战中学习代码理解、功能开发和分支管理。

07 代码理解与功能开发

5.1 接续第 4 章的固定接口

先确认 python -m src.cli_app --data data/ledger.db list 能读到三条九月样例。金额存整数分；输入 --amount 的单位为元。让助手说明 src/ledger.py 的业务函数、src/storage.py 的 load/save 和 src/cli_app.py 的 CLI 入口，不要猜测不存在的 get_records 或 run 接口。

5.2 增加月度汇总

从干净提交创建 feat/monthly-report 分支。先要求助手写计划，确认后实现 summary --month YYYY-MM 和 report --month YYYY-MM --export 路径。汇总 JSON 固定包含 month、income_cents、expense_cents、balance_cents、categories_cents；分类只统计支出。report 与 summary 复用 summarize，导出 CSV 时字段同样标明 cents，不把分显示成元。

python -m src.cli_app --data data/ledger.db summary --month 2026-09
python -m src.cli_app --data data/ledger.db report --month 2026-09 --export reports/2026-09.csv

固定样例应得到收入 800000 分、支出 4700 分、结余 795300 分。若要面向用户显示金额，4700 分显示为 47.00 元；餐饮 3500 分、交通 1200 分，占支出的 74.47% 与 25.53%。空月份返回全零、空分类，不除以零。

5.3 先运行契约测试，再合并

第 4 章 starter 附带 tests/test_contract.py。完成实现后运行 python -m unittest discover -s tests -v，它使用临时数据库，不修改真实账本；再打开导出文件核对数据。若卡住可对照 exercise-assets/ledger-reference，先读差异再理解原因，不把参考文件直接覆盖自己的数据。

确认参数错误非零退出、非法输入不增加账目、月度筛选正确。检查 git status 和 diff，提交本功能后切回 main 合并。删除已合并分支用 git branch -d，合并冲突须解决并重跑测试，不能通过删除测试来“消除冲突”。

5.4 适度拆分

本课实现规模不大，先保持 CLI、存储、业务三个边界。只有报表输出与业务计算开始互相干扰时，再抽出 report 模块；不为了展示模块数重复 SQL 或另建一套金额模型。

08 测试与调试

6.1 接着固定契约增加边界测试

从第 5 章已通过的版本创建 test/ledger-boundaries 分支。当前接口是 src.ledger.cents、validate、summarize 与 storage.load/save；没有要求额外生成 stats.py。让助手用标准库 unittest 在 tests/test_ledger.py 补边界，每项断言具体数值或错误类型，不只是“结果不为空”。

先手算：0.10 元＋0.20 元是 30 分；一个月只有收入时 expense_cents 为 0、categories_cents 为空；九月样例支出 4700 分，不能混入八月记录。

6.2 三层测试各有职责

纯函数测金额换算、空月份与分类汇总；SQLite 测试每项用 TemporaryDirectory 创建独立数据库并检查保存／重读；CLI 测试用 subprocess 运行实际入口，检查退出码、JSON 和数据库记录数。不要读取个人 data/ledger.db。

python -m unittest discover -s tests -v

所有系统都使用当前已激活虚拟环境的 python。只增加 unittest 测试，后续 Git hook 与 CI 才能使用同一发现命令；若自行改用 pytest，必须一起修改全部验收入口。

6.3 先确认缺陷，再修实现

在独立 precision-lab.py 演示 assert 0.1 + 0.2 == 0.3 会失败，再对比 Decimal 字符串运算。主项目已经存整数分，不能假定它仍有浮点缺陷。

新增 CLI 回归：0.001、NaN、负金额和无效日期应非零退出，已有记录数和金额不变。测试先失败时，核对是否读了正确的临时数据库、预期是否符合契约，再修对应实现；已经通过则只提交覆盖补充。

旧 amount 元字段如需迁移，另开任务：备份、检查 schema、事务内转整数分、核对总额和记录数、失败回滚。重复迁移不得再次乘 100，不把改列名当单位迁移。

6.4 完成本章

先运行测试，再 git status 和 git diff；提交仅包含边界测试及必要修复。确认通过后合并回 main。记录一个确实被测试抓住的反例，以及一个没有改动产品代码的覆盖补充。

09 Git工作流自动化

7.1 小步提交

在功能分支运行测试，git status --short 查看所有文件，git diff 看未暂存改动，git add 明确选择文件后用 git diff --cached 再看本次提交。请助手基于暂存差异拟提交信息，人工核对后提交；不要把未暂存功能写进本次说明。

7.2 查询历史

让助手用 git log 和 git show 找到某个功能引入的提交，返回提交号及文件证据。提交信息只能提供线索，是否真正实现仍要读 diff。

7.3 合并前审查

在功能分支且工作区干净时，先确认基准分支，再 git diff main...HEAD，要求助手对照需求和测试查找回归。修复并独立验收后，保存 main 和功能分支的提交号。若第 5 章已经合并，使用保存的两个提交比较，不要期待 main...HEAD 仍有差异。

7.4 单独练习合并冲突

在新的临时 Git 仓库创建文本文件并提交。从同一基线分别建 branch-a 和 branch-b，各自修改同一行并提交。在 branch-a 合并 branch-b 应产生冲突。请助手解释两侧意图，人工决定结果，再 git add 和 git commit；检查合并提交包含预期文本。这个实验独立于账本，避免为了造冲突破坏主线函数接口。

回到实际账本，冲突解决后重新跑完整测试再提交。不能为消除冲突而盲选一整侧，也不能删除失败测试。合并后用明确提交号核对结果，已合并分支用 git branch -d 清理。

7.5 结束条件

需求、差异与验收对应；main 保持可用；无误提交数据文件。分支或会话名字不会隔离未提交文件，激进实验优先使用独立 worktree。

10 自定义斜杠命令与AGENTS

8.1 把已验证的约定写进 AGENTS.md

在项目根目录创建 AGENTS.md，记录 Python 版本、src/cli_app.py 入口、整数分单位、--data 参数、测试命令和真实数据保护规则。先让助手读取现有实现和测试再拟稿，删除尚未实现的命令。新会话要求复述关键约束，再用实际 diff 和测试验收。

8.2 先保存普通任务模板

CLI 2.0 官方扩展页提供 /plugins、/skills、/mcp；旧 .traecli/commands/*.md 的自动加载协议未在当前参考中确认，因此本课不依赖它。建立 docs/prompts/review.md，内容包括：比较基准、允许读取的范围、检查正确性与回归风险、每项发现的文件位置及触发输入、允许零发现。使用时明确把文件内容作为本次审查任务提供，不能假定写文件后 /review 自动出现。

再建立 docs/prompts/changelog.md：根据指定两个提交之间的 git log 与 diff 生成变更草稿，区分功能、修复与兼容性；不把未提交改动写成已发布内容。通过后才人工写入 CHANGELOG。

8.3 何时迁移成扩展

先在两个会话里验证模板能重复使用，再按本机 /plugins 或 /skills 的帮助安装成正式扩展。扩展目录、frontmatter 和参数以同代官方规范为准；没有确认协议时保留普通 Markdown 流程，避免把旧路径写成最新保证。

参考：CLI 2.0 扩展。

11 全局配置自定义智能体与记忆

9.1 固定 CLI 2.0 文档基线

本次按 2026-10-02 官方 CLI 2.0 参考修订；本机未安装该产品，产品操作仍需按本机发行版验收。先保存 traecli --version、traecli --help、traecli exec --help。不能把旧使用场景页的 YAML 与 2.0 TOML 混用。

用户配置为 ~/.trae/traecli.toml。日常优先用 /model、/permissions、/login。最小默认策略：

approval_policy = "on-request"
default_permissions = ":workspace"

修改配置前保留自己的备份，重启后核对生效范围；模型名由实际账号列表选择，不复制无权限的占位模型。

9.2 先给分析角色准备可读数据

文本 Read/cat 工具不能把 SQLite 文件当 CSV。主线先用第 5 章 summary 导出结果，再交给只读分析角色：

python -m src.cli_app --data data/ledger.db add --amount 40 --type 支出 --category 餐饮 --date 2026-08-02
python -m src.cli_app --data data/ledger.db summary --month 2026-08 > august.json
python -m src.cli_app --data data/ledger.db summary --month 2026-09 > september.json

这笔八月数据只在课程数据库中追加一次。另建 budget.json：{"month":"2026-09","expense_budget_cents":4500}。预期八月支出 4000 分，九月 4700 分，环比增加 17.5%，超预算 200 分；这是练习结果，不是个人财务建议。

9.3 限定分析任务

给角色的任务只引用 august.json、september.json、budget.json，要求列数据来源、计算式和未知项。使用只读沙箱，不授权任意 Bash；与第 10 章的数据库 MCP 路线二选一，不同时堆叠配置。没有上月数据时不能编造环比。

9.4 记忆与执行边界

AGENTS.md 记录已验证的入口、整数分单位、数据忽略规则与测试命令。它是上下文约定，不是强制执行测试或数据库权限的机制；结果仍由独立命令验收。

参考：官方配置参考。

12 MCP插件与技能扩展

10.1 前提

完成第 4～5 章后，data/ledger.db 有三条固定九月账目，summary 通过验收。安装本课固定的官方 Python MCP SDK mcp==1.26.0，把 ledger_readonly_mcp.py 复制到项目 scripts/。

10.2 配置一个 stdio MCP

在 CLI 2.0 的 ~/.trae/traecli.toml 增加以下条目。先用 python -c "import sys; print(sys.executable)" 找到虚拟环境解释器，并替换三个绝对路径；Windows 可用 TOML 单引号保存反斜杠路径。

[mcp_servers.ledger_readonly]
command = "/absolute/path/.venv/bin/python"
args = ["/absolute/path/scripts/ledger_readonly_mcp.py", "/absolute/path/data/ledger.db"]

重开会话后用 /mcp 核对服务和工具列表。只应暴露 monthly_totals。调用 2026-09，期望收入 800000 分、支出 4700 分。服务使用 SQLite mode=ro 和 query_only，不靠工具名字包含 write 与否判断权限。独立尝试同一连接执行 INSERT 必须得到 readonly 错误。

10.3 服务端与客户端不能混淆

gh api mcp 不是 MCP 服务；gh api 是 HTTP API 客户端。需要 GitHub 能力时另行按 GitHub 官方 MCP server 配置，分别验证初始化、工具列表、认证与只读调用，不复用不存在的 stdio 协议。

本章先完成一条账本查询闭环。插件、传输和字段全集只在需要时查官方参考；/plugins、/skills、/mcp 是不同管理入口，避免为了介绍功能而加入无关配置。

参考：CLI 2.0 配置、工具与扩展。

13 自动化与CI集成

11.1 CLI 2.0 的非交互入口

traecli exec --sandbox read-only --ask-for-approval never -o review.txt "只读取当前项目，列出测试入口和潜在问题，不修改文件"

exec 是非交互入口；-p 选择 profile，不是 print。--json 输出 JSONL 事件流，不能对整份日志直接读 .result；需要最终机器结果时使用 --output-schema 约束，并用 -o 保存最终答复，先检查 CLI 退出码再解析。文档基线和配置见第 9 章。

11.2 测试门禁

先用 python -m unittest discover -s tests -v（自己的项目用 pytest 时才改成 pytest）作为 CI 门禁。AI Review 是补充报告，不用 grep OK 判断，NOT OK 也含 OK。不要为只读审查预授权全部 Bash。

完整调用的超时应由外部 runner 或 subprocess 的总 deadline 控制；单个 Bash 工具超时不等于查询总时限。中断后核对进程树是否已停止，并保留日志。

11.3 Git hook 的跨平台入口

Git 只查找 .githooks/pre-commit，不会自动执行 pre-commit.ps1。POSIX／Git Bash 的入口可写为：

#!/bin/sh
exec python -m unittest discover -s tests -v

Windows 若测试逻辑放在 PowerShell，仍保留无扩展名 pre-commit 启动器：

#!/bin/sh
exec pwsh -NoProfile -File .githooks/pre-commit.ps1

对应 pre-commit.ps1：

python -m unittest discover -s tests -v
exit $LASTEXITCODE

先确认已安装 pwsh，执行 git config core.hooksPath .githooks，Unix 给入口可执行权限。把一项测试临时设为必失败，尝试提交应被拒绝；恢复后才能提交。不要只看配置文件存在。

11.4 报告的使用

固定 schema 可要求 status 仅为 pass/fail、findings 为数组，仍不能用模型 pass 替代程序测试。运行失败、超时、格式错或缺输入均作为未完成。保留原始测试退出码，AI 成功解释失败也不能把 CI 改为成功。

参考：CLI 2.0 参数、Git hooks。

14 钩子与ACP集成

12.1 先区分产品入口

当前查证的完整 Hook 协议来自 TraeCode IDE 的 Hook 文档，不将其自动视为 CLI 2.0 的同名功能。本节 Hook 实验在 IDE 独立项目副本完成；CLI 用户可先完成第 11 章 Git hook，再跳到 12.4 ACP。

12.2 一份合并配置与三个实际脚本

将 revision-assets 中 hook_guard.py、hook_check.py、hook_stop.py 和 configure_ide_hooks.py 复制到项目 scripts/，在项目根目录执行 python scripts/configure_ide_hooks.py。它记录当前解释器绝对路径，生成一份含三个事件的 .trae/hooks.json；已有文件时拒绝覆盖，先人工合并。

PreToolUse 要求 shell 命令确认并拦截直接数据库文件编辑；PostToolUse 对 Python 文件作语法检查，不承诺自动格式化；Stop 运行 unittest，失败把日志写 stderr 并返回 2。它们是教学检查，不是完整沙箱或数据库访问控制。

12.3 单独验收再联合启用

该 IDE 协议中，0 正常，2 为按事件定义的阻断，其他非零通常只是非阻断错误。不能直接用 pytest 的 1 当作 Stop 阻断。

先用有效／非法 JSON 输入验证脚本：正常测试 Stop 返回 0；失败、超时和缺 cwd 返回 2；PreToolUse 的 RunCommand 返回 ask；PostToolUse 的坏 Python 返回 2。再在 IDE 实际触发对应动作核对事件名及 tool_input.file_path。若目标版本字段不同，先修适配再启用，不能静默放行。

Stop 的 loop_limit 为 3，达到限制会跳过该组，并不等于测试通过；最终仍以外部 CI／测试退出码验收。不要连续覆盖三个 hooks.json，后一次会丢掉前面的事件。

12.4 ACP 由编辑器启动

CLI 2.0 支持 traecli acp。在支持 ACP 的编辑器中配置 command 为 traecli 的绝对路径、args 为 ["acp"]，让编辑器接管 stdio；不要先后台启动一份再期待编辑器附着。先只读核对项目路径和测试入口，再做小改动查看 diff。

参考：IDE Hook 配置、CLI 子命令。

15 进阶模型权限与安全

本篇只保留本课程已使用的入口，配置全文见第 9 章，不再重复旧 YAML、-p/--print 或 IDE Hook 配置。

参数无法识别时保留版本和 help，再对照同代官方文档；不把旧版示例的一半拼进 2.0。权限错误先核对所需操作和实际沙箱，测试失败先读退出码及日志，不能统一通过扩大权限解决。

参考：当前官方参数。

16 TraeCode桌面版使用入门

第十四章（附录）TraeCode Desktop 使用入门

前面十三章都在讲 CLI。这一章我们看看 TraeCode 的 IDE 形态——TraeCode Desktop，了解它和 CLI 如何互补。

14.1 TraeCode IDE 是什么

TraeCode 是一款深度融合 AI 能力的集成开发环境，保留完整的 IDE 基础能力（编辑器、终端、调试、插件、源代码管理），同时内置 AI 编程能力。简单说：它是一个「AI 原生 IDE」。

14.2 IDE 模式 vs SOLO 模式

TraeCode 提供两种模式，按任务灵活切换：

14.3 下载与安装

下载入口：访问 trae.cn/download，根据操作系统下载对应安装包。

安装后打开 TraeCode，首次启动会引导你登录 TRAE 账号（和 CLI 同一套账号体系）。

14.4 核心能力速览

CUE 代码补全：

• 普通补全：基于上下文预测后续代码。
• 补全 Pro：基于你上一次的编辑动作，预测下一个改动点——批量重构时特别省事。
• 多行修改、修改点预测与跳转。
• 在 Python、TypeScript、Golang 项目中辅助智能导入和重命名。

智能体：用自然语言定义任务，AI 理解需求、检索代码库、制定多步骤计划、调用工具完成开发。也能创建自定义智能体。

上下文管理：可以把文件、文件夹、代码片段、终端输出、代码仓库、文档集甚至网页作为上下文，让 AI 基于更完整的信息回答。

智能代码审查：对未提交变更、单次提交或分支差异做总结和审查，配摘要、流程图和 diff 视图。

Git 工作流：内置完整 Git 支持，AI 可生成规范的 Commit Message。

安全能力：

• 隐私模式：开启后，对话内容、代码片段和 AI 输出不用于数据分析、产品优化或模型训练，代码库文件始终在本地。
• 沙箱运行：智能体生成的命令在受限环境执行，降低误操作风险。

14.5 CLI 与 IDE 的协同

CLI 和 IDE 不是二选一，而是互补的：

ACP（Agent Client Protocol）让两者打通：TraeCode CLI 支持 ACP，可作为智能体服务端接入支持 ACP 的编辑器或客户端。这意味着你可以在 IDE 里调用 CLI 的能力，获得一致的 AI 编码体验。

实际协同方式：

• 日常写代码用 IDE 的 CUE 补全，效率最高。
• 需要跑一轮「测试→修 bug→评审」的多步骤任务，切到 CLI 让它自动完成。
• CI 里用 CLI 非交互模式做自动化检查。
• 大重构前用 CLI 的 /review 审查，再到 IDE 里精细调整。

结语

恭喜你读完了整篇教程。回顾一下我们走过的路：

1. 认识产品：四类产品形态及适用场景。
2. 安装上手：macOS、Linux、WSL2、PowerShell。
3. 初体验：TUI、@提及、图片输入、斜杠命令、会话恢复。
4. 实战项目：家庭账本从零搭建。
5. 功能开发：分类统计、月度报表与分支管理。
6. 测试调试：生成测试、修 Bug、回归验证。
7. Git 工作流：自动化提交、审查、解冲突。
8. 自定义命令与 AGENTS.md：沉淀常用流程。
9. 全局配置、自定义智能体与记忆。
10. MCP、插件与技能扩展。
11. 自动化与 CI 集成。
12. Hooks 与 ACP。
13. 进阶：权限模式、工具权限、沙箱与诊断。
14. TraeCode Desktop 速览。

最重要的是贯穿全程的那条主线——好习惯：

• 每个功能一个分支，提交前看 diff。
• 不盲目接受 AI 输出，先理解再采纳。
• 把规范和流程沉淀进 AGENTS.md 和自定义命令。
• 改完跑测试，提交前做 review。

这些习惯不只让 TraeCode 用得顺，更是任何工程项目的通用素养。祝你在 AI 辅助开发的路上越走越顺。

本教程基于 TraeCode CLI 2.0 官方文档编写。产品迭代较快，如遇命令或界面与教程不符，以官方文档为准：docs.trae.cn。

17 进阶学习

这套 TraeCode 教程选择了一条很务实的主线——做一个家庭账本。

先安装和初始化，再让 CLI 调查项目。然后建立账本骨架，写下开发规范，完成功能开发、测试调试和 Git 工作流。后面的章节继续加入斜杠命令与 AGENTS.md、自定义智能体与记忆、MCP、自动化与 CI、Hooks、ACP、权限安全和 Desktop。

第 3 章第一次进入项目时，要求先调查，不急着修改。第 7 章强调小步提交和合并前审查。第 10 章接 MCP 时，只接一个可验证的账本工具，还提醒服务端与客户端不能混淆。第 11 章谈自动化与 CI 时， 明确把确定性检查与 AI 建议分开。

这最后一点尤其重要。

测试是否通过，格式是否合规，构建是否成功，这些可以由确定性程序给出结果。代码结构是否清晰、某段实现是否存在潜在风险，AI 可以提供建议。但建议不能冒充门禁，门禁也不该依赖一段不稳定的自然语言判断。

所以读完这套知识库，真正掌握的是一套分层思路。

从家庭账本到真实项目，还差什么

先调查，再修改。

先用 AGENTS.md 和项目约定告诉 TraeCode 规则，再让它执行。

先把可确定的部分交给测试、Git Hook 和 CI，再让 AI 处理需要解释与判断的部分。

先验证 MCP 工具的输入和结果，再把外部能力接进工作流。

家庭账本规模不大，这些动作已经足够形成闭环。但真实项目会立刻放大每一个问题。

一个账本功能可能只涉及几个文件。企业项目里的需求会跨前端、后端、数据库和部署配置。一个 AGENTS.md 可以写清小项目约定，大型仓库还需要分层规则、架构文档、启动脚本与模块边界。一个 CI 检查可以守住测试，复杂交付还需要权限、审计、安全扫描、发布和回滚。

自定义智能体也会遇到协作问题。

让多个 Agent 分别调研、编码、测试和 Review，听起来很高效。但它们共享什么上下文，修改怎样隔离，冲突如何处理，哪个角色可以执行高风险动作，最后谁对结果负责，都需要提前设计。

否则多智能体不是并行开发，而是并行制造混乱。。

教程里的家庭账本已经给出了很好的最小版本。继续往企业级走，需要把这些方法系统化。

需求不只是一段自然语言，而要成为 spec、plan 和 tasks。项目规则不只告诉 AI 代码风格，还要让开发环境可以启动，让日志和运行状态可读，让完成条件可以机器验证。Hooks 不只做本地提醒，还要

成为稳定的工程门禁。Worktrees 用于隔离并行修改，Skills 用于沉淀团队重复流程。

「企业级 AI 编程实战营」接的就是这一层。

课程具体怎样承接

课程用 SDD 管理需求与任务，用 Harness Engineering 建立 Agent 可工作的仓库环境，再组合 Subagents、Worktrees、Permission、Hooks、Skills 与 Slash Commands 完成复杂交付。

三个企业级项目分别覆盖从零构建、复杂自有系统和大型开源项目改造。

AI 智能体操作系统会处理 Agent Runtime、工作空间隔离、多模型路由与 MCP。分布式延时投递服务会处理高可用、故障切换和消息可靠性。Dify 平台二次开发会训练怎样用 Subagents 理解陌生代码， 用增量规格约束修改，并通过权限与 Hooks 守住回归边界。收官还有 mq9 开源协作，PR 是否合并以维护者实际 review 为准。

扫码添加学习顾问，领取完整大纲和试听资料