chore: complete v1.3 Proxy Pool milestone

.planning/milestones/v1.3-REQUIREMENTS.md

@@ -0,0 +1,233 @@
+# Requirements Archive: v1.3 Anti-Crawler Optimization
+
+**Archived:** 2026-03-18
+**Status:** SHIPPED
+
+For current requirements, see `.planning/REQUIREMENTS.md`.
+
+---
+
+# Requirements: kb-skills
+
+**Defined:** 2026-03-17
+**Core Value:** 可靠、可维护的处理管道 - 每个步骤独立、可验证、可恢复
+
+## v1.2 Requirements
+
+知乎内容爬取体系的完整实现，解决 Cookie 过期问题，支持自动登录维持。
+
+### 登录认证
+
+- [x] **AUTH-01**: 用户可通过二维码扫码登录知乎
+- [x] **AUTH-02**: 用户可手动设置 Cookie 进行认证
+- [x] **AUTH-03**: Cookie 自动持久化到本地文件，下次自动复用
+- [x] **AUTH-04**: Cookie 过期时自动检测并提示重新登录
+
+### 内容爬取
+
+- [x] **CONT-01**: 爬取知乎问答 - 问题标题、问题描述、回答内容、元数据
+- [x] **CONT-02**: 爬取知乎专栏/文章 - 标题、正文、元数据
+- [x] **CONT-03**: 爬取内容下的评论（可选开关）
+- [x] **CONT-04**: 提取作者信息、发布时间、点赞数等元数据
+
+### 网络与反爬
+
+- [x] **NET-01**: 支持代理 IP 配置
+- [x] **NET-02**: 请求频率控制，避免触发反爬
+- [x] **NET-03**: 自动获取请求签名（x-zse-96），无需手动逆向
+
+### Pipeline 整合
+
+- [x] **PIPE-01**: 替换现有 ZhihuProcessor，使用新的爬虫实现
+- [x] **PIPE-02**: 保持与现有 Pipeline 架构的兼容性
+- [x] **PIPE-03**: 支持断点续传和幂等执行
+
+## v1.1 Requirements (Complete)
+
+### 中间目录 (Intermediate)
+
+- [x] **INT-01**: 中间目录统一到 `~/work/intermediate/analysis/`
+- [x] **INT-02**: 内容目录命名保持 `{platform}_{content_id}/` 格式
+- [x] **INT-03**: 配置文件支持自定义中间目录路径
+
+### 归档步骤 (Archive)
+
+- [x] **ARC-01**: 添加 ArchiveProcessor 作为管道最后一步
+- [x] **ARC-02**: 分析完成后自动归档到最终目录
+- [x] **ARC-03**: 归档只复制 md 文件到最终目录
+- [x] **ARC-04**: 归档后可选清理中间文件
+
+### 最终目录结构 (Output)
+
+- [x] **OUT-01**: 最终目录按平台分目录 (bilibili/, zhihu/)
+- [x] **OUT-02**: 不再按时间创建归档目录
+- [x] **OUT-03**: 文件前缀加时间戳 `{timestamp}_{content_id}_analysis.md`
+- [x] **OUT-04**: 只保留 md 文件，不归档 json 文件
+
+### 代码整合 - 元数据 (Metadata Integration)
+
+- [x] **MET-01**: kb-bilibili-metadata 整合进 kb-workflow/metadata/
+- [x] **MET-02**: kb-zhihu-metadata 整合进 kb-workflow/metadata/
+- [x] **MET-03**: 删除独立的 kb-bilibili-metadata 目录
+- [x] **MET-04**: 删除独立的 kb-zhihu-metadata 目录
+- [x] **MET-05**: 更新所有导入路径指向新位置
+
+### 代码整合 - Pipeline (Pipeline Integration)
+
+- [x] **PIP-01**: kb_pipeline/ 合并进 kb-workflow/
+- [x] **PIP-02**: 保持 processors/, platforms/, schemas.py, state.py, config.py 结构
+- [x] **PIP-03**: 删除独立的 kb_pipeline 目录
+- [x] **PIP-04**: 更新 CLI 入口导入路径
+
+## v1.3 Requirements (Current)
+
+反爬虫优化，增强爬虫反检测能力，降低被封风险，提升爬取稳定性。
+
+### Proxy Pool (代理池管理)
+
+- [x] **PROXY-01**: 用户可以配置代理池 — 支持从文件或环境变量加载多个代理地址
+- [x] **PROXY-02**: 系统自动轮换代理 — 每次请求自动选择下一个可用代理
+- [x] **PROXY-03**: 代理健康检查 — 检测代理可用性，自动移除失效代理
+- [x] **PROXY-04**: 代理失败回退 — 当前代理失败时自动切换到下一个代理
+
+### Behavior Camouflage (请求行为伪装)
+
+- [ ] **BEHAV-01**: 随机请求延迟 — 请求间隔在可配置范围内随机化（默认 1-5 秒）
+- [ ] **BEHAV-02**: User-Agent 轮换 — 每次请求使用不同的真实浏览器 UA
+- [ ] **BEHAV-03**: 请求头随机化 — Accept-Language、Accept-Encoding 等头部随机化
+- [ ] **BEHAV-04**: 模拟人类浏览模式 — 支持页面滚动、鼠标移动等行为模拟（Playwright）
+
+### CAPTCHA Detection (验证码检测)
+
+- [ ] **CAPT-01**: 验证码页面检测 — 自动检测知乎/B站验证码页面
+- [ ] **CAPT-02**: 验证码触发告警 — 检测到验证码时记录日志并暂停爬取
+- [ ] **CAPT-03**: 验证码状态恢复 — 支持手动处理后继续爬取
+
+### Error Recovery (错误恢复机制)
+
+- [ ] **ERR-01**: 智能重试策略 — 根据错误类型选择不同的重试策略（403/429/超时）
+- [ ] **ERR-02**: 指数退避 + 抖动 — 重试间隔使用指数退避并添加随机抖动
+- [ ] **ERR-03**: 错误分类处理 — 区分临时错误和永久错误，避免无效重试
+- [ ] **ERR-04**: 断点续传增强 — 记录失败位置，支持从失败点恢复
+
+### Platform Adaptation (平台适配)
+
+- [ ] **PLAT-01**: 知乎反爬适配 — 针对知乎的反爬策略优化（登录态检测、请求频率限制）
+- [ ] **PLAT-02**: B站反爬适配 — 针对 B站的反爬策略优化（视频/专栏元数据获取）
+
+## v2 Requirements (Deferred)
+
+推迟到后续版本的需求。
+
+### 扩展爬取
+
+- **EXT-01**: 问题下所有回答 - 爬取问题的所有热门回答（非单页）
+- **EXT-02**: 作者全部内容 - 爬取某作者的所有文章/回答
+- **EXT-03**: 知乎视频 - 爬取知乎视频内容
+
+### 高级功能
+
+- **ADV-01**: 进度可见性 — 实时显示工作流执行进度
+- **ADV-02**: 并行步骤执行 — 支持独立步骤的并行执行
+- **ADV-03**: 说话者分离默认启用 — HF_TOKEN 配置后自动使用
+- **ADV-04**: 微信公众号处理 — 支持微信公众号文章
+
+## Out of Scope
+
+明确排除的功能范围。
+
+| Feature | Reason |
+|---------|--------|
+| 知乎会员付费内容 | 不爬取付费内容，合规考虑 |
+| 知乎视频 | v1.2 不支持，推迟到后续版本 |
+| 大规模爬取 | 仅用于个人知识库，不对平台造成负担 |
+| 付费打码服务 | 使用二维码登录替代，免费方案 |
+| 实时/流式处理 | 批量处理即可 |
+| 并发限制 | 不需要限制并发数量 |
+| 用户界面 | 命令行运行 |
+| 多语言支持 | 中文即可 |
+| 小红书 | 当前不支持 |
+
+## Traceability
+
+需求与路线图的映射关系。
+
+### v1.2 Traceability
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| AUTH-01 | Phase 7 | Complete |
+| AUTH-02 | Phase 7 | Complete |
+| AUTH-03 | Phase 7 | Complete |
+| AUTH-04 | Phase 7 | Complete |
+| CONT-01 | Phase 8 | Complete |
+| CONT-02 | Phase 8 | Complete |
+| CONT-03 | Phase 8 | Complete |
+| CONT-04 | Phase 8 | Complete |
+| NET-01 | Phase 8 | Complete |
+| NET-02 | Phase 8 | Complete |
+| NET-03 | Phase 8 | Complete |
+| PIPE-01 | Phase 9 | Complete |
+| PIPE-02 | Phase 9 | Complete |
+| PIPE-03 | Phase 9 | Complete |
+
+**v1.2 Coverage:**
+- Requirements: 14 total
+- Mapped to phases: 14
+- Unmapped: 0 ✓
+
+### v1.1 Traceability (Complete)
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| INT-01 | Phase 5 | Complete |
+| INT-02 | Phase 5 | Complete |
+| INT-03 | Phase 5 | Complete |
+| ARC-01 | Phase 5 | Complete |
+| ARC-02 | Phase 5 | Complete |
+| ARC-03 | Phase 5 | Complete |
+| ARC-04 | Phase 5 | Complete |
+| OUT-01 | Phase 5 | Complete |
+| OUT-02 | Phase 5 | Complete |
+| OUT-03 | Phase 5 | Complete |
+| OUT-04 | Phase 5 | Complete |
+| MET-01 | Phase 6 | Complete |
+| MET-02 | Phase 6 | Complete |
+| MET-03 | Phase 6 | Complete |
+| MET-04 | Phase 6 | Complete |
+| MET-05 | Phase 6 | Complete |
+| PIP-01 | Phase 6 | Complete |
+| PIP-02 | Phase 6 | Complete |
+| PIP-03 | Phase 6 | Complete |
+| PIP-04 | Phase 6 | Complete |
+
+---
+*Requirements defined: 2026-03-17*
+*Last updated: 2026-03-18 after v1.3 requirements added*
+
+### v1.3 Traceability
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| PROXY-01 | Phase 10 | Complete |
+| PROXY-02 | Phase 10 | Complete |
+| PROXY-03 | Phase 10 | Complete |
+| PROXY-04 | Phase 10 | Complete |
+| BEHAV-01 | Phase 11 | Pending |
+| BEHAV-02 | Phase 11 | Pending |
+| BEHAV-03 | Phase 11 | Pending |
+| BEHAV-04 | Phase 11 | Pending |
+| CAPT-01 | Phase 12 | Pending |
+| CAPT-02 | Phase 12 | Pending |
+| CAPT-03 | Phase 12 | Pending |
+| ERR-01 | Phase 13 | Pending |
+| ERR-02 | Phase 13 | Pending |
+| ERR-03 | Phase 13 | Pending |
+| ERR-04 | Phase 13 | Pending |
+| PLAT-01 | Phase 14 | Pending |
+| PLAT-02 | Phase 14 | Pending |
+
+**v1.3 Coverage:**
+- Requirements: 17 total
+- Mapped to phases: 17
+- Unmapped: 0 ✓

