Trae开发体验笔记

Trae AI 编程实战指南

本文档旨在系统梳理 Trae 的核心开发模式与最佳实践，帮助开发者从“对话式编程”进阶为“架构化智能开发”。

1. 核心开发模式 (Core Modes)

1.1 基础交互模式

  • IDE 模式 (Copilot-like)：

    • 定位：模块开发视角。

    • 场景：快速补全、单文件修改、局部逻辑优化。

    • 特点：轻量级交互，上下文局限于当前打开的文件或选中的代码块。

  • SOLO 模式 (Autonomous Agent)：

    • 定位：项目开发视角。

    • 场景：处理需求文档、多文件代码编写、浏览器搜索、终端调试等复杂任务。

    • 特点：具备自主权，可连续执行“搜索->规划->编辑->运行->修复”循环。

1.2 MCP 模式 (Model Context Protocol)

  • 定义：一个 AI 大模型的标准化工具箱，旨在打通 AI 模型与外部工具、数据源的桥梁。

    • 专业解释：由 Anthropic 于 2024 年发布，整合了 Function Call 标准，实现 AI 与外部世界的互联互通。

    • 通俗解释：让 AI 不仅能回答问题，还能直接调用 API、操作本地文件、访问数据库。

  • 机制：Trae (Client) <-> MCP Server (工具/数据源)。支持 stdio 和 SSE 两种传输类型。

  • 内置能力：阅读文件、编辑文件、终端操作、预览网页、联网搜索。

1.3 SKILL 模式 (Skill-Driven)

  • 定义：将特定的对话经验沉淀为可复用的技能文档 (skill.md)，让 AI 扮演特定角色或执行特定规范。

  • 调用方式：@skill/design.md。

  • 应用场景：通过项目沉淀，将对话提炼为“架构师”、“产品设计”、“前端开发”等角色的专属技能包。

    • 示例：“@skill/design.md 你现在是这份文档中定义的高级架构师。请根据这些规范，审查当前的 app/server.py。”

1.4 Plan 模式 (Planning)

  • 定义：在 SOLO 模式下触发的 Think -> Plan -> Act -> Reflect 循环。

  • 触发：SOLO Coder/Builder 均支持。面对复杂任务时，AI 会先列出步骤（Plan），经用户确认（Review）后，再分步执行（Execute）。

1.5 规则模式 (Rules)

  • 定义：在 设置 -> 规则 -> 个人规则/项目规则 中定义的全局指令。

  • 作用：预设代码风格、禁止事项或特定偏好，对所有对话生效。

2. 智能体体系 (Agents)

2.0 概念辨析：LLM vs AI Agent

很多开发者容易混淆“大模型”与“智能体”。简单来说，大模型是“大脑”，而智能体是“大脑 + 手脚 + 记忆”。

维度LLM (大模型)AI Agent (智能体)
本质概率预测引擎 (Next Token Prediction)自主决策系统 (Autonomous System)
交互方式被动 (输入 -> 输出)主动 (感知 -> 规划 -> 行动 -> 反思)
能力边界仅限于文本/图片生成可调用工具 (联网/读写文件/终端)
记忆无状态 (Stateless)有记忆 (Memory/State)
典型代表ChatGPT 网页版, Claude 网页版Trae SOLO, AutoGPT, Devin

2.1 内置智能体

  • SOLO Coder：代码专家。擅长单文件实现、正则/SQL生成、代码解释。

  • SOLO Builder：全栈工程师。擅长多文件构建、环境配置、Debug、复杂任务规划。

2.2 自定义智能体 (Custom Agents)

基于“专业分工”原则，我们定义了四个核心角色，各司其职，互不越界。

