projects/repobot/v3/README.md

# RepoBot v3

httpx 答疑助手的第三版，对应课程 [05 模块第 9 课](../../../05-agents/09-project-repobot-v3.md)。

## 和 v2 相比

v2 是一个固定流程：改写问题、检索文档、回答。文档里没有的东西，它就答不上来，比如 httpx 默认最多跟随几次重定向，这个数字只在源码里。

v3 是一个智能体，有四个工具：

- `search_docs`：在文档里做混合检索（沿用 v2 的检索）
- `read_doc`：按行读文档文件
- `grep_source`：在 httpx 源码里搜索
- `read_source`：按行读源码文件

它自己决定先查文档还是翻源码、查几次、什么时候可以回答。回答里注明依据，文档写成 `[文档 文件名]`，源码写成 `[源码 文件路径:行号]`。

## 文件

- `repobot.py`：命令行对话程序
- `agent.py`：智能体循环
- `tools.py`：四个工具，以及第一次运行时下载源码
- `retrieval.py`、`llm.py`：沿用 v2
- `eval_agent.py`：8 道题的评估，其中 5 道的答案只在源码里

## 运行

需要 Python 3.10 以上和 git，并按[第 00 模块第 2 课](../../../00-start/02-setup.md)设置好 `LLM_API_KEY`、`LLM_BASE_URL`、`LLM_MODEL` 三个环境变量。

```bash
pip install -r requirements.txt
export HF_ENDPOINT=https://hf-mirror.com   # 国内下载模型慢时使用镜像
python repobot.py
```

第一次运行会用 git 把 httpx 的源码克隆到 `.cache/httpx`，并下载嵌入模型。想用已有的源码目录，设置环境变量 `REPOBOT_SOURCE`。

不想看每一步的工具调用：

```bash
python repobot.py --quiet
```

评估：

```bash
python eval_agent.py
```

## 安全

`read_doc` 和 `read_source` 只能读文档目录和源码目录里的文件，传入 `../` 之类跳出目录的路径会被拒绝。v3 的工具都是只读的，没有任何能修改文件、发送消息的工具。