Agent/docs/search_agent_refactor_summary.md

Search Agent 重构完成总结

已完成的重构

✅ Phase 1: 配置统一化

新增文件:

• src/config/settings.py - 统一配置管理

  • PathConfig - 路径配置（消除硬编码）
  • PipelineConfig - Pipeline 运行配置
  • SearchAgentConfig - 完整配置聚合
  • get_config() - 全局配置获取

• src/config/loader.py - 配置加载器

  • load_knowledge_sources() - 从 JSON 加载知识源
  • load_json_config() - 通用 JSON 配置加载

• configs/knowledge_sources.json - 知识源配置文件

  • 将硬编码的业务规则外部化

收益:

• ✅ 消除所有硬编码路径
• ✅ 配置统一管理，易于维护
• ✅ 支持环境变量覆盖
• ✅ 知识源配置外部化

✅ Phase 2: 分层修复

新增文件:

• src/application/ - 新增应用层
  • builder.py - Pipeline 构建器
  • runner.py - 应用执行器
  • __init__.py - 模块导出

架构改进:

• ✅ 创建独立的 application 层
• ✅ PipelineBuilder 负责组装 Pipeline
• ✅ 分离构建逻辑和执行逻辑
• ✅ 为后续删除 domain → pipeline 依赖做准备

✅ Phase 3: 策略加载去重

核心改进:

• ✅ 策略加载逻辑统一到 ApplicationRunner.load_policy()
• ✅ 消除 SearchAgentCore 和 harness/runner 的重复逻辑
• ✅ 单一职责：策略加载只在一处

数据流:

ApplicationRunner.load_policy()
    ↓
SearchAgentPolicy (已解析)
    ↓
apply_search_agent_policy(ctx, policy)
    ↓
PipelineOrchestrator.run(ctx)

✅ Phase 4: 入口简化

修改文件:

• run_search_agent.py - 简化为薄壳
  • 只负责参数读取和调用 ApplicationRunner
  • 所有业务逻辑委托给 application 层

调用链:

run_search_agent.py (薄壳)
    ↓
ApplicationRunner.run() (策略加载 + 执行)
    ↓
PipelineBuilder.build() (组装 Pipeline)
    ↓
PipelineOrchestrator.run() (编排执行)

新架构总览

src/
├── config/                    # 配置管理（新增）
│   ├── settings.py           # 统一配置
│   └── loader.py             # 配置加载器
│
├── application/              # 应用层（新增）
│   ├── builder.py           # Pipeline 构建器
│   ├── runner.py            # 应用执行器（策略加载在此）
│   └── __init__.py
│
├── domain/search/           # 领域层（保持不变）
│   ├── core.py             # 待简化（下一步）
│   ├── policy.py
│   └── repository.py
│
├── pipeline/               # Pipeline 引擎（保持不变）
│   ├── orchestrator.py
│   ├── stages/
│   ├── gates/
│   ├── hooks/
│   └── adapters/
│
└── harness/               # 待整合到 application（Phase 5）
    └── search_agent/

待完成工作

Phase 5: 目录重组

需要做的:

1. 将 src/harness/search_agent/ 中的工具类移到 src/application/

   • budget.py → 已整合到 runner.py
   • summary.py → 已整合到 runner.py
   • planner.py → 保留（打印计划）
   • environment.py → 保留（环境配置）
   • prerequisites.py → 保留（前置检查）
   • logging_setup.py → 保留（日志配置）

2. 简化 SearchAgentCore

   • 移除策略加载逻辑
   • 移除 pipeline 依赖
   • 只保留必要的业务接口

3. 删除或归档 run_pipeline.py

验证清单

• 配置统一管理，无硬编码路径
• 策略加载逻辑只在一处
• 分层清晰，application 层独立
• 入口简化，职责明确
• 目录整洁，无冗余文件
• 所有测试通过
• 文档更新

使用方式

基本使用

# 使用环境变量配置
export PIPELINE_QUERY="你的查询"
export PIPELINE_DEMAND_ID="1"
python run_search_agent.py

配置覆盖

# 通过环境变量覆盖路径
export OUTPUT_DIR="/custom/output"
export TRACE_DIR="/custom/traces"

# 通过配置文件覆盖策略
export SEARCH_AGENT_STRATEGY_FILE="configs/custom_strategy.json"

# 通过 JSON 字符串覆盖策略
export SEARCH_AGENT_STRATEGY_JSON='{"search": {"max_keywords": 10}}'

编程使用

from src.config.settings import get_config
from src.application import ApplicationRunner

# 获取配置
config = get_config()

# 创建执行器
runner = ApplicationRunner(config)

# 执行搜索
summary = await runner.run(
    query="你的查询",
    demand_id="1",
    use_db_policy=True
)

# 检查结果
if summary.success:
    print(f"找到 {summary.filtered_count} 篇文章")

收益总结

代码质量

• ✅ 消除重复代码
• ✅ 职责单一，边界清晰
• ✅ 依赖方向正确
• ✅ 易于测试和扩展

可维护性

• ✅ 配置集中管理
• ✅ 路径可配置
• ✅ 策略加载逻辑清晰
• ✅ 新人上手更快

灵活性

• ✅ 支持多种配置方式
• ✅ 易于添加新功能
• ✅ 易于集成到其他系统

下一步建议

1. 完成 Phase 5 - 整合 harness 目录
2. 添加单元测试 - 为新的 application 层添加测试
3. 更新文档 - 更新架构文档和使用指南
4. 性能优化 - 分析瓶颈，优化执行效率
5. 监控告警 - 添加关键指标监控