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.mdGPT 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.pyconduct_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( queryWhat are the latest AI developments?, report_typeresearch_report, # or detailed_report, deep, outline_report report_sourceweb, # 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基于本地文档与hybridwebsocket可选的流式输出通道后文详述所有研究方法均为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 可进一步扩展需求主文件关键类主编排器gpt_researcher/agent.pyGPTResearcher研究逻辑gpt_researcher/skills/researcher.pyResearchConductor报告写作gpt_researcher/skills/writer.pyReportGenerator所有 Promptgpt_researcher/prompts.pyPromptFamily配置gpt_researcher/config/config.pyConfig配置默认值gpt_researcher/config/variables/default.pyDEFAULT_CONFIGAPI 服务backend/server/app.pyFastAPIapp搜索引擎gpt_researcher/retrievers/各检索器类从源码结构看该表中每一项都能在仓库中一一对应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结合源码可以印证并补全这条链路choose_agent()定义在 agent_creator.py由 LLM 根据查询内容决定研究代理类型与角色提示词结果在conduct_research()中被缓存于self.agent/self.roleplan_research()先对原始查询做一次搜索researcher.py再用plan_research_outline()将搜索结果与查询一起交给 LLM 拆分为子查询列表子查询并行处理每个子查询独立检索、抓取网页并汇总为 context 片段最终聚合为self.context一个字符串列表可选的图片生成GPTResearcher.conduct_research()在研究完成后、写报告前若ImageGenerator.is_enabled()则调用plan_and_generate_images()预生成插图agent.pyReportGenerator.write_report()基于 context 与PromptFamily中的报告提示词生成带引用的 Markdown 报告。更完整的分层视图后端 API 层 → Skills 层 → Actions 层 → Providers 层 → Configuration 层见 references/architecture.md其中将ContextManager相似度检索、BrowserManager网页抓取、SourceCurator来源排序、DeepResearchSkill递归深度研究等 Skill 都纳入了GPTResearcher的组成。核心模式一新增功能的 8 步模式SKILL.md 定义了一个可复用的功能扩展流水线Config→ 在gpt_researcher/config/variables/default.py添加默认配置Provider→ 在gpt_researcher/llm_provider/my_feature/创建外部 API 封装Skill→ 在gpt_researcher/skills/my_feature.py创建技能类Agent→ 在gpt_researcher/agent.py中集成Prompts→ 更新gpt_researcher/prompts.pyWebSocket→ 通过stream_output()推送事件Frontend→ 在useWebSocket.ts中处理新事件Docs→ 创建docs/docs/gpt-researcher/gptr/my_feature.md。完整的分步模板含每步的文件位置与代码骨架收录在 references/adding-features.md其要点如下第 1 步添加配置。在DEFAULT_CONFIG中加入开关与参数并在gpt_researcher/config/variables/base.py的BaseConfigTypedDict中声明类型。第 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、Providerimage_generator.py基于 Gemini 生图并将风格指令注入 prompt、Skillgpt_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/与--covgpt_researcher的运行命令。核心模式二新增一个 RetrieverGPT Researcher 的搜索引擎是可插拔的。SKILL.md 与 references/retrievers.md 给出的三步流程如下。第 1 步创建检索器文件gpt_researcher/retrievers/my_retriever/my_retriever.pyclass 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启用支持逗号分隔的多检索器RETRIEVERtavily,my_retrieverresearcher 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 为准# LLMprovider:model 组合形式 FAST_LLM... # 快速任务摘要 SMART_LLM... # 复杂推理写报告 STRATEGIC_LLM... # 规划代理选择/大纲规划 TEMPERATURE0.4 REASONING_EFFORTmedium # o 系列等推理模型low/medium/high # 检索 RETRIEVERtavily # 或 tavily,google,mcp 逗号分隔 MAX_SEARCH_RESULTS_PER_QUERY5 MAX_URLS_TO_SCRAPE... SIMILARITY_THRESHOLD0.42 # 报告 REPORT_FORMATapa # apa, mla, chicago, harvard, ieee TOTAL_WORDS1000 LANGUAGEenglish CURATE_SOURCEStrue需要注意参考文档中的默认值示例如FAST_LLMgpt-4o-mini、DEEP_RESEARCH_BREADTH4是文档撰写时的示例写法当前仓库 default.py 中的实际默认值为FAST_LLMopenai:gpt-5.4-mini、SMART_LLMopenai:gpt-5.4、TOTAL_WORDS1200、REPORT_FORMATAPA、DEEP_RESEARCH_BREADTH3、DEEP_RESEARCH_DEPTH2、DEEP_RESEARCH_CONCURRENCY4、MCP_STRATEGYfast、IMAGE_GENERATION_ENABLEDFalse等。配置时请以仓库当前内容为准。references/config-reference.md还给出了一个可直接使用的最小.env模板# Required OPENAI_API_KEYsk-your-key TAVILY_API_KEYtvly-your-key # LLM FAST_LLMgpt-4o-mini SMART_LLMgpt-4o # Report TOTAL_WORDS1000 LANGUAGEenglish # Optional: Images IMAGE_GENERATION_ENABLEDtrue GOOGLE_API_KEYAIza-your-key IMAGE_GENERATION_STYLEdark常见集成点WebSocket、MCP 与 Deep ResearchWebSocket 流式输出任何希望实时观察研究进度的宿主系统只需实现一个带send_json的对象并传入websocket参数class WebSocketHandler: async def send_json(self, data): print(f[{data[type]}] {data.get(output, )}) researcher GPTResearcher(query..., websocketWebSocketHandler())对应地Skill 内部通过stream_output(logs, 事件名, 消息, websocket)推送事件前端则由useWebSocket.ts消费。注意 SKILL.md 在“常见陷阱”中特别强调调用前必须检查if websocket:因为很多场景如脚本直接运行该对象为None。MCP 数据源GPT Researcher 内置了 Model Context Protocol 检索器可通过构造参数注入多个 MCP 服务器researcher GPTResearcher( queryOpen source AI projects, mcp_configs[{ name: github, command: npx, args: [-y, modelcontextprotocol/server-github], env: {GITHUB_TOKEN: os.getenv(GITHUB_TOKEN)} }], mcp_strategydeep, # or fast, disabled )mcp_configs中每个字典支持name、command、args、env、tool_name、connection_url、connection_typestdio/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( queryComprehensive analysis of quantum computing, report_typedeep, # 触发递归树状探索 )从源码看当report_type ReportType.DeepResearch.value时GPTResearcher.__init__会实例化DeepResearchSkillagent.pyconduct_research()检测到该模式后走_handle_deep_research()分支agent.py。三个核心参数由 DeepResearchSkill 初始化 从配置读取DEEP_RESEARCH_BREADTH每层展开的子主题数当前默认 3DEEP_RESEARCH_DEPTH递归层数默认 2DEEP_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 [] # Dont 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.MY_VARconfig.my_var访问时小写化编辑 pip 安装的包pip install -e .可编辑安装后修改源码才生效忘记 async/await所有研究方法均为异步对 None 调用websocket.send_json()先检查if websocket:忘记注册检索器必须加入retriever.py的match语句否则会静默回退到 Tavily其中第一条和第五条都能从源码直接验证前者对应Config._set_attributes()中的key.lower()后者对应get_retrievers()中get_retriever(r) or get_default_retriever()的回退表达式retriever.py。参考文档索引SKILL.md 的最后一部分给出了 12 个主题参考文档的索引全部位于.claude/references/目录可作为深入阅读的路标主题文件系统架构与分层图references/architecture.md核心组件与签名references/components.md研究流程与数据流references/flows.mdPrompt 系统references/prompts.md检索器系统references/retrievers.mdMCP 集成references/mcp.mdDeep Research 模式references/deep-research.md多智能体系统references/multi-agents.md功能添加指南references/adding-features.md高级模式references/advanced-patterns.mdREST 与 WebSocket APIreferences/api-reference.md配置变量参考references/config-reference.md配合本仓库的测试目录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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考