# Bilibili Case Workflow

> 下载 Bilibili 视频，使用 yt-dlp 获取源视频，通过 transcribe_file MCP 服务转录文本，整理视频总结，并更新 cases/ 下按序号命名的案例。适用于 Codex 需要把 Bilibili 视频沉淀为本项目案例时使用。

- Skill: `akimiojr/bilibili-case-workflow` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add akimiojr/bilibili-case-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/akimiojr/bilibili-case-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: akimiojr (https://skillmd.com/u/akimiojr)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/akimiojr/bilibili-case-workflow

---


# Bilibili 案例工作流

## 概述

使用这个技能把一个 Bilibili 视频整理成本仓库中的案例：下载源视频、转录文本、总结内容，并把结果归档到 `cases/`。

## 工作流程

1. 先阅读 `AGENT.md`、`template/README.md` 和 `template/script.md`，对齐项目语气与文件结构。
2. 从视频 URL 中提取 Bilibili 视频 ID，例如 `BV1gp5X6uE22`。
3. 先运行 `scripts/prepare_case.py`，在工作区临时目录 `.tmp/bilibili-case-workflow/<BV id>/` 中创建模板文件。
4. 将视频下载到临时目录，最终文件尽量命名为 `source.mp4`。
5. 对 `source.mp4` 调用 MCP 服务 `transcribe_file` 获取文本。
6. 在 `script.md` 中填写整理后的台词、动作说明和原始 ASR 文本。
7. 在 `README.md` 中填写案例总结、技术真相、领导话术、PPT 模板和金句摘录。
8. 生成案例名后，再运行 `scripts/prepare_case.py --archive-title "<案例名>"`，把临时工作区归档为 `cases/<序号>-<案例名>/`。
9. 检查两个 Markdown 文件中的元数据，确保视频来源、日期和本次处理信息一致。
10. 完成归档和检查后提交 git commit，commit message 遵循下方规范。
11. 完成工作流后可以删除临时目录 `.tmp/bilibili-case-workflow/<BV id>/`。

## 下载命令

使用下面的基础命令，只替换 URL 和输出路径：

```bash
uv tool run yt-dlp --cookies-from-browser edge -o '.tmp/bilibili-case-workflow/<BV id>/source.%(ext)s' 'https://www.bilibili.com/video/<BV id>/'
```

如果 yt-dlp 下载出的文件不是 mp4，先确认文件是否能直接播放；只有在确认容器与内容正确后，才转换或重命名。最终案例中尽量保留 `source.mp4`。

在 Codex 沙箱中运行该命令时，需要申请提权，因为它可能访问网络、浏览器 Cookie 和 uv 缓存。

## 转录文本

使用可用的 MCP `transcribe_file` 服务处理本地 `source.mp4`。将工具返回内容作为原始转录文本，再在 `script.md` 中轻度整理标点、分段、说话人标签和动作说明。

注意：这个 MCP 的语言参数说明有偏差，实际可用值是英文语言名，不是 `zh` / `yue` 这类简码。常见可用值包括 `Chinese`、`English`、`Cantonese`、`Japanese` 等；如果传入 `zh`，服务会报 `Unsupported language: Zh` 一类错误。

如果当前环境没有可用的 `transcribe_file` MCP 服务，下载完成后停止，并明确告诉用户：转录步骤被缺失的 MCP 服务阻塞。

## 案例写作

以 `template/README.md` 和 `template/script.md` 为必需结构。

需要先创建案例目录时，运行 `scripts/prepare_case.py`。它会先在 `.tmp/bilibili-case-workflow/<BV id>/` 建立临时工作区，并只补齐缺失的模板文件，不覆盖已有 `README.md` 或 `script.md`。

归档时，运行 `scripts/prepare_case.py --archive-title "<案例名>"`，把临时工作区复制到 `cases/<序号>-<案例名>/`。序号按 `cases/` 中现有目录自动递增。

填写 `README.md` 时：

- 保留模板中的 YAML frontmatter 字段。
- 设置 `platform: BiliBili`、`video_id`、`url`、`summarize_model` 和 `summarize_date`（填写 summarize_model 前先需要询问自己是什么模型，不要随意填写或者保持默认值不变）。
- 根据视频的核心笑点，或“技术真相 -> 包装话术”的转换，提炼案例名称。
- 保持本仓库简洁、讽刺、程序员自嘲式的语气。
- 清楚区分真实技术实现和面向 PPT 的夸张包装。

填写 `script.md` 时：

- 保留模板中的 YAML frontmatter 字段。
- 如果 MCP 返回了模型信息，将 `asr_model` 设置为对应模型；否则使用工具输出中可见的服务名或模型名。
- 临时处理阶段，可将 `local_filepath` 写成 `.tmp/bilibili-case-workflow/BV1gp5X6uE22/source.mp4`。
- 归档后，把 `local_filepath` 更新为最终目录路径，例如 `cases/001-太极加密/source.mp4`。
- 在 `## 视频脚本` 下写入可读性更好的整理版本。
- 视频中可能插入甲方广告或赞助推广段落，整理 `## 视频脚本` 时应识别并移除这些广告内容，用 `<!-- 广告：简要说明 -->` 标注跳过位置（例如 `<!-- 广告：蓝盒子床垫推广 -->`）。判断标准：与主线剧情无关、明显在介绍商品或品牌功能、带有购买引导话术的段落属于广告。
- `## 原文` 保持 ASR 原文不做任何修改，广告内容如实保留。
- 在 `## 原文` 下写入未经改写的 ASR 原文。


## 数字规范

整理时不要照搬 ASR 原文的数字写法，优先使用阿拉伯数字和常见缩写，符合中文阅读习惯：

1. 技术参数统一用缩写：4K、800MB、1.8TB、99.7%、91.2%
2. 大数用"阿拉伯数字 + 万/亿"：86万条、1.8TB，不写"八十六万条""一点八T"
3. 百分比用阿拉伯数字 + %：99.7%，不写"百分之九十九点七"
4. 可以不与 ASR 识别结果完全一致，以可读性为优先
5. 视频脚本对话部分可保留少量口语化中文数字表达（如"两千来个""五千年"），但技术参数仍用阿拉伯数字

## 更新规则

- 不要盲目覆盖用户已经整理过的内容；先阅读现有文件，保留有价值的人工修订。
- 不要改动无关案例。
- 日期统一使用 `YYYY-MM-DD` 格式。

## 项目维护

**以下改动应包含在同一次 commit 中。**

### 新人物

如果在视频中出现 `AGENTS.md` 背景角色列表里没有的人物，在归档案例的同时更新 `AGENTS.md` 中的角色列表，补充姓名和角色描述。

### README 更新

每次归档新案例后，同步更新 `README.md` 中以下两个章节：

1. **案例库**：在表格末尾追加新案例行，格式与现有行一致（序号、案例链接、一句话概括）。
2. **你遇到的问题 → 参考案例**：如果新案例属于表中已有的问题场景，在对应行追加案例编号；如果新案例属于新的问题场景，新增一行。

### 案例索引更新

每次归档新案例后，同步更新 `references/case-index.md`：

1. **场景速查表**：如果新案例属于表中已有的场景分类，在对应行追加案例编号；如果属于新的场景分类，新增一行。
2. **案例详情**：在文件末尾新增一条案例条目，格式如下：

```markdown
### <序号> <案例名>
- **概括**: <一句话概括，格式："技术真相" → "包装话术">
- **关键词**: <逗号分隔的关键词列表，覆盖技术场景和管理场景>
- **路径**: `cases/<序号>-<案例名>/`
```

关键词应覆盖：技术问题类型（如 bug、数据库、编码）、管理场景（如 汇报、绩效、领导）、包装手法（如 专项治理、数字化、资产化）。参考已有案例条目的关键词风格。

## Commit Message 规范

归档完成后提交一次 commit，范围只包含本次新增或更新的案例文件，不要把无关工作区改动混进来。

commit message 使用中文，推荐格式：

```text
归档案例：<序号>-<案例名>
```

例如：

```text
归档案例：001-稳定性专项治理
```

如果本次只是修正文稿或补充素材，而不是新增案例，使用：

```text
更新案例：<序号>-<案例名>
```

提交前需要检查：

- `cases/<序号>-<案例名>/README.md` 元数据完整。
- `cases/<序号>-<案例名>/script.md` 包含整理脚本和 ASR 原文。
- `source.mp4` 已归档到对应案例目录。
- `AGENTS.md` 中的背景角色列表已补充视频中出现的新人物。
- `README.md` 中的案例库表格和场景映射表已追加新案例。
- `references/case-index.md` 中的场景速查表和案例详情已同步更新。
- `git status` 中没有误加入 `.tmp/`、下载中间文件或无关改动。