1. 文档设计1号 (Document Designer)

  • 角色定义：产品经理 + 业务分析师。

  • 核心职责：负责“做什么”和“为什么做”。

  • 输入：用户的原始模糊需求、业务背景。

  • 输出：结构清晰的 PRD 文档、用户故事 (User Stories)、验收标准 (Acceptance Criteria)。

  • 能力边界：严禁编写代码，只负责业务逻辑梳理和需求澄清。

  • 常用指令：“你现在是文档设计1号。请根据我的描述，梳理一份 PRD，重点明确业务流程和异常处理机制。”

2. 架构师1号 (System Architect)

  • 角色定义：技术总监 + 系统架构师。

  • 核心职责：负责“怎么做”。

  • 输入：PRD 文档。

  • 输出：技术方案 (Spec)、接口定义 (API Schema)、数据库设计 (DB Model)、目录结构规划。

  • 能力边界：不写具体业务代码，只写骨架代码 (Skeleton)、Interface 定义和配置文件。

  • 常用指令：“你现在是架构师1号。引用 #design/prd.md，请设计技术方案，定义核心数据结构和模块接口。”

3. 开发1号 (Senior Developer)

  • 角色定义：高级开发工程师。

  • 核心职责：负责“实现它”。

  • 输入：技术方案 (Spec) + 测试用例 (Test Cases)。

  • 输出：可运行的业务代码、单元测试实现。

  • 能力边界：严格按照 Spec 实现，不随意变更架构。如果发现 Spec 有问题，需反馈给架构师。

  • 常用指令：“你现在是开发1号。引用 #design/spec.md 和 #tests/test_skeleton.py，请实现核心逻辑，直到测试通过。”

4. 测试1号 (QA Engineer)

  • 角色定义：测试工程师 + 质量保证。

  • 核心职责：负责“验证它”。

  • 输入：PRD + Spec。

  • 输出：测试计划、测试用例 (Test Cases)、自动化测试脚本、Bug 报告。

  • 能力边界：不修改业务代码，只编写测试代码和发现 Bug。

  • 常用指令：“你现在是测试1号。引用 #design/spec.md，请编写针对 parser.py 的单元测试，覆盖所有边界条件。”

2.3 自定义智能体流水线 (The Quartet)

针对 文档设计1号、架构师1号、开发1号、测试1号 的自动化协作方案：

  • 核心理念：文档锚点工作流。上一个角色的输出文件 = 下一个角色的输入上下文。

  • SOP (标准作业程序)：

    1. 需求固化 (文档设计1号) -> 输出 design/01_prd.md

    2. 蓝图绘制 (架构师1号) -> 引用 PRD -> 输出 design/02_spec.md (定义接口/Schema)

    3. 护栏先行 (测试1号) -> 引用 Spec -> 输出 tests/test_skeleton.py (红灯测试)

    4. 填空开发 (开发1号) -> 引用 Spec + Test -> 实现代码直到测试变绿

3. 从零开始的全流程最佳实践指南 (Step-by-Step Guide)

本指南将指导您如何从一个模糊的想法开始，利用 Trae 的工具链，一步步构建出高质量的软件项目。

Phase 0: 环境准备 (Configuration)

在开始任何对话之前，先立好规矩。

  1. 全局规则设定：

    • 进入 Settings -> Rules -> User Rules。

    • 写入：“你是一个资深全栈工程师。所有代码必须遵循 DRY 原则，优先使用 TypeScript/Python 类型注解。拒绝过度封装。任何修改前必须先解释原因。”

  2. 项目规则设定 (.trae/rules)：

    • 针对当前项目创建 .trae/rules 文件。

    • 写入：“本项目使用 FastAPI + Vue3。前端组件库强制使用 Ant Design Vue。所有 API 接口必须符合 RESTful 规范。”

Phase 1: 需求孵化 (Inception)

不要急着写代码，先让 AI 帮你理清思路。

  • 模式：SOLO Builder

  • 动作：输入原始需求，生成 PRD。

  • Prompt 示例：

    “我想要做一个量化交易的回测看板。核心功能是展示净值曲线、计算最大回撤，并支持上传 CSV 格式的交割单。请帮我梳理一份 design/prd.md，包含背景、核心功能列表、用户交互流程和验收标准。”

  • 产出：design/prd.md (项目宪章)。

