README.md

---
title: General Algorithm Problem Solving Agent
sdk: docker
app_port: 7860
---

# 通用问题优化与算法求解智能体

这是一个面向“高级算法设计与应用”课程大作业的可部署智能体项目。它基于公开可访问的大模型 API（如 Agnes AI、GPT、Claude、通义千问等 OpenAI-compatible 服务）和轻量工具调用，实现通用算法问题的结构化、算法范式检索、脚本验证、结果评估和 PDF 报告生成。

## 功能

- 输入自然语言算法问题。
- 展示 Memory、Planner、Retriever、Executor、Script Runner、Evaluator、Loop Controller、Reflector、Artifact Writer 的完整流程。
- 通过 SSE 流式展示每一步 Agent 输出。
- Retriever 使用内置算法范式知识库，不需要上传文件，不做 RAG。
- Executor 调用公开 LLM 生成算法设计和可选 Python 验证脚本。
- Script Runner 只运行轻量验证脚本，不再为每个题型硬编码专用求解器。
- 生成详细 LaTeX 源码和 PDF 求解报告。
- 自定义 HTML/CSS/JS 前端，可通过 Docker 部署到 Hugging Face Spaces。

## 本地运行

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

打开 `http://127.0.0.1:7860`。

## Agnes AI API 配置

应用固定使用 Agnes AI 的 `agnes-2.0-flash` 模型和 `https://apihub.agnes-ai.com/v1/chat/completions` 接口。推荐在 Hugging Face Spaces 的 `Settings -> Variables and secrets` 中添加：

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

本地演示时也可以复制 `.env.example` 为 `.env`，写入 `AGNES_API_KEY` 后重启服务。前端不会显示或上传 Key，只会检测后端是否已经配置。如果不配置 API，应用会使用离线算法范式模板进行演示；要获得真正通用的问题求解效果，需要配置公开 LLM API。

## Hugging Face Spaces 部署

详细步骤见 `DEPLOYMENT.md`。核心流程如下：

1. 登录 Hugging Face。
2. 创建新的 Public Space。
3. Space SDK 选择 `Docker`。
4. 将本项目中的核心文件上传到 Space 根目录：
   - `server.py`
   - `agent_core.py`
   - `tools.py`
   - `reporting.py`
   - `static/index.html`
   - `static/styles.css`
   - `static/app.js`
   - `requirements.txt`
   - `README.md`
   - `Dockerfile`
   - `report/project_report.tex`
   - `report/project_report.pdf`
   - `DEPLOYMENT.md`
   - `VIDEO_SCRIPT.md`
5. 在 Space 的 Secrets 中配置 `AGNES_API_KEY`。
6. 等待 Space 自动构建完成，获得公开访问链接。

不要把 `.env` 明文上传到公开 Space。把 key 放在 Space 的 `Settings -> Variables and secrets` 中，老师访问页面时同样不需要输入 key。

## 录制 MP4 建议

讲稿见 `VIDEO_SCRIPT.md`。建议录制 3 到 6 分钟：

1. 打开 Hugging Face Space 公开链接。
2. 展示页面结构、固定模型和 API 状态。
3. 输入报告中的样例最短路径问题并点击运行。
4. 展示结构化问题、算法范式检索、LLM 求解、脚本验证、评估修订和最终答案。
5. 点击下载并打开 PDF 报告。
6. 说明该智能体不是固定题解，而是通用算法问题求解 Agent。

macOS 可用 QuickTime Player 或系统截图工具录屏，Windows 可用 Xbox Game Bar，跨平台可用 OBS Studio。