Troubleshooting Assistant Skill
一、用途
这是 Claude Patent Creator 的专家诊断系统，用于识别并解决该工具运行中出现的各类故障。当系统无法正常工作、出现错误信息、性能缓慢、MCP 服务器无法加载、搜索无结果或报错、GPU 未检测、BigQuery 认证失败、索引构建失败、测试失败或出现异常行为时使用。
二、排查方法
采用六步流程：
- 收集信息（错误、近期变更、系统状态）
- 复现问题（最小测试用例，是否可稳定复现）
- 隔离组件（哪一部分失败？依赖项如何？）
- 诊断根因（检查日志、测试组件、验证配置）
- 应用修复（针对性方案，验证有效）
- 防止复发（记录、增加监控、更新检查）
三、常见问题与快速修复
- 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 服务器问题：服务器未加载、工具不可用或返回错误；提供五步诊断流程、路径验证与纠正、依赖排查、服务器重启步骤。
- GPU 与 BigQuery 问题：GPU 未检测、性能慢、BigQuery 认证失败、查询超时；涵盖 CUDA 检测与 PyTorch 重装、性能诊断与优化、BigQuery 认证与权限、超时配置。
- 索引、依赖与配置问题：索引未找到、构建失败、ModuleNotFoundError、导入错误、环境变量未加载、搜索结果不相关；涵盖索引重建、内存不足（OOM）解决方案、虚拟环境激活、Pydantic 校验错误、配置排查、搜索质量调优。
五、诊断工具
健康检查套件：
完整系统健康检查
patent-creator health
各组件单独测试
python scripts/test_gpu.py python scripts/test_bigquery.py python scripts/test_analyzers.py python scripts/test_install.py
组件隔离测试：
测试 MPEP 搜索
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')"
测试 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')"
测试分析器
python -c "from mcp_server.claims_analyzer import ClaimsAnalyzer;
analyzer = ClaimsAnalyzer();
print('OK' if analyzer.analyze('1. A test claim.') else 'FAILED')"
此外还包含日志分析（调试模式）、MCP 通信调试、性能分析、内存分析、问题上报流程。
六、预防最佳实践
- 定期健康检查（每周运行 patent-creator health）
- 监控日志中的警告与错误
- 保持依赖更新（部署前先测试）
- 变更前备份（尤其是索引重建）
- 记录修改内容
- 变更后测试（运行测试套件）
- 版本控制（使用 git）
- 环境一致性（相同的 Python/CUDA 版本）
七、快速参考
最常见错误及对应方案：
- "Tool not found" → MCP 类 → claude mcp list
- "ModuleNotFoundError" → 依赖类 → 激活 venv 并重新安装
- "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 模型参数
诊断命令：
系统健康
patent-creator health
测试组件
python scripts/test_gpu.py python scripts/test_bigquery.py python scripts/test_install.py
检查注册
claude mcp list
检查路径
patent-creator verify-config
启用调试日志
export PATENT_LOG_LEVEL=DEBUG