# Search Agent 架构重构方案

## 当前问题总结

### 🔴 严重问题
1. **策略加载逻辑重复** - `SearchAgentCore` 和 `harness/runner` 都在加载策略，职责不清
2. **分层违规** - domain 层反向依赖 pipeline 层
3. **硬编码路径散落** - `tests/output`、`tests/traces` 等路径到处都是

### 🟡 中等问题
4. **配置分散** - 配置分布在 4 个地方，难以管理
5. **职责混乱** - `pipeline/runner.py` 同时做装配、CLI、知识源定义
6. **入口重复** - `run_pipeline.py` 和 `run_search_agent.py` 职责不清

## 目标架构

```
search_agent/
├── core/                    # 核心领域逻辑（纯业务）
│   ├── __init__.py
│   ├── models.py           # 数据模型（Policy, Context, Article 等）
│   ├── policy.py           # 策略定义和应用
│   └── repository.py       # 策略仓储（DB 访问）
│
├── pipeline/               # 流水线引擎（可复用）
│   ├── __init__.py
│   ├── orchestrator.py    # 流水线编排器
│   ├── base.py            # Stage/Gate/Hook 基类
│   ├── context.py         # 上下文数据结构
│   ├── stages/            # 各个阶段实现
│   │   ├── __init__.py
│   │   ├── demand_analysis.py
│   │   ├── query_expansion.py
│   │   ├── content_search.py
│   │   ├── content_filter.py
│   │   ├── account_precipitate.py
│   │   └── output_persist.py
│   ├── gates/             # 质量门禁
│   │   ├── __init__.py
│   │   ├── search_completeness.py
│   │   ├── filter_sufficiency.py
│   │   └── output_schema.py
│   ├── hooks/             # 观察者钩子
│   │   ├── __init__.py
│   │   ├── trace_hook.py
│   │   ├── progress_hook.py
│   │   └── database_hook.py
│   └── adapters/          # 外部工具适配器
│       ├── __init__.py
│       ├── weixin.py
│       └── knowledge.py
│
├── config/                 # 配置管理（统一入口）
│   ├── __init__.py
│   ├── settings.py        # 配置类定义
│   ├── defaults.py        # 默认配置
│   └── loader.py          # 配置加载器
│
├── application/           # 应用层（组装和编排）
│   ├── __init__.py
│   ├── builder.py         # Pipeline 构建器
│   ├── runner.py          # 执行器（带预算、超时等约束）
│   └── service.py         # 对外服务接口
│
├── infrastructure/        # 基础设施
│   ├── __init__.py
│   ├── database.py        # 数据库连接池
│   ├── http_client.py     # HTTP 客户端
│   └── logging.py         # 日志配置
│
└── cli/                   # 命令行入口
    ├── __init__.py
    └── main.py            # 统一 CLI 入口

# 根目录
run_search_agent.py        # 简化为 CLI 入口的薄壳
configs/                   # 外部配置文件
├── default.json          # 默认配置
├── production.json       # 生产配置
└── knowledge_sources.json # 知识源配置
```

## 重构步骤

### Phase 1: 配置统一化（P2 优先）

**目标**: 消除硬编码，统一配置入口

**步骤**:
1. 创建 `src/config/settings.py` - 定义完整的配置类
2. 创建 `src/config/loader.py` - 统一加载环境变量和配置文件
3. 修改所有硬编码路径，改为从配置读取
4. 将 `default_knowledge_sources()` 移到 `configs/knowledge_sources.json`

**文件变更**:
- 新增: `src/config/settings.py`, `src/config/loader.py`
- 修改: `src/pipeline/runner.py`, `src/domain/search/core.py`
- 新增: `configs/knowledge_sources.json`

### Phase 2: 分层修复（P1）

**目标**: 修复 domain 层反向依赖 pipeline 层的问题

**步骤**:
1. 创建 `src/application/builder.py` - 负责组装 pipeline
2. 将 `build_default_pipeline()` 从 `pipeline/runner.py` 移到 `application/builder.py`
3. `SearchAgentCore` 不再导入 `pipeline.runner`，改为接受 `PipelineOrchestrator` 注入
4. 重命名 `pipeline/runner.py` 为 `pipeline/factory.py`（只做工厂职责）

**文件变更**:
- 新增: `src/application/builder.py`
- 修改: `src/domain/search/core.py`
- 重命名: `src/pipeline/runner.py` → `src/pipeline/factory.py`

### Phase 3: 策略加载去重（P0 最高优先级）

**目标**: 消除策略加载重复逻辑

**步骤**:
1. 将 `harness/runner.py` 重命名为 `application/runner.py`
2. `SearchAgentCore.run()` 移除 `use_db_policy` 参数和内部策略加载逻辑
3. `SearchAgentCore.run()` 只接受 `policy: SearchAgentPolicy` 参数（必填）
4. 策略加载完全由 `application/runner.py` 负责

**文件变更**:
- 移动: `src/harness/search_agent/runner.py` → `src/application/runner.py`
- 修改: `src/domain/search/core.py` - 简化接口
- 修改: `run_search_agent.py` - 调用新接口

### Phase 4: 入口简化

**目标**: 统一 CLI 入口，消除重复

**步骤**:
1. 创建 `src/cli/main.py` - 统一 CLI 入口
2. `run_search_agent.py` 简化为薄壳，只调用 `cli.main()`
3. 删除或归档 `run_pipeline.py`（功能已被 `run_search_agent.py` 覆盖）

**文件变更**:
- 新增: `src/cli/main.py`
- 简化: `run_search_agent.py`
- 删除: `run_pipeline.py`（或移到 `scripts/legacy/`）

### Phase 5: 目录重组

**目标**: 清晰的模块边界

**步骤**:
1. 将 `src/harness/` 内容整合到 `src/application/`
2. 删除空的 `src/harness/` 目录
3. 确保每个模块职责单一

**文件变更**:
- 移动: `src/harness/search_agent/*` → `src/application/`
- 删除: `src/harness/` 目录

## 重构后的调用链

```
run_search_agent.py (薄壳)
    ↓
src/cli/main.py (CLI 解析)
    ↓
src/application/runner.py (策略加载 + 预算控制)
    ↓
src/application/builder.py (组装 pipeline)
    ↓
src/domain/search/core.py (执行业务逻辑)
    ↓
src/pipeline/orchestrator.py (编排各阶段)
    ↓
src/pipeline/stages/* (具体阶段实现)
```

## 配置加载优先级

```
1. 环境变量 (PIPELINE_*, SEARCH_AGENT_*)
2. 命令行参数 (--config, --strategy-file)
3. 配置文件 (configs/*.json)
4. 代码默认值 (src/config/defaults.py)
```

## 验证清单

重构完成后，确保：
- [ ] 所有测试通过
- [ ] 没有硬编码路径
- [ ] 配置可以通过环境变量或文件覆盖
- [ ] 分层清晰，domain 不依赖 pipeline
- [ ] 策略加载逻辑只在一处
- [ ] CLI 入口统一
- [ ] 文档更新

## 风险控制

1. **渐进式重构** - 每个 Phase 独立完成并测试
2. **保留旧代码** - 重构期间保留旧文件，标记为 deprecated
3. **测试覆盖** - 每个 Phase 完成后运行完整测试
4. **回滚计划** - 使用 git 分支，每个 Phase 一个 commit

## 预期收益

- ✅ 代码结构清晰，职责明确
- ✅ 配置统一管理，易于维护
- ✅ 分层合理，依赖方向正确
- ✅ 消除重复代码
- ✅ 易于测试和扩展
- ✅ 新人上手更快