kb-skills/.planning/phases/10-proxy-pool/10-CONTEXT.md

Phase 10: Proxy Pool (代理池管理) - Context

Gathered: 2026-03-18 Status: Ready for planning

## Phase Boundary

建立代理池基础设施，支持多代理配置、自动轮换和健康检查。此阶段不涉及请求行为伪装（Phase 11）和验证码处理（Phase 12）。

核心能力：

• 从配置文件加载多个代理地址
• 每次请求自动轮换代理
• 代理健康检查（被动检测）
• 失效代理自动切换和恢复

## Implementation Decisions

代理池配置方式

• 配置来源: YAML 文件（~/.kb_proxies.yaml）
• 配置格式: 简单 URL 列表，认证信息嵌入 URL

  proxies:
    - "http://user:pass@proxy1.example.com:8080"
    - "http://proxy2.example.com:3128"
    - "socks5://user:pass@proxy3.example.com:1080"
  

• 向后兼容: 如果未配置代理池文件，自动回退到现有的 HTTP_PROXY 环境变量（单代理模式）
• 支持的协议: HTTP、HTTPS、SOCKS5

轮换策略

• 策略: 顺序轮换（Round-Robin）
• 时机: 每次请求自动轮换到下一个代理
• 实现: 维护一个索引指针，每次请求后递增并循环

健康检查机制

• 检测方式: 被动检测（请求失败时标记）
• 失效判断: 连续 3 次请求失败后标记为失效
• 失败类型: 网络超时、连接失败、代理返回错误

失效代理处理

• 策略: 暂时移除 + 冷却恢复
• 冷却时间: 5 分钟后自动恢复到轮换池
• 全失效处理: 所有代理都失效时，回退到第一个代理继续尝试请求

Claude's Discretion

• 冷却时间的具体实现方式（定时器 vs 惰性检查）
• 代理统计信息的记录格式（可选功能）
• 日志输出的详细程度
• 失效代理的具体判断条件（HTTP 状态码范围）

## Specific Ideas

• 配置文件示例:

  # ~/.kb_proxies.yaml
  proxies:
    - "http://127.0.0.1:7890"  # 本地代理
    - "http://user:pass@proxy.example.com:8080"  # 带认证
    - "socks5://127.0.0.1:1080"  # SOCKS5
  

• 轮换实现: current_index = (current_index + 1) % len(available_proxies)
• 冷却检查: if now() - proxy.failed_at > 300: proxy.available = True

<code_context>

Existing Code Insights

Reusable Assets

• kb_workflow/crawler/config.py — CrawlerConfig、ProxyConfig 类，已有单代理支持
• kb_workflow/crawler/config.py — to_playwright_format() 方法，代理格式转换
• kb_workflow/crawler/zhihu_crawler.py — ZhihuCrawler 类，使用代理配置
• kb_workflow/pipeline/config.py — KBSettings 配置类，pydantic-settings 模式

Established Patterns

• 配置管理: pydantic BaseModel + 环境变量 + YAML 文件
• 浏览器代理: Playwright browser.new_context(proxy=...)
• 配置文件位置: ~/.kb_* 命名约定

Integration Points

• ProxyPool 类替换现有的单代理逻辑
• CrawlerConfig 扩展支持代理池
• ZhihuCrawler._start_browser_with_proxy() 改为从代理池获取代理
• 配置文件加载: 启动时读取 ~/.kb_proxies.yaml

</code_context>

## Deferred Ideas

• API 获取代理 — 从代理服务商 API 自动获取代理，推迟到后续版本
• 加权轮换 — 根据代理质量/速度加权，推迟到后续版本
• 代理统计面板 — 展示每个代理的成功率、响应时间，推迟到后续版本
• 配置热加载 — 运行时检测配置文件变化并重新加载，推迟到后续版本

---

Phase: 10-proxy-pool Context gathered: 2026-03-18