.planning/milestones/v1.3-ROADMAP.md

@@ -0,0 +1,136 @@
+# Roadmap: kb-skills
+
+## Milestones
+
+- ✅ **v1.0 Pipeline Architecture** - Phases 1-4 (shipped 2011-03-15)
+- ✅ **v1.1 Architecture Refactor** - Phases 5-6 (shipped 2011-03-16)
+- ✅ **v1.2 Zhihu Crawler** - Phases 7-9 (shipped 2011-03-17)
+- 🚧 **v1.3 Anti-Crawler Optimization** - Phases 10-14 (in progress)
+
+## Phases
+
+<details>
+<summary>✅ v1.0 Pipeline Architecture (Phases 1-4) - SHIPPED 2011-03-15</summary>
+
+### Phase 1: Foundation
+**Goal**: 项目基础设施和状态管理
+**Plans**: 3 plans
+
+Plans:
+- [x] 01-01: WorkflowStateManager 状态管理
+- [x] 01-02: LinkParser URL 解析
+- [x] 01-03: IdempotencyChecker 幂等检查
+
+### Phase 2: Adapters
+**Goal**: 平台元数据适配器
+**Plans**: 2 plans
+
+Plans:
+- [x] 02-01: BilibiliAdapter B站适配器
+- [x] 02-02: ZhihuAdapter 知乎适配器
+
+### Phase 3: Processors
+**Goal**: 管道处理器架构
+**Plans**: 3 plans
+
+Plans:
+- [x] 03-01: BaseProcessor 基类
+- [x] 03-02: 具体处理器实现
+- [x] 03-03: Schema 验证
+
+### Phase 4: Pipeline
+**Goal**: 处理器编排和 CLI
+**Plans**: 2 plans
+
+Plans:
+- [x] 04-01: Pipeline 编排引擎
+- [x] 04-02: CLI process 命令
+
+</details>
+
+<details>
+<summary>✅ v1.1 Architecture Refactor (Phases 5-6) - SHIPPED 2011-03-16</summary>
+
+### Phase 5: 归档与目录优化
+**Goal**: 统一中间目录结构，添加自动归档步骤，优化最终目录布局
+**Depends on**: Phase 4
+**Requirements**: INT-01, INT-02, INT-03, ARC-01, ARC-02, ARC-03, ARC-04, OUT-01, OUT-02, OUT-03, OUT-04
+**Success Criteria** (what must be TRUE):
+  1. 所有分析任务的中间文件统一存放在 `~/work/intermediate/analysis/{platform}_{content_id}/`
+  2. 分析完成后 md 文件自动复制到按平台分组的最终目录
+  3. 最终目录结构为 `{KB_ARCHIVE_PATH}/{platform}/{YYYYMMDD}_{content_id}_analysis.md`
+  4. 归档时检测重复文件，询问用户是否覆盖
+  5. 不自动清理中间文件（用户手动维护）
+**Plans**: 3 plans (all complete)
+
+### Phase 6: 代码整合
+**Goal**: 将独立的元数据技能和 Pipeline 模块整合进 kb-workflow
+**Depends on**: Phase 5
+**Requirements**: MET-01, MET-02, MET-03, MET-04, MET-05, PIP-01, PIP-02, PIP-03, PIP-04
+**Success Criteria** (what must be TRUE):
+  1. kb-bilibili-metadata 和 kb-zhihu-metadata 代码移入 kb-workflow/metadata/
+  2. kb_pipeline/ 代码合并入 kb-workflow/ 保持 processors/, platforms/, schemas.py 结构
+  3. 所有导入路径更新指向新位置，CLI 正常工作
+  4. 原独立的 kb-bilibili-metadata、kb-zhihu-metadata、kb_pipeline 目录已删除
+  5. 所有 sys.path 动态操作已删除或重构
+  6. Pipeline 类可从 kb_workflow.pipeline 包级别导入
+**Plans**: 3 plans (all complete)
+
+</details>
+
+<details>
+<summary>✅ v1.2 Zhihu Crawler (Phases 7-9) - SHIPPED 2011-03-17</summary>
+
+### Phase 7: 登录认证体系
+**Goal**: 建立知乎登录认证机制，支持二维码扫码和手动 Cookie 两种方式，实现 Cookie 持久化和过期检测
+**Depends on**: Phase 6
+**Requirements**: AUTH-01, AUTH-02, AUTH-03, AUTH-04
+**Success Criteria** (what must be TRUE):
+  1. 用户可以通过命令行显示二维码并扫码登录知乎
+  2. 扫码失败时用户可以手动设置 Cookie 进行认证
+  3. Cookie 自动保存到本地文件，下次运行自动复用
+  4. Cookie 过期时系统自动检测并提示用户重新登录
+**Plans**: 3 plans (all complete)
+
+### Phase 8: 内容爬取实现
+**Goal**: 实现知乎问答、专栏/文章、评论的完整爬取功能，包含网络反爬措施
+**Depends on**: Phase 7
+**Requirements**: CONT-01, CONT-02, CONT-03, CONT-04, NET-01, NET-02, NET-03
+**Success Criteria** (what must be TRUE):
+  1. 用户可以爬取知乎问答（问题标题、描述、回答内容、元数据）
+  2. 用户可以爬取知乎专栏/文章（标题、正文、元数据）
+  3. 用户可以选择是否爬取内容下的评论
+  4. 爬取结果包含作者信息、发布时间、点赞数等完整元数据
+  5. 用户可以配置代理 IP 以降低被封风险
+**Plans**: 3 plans (all complete)
+
+### Phase 9: Pipeline 整合
+**Goal**: 将新爬虫实现整合进现有 Pipeline 架构，替换原有知乎处理器
+**Depends on**: Phase 8
+**Requirements**: PIPE-01, PIPE-02, PIPE-03
+**Success Criteria** (what must be TRUE):
+  1. 知乎链接使用新爬虫处理器，无需手动设置 Cookie
+  2. 新处理器与现有 Pipeline 架构完全兼容
+  3. 支持断点续传和幂等执行（与其他处理器行为一致）
+**Plans**: 1 plan (complete)
+
+</details>
+
+### 🚧 v1.3 Anti-Crawler Optimization (In Progress)
+
+**Milestone Goal:** 增强爬虫反检测能力，降低被封风险，提升爬取稳定性
+
+#### Phase 10: Proxy Pool (代理池管理)
+**Goal**: 建立代理池基础设施，支持多代理配置、自动轮换和健康检查
+**Depends on**: Phase 9
+**Requirements**: PROXY-01, PROXY-02, PROXY-03, PROXY-04
+**Success Criteria** (what must be TRUE):
+  1. 用户可以从配置文件或环境变量加载多个代理地址
+  2. 每次请求自动选择下一个可用代理，实现负载均衡
+  3. 代理不可用时自动检测并标记为失效
+  4. 当前代理失败时自动切换到备用代理继续请求
+**Plans**: 2 plans
+
+Plans:
+- [x] 10-01: ProxyPool 核心类实现 — 从 YAML/环境变量加载代理，Round-Robin 轮换
+- [ ] 10-02: 健康检查与 ZhihuCrawler 集成 — 被动检测、冷却恢复、代理切换