# 开始动手之前

这一节是**动手之前的一次性准备**工作，一共做两件事：① 把 AI 编程工具和 Python 环境装好；② 顺便学习写一份对 AI 友好的 spec 。

## 准备工具

做量化交易需要的工具其实很少。入门阶段你只需要一个基础环境，本书会用三样东西搭出来：① 数据源（拿什么做实验）；② 编程环境（在哪跑代码）；③ AI 编程工具（替你写代码）。下面分别介绍。

### 数据源：策略的“原材料”

数据是策略的“原材料”——没有数据，回测无从谈起。本书用两个免费的数据源就够了，对比如表 II-1 所示。

**表 II-1 本书使用的数据源**

| 数据源       | 覆盖范围                 | 费用 |
|--------------|--------------------------|------|
| **akshare**  | A 股为主，数据全、更新快 | 免费 |
| **yfinance** | 全球股票，接口简单       | 免费 |

本书用 akshare（A 股）+ yfinance（美股 / 全球）两个免费源就够了。等你把整个流程跑通、确定要认真做了，再考虑付费数据源。

数据有几个坑要提前知道：**复权方式**（前复权、后复权、不复权，用错了结果完全不同）、**停牌处理**（停牌期间的价格怎么填充）、**幸存者偏差**（只用当前在市的股票回测会高估收益）。这些问题在后续章节遇到时会展开。

### 编程环境：跑策略的“工作台”

有了数据，还需要一个可以运行策略的工作台。你不需要复杂的工程系统，只需要一组基础工具，对照如表 II-2 所示。

**表 II-2 本书使用的编程环境**

| 工具                 | 用途                             |
|----------------------|----------------------------------|
| **Python 3.12**      | 编程语言本体                     |
| **Jupyter Notebook** | 交互式编程环境，可以边写边看结果 |
| **常用库**           | pandas、NumPy、Matplotlib        |

不需要 GPU、不需要云服务器、不需要数据库——一台普通电脑就够了。

> 第 2 章起，本书会用到一个叫 **open-xquant** 的开源框架——它的设计理念和“为什么需要它”会在第 2 章章首详细介绍。本节只列你**现在**要装的工具。

## 安装 TRAE

工具列出来后，开始装。先装 TRAE（本书用于演示 AI 编程的AI 编程工具），再让 TRAE 按一份 spec 帮你装 Python 环境。

### 为什么选 TRAE？

本书以 TRAE 为演示工具。如果你已经在用 Cursor、Claude Code、Codex 或其他 AI 编程工具，完全可以继续使用——操作方式相同：在对话框用自然语言结构化写下想法（即spec），AI 将其翻译成 python 程序，执行即可。

主流的 AI 编程工具不少，对比如表 II-3 所示。

**表 II-3 主流 AI 编程工具对比**

| 工具                | 简介                                  |
|---------------------|---------------------------------------|
| VS Code + Copilot   | 老牌编辑器，加装 AI 插件              |
| Cursor              | AI 原生编辑器，海外用户多             |
| Claude Code / Codex | 命令行工具，专业开发者常用            |
| **TRAE**            | 字节跳动出品，AI-first 设计，中文界面 |

本书选择 TRAE 的原因：

- **AI-first，SOLO 模式**：整个界面围绕“和 AI 对话”设计，不需要你懂编辑器怎么操作
- **模型实力强**：字节有自己的大模型（如豆包），能力不输一线
- **免费可用**：个人开发者免费使用，还能免费接入自定义模型
- **对中国用户友好**：中文界面，国内直连

一句话：TRAE 是目前对零基础、中国用户最友好的 AI 编程工具。

### 四步装好 TRAE

#### 1. 下载 TRAE

访问 TRAE 官网 trae.cn / trae.ai，根据你的操作系统（macOS 或 Windows）下载安装包，下载页面如图 II-1 所示。

![TRAE 官网下载页面](images/getting-started/trae-download-page.png)

