前置准备：依赖安装与后端项目启动

项目实战篇提供订单异常工作台及其 Python 后端。本节完成依赖安装、数据库准备和服务启动，再通过浏览器确认系统能够正常使用。

安装与启动命令以 Windows PowerShell 为例。完成后，打开前端页面、输入Agent令牌，即可查看固定的教学订单。

0.1 先看启动哪些东西

浏览器：订单异常工作台（http://127.0.0.1:8000/）
                 ↓
终端：Uvicorn运行FastAPI，同时提供页面与业务接口
                 ↓
业务数据库：MySQL（127.0.0.1:3307）或本地SQLite文件
                 +
LangGraph检查点：由CHECKPOINT_PATH指定的本地SQLite文件

业务数据库保存订单、库存和工单；检查点文件保存工作流暂停与恢复所需状态。即使选择 MySQL，项目仍使用独立 SQLite 文件保存检查点。

准备项	作用	是否必须
Python 3.12	执行业务代码	必须，项目要求 >=3.12 且 ❤️.13
uv	创建虚拟环境、安装锁定依赖、启动命令	必须
PyCharm或其他编辑器	打开代码、编辑.env、使用终端	任选一种
Docker Desktop与Compose	启动课程MySQL容器	MySQL路线需要
浏览器	打开订单异常工作台，查询并查看结果	需要
Codex	后续通过Agent调用工具	后端启动阶段不依赖它

前端由FastAPI直接提供，页面与业务接口共用8000端口。安装完成后只需启动一个应用进程，不需要单独构建前端或运行npm install。业务系统运行不需要OpenAI或DeepSeek模型密钥。

0.2 打开正确的工程目录

在编辑器中打开：

代码/ecommerce-agent

也可以先用资源管理器进入该目录，再在地址栏输入 powershell 打开终端。后续命令都从 ecommerce-agent 根目录执行。

Get-Location
Get-ChildItem -Force

应看到 app、samples、tests、pyproject.toml、uv.lock、compose.yaml、.env.example 和 .python-version。

文件	含义
.python-version	项目选用Python 3.12
pyproject.toml	依赖范围与项目配置
uv.lock	课程锁定的具体依赖版本
.env.example	环境配置样板
compose.yaml	MySQL容器配置
app/api.py	FastAPI入口，提供业务接口和前端页面
app/static	前端HTML、CSS和JavaScript文件
app/seed.py	建表与教学数据初始化

复制工程时保留点号开头的文件和目录；虚拟环境 .venv 应在本机重新创建，不从其他电脑直接搬用。

0.3 安装uv和Python 3.12

安装uv

已安装时先检查：

uv --version

尚未安装，可使用 Windows 的 WinGet：

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

安装后重新打开 PowerShell，再运行 uv --version。没有 WinGet 时，使用uv官方安装页提供的安装器或发行包方式。

准备Python

uv 可以安装并管理项目需要的解释器：

uv python install 3.12

如果本机已经有可用的 Python 3.12，uv 也可以使用现有解释器。安装方式见官方Python管理说明。

这里的3.12指版本系列，补丁号可以不同。项目要求小于3.13，不能直接使用电脑中任意最新Python版本替代。

安装工程依赖

回到工程根目录：

uv sync --frozen
uv run --frozen python --version
uv run --frozen python -c "import fastapi, uvicorn, sqlalchemy, pymysql, mcp, langgraph, dotenv; print('核心依赖导入成功')"

uv sync 创建 .venv 并安装锁定依赖，包括开发组中的pytest。--frozen 表示沿用现有锁文件，不为本次操作重新解析更新版本。

不必再逐项执行 pip install，也不需要手工激活虚拟环境。uv run 会使用项目环境。编辑器解释器选择：

.venv/Scripts/python.exe

依赖	用途
FastAPI、Uvicorn	HTTP接口与服务进程
SQLAlchemy、PyMySQL	业务表查询与MySQL连接
httpx	MCP层调用业务HTTP接口
mcp	暴露MCP工具
LangGraph、SQLite checkpointer	有状态工作流与持久化
python-dotenv	加载.env配置

项目使用官方mcp包的1.x API，不需要额外安装独立fastmcp包。具体版本以工程uv.lock为准。

0.4 创建本地配置

首次准备时执行：

