kb-skills/.planning/phases/09-pipeline-integration/09-CONTEXT.md

Phase 9: Pipeline 整合 - Context

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

## Phase Boundary

将新爬虫实现整合进现有 Pipeline 架构，替换原有知乎处理器。

此阶段不涉及新功能开发（Phase 7/8 已完成），只负责整合工作。

## Implementation Decisions

整合方式

• 策略: 修改现有 ZhihuAdapter 内部实现，切换到使用 ZhihuCrawler
• 接口保持: 保持 ZhihuAdapter 的公共接口不变，对 DownloadProcessor 无感知变化
• 实现变更: fetch_metadata() 和 fetch_content() 内部调用 ZhihuCrawler 而非 ZhihuPlaywrightExtractor

评论数据处理

• 默认行为: 评论爬取默认开启
• 存储方式: 评论追加到正文末尾（Markdown 格式）
• 数量上限: 20 条热门评论（使用 hot 排序，API 默认限制）
• 嵌套处理: 不展开回复的回复，只爬第一层评论（继承自 Phase 8）

Cookie 过期处理

• 策略: 自动触发扫码登录
• 流程: 检测到 Cookie 失效时，调用 ZhihuLogin 触发扫码登录，用户扫码后继续执行
• 用户体验: 用户会看到二维码提示，扫码后流程自动继续

失败降级策略

• 策略: 直接报错，不降级
• 不降级: 新爬虫失败时不尝试旧版 ZhihuPlaywrightExtractor
• 错误处理: 抛出异常，由上层 Pipeline 统一处理错误

Claude's Discretion

• 评论追加到正文的具体 Markdown 格式（标题、分隔线等）
• 二维码显示的具体实现方式（终端/图片文件）
• 错误提示信息的具体文案

<code_context>

Existing Code Insights

Reusable Assets

• kb_workflow/crawler/zhihu_crawler.py — ZhihuCrawler 类，已实现问答/专栏/评论爬取
• kb_workflow/crawler/models.py — CrawlResult, AnswerData, ArticleData, CommentsResult 数据模型
• kb_workflow/crawler/config.py — CrawlerConfig 配置类，支持代理和延迟配置
• kb_workflow/auth/zhihu_login.py — ZhihuLogin 类，二维码登录和 Cookie 管理
• kb_workflow/pipeline/platforms/zhihu.py — ZhihuAdapter 类（待修改）
• kb_workflow/pipeline/processors/download.py — DownloadProcessor，调用 Adapter 接口

Established Patterns

• PlatformAdapter 接口: fetch_metadata(), fetch_content(), get_content_type(), get_output_filename()
• BaseProcessor 模式: 状态检查、幂等执行、错误记录
• 配置管理: pydantic-settings + 环境变量
• 错误处理: AuthError 异常类

Integration Points

• ZhihuAdapter.fetch_metadata() → 调用 ZhihuCrawler.crawl_answer() / crawl_article()
• ZhihuAdapter.fetch_content() → 调用 ZhihuCrawler 并格式化输出（含评论）
• Cookie 过期 → 调用 ZhihuLogin 触发扫码登录
• 输出格式 → 保持与现有 Pipeline 兼容（metadata.json + content.md）

</code_context>

## Specific Ideas

• 评论追加格式示例:

  ## 正文内容
  [原回答/文章内容]
  
  ---
  
  ## 热门评论
  1. **@用户A**: 评论内容...
  2. **@用户B**: 评论内容...
  

• Cookie 过期检测: 通过 API 响应状态码或返回内容判断
• 自动登录触发: ZhihuLogin().login_qrcode() 方法

## Deferred Ideas

None — discussion stayed within phase scope

---

Phase: 09-pipeline-integration Context gathered: 2026-03-17