478 lines
19 KiB
Markdown
478 lines
19 KiB
Markdown
# Phase 2: Platform Skills - Research
|
||
|
||
**Researched:** 2026-03-13
|
||
**Domain:** Python / B站知乎API集成 / 内容获取管道
|
||
**Confidence:** HIGH
|
||
|
||
## Summary
|
||
|
||
Phase 2 需要集成B站和知乎平台的内容获取能力，形成从链接到原始内容的完整流程。项目已有完整的平台API实现（kb-bilibili-metadata、kb-zhihu-metadata），以及链接解析器（kb-link-parser）。Phase 1 已建立了核心管道基础设施（schemas.py、errors.py、config.py、retry.py）。
|
||
|
||
**Primary recommendation:** 复用现有平台提取器实现，通过统一 LinkParser 类整合链接解析，使用 Phase 1 的 StepInput/StepOutput 模式包装现有功能，确保幂等检查和网络重试机制。
|
||
|
||
<user_constraints>
|
||
## User Constraints (from CONTEXT.md)
|
||
|
||
### Locked 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 机制）
|
||
|
||
### Deferred Ideas (OUT OF SCOPE)
|
||
- B站/知乎用户主页跟踪 — 未来功能
|
||
- 批量链接处理 — 当前只处理单个链接
|
||
- 进度显示 — v2 考虑
|
||
|
||
</user_constraints>
|
||
|
||
<phase_requirements>
|
||
## Phase Requirements
|
||
|
||
| ID | Description | Research Support |
|
||
|----|-------------|-----------------|
|
||
| PLAT-01 | B站视频处理 - 支持 B站视频的元数据提取、字幕下载、语音识别、深度分析 | 复用 kb-bilibili-metadata/bilibili_extractor.py 的 BilibiliExtractor 类，支持视频元数据和专栏提取 |
|
||
| PLAT-02 | B站专栏处理 - 支持 B站专栏的文字提取和深度分析 | 复用 kb-bilibili-content/bilibili_content.py 的 extract_article() 方法 |
|
||
| PLAT-03 | 知乎问答/专栏处理 - 支持知乎问答和专栏的文字提取和深度分析 | 复用 kb-zhihu-metadata/zhihu_extractor.py 的 ZhihuPlaywrightExtractor 类 |
|
||
|
||
</phase_requirements>
|
||
|
||
## Standard Stack
|
||
|
||
### Core
|
||
| Library | Version | Purpose | Why Standard |
|
||
|---------|---------|---------|--------------|
|
||
| pydantic | v2 | Schema 验证 | Phase 1 已采用，类型安全，自动验证 |
|
||
| pydantic-settings | v2 | 配置管理 | Phase 1 已采用，统一从 ~/.kb_env 加载 |
|
||
| tenacity | 8.x | 重试机制 | Phase 1 已采用，指数退避，装饰器模式 |
|
||
| httpx | 0.27+ | HTTP 客户端 | 现有代码已使用，支持异步，比 requests 更现代 |
|
||
| aiohttp | 3.9+ | 异步 HTTP | 现有代码已使用，用于 B站 API 调用 |
|
||
|
||
### Supporting
|
||
| Library | Version | Purpose | When to Use |
|
||
|---------|---------|---------|-------------|
|
||
| playwright | 1.40+ | 浏览器自动化 | 知乎内容提取、B站专栏全文获取 |
|
||
| yt-dlp | latest | 视频下载 | B站视频下载（替代 bilibili-dl） |
|
||
| requests | 2.31+ | 同步 HTTP | 短链解析、简单 API 调用 |
|
||
|
||
### Alternatives Considered
|
||
| Instead of | Could Use | Tradeoff |
|
||
|------------|-----------|----------|
|
||
| playwright | selenium | Playwright 更现代，API 更友好，异步支持更好 |
|
||
| httpx | requests | httpx 支持异步，更适合高并发场景；requests 更简单稳定 |
|
||
|
||
**Installation:**
|
||
```bash
|
||
pip install pydantic pydantic-settings tenacity httpx aiohttp playwright yt-dlp requests
|
||
playwright install chromium # Playwright 浏览器安装
|
||
```
|
||
|
||
## Architecture Patterns
|
||
|
||
### Recommended Project Structure
|
||
```
|
||
kb_pipeline/
|
||
├── __init__.py # 导出公共 API
|
||
├── schemas.py # StepInput/StepOutput/WorkflowState（Phase 1 已完成）
|
||
├── errors.py # KBError 体系（Phase 1 已完成）
|
||
├── config.py # KBSettings 配置（Phase 1 已完成）
|
||
├── retry.py # retry_on_network_error（Phase 1 已完成）
|
||
├── state.py # WorkflowStateManager（Phase 1 已完成）
|
||
├── link_parser.py # 统一链接解析器（Phase 2 新增）
|
||
├── platforms/ # 平台适配器（Phase 2 新增）
|
||
│ ├── __init__.py
|
||
│ ├── base.py # 平台适配器基类
|
||
│ ├── bilibili.py # B站适配器
|
||
│ └── zhihu.py # 知乎适配器
|
||
└── content_fetcher.py # 内容获取协调器（Phase 2 新增）
|
||
```
|
||
|
||
### Pattern 1: 平台适配器模式
|
||
**What:** 为每个平台创建统一的适配器接口，封装元数据提取和内容获取逻辑
|
||
**When to use:** 需要支持多个内容平台时
|
||
**Example:**
|
||
```python
|
||
# Source: 项目设计模式
|
||
from abc import ABC, abstractmethod
|
||
from typing import Dict, Any, Optional
|
||
from kb_pipeline.schemas import StepInput, StepOutput
|
||
|
||
class PlatformAdapter(ABC):
|
||
"""平台适配器基类"""
|
||
|
||
@abstractmethod
|
||
def get_content_type(self, url: str) -> str:
|
||
"""识别内容类型 (video/article/answer/zhuanlan)"""
|
||
pass
|
||
|
||
@abstractmethod
|
||
async def fetch_metadata(self, content_id: str, content_type: str) -> Dict[str, Any]:
|
||
"""获取元数据"""
|
||
pass
|
||
|
||
@abstractmethod
|
||
async def fetch_content(self, content_id: str, content_type: str) -> str:
|
||
"""获取正文内容（Markdown格式）"""
|
||
pass
|
||
|
||
@abstractmethod
|
||
def get_output_filename(self, content_id: str, content_type: str) -> str:
|
||
"""生成输出文件名"""
|
||
pass
|
||
```
|
||
|
||
### Pattern 2: 链接解析统一入口
|
||
**What:** 统一 LinkParser 类处理所有平台的 URL 解析
|
||
**When to use:** 任何需要从 URL 提取平台和内容 ID 的场景
|
||
**Example:**
|
||
```python
|
||
# Source: 基于现有 kb-link-parser/link-parser.py 重构
|
||
import re
|
||
from typing import Optional, Dict, Any
|
||
from dataclasses import dataclass
|
||
|
||
@dataclass
|
||
class ParsedLink:
|
||
"""解析后的链接信息"""
|
||
platform: str # "bilibili" | "zhihu"
|
||
content_type: str # "video" | "article" | "answer" | "zhuanlan"
|
||
content_id: str # BV号、CV号、知乎ID等
|
||
original_url: str # 原始 URL
|
||
resolved_url: str # 解析后的完整 URL（短链展开后）
|
||
|
||
class LinkParser:
|
||
"""统一链接解析器"""
|
||
|
||
# B站正则模式
|
||
BILIBILI_PATTERNS = {
|
||
"video": re.compile(r'bilibili\.com/video/(BV[a-zA-Z0-9]+)'),
|
||
"article": re.compile(r'bilibili\.com/read/cv(\d+)'),
|
||
"short": re.compile(r'b23\.tv/([a-zA-Z0-9]+)'),
|
||
}
|
||
|
||
# 知乎正则模式
|
||
ZHIHU_PATTERNS = {
|
||
"answer": re.compile(r'zhihu\.com/question/\d+/answer/(\d+)'),
|
||
"zhuanlan": re.compile(r'zhuanlan\.zhihu\.com/p/(\d+)'),
|
||
"zvideo": re.compile(r'zhihu\.com/zvideo/(\d+)'),
|
||
}
|
||
|
||
def parse(self, url: str) -> Optional[ParsedLink]:
|
||
"""解析 URL，返回结构化信息或 None"""
|
||
# 1. 先处理短链
|
||
resolved = self._resolve_short_link(url)
|
||
|
||
# 2. 匹配平台模式
|
||
for platform, patterns in [("bilibili", self.BILIBILI_PATTERNS),
|
||
("zhihu", self.ZHIHU_PATTERNS)]:
|
||
for content_type, pattern in patterns.items():
|
||
match = pattern.search(resolved)
|
||
if match:
|
||
return ParsedLink(
|
||
platform=platform,
|
||
content_type=content_type,
|
||
content_id=match.group(1),
|
||
original_url=url,
|
||
resolved_url=resolved
|
||
)
|
||
|
||
return None # 无法识别，返回 None（不抛异常）
|
||
|
||
def _resolve_short_link(self, url: str) -> str:
|
||
"""解析短链"""
|
||
# 复用现有 link_parser_shortlink.py 的逻辑
|
||
if "b23.tv" in url:
|
||
try:
|
||
import requests
|
||
resp = requests.head(url, allow_redirects=True, timeout=10)
|
||
return resp.url
|
||
except Exception:
|
||
pass
|
||
return url
|
||
```
|
||
|
||
### Pattern 3: 幂等检查机制
|
||
**What:** 在执行前检查输出文件是否已存在
|
||
**When to use:** 避免重复下载和处理
|
||
**Example:**
|
||
```python
|
||
# Source: CONTEXT.md 决策
|
||
from pathlib import Path
|
||
from typing import Tuple
|
||
|
||
class IdempotencyChecker:
|
||
"""幂等检查器"""
|
||
|
||
def check_exists(self, output_dir: Path, content_id: str) -> Tuple[bool, list[Path]]:
|
||
"""检查文件是否已存在
|
||
|
||
Returns:
|
||
(exists, files): 是否存在，存在的文件列表
|
||
"""
|
||
metadata_file = output_dir / f"{content_id}_metadata.json"
|
||
content_file = output_dir / f"{content_id}_content.md"
|
||
|
||
existing = []
|
||
if metadata_file.exists():
|
||
existing.append(metadata_file)
|
||
if content_file.exists():
|
||
existing.append(content_file)
|
||
|
||
return len(existing) > 0, existing
|
||
|
||
def prompt_redownload(self, existing_files: list[Path]) -> bool:
|
||
"""询问用户是否重新下载
|
||
|
||
Returns:
|
||
True 表示重新下载，False 表示跳过
|
||
"""
|
||
file_list = "\n".join(f" - {f.name}" for f in existing_files)
|
||
print(f"内容已存在:\n{file_list}")
|
||
response = input("是否重新下载？[y/N]: ").strip().lower()
|
||
return response == 'y'
|
||
```
|
||
|
||
### Anti-Patterns to Avoid
|
||
- **每个平台单独的 CLI 入口:** 不要为每个平台创建独立的命令行工具，应统一到工作流管道
|
||
- **硬编码文件路径:** 使用 KBSettings 配置，不要硬编码输出目录
|
||
- **忽略网络错误:** 必须使用 retry_on_network_error 装饰器处理网络请求
|
||
- **同步阻塞调用:** 元数据获取和内容下载应使用 async/await
|
||
|
||
## Don't Hand-Roll
|
||
|
||
| Problem | Don't Build | Use Instead | Why |
|
||
|---------|-------------|-------------|-----|
|
||
| BV/AV号转换 | 自己实现算法 | bilibili-api 库的转换函数 | 算法复杂，易出错 |
|
||
| 短链解析 | HTTP 重定向处理 | requests.head(allow_redirects=True) | 自动处理重定向链 |
|
||
| HTML 转 Markdown | 正则替换 | markdown_converter.py 已有实现 | 处理各种 HTML 边界情况 |
|
||
| 浏览器自动化 | selenium 脚本 | Playwright + 现有提取器 | 现有代码已完整实现 |
|
||
|
||
**Key insight:** 现有代码库已有完整的平台 API 实现，Phase 2 的核心工作是**整合**而非**重写**。
|
||
|
||
## Common Pitfalls
|
||
|
||
### Pitfall 1: B站 API 403 错误
|
||
**What goes wrong:** 直接调用 B站 API 返回 403 Forbidden
|
||
**Why it happens:** B站有反爬机制，需要正确的 User-Agent 和 Referer
|
||
**How to avoid:** 使用现有 BilibiliExtractor 的 DEFAULT_HEADERS
|
||
**Warning signs:** API 返回 403，或返回空数据
|
||
|
||
### Pitfall 2: 知乎需要登录
|
||
**What goes wrong:** 知乎内容无法获取，返回登录页面
|
||
**Why it happens:** 知乎对未登录用户限制内容访问
|
||
**How to avoid:** 从 KBSettings 获取 zhihu_cookie，传递给 Playwright 浏览器
|
||
**Warning signs:** 内容为空，页面标题包含"登录"
|
||
|
||
### Pitfall 3: 短链解析超时
|
||
**What goes wrong:** b23.tv 短链解析卡住或超时
|
||
**Why it happens:** 网络问题或短链服务不可用
|
||
**How to avoid:** 设置合理的 timeout（10秒），失败时返回原始 URL
|
||
**Warning signs:** 请求超时，网络异常
|
||
|
||
### Pitfall 4: 文件名包含特殊字符
|
||
**What goes wrong:** 标题包含 / : * ? " < > | 等字符导致文件创建失败
|
||
**Why it happens:** 操作系统文件系统限制
|
||
**How to avoid:** 实现文件名清理函数，移除或替换非法字符
|
||
**Warning signs:** FileNotFoundError，PermissionError
|
||
|
||
### Pitfall 5: 幂等检查遗漏
|
||
**What goes wrong:** 重复执行产生重复文件或覆盖已有内容
|
||
**Why it happens:** 忘记在执行前检查文件是否存在
|
||
**How to avoid:** 在 LinkParser 解析成功后立即检查，遵循 CONTEXT.md 的决策
|
||
**Warning signs:** workflow_state.json 中步骤状态与实际文件不一致
|
||
|
||
## Code Examples
|
||
|
||
### B站视频元数据获取
|
||
```python
|
||
# Source: kb-bilibili-metadata/bilibili_extractor.py
|
||
from kb_bilibili_metadata.bilibili_extractor import BilibiliExtractor
|
||
|
||
async def fetch_bilibili_video(bvid: str) -> dict:
|
||
"""获取 B站视频元数据"""
|
||
extractor = BilibiliExtractor(headless=True, timeout=30)
|
||
result = extractor.extract_video_metadata(bvid)
|
||
|
||
# 提取核心字段
|
||
return {
|
||
"title": result["metadata"]["title"],
|
||
"author": result["metadata"]["author"],
|
||
"duration": result["metadata"]["duration"],
|
||
"pubtime": result["metadata"]["pubtime"],
|
||
"description": result["description"],
|
||
"stats": result["stats"],
|
||
"bvid": result["metadata"]["bvid"],
|
||
"url": result["metadata"]["url"],
|
||
}
|
||
```
|
||
|
||
### 知乎内容提取
|
||
```python
|
||
# Source: kb-zhihu-metadata/zhihu_extractor.py
|
||
from kb_zhihu_metadata.zhihu_extractor import ZhihuPlaywrightExtractor
|
||
from kb_pipeline.config import get_settings
|
||
|
||
async def fetch_zhihu_content(url: str) -> dict:
|
||
"""获取知乎内容"""
|
||
settings = get_settings()
|
||
cookie = settings.zhihu_cookie.get_secret_value()
|
||
|
||
extractor = ZhihuPlaywrightExtractor(
|
||
headless=True,
|
||
timeout=30,
|
||
cookie=cookie if cookie else None
|
||
)
|
||
|
||
result = extractor.extract(url)
|
||
if not result:
|
||
return None
|
||
|
||
return {
|
||
"type": result["type"],
|
||
"title": result["title"],
|
||
"author": result["author"],
|
||
"content": result["content_markdown"],
|
||
"publish_time": result["publish_time"],
|
||
"url": url,
|
||
"content_id": result["content_id"],
|
||
}
|
||
```
|
||
|
||
### 内容输出格式
|
||
```python
|
||
# Source: CONTEXT.md 决策
|
||
from datetime import datetime
|
||
import yaml
|
||
|
||
def format_content_markdown(metadata: dict, content: str) -> str:
|
||
"""生成标准 Markdown 格式（YAML Frontmatter + 正文）"""
|
||
frontmatter = {
|
||
"title": metadata["title"],
|
||
"author": metadata["author"],
|
||
"source_url": metadata["url"],
|
||
"platform": metadata["platform"],
|
||
"content_type": metadata["content_type"],
|
||
"fetched_at": datetime.now().isoformat(),
|
||
}
|
||
|
||
return f"---\n{yaml.dump(frontmatter, allow_unicode=True)}---\n\n{content}"
|
||
```
|
||
|
||
## State of the Art
|
||
|
||
| Old Approach | Current Approach | When Changed | Impact |
|
||
|--------------|------------------|--------------|--------|
|
||
| 各平台独立脚本 | 统一管道模型 | Phase 1 | 可复用基础设施，统一错误处理 |
|
||
| 手动处理短链 | 自动解析 + 回退 | 现有 | 提升用户体验，减少手动操作 |
|
||
| 同步阻塞请求 | 异步并发 | 现有 | 提升性能，支持并发处理 |
|
||
|
||
**Deprecated/outdated:**
|
||
- bilibili-dl: 已被 yt-dlp 替代，yt-dlp 支持更多平台且维护活跃
|
||
- selenium: 已被 Playwright 替代，Playwright API 更现代
|
||
|
||
## Open Questions
|
||
|
||
1. **Playwright 浏览器安装**
|
||
- What we know: Playwright 需要单独安装浏览器（`playwright install chromium`）
|
||
- What's unclear: 是否需要在首次运行时自动检测并提示安装
|
||
- Recommendation: 在 README 中说明安装步骤，运行时检测并给出友好提示
|
||
|
||
2. **Cookie 过期处理**
|
||
- What we know: 知乎需要 Cookie 才能获取完整内容
|
||
- What's unclear: Cookie 过期时的错误提示和刷新机制
|
||
- Recommendation: 检测登录页面特征，返回 AuthError 并提示更新 Cookie
|
||
|
||
## Validation Architecture
|
||
|
||
### Test Framework
|
||
| Property | Value |
|
||
|----------|-------|
|
||
| Framework | pytest 8.x |
|
||
| Config file | pytest.ini |
|
||
| Quick run command | `pytest tests/test_pipeline/test_link_parser.py -x -v` |
|
||
| Full suite command | `pytest tests/ -v --cov=kb_pipeline` |
|
||
|
||
### Phase Requirements → Test Map
|
||
| Req ID | Behavior | Test Type | Automated Command | File Exists? |
|
||
|--------|----------|-----------|-------------------|-------------|
|
||
| PLAT-01 | B站视频元数据提取 | unit | `pytest tests/test_platforms/test_bilibili.py::test_video_metadata -x` | Wave 0 |
|
||
| PLAT-01 | B站视频内容下载 | integration | `pytest tests/test_platforms/test_bilibili.py::test_video_content -x` | Wave 0 |
|
||
| PLAT-02 | B站专栏内容提取 | unit | `pytest tests/test_platforms/test_bilibili.py::test_article_content -x` | Wave 0 |
|
||
| PLAT-03 | 知乎问答内容提取 | unit | `pytest tests/test_platforms/test_zhihu.py::test_answer_content -x` | Wave 0 |
|
||
| PLAT-03 | 知乎专栏内容提取 | unit | `pytest tests/test_platforms/test_zhihu.py::test_zhuanlan_content -x` | Wave 0 |
|
||
| PLAT-01/02/03 | 链接解析 | unit | `pytest tests/test_pipeline/test_link_parser.py -x` | Wave 0 |
|
||
| PLAT-01/02/03 | 幂等检查 | unit | `pytest tests/test_pipeline/test_idempotency.py -x` | Wave 0 |
|
||
|
||
### Sampling Rate
|
||
- **Per task commit:** `pytest tests/test_pipeline/test_link_parser.py tests/test_platforms/ -x`
|
||
- **Per wave merge:** `pytest tests/ -v --cov=kb_pipeline --cov-report=term-missing`
|
||
- **Phase gate:** Full suite green before `/gsd:verify-work`
|
||
|
||
### Wave 0 Gaps
|
||
- [ ] `tests/test_pipeline/test_link_parser.py` — LinkParser 单元测试
|
||
- [ ] `tests/test_pipeline/test_idempotency.py` — 幂等检查测试
|
||
- [ ] `tests/test_platforms/__init__.py` — 测试模块初始化
|
||
- [ ] `tests/test_platforms/conftest.py` — 平台测试共享 fixtures
|
||
- [ ] `tests/test_platforms/test_bilibili.py` — B站适配器测试
|
||
- [ ] `tests/test_platforms/test_zhihu.py` — 知乎适配器测试
|
||
- [ ] Mock fixtures: B站/知乎 API 响应数据
|
||
|
||
## Sources
|
||
|
||
### Primary (HIGH confidence)
|
||
- 现有代码: `kb-bilibili-metadata/bilibili_extractor.py` - B站 API 调用实现
|
||
- 现有代码: `kb-zhihu-metadata/zhihu_extractor.py` - 知乎 Playwright 提取器
|
||
- 现有代码: `kb-link-parser/link-parser.py` - 链接解析器
|
||
- 现有代码: `kb_pipeline/schemas.py` - Phase 1 Schema 定义
|
||
|
||
### Secondary (MEDIUM confidence)
|
||
- Phase 1 实现: `kb_pipeline/errors.py`, `kb_pipeline/config.py`, `kb_pipeline/retry.py`
|
||
- 现有代码: `kb_workflow/kb_workflow.py` - 子技能映射和内容类型判断
|
||
|
||
### Tertiary (LOW confidence)
|
||
- N/A - 本阶段研究基于现有代码库，无外部来源
|
||
|
||
## Metadata
|
||
|
||
**Confidence breakdown:**
|
||
- Standard stack: HIGH - 基于 Phase 1 已采用的技术栈和现有代码
|
||
- Architecture: HIGH - 现有代码已有成熟实现，主要是整合工作
|
||
- Pitfalls: HIGH - 基于现有代码中已处理的问题和 CONTEXT.md 决策
|
||
|
||
**Research date:** 2026-03-13
|
||
**Valid until:** 30 days - Python 和相关库相对稳定
|
||
|
||
---
|
||
|
||
*Research complete. Ready for planning phase.*
|