#### 2. 安装 TRAE

运行下载的安装包，按照向导提示完成安装。安装过程很简单，一路点“下一步”即可（Windows 安装向导见图 II-2，macOS 见图 II-3）。

![TRAE Windows 安装向导](images/getting-started/trae-install-wizard-windows.png)

![TRAE macOS 安装向导](images/getting-started/trae-install-wizard-mac.png)

#### 3. 打开 TRAE，认识界面

安装完成后打开 TRAE。默认是 IDE 模式（如图 II-4 所示），但本书要用的是 SOLO 模式——它对 AI 编程更友好，整个界面围绕“和 AI 对话”设计。切换到 SOLO 模式后的界面如图 II-5 所示。

![TRAE 默认的 IDE 模式界面](images/getting-started/trae-main-interface-ide.png)

![TRAE SOLO 模式界面](images/getting-started/trae-main-interface.png)

SOLO 模式下你只需要关注一个区域：**AI 助手对话框**。后续所有操作都是在这个对话框里完成的。

#### 4. 创建学习目录

在你的桌面上新建一个文件夹（书中示例文件夹叫 `xquant` ）。然后在 TRAE 中打开它：菜单 → 文件 → 打开文件夹 → 选择 `xquant`，操作过程如图 II-6 所示。

![在 TRAE 中打开 xquant 文件夹](images/getting-started/trae-open-folder.png)

打开后，你会在左侧文件管理器中看到 `xquant` 这个文件夹名称。现在它是空的，很快 AI 会帮你把需要的文件都创建好。

## 一起写第一份 spec：让 AI 装 Python 环境

到这一步 TRAE 装好了，但 Python 还没装。我们的目标是装 Python 3.12 + 7 个依赖包，并且自动验证每个组件都装对了。

最直接的做法是直接告诉 TRAE：“给我装一下 Python 环境。”

不行——AI 不知道你要哪个版本、用什么工具、要哪些包、跑通的标志是什么。它会按自己的偏好装一套，你的同学按他的电脑装另一套，半年后你们的环境完全不同。

正确的做法是写一份 **spec**——前言里讲过的「任务说明书」，把“做什么 + 做成什么样”清清楚楚交给 AI。这份 spec 我们已经写好放在仓库里了——但与其让你直接抄一遍，不如一起从零把骨架走一遍，等你看明白每一段为什么这么写，再去打开真实文件对照。下面我们一段段写。

### spec 长什么样：四段骨架

一份能让 AI 稳定执行的 spec，通常有四段：

> 📌 **spec 的四段骨架**
>
> 1\. **上下文** — 在什么前提下做这件事（AI 不知道你之前做了什么，要明示）
>
> 2\. **任务** — 一句话点明本次要做什么，不用写怎么做。本书中示例
>
> 3\. **要求** — 具体步骤，AI 自由度越小越可复现
>
> 4\. **结果呈现** — 怎么算成功（最容易被忽略也最重要的部分）

四段是 spec 必须回答的四个问题：**前提是什么 / 做什么 / 怎么做 / 算不算做对了**——哪一段都不能少。

我们一段段把“装环境”这个任务写成 spec。

### 第一段：上下文

我们的状况很简单：刚装好 TRAE，打开了一个空目录，但 Python 一切还没装。这一段写出来：

> **上下文**：我（学员）刚在 TRAE 中打开了一个空目录作为课程根目录。本机是 macOS，尚未安装 Python 或任何依赖。这是课程的第一份 spec——后续spec 都依赖这一份装出的环境。

本节后续四段 blockquote 全部以 macOS 为例展示。Windows 用户按相同骨架，把「macOS」替换成「Windows」、把 mac 命令替换成 PowerShell 命令即可——具体替换在 `specs/spec-01-env-setup-windows.md` 文件里逐行对照，本节无需重复。

