02 · 环境搭建:uv 与开发工具链

本篇目标:把三个项目需要的所有开发工具一次性装好、配好、验证好。跟着做完,你的电脑就是一台合格的 Agent 开发机。全程约半天。

0. 我们要装什么,为什么

说明:官方仓库里项目一、三用的是传统 python -m venv + pip,项目二用的是 uv。本教程统一用 uv——它同时取代这两者,而且快得多。你也随时可以退回 pip,命令我都会给双份。

0.1 零基础必读:什么是终端,怎么用

本篇开始会大量出现"在终端执行 xxx 命令"。终端(Terminal / 命令行)就是一个用文字和电脑对话的窗口:你敲一行命令,回车,电脑执行并把结果打印给你。装软件、启动后端、看报错,全都在这里进行。

怎么打开:

• macOS:按 Command + 空格 调出聚焦搜索,输入"终端"(Terminal),回车
• Windows:按 Win 键,输入 "PowerShell",回车(不要用老的"命令提示符 cmd",本教程命令按 PowerShell 给)

打开后你会看到一行提示符(类似 c@MacBook ~ %),光标在闪——它在等你输入。先学四个保命命令:

pwd            # 我现在在哪个文件夹?(Windows PowerShell 也支持)
ls             # 列出当前文件夹里有什么
cd 文件夹名     # 进入某个文件夹(cd = change directory)
cd ..          # 返回上一层文件夹

四个使用常识:

1. 终端里的命令是在"当前文件夹"里执行的。教程里说"在 backend 目录下执行",意思是先 cd 进去再敲命令。报"文件不存在"时,第一反应用 pwd 看看自己站在哪
2. 复制粘贴:macOS 正常 Cmd+C/V;Windows PowerShell 里右键=粘贴
3. 命令执行中时终端会"卡住不动"(比如启动后端后),这是正常的——它在干活。想终止按 Ctrl + C
4. 本教程需要同时开多个终端(一个跑后端、一个跑前端):终端窗口可以开任意多个,互不影响

1. 安装 Python(3.10 或更高)

三个项目都要求 Python >= 3.10。

macOS:

# 用 Homebrew(推荐)
brew install python@3.12

# 验证
python3 --version   # 应显示 3.10 以上

Windows:

1. 打开 https://www.python.org/downloads/ 下载最新版安装包
2. 安装时务必勾选 "Add Python to PATH"(不勾后面全部命令报"不是内部或外部命令")
3. 打开 PowerShell 验证:python --version

Linux (Ubuntu/Debian):

sudo apt update && sudo apt install python3 python3-venv python3-pip
python3 --version

坑位预警:如果 python3 --version 显示 3.8/3.9,后面装依赖时会报 requires-python >=3.10 错误。请务必先升级。

2. 安装 uv —— 本教程的核心工具

uv 是 Rust 写的 Python 包管理器,一个工具顶三个:pip(装包)、venv(虚拟环境)、pyenv(管理 Python 版本)。

macOS / Linux:

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

Windows (PowerShell):

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

装完重开一个终端,验证:

uv --version    # 显示版本号即成功

2.1 uv 的四个最常用命令

# 1. 在项目目录下创建虚拟环境(生成 .venv 文件夹)
uv venv

# 2. 装包(自动装进 .venv,不污染系统)
uv pip install fastapi

# 3. 按 requirements.txt 批量装(项目一、三会用)
uv pip install -r requirements.txt

# 4. 按 pyproject.toml 同步依赖(项目二会用,读取 uv.lock 精确复现环境)
uv sync

2.2 虚拟环境是什么?为什么必须用?

虚拟环境 = 每个项目自己独立的"包仓库"。项目 A 要 pydantic 2.x、项目 B 要 pydantic 1.x,不用虚拟环境就会互相打架。

激活虚拟环境(激活后,python、pip 命令都指向这个环境):

# macOS / Linux
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

激活成功的标志:命令行提示符前面多了 (.venv) 或 (项目名)。

小技巧:用 uv run python main.py 可以不激活直接在虚拟环境里跑命令,忘了激活也不怕。

2.3 uvx —— 项目一会悄悄用到它

uvx 是 uv 自带的"临时运行器":不安装、直接跑一个 Python 工具包。项目一的后端代码里有这样一行:

server_command=["uvx", "amap-mcp-server"]

意思是:Agent 启动时,用 uvx 临时拉起高德地图 MCP 服务器。所以就算你用 pip 装依赖,uv 也必须装——没有它,项目一的地图工具起不来。

3. 安装 Node.js(前端需要)

项目一、二的前端是 Vue 3 + Vite,需要 Node.js 16+(建议直接装 LTS 版本,当前是 20+)。

macOS:

brew install node

Windows / Linux: 到 https://nodejs.org/ 下载 LTS 安装包。

验证:

node --version    # v18 以上
npm --version     # 随 node 一起装上

npm 是 Node 的包管理器,角色相当于 Python 世界的 pip。前端目录里跑 npm install = 后端目录里跑 uv pip install -r requirements.txt。

国内网络下 npm 很慢,建议换淘宝镜像:

npm config set registry https://registry.npmmirror.com

4. 安装 Git 并拉取官方仓库

