GPT Researcher 开发技能指南：SKILL.md 全解——从快速上手到扩展研究代理的核心模式

GPT Researcher 开发技能指南：SKILL.md 全解——从快速上手到扩展研究代理的核心模式

【免费下载链接】gpt-researcherAn autonomous agent that conducts deep research on any data using any LLM providers项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-researcher

本文以仓库中的.claude/SKILL.md（GPT Researcher 开发技能文档）为主体，系统讲解这一 LLM 自主深度研究代理的使用入口、关键文件地图、planner-executor-publisher 架构、新增功能的 8 步模式、新增检索器（Retriever）的完整流程、配置优先级规则，以及 WebSocket 流式输出、MCP 数据源、Deep Research 模式三大集成点。读完本文，你能够独立读懂 GPT Researcher 的调用链路，并按照仓库既有模式安全地扩展它的功能。

SKILL.md 是什么：面向开发者与 Agent 的项目开发手册

.claude/SKILL.md是 GPT Researcher 仓库内置的“开发技能”文档（frontmatter 中声明name: gpt-researcher），其定位是给开发者（以及 AI 编程 Agent）提供一份理解、扩展、调试和集成该项目的一站式手册。它声明了适用场景：添加功能、理解架构、操作 API、定制研究工作流、添加新检索器、集成 MCP 数据源，以及排查研究管线问题。

文档开篇给出了项目的一句话架构定义：

GPT Researcher 是一个基于 LLM 的自主代理，采用planner-executor-publisher（规划者-执行者-发布者）模式，并通过并行化代理工作来获得速度与可靠性。

这个定义与源码一致：在 agent.py 中，GPTResearcher类在初始化时组装了ResearchConductor（规划与采集）、ReportGenerator（写作）、ContextManager、BrowserManager、SourceCurator等一组 Skill 对象（见 gpt_researcher/agent.py），conduct_research()完成规划与检索后，再由write_report()生成最终报告，正是 planner-executor-publisher 三段式的实现。

快速上手：Python API 与前后端服务

基本 Python 用法

SKILL.md 给出的最小可用示例如下，这是与 agent.py 中GPTResearcher.__init__参数签名完全对应的入口：

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())

几个关键参数结合源码说明：

• query：研究问题，必填；
• report_type：报告类型，默认research_report（源码中默认值来自ReportType.ResearchReport），另支持detailed_report、deep、outline_report等取值；
• report_source：信息来源，默认web，还支持local（基于本地文档）与hybrid；
• websocket：可选的流式输出通道（后文详述）；
• 所有研究方法均为async，必须用await调用。

conduct_research()内部流程（见 gpt_researcher/agent.py）：先处理 deep research 分支，再调用choose_agent()选择代理角色，然后委托ResearchConductor.conduct_research()执行规划与检索，最后若启用了图片生成就预先生成图片。write_report()则将累积的self.context交给ReportGenerator生成 Markdown 报告。

启动前后端服务

# Backend python -m uvicorn backend.server.server:app --reload --port 8000 # Frontend cd frontend/nextjs && npm install && npm run dev

后端入口为 FastAPI 应用 backend/server/app.py，前端为 Next.js 应用（位于 frontend/nextjs/），二者通过 WebSocket 实时推送研究进度事件。

关键文件位置速查表

SKILL.md 提供了一份“需求 → 主文件 → 关键类”的定位表，这是快速导航本仓库的核心索引（结合 references/architecture.md 可进一步扩展）：

从源码结构看，该表中每一项都能在仓库中一一对应：ResearchConductor定义在 researcher.py，负责plan_research()（规划子查询）与conduct_research()（并发检索）；DEFAULT_CONFIG定义在 default.py，是全部配置项的唯一权威默认值来源。

架构总览：从用户查询到 Markdown 报告

SKILL.md 中的核心调用链如下：

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

结合源码可以印证并补全这条链路：

