starmen1265
6a819b6c80
PR Test / lint (pull_request) Successful in 2s
- Fix CLI path: kb-workflow -> kb_workflow - Add login command documentation for Zhihu - Update directory structure to match actual paths - Add environment variable checks section - Document strict failure handling principle - Update technical architecture diagram
191 lines
6.2 KiB
Markdown
191 lines
6.2 KiB
Markdown
---
|
||
name: kb-workflow
|
||
description: 当收到"添加到知识库 + 链接" 或"保存到知识库 + 链接"时使用
|
||
---
|
||
|
||
# KB Workflow
|
||
|
||
知识库内容处理管道，支持 B站、知乎等平台的内容抓取、语音识别、深度分析和归档。
|
||
|
||
## 什么时候使用
|
||
|
||
当用户发送包含以下模式的消息时，此技能自动触发：
|
||
|
||
| 触发词 | 行为 | 示例 |
|
||
|--------|------|------|
|
||
| `添加到知识库` + 链接 | 添加到知识库并处理 | "添加到知识库 https://www.bilibili.com/video/BVxxx" |
|
||
| `保存到知识库` + 链接 | 同上 | "保存到知识库 https://zhuanlan.zhihu.com/p/xxx" |
|
||
|
||
## 环境变量
|
||
|
||
### 执行前必须检查
|
||
|
||
在执行 workflow 之前，必须检查环境变量是否已经设置。
|
||
|
||
**必须的环境变量**（缺失则报错退出）：
|
||
|
||
```bash
|
||
# ~/.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（说话者分离） |
|
||
|
||
### 检查命令
|
||
|
||
```bash
|
||
# 从 ~/.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 执行方式
|
||
|
||
### 处理链接
|
||
|
||
```bash
|
||
# 处理 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
|
||
```
|
||
|
||
### 知乎登录
|
||
|
||
```bash
|
||
# 二维码扫码登录（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 分析器
|
||
```
|