macOS: 终端输入 git --version,没有会自动弹窗引导安装。 Windows: https://git-scm.com/ 下载安装(一路默认下一步)。

名词解释:GitHub 是全世界最大的代码托管网站,一个"仓库(repository)"就是一个项目的完整代码文件夹;git clone = 把这个文件夹完整下载到你电脑上。Git 本身是版本管理工具,本教程只用到它"下载代码"这一个功能,不用深学。

然后把官方代码仓库拉到本地:

cd ~/PycharmProjects        # 或你喜欢的任何目录
git clone https://github.com/datawhalechina/hello-agents.git
cd hello-agents/code
ls    # 应看到 chapter1 ~ chapter16 目录

我们主要用到:

code/chapter13/helloagents-trip-planner/    # 项目一:旅行助手
code/chapter14/helloagents-deepresearch/    # 项目二:深度研究
code/chapter15/Helloagents-AI-Town/         # 项目三:赛博小镇

网络不通 GitHub?用国内镜像:git clone https://gitee.com/mirrors_datawhalechina/hello-agents.git(若镜像不存在,可在 https://ghproxy.link/ 找加速前缀,如 git clone https://ghfast.top/https://github.com/datawhalechina/hello-agents.git)。

5. 安装编辑器

推荐 VS Code(免费、轻量):https://code.visualstudio.com/

装好后安装这几个扩展(左侧扩展图标 → 搜索):

• Python(微软官方,语法提示 + 调试)
• Pylance(类型检查,看代码时能悬停显示函数签名)
• Vue - Official(项目一、二的前端 .vue 文件高亮)
• Even Better TOML(看 pyproject.toml 用)

已经在用 PyCharm 也完全可以,注意把项目解释器指到 .venv 即可(设置 → Project → Python Interpreter → Add → Existing → 选 .venv/bin/python)。

6. 申请 API Key

6.1 LLM API Key(必须,三个项目都要)

任选其一(都便宜或免费,教程实测均可用):

拿到手的是一串 sk- 或类似开头的字符串。把它当密码保管:不要发群里、不要提交到 Git。

三个项目的 .env 都用同一套变量名(HelloAgents 框架约定):

LLM_MODEL_ID=Qwen/Qwen2.5-72B-Instruct       # 模型名
LLM_API_KEY=你申请到的key
LLM_BASE_URL=https://api-inference.modelscope.cn/v1/

用 DeepSeek 就写 LLM_MODEL_ID=deepseek-chat + 对应 BASE_URL。模型名、Key、地址三者必须来自同一家,混着填是新手第一大坑。

6.2 高德地图 API Key(项目一要用,免费)

1. 注册高德开放平台:https://lbs.amap.com/
2. 控制台 → 应用管理 → 创建新应用
3. 在应用下添加两个 Key: - 服务平台选 Web服务 → 给后端 MCP 用(填到后端 .env 的 AMAP_API_KEY) - 服务平台选 Web端(JS API) → 给前端地图显示用(填到前端 .env)
4. 个人开发者免费额度:每天几千次调用,学习绰绰有余

6.3 搜索 API(项目二可选)

项目二默认用 DuckDuckGo 搜索,无需任何 Key。想要更高质量的搜索结果,可以再申请 Tavily(每月 1000 次免费),后面项目二篇会讲怎么切换。

7. 全链路验证:跑一个最小 Agent

新建一个测试目录,验证"uv + Python + LLM Key"全链路通畅:

mkdir ~/agent-env-test && cd ~/agent-env-test
uv venv
source .venv/bin/activate            # Windows: .venv\Scripts\Activate.ps1
uv pip install "hello-agents>=0.2.4"

创建 .env 文件(填你自己的 Key):

LLM_MODEL_ID=Qwen/Qwen2.5-72B-Instruct
LLM_API_KEY=你的key
LLM_BASE_URL=https://api-inference.modelscope.cn/v1/

创建 test.py:

from dotenv import load_dotenv
from hello_agents import SimpleAgent, HelloAgentsLLM

load_dotenv()

llm = HelloAgentsLLM()          # 自动读取上面三个环境变量
agent = SimpleAgent(
    name="测试助手",
    llm=llm,
    system_prompt="你是一个友好的助手,回复控制在20字以内。"
)

print(agent.run("用一句话证明你活着"))

运行:

python test.py

看到模型回复一句话 → 恭喜,环境全通了。 报错的话,对照第 09 篇排错手册,或先检查:Key 填对没有、BASE_URL 末尾斜杠、网络代理。

8. (项目三前置)安装 Godot

可以现在装,也可以到项目三再装:

1. 打开 https://godotengine.org/download
2. 下载 Godot 4.2+ 标准版(不需要 .NET 版)
3. macOS 拖进应用程序;Windows 解压即用,无需安装

Godot 是单文件绿色软件,总共不到 100MB。

自测清单

以下命令全部有正常输出,才算环境搭建完成:

python3 --version     # >= 3.10
uv --version
node --version        # >= 16
npm --version
git --version

外加:

1. test.py 成功打印出 LLM 的回复
2. 高德开放平台里能看到两个 Key(Web服务 + Web端JS API)
3. 官方仓库已 clone 到本地,能看到 code/chapter13~15 三个目录

下一篇:03 · Agent 原理与 HelloAgents 框架精讲