1. choose_agent()：定义在 agent_creator.py，由 LLM 根据查询内容决定研究代理类型与角色提示词，结果在conduct_research()中被缓存于self.agent/self.role；
2. plan_research()：先对原始查询做一次搜索（researcher.py），再用plan_research_outline()将搜索结果与查询一起交给 LLM 拆分为子查询列表；
3. 子查询并行处理：每个子查询独立检索、抓取网页并汇总为 context 片段，最终聚合为self.context（一个字符串列表）；
4. 可选的图片生成：GPTResearcher.conduct_research()在研究完成后、写报告前，若ImageGenerator.is_enabled()则调用plan_and_generate_images()预生成插图（agent.py）；
5. ReportGenerator.write_report()：基于 context 与PromptFamily中的报告提示词生成带引用的 Markdown 报告。

更完整的分层视图（后端 API 层 → Skills 层 → Actions 层 → Providers 层 → Configuration 层）见 references/architecture.md，其中将ContextManager（相似度检索）、BrowserManager（网页抓取）、SourceCurator（来源排序）、DeepResearchSkill（递归深度研究）等 Skill 都纳入了GPTResearcher的组成。

核心模式一：新增功能的 8 步模式

SKILL.md 定义了一个可复用的功能扩展流水线：

1. Config→ 在gpt_researcher/config/variables/default.py添加默认配置；
2. Provider→ 在gpt_researcher/llm_provider/my_feature/创建外部 API 封装；
3. Skill→ 在gpt_researcher/skills/my_feature.py创建技能类；
4. Agent→ 在gpt_researcher/agent.py中集成；
5. Prompts→ 更新gpt_researcher/prompts.py；
6. WebSocket→ 通过stream_output()推送事件；
7. Frontend→ 在useWebSocket.ts中处理新事件；
8. Docs→ 创建docs/docs/gpt-researcher/gptr/my_feature.md。

完整的分步模板（含每步的文件位置与代码骨架）收录在 references/adding-features.md，其要点如下：

第 1 步：添加配置。在DEFAULT_CONFIG中加入开关与参数，并在gpt_researcher/config/variables/base.py的BaseConfig（TypedDict）中声明类型。

第 2 步：创建 Provider。封装第三方 API，必须实现is_enabled()（通常检查 API Key 与模型是否齐备）和异步execute()方法。

第 3 步：创建 Skill。Skill 是 Provider 与 Agent 之间的适配层，统一模式为：

class MyFeatureSkill: def __init__(self, researcher): self.researcher = researcher self.config = researcher.cfg self.provider = MyFeatureProvider(...) def is_enabled(self) -> bool: return getattr(self.config, 'my_feature_enabled', False) and self.provider.is_enabled() async def execute(self, context: str, query: str) -> List[Dict]: if not self.is_enabled(): return [] # ... 调用 provider 并 stream_output 推送进度

第 4 步：集成到 Agent。在GPTResearcher.__init__中按开关初始化，在conduct_research()中按序调用。

第 5 步：更新 Prompt。在PromptFamily中新增静态提示词生成方法。

第 6 步：WebSocket 事件。通过stream_output()在 Skill 内部直接完成。

第 7 步：前端处理。在 frontend/nextjs/hooks/useWebSocket.ts 中识别新的事件内容。

第 8 步：文档。按 Docusaurus 约定放置 Markdown 文档。

参考案例：图片生成功能的真实落地

references/adding-features.md 以仓库中真实存在的图片生成功能作为案例，展示了 8 步模式的完整产物：配置项IMAGE_GENERATION_ENABLED/MAX_IMAGES/STYLE（见 default.py）、Provider（image_generator.py，基于 Gemini 生图并将风格指令注入 prompt）、Skill（gpt_researcher/skills/image_generator.py 中的ImageGenerator，先由 LLM 从 context 中规划视觉概念、再并发生成图片）、Agent 集成（conduct_research()末尾预生成、write_report()中通过available_images传入报告生成器）、Prompt 更新（报告提示词中注入AVAILABLE IMAGES - Embed where relevant using Title指令）。

