🎬 VideoMind

把任意 B 站视频变成结构化知识：学习笔记 · 文章 · 复习卡片 · 教学网页。 一个工具，两种用法：命令行 CLI + 跨 Agent 的 Skill（Claude Code / Codex 通用）。

pip install videomind
videomind "https://www.bilibili.com/video/BVxxxxxxxx"

VideoMind 会真正看懂视频（基于画面 + 声音，不是浅层字幕总结），萃取操作步骤、方法论、关键观点，产出可交付的 Markdown 笔记与结构化 JSON。长视频（最长 4 小时）自动分段处理。

---

✨ 特性

• 🎯 深度理解：画面细节 + 语音内容，不是字幕压缩
• 📝 四种产物：学习笔记 / 文章 / 复习卡片 / 教学网页
• ✂️ 长视频分段：自动切段、重叠合并，最长 4 小时
• ⚡ 一条命令：videomind <链接> 提交→等待→保存一步到位
• 🤖 Agent Skill：符合 Agent Skills 开放标准，Claude Code / Codex 等通用

---

📦 安装

方式一：命令行工具

pip install videomind

方式二：作为 Agent Skill（Claude Code / Codex 等）

用 skills CLI 一键装进你的 AI agent（会自动带上本仓库的 skill 描述）：

# 装进 Claude Code（全局）
npx skills add CjQkJ/videomind --agent claude-code -g -y

# 装进 Codex 等（按 skills CLI 支持的 --agent 目标）
npx skills add CjQkJ/videomind --agent codex -g -y

Skill 内部调用 videomind CLI，因此仍需 pip install videomind（现代 agent 会在首次使用时自动安装）。

---

🔑 配置

拿到一个 vw_ 开头的 API Key 后，任选一种方式配置：

# 方式 A：保存到本地（推荐，仅配置一次）
videomind config set-key vw_你的API密钥

# 方式 B：环境变量（适合 CI / 容器）
export VIDEOMIND_API_KEY=vw_你的API密钥

验证配置：

videomind whoami     # 显示当前账号与 tier

---

🚀 快速开始

# 一条龙：提交 → 等待 → 保存到 ./job_<id>/result.md + result.json
videomind "https://www.bilibili.com/video/BVxxxxxxxx"

# 指定输出模式与保存位置
videomind "https://www.bilibili.com/video/BVxxxxxxxx" --mode cards -o ./notes/

处理时长：约每 10 分钟视频需要 2–3 分钟。长视频自动分段。

---

📋 命令参考

命令	说明
videomind <url>	一条龙：提交→等待→保存（等价于 run）
videomind run <url>	同上的显式写法
videomind submit <url>	仅提交，立即返回 job_id
videomind status <job_id>	查询任务进度
videomind wait <job_id>	轮询直到成功/失败
videomind result <job_id>	下载结果（-f md|json|html，-o 指定路径）
videomind jobs	列出历史任务（-n 限制条数）
videomind health	服务状态与配额
videomind whoami	验证 Key、显示账号
videomind config set-key <key>	保存 API Key
videomind config show	查看配置（Key 脱敏）

---

🎨 输出模式（--mode）

值	适用	产物
study_note	系统学习、做笔记（默认）	结构化学习笔记
article	对外发布、博客	可读长文
cards	复习、速记	知识卡片
teaching_html	教学、演示	HTML 网页

---

🤖 作为 Agent Skill 使用

装好 skill 后（见上方「方式二」），在你的 AI agent 里直接说：

「帮我总结这个视频：https://www.bilibili.com/video/BVxxxxxxxx」

agent 会自动调用 videomind CLI 提交视频、等待完成、读取笔记并给你摘要。

skill 自身是 agent-中立的：只用标准 frontmatter（name + description），不依赖任何单一 agent 的专有字段，因此兼容 Claude Code、Codex 及任何遵循 Agent Skills 开放标准 的工具。

---

⚙️ 自部署 / 连自己的服务

默认连接作者部署的公开服务 http://8.163.133.244:17892。若你自行部署了 Video Workbench 后端，改一下地址即可：

videomind config set-key vw_你的key --base-url http://你的服务器:17892
# 或环境变量 VIDEOMIND_BASE_URL

---

🛠️ 开发

git clone https://github.com/CjQkJ/videomind.git
cd videomind
pip install -e .          # 可编辑安装
pip install pytest        # 测试
pytest                    # 跑测试

项目结构：

videomind/
├── pyproject.toml
├── README.md
├── src/videomind/        # CLI 包
│   ├── cli.py            # 命令行入口（Typer）
│   ├── client.py         # HTTP 客户端
│   └── config.py         # 配置（文件 + 环境变量）
└── skills/videomind/     # Agent Skill（开放标准）
    ├── SKILL.md          # skill 入口（name + description）
    ├── scripts/          # 可调用脚本
    └── references/       # API 参考

---

❓ 常见问题

现象	处理
未配置 API Key	运行 videomind config set-key <key> 或设环境变量
任务一直 queued	并发已满，排队等待即可
任务 failed	多为源视频下载失败（B 站风控）或时长超限，换链接重试
想换输出形式	重新 videomind <url> --mode cards

---

📄 License

MIT © CjQkJ