kb-skills/kb_workflow/SKILL.md

name, description

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

KB Workflow

知识库内容处理管道，支持 B站、知乎等平台的内容抓取、语音识别、深度分析和归档。

什么时候使用

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

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

环境变量

执行前必须检查

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

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

# ~/.kb_env 文件
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 KB_INTERMEDIATE_PATH="~/work/intermediate/analysis"
export KB_ARCHIVE_PATH="~/work/zq/30.资源/AI分析"

可选的环境变量：

变量名	用途
BILIBILI_COOKIE	下载会员视频
KB_GIT_USER / KB_GIT_EMAIL	Git 提交信息
HF_TOKEN	HuggingFace Token（说话者分离）

检查命令

# 从 ~/.kb_env 加载环境变量
if [ -f ~/.kb_env ]; then
    source ~/.kb_env
fi

# 检查必须的环境变量
if [ -z "$AI_API_KEY" ] || [ -z "$AI_PROVIDER" ] || [ -z "$AI_MODEL" ]; then
    echo "❌ 错误：必须的环境变量未设置"
    echo "请配置 ~/.kb_env 文件"
    exit 1
fi

echo "✅ 环境变量检查通过"

Workflow 执行方式

处理链接

# 处理 URL（自动执行完整管道）
python kb_workflow/kb_workflow.py process "https://www.bilibili.com/video/BVxxx"

# 指定输出目录
python kb_workflow/kb_workflow.py process "https://..." -o /path/to/output

# 强制重新执行（忽略已完成状态）
python kb_workflow/kb_workflow.py process "https://..." --no-skip

知乎登录

# 二维码扫码登录（Cookie 自动保存）
python kb_workflow/kb_workflow.py login

# 检查 Cookie 状态
python kb_workflow/kb_workflow.py login --status

# 从 JSON 文件导入 Cookie
python kb_workflow/kb_workflow.py login --import-cookie cookies.json

注意： 知乎链接处理时会自动检测 Cookie 是否过期，过期则自动触发扫码登录。

支持的平台和内容类型

平台	内容类型	URL 示例
B站	视频	bilibili.com/video/BVxxx
B站	专栏	bilibili.com/read/cvxxx
知乎	问答	zhihu.com/question/xxx/answer/xxx
知乎	专栏	zhuanlan.zhihu.com/p/xxx

处理流程

┌─────────────────────────────────────────────────────────────┐
│                    Pipeline 处理流程                         │
├─────────────────────────────────────────────────────────────┤
│  1. Parse     → LinkParser 解析 URL，识别平台和 ID           │
│  2. Download  → 平台适配器获取元数据和内容                    │
│  3. ASR       → 语音识别（视频无字幕时）                      │
│  4. Analyze   → DeepAnalyzer 生成深度分析报告                │
│  5. Archive   → 归档到 KB_ARCHIVE_PATH                      │
└─────────────────────────────────────────────────────────────┘

知乎特殊处理：

• 评论默认爬取并追加到正文末尾
• Cookie 过期时自动弹出二维码，扫码后继续执行
• 无需手动设置 Cookie

目录结构

工作目录（KB_INTERMEDIATE_PATH）：

~/work/intermediate/analysis/
└── {platform}_{content_id}/
    ├── metadata.json      # 元数据
    ├── content.md         # 内容（含评论）
    └── downloads/         # 下载的媒体文件

归档目录（KB_ARCHIVE_PATH）：

~/work/zq/30.资源/AI分析/
└── YYYY-MM-DD/
    └── {platform}_{id}_analysis.md  # 深度分析报告

⚠️ 严格失败处理原则

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

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

示例

用户: 添加到知识库 https://zhuanlan.zhihu.com/p/123456789

Claude:
✅ 环境变量检查通过

◆ 处理中...
  → 解析 URL: zhihu 专栏 123456789
  → 获取元数据...
  → 爬取内容和评论...
  → 深度分析...

✅ 完成！

标题: 深度学习在推荐系统中的应用
内容目录: ~/work/intermediate/analysis/zhihu_123456789/
归档文件: ~/work/zq/30.资源/AI分析/2026-03-17/zhihu_123456789_analysis.md

技术架构

kb_workflow/
├── kb_workflow.py        — CLI 入口
├── auth/
│   └── zhihu_login.py    — 知乎登录和 Cookie 管理
├── crawler/
│   ├── zhihu_crawler.py  — 知乎爬虫（问答/专栏/评论）
│   └── models.py         — 数据模型
├── pipeline/
│   ├── pipeline.py       — Pipeline 编排引擎
│   ├── processors/       — 处理器实现
│   │   ├── parse.py      — URL 解析
│   │   ├── download.py   — 内容下载
│   │   ├── asr.py        — 语音识别
│   │   ├── analyze.py    — 深度分析
│   │   └── archive.py    — 归档
│   ├── platforms/        — 平台适配器
│   │   └── zhihu.py      — 知乎适配器（使用 ZhihuCrawler）
│   └── schemas.py        — 数据模型
└── deep_analyzer/        — AI 分析器