FEATURE_DIAGNOSIS.md

功能诊断指南

🔍 问题：新增功能无法使用

如果您发现Graph View和摘要高亮功能无法使用，请按照以下步骤诊断：

✅ 第一步：检查代码是否已更新

1. 确认文件已更新

检查 static/index.html 是否包含新功能：

# 检查Graph View相关的代码
grep -n "Graph View\|tab-graph\|graph-view" static/index.html

# 检查摘要高亮相关的代码
grep -n "highlighted_snippet" static/index.html

应该看到：

• Tab导航按钮
• Graph View容器
• 摘要高亮处理代码

2. 检查后端API

# 检查Graph API
grep -n "/api/search/graph" web_server.py

# 检查摘要高亮
grep -n "generate_highlighted_snippet\|highlighted_snippet" search_engine.py

🚀 第二步：重启服务器

重要：代码更改后必须重启服务器！

停止旧服务器

# 查找运行中的服务器进程
ps aux | grep "web_server.py\|uvicorn"

# 停止服务器（替换PID）
kill <PID>

启动新服务器

cd /Users/papersiii/tum-search
python3 web_server.py --mode user --port 8000

🌐 第三步：清除浏览器缓存

方法1：硬刷新

• Windows/Linux: Ctrl + Shift + R
• Mac: Cmd + Shift + R

方法2：清除缓存

1. 打开浏览器开发者工具（F12）
2. 右键点击刷新按钮
3. 选择"清空缓存并硬性重新加载"

方法3：使用无痕模式

在新无痕窗口中打开：

http://localhost:8000/

🔎 第四步：检查功能是否出现

测试Graph View

1. 搜索任意关键词（如 "TUM"）
2. 查看搜索结果区域上方 - 应该看到两个Tab：
   • ✅ "List View" (列表视图)
   • ✅ "Graph View" (网络图视图)
3. 点击 "Graph View" Tab - 应该显示网络图

测试摘要高亮

1. 搜索任意关键词（如 "TUM"）
2. 查看搜索结果卡片中的摘要文本
3. 关键词应该以青色加粗显示

🐛 常见问题排查

问题1：看不到Graph View Tab

可能原因：

• 浏览器缓存了旧页面
• 服务器没有重启
• 访问了错误的URL

解决方案：

1. 确认访问 http://localhost:8000/（根路径）
2. 硬刷新页面（Ctrl+Shift+R）
3. 检查浏览器控制台是否有错误

问题2：摘要高亮不显示

可能原因：

• 搜索结果中没有 highlighted_snippet 字段
• 关键词在文本中不存在
• HTML渲染问题

检查方法：

1. 打开浏览器开发者工具（F12）
2. 切换到 Network 标签
3. 执行搜索
4. 点击 /api/search?q=... 请求
5. 查看响应中的 results 数组
6. 检查第一个结果是否有 highlighted_snippet 字段

问题3：Graph View为空或报错

可能原因：

• ECharts库未加载
• 网络图数据为空
• JavaScript错误

检查方法：

1. 打开浏览器控制台（F12）
2. 查看是否有JavaScript错误
3. 检查是否加载了ECharts：

   typeof echarts !== 'undefined'
   

4. 检查API响应：

   fetch('/api/search/graph?q=TUM').then(r => r.json()).then(console.log)
   

🔧 手动测试步骤

测试1：检查后端API

# 启动服务器后，测试搜索API
curl "http://localhost:8000/api/search?q=TUM" | python3 -m json.tool | head -50

# 检查是否包含highlighted_snippet字段
curl "http://localhost:8000/api/search?q=TUM" | grep -o "highlighted_snippet" | head -1

测试2：检查Graph API

# 测试Graph API
curl "http://localhost:8000/api/search/graph?q=TUM&max_nodes=10" | python3 -m json.tool

应该返回包含 nodes 和 edges 的JSON数据。

测试3：浏览器控制台测试

在浏览器控制台中输入：

// 检查Tab元素是否存在
document.getElementById('tab-graph')

// 检查Graph容器是否存在
document.getElementById('graph-container')

// 检查ECharts是否加载
typeof echarts

// 测试Graph API
fetch('/api/search/graph?q=TUM').then(r => r.json()).then(data => {
    console.log('节点数量:', data.nodes?.length);
    console.log('边数量:', data.edges?.length);
})

📝 功能确认清单

Graph View功能

• 搜索后能看到两个Tab（List View和Graph View）
• 点击Graph View Tab后能显示网络图
• 网络图中有节点和连线
• 中心节点是青色，相关节点是紫色
• 点击节点可以跳转到详情页

摘要高亮功能

• 搜索结果中的关键词被加粗显示
• 关键词是青色（cyan-400）
• 关键词有半透明背景
• 多个关键词都会被高亮

🆘 如果仍然无法使用

检查清单

1. ✅ 服务器已重启

   ps aux | grep web_server
   

2. ✅ 访问正确的URL

   • http://localhost:8000/ ✅
   • http://localhost:8000/static/index.html ✅

3. ✅ 浏览器缓存已清除

   • 使用无痕模式测试

4. ✅ 检查服务器日志

   • 查看终端输出是否有错误

5. ✅ 检查浏览器控制台

   • 按F12打开开发者工具
   • 查看Console标签的错误信息

获取帮助信息

如果仍然无法解决，请提供以下信息：

1. 服务器日志（终端输出）
2. 浏览器控制台错误（F12 → Console）
3. 网络请求响应（F12 → Network → 查看 /api/search 响应）
4. 访问的URL

🔄 快速修复步骤

# 1. 停止服务器
pkill -f "web_server.py"

# 2. 确认代码已更新
git status
git log --oneline -3

# 3. 清除浏览器缓存（在浏览器中操作）

# 4. 重启服务器
cd /Users/papersiii/tum-search
python3 web_server.py --mode user --port 8000

# 5. 在无痕窗口中访问
# http://localhost:8000/

📚 相关文件位置

• 前端代码：static/index.html

  • Graph View: 第193-222行
  • 摘要高亮: 第938-999行

• 后端API：

  • Graph API: web_server.py 第223-370行
  • 搜索API: web_server.py 第218-221行
  • 摘要高亮: search_engine.py 第226-241行