openclaw-skills/skills/kb-workflow/SKILL.md

---
name: kb-workflow
description: 当收到"添加到知识库 + 链接" 或"保存到知识库 + 链接"时使用
---

# KB Workflow

## 什么时候使用

当用户发送包含以下模式的消息时，此技能自动触发：

| 触发词 | 行为 | 示例 |
|--------|------|------|
| `添加到知识库` + 链接 | 添加到知识库并处理 | "添加到知识库 https://www.bilibili.com/video/BVxxx" |
| `保存到知识库` + 链接 | 同上 | "保存到知识库 https://www.bilibili.com/video/BVxxx" |

## 环境变量

在执行 workflow 之前，必须检查环境变量是否已经设置。
以下是必须的环境变量，如果缺失必须询问用户获得。没有全部设置完成之前禁止进行后续操作。      
| 变量名 | 用途 | 示例 |
|--------|------|------|
| `KB_BASE_PATH` | 知识库根目录 | `~/work/kb`
| `AI_API_KEY` | AI深度分析 | `sk-xxx` |
| `AI_PROVIDER` | AI提供商 | `openai`, `zhipu`, `minimax` |
| `AI_MODEL` | AI模型 | `gpt-4` |

以下是可选的环境变量，询问用户是否要设置，允许暂时跳过
| 变量名 | 用途 | 示例 |
|--------|------|------|
| `BILIBILI_COOKIE` | 下载会员视频 | `SESSDATA=xxx; bili_jct=xxx` |
| `KB_GIT_USER` | Git提交用户名 | `Your Name` |
| `KB_GIT_EMAIL` | Git提交邮箱 | `your@email.com` |


## Workflow 执行方式

主代理直接执行以下步骤，无需启动 kb-workflow 子代理：

1. 主代理启动子代理调用 kb-link-parser
2. 主代理启动子代理调用 kb-平台-metadata
3. 主代理启动子代理调用 kb-平台-content
4. 主代理启动子代理调用 kb-ocr-processor（如需要）
5. 主代理启动子代理调用 kb-deep-analyzer
6. 主代理执行 `kb_workflow.py --archive-file` 归档


## Workflow 执行步骤

当触发后，按照以下步骤执行：

### 步骤 1: 环境变量检查
立刻告知用户，启用技能kb-workflow.
参考环境变量标题下内容执行。
如果必须的环境变量都没问题，继续执行下面的步骤。

### 步骤 2: 链接解析

1. 获取目录路径：
```bash
python3 kb_workflow.py --pending
```

2. 启动子代理调用 kb-link-parser：
```bash
python3 /path/to/link-parser.py --url "[URL]"
```

3. 解析输出 JSON，提取 filename 和 platform

### 步骤 3: 元数据提取

1. 获取元数据目录路径：
```bash
python3 kb_workflow.py --metadata
# 返回: {"path": "/home/admin/work/knowledge-base/metadata"}
```

2. 构建输出文件路径：`${metadata_dir}/${platform}_${id}.meta.json`

3. 启动子代理调用对应平台的 metadata 技能（传入 `--output`）：
```bash
# Bilibili
python3 /path/to/bilibili_metadata.py --id "[ID]" --type video --output "${metadata_dir}/bilibili_[ID].meta.json"

# Zhihu
python3 /path/to/zhihu_metadata.py --id "[ID]" --type question --output "${metadata_dir}/zhihu_[ID].meta.json"
```

4. 解析输出 JSON，提取 filename

### 步骤 4: 内容下载

1. 获取目录路径：
```bash
python3 kb_workflow.py --content_downloads
python3 kb_workflow.py --content
```

2. 启动子代理调用对应平台的 content 技能：
```bash
# Bilibili 字幕下载（自动检测是否有官方字幕）
python3 /path/to/bilibili_content.py --id "[ID]" --type subtitle-download --output [content_dir]

# 返回 JSON 包含 has_subtitle 字段
```

3. 解析输出 JSON：
- **has_subtitle = true**: 有官方字幕，直接进入步骤 6
- **has_subtitle = false**: 没有官方字幕，继续步骤 5

> ⚠️ **重要提示**：没有找到官方字幕是**正常的**！很多视频没有自动生成的字幕。不要因为没有字幕就停止工作流，继续执行 Whisper 步骤即可。

### 步骤 5: 语音识别转文字（仅当没有官方字幕时执行）

> ⚠️ **重要**：此步骤仅在**没有官方字幕**时执行。如果有官方字幕，**跳过此步骤**。

此步骤使用 Whisper 进行语音识别：
- **严禁跳过**：必须等待识别完成
- **定时汇报**：每2-3分钟向用户汇报进度
- **超时时间**：30分钟
- **耐心等待**：不要中途启动其他步骤，必须串行执行

