361 lines
11 KiB
Markdown
361 lines
11 KiB
Markdown
---
|
||
name: kb-workflow
|
||
description: 当收到"添加到知识库 + 链接" 或"保存到知识库 + 链接"时使用
|
||
---
|
||
|
||
# KB Workflow
|
||
|
||
## 什么时候使用
|
||
|
||
当用户发送包含以下模式的消息时，此技能自动触发：
|
||
|
||
| 触发词 | 行为 | 示例 |
|
||
|--------|------|------|
|
||
| `添加到知识库` + 链接 | 添加到知识库并处理 | "添加到知识库 https://www.bilibili.com/video/BVxxx" |
|
||
| `保存到知识库` + 链接 | 同上 | "保存到知识库 https://www.bilibili.com/video/BVxxx" |
|
||
|
||
## 环境变量
|
||
|
||
### 执行前必须检查
|
||
|
||
在执行 workflow 之前，必须检查环境变量是否已经设置。
|
||
|
||
**必须的环境变量**（缺失则报错退出）：
|
||
|
||
配置方式：将变量写入 `~/.kb_env` 文件：
|
||
```bash
|
||
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"
|
||
```
|
||
|
||
**可选的环境变量**：
|
||
| 变量名 | 用途 | 示例 |
|
||
|--------|------|------|
|
||
| `BILIBILI_COOKIE` | 下载会员视频 | `SESSDATA=xxx; bili_jct=xxx` |
|
||
| `KB_GIT_USER` | Git提交用户名 | `Your Name` |
|
||
| `KB_GIT_EMAIL` | Git提交邮箱 | `your@email.com` |
|
||
|
||
### 检查命令
|
||
|
||
```bash
|
||
# 检查必须的环境变量
|
||
echo "AI_API_KEY: ${AI_API_KEY:0:10}..."
|
||
echo "AI_PROVIDER: $AI_PROVIDER"
|
||
echo "AI_MODEL: $AI_MODEL"
|
||
echo "AI_BASE_URL: $AI_BASE_URL"
|
||
|
||
# 验证方式1: 检查变量是否存在
|
||
if [ -z "$AI_API_KEY" ]; then
|
||
echo "❌ AI_API_KEY 未设置"
|
||
exit 1
|
||
fi
|
||
|
||
# 验证方式2: 执行测试调用
|
||
python3 -c "
|
||
import os
|
||
if not os.environ.get('AI_API_KEY'):
|
||
raise RuntimeError('AI_API_KEY 未设置')
|
||
print('✅ 环境变量检查通过')
|
||
"
|
||
```
|
||
|
||
|
||
## 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: 环境变量检查
|
||
|
||
**❌ 禁止跳过此步骤！必须先检查环境变量。**
|
||
|
||
```bash
|
||
# 0. 从 ~/.kb_env 加载环境变量（专门的知识库配置文件，不受 bashrc 交互式检查影响）
|
||
if [ -f ~/.kb_env ]; then
|
||
source ~/.kb_env
|
||
fi
|
||
|
||
# 1. 检查必须的环境变量是否存在
|
||
if [ -z "$AI_API_KEY" ] || [ -z "$AI_PROVIDER" ] || [ -z "$AI_MODEL" ] || [ -z "$AI_BASE_URL" ]; then
|
||
echo "❌ 错误：必须的环境变量未设置"
|
||
echo "请配置以下环境变量："
|
||
echo " - AI_API_KEY"
|
||
echo " - AI_PROVIDER (zhipu/openai/minimax)"
|
||
echo " - AI_MODEL"
|
||
echo " - AI_BASE_URL"
|
||
exit 1
|
||
fi
|
||
|
||
echo "✅ 环境变量检查通过"
|
||
echo " AI_PROVIDER: $AI_PROVIDER"
|
||
echo " AI_MODEL: $AI_MODEL"
|
||
```
|
||
|
||
**如果检查不通过，必须**：
|
||
1. 报错提示用户
|
||
2. 退出，不执行后续步骤
|
||
3. 等待用户配置好环境变量后重新执行
|
||
|
||
## ⚠️ 严格失败处理原则
|
||
|
||
> **深度分析步骤必须成功，否则整个流程失败**
|
||
|
||
在执行工作流时，必须遵守以下原则：
|
||
1. **深度分析不可跳过**：kb-deep-analyzer 是必须成功执行的步骤
|
||
2. **失败即终止**：如果深度分析返回 `success: false`，必须立即停止并汇报失败
|
||
3. **禁止降级处理**：不能使用预设模板或简单摘要来"假装成功"
|
||
4. **每次执行都要使用 AI**：必须有真实的 AI API 调用记录
|
||
|
||
### 步骤 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（使用 g5 模型）：
|
||
```bash
|
||
python3 /path/to/deep_analyzer.py --metadata [meta_path] --content [content_path] --output [analyzed_dir]/[filename].md --provider zhipu --model glm-5
|
||
```
|
||
|
||
**环境变量设置**（在子代理中设置）：
|
||
- `AI_PROVIDER=zhipu`
|
||
- `AI_MODEL=glm-5`
|
||
|
||
6. 解析输出 JSON，检查 `success` 字段：
|
||
|
||
> ⚠️ **深度分析失败 = 整个流程失败**
|
||
> - 如果 `success = true`：继续步骤 7（归档）
|
||
> - 如果 `success = false`：**立即终止流程**，向用户汇报失败原因
|
||
> - **严禁**继续执行后续步骤或使用降级内容"假装成功"
|
||
|
||
### 步骤 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 --provider zhipu --model glm-5` | `{p}_{id}.md` | **使用 g5 模型，必须成功** |
|
||
|
||
## 条件分支逻辑
|
||
|
||
```
|
||
步骤3: 获取元数据
|
||
↓
|
||
步骤4: 下载字幕 (--type subtitle-download)
|
||
↓
|
||
┌─────────────────────────────────────┐
|
||
│ has_subtitle = true? │
|
||
├─────────────────────────────────────┤
|
||
│ 是 → 直接进入步骤6（深度分析） │
|
||
│ 否 → 进入步骤5（Whisper语音识别） │
|
||
└─────────────────────────────────────┘
|
||
↓
|
||
步骤6: 深度分析
|
||
↓
|
||
┌─────────────────────────────────────┐
|
||
│ kb-deep-analyzer 执行结果 │
|
||
├─────────────────────────────────────┤
|
||
│ success = true → 步骤7（归档） │
|
||
│ success = false → ❌ 整个流程失败 │
|
||
└─────────────────────────────────────┘
|
||
```
|
||
|
||
> ⚠️ **重要：深度分析失败则整个流程失败**
|
||
> - 深度分析必须使用正确的 AI 模型（glm-4.7）完整分析字幕内容
|
||
> - 如果 `kb-deep-analyzer` 返回 `success: false`，**必须汇报失败**，不能继续执行后续步骤
|
||
> - 不能使用预设模板或降级内容来"假装成功"
|
||
> - 失败时必须向用户报告具体的错误原因
|
||
|
||
> ⚠️ **重要**：没有找到官方字幕是**正常的**！很多视频没有自动生成的字幕。
|
||
> - 如果 `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"
|
||
```
|
||
|