if (-not (Test-Path -LiteralPath ".env")) {
    Copy-Item -LiteralPath ".env.example" -Destination ".env"
}

这段命令仅在 .env 不存在时复制，避免覆盖已经调整过的配置。用编辑器打开 .env。

两个令牌需要不同：AGENT_TOKEN 用于业务查询和工作流推进；APPROVER_TOKEN 用于人工审批。replace-开头的占位值会被API拒绝。

可以用以下命令在终端生成两段不同的本地随机值，再分别填入：

uv run --frozen python -c "import secrets; print('Agent令牌：', secrets.token_hex(24)); print('审批令牌：', secrets.token_hex(24))"

保留自己的实际值，稍后在前端的“Agent令牌”输入框填写AGENT_TOKEN。APPROVER_TOKEN用于后续人工审批，不复制给MCP进程。

.env 的读取不会覆盖进程中已经存在的同名环境变量。更换配置后要重启API；若行为仍像旧配置，检查启动终端是否残留同名变量。不要展示含真实凭据的整份配置。

0.5 选择数据库路线

路线A：MySQL

需要学习MySQL接入时使用此路线。

从Docker官方Windows安装页安装Docker Desktop，按安装器要求准备虚拟化及WSL等环境。启动应用，等待引擎就绪，使用Linux容器模式。

检查：

docker version
docker compose version

docker version 应同时有 Client 和 Server 信息。只有客户端版本，仍不能说明引擎已经启动。

在工程根目录启动数据库：

docker compose up -d --wait
docker compose ps

首次运行会下载MySQL镜像，完成后服务应为运行且健康。compose.yaml 使用MySQL 8.4，将本机3307映射到容器3306，并使用命名卷保存数据。

.env 中保留：

DATABASE_URL=mysql+pymysql://course:course_local_only@127.0.0.1:3307/ecommerce?charset=utf8mb4
CHECKPOINT_PATH=data/checkpoints.sqlite
AGENT_TOKEN=填入自己生成的Agent令牌
APPROVER_TOKEN=填入自己生成的另一个审批令牌

课程容器创建 ecommerce 数据库和 course 账号。不需要另外安装一套本机MySQL。3307是API从本机连接时使用的端口，不能误写成容器内部3306。

路线B：SQLite本地运行

暂时没有Docker时，可以先运行同一后端。在.env中改成：

DATABASE_URL=sqlite:///data/business.sqlite
CHECKPOINT_PATH=data/checkpoints-local.sqlite
AGENT_TOKEN=填入自己生成的Agent令牌
APPROVER_TOKEN=填入自己生成的另一个审批令牌

SQLite随Python使用，不需要单独安装数据库服务。此路线跳过Docker命令，其余初始化和API启动命令一致。

两条路线二选一。更换业务数据库时，配套换一个新的CHECKPOINT_PATH，避免旧工作流检查点关联新业务库。SQLite可以验证本地功能，MySQL连接与部署仍需在MySQL环境确认。

0.6 初始化教学数据

在工程根目录执行：

uv run --frozen python -m app.seed

预期输出：

初始化完成：7 个订单、3 条库存、2 条履约记录

程序创建五张业务表，再插入固定样本。data目录也会自动创建。日期固定在2026-10-10，便于后面重复核对。

这一步只在新课程数据库上执行一次。看到“订单表已有数据，初始化已停止”时，说明已有订单受到保护，不需要为了启动服务清空它们。

数据库配置改动后，先确认初始化连接的是哪一个库。初始化程序不负责启动数据库，也不负责启动API。

0.7 启动应用服务

uv run --frozen python -m uvicorn app.api:app --host 127.0.0.1 --port 8000 --workers 1

参数	含义
python -m uvicorn	通过Python模块启动Uvicorn，避开Windows命令启动器的路径问题
app.api:app	导入app/api.py中的app对象
--host 127.0.0.1	本机访问
--port 8000	前端页面与HTTP接口共用的端口
--workers 1	单服务进程，与课程工作流锁设计一致

看到Application startup complete后，保留这个终端。服务运行时不返回普通命令提示符是正常现象，接下来切换到浏览器操作。

本项目使用一个稳定的应用进程，不默认添加--reload，避免编辑文件触发重启干扰工作流。

0.8 在浏览器确认系统可用

打开工作台

浏览器访问：

http://127.0.0.1:8000/

