docs(10): capture phase context for proxy pool

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

@@ -0,0 +1,108 @@
+# Phase 10: Proxy Pool (代理池管理) - Context
+
+**Gathered:** 2026-03-18
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+建立代理池基础设施，支持多代理配置、自动轮换和健康检查。此阶段不涉及请求行为伪装（Phase 11）和验证码处理（Phase 12）。
+
+核心能力：
+- 从配置文件加载多个代理地址
+- 每次请求自动轮换代理
+- 代理健康检查（被动检测）
+- 失效代理自动切换和恢复
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### 代理池配置方式
+- **配置来源**: YAML 文件（`~/.kb_proxies.yaml`）
+- **配置格式**: 简单 URL 列表，认证信息嵌入 URL
+  ```yaml
+  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 状态码范围）
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- 配置文件示例:
+  ```yaml
+  # ~/.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`
+
+</specifics>
+
+<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>
+## Deferred Ideas
+
+- **API 获取代理** — 从代理服务商 API 自动获取代理，推迟到后续版本
+- **加权轮换** — 根据代理质量/速度加权，推迟到后续版本
+- **代理统计面板** — 展示每个代理的成功率、响应时间，推迟到后续版本
+- **配置热加载** — 运行时检测配置文件变化并重新加载，推迟到后续版本
+
+</deferred>
+
+---
+
+*Phase: 10-proxy-pool*
+*Context gathered: 2026-03-18*