# obsidian-kb + bilibili-extractor 整合 - 实现计划

**Goal:** 将 bilibili-extractor 的提取能力整合到 obsidian-kb，输出markdown到Obsidian按UP主分类管理

**Approach:** 保持 obsidian-kb 现有架构，新增提取层和输出层，替换原有提取逻辑

**Estimated Total Time:** 90-120 分钟

---

## Checkpoint 1: 代码结构调整
- [ ] Task 1: 创建 extractors 目录结构 (~3 min)
  - **Action:** `mkdir -p /home/admin/.openclaw/workspace/skills/obsidian-kb/src/extractors`
  - **Verify:** `ls -la` 确认目录存在
- [ ] Task 2: 创建 outputs 目录结构 (~3 min)
  - **Action:** `mkdir -p /home/admin/.openclaw/workspace/skills/obsidian-kb/src/outputs`
  - **Verify:** `ls -la` 确认目录存在
- [ ] Task 3: 创建 __init__.py 文件 (~2 min)
  - **Action:** 在 extractors/ 和 outputs/ 创建 __init__.py
  - **Verify:** 文件创建成功

---

## Checkpoint 2: 提取器基类和配置扩展
- [ ] Task 1: 创建提取器基类 (~5 min)
  - **Action:** 创建 `src/extractors/base.py`，定义 Extractor 基类和接口
  - **Verify:** 基类定义完成，包含 extract() 抽象方法
- [ ] Task 2: 扩展 config.py 配置 (~5 min)
  - **Action:** 在 DEFAULT_CONFIG 中添加 output.organize_by, output.filename_format, sources.bilibili.extraction
  - **Verify:** 配置项添加成功，支持环境变量覆盖

---

## Checkpoint 3: B站提取器实现
- [ ] Task 1: 移植 bilibili-extractor 核心逻辑 (~10 min)
  - **Action:** 创建 `src/extractors/bilibili_extractor.py`，从 bilibili_extractor.py 移植 Playwright 提取逻辑
  - **Verify:** 提取器能独立运行，返回元数据+字幕
- [ ] Task 2: 测试提取器 (~5 min)
  - **Action:** 用真实BV号测试（BV1MnFNz5EDL）
  - **Verify:** 成功提取视频信息、统计数据、字幕

---

## Checkpoint 4: 处理器接口调整
- [ ] Task 1: 调整 analyzer 接口 (~5 min)
  - **Action:** 修改 `src/processors/analyzer.py`，从提取器数据结构接收输入
  - **Verify:** 接口调整完成
- [ ] Task 2: 实现无字幕降级逻辑 (~5 min)
  - **Action:** 添加无字幕分支处理（使用视频简介，只保留默认标签）
  - **Verify:** 无字幕场景逻辑正确
- [ ] Task 3: 调整 chunker 接口 (~3 min)
  - **Action:** 修改 chunker 接收提取器数据
  - **Verify:** 接口调整完成

---

## Checkpoint 5: 输出器实现
- [ ] Task 1: 实现 ObsidianWriter (~8 min)
  - **Action:** 创建 `src/outputs/obsidian_writer.py`，实现按UP主分类写入
  - **Verify:** 能创建 `vault/videos/bilibili/{author}/` 目录并写入文件
- [ ] Task 2: 实现 GitSync (~5 min)
  - **Action:** 创建 `src/outputs/git_sync.py`，实现 git commit/push
  - **Verify:** Git 同步逻辑正确
- [ ] Task 3: 测试输出器 (~5 min)
  - **Action:** 用测试数据验证输出
  - **Verify:** 文件结构、frontmatter、内容格式正确

---

## Checkpoint 6: 主流程集成
- [ ] Task 1: 集成提取层到主流程 (~8 min)
  - **Action:** 修改 handler.py 或主入口，调用提取器→处理器→输出器
  - **Verify:** 完整数据流打通
- [ ] Task 2: 添加错误处理 (~5 min)
  - **Action:** 在各层添加 try-except，返回友好错误提示
  - **Verify:** 错误场景有明确提示
- [ ] Task 3: 添加日志记录 (~3 min)
  - **Action:** 添加详细错误日志
  - **Verify:** 日志记录完整

---

## Checkpoint 7: 集成测试
- [ ] Task 1: 完整流程测试（有字幕）(~8 min)
  - **Action:** 用有字幕BV号测试完整流程
  - **Verify:** Obsidian笔记生成正确，内容完整
- [ ] Task 2: 降级流程测试（无字幕）(~5 min)
  - **Action:** 用无字幕BV号测试
  - **Verify:** 优雅降级，输出基础元数据笔记
- [ ] Task 3: 错误场景测试 (~5 min)
  - **Action:** 测试网络错误、无效BV号等
  - **Verify:** 错误提示友好，不崩溃

---

## Checkpoint 8: 文档更新
- [ ] Task 1: 更新 SKILL.md (~5 min)
  - **Action:** 添加提取器说明、配置说明、使用示例
  - **Verify:** 文档完整准确
- [ ] Task 2: 更新 README.md (~3 min)
  - **Action:** 更新项目说明、快速开始
  - **Verify:** README 清晰易懂
- [ ] Task 3: 更新 requirements.txt (~2 min)
  - **Action:** 添加新依赖（playwright, undetected-playwright）
  - **Verify:** 依赖完整

---

## Verification Criteria
- [ ] 所有 checkpoint 完成
- [ ] 有字幕视频：生成完整深度分析笔记
- [ ] 无字幕视频：优雅降级生成基础笔记
- [ ] 按 UP 主分类：目录结构正确
- [ ] 错误处理：所有错误场景有友好提示
- [ ] 文档完整：SKILL.md 和 README.md 更新
- [ ] 用户测试通过：真实视频验证成功

---

## 执行选项

计划已保存到 `memory/plans/obsidian-kb-integration.md`

**1. Single-Agent（本会话串行执行）**
   - 我在这里按顺序完成任务
   - 每个 checkpoint 汇报进度
   - 有问题随时调整

**2. Dispatch Multiple Agents（并行执行）**
   - 派多个子代理并行处理独立任务
   - 整合结果
   - 适合大项目加速

选择哪种执行方式？