应看到“订单异常工作台”，左侧有异常订单、处理工作流、工单记录、人工审批四个入口，右上角显示“服务已连接”。

服务状态只说明应用可以响应。还需要完成下面的查询，确认认证、数据库与教学数据可用。

输入令牌并查询

在页面顶部“Agent令牌”输入框中，填写.env中AGENT_TOKEN的实际值。只填令牌本身，不添加Bearer前缀，也不要填审批令牌。

保持页面默认条件：

字段	值
支付日期	2026-10-10
判断基准时间	2026-10-11 12:00，UTC+8

点击“查询异常订单”。预期匹配订单为3条，第一页显示A1001和A1002；点击“下一页”，显示A1003。

再点击一条订单的“查看证据”，确认能够展开库存、履约及建议信息。这里先确认页面可以使用；为什么这三单进入清单、证据怎样解读，在第二章展开。

令牌只在当前页面中使用，刷新页面后需要重新输入。后端修改令牌并重启后，页面也要使用相同的新值。

确认后进入项目学习

完成以下观察即可：

观察	说明
页面正常显示	前端文件可访问
服务已连接	API可以响应
查询返回3条固定订单	身份、业务数据库和教学数据可用
翻页和证据能打开	页面能够继续调用业务接口

本节不需要创建工作流或提交审批。保持服务运行，继续第一章和第二章。

需要查看接口定义时，可从页面左侧打开“查看API文档”；接口调用原理在后续章节介绍。

0.9 停止与再次启动

在运行服务的终端按Ctrl+C结束应用。MySQL路线还可以停止容器：

docker compose stop

该操作保留课程数据卷。下次启动Docker Desktop后，在工程目录执行：

docker compose up -d --wait
uv run --frozen python -m uvicorn app.api:app --host 127.0.0.1 --port 8000 --workers 1

SQLite路线只需重新运行应用启动命令。随后在浏览器打开工作台并输入Agent令牌。依赖未变化时不用重复安装；数据库已初始化时不用再次seed。

保留业务数据库和检查点文件，才能延续已有工作流。不要在每次录制启动前删除data目录或课程数据卷。

重新录制时清空演示数据

先停止API和MCP，在工程根目录执行：

uv run --frozen python -m app.reset_demo --yes
uv run --frozen python -m app.seed

也可以用一条命令完成清空和初始化：

uv run --frozen python -m app.reset_demo --yes --seed

双击工程中的reset-demo.cmd则会先显示目标，要求输入DELETE确认。 脚本仅清空课程业务表和对应检查点，先备份到data/reset-backups， 保留.env与outputs。旧工作流编号和审批记录在重置后失效。 完整范围与端口配置见工程说明。

0.10 常见启动问题

现象	检查与处理
uv命令不存在	安装后重开终端，确认PATH；参照官方安装页
Python版本不符合	执行uv python install 3.12，再检查uv run中的版本
依赖下载失败	阅读网络、代理或证书报错，恢复下载条件后重试uv sync --frozen
找不到pyproject.toml或app模块	回到ecommerce-agent工程根目录
Docker只有Client没有Server	启动Docker Desktop，等待引擎就绪
MySQL容器不健康	查看docker compose logs mysql，确认首次初始化和端口状态
3307端口占用	停止冲突服务，或同步调整compose映射及DATABASE_URL
MySQL连接拒绝	容器未启动、端口错误或初始化未完成
MySQL认证失败	数据库账号、密码或已有数据卷中的账号与当前配置不一致
API提示非占位令牌	将两个replace-值改成不同实际值，检查旧环境变量，再重启
8000端口占用	停止旧API进程；若改端口，浏览器访问地址同步修改
uv trampoline failed to canonicalize script path	使用本节的uv run --frozen python -m uvicorn启动形式
页面显示服务已连接，但查询失败	检查数据库连接、是否建表、是否执行seed及服务端日志
页面打不开或显示服务未连接	检查应用进程是否仍在运行、地址与端口是否正确
查询提示401或403	确认页面使用AGENT_TOKEN，且与后端实际读取值一致
查询数量与课程不同	检查固定日期、带时区的as_of、分页和已有数据变化

本节完成页面查询即可。第三章再启动8001端口的MCP HTTP服务并配置Codex连接；人工审批操作在工作流章节介绍。

项目篇目录 · 第一章：项目背景与架构 · 第二章：认识已有电商系统