自动同步: 2026-03-15 02:10

skills/kb-workflow/SKILL.md

@@ -5,698 +5,200 @@ description: 当收到"添加到知识库 + 链接" 或"保存到知识库 + 链
 
 # KB Workflow
 
-## 触发条件
+## 什么时候使用
+
+当用户发送包含以下模式的消息时，此技能自动触发：
 
 | 触发词 | 行为 | 示例 |
 |--------|------|------|
 | `添加到知识库` + 链接 | 添加到知识库并处理 | "添加到知识库 https://www.bilibili.com/video/BVxxx" |
 | `保存到知识库` + 链接 | 同上 | "保存到知识库 https://www.bilibili.com/video/BVxxx" |
 
----
+## 环境变量
 
-## 状态机定义
+### 执行前必须检查
 
-工作流是一个严格的状态机，每个状态有明确的前置条件和后置条件：
+在执行 workflow 之前，必须检查环境变量是否已经设置。
 
-| 状态 | 前置条件 | 执行动作 | 成功后进入 | 失败处理 |
-|------|---------|---------|-----------|---------|
-| `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 提交邮箱 | 归档时使用 |
-
-### 配置方法
+**必须的环境变量**（缺失则报错退出）：
 
+配置方式：将变量写入 `~/.kb_env` 文件：
 ```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
 ```
 
----
+**可选的环境变量**：
+| 变量名 | 用途 | 示例 |
+|--------|------|------|
+| `BILIBILI_COOKIE` | 下载会员视频 | `SESSDATA=xxx; bili_jct=xxx` |
+| `KB_GIT_USER` | Git提交用户名 | `Your Name` |
+| `KB_GIT_EMAIL` | Git提交邮箱 | `your@email.com` |
+| `KB_ARCHIVE_PATH` | 归档目录路径 | `~/work/zq/30.资源/AI分析` |
+| `KB_GIT_ROOT` | Git仓库根目录 | `~/work/zq` |
+| `HF_TOKEN` | HuggingFace Token（说话者分离） | `hf_xxx` |
 
-## 步骤详解
+### 检查命令
 
-### Step 0: 环境变量检查
-
-**前置条件：** 无
-
-**执行命令：**
 ```bash
-# 加载环境变量
-if [ -f ~/.kb_env ]; then source ~/.kb_env; fi
+# 从 ~/.kb_env 加载环境变量
+if [ -f ~/.kb_env ]; then
+    source ~/.kb_env
+fi
+
+# 检查必须的环境变量
+if [ -z "$AI_API_KEY" ] || [ -z "$AI_PROVIDER" ] || [ -z "$AI_MODEL" ] || [ -z "$AI_BASE_URL" ]; then
+    echo "❌ 错误：必须的环境变量未设置"
+    echo "请配置 ~/.kb_env 文件"
+    exit 1
+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 "✅ 环境变量检查通过"
 ```
 
-**成功标准：**
-- 所有必需变量已设置
-- 输出 "✅ 环境变量检查通过"
+## Workflow 执行方式
 
-**失败处理：**
-- 缺少任何必需变量 → 报错退出，提示用户配置
+### 方式一：一键处理（推荐）
 
-**输出示例：**
-```
-✅ 环境变量检查通过
-   AI_PROVIDER: zhipu
-   AI_MODEL: glm-5
-```
+使用管道 CLI 一键完成所有步骤：
 
-**错误示例：**
-```
-❌ 错误：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]"
+python3 kb-workflow/kb_workflow.py process "https://www.bilibili.com/video/BVxxx"
 ```
 
-**成功标准：**
-- 返回 JSON 包含 `success: true`
-- 包含字段：`platform`, `content_type`, `content_id`
-- 生成文件：`pending/{platform}_{id}.link.json`
+**该命令自动执行：**
+1. URL 解析 → 识别平台和内容 ID
+2. 元数据提取 → 获取标题、作者等信息
+3. 内容下载 → 字幕/视频/文章内容
+4. 语音识别 → Whisper/FunASR（如需要）
+5. 深度分析 → AI 生成分析报告
+6. 归档 → 移动到归档目录
 
-**失败处理：**
-- 不支持的平台 → 报错退出，告知用户支持的平台
-- 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
+# 指定输出目录
+python3 kb-workflow/kb_workflow.py process "https://..." -o /path/to/output
 
-# 根据平台选择命令
-# 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"
+# 强制重新执行（忽略已完成状态）
+python3 kb-workflow/kb_workflow.py process "https://..." --no-skip
 ```
 
-**成功标准：**
-- 返回 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
+# 1. 查重
+python3 kb-workflow/kb_workflow.py --check --url "https://..."
 
