gpt-researcher

GPT Researcher 开发技能

GPT Researcher 是一个基于大模型的自主 Agent，采用规划者-执行者-发布者模式，并通过并行化的 Agent 工作来提升速度与可靠性。

快速开始

基础 Python 用法

from gpt_researcher import GPTResearcher
import asyncio

async def main():
    researcher = GPTResearcher(
        query="What are the latest AI developments?",
        report_type="research_report",  # or detailed_report, deep, outline_report
        report_source="web",            # or local, hybrid
    )
    await researcher.conduct_research()
    report = await researcher.write_report()
    print(report)

asyncio.run(main())

运行服务

# Backend
python -m uvicorn backend.server.server:app --reload --port 8000

# Frontend
cd frontend/nextjs && npm install && npm run dev

---

关键文件位置

需求	主要文件	关键类
主编排器	gpt_researcher/agent.py	GPTResearcher
研究逻辑	gpt_researcher/skills/researcher.py	ResearchConductor
报告撰写	gpt_researcher/skills/writer.py	ReportGenerator
所有提示词	gpt_researcher/prompts.py	PromptFamily
配置	gpt_researcher/config/config.py	Config
配置默认值	gpt_researcher/config/variables/default.py	DEFAULT_CONFIG
API 服务	backend/server/app.py	FastAPI app
搜索引擎	gpt_researcher/retrievers/	各类检索器

---

架构概览

User Query → GPTResearcher.__init__()
                │
                ▼
         choose_agent() → (agent_type, role_prompt)
                │
                ▼
         ResearchConductor.conduct_research()
           ├── plan_research() → sub_queries
           ├── For each sub_query:
           │     └── _process_sub_query() → context
           └── Aggregate contexts
                │
                ▼
         [Optional] ImageGenerator.plan_and_generate_images()
                │
                ▼
         ReportGenerator.write_report() → Markdown report

详细架构图：参见 references/architecture.md

---

核心模式

添加新功能（8 步模式）

1. 配置 → 添加到 gpt_researcher/config/variables/default.py
2. Provider → 在 gpt_researcher/llm_provider/my_feature/ 中创建
3. Skill → 在 gpt_researcher/skills/my_feature.py 中创建
4. Agent → 集成到 gpt_researcher/agent.py
5. 提示词 → 更新 gpt_researcher/prompts.py
6. WebSocket → 通过 stream_output() 发送事件
7. 前端 → 在 useWebSocket.ts 中处理事件
8. 文档 → 创建 docs/docs/gpt-researcher/gptr/my_feature.md

包含 Image Generation 案例研究的完整功能添加指南：参见 references/adding-features.md

添加新检索器

# 1. Create: gpt_researcher/retrievers/my_retriever/my_retriever.py
class MyRetriever:
    def __init__(self, query: str, headers: dict = None):
        self.query = query
    
    async def search(self, max_results: int = 10) -> list[dict]:
        # Return: [{"title": str, "href": str, "body": str}]
        pass

# 2. Register in gpt_researcher/actions/retriever.py
case "my_retriever":
    from gpt_researcher.retrievers.my_retriever import MyRetriever
    return MyRetriever

# 3. Export in gpt_researcher/retrievers/__init__.py

完整检索器文档：参见 references/retrievers.md

---

配置

访问时配置键会被转为小写：

# In default.py: "SMART_LLM": "gpt-4o"
# Access as: self.cfg.smart_llm  # lowercase!

优先级：环境变量 → JSON 配置文件 → 默认值

完整配置参考：参见 references/config-reference.md

---

常见集成点

WebSocket 流式传输

class WebSocketHandler:
    async def send_json(self, data):
        print(f"[{data['type']}] {data.get('output', '')}")

researcher = GPTResearcher(query="...", websocket=WebSocketHandler())

MCP 数据源

researcher = GPTResearcher(
    query="Open source AI projects",
    mcp_configs=[{
        "name": "github",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": {"GITHUB_TOKEN": os.getenv("GITHUB_TOKEN")}
    }],
    mcp_strategy="deep",  # or "fast", "disabled"
)

MCP 集成详情：参见 references/mcp.md

深度研究模式

researcher = GPTResearcher(
    query="Comprehensive analysis of quantum computing",
    report_type="deep",  # Triggers recursive tree-like exploration
)

深度研究配置：参见 references/deep-research.md

---

错误处理

在 Skill 中始终使用优雅降级：

async def execute(self, ...):
    if not self.is_enabled():
        return []  # Don't crash
    
    try:
        result = await self.provider.execute(...)
        return result
    except Exception as e:
        await stream_output("logs", "error", f"⚠️ {e}", self.websocket)
        return []  # Graceful degradation

---

关键易错点

❌ 错误	✅ 正确
config.MY_VAR	config.my_var（小写）
编辑通过 pip 安装的包	pip install -e .
忘记 async/await	所有研究方法都是异步的
在 None 上调用 websocket.send_json()	先检查 if websocket:
未注册检索器	添加到 retriever.py 的 match 语句中

---

参考文档

主题	文件
系统架构与图表	references/architecture.md
核心组件与签名	references/components.md
研究流程与数据流	references/flows.md
提示词系统	references/prompts.md
检索器系统	references/retrievers.md
MCP 集成	references/mcp.md
深度研究模式	references/deep-research.md
多 Agent 系统	references/multi-agents.md
添加功能指南	references/adding-features.md
高级模式	references/advanced-patterns.md
REST 与 WebSocket API	references/api-reference.md
配置变量	references/config-reference.md