Imported from wdd9700/ResearchMap (AGENTS.md). Install upstream with npx skills add wdd9700/ResearchMap. Copyright stays with the author.

ResearchMap Agent — AI Agent Instructions

Agent Decision Checklist

当用户请求涉及以下场景时，按此优先级行动：

1. 运行/测试/验证 → 使用 Quick Commands。
2. 调研新领域 → 调用工作流：search_research → graph_update → tree_update → timeline_update → export_all_structures。
3. 修改 Open WebUI 工具 → 只改 open_webui_tools/researchmap_agent_tools.py，保持 class Tools 顶层定义和 async 方法签名。
4. 修改前端面板 → 只改 web/researchmap_live.html；辅助脚本 scripts/_rewrite_ui.py / scripts/fix_rewrite.py 仅用于手动覆盖，不加入主流程。
5. 安装到 Open WebUI → 使用 scripts/install_open_webui_researchmap.py，注意硬编码路径需用 --open-webui-root 覆盖。

Quick Commands

演示输出写入 artifacts/demo_output.md 和 state/demo_state.json。

Architecture

open_webui_tools/researchmap_agent_tools.py   # Open WebUI Tool：class Tools + 状态/导出函数
scripts/run_demo.py                           # 命令行演示脚本
scripts/researchmap_demo_server.py            # 本地 HTTP + SSE 演示服务器
scripts/install_open_webui_researchmap.py     # 直接写入本地 Open WebUI SQLite 的安装脚本
web/researchmap_live.html                     # 三栏实时演示面板（原生 JS + SSE）
SYSTEM_PROMPT.md                              # 给 LLM 的系统提示词
DEMO_PROMPTS.md                               # 三段演示 prompt 与示例载荷
tests/test_researchmap_agent_tools.py         # 核心工具 unittest 测试
tests/test_researchmap_demo_server.py         # 演示服务器纯函数测试

所有工具都是 Tools 类的 async 方法，通过 __event_emitter__ 发送 status 事件。工具调用规则详见 SYSTEM_PROMPT.md。

Key Conventions

ID Slugging

• 节点、边、事件、树节点的 ID 都会被规范化：小写、非字母数字替换为 _、去首尾下划线。
• 新增节点/边/路径时，优先用显式 id；否则从 label 自动生成 slug。
• 深潜和删除时，传入 label 也能匹配（会先 slug 化再查找）。

State Management

• 状态是一个 JSON 对象，包含 project_id、graph、tree、timeline、sources、node_details。
• sources 缓存 search_research 返回的论文/网页元数据；node_details 缓存 node_deep_dive 生成的结构化解释。
• 每次更新后自动调用 _save_state；state_path 优先从环境变量 RESEARCHMAP_STATE_PATH 读取，否则用 valves。
• 如果 JSON 损坏，会备份为 .broken 并重建空状态；_normalize_state 会补全缺省字段以保证向后兼容。

Graph

• 节点类型限定为 paper、method、concept、dataset、benchmark、claim；非法类型会回退为 concept。
• 边关系限定为 depends_on、improves、influences、uses、contrasts、extends、replaces、applies_to。
• 添加边时若端点不存在，会自动创建占位节点。
• 删除节点会级联删除相关边。

Tree

• 多叉树节点包含 id、label、children、parent_id、可选 description/examples/source_ids/details。
• add_path 会按路径逐级创建缺失节点；如果根节点 label 与路径首项冲突，会自动插入 ResearchMap 作为新根。
• move_node 会先 detach 再挂载到新父节点；不能移动根节点。

Timeline

• 事件必须包含 time；支持 2017、2020-06、2021/12 等格式，内部用正则提取 4 位数年份排序。
• 每次 add_event(s) / update_event 后会按年份重新排序。
• 事件 ID 默认由 {time}-{title} slug 化生成。

Deep Dive

