Initiation

AGENTS.md

@@ -0,0 +1,124 @@
+# Open Deep Research 仓库概览
+
+## 项目描述
+
+Open Deep Research 是一个可配置、完全开源的深度研究智能体(deep research agent)，支持多个模型提供商、搜索工具以及 MCP（Model Context Protocol，模型上下文协议）服务器。它能够通过并行处理自动执行研究任务，并生成内容全面的研究报告。
+
+## 仓库结构
+
+### 根目录
+
+* `README.md` - 完整的项目文档，包含快速入门指南
+* `pyproject.toml` - Python 项目配置与依赖声明
+* `langgraph.json` - LangGraph 配置文件，用于定义主图(Graph)的入口点
+* `uv.lock` - UV 包管理器的依赖锁定文件
+* `LICENSE` - MIT 许可证
+* `.env.example` - 环境变量模板（不受版本控制追踪）
+
+### 核心实现（`src/open_deep_research/`）
+
+* `deep_researcher.py` - LangGraph 的主要实现文件（入口点：`deep_researcher`）
+* `configuration.py` - 配置管理与设置
+* `state.py` - 图状态(Graph state)定义与数据结构
+* `prompts.py` - 系统提示词与提示词模板
+* `utils.py` - 工具函数与辅助功能
+* `files/` - 研究输出文件与示例文件
+
+### 遗留实现（`src/legacy/`）
+
+包含两种早期的研究实现：
+
+* `graph.py` - 带有人机协同(human-in-the-loop)机制的规划与执行(plan-and-execute)工作流
+* `multi_agent.py` - 监督者—研究员(supervisor-researcher)多智能体架构
+* `legacy.md` - 遗留实现的说明文档
+* `CLAUDE.md` - 面向遗留实现的 Claude 专用指令
+* `tests/` - 遗留实现专用测试
+
+### 安全模块（`src/security/`）
+
+* `auth.py` - 用于 LangGraph 部署的身份验证处理程序
+
+### 测试（`tests/`）
+
+* `run_evaluate.py` - 主评估脚本，配置为在 Deep Research Bench 上运行
+* `evaluators.py` - 专用评估函数
+* `prompts.py` - 评估提示词与评估标准
+* `pairwise_evaluation.py` - 对比评估工具
+* `supervisor_parallel_evaluation.py` - 多线程并行评估
+
+### 示例（`examples/`）
+
+* `arxiv.md` - ArXiv 研究示例
+* `pubmed.md` - PubMed 研究示例
+* `inference-market.md` - 推理市场分析示例
+
+### 手把手教学（deep_research_from_scratch/）
+* 改文件夹下放的该项目进面向人类初学者的教学jupyter notebook内容，可视为与本项目的实际运行和使用完全解耦的模块
+
+## 核心技术
+
+* **LangGraph** - 工作流编排与图执行(Graph execution)
+* **LangChain** - 大语言模型集成与工具调用(tool calling)
+* **多个 LLM 提供商** - 支持 OpenAI、Anthropic、Google、Groq 和 DeepSeek
+* **搜索 API** - 支持 Tavily、OpenAI/Anthropic 原生搜索、DuckDuckGo 和 Exa
+* **MCP Servers** - 通过 Model Context Protocol 扩展智能体能力
+
+# Open Deep Research 智能体工作规范
+
+## 启动流程（Startup Workflow）
+
+开始修改前：
+
+1. 确认位于仓库根目录并阅读 `README.md`。
+2. 阅读 `feature_list.json`、`progress.md` 和 `session-handoff.md`。
+3. 执行 `git status --short`，保留用户已有及无关改动。
+4. 一次只处理一个功能（One feature at a time）。
+5. 运行 `./init.sh`；若基线失败，先记录证据再修改。
+
+缺少开发依赖时执行 `uv sync --extra dev`。
+
+## 项目范围（Scope）
+
+核心代码位于 `src/open_deep_research/`，认证代码位于 `src/security/`，
+评估工具位于 `tests/`，遗留实现位于 `src/legacy/`。
+`deep_research_from_scratch/` 是独立教学模块，除非当前功能明确要求，否则不要修改。
+
+- 不得静默扩大功能范围。
+- 不得覆盖或清理无关工作树改动。
+- 不得提交 `.env`、API 密钥、私有 MCP 配置或敏感报告。
+
+## 状态文件
+
+- `feature_list.json`：功能 status、dependencies 和 evidence 的唯一来源。
+- `progress.md`：记录当前状态、决定、阻塞项、文件和下一步。
+- `session-handoff.md`：跨会话恢复入口。
+- `init.sh`：统一验证入口。
+
+状态仅使用 `not-started`、`in-progress`、`blocked`、`completed`。
+
+## 验证命令（Verification Commands）
+
+```bash
+./init.sh
+```
+
+脚本执行源码编译、Ruff、mypy 和遗留测试收集。它不会运行
+`python tests/run_evaluate.py`，因为完整评估依赖外部服务并可能产生费用。
+
+## 完成标准（Definition of Done）
+
+功能只有同时满足以下条件才算完成：
+
+- 范围内行为已实现。
+- 相关验证已运行并通过。
+- 命令结果或其他证据已记录。
+- 相关文档已更新。
+- 状态文件足以让下一会话独立恢复。
+
+## 会话结束（End of Session）
+
+1. 更新功能 status 和 evidence。
+2. 在 `progress.md` 记录验证、文件、阻塞项和下一步。
+3. 未完成时更新 `session-handoff.md`。
+4. 检查 `git status --short`。
+5. 留下 clean、可重复验证且不依赖聊天记录的恢复路径。

