# obsidian-kb 技能改进待办事项

**创建时间**: 2026-02-06 20:15
**技能版本**: 1.0.0
**状态**: 🟡 进行中

---

## 问题记录

### 事件背景

用户通过 WhatsApp 发送 B站视频短链接 `https://b23.tv/oLBZZfK`，期望技能自动处理。实际流程：

1. ❌ 技能未自动触发
2. ⚠️ 短链接解析失败（B站 412 反爬虫）
3. 📝 手动提取 BV 号 `BV1jcFqz7EFW` 成功处理
4. ⚠️ 视频无字幕，生成笔记内容为空

用户反馈的四个问题：
1. 技能应该立刻触发
2. 应该有短链接到长链接的解析过程（手机用户无法获取长链）
3. 为技能增加单个视频链接分析功能
4. 针对没有字幕的，看看有没有本地生成字幕的方法

---

## 待办任务

### ✅ 任务1：实现自动触发机制

**状态**: 已完成 ✓
**完成时间**: 2026-02-06
**优先级**: P0（最高）
**实际工时**: 2 小时

#### 实施结果

**方案A: SKILL.md 触发规则 + Handler 脚本**
在 SKILL.md 中添加了 frontmatter 元数据和触发规则说明，创建了 handler.py 脚本处理链接检测和预览。

**完成的修改**:
- [x] 1.1 研究 OpenClaw 技能触发机制
- [x] 1.2 在 SKILL.md 中添加触发规则（frontmatter + 文档）
- [x] 1.3 创建 handler.py 处理链接检测
- [x] 1.4 测试所有 URL 模式
- [x] 1.5 优化用户体验（确认提示、短链接友好提示）

**文件变更**:
- `skills/obsidian-kb/SKILL.md` - 添加 frontmatter 和触发规则章节
- `skills/obsidian-kb/handler.py` - 新增自动触发处理器
- `skills/obsidian-kb/AUTO_TRIGGER.md` - 新增实现文档

**支持的模式**:
- B站视频: `https://www.bilibili.com/video/BV*`, `BV*`, `https://b23.tv/*`
- YouTube 视频: `https://www.youtube.com/watch?v=*`, `https://youtu.be/*`
- 知乎文章: `https://zhuanlan.zhihu.com/p/*`

**测试结果**:
✅ 所有 URL 模式检测正确
✅ 短链接显示友好提示
✅ 支持批量检测多个链接
✅ 智能去重避免重复显示

详细文档: `skills/obsidian-kb/AUTO_TRIGGER.md`

---

### ✅ 任务2：短链接解析功能

**状态**: 已完成 ✓
**完成时间**: 2026-02-06
**优先级**: P2（中等）
**实际工时**: 1.5 小时

#### 实施结果

**方案A: 用户引导（已实现）**
在检测到短链接时显示友好的用户引导信息，分别针对手机用户和桌面用户提供建议。

**方案B: 浏览器自动化（已实现框架）**
提供了 PlaywrightResolver 类，支持可选的浏览器自动化解析。

**完成的修改**:
- [x] 2.1 评估各方案可行性
- [x] 2.2 实施方案B（用户引导）- 主功能
- [x] 2.3 研究 Playwright 集成 - 可选功能
- [x] 2.4 测试各种短链接场景

#### 文件变更
- `skills/obsidian-kb/shortlink_resolver.py` - 新增短链接解析模块
- `skills/obsidian-kb/handler.py` - 集成短链接检测
- `skills/obsidian-kb/add_video.py` - 支持短链接解析和 Playwright
- `skills/obsidian-kb/SKILL.md` - 更新文档
- `skills/obsidian-kb/AUTO_TRIGGER.md` - 添加短链接章节

#### 核心功能

1. **ShortLinkResolver 类**
   - 检测 B站短链接（b23.tv）
   - 支持其他短链接服务（bit.ly, t.cn, dwz.cn 等）
   - 格式化友好的帮助信息

2. **PlaywrightResolver 类（可选）**
   - 浏览器自动化解析短链接
   - 需要安装：`pip install playwright && playwright install chromium`
   - 在 `add_video.py` 中使用 `--playwright` 参数启用

3. **集成到现有流程**
   - `handler.py` 自动触发时检测短链接
   - `add_video.py` 手动添加时支持短链接
   - 智能区分短链接和完整 URL

#### 测试结果
✅ 单个 B站短链接检测
✅ 多个短链接检测
✅ 友好的用户引导信息
✅ 集成到 handler.py
✅ add_video.py 支持短链接
✅ 完整 URL 和 BV 号正常工作

#### 验收标准
- [x] 短链接能够友好处理（显示引导信息）
- [x] 用户不会感到困惑
- [x] 支持 b23.tv 和其他短链接服务（检测）
- [x] 集成到 handler.py
- [x] 测试各种短链接场景（单个、多个、混合）

详细文档: `skills/obsidian-kb/AUTO_TRIGGER.md`（短链接章节）

---

### 🟡 任务3：单个视频快速添加功能

**优先级**: P1（高）
**预计工时**: 1 小时

#### 问题描述
当前技能是批量订阅模式，缺少快速添加单个视频的命令。用户需要手动编写脚本。

#### 技术方案

