1 line
9.2 KiB
JSON
1 line
9.2 KiB
JSON
{"repo": "arkrolin/deepresearch-agent-skills", "files": {"README.md": {"42095e6d42255dfd8303dd7dfde037eec1527994": {"t": 1785746448.782212, "n": 5528, "h": "f02966e46a69151c", "c": "# Deep Research Agent\n\n[](https://www.python.org/downloads/)\n[](https://github.com/arkrolin/deepresearch-agent)\n[](LICENSE)\n\n基于大语言模型的多智能体深度研究系统。像人类研究员一样完成**拆解问题 → 执行搜索 → 记忆复用 → 批判审视 → 验证修正**的完整研究链路，最终输出结构化、可验证的研究报告。\n\n```\n研究问题\n │\n ▼\n┌───────────────────────────────────────────────────┐\n│ M2 规划器: LLM 拆解为子任务 DAG │\n└───────────────────────────────────────────────────┘\n │\n ▼\n┌───────────────────────────────────────────────────┐\n│ M1 编排器: 11 状态 FSM + 4 级降级执行 │\n│ (容忍 → 修补 → 重规划 → 强制合成) │\n└───────────────────────────────────────────────────┘\n │\n ▼\n┌───────────────────────────────────────────────────┐\n│ M3 压缩器: 三级语义过滤 │\n│ (动态分位数 → TextRank → 原文保留) │\n└───────────────────────────────────────────────────┘\n │\n ▼\n┌───────────────────────────────────────────────────┐\n│ M5 QA 循环: 双 Agent 完备性验证 │\n│ \"报告是否完整回答了这些核心问题？\" │\n└───────────────────────────────────────────────────┘\n │\n ▼\n┌───────────────────────────────────────────────────┐\n│ M6 对抗循环: 红蓝 Agent 强健性挑战 │\n│ \"事实性 · 逻辑 · 引用 · 覆盖面 · 时效\" │\n└───────────────────────────────────────────────────┘\n │\n ▼\n 研究报告\n```\n\n## 架构概览\n\n### 六大核心模块\n\n| 模块 | 职责 | 关键能力 |\n|------|------|----------|\n| **M1 编排器** | 中央执行引擎 | 自定义 DAG 调度器、11 状态 FSM、4 级降级（单节点容忍 → 局部修补 → 全局重规划 → 超时强制合成） |\n| **M2 规划器** | 问题拆解 | LLM 驱动任务分解、JSON DAG 动态生成、环路检测 + 多后端重试、幽灵依赖过滤、缺口补充规划 |\n| **M3 压缩器** | 长上下文压缩 | L1 动态分位数粗筛、L2 Query-Biased TextRank 关键句提取、L3 Token 预算组装 |\n| **M4 记忆库** | 跨 Agent 共享记忆 | SQLite + FAISS 向量索引、余弦去重（>0.92）、矛盾检测（启发式 + 数值 + 语义）、LRU 淘汰、会话隔离 |\n| **M5 QA 循环** | 完备性验证 | Q Agent 生成评分量规、A Agent 自评回答（2/1/0 分制）、缺口驱动的重规划、收敛：≥8.0 分或 3 轮 |\n| **M6 对抗循环** | 强健性挑战 | Red Agent 5 维结构化缺陷检测、Controller 震荡检测（余弦 > 0.9）、Blue Agent 基于记忆库的 Diff 修补（增/删/改/验） |\n\n### 横向能力\n\n- **LLM 路由器**: 基于 LiteLLM 的多后端路由，支持 DeepSeek / OpenAI / MiMo 的自动故障转移链\n- **流式 + 非流式**: 统一的异步接口，覆盖所有后端\n\n## 快速开始\n\n### 环境要求\n\n- Python 3.11+\n- [uv](https://docs.astral.sh/uv/)（推荐）或 pip\n\n### 安装\n\n```bash\ngit clone https://github.com/arkrolin/deepresearch-agent.git\ncd deepresearch-agent\nuv sync\n```\n\n### 配置 LLM API 密钥\n\n通过环境变量配置：\n\n```bash\nexport DEEPRESEARCH_MODELS='{\"reasoning\":\"deepseek/deepseek-chat\",\"fast\":\"openai/gpt-4o-mini\",\"embedding\":\"openai/text-embedding-3-small\"}'\nexport DEEPRESEARCH_FALLBACK=\"deepseek/deepseek-chat,openai/gpt-4o-mini\"\nexport DEEPSEEK_API_KEY=\"sk-...\"\nexport OPENAI_API_KEY=\"sk-...\"\n```\n\n或使用 YAML 配置文件：\n\n```yaml\n# config.yaml\nmodels:\n reasoning: \"deepseek/deepseek-chat\"\n fast: \"openai/gpt-4o-mini\"\n embedding: \"openai/text-embedding-3-small\"\nfallback_chain:\n - deepseek/deepseek-chat\n - openai/gpt-4o-mini\n```\n\n### 使用方式\n\n**命令行:**\n\n```bash\n# 快速研究\ndeepresearch run \"量子计算最近有哪些突破？\" --depth deep --output report.md\n\n# 从 JSON 任务文件执行\ndeepresearch run task.json --config config.yaml\n\n# 评测（Phase 5 规划中）\ndeepresearch eval --dataset hotpotqa --metrics factuality,hallucination,coverage,logic\n```\n\n**Python API:**\n\n```python\nfrom deepresearch import DeepResearch\nfrom deepresearch.config import RouterConfig\nfrom deepresearch.llm.router import LLMRouter\n\nrouter = LLMRouter(RouterConfig.from_yaml(\"config.yaml\"))\nagent = DeepResearch(llm=router)\n\nreport = await agent.research(\n \"Transformer 架构对 NLP 领域产生了哪些影响？\",\n depth=\"deep\",\n max_time=600,\n)\nprint(report.status, report.metrics)\n```\n\n### 运行测试\n\n```bash\nuv run pytest tests/ -v\n# 170 个测试全部通过\n```\n\n## 开发流程\n\n### 分支策略\n\n```\nmaster ← Phase 1：基础骨架\n ├── v0.2.0-alpha.1 ← Phase 2：M2 规划器 + M3 压缩器 (133 tests)\n ├── v0.3.0-alpha.1 ← Phase 3：M5 QA 验证循环 (150 tests)\n ├── v0.4.0-alpha.1 ← Phase 4：M6 对抗循环 (170 tests)\n └── v0.5.0-alpha.1 ← Phase 5：评测框架（规划中）\n```\n\n每个阶段分支独立开发 → 设计审查 → 实现 → 测试 → 代码审查 → 修复 → 推送。各阶段递进且向后兼容。\n\n### 项目结构\n\n```\ndeepresearch/\n├── api.py # 公共 Python API\n├── cli.py # 命令行入口 (click)\n├── config.py # 配置管理 (YAML + 环境变量)\n├── core/ # 执行引擎\n│ ├── orchestrator.py # M1: DAG 执行 + 11 状态 FSM\n│ ├── dag.py # DAG 图 + 拓扑排序\n│ ├── state_machine.py# FSM 状态转移表\n│ ├── degradation.py # 4 级降级监控\n│ └── planner.py # M2: LLM 驱动问题拆解\n├── memory/ # 共享记忆\n│ ├── store.py # M4: SQLite + FAISS 统一接口\n│ ├── vector.py # FAISS 索引封装\n│ ├── dedup.py # 余弦去重门控\n│ ├── contradiction.py# 矛盾检测与消解\n│ └── eviction.py # LRU 淘汰追踪\n├── llm/ # 模型路由\n│ ├── router.py # LiteLLM 封装 + 故障转移\n│ └── config.py # 路由器配置\n├── compressor/ # M3: 上下文压缩\n│ ├── compressor.py # 三级过滤管道\n│ └── textrank.py # Query-Biased TextRank\n├── qa/ # M5: QA 验证\n│ ├── loop.py # Q/A Agent 循环\n│ └── scorer.py # 评分逻辑\n└── adversarial/ # M6: 对抗审查\n ├── loop.py # 红蓝 Agent Actor Model\n ├── controller.py # 震荡检测 + 收敛判定\n └── diff_engine.py # Diff 操作引擎\n```\n\n## 核心设计决策\n\n**无重量级框架依赖。** DAG 引擎、状态机和记忆库均基于 asyncio + SQLite + FAISS 从零构建。仅 LiteLLM 用于跨模型供应商适配。\n\n**记忆优先的修补机制。** Blue Agent（M6）永不发起外部网络请求。所有报告修补均基于 M4 记忆库中已有的内容，确保事实依据可溯源、杜绝幻觉扩散。\n\n**缺口驱动的闭环比规划。** QA Loop（M5）不仅评分——它生成结构化的缺口报告，反馈给规划器（M2）生成补充 DAG 节点，形成完整的质量提升闭环。\n\n**震荡感知的收敛控制。** 对抗循环通过 Flaw History Ledger 追踪已修复的缺陷。当 Red Agent 重新提出已修复问题（余弦相似度 > 0.9），系统优雅终止、保留上一轮干净草稿、并将争议点作为\"研究局限性\"附在报告末尾。\n\n## 许可证\n\nMIT"}}}} |