troubleshooting-assistant

故障排查助手技能

用于识别和解决 Claude Patent Creator 问题的专家诊断系统。

适用场景

系统无法运行、出现错误消息、性能缓慢、MCP 服务未加载、搜索无结果或报错、未检测到 GPU、BigQuery 认证失败、索引构建失败、测试失败或行为异常。

故障排查方法

Problem Reported
  |
[1] Gather Information (errors, recent changes, system state)
  |
[2] Reproduce Issue (minimal test case, consistent?)
  |
[3] Isolate Component (which part failing? dependencies?)
  |
[4] Diagnose Root Cause (check logs, test components, verify config)
  |
[5] Apply Fix (targeted solution, verify works)
  |
[6] Prevent Recurrence (document, add monitoring, update checks)

常见问题与快速修复

问题	快速修复
MCP 服务未加载	claude mcp list -> 如果缺失，请重新注册
未检测到 GPU	重新安装带 CUDA 的 PyTorch
BigQuery 认证失败	gcloud auth application-default login
未找到索引	patent-creator rebuild-index
导入错误	激活虚拟环境：venv\Scripts\activate
搜索速度缓慢	检查 GPU 使用情况，降低 top_k，禁用 HyDE
结果不相关	使用 MPEP 术语重新表述查询

详细问题指南

MCP 服务问题

问题： 服务未加载、工具无法使用或返回错误

• 5 步诊断工作流
• 路径验证与修正
• 依赖项故障排查
• 服务重启流程

GPU 与 BigQuery 问题

问题： 未检测到 GPU、性能缓慢、BigQuery 认证失败、查询超时

• CUDA 检测与 PyTorch 重新安装
• 性能诊断与优化
• BigQuery 认证与权限
• 超时配置

索引、依赖项与配置

问题： 未找到索引、构建失败、ModuleNotFoundError、导入错误、环境变量未加载、搜索结果不相关

• 索引重建流程
• OOM（内存不足）解决方案
• 虚拟环境激活
• Pydantic 验证错误
• 配置故障排查
• 搜索质量调优

诊断工具

健康检查套件

# Full system health
patent-creator health

# Individual components
python scripts/test_gpu.py
python scripts/test_bigquery.py
python scripts/test_analyzers.py
python scripts/test_install.py

组件隔离

# Test MPEP search
python -c "from mcp_server.mpep_search import MPEPIndex; \
           index = MPEPIndex(); index.build_index(); \
           print('OK' if index.search('test', top_k=1) else 'FAILED')"

# Test BigQuery
python -c "from mcp_server.bigquery_search import BigQueryPatentSearch; \
           search = BigQueryPatentSearch(); \
           print('OK' if search.search_by_keywords('neural network', limit=1) else 'FAILED')"

# Test analyzers
python -c "from mcp_server.claims_analyzer import ClaimsAnalyzer; \
           analyzer = ClaimsAnalyzer(); \
           print('OK' if analyzer.analyze('1. A test claim.') else 'FAILED')"

• 日志分析（调试模式）
• MCP 通信调试
• 性能分析
• 内存分析
• 问题升级流程

预防最佳实践

1. 定期进行健康检查（每周运行 patent-creator health）
2. 监控日志中的警告和错误
3. 保持依赖项更新（部署前进行测试）
4. 更改前先备份（尤其是重建索引前）
5. 记录修改内容
6. 更改后进行测试（运行测试套件）
7. 使用版本控制（使用 git）
8. 保持环境一致（使用相同的 Python/CUDA 版本）

快速参考

最常见的错误

错误	类别	解决方案
"Tool not found"	MCP	claude mcp list
"ModuleNotFoundError"	依赖项	激活虚拟环境并重新安装
"CUDA not available"	GPU	重新安装带 CUDA 的 PyTorch
"Permission denied"（BigQuery）	认证	gcloud auth application-default login
"Index not found"	索引	patent-creator rebuild-index
"Out of memory"	索引构建	减小批次大小
"Validation error"	输入	检查 Pydantic 模型参数

诊断命令

# System health
patent-creator health

# Test components
python scripts/test_gpu.py
python scripts/test_bigquery.py
python scripts/test_install.py

# Check registration
claude mcp list

# Check paths
patent-creator verify-config

# Enable debug logging
export PATENT_LOG_LEVEL=DEBUG