kb-skills/.planning/phases/02-platform-skills/02-CONTEXT.md

Phase 2: Platform Skills - Context

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

## Phase Boundary

集成B站和知乎平台的内容获取能力，形成从链接到原始内容的完整流程。包括：

• 链接解析（平台识别、内容类型判断、ID提取）
• 元数据提取（标题、作者、时间等结构化信息）
• 内容下载（视频/专栏/问答的正文内容）

此阶段不涉及 ASR/OCR 处理（Phase 3），也不涉及深度分析（Phase 4）。

## 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 机制）

<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>

## Specific Ideas

• 短链解析: HTTP HEAD 请求获取 Location 头，或使用 requests 库的 allow_redirects
• 幂等检查提示: "内容已存在: {path}。是否重新下载？[y/N]"
• 文件命名示例: bilibili_BV1GJ411x7Qw_metadata.json, bilibili_BV1GJ411x7Qw_content.md

## Deferred Ideas

• B站/知乎用户主页跟踪 — 未来功能
• 批量链接处理 — 当前只处理单个链接
• 进度显示 — v2 考虑

---

Phase: 02-platform-skills Context gathered: 2026-03-13