一个基于 AgenticX 构建的深度研究助手。系统支持 Basic 与 Advanced 两种研究模式，集成搜索、内容抓取、总结、报告生成、协议服务与持久化能力，适合对复杂主题进行可追踪、可扩展的研究分析。
本项目的主线已经从早期的单一 workflows/unified_research_workflow.py 演进为 flows/ 驱动的 v2 架构：
BasicResearchFlow: 面向明确问题的快速深度研究。AdvancedResearchFlow: 面向复杂主题的规划、搜索、总结、反思和收敛流程。workflows/: 保留兼容层与旧版深搜流程，便于历史代码迁移。server/: 提供 FastAPI、SSE、A2A、MCP 与 NEAR 适配能力。
- 基础模式 (Basic): 生成多条搜索查询，抓取内容，汇总证据并输出研究报告。
- 高级模式 (Advanced): 引入规划、知识缺口识别、多轮搜索、并发总结和质量收敛。
- Token 预算控制: 通过
token_budget.py对上下文、摘要和报告生成进行预算管理。 - 内容获取增强:
tools/content_fetch.py提供 Jina Reader 兼容抓取、超时控制、回退与内容清洗。
- 规划智能体: 制定研究策略，识别知识缺口。
- 查询生成智能体: 根据研究目标和上下文生成多条高覆盖查询。
- 研究总结智能体: 并发分析搜索结果，抽取关键事实、风险和后续问题。
- 报告写作智能体: 输出结构化 Markdown 研究报告。
- 搜索工具: 支持 BochaaI、Bing、Google 与测试 Mock 场景。
- FastAPI 服务:
server/api.py提供 HTTP API。 - SSE 事件流:
server/sse.py支持流式研究进度。 - A2A / MCP / NEAR 适配:
server/near_adapter.py暴露协议兼容端点。 - 数据库管理:
db/manager.py管理研究任务、事件和结果持久化。
系统采用分层架构：用户通过 CLI、HTTP API 或协议入口发起研究任务，服务层负责任务编排、实时事件和状态持久化，工作流层根据模式选择 Basic 或 Advanced Flow，Agent 与工具层完成搜索、抓取、总结和报告生成。
Basic 模式面向明确研究问题，主链路是生成查询、执行搜索、抓取内容、总结证据并输出报告。
Advanced 模式增加研究规划、知识缺口识别、多轮迭代和收敛判断，适合复杂主题的深度探索。
服务化流程覆盖任务创建、状态持久化、后台执行、SSE 进度推送和最终结果获取。
内容处理流程强调从搜索结果到网页正文、清洗、Token 预算、并发总结和报告证据链的生成过程。
git clone https://github.com/DemonDamon/AgenticX-DeepResearch.git
cd AgenticX-DeepResearchpip install -r requirements.txtcp env_template.txt .env常用变量：
| 变量名 | 说明 | 必需 | 默认值 |
|---|---|---|---|
KIMI_API_KEY |
Kimi API 密钥 | 是 | - |
KIMI_API_BASE |
Kimi API 地址 | 否 | https://api.moonshot.cn/v1 |
KIMI_MODEL_NAME / KIMI_MODEL |
Kimi 模型名称 | 否 | moonshot-v1-32k |
BOCHAAI_API_KEY |
BochaaI 搜索密钥 | 否 | - |
BING_API_KEY |
Bing Search 密钥 | 否 | - |
GOOGLE_API_KEY |
Google Search 密钥 | 否 | - |
SEARCH_ENGINE |
搜索引擎选择 | 否 | bochaai |
python -m pytest -q当前完整测试基线：108 passed, 1 skipped。
# 基础模式
python main.py "ChatGPT 对教育行业的影响" --mode basic
# 高级模式
python main.py "区块链技术应用" --mode advanced
# 不传 topic 时会进入命令行输入
python main.py当前
main.py仅支持basic与advanced两种模式。早期文档中的interactive参数和--max_research_loopsCLI 参数已经不再是当前入口能力。
uvicorn server.api:app --reload --host 0.0.0.0 --port 8000服务层覆盖：
- 研究任务创建、查询和结果获取。
- 流式事件推送。
- A2A、MCP、NEAR 兼容协议端点。
- 能力矩阵与服务注册信息。
AgenticX-DeepResearch/
├── .plan/ # 分阶段计划与 TDD 路线
├── .conclusions/ # 架构与模块总结
├── agents/ # 规划、查询、总结、报告等智能体
├── db/ # 数据模型与数据库管理
├── docs/
│ ├── capability_matrix.md # 能力矩阵
│ └── refactoring/ # 阶段重构报告
├── flows/ # v2 Basic / Advanced Flow
├── interactive/ # 交互和进度组件
├── report/ # 引文、质量评估和报告构建
├── server/ # FastAPI、SSE、协议适配
├── tests/ # 单元、集成、协议和 P0 回归测试
├── tools/ # 搜索、内容抓取、分析和验证工具
├── workflows/ # 兼容工作流与旧版深搜流程
├── main.py # CLI 入口
├── models.py # 领域模型
├── token_budget.py # Token 预算工具
├── config.yaml # 默认配置
├── env_template.txt # 环境变量模板
├── requirements.txt # Python 依赖
├── Dockerfile
└── DEPLOYMENT.md
- P0 Kimi Gap TDD Roadmap: P0 能力补齐的分阶段计划。
- Capability Matrix: 当前功能与协议能力矩阵。
- Refactoring Reports: Phase 1 到 Phase 6 的重构报告归档。
- Deployment Guide: 部署说明。
config.yaml 中的主要配置：
llm.provider: LLM 提供者，默认kimi。llm.model: 模型名称。search.engine: 搜索引擎，默认bochaai。deep_search.max_research_loops: 深度搜索循环配置，主要供兼容工作流使用。deep_search.max_search_results: 每次搜索的最大结果数。
| 特性 | 实现方式 | 优势 |
|---|---|---|
| Flow 架构 | flows/basic_flow.py 与 flows/advanced_flow.py |
当前入口清晰，便于扩展 |
| 内容抓取 | Jina Reader 兼容抓取与回退策略 | 提升真实网页内容利用率 |
| 查询覆盖 | 默认 10 条查询生成 | 提升复杂主题召回率 |
| 并发总结 | 多来源结果并发处理 | 降低等待时间 |
| Token 预算 | token_budget.py |
控制上下文长度与成本 |
| 协议适配 | FastAPI + SSE + A2A + MCP + NEAR | 支持服务化集成 |
| 测试闭环 | 单元、集成、协议和 P0 回归测试 | 变更可验证 |
- API 密钥错误: 检查
.env中的KIMI_API_KEY。 - 搜索无结果: 确认
SEARCH_ENGINE与对应 API Key 是否匹配。 - Bing 搜索失败: 当前代码读取
BING_API_KEY，不要只配置旧名BING_SUBSCRIPTION_KEY。 - 内容抓取超时: 检查网络环境，系统会自动进行回退处理。
- 测试产生本地文件:
research.db、output/和.DS_Store属于本地运行产物，不应提交。
# 完整测试
python -m pytest -q
# 只运行 P0 能力回归
python -m pytest tests/test_p0_gap_closure.py -q
# 只运行服务协议测试
python -m pytest tests/test_server_v1.py tests/test_phase6_protocols.py -qMIT License