Phase 2: 架构蓝图 (Blueprint)

有了 PRD，接下来要定技术栈和数据结构。

  • 模式：SOLO Builder

  • 动作：引用 PRD，生成技术方案 (Spec)。

  • Prompt 示例：

    “引用 #design/prd.md。请设计技术方案 design/spec.md。

    1. 技术栈：推荐适合的数据分析栈（如 Python Pandas + ECharts）。

    2. 数据模型：定义核心的 Trade 和 Portfolio 数据结构（TypeScript Interface 或 Python Pydantic Model）。

    3. 目录结构：规划清晰的文件目录。”

  • 产出：design/spec.md (施工图纸)。

Phase 3: 核心骨架搭建 (Skeleton)

先跑通“Hello World”，确保基础设施可用。

  • 模式：SOLO Builder (Plan Mode)

  • 动作：初始化项目，配置 Linter。

  • Prompt 示例：

    “基于 #design/spec.md，请初始化项目骨架。

    1. 创建目录结构。

    2. 配置 pyproject.toml 或 package.json，安装依赖。

    3. 配置 ESLint/Ruff，确保代码风格统一。

    4. 创建一个最简单的 main.py 或 App.vue，确保能运行起来。”

  • 验收：终端运行无报错。

Phase 4: 迭代开发 (Iteration)

按模块切分任务，使用 TDD（测试驱动）护航。

  • 模式：SOLO Builder + SOLO Coder

  • 循环步骤：

    1. 定义接口：先写 Type/Interface。

    2. 编写测试：“引用 Spec，为数据解析模块编写 tests/test_parser.py，覆盖 CSV 格式错误的异常情况。”

    3. 实现功能：“引用测试文件，实现 parser.py，直到测试通过。”

    4. 代码审查：“@SOLO Coder 审查 parser.py，优化变量命名，补充注释。”

Phase 5: 验收与交付 (Delivery)

  • 模式：SOLO Builder

  • 动作：补充文档，清理遗留问题。

  • Prompt 示例：

    “请扫描全项目，生成一份 README.md，包含项目简介、安装步骤和快速启动命令。同时检查是否有未完成的 TODO 注释。”

3.6 验证与测试

  • 原则：严谨的项目需要测试覆盖。

  • 实践：

    • 单元测试：生成工具函数时，要求同时生成 Vitest/Jest 用例。

    • 组件测试：关键 UI 组件配套 Storybook 或测试用例。

3.7 智能体协作策略 (Collaboration Strategy)

是否有必要引入“四人组” (The Quartet)？答案取决于任务复杂度和项目阶段。

1. 必要性分析 (Pros & Cons)

  • 优势 (Pros)：

    • 上下文隔离：每个智能体只关注自己的任务，避免了上下文过长导致的 AI “幻觉”和逻辑混乱。

    • 质量护航：通过“架构先行”和“测试驱动”，从源头杜绝了低级错误。

    • 可维护性：留下了完整的文档链 (PRD -> Spec -> Test -> Code)，方便后续维护和新人接手。

  • 劣势 (Cons)：

    • 交互成本：需要切换角色、生成中间文档，比直接写代码慢。

    • Token 消耗：产生大量文档和多轮对话。

2. 适用场景建议 (Recommendations)

建议采用 “分级响应机制”：

  • 🟢 Level 1: 简单任务 (Hotfix / Small Tweak)

    • 场景：修改文案、调整样式、修复简单 Bug。

    • 策略：直接使用 IDE 模式 或 SOLO Coder。

    • 不需要：文档设计1号、架构师1号。

  • 🟡 Level 2: 独立功能模块 (Feature)

    • 场景：新增一个图表、增加一个 API 接口。

    • 策略：架构师1号 + 开发1号。

    • 流程：简要 Spec -> 代码实现 -> 人工验证。

  • 🔴 Level 3: 复杂系统/核心重构 (Epic / Refactor)

    • 场景：从零构建项目、重构核心交易引擎、涉及资金计算的模块。

    • 策略：完整四人组 (The Quartet)。

    • 流程：PRD (文档1号) -> Spec (架构1号) -> Test (测试1号) -> Code (开发1号)。

