tools-only Claude Code Deep Research Agent - 项目理解文档
1. 项目概述
这是一个基于 Claude Code 的深度研究框架，旨在实现类似 OpenAI Deep Research 和 Google Gemini Deep Research 的功能。项目的核心理念是利用 Anthropic Claude Code 的能力，通过系统化的方法论和多智能体协作，完成复杂的、多步骤的深度研究任务。
1.1 项目定位
- 名称: Claude Deep Research Agent
- 目标: 使用 Claude Code 实现高质量、带引用的深度研究报告
- 核心理念: 通过 Graph of Thoughts (GoT) 框架和 7 阶段深度研究流程，超越传统的单次查询模式
1.2 当前工作流程
[用户原始问题]
↓
[ChatGPT (o3/o3-pro)] - 问题细化和结构化
↓
[Claude Code (opus)] - 执行深度研究
↓
[带引用的综合研究报告]
关键问题: 目前依赖 ChatGPT 来预处理问题，用户希望能够完全用 Claude Code 实现。
2. 核心文件分析
2.1 README.md
作用: 项目说明和快速开始指南
核心内容:
- 解释项目存在的理由：LLM 在单次查询上表现良好，但在需要迭代查询、来源验证和引用的复杂多步骤研究上存在困难
- 定义了仓库结构：
CLAUDE.md- Claude Code 的主指令文件Claude2.md- 更深度的版本，更接近 Graph of Thoughts 模式Deep Research Question Generator System Prompt.md- ChatGPT 系统提示词deepresearchprocess.md- 7 阶段深度研究流程基础文档.template_mcp.json- 可选的 MCP 服务器配置
2.2 CLAUDE.md (主指令文件)
作用: Claude Code 的核心操作指南
核心架构:
A. 7 阶段深度研究流程
- Phase 1: Question Scoping - 问题范围界定
- Phase 2: Retrieval Planning - 检索计划
- Phase 3: Iterative Querying - 迭代查询
- Phase 4: Source Triangulation - 来源三角验证
- Phase 5: Knowledge Synthesis - 知识综合
- Phase 6: Quality Assurance - 质量保证
- Phase 7: Output & Packaging - 输出和打包
B. 多智能体研究策略
Phase 2: 检索规划
├── 主题分解智能体
└── 并行研究智能体 (每个子主题一个)
Phase 3: 迭代查询
├── 网络研究智能体 (3-5个) - 当前信息、趋势、新闻
├── 学术/技术智能体 (1-2个) - 研究论文、技术规范
└── 交叉引用智能体 (1个) - 事实核查和验证
C. 工具使用协议
- WebSearch: 通用网络搜索
- WebFetch: 提取特定 URL 内容
- Read/Write: 管理研究文档
- Task: 生成自主智能体
- TodoWrite: 跟踪研究进度
- MCP 服务器:
mcp__filesystem__: 文件系统操作mcp__puppeteer__: 浏览器自动化（动态网页内容）
2.3 Claude2.md
作用: 更深度的 GoT (Graph of Thoughts) 实现版本
关键区别:
- 更完整的 Graph of Thoughts 实现
- 使用 Task 智能体模拟 GoT 操作
- 无需外部 Python 设置
- 自动执行图状态维护
核心概念:
图结构:
- 节点 (Nodes) = 研究发现
- 边 (Edges) = 依赖关系
- 分数 (Scores) = 质量 (0-10)
- 前沿 (Frontier) = 可扩展的活跃节点
转换操作:
- Generate(k): 从父节点创建 k 个新想法
- Aggregate(k): 将 k 个想法合并为一个更强的想法
- Refine(1): 改进想法而不添加新内容
- Score: 评估想法质量
- KeepBestN(n): 每层保留最佳 n 个节点
2.4 Deep Research Question Generator System Prompt.md
作用: 用于 ChatGPT 的系统提示词，将用户原始问题转换为结构化提示词
核心功能:
- 问澄清问题（范围、格式、约束、背景）
- 生成结构化的深度研究提示词
- 输出 OpenAI 和 Google Gemini 两种格式
示例结构:
### TASK - 任务描述
### CONTEXT/BACKGROUND - 背景
### SPECIFIC QUESTIONS OR SUBTASKS - 具体问题/子任务
### KEYWORDS - 关键词
### CONSTRAINTS - 约束（时间、地理、来源类型）
### OUTPUT FORMAT - 输出格式
### FINAL INSTRUCTIONS - 最终指令
3. 研究方法论
3.1 Graph of Thoughts (GoT) 框架
来源: 基于 SPCL, ETH Zürich 的研究
核心优势:
- 并行处理: 多个研究路径可同时探索
- 质量优化: 通过评分和修剪来优化信息质量
- 回溯能力: 可放弃较差的研究路径
- 动态探索: 根据中间结果调整研究策略
执行流程示例:
用户: "Deep research CRISPR gene editing safety"
迭代 1: 初始化和探索
- Controller 创建根节点
- Generate(3) 部署 3 个并行智能体:
* 当前证据和成功率
* 安全顾虑和限制
* 未来影响和法规
- 结果: 3 个想法，分数 (6.8, 8.2, 7.5)
迭代 2: 深化最佳路径
- n3 (8.2): 高分 → Generate(3) 更深探索
- n2 (7.5): 中等 → Generate(2)
- n4 (6.8): 低分 → Refine(1) 改进
迭代 3: 聚合强分支
- Aggregate(3) 合并最佳想法
迭代 4: 最终打磨
- Refine(1) 增强清晰度和完整性
- 最终想法分数: 9.5
3.2 引用要求
每个事实性声明必须包含:
- 作者/组织
- 发布日期
- 来源标题
- URL/DOI
- 页码（如适用）
来源质量评级:
- A: 同行评议的 RCT、系统评价、荟萃分析
- B: 队列研究、病例对照研究、临床指南
- C: 专家意见、病例报告、机制研究
- D: 初步研究、预印本、会议摘要
- E: 轶事、理论或推测
3.3 防幻觉策略
Chain-of-Verification (CoVe):
- 生成初始研究发现
- 为每个声明创建验证问题
- 搜索证据回答验证问题
- 基于验证结果修正发现
ReAct 模式 (Reason + Act):
- Reason: 分析需要什么信息
- Act: 执行搜索或检索操作
- Observe: 处理结果
- Repeat: 直到收集足够证据
Human-in-the-Loop 检查点:
- 规划后：批准研究策略
- 验证期间：专家审查技术声明
- 最终确定前：利益相关者签字
4. 输出结构
4.1 标准文件夹结构
RESEARCH/
└── [topic_name]/
├── README.md (概述和导航)
├── executive_summary.md (1-2 页摘要)
├── full_report.md (综合发现)
├── data/
│ ├── raw_data.csv
│ ├── processed_data.json
│ └── statistics_summary.md
├── visuals/
│ ├── charts/
│ ├── graphs/
│ └── infographics/
├── sources/
│ ├── bibliography.md
│ ├── source_summaries.md
│ └── screenshots/
├── research_notes/
│ ├── agent_1_findings.md
│ ├── agent_2_findings.md
│ └── synthesis_notes.md
└── appendices/
├── methodology.md
├── limitations.md
└── future_research.md
4.2 示例输出分析
主题: AI Content Detection Field Briefing 规模: >50,000 词 输出时间: 需要多个智能体并行工作
主要部分:
- Executive Summary (≤1,500 词)
- Main Report (分为编号的部分和子部分)
- End-User Quick-Reference Toolkit (清单、备忘单)
- Developer Solution Blueprints (架构图、伪代码)
- Roadmap Tables (短期/中期)
- Appendices (详细基准、数据表、术语表)
5. 用户需求分析
5.1 当前架构的问题
依赖 ChatGPT 的问题:
- 需要两个独立的工具/账户
- ChatGPT 限制和成本
- 工作流程不连贯
- 无法充分利用 Claude Code 的原生能力
5.2 期望的改进
用户目标:
[用户原始问题]
↓
[Claude Code Agent] - 问题细化 + 深度研究
↓
[带引用的综合研究报告]
核心需求:
- 利用 Claude Code Skills: 创建可重用的研究技能
- 利用 Claude Code Commands: 创建便捷的斜杠命令
- 消除 GPT 依赖: 完全用 Claude Code 实现问题细化
- 自动化流程: 从原始问题到最终报告的一键执行
6. Claude Code 原生功能分析
6.1 Skills 系统
定义: Skills 是可重用的能力，可以被 Claude Code 动态加载和执行。
在此项目中的应用场景:
Skills/
├── question-refiner/ # 问题细化技能
│ ├── skill.json
│ ├── instructions.md
│ └── examples.md
├── researcher/ # 研究执行技能
│ ├── skill.json
│ ├── got-controller.md
│ ├── web-search.md
│ └── citation-formatter.md
├── synthesizer/ # 综合技能
│ ├── skill.json
│ └── instructions.md
└── validator/ # 验证技能
├── skill.json
└── verification-checklist.md
6.2 Commands 系统
定义: Commands 是用户可以调用的快捷操作。
在此项目中的应用场景:
Commands/
├── deep-research # /deep-research [topic]
├── refine-question # /refine-question [raw question]
├── plan-research # /plan-research [topic]
├── execute-research # /execute-research [plan]
└── validate-facts # /validate-facts [findings]
6.3 MCP (Model Context Protocol) 服务器
可用的 MCP 功能:
- mcp__web_reader__webReader: 网页内容提取（已配置）
- mcp__4_5v_mcp__analyze_image: 图像分析（已配置）
- 潜在的其他 MCP:
- Puppeteer (浏览器自动化)
- Filesystem (文件系统操作)
7. 实现方案建议
7.1 架构设计
┌─────────────────────────────────────────────────────────────┐
│ Claude Code Agent │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Command: /deep-research [topic] │ │
│ └──────────────────┬──────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Skill: question-refiner │ │
│ │ - 问澄清问题 │ │
│ │ - 生成结构化研究提示词 │ │
│ └──────────────────┬──────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Skill: research-planner (GoT Controller) │ │
│ │ - 分解主题为子主题 │ │
│ │ - 创建研究图 │ │
│ │ - 部署并行研究智能体 │ │
│ └──────────────────┬──────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Multi-Agent Execution │ │
│ │ ├─ Web Research Agents (3-5) │ │
│ │ ├─ Academic/Technical Agents (1-2) │ │
│ │ └─ Cross-Reference Agent (1) │ │
│ └──────────────────┬──────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Skill: synthesizer │ │
│ │ - 聚合发现 │ │
│ │ - 解决矛盾 │ │
│ │ - 创建连贯叙述 │ │
│ └──────────────────┬──────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Skill: validator │ │
│ │ - 事实核查 │ │
│ │ - 引用验证 │ │
│ │ - 质量评分 │ │
│ └──────────────────┬──────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Output Generation │ │
│ │ - Executive Summary │ │
│ │ - Full Report │ │
│ │ - Bibliography │ │
│ │ - Appendices │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
7.2 技术实现要点
A. Question Refiner Skill
功能: 替代 ChatGPT 的问题细化
实现方式:
输入: 用户原始问题
处理:
1. 识别模糊点
2. 生成澄清问题
3. 等待用户回答
4. 生成结构化研究提示词
输出: 结构化研究任务
B. GoT Controller Skill
功能: 管理研究图状态
实现方式:
使用 Task 工具创建子智能体:
- Controller Agent: 维护图状态
- Generate Agents: 探索研究路径
- Aggregate Agent: 合并发现
- Refine Agent: 改进内容
- Score Agent: 评估质量
C. Citation Manager Skill
功能: 确保所有声明都有引用
实现方式:
自动检查:
- 每个事实性声明是否有来源
- 引用格式是否正确
- 来源是否可靠
- 是否存在矛盾
7.3 文件结构建议
claude-code-deep-research/
├── .claude/
│ ├── skills/
│ │ ├── question-refiner/
│ │ │ ├── skill.json
│ │ │ ├── instructions.md
│ │ │ └── examples.md
│ │ ├── research-executor/
│ │ │ ├── skill.json
│ │ │ ├── phases.md
│ │ │ └── agent-templates.md
│ │ ├── got-controller/
│ │ │ ├── skill.json
│ │ │ ├── graph-operations.md
│ │ │ └── scoring.md
│ │ ├── synthesizer/
│ │ │ ├── skill.json
│ │ │ └── instructions.md
│ │ └── citation-validator/
│ │ ├── skill.json
│ │ └── checklist.md
│ └── commands/
│ ├── deep-research/
│ │ └── command.json
│ ├── refine-question/
│ │ └── command.json
│ └── plan-research/
│ └── command.json
├── CLAUDE.md # 主文档（保留）
├── CLAUDE2.md # GoT 版本（保留）
├── deepresearchprocess.md # 流程文档（保留）
├── PROJECT_UNDERSTANDING.md # 本文档
├── IMPLEMENTATION_GUIDE.md # 待创建：实现指南
└── examples/ # 示例输出（保留）
7.4 Skill JSON 结构示例
question-refiner/skill.json:
{
"name": "question-refiner",
"description": "将原始研究问题细化为结构化的深度研究任务，通过澄清问题确保研究目标清晰",
"instructions": "读取 instructions.md 获取详细指令",
"examples": "读取 examples.md 查看示例"
}
deep-research/command.json:
{
"name": "deep-research",
"description": "对给定主题执行完整的深度研究流程",
"usage": "/deep-research [研究主题]",
"skill": "research-executor"
}
8. 关键技术挑战和解决方案
8.1 挑战 1: Context 限制
问题: 深度研究可能生成超过 200K tokens 的内容
解决方案:
- 分模块生成（每个部分独立文件）
- 使用摘要和引用链接
- 渐进式综合（分层聚合）
8.2 挑战 2: 引用准确性
问题: 幻觉引用或格式错误
解决方案:
- Chain-of-Verification 验证循环
- 强制每个声明都有来源
- 使用多个来源验证关键声明
8.3 挑战 3: 研究质量一致性
问题: 不同智能体输出质量不均
解决方案:
- 标准化智能体提示词模板
- 评分和修剪低质量分支
- 聚合多个来源
8.4 挑战 4: 用户交互
问题: 如何处理需要用户澄清的情况
解决方案:
- 使用 AskUserQuestion 工具
- 分阶段执行（规划 → 用户确认 → 执行）
- 保存中间状态供用户审查
9. 实施路线图
Phase 1: 基础 Skills (1-2 周)
- 创建 question-refiner skill
- 创建 research-executor skill
- 测试基础工作流程
Phase 2: GoT 集成 (2-3 周)
- 创建 got-controller skill
- 实现图操作（Generate, Aggregate, Refine, Score）
- 创建智能体模板系统
Phase 3: Commands 和 UI (1 周)
- 创建 /deep-research command
- 创建 /refine-question command
- 优化用户交互流程
Phase 4: 质量保证 (1-2 周)
- 创建 citation-validator skill
- 实现自动化质量检查
- 添加人工审查检查点
Phase 5: 测试和优化 (1-2 周)
- 端到端测试
- 性能优化
- 文档完善
10. 与现有代码的兼容性
10.1 保留的文档
CLAUDE.md- 作为参考文档Claude2.md- GoT 实现参考deepresearchprocess.md- 流程参考examples/- 输出示例
10.2 新增的文档
PROJECT_UNDERSTANDING.md- 本文档IMPLEMENTATION_GUIDE.md- 实施指南.claude/skills/- Skills 定义.claude/commands/- Commands 定义
10.3 迁移策略
- 渐进式迁移: 先实现基础功能，再添加高级特性
- 向后兼容: 保留原有的手动工作流程
- A/B 测试: 比较新旧方法的输出质量
11. 成功指标
11.1 功能性指标
- 能够完全用 Claude Code 完成深度研究（无需 ChatGPT）
- 输出质量达到或超过示例标准
- 所有声明都有正确的引用
- 研究时间 < 30 分钟（对于 50,000 词报告）
11.2 用户体验指标
- 单命令执行:
/deep-research [topic] - 交互式澄清: 自动询问必要细节
- 进度可见: TodoWrite 跟踪进度
- 可中断和恢复: 保存中间状态
11.3 技术指标
- Context 使用效率 > 80%
- 智能体并行度 ≥ 5
- 引用准确率 > 95%
- 幻觉率 < 5%
12. 总结和下一步
12.1 核心价值
这个项目展示了一种使用 Claude Code 实现高质量深度研究的方法论。通过系统化的 7 阶段流程、Graph of Thoughts 框架和多智能体协作，可以生成超越传统单次查询的综合研究报告。
12.2 改进方向
将 ChatGPT 依赖替换为 Claude Code 原生 Skills 和 Commands，实现：
- 更流畅的工作流程
- 更好的集成和自动化
- 更低的复杂度和成本
- 更充分利用 Claude Code 的能力
12.3 立即行动
- 审查本理解文档的准确性
- 确认优先级和范围
- 开始实施 Phase 1: 基础 Skills
- 迭代开发和测试
文档版本: 1.0 最后更新: 2025-12-25 作者: Claude (Sonnet 4.5)