Agent/docs/search_agent_refactor_plan.md

Search Agent 架构重构方案

当前问题总结

🔴 严重问题

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

🟡 中等问题

1. 配置分散 - 配置分布在 4 个地方，难以管理
2. 职责混乱 - pipeline/runner.py 同时做装配、CLI、知识源定义
3. 入口重复 - 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

预期收益

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