projects/repobot/v4/README.md

# RepoBot v4

httpx 答疑助手的第四版，也是第一部分的最终版，对应课程 [06 模块第 6 课](../../../06-production/06-project-repobot-v4.md)。

## 和 v3 相比

v3 是一个命令行程序。v4 把它变成一个可以放到网上给别人用的网页服务：

- **网页界面和接口**：`POST /api/chat` 返回流式事件（SSE），前端一边接收一边显示，还能看到它正在调用哪个工具。
- **输入护栏**：问题先经过一个分类器，和 httpx 无关的、试图越权的，直接返回固定回复，不交给智能体。
- **输出护栏**：回答发出之前，遮住看起来像密钥、token、手机号的内容。流式输出按整行检查。
- **日志**：每个请求、每次模型调用、每次工具调用都记在 `logs/traces.jsonl` 里。
- **输入校验**：问题最长 2000 字，历史最多 10 条，历史里只允许 user 和 assistant 两种角色。

## 文件

- `server.py`：FastAPI 服务
- `agent.py`：流式版的智能体循环
- `guard.py`：输入护栏和输出护栏
- `tracing.py`：追踪日志
- `tools.py`、`retrieval.py`、`llm.py`：沿用 v3
- `static/index.html`：网页
- `Dockerfile`：容器镜像

## 在本机运行

需要 Python 3.10 以上和 git，并设置好 `LLM_API_KEY`、`LLM_BASE_URL`、`LLM_MODEL` 三个环境变量。

```bash
pip install -r requirements.txt
export HF_ENDPOINT=https://hf-mirror.com
uvicorn server:app --host 127.0.0.1 --port 8000
```

启动时会加载模型、下载源码（第一次），等 `curl http://127.0.0.1:8000/healthz` 返回 `{"ok":true}` 之后，用浏览器打开 `http://127.0.0.1:8000`。

用 curl 直接调接口：

```bash
curl -N -X POST http://127.0.0.1:8000/api/chat \
  -H 'Content-Type: application/json' \
  -d '{"message": "httpx 默认最多跟随几次重定向？", "history": []}'
```

## 部署

课程里讲了两种方式：用 Docker，或者直接在一台 Linux 服务器上用 systemd 运行。详见第 6 课。

Dockerfile 要在 `AI-Course` 目录下构建，因为它需要复制 `data/httpx-docs`：

```bash
docker build -f projects/repobot/v4/Dockerfile -t repobot .
docker run -p 8000:8000 -e LLM_API_KEY=你的密钥 repobot
```

说明：写课时的机器上没有 Docker，这个 Dockerfile 没有实际构建过。本机运行（上面的 uvicorn 方式）是真实测试过的。

## 上线前要补的

这个版本适合给小范围的用户试用。正式对外开放之前，至少还要：

- 加上身份验证或者按 IP 限流，防止被人刷接口、刷光你的 API 余额。
- 在前面放一个反向代理（比如 Nginx、Caddy），负责 HTTPS。
- 定期查看 `logs/traces.jsonl`，并设置日志的保留期限。