单元 00：准备开发环境

在真正讨论市场、收益率和策略之前，我们先完成一件很具体的事：让同一份代码在不同电脑上得到相同的结果。

本单元结束时，你会用 Python 读取一份日频行情 CSV，并确认它包含哪个标的、多少条记录以及什么日期范围。整个过程不需要金融知识，也不需要注册数据平台。

本单元目标

完成本单元后，你将能够：

从 GitHub 克隆教程仓库并进入项目根目录；
使用 uv 创建并同步项目环境；
理解 CSV 文件和数据框（DataFrame）在教程中的分工；
运行一段代码，读取并观察第一份日频行情；
根据预期输出判断自己的环境和数据是否正确。

最终产物是一条可以反复执行的命令：

bash

uv run python examples/unit00/read_prices.py

前置条件

你需要：

一台可以使用终端的 Windows、macOS 或 Linux 电脑；
已安装 Git，并能执行 git --version；
能够执行基本命令，但不需要熟悉 Python 虚拟环境；
能够访问 GitHub；
首次同步环境时可以访问 Python 软件包仓库。

如果尚未安装 Git，请先按照 Git 官方安装说明完成安装。

场景：为什么先管理环境

量化研究很依赖计算结果。如果两个人运行同一段代码，却因为 Python 或第三方库版本不同得到不同结果，我们就无法判断差异来自策略，还是来自环境。

本项目使用 uv 管理两类信息：

pyproject.toml 说明项目需要哪些依赖以及支持哪个 Python 版本；
uv.lock 记录依赖解析后的精确版本，让不同电脑尽可能安装同一套环境。

你可以把虚拟环境理解成项目自己的工具箱。项目需要的 Python 和软件包放在这个工具箱中，不必和电脑上其他项目共用。uv 默认把它放在项目根目录的 .venv/ 中；如果环境损坏，可以根据项目配置重新创建。

克隆教程仓库

选择一个用于存放项目的目录，在终端中执行：

bash

git clone https://github.com/Sunhill666/LearnQuant.git
cd LearnQuant

第一条命令把教程文档、示例代码和固定数据下载到 LearnQuant/，第二条命令进入这个目录。

确认当前位于项目根目录

执行 git status 应能看到当前仓库状态。项目根目录同时包含 pyproject.toml、uv.lock、docs/ 和 examples/；后续命令都在这里运行。

安装并确认 uv

如果已经安装 uv，直接检查版本：

bash

uv --version

看到类似 uv 0.x.y 的版本信息即可，具体数字可能不同。

如果终端提示找不到 uv，请按照 uv 官方安装文档操作。选择你的操作系统：

macOS / LinuxWindows PowerShell

bash

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

先确认你可以执行安装脚本

安装脚本会从网络下载并执行程序。如果你所在的组织不允许这种安装方式，请使用官方文档列出的 Homebrew、WinGet、pipx 等方式，或先让管理员审核脚本。安装完成后可能需要重启终端。

同步项目环境

确认当前位于项目根目录，然后执行：

bash

uv sync --locked

这条命令会：

读取 .python-version，确定项目使用 Python 3.12；
读取 pyproject.toml 和 uv.lock；
在需要时创建 .venv/；
安装锁文件中已经确定的依赖版本。

--locked 表示不允许命令悄悄更新锁文件。如果依赖声明和锁文件不一致，命令会直接报错。这样每位学习者安装的依赖版本都与示例验证时一致，减少“同一份代码在不同电脑上表现不同”的情况。

环境就绪的判断

uv sync --locked 没有报错，就说明环境已经准备好。下一步直接用它运行第一个量化示例。

认识第一份行情数据

打开 demo_etf_daily.csv，你会看到类似下面的内容：

csv

symbol,date,open,high,low,close,volume
DEMO_ETF,2024-01-02,100.00,101.20,99.80,100.80,1000000
DEMO_ETF,2024-01-03,100.90,102.10,100.50,101.70,1120000

CSV（Comma-Separated Values，逗号分隔值）是一种纯文本表格格式：

第一行是列名；
后面每一行是一条记录；
同一行的字段用逗号分隔。

这份文件包含 10 个连续交易日的合成日线。ETF（Exchange-Traded Fund，交易所交易基金）可以暂时理解为“一篮子资产组成、又能像股票一样交易的基金”，单元 01 会详细解释。DEMO_ETF 只是借用了这个名字的虚构教学标的，不对应任何真实证券；所有价格和成交量均由项目手工构造。这样做是为了让第一课稳定可运行，而不是把时间花在网络、密钥和数据授权上。

文件的完整来源、字段、时间和价格口径记录在样例数据说明。真实行情会在后续单元引入。

你现在不需要记忆每个行情字段。先建立一个直觉：一行代表一个标的在一个交易日的行情摘要。单元 01 会正式解释开盘价、最高价、最低价、收盘价和成交量。

用 pandas 读取 CSV

运行本单元示例：

bash

uv run python examples/unit00/read_prices.py

这里不需要手动激活 .venv。uv run 会自动在项目环境中执行后面的命令，后续教程也统一采用这种写法。

预期输出：

text

