From ea82f5d965556013b81107919d87d9ae61e82b8d Mon Sep 17 00:00:00 2001
From: starmen1265 <starmen1265@163.com>
Date: Fri, 13 Mar 2026 17:43:03 +0800
Subject: [PATCH] docs(02): capture phase 2 context

---
 .../phases/02-platform-skills/02-CONTEXT.md   | 102 ++++++++++++++++++
 1 file changed, 102 insertions(+)
 create mode 100644 .planning/phases/02-platform-skills/02-CONTEXT.md

diff --git a/.planning/phases/02-platform-skills/02-CONTEXT.md b/.planning/phases/02-platform-skills/02-CONTEXT.md
new file mode 100644
index 0000000..e61cd9c
--- /dev/null
+++ b/.planning/phases/02-platform-skills/02-CONTEXT.md
@@ -0,0 +1,102 @@
+# Phase 2: Platform Skills - Context
+
+**Gathered:** 2026-03-13
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+集成B站和知乎平台的内容获取能力，形成从链接到原始内容的完整流程。包括：
+- 链接解析（平台识别、内容类型判断、ID提取）
+- 元数据提取（标题、作者、时间等结构化信息）
+- 内容下载（视频/专栏/问答的正文内容）
+
+此阶段不涉及 ASR/OCR 处理（Phase 3），也不涉及深度分析（Phase 4）。
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### 链接解析策略
+- **解析器结构**: 统一 LinkParser 类 — 一个模块处理所有平台，通过正则/模式匹配区分
+- **支持 URL 类型**:
+  - B站视频: bilibili.com/video/BVxxx, b23.tv/xxx（短链解析）
+  - B站专栏: bilibili.com/read/cvxxx
+  - 知乎问答: zhihu.com/question/xxx/answer/xxx
+  - 知乎专栏: zhuanlan.zhihu.com/p/xxx
+- **ID 提取**: BV号 + AV号（同时支持，自动转换）
+- **短链支持**: 支持 b23.tv 短链解析，获取真实 URL
+- **错误处理**: 无法识别的 URL 返回 None + 错误信息（不抛异常）
+
+### 元数据输出格式
+- **B站视频字段**: 标题、作者、时长、发布时间、描述、封面、链接、ID（BV号）
+- **知乎字段**: 标题、作者、发布时间、内容摘要、链接、ID
+- **文件命名**: 平台_ID.json（如 bilibili_BV1xx.json, zhihu_12345.json）
+- **存储位置**: 内容目录下（与内容文件同目录）
+
+### 内容输出格式
+- **Markdown 结构**: YAML Frontmatter + 正文内容
+- **Frontmatter 字段**: title, author, source_url, platform, content_type, fetched_at
+- **图片处理**: 保留原始链接（不下载到本地）
+- **格式保留**: 基础格式（标题、段落、列表、代码块）
+- **不保留**: 表格、数学公式、LaTeX（Phase 2 不处理）
+
+### 幂等检查机制
+- **检查时机**: 链接解析后 — 解析成功后立即检查目录是否存在
+- **判断依据**: 检查输出文件是否存在（元数据 JSON + 内容 Markdown）
+- **重复处理**: 询问用户 — 发现已存在文件时询问是否重新下载
+
+### Claude's Discretion
+- LinkParser 的正则表达式具体实现
+- 文件名清理规则（特殊字符处理）
+- 网络请求超时时间和重试次数（复用 Phase 1 的 retry 机制）
+
+</decisions>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- `kb_workflow.py`: 子技能映射 (METADATA_AGENTS, CONTENT_AGENTS)、内容类型判断函数 — 可直接复用
+- `kb-bilibili-metadata/bilibili_extractor.py`: B站 API 调用、元数据提取 — 已有完整实现
+- `kb-bilibili-metadata/bilibili_metadata.py`: CLI 入口 — 可作为集成参考
+- `kb-zhihu-metadata/zhihu_extractor.py`: 知乎 API 调用 — 已有完整实现
+- `kb_pipeline/schemas.py`: StepInput, StepOutput, WorkflowState — Phase 1 已定义
+
+### Established Patterns
+- 子技能调用模式: `METADATA_AGENTS[platform]` → 执行对应 CLI
+- 内容类型分类: VIDEO_CONTENT_TYPES, TEXT_CONTENT_TYPES
+- 错误处理: 使用 Phase 1 的 KBError 体系
+- 配置管理: 使用 Phase 1 的 KBSettings
+
+### Integration Points
+- LinkParser 输出 → WorkflowState.content_id
+- 元数据提取 → 使用 StepInput/StepOutput 模式
+- 内容下载 → 更新 WorkflowState 步骤状态
+- 错误 → 使用 Phase 1 的 retry_on_network_error 装饰器
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+- 短链解析: HTTP HEAD 请求获取 Location 头，或使用 requests 库的 allow_redirects
+- 幂等检查提示: "内容已存在: {path}。是否重新下载？[y/N]"
+- 文件命名示例: `bilibili_BV1GJ411x7Qw_metadata.json`, `bilibili_BV1GJ411x7Qw_content.md`
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- B站/知乎用户主页跟踪 — 未来功能
+- 批量链接处理 — 当前只处理单个链接
+- 进度显示 — v2 考虑
+
+</deferred>
+
+---
+
+*Phase: 02-platform-skills*
+*Context gathered: 2026-03-13*