用 Claude Code 参与 GPT Researcher 开发：AI 辅助开发技能文件（.claude/skills）完全指南

用 Claude Code 参与 GPT Researcher 开发AI 辅助开发技能文件.claude/skills完全指南【免费下载链接】gpt-researcherAn autonomous agent that conducts deep research on any data using any LLM providers项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-researcherGPT Researcher 仓库内置了一套面向 AI 编程助手的技能文件体系.claude/skills/它把一位资深贡献者掌握的架构、模式、陷阱与最佳实践以结构化文档的形式沉淀下来让 Claude Code 等 AI 助手自动发现、即时理解、按模式贡献。本文以 docs/docs/gpt-researcher/gptr/ai-development.md 为核心骨架结合仓库中真实的.claude/技能文件、参考文档与源码实现完整讲解这套 AI 辅助开发体系的目录结构、文件内容、使用方式、贡献工作流、8 步功能开发模式以及技能文件的维护最佳实践。读完本文你将掌握如何安装与启动 Claude Code 并让它自动加载 GPT Researcher 技能如何用自然语言让 AI 助手完成代码理解、功能实现、调试与测试以及当仓库架构演化后如何正确更新技能文件让这套可被 AI 读取的开发者大脑始终保持新鲜。Overview为什么需要一份给 AI 看的开发文档GPT Researcher 是一个基于 LLM 的自主深度研究代理采用 planner–executor–publisher 模式并通过并行化代理工作来兼顾速度与可靠性见 .claude/SKILL.md。它的代码面覆盖后端 API、研究编排、报告生成、检索器、爬虫、MCP 集成、多代理系统与前端新贡献者仅靠阅读源码很难快速建立起全局认知。为此仓库维护了.claude/skills/目录当前仓库中实际表现为 .claude/SKILL.md 与 .claude/references/ 参考文档目录其中包含 Claude 在操作该仓库时会自动发现并使用的详细文档。这套体系带来四方面的收益更快上手Claude 能瞬间理解架构无需逐文件考古一致的贡献AI 生成的代码遵循仓库既有模式而非看起来能跑的野路子更少错误文档明确记录了常见陷阱与最佳实践端到端能力可以按 8 步模式完整实现新功能从配置一路做到前端与文档。官方文档将其定性为一位专家开发者对 GPT Researcher 全部知识的脑力倾泻brain dump并以 AI 助手可消费的形式交付见 docs/docs/gpt-researcher/gptr/ai-development.md。技能目录结构SKILL.md 与 REFERENCE.md 的分工原文档给出的目录骨架如下.claude/ └── skills/ ├── SKILL.md # Comprehensive development guide (~1,500 lines) └── REFERENCE.md # Quick lookup for config, API, WebSocket events需要说明当前仓库中的实际组织方式为.claude/SKILL.md入口主文档与.claude/references/分主题参考文档目录后者进一步细分为 architecture.md、components.md、flows.md、prompts.md、retrievers.md、mcp.md、deep-research.md、multi-agents.md、adding-features.md、advanced-patterns.md、api-reference.md、config-reference.md。这一变化说明技能体系从两大文件演进为入口 主题参考的模块化形态但主文档深入讲解 参考文档快速查找的核心理念一脉相承。SKILL.md 里有什么.claude/SKILL.md 是完整的开发指南其 frontmatter 中的name: gpt-researcher与description字段用于让 Claude 判断何时该加载这份技能。内容覆盖章节内容说明Quick Start最小 Python 用法与前后端启动命令Key File Locations核心文件与关键类对照表GPTResearcher、ResearchConductor、ReportGenerator等Architecture Overview从查询到报告的完整系统流程图Core Patterns8 步功能新增模式、新增检索器模式Configuration配置加载优先级与键名小写化规则Common Integration PointsWebSocket 流式输出、MCP 数据源、Deep Research 模式Error Handling优雅降级graceful degradation模式Critical Gotchas常见错误与正确写法对照表Reference Documentation指向.claude/references/各主题文档的索引表其中 SKILL.md 的 Reference Documentation 表格 把全部 12 个参考文档按主题列成索引Claude 可以根据任务按需深入对应文件。REFERENCE.md 里有什么原文档说明参考文档提供快速查找能力包括全部环境变量、REST API 端点、WebSocket 消息类型、Python 客户端参数。这些内容在当前仓库中分散在 config-reference.md配置与环境变量与 api-reference.mdREST/WebSocket API中。以 config-reference.md 为例它按主题组织为必填变量、LLM 配置、Provider API Keys、检索器配置、报告配置、功能开关图片生成 / Deep Research / MCP / 本地文档 / 服务端、配置优先级与示例.env。其中配置优先级明确为Environment Variables (highest) ↓ JSON Config File (if provided) ↓ Default Values (lowest)并强调一个关键事实配置键在访问时必须小写化——default.py中定义的是SMART_LLM: gpt-4o访问时需写self.cfg.smart_llm。这与 .claude/SKILL.md 的 Critical Gotchas 中config.MY_VAR❌ →config.my_var✅的提醒相互印证。使用 Claude Code安装与典型提示词安装与启动安装 Claude CodeVS Code 扩展或 CLI 形式打开 GPT Researcher 仓库Claude 会自动发现.claude/skills/中的技能并加载。官方示例提示词原文档给出了四类典型用法均可直接使用理解代码库How does the research flow work from query to report?新增功能引用 8 步模式I want to add a feature that generates audio summaries of reports. Follow the 8-step pattern from the skills file.调试Why might images not be appearing in the report? Check the image generation flow.扩展功能新增检索器Add a new retriever for Wikipedia. Follow the retriever pattern in the skills.这些提示词之所以有效是因为 SKILL.md 中包含了 Quick Start、Architecture Overview、Core Patterns 等可以直接检索的内容。Claude 能做什么在原文档的基础上结合 SKILL.md 的实际能力清单加载技能后 Claude 可以解释任意代码片段——架构、数据流、组件交互端到端实现功能——Config → Provider → Skill → Agent → Prompts → Frontend 全链路调试问题——了解常见陷阱与错误模式编写测试——掌握 pytest 组织方式仓库tests/目录下有 test_agent_creator_json_shape.py、test_research_conductor_retrieval.py 等大量可参考的测试新增检索器——遵循 SKILL.md 的 retriever 模式修改提示词——理解 prompts.py 中的PromptFamily体系扩展 API——熟悉 FastAPI 模式与 WebSocket 事件见 backend/server/app.py 与 backend/server/websocket_manager.py。用 Claude 参与贡献工作流与示例开始之前Fork 并 clone 仓库以可编辑模式安装pip install -e .配置.env文件填入所需 API Key可参考 config-reference.md 的示例 .env在带 Claude Code 的编辑器中打开仓库。贡献工作流向 Claude 描述你的功能/修复及上下文让 Claude 按既有模式实现审查改动——让 Claude 解释它做了什么充分测试——python -m pytest tests/提交 PR并附清晰描述。实战示例新增报告写作风格功能原文档给出了一个完整示例——让用户通过环境变量指定报告写作风格如 academic、blog post、executive summaryI want to add a feature that allows users to specify a custom writing style for reports (e.g., academic, blog post, executive summary). This should: 1. Be configurable via environment variable 2. Affect the report generation prompt 3. Be optional with a sensible default Please implement following the 8-step pattern.按技能文件Claude 会执行在配置默认值中加入REPORT_STYLE在BaseConfig中新增类型定义见 gpt_researcher/config/variables/base.py 与 gpt_researcher/config/variables/default.py更新 gpt_researcher/prompts.py 中的提示词生成函数PromptFamily.generate_report_prompt等展示具体改动并解释配置键访问需小写等陷阱。源码级纵深8 步功能新增模式原文档提到8 步模式是技能文件的核心能力之一。其完整定义位于 SKILL.md 的 Core Patterns展开说明在 adding-features.md┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │1.CONFIG│ → │2.PROVIDER│ → │3.SKILL │ → │4.AGENT │ └────────┘ └────────┘ └────────┘ └────────┘ ↓ ↓ ↓ ↓ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │5.PROMPTS│ → │6.WEBSOCKET│→ │7.FRONTEND│→ │8.DOCS │ └────────┘ └────────┘ └────────┘ └────────┘Step 1 配置在gpt_researcher/config/variables/default.py的DEFAULT_CONFIG中新增键并在gpt_researcher/config/variables/base.py的BaseConfigTypedDict中声明类型Step 2 Provider在gpt_researcher/llm_provider/my_feature/创建 provider 类含is_enabled()与async execute()并在gpt_researcher/llm_provider/__init__.py导出Step 3 Skill在gpt_researcher/skills/my_feature.py创建技能类通过stream_output()发送进度事件并在gpt_researcher/skills/__init__.py导出Step 4 Agent 集成在 gpt_researcher/agent.py 的__init__中按配置决定是否实例化技能在conduct_research()中调用Step 5 提示词在gpt_researcher/prompts.py中新增generate_my_feature_prompt之类的静态方法Step 6 WebSocket 事件由技能内部的stream_output()天然完成无需额外编码Step 7 前端在frontend/nextjs/hooks/useWebSocket.ts中处理新事件如my_feature_startStep 8 文档创建docs/docs/gpt-researcher/gptr/my_feature.md。技能文件还以图片生成Image Generation功能作为完整案例研究见 adding-features.md 的 Image Generation Case Study逐步骤展示了真实实现配置IMAGE_GENERATION_MODEL、IMAGE_GENERATION_MAX_IMAGES、IMAGE_GENERATION_ENABLED、IMAGE_GENERATION_STYLEprovider 使用 Geminimodels/gemini-2.5-flash-image技能在报告写作前预生成图片并传入write_report()的available_images参数让提示词把图片以Title形式嵌入报告。这一模式与源码实现高度吻合在 gpt_researcher/agent.py 的__init__中ResearchConductor、ReportGenerator、ContextManager、BrowserManager、SourceCurator被依次实例化ImageGenerator按配置初始化DeepResearchSkill仅在report_type ReportType.DeepResearch.value时创建——即按配置条件化装配技能就是GPTResearcher的实际装配方式。架构纵深从查询到报告的完整链路技能文档中的架构图architecture.md把系统划分为五层用户请求 → 后端 API 层FastAPI / WebSocket Manager / Report Store→GPTResearcher编排层Skills 层 Actions 层 Providers 层→ 配置层。对照源码核心调用链为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其中GPTResearcher的核心方法签名components.md与 gpt_researcher/agent.py 的__init__实现 完全对应query必填、report_type默认research_report、report_format、report_sourceweb/local/hybrid/azure等、tone、source_urls、query_domains、config_path、websocket、mcp_configs/mcp_strategy等。数据流方面flows.mdplan_research()用 LLM 生成 3-5 个子查询每个子查询依次走 MCP 检索可选→ Web 搜索 → URL 爬取 → 向量相似度筛选 → 合并上下文最终聚合为完整 context 交给报告生成。检索器如何新增一个搜索引擎SKILL.md 的 Adding a New Retriever 给出了三步式模式# 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原文档说技能覆盖全部 14 个检索器当前仓库 gpt_researcher/retrievers/ 下实际包含 Tavily、Google、Bing、Brave、Serper、SerpAPI、Exa、DuckDuckGo、Searx、Arxiv、OpenAlex、PubMed Central、Semantic Scholar、Bocha、CRW、GetXAPI、GroundRoute、XQuik、MCP、Custom 等检索器具体以仓库现状为准。注意任何新检索器都必须在 gpt_researcher/actions/retriever.py 的 match 语句中注册这正是 Critical Gotchas 中Not registering retriever要避免的错误。MCP 与 Deep Research 集成点技能文件还覆盖了两个重要扩展点MCP 数据源通过mcp_configs传入如 GitHub MCP servermcp_strategy可取fast仅对原始查询运行一次 MCP性能最优、deep对每个子查询都运行 MCP最彻底、disabled跳过 MCP仅用 Web 检索器。源码中_resolve_mcp_strategy()还处理了与已废弃的mcp_max_iterations参数的向后兼容见 gpt_researcher/agent.py。Deep Research 模式report_typedeep触发递归树状探索配置项DEEP_RESEARCH_BREADTH每层子主题数、DEEP_RESEARCH_DEPTH递归层级、DEEP_RESEARCH_CONCURRENCY并行任务数可调。技能文件的维护与最佳实践原文档明确指出新增重大功能或架构变化后必须同步更新技能文件更新.claude/skills/SKILL.md加入新模式在.claude/skills/REFERENCE.md中补充新配置变量对应到当前仓库即更新.claude/references/config-reference.md若新功能是优秀范例将其作为 case study 写入。技能文件的最佳实践包括与当前仓库的写作风格一致代码示例必须真实——取自实际实现而非理想化伪代码adding-features.md 的图片生成案例即是真实实现的范本同时写清是什么与为什么突出记录陷阱——如 Critical Gotchas 表格 中所有研究方法都是 async别忘awaitwebsocket.send_json()前先判空等组件变化时同步更新数据流图把新功能加入 Supported Options 相关小节。关于测试的落地细节技能文档中的测试指南强调使用 pytest。仓库 tests/ 目录提供了大量与技能内容对应的真实测试可作为参考例如配置与 JSON 修复相关的 test_convert_env_value_json_repair.py、检索器健壮性相关的 test_brave_retriever.py 与 test_serper_retriever.py、以及 Deep Research 相关的 test_deep_research_parsing.py。运行方式# 全部测试 python -m pytest tests/ # 指定测试 python -m pytest tests/test_my_feature.py -v # 带覆盖率 python -m pytest tests/ --covgpt_researcher总结为什么这套体系值得维护AI 辅助开发正在成为标准实践。维护高质量技能文件的长期收益包括新贡献者可在几分钟内完成上手而不是几小时资深贡献者借助 AI 辅助可以更快交付代码质量在 AI 参与下保持一致文档作为副产品始终保持最新——因为任何架构变更都会要求同步更新技能文件。本质上技能文件就是一位 GPT Researcher 专家开发者的全部知识沉淀只不过它的读者是 AI 助手。对于任何希望借助 Claude Code 深度参与本仓库开发、扩展检索器、接入 MCP 数据源或实现完整新功能的开发者.claude/SKILL.md 与 .claude/references/ 就是第一手开发手册而 docs/docs/gpt-researcher/gptr/ai-development.md 则是理解这套体系设计意图的最佳入口。进一步阅读仓库根目录的 CONTRIBUTING.md 提供了面向人类的贡献指南可与技能文件互为补充docs/docs/gpt-researcher/gptr/下的 config.md、deep_research.md、scraping.md 等文档则对应技能参考文档中的各主题方便对照阅读。【免费下载链接】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），仅供参考