3. 结论

对于 kc_portfolio_manager 这样涉及金融数据和策略回测的项目，核心逻辑层（数据处理、净值计算、回测引擎）强烈建议使用 Level 3 完整模式，以确保数据的准确性和系统的稳健性。而对于前端 UI 展示层，可以根据复杂度灵活选择 Level 1 或 Level 2。

4. 开发模式对比矩阵 (Comparison Matrix)

为了帮助您在不同场景下选择最合适的开发模式，我们将几种常见的交互方式进行了深度对比。

特性维度Chat 对话 (基础)IDE 对话 (Copilot)设计驱动 (DDD)测试驱动 (TDD)多 Agent 团队 (The Quartet)
核心驱动力随意问答上下文感知文档 (PRD/Spec)测试用例 (Test Cases)角色分工 (Roles)
自动化程度⚪ 低 (手动复制粘贴)🔵 中 (辅助补全)🟡 高 (生成骨架)🟠 极高 (循环修复)🔴 全自动 (流水线)
人工干预高频 (每句都要管)中频 (单点确认)低频 (文档审核)低频 (测试红绿灯)极低 (关键节点验收)
上下文质量❌ 易断裂/幻觉✅ 局部精准✅✅ 全局结构化✅✅✅ 逻辑严密✅✅✅✅ 隔离且清晰
适用场景知识问答, 概念解释单函数实现, Bug修复新项目启动, 模块设计核心算法, 复杂逻辑复杂系统重构, 金融级交付
缺陷无法落地, 容易跑偏缺乏宏观视野文档维护成本高初期编写成本高Token 消耗大, 速度慢

5. 实战案例诊断：Portfolio Manager 的困境与破局

本节将“无法收敛”的问题拆解为三个层次：项目设计代码层、用户与 AI 交互内容层、AI 自动化处理层。三个层次缺一不可：只优化其中一层，往往仍会回到拉锯战。

5.1 项目设计代码层（Design & Code Layer）

  • 项目背景：本项目以 Python（Solara）+ Pandas 为主，目标输出交互式 HTML 交易复盘报告。

  • 结构现状：app/templates/ 下按报告类型拆出多个模板目录（如 trade_replay/、deep_report/、combined_report/），每个模板包含 parser.py、report.py、generator.py 三类文件，体现了“解析-报告-生成”的分层意图。

  • 关键断点：在 app/templates/trade_replay/generator.py 的 ReportGenerator 中，出现了典型的“上帝类”倾向：同一处同时承担数据解析、指标计算与图表渲染（Pyecharts 配置）等职责，导致任一侧改动都可能牵连另一侧。

  • 直接后果：

    • UI 改动（样式、配色、布局）会触碰或隐式影响计算路径与数据组织形式；

    • 计算改动（口径、字段、精度）会破坏图表期望的输入结构，引发渲染异常或静默错误；

    • 缺少稳定的“数据契约”，模板间口径一致性难以保证，回归验证成本飙升。

  • 工程化建议（仅设计层面）：

    • 以“数据契约”作为系统中心，先定义报告输出所需的字段集合、口径说明、精度与缺失值策略；

    • 明确三层边界：解析层只负责读入与清洗，计算层只负责指标，渲染层只负责展示；渲染层禁止新增计算口径。