-# B站视频 - 优先尝试字幕
-python3 ~/.openclaw/skills/kb-bilibili-content/bilibili_content.py \
-    --id "[BV号]" --type subtitle-download \
-    --output "content/downloads/"
+# 2. 一键处理
+python3 kb-workflow/kb_workflow.py process "https://..."
 
-# 检查是否有官方字幕
-# 如果 has_subtitle=true → 进入 Step 5
-# 如果 has_subtitle=false → 下载视频，进入 Step 4
+# 3. 归档
+python3 kb-workflow/kb_workflow.py --archive-file "/path/to/report.md"
 ```
 
-**成功标准：**
-- 返回 JSON 包含 `success: true`
-- `has_subtitle=true`: 有字幕文件
-- `has_subtitle=false`: 视频文件下载成功
+## 支持的平台和内容类型
 
-**失败处理：**
-- 403 禁止访问 → 检查 BILIBILI_COOKIE 配置
-- 网络超时 → 重试1次
-- 会员视频 → 提示需要配置 Cookie
+| 平台 | 内容类型 | URL 示例 |
+|------|----------|----------|
+| B站 | 视频 | `bilibili.com/video/BVxxx` |
+| B站 | 专栏 | `bilibili.com/read/cvxxx` |
+| 知乎 | 问答 | `zhihu.com/question/xxx` |
+| 知乎 | 专栏 | `zhuanlan.zhihu.com/p/xxx` |
+| 知乎 | 视频 | `zhihu.com/zvideo/xxx` |
+
+## 处理流程
 
-**输出示例（有字幕）：**
-```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": "无官方字幕，需要下载视频进行语音识别"
-}
+┌─────────────────────────────────────────────────────────────┐
+│                    kb-workflow process                       │
+├─────────────────────────────────────────────────────────────┤
+│  1. Parse     → LinkParser 解析 URL                         │
+│  2. Download  → 平台适配器获取元数据和内容                    │
+│  3. ASR       → 语音识别（视频无字幕时）                      │
+│  4. Analyze   → DeepAnalyzer 生成分析报告                    │
+│  5. Archive   → 归档到 KB_ARCHIVE_PATH                      │
+└─────────────────────────────────────────────────────────────┘
 ```
 
-**错误示例：**
-```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/）：**
+```
+~/work/knowledge-base/
+├── pending/           # 待处理链接
+├── metadata/          # 元数据 JSON
+├── content/           # 内容文件
+│   └── downloads/     # 下载的视频/字幕
+└── analyzed/          # 分析报告
 ```
-~/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分析/        # 归档目录
+**归档目录（默认 ~/work/zq/30.资源/AI分析/）：**
+```
+~/work/zq/30.资源/AI分析/
 └── YYYY-MM-DD/
-    └── {platform}_{id}.md
+    └── {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 调用
+> **深度分析步骤必须成功，否则整个流程失败**
+
+1. **深度分析不可跳过**：AI 分析是必须成功执行的步骤
+2. **失败即终止**：如果分析返回失败，必须立即停止并汇报
+3. **禁止降级处理**：不能使用预设模板或简单摘要来"假装成功"
+4. **每次执行都要使用 AI**：必须有真实的 AI API 调用记录
+
+## 辅助命令
+
+```bash
+# 查重
+python3 kb-workflow/kb_workflow.py --check --url "https://..."
+
+# 获取目录路径
+python3 kb-workflow/kb_workflow.py --base-path
+python3 kb-workflow/kb_workflow.py --metadata
+python3 kb-workflow/kb_workflow.py --content
+python3 kb-workflow/kb_workflow.py --analyzed
+
+# 归档分析报告
+python3 kb-workflow/kb_workflow.py --archive-file "/path/to/report.md"
+```
+
+## 示例
+
+```
+用户: 添加到知识库 https://www.bilibili.com/video/BV1xx
+
+Claude:
+✅ 环境变量检查通过
+
+◆ 处理中...
+  → 解析 URL: bilibili 视频 BV1xx
+  → 获取元数据...
+  → 下载字幕...
+  → 深度分析...
+
+✅ 完成！
+
+标题: 【教程】如何使用 Python 进行数据分析
+处理阶段: 全部完成
+最终文件: ~/work/zq/30.资源/AI分析/2026-03-15/bilibili_BV1xx.md
+```
+
+## 技术架构
+
+```
+kb-workflow/kb_workflow.py (CLI)
+    └── kb_pipeline/ (核心管道包)
+        ├── pipeline.py      — Pipeline 编排引擎
+        ├── processors/      — 处理器实现
+        │   ├── parse.py     — URL 解析
+        │   ├── download.py  — 内容下载
+        │   ├── asr.py       — 语音识别
+        │   └── analyze.py   — 深度分析
+        └── schemas.py       — 数据模型
+```