该参考文档还给出了新功能的测试模板：用monkeypatch.setenv模拟环境变量，分别断言“默认关闭时 Skill 为 None”与“启用后is_enabled()为 True”，并提供了python -m pytest tests/与--cov=gpt_researcher的运行命令。

核心模式二：新增一个 Retriever

GPT Researcher 的搜索引擎是可插拔的。SKILL.md 与 references/retrievers.md 给出的三步流程如下。

第 1 步：创建检索器文件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]: # 必须返回统一结构的记录列表 # [{"title": str, "href": str, "body": str}] pass

统一返回结构（title/href/body）是与上游get_search_results()对接的契约；后续网页抓取与 context 组装都依赖这三个字段。

第 2 步：在工厂函数中注册。权威注册点是 gpt_researcher/actions/retriever.py 中get_retriever()的match语句（当前已注册 google、searx、searchapi、serpapi、serper、duckduckgo、bing、brave、bocha、arxiv、tavily、groundroute、exa、crw、semantic_scholar、pubmed_central、custom、mcp、xquik、openalex、getxapi 共 21 个检索器）：

case "my_retriever": from gpt_researcher.retrievers.my_retriever import MyRetriever return MyRetriever

第 3 步：在gpt_researcher/retrievers/__init__.py中导出。

使用方式：通过环境变量或headers启用，支持逗号分隔的多检索器：

RETRIEVER=tavily,my_retriever

researcher = GPTResearcher(query="...") # 将同时使用 Tavily 与自定义检索器

从源码看，解析逻辑在get_retrievers()（retriever.py）中，优先级为：headers["retrievers"]→headers["retriever"]→cfg.retrievers→cfg.retriever→ 默认TavilySearch；无法识别的名称会静默回退到默认检索器，这也是“忘记注册”这一常见错误难以察觉的原因。

配置体系：优先级、小写化与关键默认值

SKILL.md 对配置系统提出了两条铁律：

铁律一：配置键访问时全部小写化。默认值字典中是大写下划线命名，Config类在设置属性时执行setattr(self, key.lower(), value)（见 config.py），因此：

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

铁律二：优先级为 环境变量 → JSON 配置文件 → 默认值。Config.__init__加载 JSON 配置后，在_set_attributes()中对每个键检查os.getenv(key)，环境变量存在则覆盖（config.py）。

常用配置项可按功能域归纳（完整清单见 references/config-reference.md，默认值以 default.py 为准）：

# LLM（provider:model 组合形式） FAST_LLM=... # 快速任务（摘要） SMART_LLM=... # 复杂推理（写报告） STRATEGIC_LLM=... # 规划（代理选择/大纲规划） TEMPERATURE=0.4 REASONING_EFFORT=medium # o 系列等推理模型：low/medium/high # 检索 RETRIEVER=tavily # 或 tavily,google,mcp 逗号分隔 MAX_SEARCH_RESULTS_PER_QUERY=5 MAX_URLS_TO_SCRAPE=... SIMILARITY_THRESHOLD=0.42 # 报告 REPORT_FORMAT=apa # apa, mla, chicago, harvard, ieee TOTAL_WORDS=1000 LANGUAGE=english CURATE_SOURCES=true

需要注意：参考文档中的默认值示例（如FAST_LLM=gpt-4o-mini、DEEP_RESEARCH_BREADTH=4）是文档撰写时的示例写法；当前仓库 default.py 中的实际默认值为FAST_LLM=openai:gpt-5.4-mini、SMART_LLM=openai:gpt-5.4、TOTAL_WORDS=1200、REPORT_FORMAT=APA、DEEP_RESEARCH_BREADTH=3、DEEP_RESEARCH_DEPTH=2、DEEP_RESEARCH_CONCURRENCY=4、MCP_STRATEGY=fast、IMAGE_GENERATION_ENABLED=False等。配置时请以仓库当前内容为准。

references/config-reference.md还给出了一个可直接使用的最小.env模板：

