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

---
name: kb-workflow
description: 知识库工作流编排技能，提供收件箱扫描、内容处理、归档、订阅检测、Git版本管理和自动清理功能。
metadata:
  short-description: 知识库工作流编排
---

# KB Workflow

## Description

KB Workflow 是一个完整的知识库管理系统，包含：

**核心功能**：
- 📥 **收件箱扫描** - 扫描四个子目录 (pending, metadata, content, analyzed)
- 🔄 **内容处理** - 调用子agent处理各阶段
- 📦 **Git版本管理** - 归档后自动提交并推送
- 🔔 **订阅管理** - 跟踪订阅源更新
- 🧹 **自动清理** - 定期清理临时文件
- 📊 **汇报生成** - 生成处理统计

## 触发方式

### 自然语言触发

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

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

### 支持的平台

| 平台 | 子技能 |
|------|--------|
| Bilibili | kb-bilibili-metadata, kb-bilibili-content |
| 知乎 | kb-zhihu-metadata |

## 架构设计

```
用户: "添加到知识库 https://www.bilibili.com/video/BV1ci4y1V7tb"
     │
     ▼
┌─────────────────────────────────────────────────────────┐
│ kb-workflow (主代理)                                      │
│                                                          │
│ 职责:                                                    │
│ 1. 接收用户消息，识别触发词和链接                          │
│ 2. 查重（根据URL/文件名）                                  │
│ 3. 调用子agent处理各阶段                                  │
│ 4. 文件流转（mv）                                         │
│ 5. Git版本管理                                           │
│ 6. 归档和清理                                             │
└─────────────────────────────────────────────────────────┘
         │              │              │              │
         ▼              ▼              ▼              ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ kb-link-parser│ │kb-bilibili- │ │kb-bilibili- │ │ kb-deep-     │
│  (子agent)    │ │ metadata     │ │ content      │ │ analyzer     │
│               │ │  (子agent)    │ │  (子agent)    │ │  (子agent)    │
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
```

## 处理流程

### 完整流程（6个阶段）

```
用户发送"添加到知识库 + 链接"
        │
        ▼
kb-workflow:
  1. 查重（根据URL/文件名）
  2. 确认目录存在
  3. 调用 kb-link-parser (sessions_spawn)
        │
        ▼
kb-link-parser (子agent):
  解析URL
  输出: pending/bilibili_BV1ci4y1V7tb.link.json
  返回: {"success": true/false, "output_file": "pending/..."}
        │
        ▼
kb-workflow:
  从文件名提取平台 "bilibili" → 调用 kb-bilibili-metadata
        │
        ▼
kb-bilibili-metadata (子agent):
  获取元数据
  输出: metadata/bilibili_BV1ci4y1V7tb.meta.json
  返回: {"success": true/false, "output_file": "metadata/..."}
        │
        ▼
kb-workflow:
  调用 kb-bilibili-content
        │
        ▼
kb-bilibili-content (子agent):
  下载视频+字幕
  输出: content/downloads/*.mp4, *.srt
  返回: {"success": true/false, "output_file": "...", "subtitles": "..."}
        │
        ▼
kb-workflow:
  拿到字幕文件 → 调用 kb-ocr-processor
        │
        ▼
kb-ocr-processor (子agent):
  OCR处理
  输出: content/bilibili_BV1ci4y1V7tb.txt
  返回: {"success": true/false, "output_file": "content/..."}
        │
        ▼
kb-workflow:
  拿到txt文件 → 调用 kb-deep-analyzer
        │
        ▼
kb-deep-analyzer (子agent):
  深度分析
  输出: analyzed/bilibili_BV1ci4y1V7tb.md
  返回: {"success": true/false, "output_file": "analyzed/..."}
        │
        ▼
kb-workflow:
  mv → archive/YYYY-MM-DD/
  git add → commit → push
  汇报完成
```

## 目录结构

```
知识库根目录 KB_BASE_PATH/
├── archive/            # Git归档目录
│   ├── YYYY-MM-DD/    # 按日期归档
│   └── subscriptions/  # 订阅数据
├── pending/           # 链接解析结果 (*.link.json)
├── metadata/          # 元数据 (*.meta.json)
├── content/
│   ├── downloads/     # 视频文件 (*.mp4) - 7天后清理
│   └── subtitles/     # 字幕文件 (*.srt) - 7天后清理
├── frames/            # 视频截帧 (*.jpg) - 7天后清理
└── analyzed/          # 分析报告 (*.md)
```

## 设计原则

### workflow 职责

| 操作 | 说明 |
|------|------|
| 查重 | 根据URL/文件名查重 |
| 创建目录 | 确保 base_path 下目录存在 |
| 调用子agent | 使用 sessions_spawn 调用子技能 |
| 提取文件名 | 从子agent返回的output_file提取 |
| 提取平台 | 从文件名第一个下划线之前提取（不读内容） |
| 传递信息 | 给子agent提示词 + 需要的路径 |
| 文件流转 | 最后归档 |
| Git | commit + push |

### workflow 不管

- 不读文件内容
- 不关心子技能内部格式
- 子技能自己定义输入输出规范

### 子agent 调用方式

```python
# kb-workflow 调用子agent
result = sessions_spawn(
    agentId="子技能名称",
    task="提示词 + 需要的路径信息",
    timeoutSeconds=120
)
```

### 子技能返回格式

所有子技能应返回JSON：

```json
{
  "success": true,
  "output_file": "完整文件路径",
  "subtitles": "字幕文件路径（可选）"
}
```

## 环境变量

```bash
export KB_BASE_PATH="/path/to/knowledge-base"   # 知识库根目录
export KB_GIT_ROOT="/path/to/archive"           # Git仓库目录
export KB_GIT_REMOTE="git@github.com:user/repo.git"  # 远程仓库
export KB_GIT_USER="Username"                   # 用户名
export KB_GIT_EMAIL="user@example.com"          # 邮箱
```

## Usage

### 作为 OpenClaw 技能

当用户发送消息时自动触发：
```
用户: "添加到知识库 https://www.bilibili.com/video/BVxxx"
```

### 作为子代理

```python
# 从其他技能调用
result = sessions_spawn(
    agentId="kb-workflow",
    task="添加到知识库 https://www.bilibili.com/video/BVxxx"
)
```

### 命令行

```bash
# 处理单个URL
python kb_workflow.py --url "https://www.bilibili.com/video/BVxxx"
```

## 子技能集成

| 阶段 | 子技能 | 输出文件 |
|------|--------|----------|
| 链接解析 | kb-link-parser | pending/{platform}_{id}.link.json |
| 元数据 | kb-bilibili-metadata | metadata/{platform}_{id}.meta.json |
| 内容 | kb-bilibili-content | content/downloads/{platform}_{id}.mp4, content/subtitles/{platform}_{id}.srt |
| OCR | kb-ocr-processor | content/{platform}_{id}.txt |
| 分析 | kb-deep-analyzer | analyzed/{platform}_{id}.md |

## Related Skills

- **kb-link-parser** - 链接解析
- **kb-bilibili-metadata** - B站元数据
- **kb-bilibili-content** - B站内容获取
- **kb-deep-analyzer** - 深度分析
- **kb-ocr-processor** - OCR处理