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

# KB Workflow

## 触发条件

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

---

## 状态机定义

工作流是一个严格的状态机，每个状态有明确的前置条件和后置条件：

| 状态 | 前置条件 | 执行动作 | 成功后进入 | 失败处理 |
|------|---------|---------|-----------|---------|
| `init` | 用户触发 + URL 有效 | 创建 state.json，检查环境变量 | `link_parse` | 报错退出 |
| `link_parse` | state.json 存在 | 解析链接，提取平台和ID | `metadata` | 记录错误，最多重试1次 |
| `metadata` | platform, content_id 已知 | 提取元数据 | `content` | 记录错误，最多重试1次 |
| `content` | 元数据文件存在 | 下载内容/字幕 | `analyze` 或 `whisper` | 根据错误类型处理 |
| `whisper` | 视频已下载，无官方字幕 | 语音识别转文字 | `analyze` | 尝试 OCR 降级 |
| `analyze` | 有文本内容（字幕/识别结果/文章） | AI 深度分析 | `archive` | **流程失败，报错退出** |
| `archive` | 分析报告存在 | 归档 + Git 提交 | `done` | 记录错误，可手动处理 |
| `done` | - | 汇报完成 | - | - |

### 状态判断流程图

```
用户发送链接
    ↓
┌─────────────────────────────────────┐
│ Step 0: 环境变量检查                 │
│ 缺少必需变量 → 报错退出              │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│ Step 1: 链接解析 (link_parse)        │
│ 输出: platform, content_type, id     │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│ Step 2: 元数据提取 (metadata)        │
│ 输出: title, author, etc.            │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│ content_type 判断                    │
├─────────────────────────────────────┤
│ video/zvideo → Step 3a (视频处理)   │
│ article/zhuanlan/question → Step 3b │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│ Step 3a: 视频处理                    │
│ 有官方字幕? → 是 → Step 5           │
│            → 否 → Step 4 (Whisper)  │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│ Step 3b: 文章处理                    │
│ 提取文字 → 直接进入 Step 5          │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│ Step 4: Whisper 语音识别 (可选)      │
│ 无字幕时执行，生成 text/json/srt     │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│ Step 5: 深度分析 (analyze)           │
│ ⚠️ 必须成功，否则流程失败            │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│ Step 6: 归档 (archive)               │
│ 复制到归档目录 + Git 提交            │
└─────────────────────────────────────┘
    ↓
   完成
```

---

## 环境变量清单

### 必需变量（缺失则报错退出）

| 变量名 | 用途 | 示例 |
|--------|------|------|
| `AI_API_KEY` | AI API 密钥 | `your-api-key` |
| `AI_PROVIDER` | AI 提供商 | `zhipu` / `openai` / `minimax` |
| `AI_MODEL` | 模型名称 | `glm-5` / `gpt-4` |
| `AI_BASE_URL` | API 端点 | `https://open.bigmodel.cn/api/coding/paas/v4` |

### 可选变量

| 变量名 | 用途 | 用途说明 |
|--------|------|---------|
| `BILIBILI_COOKIE` | B站登录态 | 下载会员视频 |
| `ZHIHU_COOKIE` | 知乎登录态 | 访问专栏等 |
| `HF_TOKEN` | HuggingFace Token | 说话者分离功能 |
| `KB_ARCHIVE_PATH` | 归档目录 | 默认 `~/work/zq/30.资源/AI分析` |
| `KB_GIT_ROOT` | Git 仓库根目录 | 默认 `~/work/zq` |
| `KB_GIT_USER` | Git 提交用户名 | 归档时使用 |
| `KB_GIT_EMAIL` | Git 提交邮箱 | 归档时使用 |

### 配置方法

```bash
# 创建专用配置文件
cat > ~/.kb_env << 'EOF'
export AI_API_KEY="your-api-key"
export AI_PROVIDER="zhipu"
export AI_MODEL="glm-5"
export AI_BASE_URL="https://open.bigmodel.cn/api/coding/paas/v4"
export BILIBILI_COOKIE="SESSDATA=xxx; bili_jct=xxx"
export KB_ARCHIVE_PATH="$HOME/work/zq/30.资源/AI分析"
export KB_GIT_ROOT="$HOME/work/zq"
EOF

# 在 ~/.bashrc 中添加
[ -f ~/.kb_env ] && source ~/.kb_env
```

