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

---
name: kb-workflow
description: 知识库工作流编排技能。接收"添加到知识库 + 链接"消息，编排各子代理完成完整处理流程。
metadata:
  short-description: 知识库工作流编排
---

# KB Workflow

## 触发条件

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

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

## Workflow 步骤

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

### 步骤 1: 查重

**操作：** 检查知识库是否已存在此内容。

1. 根据 URL 中的 ID（如 `BVxxx`）扫描 `knowledge-base/metadata/` 和 `knowledge-base/archive/` 目录
2. 如果存在：
   - 汇报用户内容已存在及其状态
   - 询问用户是要更新还是跳过
   - 等待用户指示
3. 如果不存在：继续步骤 2

### 步骤 2: 调用 kb-link-parser

**操作：** 解析 URL，获取平台和内容 ID。

```python
# 调用方式
result = sessions_spawn(
    agentId="kb-link-parser",
    task="""解析以下URL，将结果保存到指定目录：

URL: [用户的URL]

输出目录: ~/work/knowledge-base/pending
输出文件名格式: {platform}_{id}.link.json

请解析URL中的平台和内容ID，将解析结果保存为JSON文件。
返回结果时告诉我输出文件的完整路径。""",
    timeoutSeconds=60
)
```

**预期输出：** `pending/{platform}_{id}.link.json`

### 步骤 3: 提取平台并调用对应元数据技能

**操作：** 从文件名提取平台（如 `bilibili`），调用对应平台的元数据技能。

```python
# 从返回结果中提取 output_file
output_file = result.get("output_file")
platform = output_file.split("/")[-1].split("_")[0]  # 从文件名提取平台
content_id = output_file.split("/")[-1].split("_")[1].split(".")[0]
```

**调用元数据技能：**

```python
if platform == "bilibili":
    agent = "kb-bilibili-metadata"
elif platform == "zhihu":
    agent = "kb-zhihu-metadata"

result = sessions_spawn(
    agentId=agent,
    task="""获取链接的元数据：

链接文件: [上一步的output_file]
输出目录: ~/work/knowledge-base/metadata

请读取链接文件，提取URL，然后获取该链接的元数据（标题、作者、播放量等）。
将元数据保存为JSON文件，文件名格式: {platform}_{id}.meta.json

返回结果时告诉我输出文件的完整路径。""",
    timeoutSeconds=120
)
```

**预期输出：** `metadata/{platform}_{id}.meta.json`

### 步骤 4: 调用内容下载技能

**操作：** 根据平台调用内容下载技能。

```python
if platform == "bilibili":
    agent = "kb-bilibili-content"

result = sessions_spawn(
    agentId=agent,
    task="""下载视频内容：

元数据文件: [上一步的output_file]
下载目录: ~/work/knowledge-base/content

请读取元数据文件，获取视频信息，然后下载视频和字幕。
视频保存到: content/downloads/
字幕保存到: content/subtitles/

文件名格式: {platform}_{id}.mp4 和 {platform}_{id}.srt

返回结果时告诉我下载的视频文件和字幕文件的完整路径。""",
    timeoutSeconds=600
)
```

**预期输出：**
- `content/downloads/{platform}_{id}.mp4`
- `content/subtitles/{platform}_{id}.srt`（可能没有）

### 步骤 5: OCR 处理

**操作：** 对视频或字幕进行 OCR 提取文字。

```python
subtitle_file = result.get("subtitle") or result.get("subtitles")
video_file = result.get("output_file")

# 如果有字幕用字幕，没有就用视频
ocr_source = subtitle_file or video_file

result = sessions_spawn(
    agentId="kb-ocr-processor",
    task="""处理文件，提取文字内容：

源文件: [ocr_source]
输出目录: ~/work/knowledge-base/content

请读取文件，提取文字内容。
输出文件名格式: {platform}_{id}.txt

返回结果时告诉我输出文件的完整路径。""",
    timeoutSeconds=1800  # 30分钟
)
```

**预期输出：** `content/{platform}_{id}.txt`

### 步骤 6: 深度分析

**操作：** 调用深度分析生成最终报告。

```python
result = sessions_spawn(
    agentId="kb-deep-analyzer",
    task="""深度分析内容：

元数据文件: [步骤3的output_file]
文字内容文件: [步骤5的output_file]（如果存在，否则用元数据文件）
输出目录: ~/work/knowledge-base/analyzed

请读取元数据和文字内容，进行深度分析。
生成分析报告，保存为Markdown文件。
文件名格式: {platform}_{id}.md

分析报告应包含：
- 一句话总结
- 核心要点
- 时间轴（如适用）
- 推荐标签

返回结果时告诉我输出文件的完整路径。""",
    timeoutSeconds=180
)
```

**预期输出：** `analyzed/{platform}_{id}.md`

### 步骤 7: 归档和 Git

**操作：** 移动文件到归档目录，提交 Git。

```python
# 1. 创建归档目录
date_dir = Path.home() / "work/knowledge-base/archive" / datetime.now().strftime('%Y-%m-%d')
date_dir.mkdir(parents=True, exist_ok=True)

# 2. 移动分析报告
analyzed_file = Path(result.get("output_file"))
archive_file = date_dir / analyzed_file.name
shutil.copy(analyzed_file, archive_file)

# 3. 复制元数据
meta_file = Path.home() / "work/knowledge-base/metadata" / f"{analyzed_file.stem}.meta.json"
if meta_file.exists():
    shutil.copy(meta_file, date_dir / meta_file.name)

# 4. Git commit（如果已初始化）
git_root = Path.home() / "work/knowledge-base/archive"
subprocess.run(['git', 'add', '.'], cwd=str(git_root))
subprocess.run(['git', 'commit', '-m', f"Archive: {analyzed_file.name}"], cwd=str(git_root))
```

### 步骤 8: 汇报完成

**操作：** 向用户汇报处理结果。

```python
汇报内容：
- 视频标题
- 处理阶段完成情况
- 最终文件路径
- Git commit 信息
```

## 目录结构

```
~/work/knowledge-base/
├── archive/
│   └── YYYY-MM-DD/
│       └── {platform}_{id}.md          # 分析报告
│       └── {platform}_{id}.meta.json   # 元数据
├── pending/
│   └── {platform}_{id}.link.json       # 链接解析结果
├── metadata/
│   └── {platform}_{id}.meta.json       # 元数据
├── content/
│   ├── downloads/
│   │   └── {platform}_{id}.mp4         # 视频文件
│   ├── subtitles/
│   │   └── {platform}_{id}.srt         # 字幕文件
│   └── {platform}_{id}.txt             # OCR结果
└── analyzed/
    └── {platform}_{id}.md              # 分析报告
```

## 环境变量（可选）

```bash
export KB_BASE_PATH="~/work/knowledge-base"  # 知识库根目录
```

## 支持的平台

| 平台 | 元数据技能 | 内容技能 |
|------|-----------|---------|
| Bilibili | kb-bilibili-metadata | kb-bilibili-content |
| 知乎 | kb-zhihu-metadata | - |

## 注意事项

1. **文件名提取平台：** 从文件名第一个下划线之前提取（如 `bilibili_BVxxx.link.json` → `bilibili`）
2. **不读文件内容：** workflow 只根据文件名判断，不读取文件内部
3. **超时设置：** OCR 步骤较长，建议 30 分钟超时
4. **子代理权限：** 确保子代理已在 allowlist 中配置