（十八）运行与重建完整学习助手

1. 从目录找到职责

完整项目延续第十七章的 src 布局。安装名为 python-notes-study-agent，导入包是 studyagent，CLI 入口是 study-agent。

study_agent/
├── pyproject.toml                 # Python 版本、依赖与 CLI 入口。
├── uv.lock                        # 同一组解析出的依赖版本。
├── src/studyagent/
│   ├── resources/notes.json       # 随包安装的练习笔记。
│   ├── retrieval.py               # 分块、向量编码与可读材料检索。
│   ├── generation.py              # 提示、解析和引用检查。
│   ├── tool_agent.py              # LangChain 工具循环与回放模型。
│   ├── workflow.py                # 业务状态图、暂停与保存节点。
│   ├── storage.py                 # SQLite 计划与唯一操作编号。
│   ├── service.py                 # 开始、查看、恢复与重试。
│   ├── cli.py                    # 各次独立命令的参数和连接管理。
│   └── web.py                    # FastAPI 身份依赖与路由。
├── demos/                         # 可逐个运行的短例。
└── tests/                         # 检索、工具、恢复、事务和 HTTP 检查。

运行依赖由 pyproject.toml 声明；本章使用 LangChain 1.4.6、LangGraph 1.2.16、SQLite checkpoint 3.1.2 和 text splitters 1.1.3，具体间接依赖以随项目提供的 uv.lock 为准。ollama 是可选扩展；uv 的 --all-extras 安装它，但不会下载模型权重。

2. 用 uv 或 pip 准备环境

# 在 study_agent 目录执行，先核对项目环境与测试。
uv sync --locked --all-extras
uv run python --version
uv run pytest -q
# 每个 demos 文件演示一个独立过程。
uv run python demos/prompt_chain.py
uv run python demos/cosine.py
uv run python demos/tool_round.py
uv run python demos/state_updates.py
uv run python demos/retry_read.py
uv run python demos/evaluate.py
# 逐步核对分块、计数向量、筛选顺序、材料到消息和手动工具交接。
uv run python demos/chunk_walk.py
uv run python demos/keyword_vectors.py
uv run python demos/filter_order.py
uv run python demos/rag_walk.py
uv run python demos/tool_dispatch.py
# 观察节点重入、关闭连接后的恢复，以及业务已提交时的重试。
uv run python demos/node_reentry.py
uv run python demos/checkpoint_walk.py
uv run python demos/crash_retry_walk.py

Windows 使用 pip 路线时：

# 在新目录创建 Python 3.12 的环境，使用该环境的解释器安装项目。
py -3.12 -m venv .venv
.venv\Scripts\python -m pip install -e ".[ollama]" -r requirements-dev.txt
.venv\Scripts\python -m pytest -q
# python -m 入口与安装后的 study-agent 命令对应同一 CLI。
.venv\Scripts\python -m studyagent --data data ask "FastAPI 数据库会话什么时候关闭？" --thread api-1

macOS/Linux 使用 .venv/bin/python。pip 根据项目声明解析依赖；按同一份 uv.lock 重建时使用 uv 路线。两条路线都先在项目根目录运行检查，再离开源码目录测试安装包资源是否能够读取。

3. 沿暂停点核对数据库

首次提问用 --thread numpy-1 --plan，查看 pending 后先运行 plans，应该仍为空；批准后再次查看，得到一行。再用一个新编号 numpy-2 提问，执行 reject，计划表仍只有前一行。关闭终端后重新执行 status 或 plans，读取结果与关闭前一致。

计划表在 data/plans.sqlite3，检查点在 data/checkpoints.sqlite3。备份时先停止相关进程，保留两份数据库及源码、锁定文件；若只带走计划库，可以读正式计划，却无法从丢失的检查点继续尚未确认的任务。