---

## 步骤详解

### Step 0: 环境变量检查

**前置条件：** 无

**执行命令：**
```bash
# 加载环境变量
if [ -f ~/.kb_env ]; then source ~/.kb_env; fi

# 检查必需变量
for var in AI_API_KEY AI_PROVIDER AI_MODEL AI_BASE_URL; do
    if [ -z "${!var}" ]; then
        echo "❌ 错误：$var 未设置"
        exit 1
    fi
done
echo "✅ 环境变量检查通过"
```

**成功标准：**
- 所有必需变量已设置
- 输出 "✅ 环境变量检查通过"

**失败处理：**
- 缺少任何必需变量 → 报错退出，提示用户配置

**输出示例：**
```
✅ 环境变量检查通过
   AI_PROVIDER: zhipu
   AI_MODEL: glm-5
```

**错误示例：**
```
❌ 错误：AI_API_KEY 未设置
请配置以下环境变量：
  - AI_API_KEY
  - AI_PROVIDER
  - AI_MODEL
  - AI_BASE_URL
```

---

### Step 1: 链接解析

**前置条件：**
- 环境变量检查通过
- URL 格式有效

**执行命令：**
```bash
# 获取目录路径
python3 ~/.openclaw/skills/kb-workflow/kb_workflow.py --pending

# 解析链接
python3 ~/.openclaw/skills/kb-link-parser/link-parser.py --url "[URL]"
```

**成功标准：**
- 返回 JSON 包含 `success: true`
- 包含字段：`platform`, `content_type`, `content_id`
- 生成文件：`pending/{platform}_{id}.link.json`

**失败处理：**
- 不支持的平台 → 报错退出，告知用户支持的平台
- URL 无效 → 报错退出，请用户提供正确链接

**输出示例：**
```json
{
  "success": true,
  "platform": "bilibili",
  "content_type": "video",
  "content_id": "BV1xx411c7mD",
  "output_file": "pending/bilibili_BV1xx411c7mD.link.json"
}
```

**错误示例：**
```json
{
  "success": false,
  "error": "不支持的平台: example.com",
  "supported_platforms": ["bilibili.com", "zhihu.com", "youtube.com"]
}
```

---

### Step 2: 元数据提取

**前置条件：**
- Step 1 完成
- `platform`, `content_type`, `content_id` 已知

**执行命令：**
```bash
# 获取目录路径
python3 ~/.openclaw/skills/kb-workflow/kb_workflow.py --metadata

# 根据平台选择命令
# B站视频
python3 ~/.openclaw/skills/kb-bilibili-metadata/bilibili_metadata.py \
    --id "[BV号]" --type video \
    --output "metadata/bilibili_[BV号].meta.json"

# B站专栏
python3 ~/.openclaw/skills/kb-bilibili-metadata/bilibili_metadata.py \
    --id "[cv号]" --type article \
    --output "metadata/bilibili_cv[cv号].meta.json"

# 知乎问答
python3 ~/.openclaw/skills/kb-zhihu-metadata/zhihu_metadata.py \
    --id "[问题ID]" --type question \
    --output "metadata/zhihu_[ID].meta.json"

# 知乎视频
python3 ~/.openclaw/skills/kb-zhihu-metadata/zhihu_metadata.py \
    --id "[视频ID]" --type zvideo \
    --output "metadata/zhihu_[ID].meta.json"
```

**成功标准：**
- 返回 JSON 包含 `success: true`
- 包含字段：`platform`, `content_id`, `title`
- 生成文件：`metadata/{platform}_{id}.meta.json`

**失败处理：**
- 网络错误 → 重试1次
- 内容不存在 → 报错退出
- 需要登录 → 提示配置 Cookie

**输出示例：**
```json
{
  "success": true,
  "platform": "bilibili",
  "content_id": "BV1xx411c7mD",
  "content_type": "video",
  "title": "视频标题",
  "author": "UP主名字",
  "duration": "10:30",
  "output_file": "metadata/bilibili_BV1xx411c7mD.meta.json"
}
```

