docs(06): capture phase context

2026-03-16 23:42:31 +08:00
parent bee61f6e08
commit 9f4aee0ac7
1 changed files with 147 additions and 0 deletions
@@ -0,0 +1,147 @@
+# Phase 6: 代码整合 - Context
+
+**Gathered:** 2026-03-16
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+将独立的元数据技能和 Pipeline 模块整合进 kb-workflow。包括：
+- kb-bilibili-metadata + kb-zhihu-metadata → kb-workflow/metadata/
+- kb_pipeline/ → kb-workflow/pipeline/
+- 更新所有导入路径
+- 删除原独立目录
+
+此阶段不涉及新功能开发，只做代码整合和结构重组。
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### 目录结构
+- **完全扁平化**: kb-workflow/metadata/ 和 kb-workflow/pipeline/ 作为顶级子目录
+- **元数据目录**: kb-workflow/metadata/bilibili_extractor.py, zhihu_extractor.py 等
+- **Pipeline 目录**: kb-workflow/pipeline/processors/, kb-workflow/pipeline/platforms/ 等
+- **保留原文件名**: bilibili_extractor.py 不重命名为 bilibili.py，保持迁移安全
+
+### 导入策略
+- **外部导入**: 统一从 kb_workflow 导入
+  - `from kb_workflow.metadata.bilibili_extractor import ...`
+  - `from kb_workflow.pipeline.processors import ...`
+- **内部导入**: 使用绝对导入
+  - `from kb_workflow.pipeline.processors.base import BaseProcessor`
+- **更新范围**: 所有测试文件、CLI 入口、处理器间引用
+
+### 整合顺序
+- **先 metadata 后 pipeline**:
+  1. 移动 kb-bilibili-metadata → kb-workflow/metadata/
+  2. 移动 kb-zhihu-metadata → kb-workflow/metadata/
+  3. 更新 metadata 相关导入
+  4. 运行测试验证
+  5. 移动 kb_pipeline → kb-workflow/pipeline/
+  6. 更新 pipeline 相关导入
+  7. 运行测试验证
+
+### 验证策略
+- **分步验证**: 每个子整合完成后运行测试
+- **测试命令**: `pytest tests/ -v`
+- **失败处理**: 测试失败时不继续下一步，先修复问题
+
+### 清理策略
+- **立即删除**: 整合完成且测试通过后立即删除原目录
+- **删除目录**: kb-bilibili-metadata/, kb-zhihu-metadata/, kb_pipeline/
+- **Git 提交**: 每个子整合单独提交，便于回滚
+
+### Claude's Discretion
+- 具体导入路径更新时的细节调整
+- 处理意外的循环导入问题
+- 测试文件的导入更新方式
+
+</decisions>
+
+<code_context>
+## Existing Code Insights
+
+### 要整合的模块
+- **kb-bilibili-metadata/** (3 files):
+  - bilibili_extractor.py - B站 API 调用和元数据提取
+  - bilibili_metadata.py - CLI 入口
+  - __init__.py
+- **kb-zhihu-metadata/** (5 files):
+  - zhihu_extractor.py - 知乎 Playwright 提取
+  - zhihu_metadata.py - CLI 入口
+  - zhihu_article_crawler.py - 文章爬虫
+  - markdown_converter.py - Markdown 转换
+  - __init__.py
+- **kb_pipeline/** (20 files):
+  - 核心模块: pipeline.py, schemas.py, config.py, state.py, errors.py, retry.py, idempotency.py, link_parser.py
+  - processors/: base.py, parse.py, download.py, asr.py, analyze.py, archive.py
+  - platforms/: base.py, bilibili.py, zhihu.py
+
+### 导入依赖关系
+- kb-workflow/kb_workflow.py → kb_pipeline.pipeline, kb_pipeline.processors
+- kb_pipeline/platforms/zhihu.py → kb-zhihu-metadata (ZhihuPlaywrightExtractor)
+- kb_pipeline/platforms/bilibili.py → kb-bilibili-metadata (BilibiliExtractor)
+- tests/ → 多个 kb_pipeline 模块
+
+### Integration Points
+- CLI 入口: kb-workflow/kb_workflow.py 需要更新导入路径
+- 平台适配器: platforms/zhihu.py, platforms/bilibili.py 需要更新元数据模块导入
+- 测试文件: tests/ 目录下所有测试需要更新导入
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+- 整合后目录结构:
+  ```
+  kb-workflow/
+  ├── kb_workflow.py        # CLI 入口
+  ├── metadata/
+  │   ├── __init__.py
+  │   ├── bilibili_extractor.py
+  │   ├── bilibili_metadata.py
+  │   ├── zhihu_extractor.py
+  │   ├── zhihu_metadata.py
+  │   ├── zhihu_article_crawler.py
+  │   └── markdown_converter.py
+  └── pipeline/
+      ├── __init__.py
+      ├── pipeline.py
+      ├── schemas.py
+      ├── config.py
+      ├── state.py
+      ├── errors.py
+      ├── retry.py
+      ├── idempotency.py
+      ├── link_parser.py
+      ├── processors/
+      │   ├── __init__.py
+      │   ├── base.py
+      │   ├── parse.py
+      │   ├── download.py
+      │   ├── asr.py
+      │   ├── analyze.py
+      │   └── archive.py
+      └── platforms/
+          ├── __init__.py
+          ├── base.py
+          ├── bilibili.py
+          └── zhihu.py
+  ```
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+None — discussion stayed within phase scope
+
+</deferred>
+
+---
+
+*Phase: 06-code-consolidation*
+*Context gathered: 2026-03-16*