AI Agent 量化课程课前准备

建议至少提前一天完成，首次下载工具和依赖可能需要较长时间。

1. 课前完成清单

准备稳定的网络环境。
安装 CodeBuddy IDE 并完成登录。
安装 Git。
通过 Git 下载 QuantSpace。
用 AI 编程工具打开 QuantSpace 仓库根目录。

本课程默认使用 CodeBuddy 演示和完成任务。QuantSpace 同时兼容 ChatGPT Codex、Claude Code、Cursor、Qoder、TRAE、OpenCode、OpenClaw、Kimi Code 等其他 AI 编程工具；已经熟悉其他工具的学员可以继续使用，但本页只介绍 CodeBuddy 的安装方式。

2. 网络环境

课程需要访问 GitHub、Python、PyPI 和 CodeBuddy 官网。请学员自备稳定、合规的海外网络访问方式，并遵守所在地及所在机构的网络规定。

建议提前确认能够访问：

如果网络不稳定，请提前完成软件下载、账号登录和 Python 依赖安装。Python 包无法从官方 PyPI 下载时，可参考第 6.2 节使用国内镜像。

3. AI 编程工具

本课程默认使用 CodeBuddy IDE。它同时提供代码编辑和 AI Agent 能力，适合初学者直接在图形界面中打开课程项目、运行命令和查看修改。

如需订阅会员，请在开通前确认所在地区可用、套餐额度及自动续费规则，并根据课程周期决定是否续订。

3.1 安装 CodeBuddy IDE

安装与登录文档：CodeBuddy IDE 安装和登录

系统要求：

macOS 11 或更高版本。
Windows 10 或更高版本。

安装步骤：

打开 CodeBuddy 官方安装文档，进入下载页面并选择与操作系统和处理器匹配的版本。
Windows 双击安装包并按提示完成安装；macOS 将 CodeBuddy IDE 拖入 Applications。
启动 CodeBuddy IDE，点击“登录”，在浏览器中使用微信或手机号完成登录。

安装和登录完成后，继续按照第 4 节下载并打开课程项目。不要在尚未打开 agent-quantspace 项目时让 AI Agent 开始安装项目环境。

4. 公共基础工具

4.1 安装 Git

下载：Git

Windows：

安装 Git for Windows，保持默认选项即可。
重新打开 PowerShell。

macOS：

xcode-select --install

验证：

git --version

4.2 从 GitHub 下载 QuantSpace

推荐直接通过 CodeBuddy 下载并打开项目：

回到 CodeBuddy 首页，点击“克隆 Git 仓库”。
输入仓库地址 https://github.com/quantskills/agent-quantspace.git。
选择用来存放课程项目的本地目录，等待克隆完成。
克隆完成后点击“打开”，进入 agent-quantspace 项目。

也可以在准备用来存放课程项目的目录中执行：

git clone https://github.com/quantskills/agent-quantspace.git
cd agent-quantspace

确认目录中存在 AGENTS.md、README.md、pyproject.toml 和 uv.lock。

已经下载过项目时，在项目目录执行：

git pull

如果本地存在未保存的修改，先备份或向老师求助，不要直接覆盖。

4.3 使用 CodeBuddy 打开项目根目录

如果克隆完成后项目没有自动打开，或者项目已经下载到本地，则在 CodeBuddy 首页点击“打开文件夹”，或从菜单选择 文件 -> 打开文件夹，然后选择完整的 agent-quantspace 文件夹。

不要只打开存放项目的父目录，也不要只打开项目中的 lessons、skills 等子目录。CodeBuddy 官方操作说明：打开或克隆项目

确认 CodeBuddy 左侧文件树的根目录是 agent-quantspace，并且可以直接看到：

AGENTS.md
.python-version
pyproject.toml
uv.lock

确认项目根目录已经正确打开后，先按照第 4.4 节安装 Parquet 插件，再按照第 4.5 节进入 AI Agent 对话。CodeBuddy Agent 会自动把当前打开的项目作为工作上下文。

4.4 在 CodeBuddy 中安装 Parquet 插件

课程数据主要使用 Parquet 格式，不需要另外安装 VS Code。直接在 CodeBuddy 中安装 Parquet 查看插件即可：

打开 CodeBuddy 左侧的“扩展”面板。Windows 使用 Ctrl + Shift + X，macOS 使用 Command + Shift + X。
搜索 Parquet Viewer，选择与当前 CodeBuddy 版本兼容的插件并点击“安装”。
安装完成后，在 CodeBuddy 文件树中打开 .parquet 文件，应能看到文件内容而不是二进制乱码。

本课程只要求查看 Parquet 文件，不需要编辑其中的数据。如果插件市场提示版本不兼容，请选择搜索结果中另一款支持 Parquet 预览的插件。

4.5 把本文档交给 CodeBuddy AI Agent

在 CodeBuddy 右上角点击“打开 Agents”，进入智能体界面。
新建任务并选择“编程模式”，确认任务使用的工作目录是当前打开的 agent-quantspace。
将本文档内容复制到对话框，或者把保存后的文档文件拖入对话框作为上下文。
在文档后附上下面的请求并发送：

