FastMCP × PydanticAI 研究代理
一个使用PydanticAI的对话式ReAct风格研究代理，它连接到一个MCP HTTP服务器（FastMCP），用于开放网络风格的工具：搜索、获取、笔记记忆和PII（个人可识别信息）保护。该代理生成结构化的研究简报，包含数字引用、简短引文和持久日志。
特点/特性
- 带有MCP工具调用（搜索、获取、笔记、守卫）的ReAct决策循环
- 从抓取的页面中清理并提取片段
- 撰写5至8段的简短文章，并在文中直接标注数字编号的引用\[n\]
- 确保至少2条简短引语（每条不超过10个字）
- 参考文献部分映射\[n\]到标题+网址（≥3个不同域名）
- PII（个人可识别信息）保护检查；若标记则创建HITL（人工在环测试）工单
- 日志文件：search_results.json（搜索结果.json）、selected_urls.json（选中网址.json）、snippets.json（片段.json）
- 持久化存储 SQLite 内存（notes.sqlite）
快速入门
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -U pip
pip install -r requirements.txt
Copy-Item .env.example .env # then edit OPENAI_API_KEY if you have one运行（确保 MCP_HTTP_URL 指向一个正在运行的 MCP HTTP 服务器组件或开发服务器）：
python -m student.run --topic "US semiconductor export controls (2024–2025) overview" --out artifacts可选：运行本地开发MCP存根
启动存根服务器（在另一个终端中）：
python -m student.dev_server然后在运行代理之前，在你的shell中进行设置：
$env:MCP_HTTP_URL="http://127.0.0.1:8765"写入输出目录的工件：
- brief.md（除非标记为PII）
- report.json（包含 pii_flagged 布尔值）
- search_results.json 翻译为中文是：“搜索结果.json”
- selected_urls.json 翻译为中文是：“选定的URL列表.json”
- snippets.json 翻译成中文是：“代码片段.json”
- notes.sqlite（或已更新）
- hitl_ticket.json（仅当PII被标记时）
- reflection.txt（单篇600-700字的反思，生成一次）
环境变量
- OPENAI_API_KEY（如果模型已存根，则在评分时可选）
- OPENAI_MODEL（默认：openai:gpt-4o-mini）
- MCP_HTTP_URL（必需）：MCP HTTP服务器的基础URL
- ASSIGNMENT_MODE（可选）：dev（开发）或 grading（评分）
开发说明
如果你没有真实的MCP服务器，我们稍后会添加一个最小的存根用于本地测试。评分系统会提供其自己的确定性MCP。
反思：在成功运行非个人身份信息（PII）任务后，若未手动指定，则自动生成名为reflection.txt的文件。
安全
请不要提交真实的API密钥（.env文件已被git忽略）。撤销任何你公开粘贴的密钥。
许可证
教育任务支架（或教学任务脚手架）。