DEPLOYMENT.md

# Hugging Face Spaces 部署说明

## 1. 创建 Space

1. 登录 Hugging Face。
2. 点击 `New Space`。
3. Space 名称可填写 `algorithm-agent` 或课程要求的名称。
4. SDK 选择 `Docker`。
5. Visibility 建议选择 `Public`，这样老师可以直接通过公开链接访问。

## 2. 上传项目文件

上传本目录中的核心文件到 Space 根目录：

- `README.md`
- `Dockerfile`
- `requirements.txt`
- `app.py`
- `server.py`
- `agent_core.py`
- `tools.py`
- `reporting.py`
- `static/index.html`
- `static/styles.css`
- `static/app.js`
- `report/project_report.tex`
- `report/project_report.pdf`

不需要上传：

- `.venv/`
- `__pycache__/`
- `outputs/`
- `.env`
- 本地运行产生的 `.aux`、`.log`、`.out`

## 3. 配置 API Key

不要把 `.env` 明文上传到公开 Space。正确做法是在 Space 中添加 Secret：

1. 打开 Space 的 `Settings`。
2. 进入 `Variables and secrets`。
3. 添加 Secret：

```text
Name: AGNES_API_KEY
Value: 你的 Agnes AI API Key
```

程序会自动从环境变量读取 `AGNES_API_KEY`。老师访问公开 Space 时不需要输入 key，前端也不会显示 key。

## 4. 固定模型与接口

代码中已经固定：

```text
模型: agnes-2.0-flash
接口: https://apihub.agnes-ai.com/v1/chat/completions
```

前端只检测后端是否已经配置 key，不允许用户修改模型或接口地址。

## 5. 本地验证

本地运行：

```bash
python3 -m pip install -r requirements.txt
uvicorn server:app --host 127.0.0.1 --port 7860
```

打开：

```text
http://127.0.0.1:7860
```

如果本地要用 Agnes AI，在项目根目录创建 `.env`：

```text
AGNES_API_KEY=你的 Agnes AI API Key
```

修改 `.env` 后需要重启服务。

## 6. 提交材料

最终提交建议包含：

- Hugging Face Space 公开链接。
- MP4 录屏文件。
- `report/project_report.pdf`。