请按照这份课前准备文档检查当前项目环境，并完成尚未完成的安装步骤，最后执行第 7 节的环境验收。
已经完成的步骤只需验证，不要重复安装。
如需管理员权限、账号登录、浏览器授权或敏感信息，请暂停并提示我手工完成。
不要修改 QuantSpace 的课程代码和课程材料。

根据提示批准必要的命令，但不要把系统密码、Cookie、访问令牌或 API Key 直接发送给 AI。CodeBuddy Agent 应在当前 agent-quantspace 项目中执行命令；如果对话中显示的是其他工作目录，请先停止任务并重新选择项目根目录。

5. 安装 Python 3.11

项目通过 .python-version 固定使用 Python 3.11。推荐让 uv 管理 Python，不需要单独配置系统 PATH。

pyproject.toml 和 uv.lock 顶部的 requires-python 描述项目支持的 Python 版本范围；uv.lock 中出现 Python 3.12、3.13 等条件，是 uv 为其他解释器准备的依赖解析分支，不表示课程要求切换到这些版本。课前安装以 .python-version 指定的 Python 3.11 为准。

安装过程中不要删除或修改 .python-version，不要擅自修改 pyproject.toml 或 uv.lock 中的 requires-python，也不要使用 --ignore-requires-python 绕过版本检查。如发现这些文件的版本信息不一致，请停止安装并向老师反馈。

文档：uv 安装

5.1 Windows

在 PowerShell 中执行：

winget install --id=astral-sh.uv -e

如果没有 WinGet：

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

重新打开 PowerShell，然后执行：

uv --version
uv python install 3.11

5.2 macOS

在终端执行：

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

重新打开终端，然后执行：

uv --version
uv python install 3.11

已安装 Homebrew 时也可以执行：

brew install uv
uv python install 3.11

5.3 验证

uv run --no-project --python 3.11 python --version

应显示 Python 3.11.x。

6. 安装项目依赖

以下命令都应在包含 pyproject.toml 和 uv.lock 的项目根目录中执行。

6.1 课程推荐安装

uv sync --locked --extra panda_data --extra query

该命令会创建 .venv，并安装默认数据分析依赖、PandaData、DuckDB 和开发测试工具。

项目依赖统一通过 uv sync 管理，不要在 .venv 中逐个执行 pip install。

6.2 无法访问 PyPI 时使用国内镜像

如果官方 PyPI 超时或下载过慢，可临时使用国内镜像。以下命令以清华 TUNA 为例：

uv sync --locked --default-index https://pypi.tuna.tsinghua.edu.cn/simple --extra panda_data --extra query

也可以把镜像地址替换为：

中科大：https://mirrors.ustc.edu.cn/pypi/simple
阿里云：https://mirrors.aliyun.com/pypi/simple/

参考：

某个镜像缺少包或版本时，直接更换另一个镜像。国内镜像只解决 Python 包下载问题，不能解决 GitHub、AI 工具登录或 Python 解释器下载问题。

6.3 可选依赖

进入相关课程后再按需安装：

# PyCaret 机器学习扩展
uv sync --locked --extra panda_data --extra query --extra ml

# tsfresh 时间序列扩展
uv sync --locked --extra panda_data --extra query --extra ts

7. 环境验收

在项目根目录执行：

uv run python --version
uv run python -c "import numpy, pandas, matplotlib, sklearn, pyarrow, xgboost; print('核心依赖正常')"
uv run python -c "from skills.ingest import PandaDataClient; print('QuantSpace 接口正常')"

然后确认：

CodeBuddy IDE 或所选 AI 编程工具能够打开 agent-quantspace 仓库根目录。
新建的 AI 会话能够读取 AGENTS.md、.python-version 和 pyproject.toml，并正确说明课程使用 Python 3.11。
CodeBuddy 能够阅读 .py 和 .md 文件，并通过 Parquet 插件打开 .parquet 文件。
三条验收命令分别显示 Python 版本、核心依赖正常 和 QuantSpace 接口正常。

8. 常见问题

AI 编程工具提示项目需要 Python 3.13 或更高版本

这是对项目配置的误读。本课程统一使用 Python 3.11，版本由仓库根目录的 .python-version 指定。

pyproject.toml 和 uv.lock 顶部的 requires-python = ">=3.10" 表示项目支持 Python 3.10 及以上版本，不表示必须使用 Python 3.13。uv.lock 中出现的 python_full_version == "3.13.*" 等内容，是 uv 为不同 Python 版本和操作系统生成的依赖解析分支，也不表示项目最低需要 Python 3.13。

遇到这种提示时，应继续使用 Python 3.11，并按照第 5、6 节的命令安装。不要删除或修改 .python-version，不要擅自修改 requires-python，也不要使用 --ignore-requires-python 绕过版本检查。

命令不存在

关闭并重新打开终端。如果仍然无效，检查命令是否已加入 PATH。macOS 使用 zsh 时也可以执行：

source ~/.zshrc

`uv sync` 下载失败

重试原命令，uv 通常会复用已下载的缓存。
检查 PyPI、GitHub 和 Astral 的网络连接。
尝试第 6.2 节的国内镜像。
不要在下载过程中删除 .venv 或 uv 缓存。

AI 工具无法登录

检查官网连接、账号权限、系统时间和浏览器登录回调。需要 API Key 时在本机安全输入，不要发到课程群或写入 Git 仓库。