README.md

@@ -28,13 +28,26 @@ uv venv
 source .venv/bin/activate  # On Windows: .venv\Scripts\activate
 ```
 
+```bash
+git clone https://github.com/langchain-ai/open_deep_research.git
+cd open_deep_research
+
+conda create -n open-deep-research python=3.11 -y
+conda activate open-deep-research
+python -m pip install --upgrade pip setuptools wheel
+```
+
 2. Install dependencies:
 ```bash
 uv sync
 # or
 uv pip install -r pyproject.toml
 ```
 
+```bash
+pip install -e . # 可编辑模式安装当前目录中的项目，并基于pyproject.toml进行依赖解析
+```
+
 3. Set up your `.env` file to customize the environment variables (for model selection, search tools, and other configuration settings):
 ```bash
 cp .env.example .env

feature_list.json

@@ -0,0 +1,12 @@
+{
+  "features": [
+    {
+      "id": "harness-001",
+      "name": "初始化最小可用智能体 Harness",
+      "description": "在不修改业务代码的前提下，建立指令、状态、验证、范围控制和会话交接机制。",
+      "dependencies": [],
+      "status": "completed",
+      "evidence": "五个 Harness 文件已生成；结构验证 100/100（25/25），JSON 与格式检查通过，未修改业务代码。"
+    }
+  ]
+}

init.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+set -e
+
+echo "=== Open Deep Research Harness 验证 ==="
+
+echo "=== 编译 Python 源码 ==="
+python -m compileall -q src
+
+echo "=== Ruff 检查 ==="
+python -m ruff check .
+
+echo "=== mypy 类型检查 ==="
+python -m mypy src
+
+echo "=== 收集遗留测试（不调用外部 API）==="
+python -m pytest --collect-only -q src/legacy/tests
+
+echo "=== 验证完成 ==="
+echo "读取 feature_list.json，选择一个功能，并在 progress.md 记录证据。"

progress.md

@@ -0,0 +1,48 @@
+# 会话进度记录
+
+## 当前状态（Current State）
+
+**最后更新（Last Updated）：** 2026-06-21
+**当前功能：** `harness-001`
+**状态：** 已完成
+
+## 已完成（What's Done）
+
+- 创建五个最小 Harness 文件。
+- 配置不调用外部模型或搜索 API 的日常检查。
+- 保留业务代码和已有无关改动。
+
+## 最终检查（What's In Progress）
+
+- 五个 Harness 子系统全部通过验证。
+- JSON、格式和 Git 变更范围检查通过。
+
+## 下一步（What's Next）
+
+1. 后续修改业务代码前新增一个具体功能。
+2. 缺少工具时运行 `uv sync --extra dev`。
+3. 运行 `./init.sh` 并记录结果。
+
+## 阻塞项与风险（Blockers / Risks）
+
+- Ruff、mypy 和 pytest 需要开发环境。
+- 遗留质量测试调用外部服务，因此 `init.sh` 只收集测试。
+
+## 本次修改文件（Files Modified This Session）
+
+- `AGENTS.md`
+- `feature_list.json`
+- `progress.md`
+- `init.sh`
+- `session-handoff.md`
+
+## 验证证据（Verification Evidence）
+
+- 结构验证：`100/100`，共 `25/25` 项通过。
+- JSON 与格式检查：通过。
+- 业务文件变更范围检查：通过。
+- 业务代码测试：本次未修改业务代码，无需执行。
+
+## 下次会话说明
+
+读取全部状态文件并运行 `./init.sh` 后，再开始具体功能。

session-handoff.md

@@ -0,0 +1,42 @@
+# 会话交接
+
+## 当前目标（Current Objective）
+
+- 目标：初始化并验证最小可用智能体 Harness。
+- 当前状态：已完成，所有结构检查通过。
+- 分支 / 提交：当前工作树，未创建提交。
+
+## 本次已完成
+
+- 添加指令、状态、验证、范围和生命周期文件。
+- 保持业务代码不变。
+
+## 验证证据
+
+| 检查 | 命令 | 结果 | 备注 |
+|---|---|---|---|
+| 结构验证 | `validate-harness.mjs --target .` | 通过 | 100/100，25/25 项 |
+| 功能清单 | JSON 解析与格式检查 | 通过 | JSON 有效，无尾随空格 |
+| 变更范围 | Git 路径检查 | 通过 | 未修改业务代码或项目配置 |
+
+## 修改文件（Files Changed）
+
+- `AGENTS.md`
+- `feature_list.json`
+- `progress.md`
+- `init.sh`
+- `session-handoff.md`
+
+## 阻塞项与风险（Blockers / Risks）
+
+- 当前 Python 环境缺少 Ruff、mypy 和 pytest；运行完整 `init.sh` 前需执行 `uv sync --extra dev`。
+
+## 下次会话启动（Next Session）
+
+1. 阅读 `AGENTS.md`、`feature_list.json` 和 `progress.md`。
+2. 查看本交接文件与 `git status --short`。
+3. 修改前运行 `./init.sh`。
+
+## 建议下一步（Recommended Next Step）
+
+- 修改业务代码前，在 `feature_list.json` 新增一个具体功能。