这一段示范的是 spec 写作的第一条要点，下面我把它单列出来——本节后续每写完一段 spec，都会附一条对应的「📌 要点」。这是全书第一次出现这种样式块，它和正文并列、可以反复回查。

> 📌 **要点 1：能一句话说清的事就不要写两句** AI 一次能处理的信息有限。你写得啰嗦，最关键的指令容易被它忽略。写 spec 的过程是反复“还能不能再短一点”的过程。

### 第二段：任务

任务段要具体到一句话能说清。“装好 Python 环境”不够具体——什么版本？用什么工具？哪些包？

> **任务**：在当前目录下完成 macOS 量化课程编程环境配置——装 uv → 用 uv 创建 Python 3.12 虚拟环境 → 装 7 个依赖包 → 创建并跑通 check_env.py 自检脚本。
>
> 📌 **要点 2：关键事物要具体到 ID 或版本号** “Python” 不够，要 “Python 3.12”；“包管理工具”不够，要 “uv”；“装一些库”不够，要 “7 个具体的库”。任何 spec 中的关键名词都要具体到不能再具体的程度，AI 才不会按自己的偏好随便选一个。

### 第三段：要求

要求段是 spec 的主体——把“怎么做”拆成步骤。环境配置一共 6 步：确认目录、装 uv、建虚拟环境、装依赖、写 check_env.py、跑 check。以下要求比较具体，是因为编程需要让环境前后一致，避免引起不必要的问题，实际工作中我们不必告诉 AI 应该怎么做，所以你可以完全复制这一段：

> **要求**： 1. **确认当前目录**——在终端运行 `pwd`，记录路径，后续操作都在这个目录下。 2. **安装 uv**——运行 `curl -LsSf https://astral.sh/uv/install.sh | sh`，再 `source $HOME/.local/bin/env`，最后 `uv --version` 应输出版本号。 3. ……（共 6 步，完整内容见 `specs/spec-01-env-setup-mac.md`）

完整 6 步加上每一步的命令、check_env.py 全文都在 spec 文件里。这里只挑两个特别值得讲的细节。

**装依赖时为什么要锁版本号？** 比较两种写法：

❌ `uv pip install pandas numpy matplotlib` ✅ `uv pip install pandas==3.0.* numpy==2.4.* matplotlib==3.10.*`

不锁版本的话，半年后你重新跑 spec，pandas 升到了 3.1，某个 API 改了，书上的图就跑不出来。锁到 `==X.Y.*` 既允许 patch 升级（修 bug 的小版本）又不会跨 minor（可能改 API 的版本），最稳。

> 📌 **要点 3：能锁的都锁住——版本号、日期、随机种子** 量化交易的命脉是“可复现”。你今天跑出来的图，明天还得跑得出来；你电脑上跑的回测，老师电脑上的结果一样；半年后回头检查，依然能复现。任何会随时间漂移的东西（库版本、日期窗口、随机数）都要锁。

环境配置这件事**没有图表可看**——某个包没装好，当下不会报错，等到第 1 章跑实验时才暴露问题。所以验证必须是机械的、固定的、可重复的。所以我们把检查脚本写进了 spec，这就是告诉 AI 使用指定的工具完成某些任务，从而提高 AI 任务的确定性。AI 只能照着抄一份一字不差的，每个学员跑出的报告完全一致——失败时哪一项 FAIL 就是哪一项装错了。

### 第四段：结果呈现

最后一段是“成功长什么样”。一份 spec 没有这一段，AI 跑完你只能凭感觉判断对错。

> **结果呈现**： 1. `python check_env.py` 最末两行输出 `结果: 11/11 全部通过！` + `环境配置完成，可以开始课程。` 2. 命令退出码为 0 3. 当前目录下存在 `.venv/` 与 `check_env.py`
>
> 📌 **要点 4：成功的标志要可机械验证** “跑通了” / “看起来对” / “应该没问题”——这些都是不合格的成功标志。一份好 spec 的结果呈现段要让 AI 自己能说“对了”或“错了”，不需要学员凭感觉判断。assert 语句、具体的数字（11/11）、具体的文件名、退出码——这些就是机械验证。

