ResearchMap Agent

基于 Open WebUI 工具调用的科研调研地图生成系统。它把 LLM 的调研过程沉淀为三类数据结构：

• 有向图 Graph：论文、方法、概念之间的依赖、影响、改进、对比、迁移关系。
• 多叉树 Tree：领域、技术路线、方法体系之间的分类和层级关系。
• 时间线性表 Timeline：研究方向的历史演进和阶段变化。

当前版本是最小可交付实现：Python 单文件 Open WebUI Tool、JSON 临时状态、真实学术 API 搜索（arXiv / Semantic Scholar / OpenAlex，无需 API key）、Mermaid 导出、节点位置感知深潜（subagent 真实检索原论文元数据）、演示脚本和单元测试。

文件结构

open_webui_tools/researchmap_agent_tools.py   Open WebUI 工具文件
SYSTEM_PROMPT.md                              ResearchMap Agent 系统提示词
DEMO_PROMPTS.md                               三段演示 prompt 和示例载荷
AGENTS.md                                     AI Agent 项目速查与决策清单
scripts/run_demo.py                           本地演示脚本
scripts/researchmap_demo_server.py            本地 HTTP + SSE 演示服务器
scripts/install_open_webui_researchmap.py     直接写入本地 Open WebUI SQLite 的安装脚本
web/researchmap_live.html                     三栏实时演示面板
tests/test_researchmap_agent_tools.py         核心工具 unittest 测试
tests/test_researchmap_demo_server.py         演示服务器纯函数测试

依赖

当前仓库没有 requirements.txt / pyproject.toml，请手动安装：

pip install requests

pydantic 由 Open WebUI 环境提供；代码内部已对缺失情况做降级兼容。

Open WebUI 接入

Open WebUI 官方文档要求 Workspace Tools 写成一个 Python 文件，并在顶层定义 class Tools；工具方法应带类型注解，推荐使用 async 函数。将 open_webui_tools/researchmap_agent_tools.py 作为 Workspace Tool 导入即可。

当前机器上的 Open WebUI 位于：

http://127.0.0.1:3000

本仓库提供了直接写入当前 Open WebUI SQLite 数据库的安装脚本。脚本中的 DEFAULT_OPEN_WEBUI_ROOT 指向本地路径，在其他机器上请用 --open-webui-root 覆盖：

python scripts\install_open_webui_researchmap.py --open-webui-root <你的 open_webui 包路径>

例如（仅供参考，请按实际环境修改）：

E:\projects\LearningEnvironment\exampilot\.venv-openwebui\Scripts\python.exe scripts\install_open_webui_researchmap.py

脚本会 upsert：

• Tool：researchmap_agent_tools
• Model/Agent：researchmap-agent
• Agent 名称：ResearchMap Agent
• Base model：默认复用当前 Open WebUI 里的 kimi-k2.7-code-highspeed
• Tool state：F:\Projects\ResearchGraph\state\open_webui_researchmap_state.json

推荐步骤：

1. 启动 Open WebUI。
2. 进入 Workspace / Tools，新建或导入工具。
3. 粘贴 open_webui_tools/researchmap_agent_tools.py 的完整内容并保存。
4. 新建 Model/Agent，系统提示词使用 SYSTEM_PROMPT.md。
5. 给该 Agent 启用 ResearchMap Agent Tools。
6. 在聊天中运行 DEMO_PROMPTS.md 中的三个演示。

如果 Open WebUI 跑在 Docker 中，建议把工具 Valve state_path 设置为：

/app/backend/data/researchmap_state.json

这样 JSON 状态会持久化在 Open WebUI 数据目录。

工具列表

• search_research(query, top_k, source_type)：并行查询 arXiv / Semantic Scholar / OpenAlex，返回论文/网页材料并缓存到 sources，不直接更新结构。失败时回退到结构上下文。本地缓存于 .researchmap_search_cache.json。
• graph_update(action, nodes, edges, ...)：维护有向图，支持节点和边的增删改查。
• tree_update(action, path, node, ...)：维护多叉树，支持路径插入、节点增删改移。
• timeline_update(action, event, events, ...)：维护按时间排序的线性表。
• node_deep_dive(node_id, query)：读取节点在图/树/时间线中的结构上下文，并真实检索原论文元数据（arXiv/S2/OpenAlex）；工具侧生成结构化深潜草稿并写回节点。在 Open WebUI 对话里，最终表述由模型基于该工具结果继续组织。
• export_all_structures()：导出三张 Mermaid 图。
• reset_project(project_id)：重置临时状态。
• save_project_state() / load_project_state()：查看当前 JSON 状态。

本地验证

运行单元测试：

python -m unittest discover -s tests

生成演示输出：

python scripts/run_demo.py --scenario deep-dive

输出文件：

artifacts/demo_output.md
state/demo_state.json

启动实时交互面板：

python scripts/researchmap_demo_server.py --host 127.0.0.1 --port 8787 --state state/web_demo_state.json

可通过环境变量指定状态文件：

set RESEARCHMAP_STATE_PATH=state/my_state.json
python scripts/researchmap_demo_server.py

打开：

http://127.0.0.1:8787

实时面板支持：

• 左侧窄栏嵌入 Open WebUI，并保留完整 Open WebUI 打开按钮；
• 底部固定输入框直接驱动结构生成；
• SSE 逐步推送搜索、抽取、建图、建树、更新时间线状态；
• 中间主工作区同时展示 Graph / Tree / Timeline；
• 右侧展示 deep dive 和任务状态 / JSON；
• Graph / Tree / Timeline 节点点击；
• 点击节点后触发 node_deep_dive，并把 deep dive 结果写回节点 details。

注意：8787 面板是课程演示用 sidecar。它直接调用本项目工具，调研请求会先走真实 search_research，再根据返回材料实时生成节点、候选关系、树路径和时间事件；Open WebUI 中的 ResearchMap Agent 才是完整的大模型工具调用链路。

课程答辩主线

本项目把科研调研过程抽象为三类数据结构维护问题：

第一，研究方法之间存在依赖、影响、改进和对比关系，因此用有向图表示，并用邻接关系和节点哈希表支持快速查找与更新。

第二，研究领域和技术路线具有分类和层级归属关系，因此用多叉树表示，并维护父子指针、路径插入、节点移动和子树删除。

第三，研究方向存在明确的历史演进过程，因此用按时间排序的线性表表示，每次插入或更新后按年份重新排序。

系统通过 LLM 工具调用完成对图、树和时间线性表的增删改查，并在每次更新后导出 Mermaid。节点深潜进一步把图、树、时间线的上下文组合成位置感知解释。

取舍

• 搜索默认并行查询 arXiv / Semantic Scholar / OpenAlex 三个公开 API，无需 API key；磁盘缓存于 .researchmap_search_cache.json 避免重复请求和限流。
• 节点深潜是真实 subagent 行为：根据节点 label + year + 别名多查询检索原论文，按年份和标题匹配度选最佳结果；三个 API 全失败时回退到结构上下文解释。
• 前端实时动效先用 Open WebUI 的 status 事件和 Mermaid 返回实现。
• 真正点击事件、后台队列、PDF 解析和独立可视化面板留到后续版本。