diff --git a/.planning/phases/09-pipeline-integration/09-CONTEXT.md b/.planning/phases/09-pipeline-integration/09-CONTEXT.md new file mode 100644 index 0000000..8d0c39a --- /dev/null +++ b/.planning/phases/09-pipeline-integration/09-CONTEXT.md @@ -0,0 +1,100 @@ +# 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 格式(标题、分隔线等) +- 二维码显示的具体实现方式(终端/图片文件) +- 错误提示信息的具体文案 + + + + +## 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) + + + + +## Specific Ideas + +- 评论追加格式示例: + ```markdown + ## 正文内容 + [原回答/文章内容] + + --- + + ## 热门评论 + 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*