**错误示例：**
```json
{
  "success": false,
  "error": "视频不存在或已被删除",
  "content_id": "BV1xx411c7mD"
}
```

---

### Step 3a: 视频内容下载

**前置条件：**
- Step 2 完成
- `content_type` 为 `video` 或 `zvideo`

**执行命令：**
```bash
# 获取目录路径
python3 ~/.openclaw/skills/kb-workflow/kb_workflow.py --content_downloads

# B站视频 - 优先尝试字幕
python3 ~/.openclaw/skills/kb-bilibili-content/bilibili_content.py \
    --id "[BV号]" --type subtitle-download \
    --output "content/downloads/"

# 检查是否有官方字幕
# 如果 has_subtitle=true → 进入 Step 5
# 如果 has_subtitle=false → 下载视频，进入 Step 4
```

**成功标准：**
- 返回 JSON 包含 `success: true`
- `has_subtitle=true`: 有字幕文件
- `has_subtitle=false`: 视频文件下载成功

**失败处理：**
- 403 禁止访问 → 检查 BILIBILI_COOKIE 配置
- 网络超时 → 重试1次
- 会员视频 → 提示需要配置 Cookie

**输出示例（有字幕）：**
```json
{
  "success": true,
  "type": "subtitle",
  "has_subtitle": true,
  "subtitle_file": "content/downloads/bilibili_BV1xx411c7mD.srt",
  "message": "官方字幕下载成功"
}
```

**输出示例（无字幕）：**
```json
{
  "success": true,
  "type": "subtitle",
  "has_subtitle": false,
  "message": "无官方字幕，需要下载视频进行语音识别"
}
```

**错误示例：**
```json
{
  "success": false,
  "error": "403 Forbidden - 可能需要会员权限",
  "suggestion": "请配置 BILIBILI_COOKIE 环境变量"
}
```

---

### Step 3b: 文章内容提取

**前置条件：**
- Step 2 完成
- `content_type` 为 `article`、`zhuanlan` 或 `question`

**执行命令：**
```bash
# B站专栏
python3 ~/.openclaw/skills/kb-bilibili-content/bilibili_content.py \
    --id "[cv号]" --type article \
    --output "content/"

# 知乎专栏
python3 ~/.openclaw/skills/kb-zhihu-content/zhihu_content.py \
    --type article-from-media \
    --output "content/"
```

**成功标准：**
- 返回 JSON 包含 `success: true`
- 包含字段：`filepath`, `content_length`
- 跳过 Step 4，直接进入 Step 5

**输出示例：**
```json
{
  "success": true,
  "type": "article",
  "filepath": "content/bilibili_cv43780186.txt",
  "content_length": 5234,
  "message": "文章内容提取成功"
}
```

---

### Step 4: Whisper 语音识别

**前置条件：**
- Step 3a 完成
- `has_subtitle=false`
- 视频文件已下载

**执行命令：**
```bash
# 获取目录路径
python3 ~/.openclaw/skills/kb-workflow/kb_workflow.py --content

# 普通识别
python3 ~/.openclaw/skills/kb-whisper/whisper.py \
    --input "content/downloads/bilibili_BV1xx411c7mD.mp4" \
    --model base \
    --output "content/"

# 带说话者分离（需要 HF_TOKEN）
if [ -n "$HF_TOKEN" ]; then
    python3 ~/.openclaw/skills/kb-whisper-diarization/whisper_diarization.py \
        --input "content/downloads/bilibili_BV1xx411c7mD.mp4" \
        --model base --diarize \
        --output "content/"
fi
```

**成功标准：**
- 返回 JSON 包含 `success: true`
- 生成文件：`.json`, `.txt`, `.srt`

**失败处理：**
- 模型未下载 → 提示下载模型
- 内存不足 → 尝试更小的模型
- Whisper 失败 → 尝试 OCR 降级

**输出示例：**
```json
{
  "success": true,
  "input_file": "content/downloads/bilibili_BV1xx411c7mD.mp4",
  "model": "base",
  "output_files": {
    "json": "content/bilibili_BV1xx411c7mD.json",
    "txt": "content/bilibili_BV1xx411c7mD.txt",
    "srt": "content/bilibili_BV1xx411c7mD.srt"
  },
  "duration_seconds": 630
}
```

