# ai-science

**Repository Path**: ricky-theseus/ai-science

## Basic Information

- **Project Name**: ai-science
- **Description**: version A
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-24
- **Last Updated**: 2026-09-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# 🧬 AI Scientist Agent

**双管线科学前沿问题研究系统 · Classic 7-Agent + Co-Scientist Elo Tournament**

[![Python 3.11](https://img.shields.io/badge/Python-3.11-blue.svg)](https://www.python.org/downloads/)
[![LangGraph](https://img.shields.io/badge/LangGraph-1.2+-green.svg)](https://github.com/langchain-ai/langgraph)
[![Qwen](https://img.shields.io/badge/LLM-Qwen_Max-purple.svg)](https://dashscope.aliyun.com/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.138+-teal.svg)](https://fastapi.tiangolo.com/)
[![Tests](https://img.shields.io/badge/Tests-1068_passed-brightgreen.svg)]()
[![V4.4](https://img.shields.io/badge/Version-V4.4_Co--Scientist-orange.svg)]()

2026 挑战杯 · 阿里云专项赛（XH-202619）

</div>

---

## 目录

- [项目简介](#项目简介)
- [双管线架构](#双管线架构)
  - [Classic 管线（文件驱动 · 7-Agent 协同）](#classic-管线文件驱动--7-agent-协同)
  - [Co-Scientist 管线（Checkpoint 驱动 · Elo 竞技循环）](#co-scientist-管线checkpoint-驱动--elo-竞技循环)
  - [管线切换（PIPELINE_MODE）](#管线切换pipeline_mode)
- [设计思路](#设计思路)
  - [迭代自优化机制](#迭代自优化机制)
  - [Judge 驱动的动态终止](#judge-驱动的动态终止)
  - [Rubric 8 维度评估体系](#rubric-8-维度评估体系)
  - [精度回滚与幂等写入](#精度回滚与幂等写入)
  - [结构化直出策略](#结构化直出策略)
  - [事实核查与反幻觉](#事实核查与反幻觉)
- [项目结构](#项目结构)
- [快速开始](#快速开始)
- [API 接口](#api-接口)
- [配置说明](#配置说明)
- [测试](#测试)
- [参考项目](#参考项目)
- [许可证](#许可证)

---

## 项目简介

AI Scientist Agent 接收 **Science 125 个前沿科学问题**之一，通过 7 个专业化 Agent 的协同工作，自动完成从问题分解到论文撰写的全流程研究：

```
输入: "后量子密码学的当前方法有哪些？它们在安全性和效率方面如何比较？"
  ↓
7-Agent 协同研究管线（多轮迭代）
  ↓
输出: 结构化研究报告（PDF / LaTeX / Markdown）+ 37篇引用论文 + 2个科学假设 + 证据验证
```

**核心特性：**

- 🔬 **双管线架构** — Classic 7-Agent 文件驱动管线 + Co-Scientist Elo 竞技循环管线，零冲突共存（ADR-12）
- 🔄 **多轮迭代自优化** — Judge 驱动的质量门控 + 反馈循环，自动决定继续迭代或输出
- 🏆 **Elo 锦标赛排名** — 假设两两对决、Elo 评分排序、近邻配对、6 策略进化变异
- 📊 **Rubric 8 维度评估** — 5 假设维度（Popper/Lakatos/Hempel 锚定）+ 3 计划维度，加权评分只记录不做门禁
- 📄 **双持久化模式** — Classic 文件驱动（JSON 文件流 + 断点续跑）| Co-Scientist Checkpoint 驱动（AsyncSqliteSaver + 状态恢复）
- 🧪 **事实核查 + 反幻觉** — 5 条确定性规则 + LLM 引用语义校验，杜绝伪造数据和虚假引用
- 📡 **REST API + SSE 实时推送** — 16 个端点 + 双模式 SSE（Classic 磁盘轮询 / Co-Scientist Checkpoint diff）
- ✅ **1068 项单元测试** — 全量 mock，零 API 调用即可跑通

---

## 双管线架构

系统提供**两套零冲突共存的管线**（ADR-12），通过 `PIPELINE_MODE` 环境变量切换：

| 特性 | Classic（`classic`） | Co-Scientist（`co-scientist`） |
|---|---|---|
| **拓扑** | 线性 7 节点 + 条件重跑边 | 循环 9 节点 + budget 驱动条件边 |
| **状态** | `PipelineState`（7 字段 thin TypedDict） | `CoScientistState`（20+ 字段，含 Pydantic 模型） |
| **持久化** | 文件驱动（`data/runs/{run_id}/*.json`） | Checkpoint 驱动（`AsyncSqliteSaver`） |
| **假设管理** | 扁平列表，每轮覆盖 | Elo 锦标赛排名 + 近邻配对 + 进化变异 |
| **迭代控制** | Feedback Agent 评分 + 收敛计数器 | Budget（成本/轮数/假设数）三重终止 |
| **输出** | 7 阶段 JSON + LaTeX/PDF | 10 字段报告 + LaTeX/PDF |
| **断点续跑** | 检测已存在阶段文件跳过 | LangGraph checkpoint 自动恢复 |
| **SSE 推送** | 磁盘轮询（`disk_poll`） | Checkpoint diff（`checkpoint_diff`） |
| **适用场景** | 单题深研、调试、Demo | 多假设竞技、成本控制、长时间运行 |

### Classic 管线（文件驱动 · 7-Agent 协同）

传统 LLM 应用通常将状态保存在内存中，一旦进程崩溃则全部丢失。Classic 管线采用**文件驱动架构（File-Driven Architecture）**，将管线的控制流与业务数据完全分离：

```mermaid
graph TB
    subgraph "PipelineState（控制流 — 7 字段）"
        S1["run_id"]
        S2["run_dir"]
        S3["iteration"]
        S4["current_stage"]
        S5["error"]
        S6["max_iterations"]
        S7["human_feedback"]
    end

    subgraph "data/runs/q_xxx/（业务数据 — 文件系统）"
        F1["00_input.json"]
        F2["01_supervisor_i1.json"]
        F3["02_literature_i1.json"]
        F4["03_hypothesis_i1.json"]
        F5["04_evidence_i1.json"]
        F6["05a_reflection_pre_i1.json"]
        F7["05b_reflection_merge_i1.json"]
        F8["06_feedback_i1.json"]
        F9["07_writer.json"]
        F10["final_report.json"]
        F11["paper.pdf"]
    end

    S2 -->|"读写路径"| F1
    S2 -->|"读写路径"| F2
    S2 -->|"读写路径"| F3
    S2 -->|"读写路径"| F9
```

**设计优势：**

| 特性 | 内存状态 | 文件驱动 |
|------|---------|---------|
| 进程崩溃恢复 | ❌ 全部丢失 | ✅ 从文件续跑 |
| API 无状态 | ❌ 需 Session | ✅ 每次从文件读取 |
| 断点调试 | ❌ 不可回溯 | ✅ 任意阶段可回看 |
| 并发安全 | ❌ 需加锁 | ✅ 文件系统天然隔离 |
| 前端解耦 | ❌ 绑定 WebSocket | ✅ REST + SSE 独立消费 |

7 个 Agent 按序执行，每个完成后将结果写入对应的 JSON 文件，下游 Agent 从文件读取上游产出：

```mermaid
graph LR
    START((START)) --> Sup[Supervisor<br/>问题分解]
    Sup --> Lit[Literature<br/>文献检索]
    Lit --> Hyp[Hypothesis<br/>假设生成]
    Hyp --> Evi[Evidence<br/>证据验证]
    Evi --> RP[Reflection-Pre<br/>初步评分]
    RP --> RM[Reflection-Merge<br/>综合评分]
    RM --> FB[Feedback<br/>反馈决策]
    FB -->|ready_for_output=true| Wrt[Writer<br/>论文撰写]
    FB -->|ready_for_output=false<br/>且 iter < max| Lit
    Wrt --> END((END))

    style Sup fill:#e1f5fe
    style Lit fill:#fff3e0
    style Hyp fill:#e8f5e9
    style Evi fill:#fce4ec
    style RP fill:#f3e5f5
    style RM fill:#f3e5f5
    style FB fill:#fff9c4
    style Wrt fill:#e0f2f1
```

### Co-Scientist 管线（Checkpoint 驱动 · Elo 竞技循环）

受 Google Co-Scientist 论文（arXiv:2502.18864）启发，Co-Scientist 管线将假设管理从"每轮覆盖"升级为**Elo 锦标赛竞技循环**——假设两两对决、评分排序、近邻配对、进化变异，budget 驱动自动终止：

```mermaid
graph TB
    START --> Supervisor
    Supervisor --> Generation
    Generation --> Reflection
    Reflection --> Proximity
    Proximity --> Ranking
    Ranking --> Evolution
    Evolution --> MetaReview
    MetaReview -->|budget 未超额| Generation
    MetaReview -->|budget 超额| Render
    Render --> END

    style Generation fill:#e3f2fd
    style Reflection fill:#fff3e0
    style Ranking fill:#fce4ec
    style Evolution fill:#e8f5e9
    style MetaReview fill:#f3e5f5
    style Render fill:#e0f2f1
```

**核心节点：**

| 节点 | 职责 | 关键机制 |
|---|---|---|
| **Supervisor** | 解析研究目标，设定初始配置 | 生成 `goal` + `constraints` |
| **Generation** | 基于 goal + 进化提示生成新假设 | 6 策略（combinatorial / fact_density / inverse / mutation / recombination / random）|
| **Reflection** | 对每个假设做同行评审 + 幻觉检测 | 输出 `ReviewRecord`，标记 is_halucination |
| **Proximity** | 构建假设嵌入图，发现近邻簇 | DashScope text-embedding-v3，阈值 0.85 |
| **Ranking** | Elo 锦标赛两两对决，排名排序 | 初始 Elo 1200，K=32，3/2 维持因子 |
| **Evolution** | 根据 Elo 排名 + 近邻配对生成进化提示 | Matchmaker 近邻优先配对 + 去重 |
| **MetaReview** | 全局评估本轮进化质量，决定继续或终止 | Budget 三重终止：成本 / 轮数 / 假设数 |
| **Render** | 生成 10 字段报告 + LaTeX + PDF | ReportRenderer 输出 `research_overview` + `report` |

**终止条件（ADR-7，任一满足即 → Render）：**

1. `money_spent >= budget_usd`（成本上限）
2. `len(meta_reviews) >= max_iterations`（最大迭代轮数）
3. `generation_count >= max_iterations × NUM_STRATEGIES`（辅助护栏）

**状态持久化：** `AsyncSqliteSaver`（LangGraph 原生 checkpointer），进程崩溃后自动从最近 checkpoint 恢复。

### 管线切换（PIPELINE_MODE）

两套管线**零冲突共存**（ADR-12），通过环境变量切换：

```bash
# Classic 7-Agent 文件驱动管线（默认）
export PIPELINE_MODE=classic

# Co-Scientist Elo 竞技循环管线
export PIPELINE_MODE=co-scientist
```

`pipeline_router.py` 根据 `PIPELINE_MODE` 返回对应的编译图 + SSE 策略：
- `classic` → `create_pipeline()` + `disk_poll` SSE
- `co-scientist` → `create_co_scientist_pipeline(checkpointer=...)` + `checkpoint_diff` SSE

---

## 设计思路

### 迭代自优化机制

单次 pass 的管线往往产出质量不稳定。我们引入**多轮迭代自优化**机制，由 Feedback Agent 在每轮结束时评估整体质量，决定是继续迭代还是输出结果：

```mermaid
sequenceDiagram
    participant P as Pipeline
    participant L as Literature
    participant H as Hypothesis
    participant E as Evidence
    participant R as Reflection
    participant F as Feedback

    Note over P: 第 1 轮迭代
    P->>L: 搜索文献
    P->>H: 生成假设
    P->>E: 验证证据
    P->>R: 评分反思
    P->>F: 综合反馈
    F-->>P: score=4/10, ready=false

    Note over P: 第 2 轮迭代（利用反思结果改进）
    P->>L: 补充搜索
    P->>H: 改进假设
    P->>E: 补充验证
    P->>R: 重新评分
    P->>F: 综合反馈
    F-->>P: score=7/10, ready=true

    Note over P: 输出最终报告
```

**迭代改进策略：**

- Reflection 将上轮的 `knowledge_gaps` 和 `weaknesses` 注入下轮 prompt，引导 Agent 聚焦薄弱环节
- Feedback 维护 `convergence_counter`：连续 2 轮分数无提升则强制输出，避免无效循环
- `iteration_history` 记录每轮快照，支持前后对比展示

### Judge 驱动的动态终止

每个 Agent 完成后经过两层审查，**仅当两层都通过时才继续**，否则反馈给 Agent 重试：

```mermaid
graph TD
    A[Agent 执行完成] --> B{min_iterations<br/>是否满足？}
    B -->|否| A
    B -->|是| C[Script Review<br/>确定性规则检查]
    C -->|不通过| D[反馈问题给 Agent]
    D --> A
    C -->|通过| E[Judge Review<br/>LLM 质量评估]
    E -->|不通过| D
    E -->|通过| F[✅ 终止，进入下一 Agent]

    style C fill:#e3f2fd
    style E fill:#f3e5f5
```

- **Script Review**（零成本）：确定性规则检查字段存在性、数量阈值、引用合法性
- **Judge Review**（低成本 qwen-turbo）：LLM 评估输出质量，返回 0-10 分 + 具体反馈
- **consecutive_review_fail** 计数器：连续失败 ≥ 3 次则强制通过（防止死循环）

### Rubric 8 维度评估体系

在 Judge 门控之外，系统提供一套**只记录不做门禁**的 Rubric 8 维度评分体系，锚定科学哲学经典框架，为迭代自优化提供定量改进信号：

**假设质量（5 维度）— reflection_merge 后评分：**

| 维度 | 锚定框架 | 0 / 5 / 10 锚点 |
|---|---|---|
| 可证伪性 (falsifiability) | Popper 1959 | 不可证伪 → 路径模糊 → 判别性实验二值化 |
| 新颖性 (novelty) | Lakatos 1978 | 复述已知 → 旧框架新角度 → 新理论框架 |
| 自洽性 (consistency) | 形式逻辑 | 自相矛盾 → 逻辑跳跃 → 闭环无矛盾 |
| 解释力 (explanatory_power) | Hempel 1948 | 单一现象 → 一类现象 → 统一多类现象 |
| 证据支撑 (evidence_support) | 贝叶斯认识论 | 无证据 → 间接证据 → 直接证据充分 |

**研究计划质量（3 维度）— research_plan 后评分：**

| 维度 | 0 / 5 / 10 锚点 |
|---|---|
| 可验证路径 (verifiable_path) | 无法落地 → 缺关键步骤 → 闭环可执行含判别条件 |
| 文献可信度 (literature_credibility) | 编造/不相关 → 真实但浅 → 真实权威直接支撑 |
| 跨学科迁移 (cross_disciplinary) | 只限本题 → 相邻可迁移 → 通用范式 |

- **加权总分**：按 `config/agents.yaml` 的 `rubric.hypothesis.weights` / `rubric.plan.weights` 加权汇总（默认可证伪性权重最高 0.25，可验证路径权重最高 0.45）
- **持久化**：per-iteration 文件（`05d_rubric_hypothesis_i{iter}.json` / `05e_rubric_plan_i{iter}.json`）+ `meta.json` 的 `rubric_history`，供 Phase 4 可视化画"科学目标指标随迭代的定量提升"曲线
- **注入**：上一轮低分维度（≤6）自动注入下一轮 hypothesis / research_plan 的 task prompt，引导 LLM 重点改进

### 精度回滚与幂等写入

管线支持**精确回滚**——当某个 Agent 失败时，仅删除该阶段文件，上游产出不受影响：

```mermaid
graph LR
    subgraph "迭代 1 文件"
        A1["01_supervisor_i1 ✅"]
        A2["02_literature_i1 ✅"]
        A3["03_hypothesis_i1 ❌"]
    end

    subgraph "迭代 2 文件"
        B1["01_supervisor_i1 ✅ 不变"]
        B2["02_literature_i2 ✅ 覆盖"]
        B3["03_hypothesis_i2 ✅ 重试"]
    end

    A3 -->|"删除 + 重试"| B3
    A1 -->|"保留"| B1
    A2 -->|"重写"| B2
```

**`determine_failed_stages()`** 根据 `error` 和 `feedback.failed_stages` 精确定位失败阶段，仅回滚必要的文件。幂等写入保证：同迭代号同阶段的文件可直接覆盖，无副作用。

### 结构化直出策略

不同 Agent 使用不同的结构化输出策略，兼顾准确性与效率：

```mermaid
graph TB
    subgraph "single_shot_json"
        SS["Supervisor / Reflection / Feedback<br/>无工具 Agent"]
        SS --> SS1["单次 json_object 调用"]
        SS1 --> SS2["structured_output 直接提取"]
    end

    subgraph "last_iter_json"
        LI["Literature / Evidence<br/>有工具 Agent"]
        LI --> LI1["多轮 ReAct 工具调用"]
        LI1 --> LI2["最后一轮 json_object"]
        LI2 --> LI3["structured_output 提取"]
    end

    subgraph "writer_latex"
        WL["Writer<br/>纯文本输出"]
        WL --> WL1["单次生成 LaTeX"]
        WL1 --> WL2["内容质量检查"]
        WL2 --> WL3["XeLaTeX 编译"]
    end
```

- **single_shot_json**：无工具 Agent 直接 `response_format=json_object`，一次调用搞定
- **last_iter_json**：有工具 Agent 先执行多轮工具调用，最后一轮强制输出结构化 JSON
- **writer_latex**：Writer 生成 LaTeX 后经过内容质量检查（字数、段数、引用数）+ XeLaTeX 编译，不达标则重试

### 事实核查与反幻觉

LLM 生成内容存在幻觉风险（编造数据、虚假引用、时态不一致）。我们实现**5 条确定性规则 + LLM 引用语义校验**：

```mermaid
graph TD
    L[LaTeX 输出] --> R1[Rule 1: Evidence-Gap<br/>证据不足的假设<br/>禁止确认性语言]
    L --> R2[Rule 2: Citation-Existence<br/>引用必须在<br/>Paper Registry 中]
    L --> R3[Rule 3: No-Fabrication<br/>禁止伪造<br/>实验数据]
    L --> R4[Rule 4: Tense-Consistency<br/>未验证假设<br/>使用条件时态]
    L --> R5[Rule 5: Minimum-Length<br/>每 section ≥ 400 字符<br/>总字数 ≥ 10000]

    R1 --> P{发现问题？}
    R2 --> P
    R3 --> P
    R4 --> P
    R5 --> P
    P -->|是| F[反馈给 Writer 重试]
    P -->|否| C[LLM 引用语义校验<br/>逐引用检查]

    style R1 fill:#ffcdd2
    style R2 fill:#f8bbd0
    style R3 fill:#e1bee7
    style R4 fill:#d1c4e9
    style R5 fill:#c5cae9
    style C fill:#b2dfdb
```

| 规则 | 检测目标 | 示例 |
|------|---------|------|
| Evidence-Gap | 证据不足却用确认语气 | ❌ "证明了X" → ✅ "可能X" |
| Citation-Existence | 引用不存在的论文 | ❌ `\cite{P99}` → ✅ 替换为 `[?]` |
| No-Fabrication | 编造实验数据 | ❌ "准确率 95.3%" → ✅ "预期准确率" |
| Tense-Consistency | 未验证假设用过去时 | ❌ "我们发现了" → ✅ "预计可能发现" |
| Minimum-Length | 内容过短 | ❌ section 仅 50 字 → ✅ ≥ 400 字 |

---

## 项目结构

```
ai-scientist/
├── config/                     # 📋 配置驱动（改配置不改代码）
│   ├── agents.yaml             #    Agent 模型、prompt、工具、策略 + rubric 权重
│   ├── tools.yaml              #    工具注册表
│   └── prompts/                #    各 Agent 的 Markdown prompt + JSON Schema
│       ├── supervisor.md
│       ├── literature.md
│       ├── hypothesis.md
│       ├── evidence.md
│       ├── reflection_pre.md
│       ├── reflection_merge.md
│       ├── feedback.md
│       ├── writer.md
│       ├── judge_system.md     #    Judge + Rubric 8 维度锚点
│       └── judge_agents.md     #    各 Agent 评审维度 + rubric 子集
├── src/
│   ├── agent/                  # 🤖 Agent 核心
│   │   ├── pipeline.py         #    Classic 7-Agent 管线（文件驱动）
│   │   ├── co_scientist_pipeline.py  #    Co-Scientist 管线（checkpoint 驱动）
│   │   ├── agents/             #    Co-Scientist 节点
│   │   │   ├── generation_node.py   #    6 策略假设生成
│   │   │   ├── reflection_node.py   #    同行评审 + 幻觉检测
│   │   │   ├── proximity_node.py    #    嵌入图 + 近邻簇
│   │   │   ├── evolution_node.py    #    进化变异 + Matchmaker 配对
│   │   │   ├── meta_review_node.py  #    全局评估 + budget 终止
│   │   │   └── supervisor_node.py   #    目标解析
│   │   ├── ranking/            #    Elo 锦标赛
│   │   │   ├── ranking_node.py     #    锦标赛编排
│   │   │   ├── elo.py              #    Elo 评分引擎
│   │   │   ├── matchmaker.py       #    近邻优先配对
│   │   │   └── adjudicators.py     #    裁判（LLM / 规则）
│   │   ├── judge.py            #    两层审查 + Rubric 8 维度评分
│   │   ├── rubric_io.py        #    Rubric 文件读写 + 注入
│   │   ├── react_loop.py       #    ReAct 循环引擎（工具调用 + Judge 审查）
│   │   ├── report_renderer.py  #    10 字段报告 + LaTeX + PDF
│   │   ├── render_latex.py     #    xelatex 编译 + BibTeX 生成
│   │   ├── result_parser.py    #    LLM 输出 → ResearchState 映射
│   │   ├── review_manager.py   #    即时审查 + 内容质量检查
│   │   ├── fact_check.py       #    5 条确定性规则 + LLM 引用校验
│   │   ├── file_io.py          #    文件读写 + 信封格式
│   │   └── ...
│   ├── state/                  #    Co-Scientist 状态契约
│   │   ├── schema.py           #    CoScientistState TypedDict（20+ 字段）
│   │   ├── checkpoint.py       #    AsyncSqliteSaver 工厂
│   │   └── reducers.py         #    keep_all / queue / override
│   ├── api/                    # 🌐 REST API
│   │   ├── main.py             #    FastAPI 应用（16 个端点）
│   │   ├── pipeline_router.py  #    双模式路由（classic / co-scientist）
│   │   ├── task_queue.py       #    SQLite 任务队列（FIFO + 并发上限）
│   │   ├── task_worker.py      #    队列消费守护线程
│   │   └── sse.py              #    SSE 实时推送
├── frontend/                   # 🖥️ Vue3 SPA
│   ├── src/                    #    组件、Pinia store、设计 token
│   ├── dist/                   #    生产构建（nginx 反代 → FastAPI :8000）
│   └── tests/                  #    Vitest 单测
├── tests/                      # ✅ 测试（1068 项）
├── scripts/                    # 🛠️ 运维脚本
│   ├── test_v41_e2e.py         #    端到端测试（真实 API）
│   ├── batch_run.py            #    批量运行 125 个问题
│   └── analyze_run.py          #    运行结果分析
├── docs/                      #    设计文档、spec、ADR
├── data/
│   ├── 125.md                  #    Science 125 前沿问题
│   ├── runs/                   #    运行产出（gitignored）
│   └── results/                #    批量结果（gitignored）
├── requirements.txt
└── .env.example
```

---

## 快速开始

### 1. 环境准备

```bash
# 克隆项目
git clone https://gitee.com/ricky-theseus/ai-science.git
cd ai-science

# 创建虚拟环境（需要 Python 3.11+）
python -m venv .venv
# 或使用 uv
uv venv --python 3.11

# 激活虚拟环境
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate

# 安装依赖
uv pip install -r requirements.txt
```

### 2. 配置 API Key

```bash
# 复制环境变量模板
cp .env.example .env

# 编辑 .env，填入 DashScope API Key
# DASHSCOPE_API_KEY=sk-your-key-here
```

> API Key 获取：[阿里云 DashScope 控制台](https://dashscope.console.aliyun.com/)

### 3. 启动服务

选择管线模式（默认 `classic`）：

```bash
# Classic 7-Agent 文件驱动管线
export PIPELINE_MODE=classic

# Co-Scientist Elo 竞技循环管线
export PIPELINE_MODE=co-scientist
```

**方式一：FastAPI 服务（推荐，供前端开发使用）**

```bash
uvicorn src.api.main:app --reload --host 0.0.0.0 --port 8000
```

启动后访问：
- API 文档（Swagger）：http://localhost:8000/docs
- API 文档（ReDoc）：http://localhost:8000/redoc

**方式二：Vue3 前端（开发模式）**

```bash
cd frontend
npm install
npm run dev
```

启动后访问：http://localhost:5173

**方式三：Vue3 前端（生产模式）**

```bash
cd frontend && npm run build
# dist/ 部署到 nginx，反代 /api → localhost:8000
```

### 4. 发起研究

**cURL：**

```bash
# 启动研究
curl -X POST http://localhost:8000/api/research \
  -H "Content-Type: application/json" \
  -d '{"question": "后量子密码学的当前方法有哪些？", "max_iterations": 3}'

# 返回: {"run_id": "q_20260810_110532", "status": "running"}

# 查询状态
curl http://localhost:8000/api/runs/q_20260810_110532/status

# 下载 PDF
curl -o report.pdf http://localhost:8000/api/runs/q_20260810_110532/pdf
```

**Python SDK：**

```python
import httpx

# 启动研究
resp = httpx.post("http://localhost:8000/api/research", json={
    "question": "后量子密码学的当前方法有哪些？",
    "max_iterations": 3
})
run_id = resp.json()["run_id"]

# SSE 实时监听
import sseclient
stream = httpx.get(f"http://localhost:8000/api/runs/{run_id}/stream", stream=True)
client = sseclient.SSEClient(stream)
for event in client.events():
    print(event.data)
```

**Python 直调管线：**

```python
from dotenv import load_dotenv
load_dotenv()
from src.agent.pipeline import run_pipeline

result = run_pipeline(
    question="后量子密码学的当前方法有哪些？",
    max_iterations=3
)
print(f"PDF: {result.get('pdf_path')}")
```

---

## API 接口

完整接口文档见 [docs/api-reference.md](docs/api-reference.md)，共 16 个端点：

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/api/research` | 启动研究，返回 run_id |
| `GET` | `/api/runs/{run_id}/status` | 查询运行状态 |
| `GET` | `/api/runs/{run_id}/stream` | SSE 实时事件流 |
| `GET` | `/api/runs` | 列出所有运行 |
| `GET` | `/api/runs/{run_id}/files` | 列出运行文件 |
| `GET` | `/api/runs/{run_id}/stage/{name}` | 读取阶段输出 |
| `DELETE` | `/api/runs/{run_id}/stage/{name}` | 删除阶段文件 |
| `GET` | `/api/runs/{run_id}/report` | 获取最终报告 |
| `GET` | `/api/runs/{run_id}/pdf` | 导出 PDF |
| `GET` | `/api/runs/{run_id}/latex` | 导出 LaTeX 源码 |
| `GET` | `/api/runs/{run_id}/markdown-file` | 导出 Markdown |
| `GET` | `/api/agents` | 列出所有 Agent |
| `GET` | `/api/agents/{name}` | 获取单个 Agent |
| `PATCH` | `/api/agents/{name}` | 修改 Agent 配置 |
| `GET` | `/api/tools` | 列出所有工具 |
| `GET` | `/api/health` | 健康检查 |

---

## 配置说明

所有 Agent 配置集中在 `config/agents.yaml`，修改配置无需改代码：

```yaml
literature:
  model: qwen-max                # 使用的大模型
  system_prompt_file: prompts/literature.md
  output_strategy: last_iter_json  # 结构化输出策略
  tools: [arxiv_search, semantic_scholar_search]
  mandatory_tools: [arxiv_search]  # 必须调用的工具
  max_iterations: 100             # 安全上限
  min_iterations: 3               # 最少轮次

writer:
  model: qwen-max
  output_strategy: writer_latex
  content_quality:
    min_total_chars: 10000        # 正文最少 10000 字
    min_section_chars: 800        # 每节最少 800 字
    min_citations: 8              # 最少 8 条引用
    max_retries: 10               # 质量不达标最多重试 10 次
```

**模型选择策略：**

| Agent | 模型 | 理由 |
|-------|------|------|
| Supervisor / Literature / Hypothesis / Writer | qwen-max | 需要高质量推理和长文本生成 |
| Evidence | qwen-plus | 验证逻辑相对简单，节约成本 |
| Reflection / Feedback / Judge | qwen-turbo | 评分和审查任务简单，追求速度 |

也可通过 API 动态修改：

```bash
curl -X PATCH http://localhost:8000/api/agents/literature \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen-plus", "max_iterations": 5}'
```

---

## 测试

```bash
# 运行全部测试（mock 模式，零 API 调用，1068 项）
uv run pytest -q --ignore=tests/e2e -m "not slow"

# 查看覆盖率
uv run pytest --cov=src --cov-report=term-missing

# 运行 Rubric 专项测试
uv run pytest tests/test_rubric.py tests/test_rubric_io.py -v

# 运行单个模块测试
uv run pytest tests/test_pipeline.py -v

# 运行真实 API 端到端测试（需要 DASHSCOPE_API_KEY）
PYTHONPATH=. .venv/Scripts/python scripts/test_v41_e2e.py
```

当前测试状态：**1068 passed, 0 failed**

---

## 参考项目

本项目的设计借鉴了以下优秀开源项目的思路：

### [AI-Scientist](https://github.com/SakanaAI/AI-Scientist) — Sakana AI

> The First AI Scientist — LLM 驱动的自动化科学研究框架

**借鉴点：**
- 科学研究的流水线化拆解（idea generation → experimentation → paper writing）
- LLM 作为研究助手的角色定义
- 自动化论文撰写 + 同行评审机制

**我们的改进：** AI-Scientist 是单 Agent 端到端模式，我们拆分为 7 个专业化 Agent 协同，引入迭代自优化和质量门控机制，输出质量更稳定。

### [LangGraph](https://github.com/langchain-ai/langgraph) — LangChain

> 基于图结构的多 Agent 编排框架

**借鉴点：**
- StateGraph 的节点-边-条件路由模型
- 多 Agent 间的状态共享机制
- 条件循环（conditional edge）实现迭代

**我们的改进：** LangGraph 默认将所有状态存在内存中，我们改为文件驱动架构（PipelineState 仅 7 个控制字段 + 文件系统存储业务数据），提升了容错性和可观测性。

### [GPT-Researcher](https://github.com/assafelovic/gpt-researcher) — Tavily

> 自主研究 Agent，给定问题自动搜索、整理、生成报告

**借鉴点：**
- 多源搜索聚合（ArXiv + Semantic Scholar 等）
- 子问题分解驱动文献检索
- 结构化报告输出

**我们的改进：** GPT-Researcher 是单次 pass，我们引入 Judge 驱动的多轮迭代 + 精度回滚，输出质量从 4/10 可提升至 7+/10。

### [AutoGen](https://github.com/microsoft/autogen) — Microsoft

> 多 Agent 对话框架，支持 Agent 间的消息传递和协作

**借鉴点：**
- Agent 角色分工和职责边界
- 人类反馈注入（human-in-the-loop）

**我们的改进：** AutoGen 侧重对话式协作，我们侧重流水线式协同（每个 Agent 有明确的输入/输出 schema），更适合自动化科研场景。

---

## 许可证

本项目为 2026 挑战杯参赛作品，仅供学习和评审使用。

---

<div align="center">

**Built with ❤️ for the 2026 Challenge Cup**

</div>