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

name, description

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

KB Workflow

什么时候使用

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

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

环境变量

执行前必须检查

在执行 workflow 之前，必须检查环境变量是否已经设置。

必须的环境变量（缺失则报错退出）：

变量名	用途	示例
AI_API_KEY	AI深度分析 API Key	sk-xxx
AI_PROVIDER	AI提供商	zhipu, openai, minimax
AI_MODEL	AI模型	glm-4.7, gpt-4
AI_BASE_URL	API 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

检查命令

# 检查必须的环境变量
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: 环境变量检查

❌ 禁止跳过此步骤！必须先检查环境变量。

# 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 "✅ 环境变量检查通过"

如果检查不通过，必须：

1. 报错提示用户
2. 退出，不执行后续步骤
3. 等待用户配置好环境变量后重新执行

⚠️ 严格失败处理原则

深度分析步骤必须成功，否则整个流程失败

在执行工作流时，必须遵守以下原则：

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

步骤 2: 链接解析

1. 获取目录路径：

python3 kb_workflow.py --pending

2. 启动子代理调用 kb-link-parser：

python3 /path/to/link-parser.py --url "[URL]"

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

步骤 3: 元数据提取

1. 获取元数据目录路径：

python3 kb_workflow.py --metadata
# 返回: {"path": "/home/admin/work/knowledge-base/metadata"}

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

3. 启动子代理调用对应平台的 metadata 技能（传入 --output）：

# 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. 获取目录路径：

python3 kb_workflow.py --content_downloads
python3 kb_workflow.py --content

2. 启动子代理调用对应平台的 content 技能：

# 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. 获取目录路径：

python3 kb_workflow.py --content

2. 启动子代理调用 kb-whisper（传入视频路径）：

# 必须传入 --output 完整路径
python3 /path/to/whisper.py --input [video_path] --model base --output [content_dir]

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

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

步骤 6: 深度分析

1. 获取目录路径：

python3 kb_workflow.py --analyzed

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

3. 如果有官方字幕，使用官方字幕的 SRT 文件

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

5. 启动子代理调用 kb-deep-analyzer：

python3 /path/to/deep_analyzer.py --metadata [meta_path] --content [content_path] --output [analyzed_dir]/[filename].md

6. 解析输出 JSON，检查 success 字段：

⚠️ 深度分析失败 = 整个流程失败

• 如果 success = true：继续步骤 7（归档）
• 如果 success = false：立即终止流程，向用户汇报失败原因
• 严禁继续执行后续步骤或使用降级内容"假装成功"

步骤 7: 归档

运行归档命令：

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: 深度分析
   ↓
┌─────────────────────────────────────┐
│ 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

辅助命令

# ------------------- 查重与归档 -------------------

# 查重
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"