---

### Step 5: 深度分析

**前置条件：**
- 有文本内容（字幕/识别结果/文章）
- 元数据文件存在

**执行命令：**
```bash
# 获取目录路径
python3 ~/.openclaw/skills/kb-workflow/kb_workflow.py --analyzed

# 分析视频
AI_API_KEY="$AI_API_KEY" AI_PROVIDER="zhipu" AI_MODEL="glm-5" \
python3 -u ~/.openclaw/skills/kb-deep-analyzer/deep_analyzer.py \
    --metadata "metadata/bilibili_BV1xx411c7mD.meta.json" \
    --content "content/bilibili_BV1xx411c7mD.json" \
    --output "analyzed/bilibili_BV1xx411c7mD.md" \
    --type video \
    --provider zhipu --model glm-5

# 分析文章
AI_API_KEY="$AI_API_KEY" AI_PROVIDER="zhipu" AI_MODEL="glm-5" \
python3 -u ~/.openclaw/skills/kb-deep-analyzer/deep_analyzer.py \
    --metadata "metadata/xxx.meta.json" \
    --content "content/xxx.txt" \
    --output "analyzed/xxx.md" \
    --type article \
    --provider zhipu --model glm-5
```

**成功标准：**
- 返回 JSON 包含 `success: true`
- 生成分析报告文件

**失败处理：**
- ⚠️ **深度分析失败 = 整个流程失败**
- API 调用失败 → 记录错误，**终止流程**
- **禁止**使用预设模板或降级内容

**输出示例：**
```json
{
  "success": true,
  "output_file": "analyzed/bilibili_BV1xx411c7mD.md",
  "model": "glm-5",
  "provider": "zhipu"
}
```

**错误示例：**
```json
{
  "success": false,
  "error": "AI API 调用失败: rate limit exceeded",
  "message": "深度分析失败，整个流程终止"
}
```

---

### Step 6: 归档

**前置条件：**
- Step 5 完成
- 分析报告文件存在

**执行命令：**
```bash
# 归档
python3 ~/.openclaw/skills/kb-workflow/kb_workflow.py \
    --archive-file "analyzed/bilibili_BV1xx411c7mD.md"

# 如果配置了 Git，会自动提交
```

**成功标准：**
- 文件复制到归档目录
- Git 提交成功（如果配置）

**失败处理：**
- 归档失败 → 记录错误，文件仍可用
- Git 失败 → 不影响主流程

**输出示例：**
```json
{
  "success": true,
  "archive_path": "~/work/zq/30.资源/AI分析/2026-03-13/bilibili_BV1xx411c7mD.md",
  "git_commit": "abc1234"
}
```

---

## 目录结构

```
~/work/knowledge-base/           # 知识库根目录
├── pending/                     # 待处理链接
│   └── {platform}_{id}.link.json
├── metadata/                    # 元数据
│   └── {platform}_{id}.meta.json
├── content/                     # 内容
│   ├── downloads/               # 视频下载
│   │   └── {platform}_{id}.mp4
│   ├── {platform}_{id}.txt      # 文本内容
│   └── {platform}_{id}.json     # Whisper 结果
└── analyzed/                    # 深度分析报告
    └── {platform}_{id}.md

~/work/zq/30.资源/AI分析/        # 归档目录
└── YYYY-MM-DD/
    └── {platform}_{id}.md
```

---

## 子技能清单

| 步骤 | 子技能 | 命令 |
|------|--------|------|
| 1 | kb-link-parser | `--url "[URL]"` |
| 2 | kb-bilibili-metadata | `--id "[ID]" --type video --output "[PATH]"` |
| 2 | kb-zhihu-metadata | `--id "[ID]" --type question --output "[PATH]"` |
| 3a | kb-bilibili-content | `--id "[ID]" --type subtitle-download --output "[PATH]"` |
| 3a | kb-bilibili-content | `--id "[ID]" --type video --output "[PATH]"` |
| 3b | kb-bilibili-content | `--id "[ID]" --type article --output "[PATH]"` |
| 3b | kb-zhihu-content | `--type article-from-media --output "[PATH]"` |
| 4 | kb-whisper | `--input "[VIDEO]" --model base --output "[PATH]"` |
| 4 | kb-whisper-diarization | `--input "[VIDEO]" --model base --diarize --output "[PATH]"` |
| 5 | kb-deep-analyzer | `--metadata "[META]" --content "[CONTENT]" --output "[OUT]" --type video` |