四段拼起来就是一份完整 spec。我们刚才在书里写过的骨架——上下文 / 任务 / 要求 / 结果呈现——和 `specs/spec-01-env-setup-mac.md`（或 `spec-01-env-setup-windows.md`，根据你的系统）里的真实文件一一对应；区别只在于真实文件把 6 步和 check_env.py 全文都写齐了。下一节我们把它交给 TRAE。

## 让 TRAE 跑这份 spec

上一节我们把这份 spec 在书里一段段写完了，现在把它交给 TRAE 真正执行。在打开 spec 文件之前，先看下面这条提示——等下 TRAE 弹窗时你就不会被吓到：

> **💡 提示：关于“沙箱”**
>
> TRAE 帮你装环境时会弹窗询问是否允许“在沙箱外运行”。别紧张：AI 平时是在一个受限的小房间（沙箱）里活动，但现在它要帮你布置整个工作台，需要你给它开一下门。遇到这个提示，直接点“是”或“允许”即可，过程示意如图 II-7 所示。
>
> 如果你打开 spec 文件第一行也写了“所有命令在沙箱外运行”——这就是 TRAE 弹窗问你的原因；不是出错，是预期里的一步。

![TRAE 沙箱提示示意](images/getting-started/trae-solo-sandbox.png)

读完提示，再打开你系统对应的 spec 文件——

- **macOS 用户**：打开 `specs/spec-01-env-setup-mac.md`
- **Windows 用户**：打开 `specs/spec-01-env-setup-windows.md`

把 spec 全部内容复制到 TRAE 的 AI 对话框中，发送。

AI 会自动完成 6 个步骤：装 uv、建虚拟环境、装 7 个依赖包（含 open-xquant 框架）、创建 check_env.py、跑自检。整个过程几分钟。你不需要理解每一步细节，只需要看最后的检查结果。

### 验证结果

如果一切顺利，你会在 TRAE 的终端中看到类似这样的输出：

    ==================================================
      XQuant 课程环境检查
    ==================================================

      [OK  ] Python 3.12.x
      [OK  ] 虚拟环境已激活
      [OK  ] jupyter
      [OK  ] pandas
      [OK  ] numpy
      [OK  ] matplotlib
      [OK  ] akshare
      [OK  ] yfinance
      [OK  ] open-xquant
      [OK  ] jupyter 命令可用
      [OK  ] akshare 数据源连通（获取到 5847 条数据）

    --------------------------------------------------
      结果: 11/11 全部通过！
      环境配置完成，可以开始课程。

实际终端输出如图 II-8 所示。

![环境检查全部通过](images/getting-started/env-check-success.png)

如果有任何项目显示 `[FAIL]`，**不要紧张，也不要自己改命令重试**——把完整的输出结果复制给 TRAE 的 AI 助手，告诉它“环境检查有失败项，请帮我修复”。AI 会照着 spec 里“故障恢复”那一节的对照表逐项排查。

> **💡 关于错误处理的原则**
>
> 整本书你都不必去**啃** Python 报错——遇到任何报错，**把完整信息复制给 AI 助手**就好。AI 排查报错的能力远比让初学者读 stack trace 强。这是本书的承诺：你只写 spec、看结果，调试交给 AI。

## 你刚刚学到了什么

### 你做了什么

刚才的过程其实包含两件事：

① **环境装好了**——这件一次性的事做完了，往后不用再碰。 ② **你看到了一份 spec 是怎么从零写出来的**——四段骨架在你眼前展开了一遍，四条核心要点各自示范了一次。

第二件事比第一件重要。

### 7 条 spec 自查清单