# Required OPENAI_API_KEY=sk-your-key TAVILY_API_KEY=tvly-your-key # LLM FAST_LLM=gpt-4o-mini SMART_LLM=gpt-4o # Report TOTAL_WORDS=1000 LANGUAGE=english # Optional: Images IMAGE_GENERATION_ENABLED=true GOOGLE_API_KEY=AIza-your-key IMAGE_GENERATION_STYLE=dark

常见集成点：WebSocket、MCP 与 Deep Research

WebSocket 流式输出

任何希望实时观察研究进度的宿主系统，只需实现一个带send_json的对象并传入websocket参数：

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

对应地，Skill 内部通过stream_output("logs", "事件名", "消息", websocket)推送事件；前端则由useWebSocket.ts消费。注意 SKILL.md 在“常见陷阱”中特别强调：调用前必须检查if websocket:，因为很多场景（如脚本直接运行）该对象为None。

MCP 数据源

GPT Researcher 内置了 Model Context Protocol 检索器，可通过构造参数注入多个 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_configs中每个字典支持name、command、args、env、tool_name、connection_url、connection_type（stdio/websocket/http）、connection_token等字段（见 agent.py 参数说明）。mcp_strategy三种取值的语义为：

• fast（默认）：仅对原始查询执行一次 MCP，性能最优；
• deep：对所有子查询都执行 MCP，覆盖最彻底；
• disabled：完全跳过 MCP，仅用 Web 检索器。

策略解析逻辑在_resolve_mcp_strategy()（agent.py）中，优先级为：mcp_strategy参数 → 已废弃的mcp_max_iterations参数（0→disabled、1→fast、-1→deep）→ 配置项MCP_STRATEGY→ 默认fast，并对旧名称optimized/comprehensive做了向后兼容映射。此外_process_mcp_configs()会直接修改self.cfg.retrievers而刻意不动os.environ，以避免并发请求之间的环境变量污染。MCP 的完整细节见 references/mcp.md。

Deep Research 模式

将report_type设为deep即触发递归树状探索：

researcher = GPTResearcher( query="Comprehensive analysis of quantum computing", report_type="deep", # 触发递归树状探索 )

从源码看，当report_type == ReportType.DeepResearch.value时，GPTResearcher.__init__会实例化DeepResearchSkill（agent.py），conduct_research()检测到该模式后走_handle_deep_research()分支（agent.py）。三个核心参数由 DeepResearchSkill 初始化 从配置读取：

• DEEP_RESEARCH_BREADTH：每层展开的子主题数（当前默认 3）；
• DEEP_RESEARCH_DEPTH：递归层数（默认 2）；
• DEEP_RESEARCH_CONCURRENCY：并行任务数，内部用asyncio.Semaphore限流（deep_research.py）。

详细配置与流程见 references/deep-research.md。

错误处理：Skill 中的优雅降级

SKILL.md 为所有 Skill 规定了统一的防御性模板：未启用时直接返回空结果而不是抛异常，异常时通过 WebSocket 记录日志并降级返回：

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

这一原则保证了单个外部 API 故障不会中断整个研究管线——例如图片生成失败时报告照常产出，只是没有插图。

常见陷阱清单

SKILL.md 汇总的五条高频错误值得逐一牢记：

其中第一条和第五条都能从源码直接验证：前者对应Config._set_attributes()中的key.lower()；后者对应get_retrievers()中get_retriever(r) or get_default_retriever()的回退表达式（retriever.py）。

参考文档索引

SKILL.md 的最后一部分给出了 12 个主题参考文档的索引，全部位于.claude/references/目录，可作为深入阅读的路标：

配合本仓库的测试目录（tests/，含大量针对配置、检索器、Scraper 与 Skill 的守护式单测），这份 SKILL.md 构成了理解与扩展 GPT Researcher 的完整知识入口：先按速查表定位文件，再按 8 步模式或三步注册流程动手扩展，最后以“小写配置键、全异步、WebSocket 判空、优雅降级”四条纪律保证改动与既有架构一致。

【免费下载链接】gpt-researcherAn autonomous agent that conducts deep research on any data using any LLM providers项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-researcher