---

## 端到端示例

### 示例 1: B站视频（有官方字幕）

**输入：** `添加到知识库 https://www.bilibili.com/video/BV1xx411c7mD`

```
Step 0: ✅ 环境变量检查通过
Step 1: ✅ 链接解析 → bilibili, video, BV1xx411c7mD
Step 2: ✅ 元数据提取 → 标题: "xxx", 作者: "xxx"
Step 3a: ✅ 字幕下载 → has_subtitle=true, bilibili_BV1xx411c7mD.srt
Step 4: ⏭️ 跳过（有官方字幕）
Step 5: ✅ 深度分析 → bilibili_BV1xx411c7mD.md
Step 6: ✅ 归档 → ~/work/zq/30.资源/AI分析/2026-03-13/
```

### 示例 2: B站视频（无官方字幕）

**输入：** `添加到知识库 https://www.bilibili.com/video/BV1yy411c7mE`

```
Step 0: ✅ 环境变量检查通过
Step 1: ✅ 链接解析 → bilibili, video, BV1yy411c7mE
Step 2: ✅ 元数据提取 → 标题: "xxx", 时长: "15:30"
Step 3a: ⚠️ 无官方字幕 → 下载视频
Step 3a: ✅ 视频下载 → bilibili_BV1yy411c7mE.mp4
Step 4: ✅ Whisper 识别 → bilibili_BV1yy411c7mE.json/txt/srt
Step 5: ✅ 深度分析 → bilibili_BV1yy411c7mE.md
Step 6: ✅ 归档
```

### 示例 3: 403 下载失败

**输入：** `添加到知识库 https://www.bilibili.com/video/BV1zz411c7mF`

```
Step 0: ✅ 环境变量检查通过
Step 1: ✅ 链接解析
Step 2: ✅ 元数据提取
Step 3a: ❌ 403 Forbidden
         → 可能需要会员权限
         → 请配置 BILIBILI_COOKIE 环境变量
         → 流程暂停，等待用户处理
```

---

## 常见错误处理

### 错误 1: 环境变量未设置

**症状：** `❌ 错误：AI_API_KEY 未设置`

**解决：**
```bash
echo 'export AI_API_KEY="your-key"' >> ~/.kb_env
source ~/.kb_env
```

### 错误 2: 403 下载失败

**症状：** B站视频下载返回 403

**解决：**
1. 获取 B站 Cookie（F12 → Network → Copy Cookie）
2. 配置环境变量：
```bash
echo 'export BILIBILI_COOKIE="SESSDATA=xxx; bili_jct=xxx"' >> ~/.kb_env
source ~/.kb_env
```

### 错误 3: 深度分析失败

**症状：** `success: false` from kb-deep-analyzer

**处理：**
- **整个流程终止**
- 检查 AI_API_KEY 是否有效
- 检查 AI_BASE_URL 是否正确
- 检查模型配额是否用尽

### 错误 4: Whisper 模型未下载

**症状：** `Model file not found`

**解决：**
```bash
cd ~/whisper.cpp
./models/download-ggml-model.sh base
```

---

## 状态管理（断点续传）

> ⚠️ 此功能需要完成 P3 实现

```bash
# 初始化状态
python3 kb_workflow.py --init-state "[URL]"

# 查询当前状态
python3 kb_workflow.py --get-state "[URL]"

# 推进到下一步
python3 kb_workflow.py --advance-step "[URL]" "metadata"

# 记录错误
python3 kb_workflow.py --record-error "[URL]" "403 Forbidden"

# 获取恢复指令
python3 kb_workflow.py --resume "[URL]"
```

---

## ⚠️ 严格失败处理原则

1. **深度分析不可跳过**：kb-deep-analyzer 是必须成功的步骤
2. **失败即终止**：如果深度分析返回 `success: false`，必须立即停止
3. **禁止降级处理**：不能使用预设模板或简单摘要"假装成功"
4. **每次执行都要使用 AI**：必须有真实的 AI API 调用