gavindiaz/xquant-beginner
1
0
Fork 0
mirror of https://github.com/xingwudao/xquant-beginner.git synced 2026-08-15 04:48:11 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: sync xquant tutorial updates

Browse Source
This commit is contained in:
xingwudao
2026-06-21 23:17:19 +08:00
parent a0d05d966f
commit c1a6decc56
25 changed files with 1955 additions and 2214 deletions
Download Patch File Download Diff File Expand all files Collapse all files
book/getting-started.md
+219 -181
View File
@@ -1,300 +1,338 @@
# 开始动手之前
# 准备工作
这一节是**动手之前的一次性准备**工作，一共做两件事：① 把 AI 编程工具和 Python 环境装好；② 顺便学习写一份对 AI 友好的 spec 。
前言讲完了学习地图，这一章先把工作台搭起来。你要做两件事：第一，把 AI 编程工具和 Python 环境准备好；第二，用“装环境”这件事，完整练一次写 spec。
## 准备工具
这一章先不要求你学会编程，也不要求你记住每一条命令。你只需要了解：把任务说明白是你的工作；让 AI 按说明执行；拿到结果后再检查对不对。本章会提供检查工具，帮你判断环境是否真的准备好了。准备工作做好了，从第 1 章开始，我们就可以直接跑量化实验。
做量化交易需要的工具其实很少。入门阶段你只需要一个基础环境，本书会用三样东西搭出来：① 数据源（拿什么做实验）；② 编程环境（在哪跑代码）；③ AI 编程工具（替你写代码）。下面分别介绍。
## 先认识要用的工具
### 数据源：策略的“原材料”
做量化实验需要的工具并不多。入门阶段先认识三类就够了：数据源、编程环境、AI 编程工具。先把这三类说清楚，后面安装时你就知道每一步在准备什么。
数据是策略的“原材料”——没有数据，回测无从谈起。本书用两个免费的数据源就够了，对比如表 II-1 所示。
### 数据源：策略的原材料
数据是量化策略实验的原材料。没有历史价格、成交量这些基础数据，就没有根据提出策略，也无法检验策略是否有效。本书主要用两个免费数据源，如表 II-1 所示。
**表 II-1 本书使用的数据源**
| 数据源 | 覆盖范围 | 费用 |
|--------------|--------------------------|------|
| **akshare** | A 股为主，数据全、更新快 | 免费 |
| **yfinance** | 全球股票，接口简单 | 免费 |
| 数据源 | 覆盖范围 | 费用 |
|--------|----------|------|
| **akshare** | A 股为主，数据全、更新快 | 免费 |
| **yfinance** | 全球股票，接口简单 | 免费 |
本书用 akshare（A 股）+ yfinance（美股 / 全球）两个免费源就够了。等你把整个流程跑通、确定要认真做了，再考虑付费数据源。
你不需要提前下载一大包数据文件。后面运行代码时，程序会自己从网上获取数据。数据很重要：没有数据做不了实验；数据错了、缺失了、处理得不对，都会影响结论，进而影响最终判断。
数据有几个坑要提前知道：**复权方式**（前复权、后复权、不复权，用错了结果完全不同）、**停牌处理**（停牌期间的价格怎么填充）、**幸存者偏差**（只用当前在市的股票回测会高估收益）。这些问题在后续章节遇到时会展开。
数据中的问题有非常多细节，略举几例，暂时听不懂没关系，比如复权、停牌、幸存者偏差，后面遇到真实实验时再讲。
### 编程环境：跑策略的“工作台”
### 编程环境：跑代码的工作台
有了数据，还需要一个可以运行策略的工作台。你不需要复杂的工程系统，只需要一组基础工具，对照如表 II-2 所示。
有了数据，还需要一个能运行程序的环境。程序写好了，要让它自动执行，需要安装一些“看不见”的软件，这在编程里叫“环境”。你可以把环境理解成厨房：数据是食材，环境是锅、灶、刀具和调料。没有这些东西，有食材也做不出饭。
我们需要的环境，是运行 Python 程序的一组工具，比如 Python 解释器、Jupyter Notebook 等。你不用先记住这些名字，后面我们会让 AI 帮你把它们装好。你不需要 GPU、云服务器或数据库，一台普通电脑就够了，操作系统是 Windows、macOS 或 Linux 都可以。
本书用到的基础环境如表 II-2 所示。
**表 II-2 本书使用的编程环境**
| 工具 | 用途 |
|----------------------|----------------------------------|
| **Python 3.12** | 编程语言本体 |
| **Jupyter Notebook** | 交互式编程环境，可以边写边看结果 |
| **常用库** | pandas、NumPy、Matplotlib |
| 工具 | 用途 |
|------|------|
| **Python 3.12** | 运行代码的语言 |
| **Jupyter Notebook** | 边写边看结果的交互式环境 |
| **常用库** | pandas、NumPy、Matplotlib 等现成工具 |
不需要 GPU、不需要云服务器、不需要数据库——一台普通电脑就够了。
表里的“库”，可以理解为别人已经写好的工具包。比如 pandas 负责处理表格数据，Matplotlib 负责画图。你不需要详细学习这些工具，只要把它们装好，AI 懂得用就行。
> 第 2 章起，本书会用到一个叫 **open-xquant** 的开源框架——它的设计理念和“为什么需要它”会在第 2 章章首详细介绍。本节只列你**现在**要装的工具。
第 2 章起，本书还会用到一个叫 **open-xquant** 的开源量化框架，它是我们自己专门为 AI 写的一个框架，等到第 2 章正式介绍它。这一章只负责把它先装进环境里。
## 安装 TRAE
### AI 编程工具：把 spec 变成代码
工具列出来后，开始装。先装 TRAE（本书用于演示 AI 编程的AI 编程工具），再让 TRAE 按一份 spec 帮你装 Python 环境。
前言里说过，你不需要先学会编程再学量化，但你必须学会把策略描述清楚，把它写成策略规格说明书，简称 spec。AI 编程工具的作用，就是把你写清楚的 spec 翻译成 Python 代码，再帮你运行和修改。
### 为什么选 TRAE？
本书以 TRAE 为演示工具。如果你已经在用 Cursor、Claude Code、Codex 或其他 AI 编程工具，完全可以继续使用——操作方式相同：在对话框用自然语言结构化写下想法（即spec），AI 将其翻译成 python 程序，执行即可。
主流的 AI 编程工具不少，对比如表 II-3 所示。
主流 AI 编程工具不少，如表 II-3 所示。
**表 II-3 主流 AI 编程工具对比**
| 工具 | 简介 |
|---------------------|---------------------------------------|
| VS Code + Copilot | 老牌编辑器，加装 AI 插件 |
| Cursor | AI 原生编辑器，海外用户多 |
| Claude Code / Codex | 命令行工具，专业开发者常用 |
| **TRAE** | 字节跳动出品，AI-first 设计，中文界面 |
| 工具 | 简介 |
|------|------|
| VS Code + Copilot | 老牌编辑器，加装 AI 插件 |
| Cursor | 使用广泛的 AI 编程工具 |
| Claude Code | Anthropic 出品的 AI 编程工具 |
| Codex | OpenAI 出品，专业开发者常用 |
| OpenCode/OpenClaw | 开源的 AI 编程工具 |
| TRAE | 字节跳动出品，AI-first 设计，中文界面 |
本书选择 TRAE 的原因：
这里要区分两个容易混淆的概念：编程工具和编程模型。表 II-3 里的都是编程工具，是你直接操作的界面；编程模型则是工具背后的能力来源。很多编程工具都可以切换或配置不同模型。具体哪个模型更适合写代码，会随着产品迭代不断变化，你不需要在这里记住某个固定名单。
- **AI-first，SOLO 模式**：整个界面围绕“和 AI 对话”设计，不需要你懂编辑器怎么操作
- **模型实力强**：字节有自己的大模型（如豆包），能力不输一线
- **免费可用**：个人开发者免费使用，还能免费接入自定义模型
- **对中国用户友好**：中文界面，国内直连
本书以 TRAE 为演示工具，原因很简单：中文界面、上手门槛低、SOLO 模式围绕“和 AI 对话”设计。对零基础读者来说，这比先学一个复杂编辑器更友好。TRAE 还在不断迭代，也许你看到这本书时，产品界面已经不一样了，我相信，这些 AI 编程工具只会越来越容易使用，而不是越来越难。
一句话：TRAE 是目前对零基础、中国用户最友好的 AI 编程工具。
如果你已经有自己熟悉的 AI 编程工具，我鼓励你继续使用自己的工具，因为本书并不是教你学会一个静态的工具，而是学会一种思维模式。后面的关键不是某个按钮在哪里，也不是要记住某个具体命令，而是学会使用 AI 来实现自己的投资想法、检验自己的投资想法，这比学习工具本身重要得多。
### 四步装好 TRAE
本书截图主要覆盖 macOS 和 Windows。如果你使用 Linux，书中的思路仍然适用，但个别安装命令、界面位置和系统权限提示可能需要按你的发行版调整。
#### 1. 下载 TRAE
接下来的安装顺序会和上面的介绍略有不同：我们先装 AI 编程工具 TRAE，再让 TRAE 帮你装 Python 环境和这些库。这样做的目的，是让 AI 从第一步开始就参与进来。
访问 TRAE 官网 trae.cn / trae.ai，根据你的操作系统（macOS 或 Windows）下载安装包，下载页面如图 II-1 所示。
## 安装并设置 TRAE
我们这一步只做三件事：下载并安装 TRAE，切到适合本书的 SOLO 模式，再打开一个学习目录。
### 下载并安装 TRAE
访问 TRAE 官网 `trae.cn` 或 `trae.ai`，根据你的操作系统下载安装包。下载页面如图 II-1 所示。
![TRAE 官网下载页面](images/getting-started/trae-download-page.png)
#### 2. 安装 TRAE
运行下载的安装包，按照向导提示完成安装。安装过程很简单，一路点“下一步”即可（Windows 安装向导见图 II-2，macOS 见图 II-3）。
下载完成后运行安装包。Windows 用户按安装向导提示继续，安装界面如图 II-2 所示；macOS 用户把 TRAE 拖入应用程序，安装界面如图 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 所示。
### 切到 SOLO 模式
安装完成后打开 TRAE。默认界面可能是 IDE 模式，如图 II-4 所示；本书使用的是 SOLO 模式，它更像“和 AI 一起完成任务”的工作台。
![TRAE 默认的 IDE 模式界面](images/getting-started/trae-main-interface-ide.png)
切到 SOLO 模式后，界面会变成图 II-5 这样。你最需要关注的是下方的 AI 对话框：后面所有 spec 都会粘贴到这里，让 AI 执行。
![TRAE SOLO 模式界面](images/getting-started/trae-main-interface.png)
SOLO 模式下你只需要关注一个区域：**AI 助手对话框**。后续所有操作都是在这个对话框里完成的。
### 选择编程模型
#### 4. 创建学习目录
TRAE 已经内置了多个编程模型，入门阶段直接使用内置模型即可，不需要一开始就购买或配置额外模型。模型选择界面如图 II-6 所示。
在你的桌面上新建一个文件夹（书中示例文件夹叫 `xquant` ）。然后在 TRAE 中打开它：菜单 → 文件 → 打开文件夹 → 选择 `xquant`，操作过程如图 II-6 所示。
![TRAE 内置的编程模型](images/getting-started/trae-model-selection.png)
![在 TRAE 中打开 xquant 文件夹](images/getting-started/trae-open-folder.png)
如果你已经有某个模型厂商的 API Key，也可以把它配置到所选的编程工具中。例如，你在 DeepSeek 的 API 平台购买了额度，就可以在后台创建 API Key，再填入 TRAE 的自定义模型配置。TRAE 的自定义模型配置界面如图 II-7 所示。
打开后，你会在左侧文件管理器中看到 `xquant` 这个文件夹名称。现在它是空的，很快 AI 会帮你把需要的文件都创建好。
![TRAE 自定义模型](images/getting-started/trae-model-provider.png)
## 一起写第一份 spec：让 AI 装 Python 环境
这里要搞清楚订阅账号和 API 账号的区别。ChatGPT Plus、Claude Max 这类订阅账号，通常是给用户本人在官方产品里直接使用的，不能直接填进“API Key”输入框。AI 编程工具如果要调用外部模型，通常需要 API 账号生成的 API Key；也有一些工具会提供官方登录或订阅集成，具体以工具自己的说明为准。入门阶段先用 TRAE 内置模型即可，后面确实需要更换模型时，再理解 API Key 也不迟。
到这一步 TRAE 装好了，但 Python 还没装。我们的目标是装 Python 3.12 + 7 个依赖包，并且自动验证每个组件都装对了。
最直接的做法是直接告诉 TRAE：“给我装一下 Python 环境。”
### 创建并打开学习目录
不行——AI 不知道你要哪个版本、用什么工具、要哪些包、跑通的标志是什么。它会按自己的偏好装一套，你的同学按他的电脑装另一套，半年后你们的环境完全不同。
在电脑上新建一个文件夹，作为本书的学习目录。建议使用英文路径，比如桌面上的 `xquant-learning` 文件夹，避免中文路径、空格或特殊符号带来额外问题。
正确的做法是写一份 **spec**——前言里讲过的「任务说明书」，把“做什么 + 做成什么样”清清楚楚交给 AI。这份 spec 我们已经写好放在仓库里了——但与其让你直接抄一遍，不如一起从零把骨架走一遍，等你看明白每一段为什么这么写，再去打开真实文件对照。下面我们一段段写。
然后在 TRAE 中打开它：菜单 → 文件 → 打开文件夹 → 选择 `xquant-learning`。操作过程如图 II-8 所示。
### spec 长什么样：四段骨架
![在 TRAE 中打开 xquant-learning 文件夹](images/getting-started/trae-open-folder.png)
一份能让 AI 稳定执行的 spec，通常有四段：
打开后，你会在左侧文件管理器中看到 `xquant-learning` 这个文件夹。现在它还是空的，下一步 AI 会帮你把需要的环境和文件创建出来。
## 让 TRAE 帮你搭建环境
到这一步，AI 编程工具准备好了，但 Python 环境还没准备好。我们的目标是把环境搭建好：装好 Python 3.12，装好本书要用的 7 个库，并用一个检查脚本确认环境真的可用。
最直接的想法，是告诉 TRAE：“给我装一下 Python 环境。”
这样不够。这里先约定一下：后面为了行文简洁，我们会把 AI 编程工具简称为 AI。它不知道你要哪个 Python 版本，用什么工具装，要装哪些库，也不知道怎样才算装对。你可能也不知道这些细节，这很正常；刚开始我会帮你把它们写清楚。
前言里讲过，spec 本身泛指一切要交给 AI 执行的任务说明书。这一章，这个任务就是搭建环境，以后的内容就专门指策略规格说明书了。本章的 spec 要说清楚的是：做什么、怎么做、做到什么程度算成功。
这份完整 spec 已经放在配套仓库里。你可以直接复制运行，但我们也从现在就在这个例子中看懂它为什么这样写。下面我们先看骨架，再一段段拆解。
### 写安装 spec
我们可以先想象一下，如果有人给我们布置一项任务，那么我们希望他怎么描述这项任务，才能让我们一次搞定的概率最高？同样的，我们把 AI 也看做一个人，一份能让 AI 高概率一次性完成的 spec，通常要回答四个问题：
> 📌 **spec 的四段骨架**
>
> 1\. **上下文** — 在什么前提下做这件事（AI 不知道你之前做了什么，要明示）
> 1. **上下文** —— 所有跟这个任务有关的信息、背景知识。
>
> 2\. **任务** — 一句话点明本次要做什么，不用写怎么做。本书中示例
> 2. **任务描述** —— 任务具体要做什么，具体而明确。
>
> 3\. **要求** — 具体步骤，AI 自由度越小越可复现
> 3. **任务要求** —— 任务要遵守的规范，满足的约束，遵循的原则等。
>
> 4\. **结果呈现** — 怎么算成功（最容易被忽略也最重要的部分）
> 4. **验收标准** —— 任务完成时要交付的清单，要满足的标准，清晰可检验。
四段是 spec 必须回答的四个问题：**前提是什么 / 做什么 / 怎么做 / 算不算做对了**——哪一段都不能少。
注意第四段“验收标准”不是让你提前知道运行结果，而是先把成功标准写清楚。以这次环境搭建为例，“看到 `11/11 全部通过`，并且有 `.venv/` 和 `check_env.py`”，这就比“装好了”清楚得多。
我们一段段把“装环境”这个任务写成 spec。
下面四段都以 macOS 为例。Windows 用户不用担心，这次要搭建的环境是跨平台的，而且 spec 的四段骨架完全相同，只需要在上下文中把 macOS 换成 Windows，把 mac 命令换成 PowerShell 命令即可。具体对应关系已经写在 `specs/spec-01-env-setup-windows.md` 里。
### 第一段：上下文
#### 第一段：上下文
我们的状况很简单：刚装好 TRAE，打开了一个空目录，但 Python 一切还没装。这一段写出来：
上下文段告诉 AI：现在是什么状态。我们刚装好 TRAE，打开了一个空目录，Python 和课程要用的库都还没装。这一段可以这样写：
> **上下文**：我（学员）刚在 TRAE 中打开了一个空目录作为课程根目录。本机是 macOS，尚未安装 Python 或任何依赖。这是课程的第一份 spec——后续spec 都依赖这一份装出的环境。
> **上下文**：我刚在 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 自检脚本。
> 📌 **要点 1：能一句话说清，就不要写两句**
>
> 📌 **要点 2：关键事物要具体到 ID 或版本号** “Python” 不够，要 “Python 3.12”；“包管理工具”不够，要 “uv”；“装一些库”不够，要 “7 个具体的库”。任何 spec 中的关键名词都要具体到不能再具体的程度，AI 才不会按自己的偏好随便选一个。
> AI 关注的是指令，不是字数。写得越啰嗦，关键要求越容易被淹没。写 spec 的过程，本质上是在删掉多余的话，只保留真正重要的信息。
### 第三段：要求
#### 第二段：任务描述
要求段是 spec 的主体——把“怎么做”拆成步骤。环境配置一共 6 步：确认目录、装 uv、建虚拟环境、装依赖、写 check_env.py、跑 check。以下要求比较具体，是因为编程需要让环境前后一致，避免引起不必要的问题，实际工作中我们不必告诉 AI 应该怎么做，所以你可以完全复制这一段：
任务描述段要一句话说明目标，不要把所有步骤塞进去。这里先补一个小词：`uv` 是一个管理 Python 环境的工具，它可以帮我们安装 Python、创建虚拟环境、安装库。
> **要求**： 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 文件里。这里只挑两个特别值得讲的细节。
> **任务描述**：在当前目录下完成 macOS 量化课程编程环境配置：安装 uv，用 uv 创建 Python 3.12 虚拟环境，安装 jupyter、pandas、NumPy、Matplotlib、akshare、yfinance、open-xquant，并创建、运行 `check_env.py` 检查脚本。
**装依赖时为什么要锁版本号？** 比较两种写法：
❌ `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`
> 📌 **要点 2：关键对象要点名**
>
> 📌 **要点 4：成功的标志要可机械验证** “跑通了” / “看起来对” / “应该没问题”——这些都是不合格的成功标志。一份好 spec 的结果呈现段要让 AI 自己能说“对了”或“错了”，不需要学员凭感觉判断。assert 语句、具体的数字（11/11）、具体的文件名、退出码——这些就是机械验证。
> “装 Python”不够，要写成“Python 3.12”；“装一些库”不够，要把 7 个库的名字列出来；“写个检查脚本”不够，要写出文件名 `check_env.py`。关键对象越明确，AI 越不容易按自己的偏好补全。
四段拼起来就是一份完整 spec。我们刚才在书里写过的骨架——上下文 / 任务 / 要求 / 结果呈现——和 `specs/spec-01-env-setup-mac.md`（或 `spec-01-env-setup-windows.md`，根据你的系统）里的真实文件一一对应；区别只在于真实文件把 6 步和 check_env.py 全文都写齐了。下一节我们把它交给 TRAE。
#### 第三段：任务要求
任务要求段是 spec 的主体。它把任务拆成可以执行的步骤。环境配置一共 6 步：确认目录、安装 uv、创建虚拟环境、安装库、创建检查脚本、运行检查脚本。
完整命令和 `check_env.py` 全文都在配套仓库的 `specs/spec-01-env-setup-mac.md` 里。书里先摘出开头几步，让你看清写法：
> **任务要求**：
>
> 1. **确认当前目录**：运行 `pwd`，记录路径，后续所有操作都在这个目录下进行。
>
> 2. **安装 uv**：运行 `curl -LsSf https://astral.sh/uv/install.sh | sh`，再运行 `source $HOME/.local/bin/env`，最后用 `uv --version` 检查是否安装成功。
>
> 3. **创建 Python 3.12 虚拟环境**：运行 `uv venv --python 3.12`，再激活虚拟环境，并用 `python --version` 确认版本。
>
> 4. **安装 7 个库**：按 spec 文件中的版本号安装 jupyter、pandas、NumPy、Matplotlib、akshare、yfinance 和 open-xquant。
>
> 5. **创建 `check_env.py`**：把 spec 文件中的检查脚本写入当前目录。
>
> 6. **运行检查脚本**：执行 `python check_env.py`，查看检查结果。
这里有个细节很重要：安装库时要锁版本号。比如不要写：
```bash
uv pip install pandas numpy matplotlib
```
而要写成：
```bash
uv pip install pandas==3.0.* numpy==2.4.* matplotlib==3.10.*
```
不锁版本，半年后某个库升级，书里的代码可能就跑不出来。锁到 `==X.Y.*`，意思是小修小补可以升级，但大版本变化先不要碰。
> 📌 **要点 3：会变化的东西要锁住**
>
> 库版本会变，日期窗口会变，随机数也可能变。量化实验最怕今天能跑、明天不能复现。凡是会随时间漂移的关键条件，都要尽量写死。
#### 第四段：验收标准
最后一段写成功标准。你还没有运行，怎么知道成功长什么样？答案是：你不用猜最终数据，只要约定检查脚本应该给出哪些信号。
比如这次我们要求看到 `11/11 全部通过`，要求命令退出码为 0，要求目录里出现 `.venv/` 和 `check_env.py`。这些都是 AI 和你都能核对的信号。
> **验收标准**：
>
> 1. `python check_env.py` 最末两行输出：
>
> ```text
> 结果: 11/11 全部通过！
> 环境配置完成，可以开始课程。
> ```
>
> 2. 命令退出码为 0。
>
> 3. 当前目录下存在 `.venv/` 目录与 `check_env.py` 文件。
> 📌 **要点 4：成功标准要能检查**
>
> “看起来没问题”不算成功标准。更好的写法是给出具体数字、具体文件名、具体输出文字。这样 AI 做完后，你不用凭感觉判断，对照检查就行。
四段拼起来，就是一份完整安装 spec。下一节我们把真实文件交给 TRAE 执行。
## 让 TRAE 跑这份 spec
上一节我们把这份 spec 在书里一段段写完了，现在把它交给 TRAE 真正执行。在打开 spec 文件之前，先看下面这条提示——等下 TRAE 弹窗时你就不会被吓到：
上一节我们已经看懂了安装 spec 的结构，现在要让 TRAE 来执行这一份任务说明书。打开文件之前，先看一个提示，等下看到弹窗就不会慌。
> **💡 提示：关于“沙箱”**
>
> TRAE 帮你装环境时会弹窗询问是否允许“在沙箱外运行”。别紧张：AI 平时是在一个受限的小房间（沙箱）里活动，但现在它要帮你布置整个工作台，需要你给它开一下门。遇到这个提示，直接点“是”或“允许”即可，过程示意如图 II-7 所示。
>
> 如果你打开 spec 文件第一行也写了“所有命令在沙箱外运行”——这就是 TRAE 弹窗问你的原因；不是出错，是预期里的一步。
> TRAE 帮你装环境时，可能会询问是否允许“在沙箱外运行”。所谓“沙箱”，就是给 AI 的操作设置一个受限制的运行范围，用来降低误操作影响真实文件和系统环境的风险。但这次要安装的 Python 环境需要访问你的真实终端和学习目录，所以通常需要允许它在终端中运行。遇到这个提示，选择“是”“允许”或“在终端中运行”即可。过程示意如图 II-9 所示。
![TRAE 沙箱提示示意](images/getting-started/trae-solo-sandbox.png)
读完提示，再打开你系统对应的 spec 文件——
现在打开你系统对应的 spec 文件：
- **macOS 用户**：打开 `specs/spec-01-env-setup-mac.md`
- **Windows 用户**：打开 `specs/spec-01-env-setup-windows.md`
把 spec 全部内容复制到 TRAE 的 AI 对话框中，发送。
把 spec 的全部内容复制到 TRAE SOLO 模式下方的 AI 对话框中，发送。
AI 会自动完成 6 个步骤：装 uv、建虚拟环境、装 7 个依赖包（含 open-xquant 框架）、创建 check_env.py、跑自检。整个过程几分钟。你不需要理解每一步细节，只需要看最后的检查结果。
TRAE 会按 spec 自动完成 6 个步骤：安装 uv、创建虚拟环境、安装 7 个库、创建 `check_env.py`、运行检查脚本。整个过程通常只需要几分钟。你不需要理解每一条命令，只需要看最后的检查结果。
### 验证结果
如果一切顺利，你会在 TRAE 的终端中看到类似这样的输出：
==================================================
XQuant 课程环境检查
==================================================
```text
==================================================
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 条数据）
[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 全部通过！
环境配置完成，可以开始课程。
--------------------------------------------------
结果: 11/11 全部通过！
环境配置完成，可以开始课程。
```
实际终端输出如图 II-8 所示。
实际终端输出如图 II-10 所示。
![环境检查全部通过](images/getting-started/env-check-success.png)
如果有任何项目显示 `[FAIL]`，**不要紧张，也不要自己改命令重试**——把完整的输出结果复制给 TRAE 的 AI 助手，告诉它“环境检查有失败项，请帮我修复”。AI 会照着 spec 里“故障恢复”那一节的对照表逐项排查。
其中 `akshare 数据源连通` 后面的条数可能和书里不同，这不影响结果。关键是这一项显示 `[OK]`，并且最后出现 `11/11 全部通过`。
> **💡 关于错误处理的原则**
如果有任何项目显示 `[FAIL]`，不要自己改命令重试。把完整输出复制给 TRAE 的 AI 助手，告诉它：“环境检查有失败项，请帮我修复。”AI 会按照 spec 里的故障恢复说明逐项排查。
> **💡 关于错误处理**
>
> 整本书你都不必去**啃** Python 报错——遇到任何报错，**把完整信息复制给 AI 助手**就好。AI 排查报错的能力远比让初学者读 stack trace 强。这是本书的承诺：你只写 spec、看结果，调试交给 AI。
> 整本书你都不必去啃 Python 报错。遇到报错，把完整信息复制给 AI 助手就好。你的工作是写清楚任务、看懂结果；调试细节先交给 AI。
## 你刚刚学到了什么
### 你做了什么
刚才这个过程包含两件事。
刚才的过程其实包含两件事：
第一，环境准备好了。这件事做完后，后面章节就可以直接跑实验。
① **环境装好了**——这件一次性的事做完了，往后不用再碰。 ② **你看到了一份 spec 是怎么从零写出来的**——四段骨架在你眼前展开了一遍，四条核心要点各自示范了一次。
第二件事比第一件重要。
第二，你看到了一份 spec 是怎样写出来的。它不是一段模糊、碎片、随意的说法，而是由上下文、任务描述、任务要求、验收标准四段组成。你把任务说清楚，AI 才能稳定执行。
### 7 条 spec 自查清单
刚才本节示范了 4 条要点（写在每段 spec 之后的「📌 要点 1-4」）。把这 4 条加上 3 条通用补充，就构成下面这份“写完 spec 过一遍”的自查清单——任何一条没做到都是问题：
把本章的 4 条要点，再加上后面会反复用到的 3 条补充，就得到一份 spec 自查清单。以后每写完一份 spec，都可以用它快速扫一遍。
| \# | 自查项 |
|----|----|
| 1 | **四段都齐了？** 上下文 / 任务 / 要求 / 结果呈现，一段都不能少 —— 结构骨架 |
| 2 | **任务一句话能说清吗？** “做一下数据分析” ❌；“获取沪深 300ETF 历史数据并可视化” ✅ —— 来自要点 1 |
| 3 | **关键事物具体到 ID 了吗？** 标的代码、库版本、文件名、参数名都点名 —— 来自要点 2 |
| 4 | **能锁的都锁了吗？** 库版本、日期窗口、随机种子——任何会随时间漂移的都要锁 —— 来自要点 3 |
| 5 | **结果呈现有“机器能判断的标志”吗？** assert、具体数字、文件名、退出码 —— 来自要点 4 |
| 6 | **写的是“做 X”而不是“不要 Y”吗？** 正向指令比否定句对 AI 更稳定 —— 通用补充（首次出现） |
| 7 | **长度合理吗？** 大多数 spec 不超过 80 行（环境配置这种特殊情况除外） —— 通用补充（首次出现） |
**表 II-4 spec 自查清单**
第 6、7 两条本节没有专门演示，会在第 1 章后续 spec 写作中遇到时再补讲。这 7 条会跟着你整本书——每写一份新 spec，最后都过一遍这个清单。
| 序号 | 自查项 |
|------|--------|
| 1 | **四段都齐了吗？** 上下文、任务描述、任务要求、验收标准，一段都不能少 |
| 2 | **任务能一句话说清吗？** 先讲目标，不要把所有步骤塞进任务描述段 |
| 3 | **关键对象准确吗？** 如版本号、库名、文件名等，都要写清楚 |
| 4 | **会变化的条件确定了吗？** 库版本、日期范围、随机种子，都要写清楚，不要变 |
| 5 | **成功标准能检验吗？** 给出具体输出、具体文件、具体数字 |
| 6 | **指令是正向的吗？** 多写“请做 X”，少写“不要 Y” |
| 7 | **长度是否合理？** 不要因为详细，就写得啰嗦，都写必要而准确的话 |
### 你需要做什么
后续每一章都会让你写或改一份 spec。开始时书里会带你一段一段写（像本节这样），后面会渐渐放手——到第 6、7 章你应该能自己写完整的 spec，到第 9 章你应该能根据问题写新 spec。
> **💡 spec 写作能力的成长曲线**
>
> 抄 → 改 → 拼 → 写。第 1 章基本是“抄 + 看懂”；第 2-3 章是“改其中几个参数”；第 4-6 章是“把多个 spec 拼成新流程”；第 7-9 章是“看到一个量化问题，自己写一份新 spec”。每一步都不用着急。
写 spec 不需要死记硬背，多写多实验，多和 AI 交互自然能掌握。模型越强，越能对 spec 容错，但把 spec 写清楚，仍然能减少返工，也能让你更容易判断 AI 有没有做对。后面进入策略实验时，open-xquant 也会帮你检查策略规格说明书里常见的遗漏。
## 准备就绪
恭喜，你现在已经具备了开始量化交易学习的全部条件。
前言和这一章涉及的核心概念，汇总在表 II-5 里。
### 速查表
**表 II-5 准备工作核心概念速查**
前言和这一节涉及的核心概念汇总在表 II-4 里。
| 概念 | 含义 | 这一章怎么用 |
|------|------|--------------|
| spec（任务说明书） | 给 AI 的结构化指令 | 用装环境练第一份 spec |
| spec 四段骨架 | 上下文 / 任务描述 / 任务要求 / 验收标准 | 按四段写清楚任务 |
| TRAE | 本书演示用的 AI 编程工具 | 把 spec 交给它执行 |
| Python 环境 | 跑代码需要的语言和库 | 用检查脚本确认可用 |
| 四个阶段 | 确定候选 / 制定规则 / 执行交易 / 评估归因 | 第 1 章开始正式进入 |
| 做 / 看 / 疑 | 写成规格 / 读懂结果 / 检验可信 | 本章先练“做”：把任务写清楚 |
**表 II-4 动手前的核心概念速查**
到这里，你已经具备了开始学习量化交易的基本条件：有 AI 编程工具，有 Python 环境，也知道一份 spec 应该怎样写。
| 概念 | 含义 | 类比 |
|----|----|----|
| 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 读者`。
第 1 章，我们会用一个真实 ETF 走一遍完整流程：写规则、跑实验、看结果，以及让你产生第一次怀疑，为什么看到实验结果漂亮不要高兴得太早。准备好了吗？翻到下一章，开始第一次量化实验。