docs(09): capture phase context

2026-03-17 22:32:44 +08:00
parent 007b0d70ef
commit e6b62f42e7
1 changed files with 100 additions and 0 deletions
@@ -0,0 +1,100 @@
+# Phase 9: Pipeline 整合 - Context
+
+**Gathered:** 2026-03-17
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+将新爬虫实现整合进现有 Pipeline 架构，替换原有知乎处理器。
+
+此阶段不涉及新功能开发（Phase 7/8 已完成），只负责整合工作。
+
+</domain>
+
+<decisions>
+## 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 格式（标题、分隔线等）
+- 二维码显示的具体实现方式（终端/图片文件）
+- 错误提示信息的具体文案
+
+</decisions>
+
+<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>
+
+<specifics>
+## Specific Ideas
+
+- 评论追加格式示例:
+  ```markdown
+  ## 正文内容
+  [原回答/文章内容]
+
+  ---
+
+  ## 热门评论
+  1. **@用户A**: 评论内容...
+  2. **@用户B**: 评论内容...
+  ```
+- Cookie 过期检测: 通过 API 响应状态码或返回内容判断
+- 自动登录触发: `ZhihuLogin().login_qrcode()` 方法
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+None — discussion stayed within phase scope
+
+</deferred>
+
+---
+
+*Phase: 09-pipeline-integration*
+*Context gathered: 2026-03-17*