刚才本节示范了 4 条要点（写在每段 spec 之后的「📌 要点 1-4」）。把这 4 条加上 3 条通用补充，就构成下面这份“写完 spec 过一遍”的自查清单——任何一条没做到都是问题：

| \# | 自查项 |
|----|----|
| 1 | **四段都齐了？** 上下文 / 任务 / 要求 / 结果呈现，一段都不能少 —— 结构骨架 |
| 2 | **任务一句话能说清吗？** “做一下数据分析” ❌；“获取沪深 300ETF 历史数据并可视化” ✅ —— 来自要点 1 |
| 3 | **关键事物具体到 ID 了吗？** 标的代码、库版本、文件名、参数名都点名 —— 来自要点 2 |
| 4 | **能锁的都锁了吗？** 库版本、日期窗口、随机种子——任何会随时间漂移的都要锁 —— 来自要点 3 |
| 5 | **结果呈现有“机器能判断的标志”吗？** assert、具体数字、文件名、退出码 —— 来自要点 4 |
| 6 | **写的是“做 X”而不是“不要 Y”吗？** 正向指令比否定句对 AI 更稳定 —— 通用补充（首次出现） |
| 7 | **长度合理吗？** 大多数 spec 不超过 80 行（环境配置这种特殊情况除外） —— 通用补充（首次出现） |

第 6、7 两条本节没有专门演示，会在第 1 章后续 spec 写作中遇到时再补讲。这 7 条会跟着你整本书——每写一份新 spec，最后都过一遍这个清单。

### 你需要做什么

后续每一章都会让你写或改一份 spec。开始时书里会带你一段一段写（像本节这样），后面会渐渐放手——到第 6、7 章你应该能自己写完整的 spec，到第 9 章你应该能根据问题写新 spec。

> **💡 spec 写作能力的成长曲线**
>
> 抄 → 改 → 拼 → 写。第 1 章基本是“抄 + 看懂”；第 2-3 章是“改其中几个参数”；第 4-6 章是“把多个 spec 拼成新流程”；第 7-9 章是“看到一个量化问题，自己写一份新 spec”。每一步都不用着急。

## 准备就绪

恭喜，你现在已经具备了开始量化交易学习的全部条件。

### 速查表

前言和这一节涉及的核心概念汇总在表 II-4 里。

**表 II-4 动手前的核心概念速查**

| 概念 | 含义 | 类比 |
|----|----|----|
| spec（任务说明书） | 给 AI 的结构化指令 | 你说清楚要做什么，AI 负责执行 |
| spec 四段骨架 | 上下文 / 任务 / 要求 / 结果呈现 | 一份 spec 必须回答的四个问题 |
| TRAE | 本书演示用的 AI 编程工具 | 也可以换成 Cursor / Claude Code 等 |
| 量化交易 | 用数据和规则做交易决策 | 把“我觉得”变成“数据显示” |
| 量化飞轮 | 候选 / 组合 / 执行 / 归因，循环往复 | 越转越聪明的轮子 |
| 三字要点 | 飞轮每一格都要走的三步：做 / 看 / 疑 | 想法要规则、结果要指标、指标要被怀疑 |

### 下一步

**第 1 章**，我们会用一个真实的 ETF 带你**走完整个飞轮一圈**——从最简单的定投开始（做），看它能不能赚钱（看），尝试让它“聪明”一些（再做、再看），最后亲眼看到“回测时间段里收益率优美、换段时间就亏损”这种典型情况（疑）。 准备好了吗？翻到下一章，开始你的第一次飞轮转动。

---

## 反馈与读者群

如果你发现本章有错别字、概念不清或实验结果不一致，欢迎
[提交 GitHub Issue](https://github.com/xingwudao/xquant-beginner/issues/new/choose)。

课程、正式书和后续更新见
[xquant.shop/courses](https://xquant.shop/courses)。

添加作者微信 `xquanter` 进入读者群。请备注：`XQuant 读者`。