1. 获取目录路径：
```bash
python3 kb_workflow.py --content
```

2. 启动子代理调用 kb-whisper（传入视频路径）：
```bash
# 必须传入 --output 完整路径
python3 /path/to/whisper.py --input [video_path] --model base --output [content_dir]
```

3. 等待 Whisper 完成（定时汇报进度）

4. 解析输出 JSON，生成 content 文件供步骤6使用

### 步骤 6: 深度分析

1. 获取目录路径：
```bash
python3 kb_workflow.py --analyzed
```

2. 准备 content JSON 文件（包含 subtitle/description）

3. 如果有官方字幕，使用官方字幕的 SRT 文件
4. 如果没有官方字幕，使用 Whisper 识别的结果

5. 启动子代理调用 kb-deep-analyzer：
```bash
python3 /path/to/deep_analyzer.py --metadata [meta_path] --content [content_path] --output [analyzed_dir]/[filename].md
```

6. 解析输出 JSON，获取分析结果

### 步骤 7: 归档

运行归档命令：
```bash
python3 kb_workflow.py --archive-file "[分析报告文件路径]"
```

### 步骤 8: 汇报完成

向用户汇报：
- 视频标题
- 处理阶段完成情况
- 最终文件路径
- Git commit 信息


## 子技能清单

| 步骤 | 子技能 | 命令示例 | 输出 | 备注 |
|------|--------|----------|------|------|
| 2 | kb-link-parser | `--url "BVxxx"` | `{p}_{id}.link.json` | |
| 3 | kb-bilibili-metadata | `--id "BVxxx" --type video` | `{p}_{id}.meta.json` | |
| 3 | kb-zhihu-metadata | `--id "xxx" --type question` | `{p}_{id}.meta.json` | |
| 4 | kb-bilibili-content | `--id "BVxxx" --type subtitle-download` | `{p}_{id}.srt` | 如果没有字幕是正常的 |
| 4 | kb-bilibili-content | `--id "BVxxx" --type video` | `{p}_{id}.mp4` | 如果需要下载视频 |
| 5 | kb-whisper | `--input xxx.mp4 --model base` | `{p}_{id}.json`, `{p}_{id}.txt` | 仅当没有官方字幕时执行 |
| 6 | kb-deep-analyzer | `--metadata x.meta.json --content x.json --output x.md` | `{p}_{id}.md` | |

## 条件分支逻辑

```
步骤3: 获取元数据
   ↓
步骤4: 下载字幕 (--type subtitle-download)
   ↓
┌─────────────────────────────────────┐
│ has_subtitle = true?                │
├─────────────────────────────────────┤
│ 是 → 直接进入步骤6（深度分析）       │
│ 否 → 进入步骤5（Whisper语音识别）    │
└─────────────────────────────────────┘
           ↓
步骤6: 深度分析
```

> ⚠️ **重要**：没有找到官方字幕是**正常的**！很多视频没有自动生成的字幕。
> - 如果 `has_subtitle = false`，继续执行 Whisper 步骤
> - 如果 `has_subtitle = true`，跳过 Whisper 步骤，直接使用官方字幕

## 目录结构

```
~/work/knowledge-base/
├── archive/
│   └── YYYY-MM-DD/
├── pending/
│   └── {platform}_{id}.link.json
├── metadata/
│   └── {platform}_{id}.meta.json
├── content/
│   ├── downloads/
│   │   └── {platform}_{id}.mp4
│   ├── {platform}_{id}.txt        # Whisper 识别的文本
│   └── {platform}_{id}.json       # Whisper 完整结果
└── analyzed/
    └── {platform}_{id}.md
```

## 辅助命令

```bash
# ------------------- 查重与归档 -------------------

# 查重
python3 kb_workflow.py --check --url "[URL]"

# 归档分析报告
python3 kb_workflow.py --archive-file "[分析报告路径]"


# ------------------- 目录路径查询 -------------------

# 获取知识库根目录（默认 ~/work/knowledge-base）
python3 kb_workflow.py --base-path "~/custom/path"

# 获取待处理目录（pending）
python3 kb_workflow.py --pending

# 获取元数据目录
python3 kb_workflow.py --metadata

# 获取内容目录
python3 kb_workflow.py --content

# 获取内容下载目录
python3 kb_workflow.py --content_downloads

# 获取字幕目录
python3 kb_workflow.py --content_subtitles

# 获取深度分析目录
python3 kb_workflow.py --analyzed

# 获取归档目录
python3 kb_workflow.py --archive

# 获取订阅信息目录
python3 kb_workflow.py --archive_subscriptions


# ------------------- 工具函数 -------------------

# 从文件名提取平台名称
python3 kb_workflow.py --extract_platform "bilibili_BVxxx.mp4"
```