# 设计方案: Deep Research Service (Reactive & Git-Native)

## 1. 定位与核心理念 (Overview)

**Deep Research** 是一个独立的、正交的数据降维与提炼服务。它的核心任务解决 "Context Overflow" 问题——当业务数据量超过大模型上下文窗口，或数据复杂度超过单次 Prompt 处理能力时，通过**自主智能体 (Autonomous Agent)** 进行迭代式的分析、摘要和结构化提取。

### 1.1 核心原则
1.  **独立性 (Independence)**: 作为一个独立的微服务 (`deep-research-service`) 运行，拥有独立的资源配额和生命周期。
2.  **Git 原生 (Git-Native)**: 利用底层的 VGCS (Virtual Git Context System) 的分支 (Branching) 和合并 (Merging) 机制，实现原始数据与研究成果的**并存**。
3.  **响应式闭环 (Reactive Loop)**: 摒弃线性的 Map-Reduce，采用 "Plan -> Act -> Critic" 的动态循环，根据当前发现的信息实时调整研究目标。
4.  **安全护栏 (Guardrails)**: 引入熵减检查、语义收敛检测和硬性预算约束，防止智能体陷入死循环或发散。

---

## 2. 系统架构 (Architecture)

### 2.1 交互流程图

```mermaid
graph TD
    subgraph "Orchestration Layer"
        Orch[Orchestrator Service]
        DAG[DAG Scheduler]
    end

    subgraph "Storage Layer (VGCS)"
        Repo[Git Repo]
        MainBr[Branch: main]
        DRBr[Branch: feat/deep_research]
    end

    subgraph "Deep Research Layer"
        Monitor[Resource Monitor]
        Reactor[Reactive Engine]
        Guard[Safety Guardrails]
    end

    %% Flow
    Orch -->|1. Task Pending (Check Size)| Monitor
    Monitor -->|2. Threshold Exceeded| Orch
    Orch -->|3. Suspend Task & Create Branch| Repo
    Repo -.-> MainBr
    MainBr -.-> DRBr
    
    Orch -->|4. Dispatch Job| Reactor
    Reactor <-->|5. Read/Write| DRBr
    Reactor <-->|6. Validate Step| Guard
    
    Reactor -->|7. Completion| Orch
    Orch -->|8. Merge/Rebase| Repo
    DRBr -->|Merge| MainBr
    Orch -->|9. Resume Task| DAG
```

### 2.2 分支策略 (Branching Strategy)

我们采用 **"并存 (Co-exist)"** 策略，而非简单的替换。

*   **Main Branch**: 包含原始海量数据 (e.g., 100份 PDF, 10万行 CSV)。
*   **Research Branch**: 从 Main 分出。Deep Research Agent 在此分支上工作，生成新的提炼文件 (e.g., `research_summary.md`, `knowledge_graph.json`)。
*   **Merge**: 任务完成后，Research Branch 被 merge 回 Main。
    *   **下游任务视角**: 下游任务可以看到原始数据（如果在 `input` 中显式请求），但默认通过 Context Selector 优先获取 `research_summary.md`。
    *   **User Option**: 用户可以选择 "Re-run from Deep Research"，即基于 merge 后的 commit 继续执行；也可以选择 "Raw Run"，强制使用原始数据（虽然可能失败）。

---

## 3. 核心逻辑: The Reactive Engine

Deep Research 不仅仅是摘要，而是一个**有状态的探索过程**。

### 3.1 状态循环 (The Loop)

Agent 维护一个动态的 `State`：
*   `Goal Stack`: 当前的研究目标栈（初始由 Prompt 决定，后续动态分裂）。
*   `Knowledge Base`: 已获取的确信事实。
*   `Trace Log`: 思考路径。

**执行步骤**:
1.  **Observe**: 读取当前分支的数据（或上一轮的输出）。
2.  **Plan**: 基于当前 Goal 和 Observe 的结果，制定下一步行动（e.g., "搜索关键词 X", "读取文件 Y 的第 10-20 页", "对文件 Z 进行摘要"）。
3.  **Act**: 执行行动，写入中间结果到 Git。
4.  **Reflect (Critic)**: 检查结果是否满足 Goal？是否发现了新线索需要更新 Goal？

### 3.2 保驾护航机制 (Guardrails)

为了防止 Agent "幻觉"、"死循环" 或 "跑题"，必须实施严格的监控。

#### A. 熵减检查 (Entropy/Novelty Check)
*   **目的**: 防止 Agent 反复咀嚼相同的信息。
*   **机制**: 计算新生成的 Research Note 与已有 Knowledge Base 的 **Embedding 相似度**。
*   **策略**: 如果 `Similarity > 0.95`，判定为无效迭代，强制终止当前子路径或回退。

#### B. 语义距离收敛 (Semantic Convergence)
*   **目的**: 防止 Agent 跑题（Divergence）。
*   **机制**: 实时计算 `Current Research Content` 向量与 `Initial User Query` 向量的距离。
*   **策略**: 距离应随迭代呈**震荡下降**趋势。如果距离显著增大（e.g., 从研究 "Apple 财务" 跑题到 "越南美食"），Supervisor 介入干预。

#### C. 预算硬约束 (Hard Budgeting)
*   **Token Cap**: 单次 Research 任务上限（e.g., 200k tokens）。
*   **Step Cap**: 最大迭代轮数（e.g., 10 loops）。
*   **Time Cap**: 超时强制终止。

---

## 4. 触发与配置 (Triggering & Config)

### 4.1 自动触发 (Auto-Trigger)
*   **Pre-flight Check**: Orchestrator 在调度 Analysis Task 前，先调用 `ContextResolver` 获取输入文件的 Metadata。
*   **Threshold Logic**:
    ```rust
    let total_tokens = estimate_tokens(file_list);
    let model_limit = llm_config.context_window; // e.g. 128k
    
    if total_tokens > (model_limit * 0.8) {
        trigger_deep_research();
    }
    ```

### 4.2 配置驱动 (Config-Driven)
允许在 `AnalysisTemplate` 中显式控制：

```json
{
  "modules": {
    "financial_analysis": {
      "deep_research": {
        "strategy": "auto", // auto | always | never
        "threshold_tokens": 50000,
        "focus_areas": ["risk", "cash_flow"] // Initial Goals
      }
    }
  }
}
```

### 4.3 基础设施配置更新

需要在 `LlmProvidersConfig` 中补充模型能力参数，以便系统知道 "上限" 是多少。

```rust
pub struct ModelConfig {
    pub model_id: String,
    pub context_window: u32, // e.g., 128000
    pub pricing_tier: String, // e.g., "high"
    // ...
}
```

---

## 5. 实施路线图 (Roadmap)

1.  **Phase 1: Infrastructure**
    *   在 `common-contracts` 定义 Deep Research 的 Task 结构和配置。
    *   更新 `LlmProvidersConfig` 支持 context window 参数。
    *   在 `Orchestrator` 实现 "Suspend & Branch" 逻辑。

2.  **Phase 2: The Service (MVP)**
    *   构建 `deep-research-service` (Rust)。
    *   实现基础的 **Map-Reduce** 逻辑作为 v0.1（先跑通流程）。
    *   集成 VGCS 分支操作。

3.  **Phase 3: The Reactive Agent**
    *   引入向量数据库（或内存向量索引）用于 Guardrails。
    *   实现 Plan-Act-Critic 循环。
    *   实现熵减和收敛检查。

4.  **Phase 4: Integration**
    *   全自动触发测试。
    *   前端可视化：展示 Research 过程的 Trace 和中间产物。