• node_deep_dive 是真实 subagent 行为：根据节点 label + year + 别名构造多查询，并行检索 arXiv / Semantic Scholar / OpenAlex。
• 别名表覆盖常见缩写：ViT→"An Image is Worth 16x16 Words"、Transformer→"Attention Is All You Need"、BERT/T5/ResNet/CLIP/Swin/MAE/DiT 等。
• 按优先级选最佳结果：年份+别名标题匹配 > 年份+label 子串 > 年份 > label 子串 > 首个结果。
• 检索命中后用真实论文标题/作者/年份/URL/摘要生成核心贡献；结合图/树/时间线上下文生成位置感知解释。
• 三个 API 全失败时回退到结构上下文解释，paper_info.retrieved_from 标记为"结构上下文（公开 API 暂未返回结果）"。
• 结果同时写回 state["node_details"][node_id] 和对应 graph/tree 节点上的 details 字段。

Search

• search_research 默认并行查询 arXiv / Semantic Scholar / OpenAlex 三个公开 API，无需 API key。
• 查询结果按年份、摘要、作者、引用数打分去重排序，缓存在 state/sources。
• 磁盘缓存于 .researchmap_search_cache.json，避免重复请求和 429 限流；只缓存非空结果。
• 三个 API 全失败时返回空列表并提示换关键词；source_type="mock" 或 use_mock_search=True 同样返回空列表并提示换关键词。
• 搜索只缓存 sources，不会更新 graph/tree/timeline；调用后需要继续抽取并调用对应更新工具。

Web 演示服务器

• GET /：返回 web/researchmap_live.html。
• GET /api/state：返回当前 state + 三段 Mermaid 字符串。
• POST /api/reset：重置项目状态。
• GET /api/agent/stream?q=...：SSE 流，事件类型包括 status、snapshot、message、deep_dive、done。
• 请求分流：含"深潜/deep/dive" → 深潜流；纯树请求 → 只建树；其他 → 搜索→建图→建树→建时间线。
• 服务器内置主题清洗与查询扩展（如视觉 Transformer、字节级 tokenizer、遥感多模态等），用于课程演示。

Tool Calling Workflow

当用户要求调研新领域时：

1. search_research(query, top_k=10) 获取材料。
2. graph_update(action="add_edges", nodes=[...], edges=[...]) 更新研究关系图。
3. tree_update(action="add_path", path=[...]) 更新研究谱系树。
4. timeline_update(action="add_events", events=[...]) 更新时间线。
5. export_all_structures() 或读取工具返回的 Mermaid 汇总结果。

Mermaid Export

• export_graph_mermaid → flowchart TD
• export_tree_mermaid → mindmap
• export_timeline_mermaid → timeline
• 所有导出函数接受完整 state dict 并返回字符串。

Common Pitfalls

• 不要在 _load_state 返回的状态上直接修改后忘记 _save_state；工具方法中已统一处理。
• 新增 graph 边时端点可以自动创建，但不要依赖自动创建的占位节点做精确展示，最好显式传入 nodes。
• 树的根节点冲突时会自动包一层 ResearchMap，这在演示中常见，不需要修复。
• 测试使用临时目录：不要覆盖 state/demo_state.json 作为测试文件；test_researchmap_agent_tools.py 已使用临时目录。
• search_research 只更新 sources，不会自动更新 graph/tree/timeline，必须继续调用对应更新工具。
• node_deep_dive 依赖公网 API，离线或限流时 paper_info.retrieved_from 会回退到结构上下文。
• Mermaid 中文标签：已做 " 转义和换行处理，但复杂换行仍可能破坏语法。
• 安装脚本路径硬编码：scripts/install_open_webui_researchmap.py 的 DEFAULT_OPEN_WEBUI_ROOT 指向本地路径，其他机器必须用 --open-webui-root 覆盖。
• 没有依赖清单：仓库缺少 requirements.txt / pyproject.toml，新环境需手动安装 requests。

Integration Notes

• Open WebUI 导入：复制 open_webui_tools/researchmap_agent_tools.py 完整内容到 Workspace Tool。
• Docker 中建议把 valves state_path 设为 /app/backend/data/researchmap_state.json。

Documentation Links

• README.md — 项目概览、接入方式、文件结构。
• SYSTEM_PROMPT.md — LLM 系统提示词与工具调用规则。
• DEMO_PROMPTS.md — 演示 prompt 与示例载荷。