Metadata-Version: 2.4
Name: videomind
Version: 0.1.0
Summary: Command-line client and Agent Skill for the VideoMind video-understanding API (Bilibili & uploads).
Author: CjQkJ
License: MIT
Project-URL: Homepage, https://github.com/CjQkJ/videomind
Project-URL: Issues, https://github.com/CjQkJ/videomind/issues
Keywords: video,ai,video-understanding,agent-skill,claude-code,codex,bilibili
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Requires-Dist: typer>=0.12
Dynamic: license-file

# 🎬 VideoMind

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

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

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

---

## ✨ 特性

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

---

## 📦 安装

### 方式一：命令行工具

```bash
pip install videomind
```

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

用 [skills CLI](https://github.com/vercel-labs/skills) 一键装进你的 AI agent（会自动带上本仓库的 skill 描述）：

```bash
# 装进 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 后，任选一种方式配置：

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

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

验证配置：

```bash
videomind whoami     # 显示当前账号与 tier
```

---

## 🚀 快速开始

```bash
# 一条龙：提交 → 等待 → 保存到 ./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 开放标准](https://agentskills.io) 的工具。

---

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

默认连接作者部署的公开服务 `http://8.163.133.244:17892`。若你自行部署了 [Video Workbench](https://github.com/CjQkJ/videomind) 后端，改一下地址即可：

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

---

## 🛠️ 开发

```bash
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