数据文件: docs/public/data/demo_etf_daily.csv
读取成功
标的: DEMO_ETF
记录数: 10
日期范围: 2024-01-02 -> 2024-01-15

前 3 行:
  symbol       date  open  high   low  close  volume
DEMO_ETF 2024-01-02 100.0 101.2  99.8  100.8 1000000
DEMO_ETF 2024-01-03 100.9 102.1 100.5  101.7 1120000
DEMO_ETF 2024-01-04 101.8 102.0 100.7  101.2  980000

检查点

只要“标的”“记录数”和“日期范围”一致，本单元的核心任务就完成了。表格中小数的显示宽度可能随 pandas 版本略有差异，不影响数据本身。

代码在做什么

打开 examples/unit00/read_prices.py，核心代码只有几步：

python

prices = pd.read_csv(DATA_PATH, parse_dates=["date"])
print(prices.head(3).to_string(index=False))

pd.read_csv 把磁盘上的 CSV 读入内存，得到一个数据框（DataFrame）。DataFrame 是 pandas 提供的二维表格对象，可以把它暂时理解为“带列名和数据类型的电子表格”。后续计算收益率、指标和策略持仓时，我们都会在 DataFrame 上增加或变换列。

parse_dates=["date"] 告诉 pandas 把 date 解析成日期，而不是普通字符串。head(3) 取前 3 行，to_string(index=False) 则让终端输出更适合阅读。

示例还做了三项最小检查：文件不能是空的、必要列必须存在、日期必须按时间递增。这些检查不是完整的数据质量审计；单元 02 会专门处理重复、缺失、非法价格和异常记录。

为什么本单元使用脚本

Python 脚本适合保存完整、可重复执行的流程；交互式笔记本（Notebook）适合边探索边观察中间结果。两者都常用于量化研究，但本教程先用脚本建立明确的输入和输出，之后需要交互式绘图时再引入 Notebook。

验证结果

完成下面的检查：

bash

uv run python -c "import pandas as pd; print(pd.__version__)"
uv run python examples/unit00/read_prices.py

第一条命令应输出 pandas 版本，第二条命令应输出 10 条记录和正确日期范围。它们分别证明：

项目依赖已经安装在可用环境中；
示例程序找到了数据文件；
CSV 能被解析成 DataFrame；
当前数据与教程使用的是同一份固定样例。

请注意，这些结果只证明开发环境和输入文件正确，不证明 DEMO_ETF 有投资价值。它甚至不是真实证券。

常见问题

终端提示 uv: command not found

uv 尚未安装，或者安装目录还没有进入系统的 PATH。先重启终端，再执行 uv --version；仍失败时回到官方安装文档检查对应系统的说明。

提示找不到 pyproject.toml

你可能不在项目根目录。切换到同时包含 pyproject.toml、uv.lock、docs/ 和 examples/ 的目录，再执行命令。

提示找不到 CSV 文件

不要只复制 read_prices.py 到其他目录运行。示例通过项目结构定位固定教学数据，需要完整项目目录。检查 docs/public/data/demo_etf_daily.csv 是否存在。

下载 Python 或依赖失败

首次 uv sync --locked 可能需要联网。代理、防火墙或软件包镜像配置都可能影响下载。网络恢复后重复执行即可；不要通过删除 uv.lock 来绕过问题。

是否需要手动执行 source .venv/bin/activate

不需要。本教程统一使用 uv run ...，由 uv 选择项目环境。你仍然可以手动激活虚拟环境，但这不是完成教程的必要步骤。

小结

本单元完成了量化研究链路的第一个环节：建立可复现环境，并把固定输入读进程序。

text

git clone → 项目目录
            ↓
pyproject.toml + uv.lock
            ↓
       uv sync --locked
            ↓
      项目 Python 环境
            ↓
     固定 CSV → DataFrame
            ↓
       可验证的终端输出

此时我们只知道“数据成功读进来了”，还不知道这些列在市场中代表什么。下一单元将进入认识市场与行情。

练习

基础练习

把示例中的 head(3) 改成 head(5)，再次运行程序，确认输出从 3 行变成 5 行。完成后可以改回原样，方便后续对照教程输出。

进阶练习

在不修改 CSV 的前提下，让程序额外输出全部列名。提示：DataFrame 的 columns 属性保存列名。思考为什么研究代码应该先检查列名，再开始计算。

单元 00：准备开发环境 ​

本单元目标 ​

前置条件 ​

场景：为什么先管理环境 ​

克隆教程仓库 ​

安装并确认 uv ​

同步项目环境 ​

认识第一份行情数据 ​

用 pandas 读取 CSV ​

代码在做什么 ​

为什么本单元使用脚本 ​

验证结果 ​

常见问题 ​

小结 ​

练习 ​

基础练习 ​

进阶练习 ​

单元 00：准备开发环境

本单元目标

前置条件

场景：为什么先管理环境

克隆教程仓库

安装并确认 uv

同步项目环境

认识第一份行情数据

用 pandas 读取 CSV

代码在做什么

为什么本单元使用脚本

验证结果

常见问题

小结

练习

基础练习

进阶练习