**新增命令: `/kb-add`**
```bash
/kb-add <URL>                 # 添加单个视频
/kb-add <URL> --process       # 添加并立即处理
/kb-add <URL> --yes           # 跳过确认
```

**实现位置**: `src/cli.py`

#### 实施步骤
- [ ] 3.1 在 cli.py 中添加 `cmd_add()` 函数
- [ ] 3.2 调用现有的 `BilibiliAdapter.extract_content()`
- [ ] 3.3 调用现有的 `Storage.save_content()`
- [ ] 3.4 支持可选的 `--process` 参数
- [ ] 3.5 更新 SKILL.md 文档

#### 代码示例
```python
def cmd_add(args: argparse.Namespace):
    """添加单个视频到收件箱"""
    adapter = BilibiliAdapter()

    # 解析 URL
    url = resolve_url(args.url)  # 可选：短链接解析

    # 提取内容
    content = adapter.extract_content(url)
    if not content:
        print(f"❌ 无法提取视频: {url}")
        return 1

    # 获取字幕
    content.transcript = adapter.get_transcript(content)

    # 保存
    storage = Storage()
    content.status = ContentStatus.CONFIRMED
    storage.save_content(content)

    print(f"✅ 已添加: {content.title}")
    print(f"   ID: {content.id}")

    # 可选：立即处理
    if args.process:
        pipeline = ProcessingPipeline()
        result = pipeline.process_full(content)
        print(f"📄 笔记: {result.output_path}")
```

#### 验收标准
- [ ] `/kb-add <URL>` 命令可用
- [ ] 支持短链接解析（配合任务2）
- [ ] 支持立即处理选项
- [ ] 更新 SKILL.md 文档

---

### 🔵 任务4：本地生成字幕功能

**优先级**: P3（低）
**预计工时**: 3-5 小时

#### 问题描述
部分视频没有字幕，导致 AI 分析结果为空。

#### 技术方案

**方案A: OpenAI Whisper（本地）**
```python
import whisper

model = whisper.load_model("base")
result = model.transcribe("audio.mp3")
print(result["text"])
```

**方案B: 阿里云语音识别（API）**
使用 Aliyun TTS/ASR API（如果已配置）

**方案C: 腾讯云语音识别（API）**
使用腾讯云 ASR API

#### 实施步骤
- [ ] 4.1 评估各方案：Whisper（本地免费）vs 云API（更准确）
- [ ] 4.2 下载视频音频（使用 yt-dlp）
- [ ] 4.3 实现字幕生成
- [ ] 4.4 支持多语言识别
- [ ] 4.5 添加缓存机制（避免重复生成）

#### 代码示例
```python
def generate_subtitles(content: Content) -> str:
    """为无字幕视频生成字幕"""

    # 1. 下载音频
    audio_path = download_audio(content.url)

    # 2. 语音识别
    model = whisper.load_model("base")
    result = model.transcribe(
        audio_path,
        language="zh",  # 自动检测
        task="transcribe"
    )

    # 3. 转换为 SRT 格式
    srt_text = to_srt(result["segments"])

    # 4. 保存到缓存
    cache_path = f"cache/subtitles/{content.id}.srt"
    save_subtitle(cache_path, srt_text)

    return srt_text
```

#### 验收标准
- [ ] 无字幕视频能生成字幕
- [ ] 字幕准确度可接受
- [ ] 处理时间合理（5分钟视频 < 1分钟）
- [ ] 支持中文字幕

---

## 技术依赖

### Whisper（本地方案）
```bash
pip install openai-whisper
pip install ffmpeg  # 系统依赖
```

### Playwright（短链接解析）
```bash
pip install playwright
playwright install chromium
```

### yt-dlp（音频下载）
```bash
pip install yt-dlp
```

---

## 实施路线图

### Phase 1: 快速修复（1-2天）
- ✅ 任务3：单个视频添加功能（1h）
- 🔲 任务1：自动触发机制（1-2h）

### Phase 2: 体验优化（3-5天）
- 🔲 任务2：短链接解析（2-3h）
- 🔲 测试与文档更新

### Phase 3: 功能增强（可选）
- 🔲 任务4：本地生成字幕（3-5h）
- 🔲 性能优化与错误处理

---

## 测试用例

### 自动触发测试
- 发送完整 URL → 触发
- 发送短链接 → 触发或引导
- 发送 BV 号 → 触发
- 发送非视频链接 → 不触发

### 单个添加测试
```bash
python3 src/cli.py add "https://www.bilibili.com/video/BVxxxxx"
python3 src/cli.py add "BVxxxxx"
python3 src/cli.py add "https://b23.tv/xxxxx"
python3 src/cli.py add "https://www.bilibili.com/video/BVxxxxx" --process
```

### 字幕生成测试
- 有字幕视频 → 跳过生成
- 无字幕视频 → 生成字幕
- 长视频 → 分段识别
- 多语言视频 → 正确识别

---

## 备注

### 当前临时方案
- `skills/obsidian-kb/add_video.py` - 单个视频添加脚本
- 手动用 curl 解析短链接
- 跳过无字幕视频

### 相关文件
- 技能目录: `skills/obsidian-kb/`
- CLI 入口: `src/cli.py`
- B站适配器: `src/sources/bilibili.py`
- 存储管理: `src/storage.py`
- 处理管道: `src/pipeline.py`

---

*最后更新: 2026-02-06 20:15*