5.2 用户与 AI 交互内容层（Interaction & Prompt Layer）

  • 交互现状：通过 SOLO 模式多角色对话推进，但在真实执行中容易在同一上下文内混用角色任务（架构、开发、测试、UI），导致“分工在口头，交付在一处”。

  • 典型失效模式：

    • 需求漂移：对“达到目标”的判定缺少可验收的定义（视觉效果、指标口径、性能边界），对话不断追加细节，目标被动变化。

    • 补丁式迭代：以“修一个错误/调一个样式”为主导，持续在同一文件上局部缝补，形成复杂耦合与历史负担。

    • 上下文污染：长对话跨越解析、计算、渲染、测试四类问题，AI 难以同时保证金融正确性与 UI 一致性，容易发生“修 A 坏 B”的回滚。

    • 锚点缺失：关键产出未固化为可复用的中间件（PRD/Spec/Schema/验收清单/黄金样例），导致每轮对话都要重新解释背景。

  • 交互改造要点：

    • 以“文档锚点”驱动：每次对话都引用同一份验收标准与数据契约，禁止口头变更；

    • 以“变更申请”约束：任何新增图表、字段或口径，都先更新设计锚点，再进入实现与验证；

    • 以“短上下文包”治理：每个 Session 只允许讨论一个层面（解析/计算/渲染/测试之一），避免跨层穿透。

5.3 AI 自动化处理层（Automation Layer）：净室流水线（Cleanroom Pipeline）

本层关注“如何让 AI 的自动化变得可控、可回归、可收敛”，核心是把 AI 的工作改造为流水线作业，而不是在一个上下文里同时做多工种。

5.3.1 目标：让 AI 只在明确边界内自动化

  • 自动化目标：把“对话式补丁”变成“可回归的批处理任务”，每一步都能产出可验收的工件（Artifact）。

  • 关键工件（建议作为固定锚点）：

    • 数据契约（Schema）：明确报告输出字段、口径、精度、缺失值策略、单位与展示规则。

    • 黄金样例（Golden Sample）：选取 1 份代表性数据作为回归基准，并明确预期结果的校验口径。

    • 验收清单（Acceptance Checklist）：将“收敛”写成可打勾的条目，而不是“看起来差不多”。

5.3.2 三段式净室流水线

  • Stage A：解析净室（Parser Cleanroom）

    • 输入：CSV/JSON 源数据。

    • 输出：清洗后的标准化数据（字段对齐、类型对齐、缺失值策略一致）。

    • 约束：不做任何指标计算，不做任何展示逻辑。

  • Stage B：计算净室（Calculator Cleanroom）

    • 输入：标准化数据。

    • 输出：符合数据契约的“指标数据包”（例如净值序列、回撤序列、持仓分布及其口径说明）。

    • 约束：不关心图表长什么样，只对“口径正确、可回归”负责。

  • Stage C：渲染净室（Renderer Cleanroom）

    • 输入：指标数据包（可使用 Mock/黄金样例）。

    • 输出：HTML 报告（布局、配色、交互、性能）。

    • 约束：严禁引入新口径计算；任何缺字段问题回退到 Stage B。

5.3.3 立即执行清单（Action Items）

  1. 冻结现状：暂停在同一会话/同一文件上继续缝补，明确“收敛前不扩需求”。

  2. 固化数据契约：把报告所需字段与口径写成一页清单，作为后续所有对话的唯一锚点。

  3. 净室拆分会话：为 Stage A/B/C 建立独立的对话上下文，分别交付解析、计算、渲染的工件。

  4. 以黄金样例回归：每轮变更只允许影响一个层面，并用同一份样例验证“没破坏旧结果”。

  5. 以验收清单收口：当清单条目全部满足即停止迭代，避免“越做越像新需求”。

总结：Trae 开发心法

  1. 慢即是快：花 30% 的时间写文档 (Phase 1-2)，能节省 50% 的 Debug 时间。

  2. 文档锚点：永远通过 # 引用文档来驱动开发，而不是靠口述。

  3. 测试为王：没有测试的代码不仅是不可靠的，而且是不可维护的。