Metadata-Version: 2.4
Name: bilibili-game-review-analyzer
Version: 0.1.5
Summary: B站游戏评论分析工具
Author: WZJ
Author-email: WZJ <1298683025@qq.com>
License-Expression: MIT
License-File: LICENSE
Requires-Dist: bilibili-api-python>=17.4.2
Requires-Dist: httpx>=0.28.1
Requires-Dist: langchain-qwq>=0.3.5
Requires-Dist: mcp[cli]>=2.0.0
Requires-Dist: python-dotenv>=1.2.2
Requires-Python: >=3.14
Description-Content-Type: text/markdown

# Bilibili Game Review Analyzer

基于 MCP Python SDK 的 B 站视频分析服务，支持视频搜索、播放地址获取及 AI 内容概括，并附带一个与 MCP 共用同一份实现的 Agent Skill。

## 功能特性

本项目提供三个 MCP 工具，以及一个调用相同代码的 Skill 命令行工具：

1. **get_video_results** — 根据关键词搜索相关视频，返回视频标题和 BV 号
2. **extract_videos_url** — 根据关键词获取视频的播放地址（含 cid）
3. **get_video_summary_tool** — 根据关键词搜索视频，并使用大语言模型概括视频内容

## 技术栈

- Python 3.14+
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)（`mcp.server.mcpserver.MCPServer`）
- [bilibili-api-python](https://github.com/Nemo2011/bilibili-api) — B 站 API 客户端
- LangChain + Qwen（`langchain-qwq`）— 视频内容智能概括
- uv — 依赖管理与打包

## 环境要求

- Python >= 3.14
- uv（推荐，用于 `uvx` 直接运行或源码开发）

## 安装

### 从 PyPI 安装

```bash
pip install bilibili-game-review-analyzer
```

或直接用 `uvx` 运行，无需手动安装：

```bash
uvx bilibili-game-review-analyzer
```

### 从源码安装

```bash
git clone https://gitee.com/zuiewangguandewang/bilibili-game-review-analyzer.git
cd bilibili-game-review-analyzer
uv sync
```

## 环境变量配置

在项目根目录创建 `.env` 文件（可从 `.env.example` 复制）：

```env
API_KEY=your_api_key_here
BASE_URL=your_api_base_url_here
MODEL=your_model_name_here
```

| 变量名 | 说明 |
|--------|------|
| API_KEY | Qwen 模型的 API 密钥 |
| BASE_URL | Qwen 模型的 API 基础地址（OpenAI 兼容接口） |
| MODEL | 模型名称（需支持视频输入，如 qwen-vl-plus） |

`.env` 已在 `.gitignore` 中，不会被提交。通过 MCP 客户端集成时，也可以直接在客户端配置的 `env` 字段中传入这三个变量。

## 使用方式

### 方式一：通过 MCP 客户端集成

服务器使用 stdio 传输协议，可与支持 MCP 标准的客户端（Claude Desktop、Cursor、Cherry Studio 等）集成。

**从 PyPI 运行（推荐）**：

```json
{
  "mcpServers": {
    "bilibili_game_review_analyzer": {
      "command": "uvx",
      "args": ["bilibili-game-review-analyzer"],
      "env": {
        "API_KEY": "your_api_key",
        "BASE_URL": "your_base_url",
        "MODEL": "your_model"
      }
    }
  }
}
```

**从本地源码运行（开发调试）**：

```json
{
  "mcpServers": {
    "bilibili_game_review_analyzer": {
      "command": "uvx",
      "args": [
        "--from",
        "D:/path/to/bilibili-game-review-analyzer",
        "bilibili-game-review-analyzer"
      ],
      "env": {
        "API_KEY": "your_api_key",
        "BASE_URL": "your_base_url",
        "MODEL": "your_model"
      }
    }
  }
}
```

### 方式二：命令行直接启动

```bash
uv run bilibili-game-review-analyzer
```

或：

```bash
uv run python -m bilibili_game_review_analyzer
```

启动后进入 stdio 模式，等待 MCP 客户端连接。

### 方式三：Skill 命令行

Skill 位于 `skills/bilibili-game-review-analyzer/`，与 MCP 服务器共用 PyPI 包中的同一份实现，不包含重复代码。

先安装依赖：

```bash
pip install -r skills/bilibili-game-review-analyzer/scripts/requirements.txt
```

再在 skill 根目录准备 `.env`（可从 `skills/bilibili-game-review-analyzer/.env.example` 复制），然后执行：

```bash
python skills/bilibili-game-review-analyzer/scripts/main.py search "黑神话悟空" --limit 3
python skills/bilibili-game-review-analyzer/scripts/main.py url "原神" --limit 2
python skills/bilibili-game-review-analyzer/scripts/main.py summary "崩坏星穹铁道" --limit 1
```

Skill 的详细说明见 [SKILL.md](skills/bilibili-game-review-analyzer/SKILL.md)。

## 工具说明

### get_video_results

根据关键词搜索相关视频，返回视频标题和 BV 号。

**参数**：
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| keyword | str | ✅ | — | 搜索关键词 |
| limit | int | ❌ | 1 | 返回结果数量限制 |

**返回**：视频列表 `List[Dict]`，每个元素包含 `title`（标题）和 `bvid`（BV 号）

---

### extract_videos_url

根据关键词获取视频的播放地址。

**参数**：
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| keyword | str | ✅ | — | 视频关键词 |
| limit | int | ❌ | 1 | 最大返回视频数量 |

**返回**：视频信息列表 `List[Dict]`，每个元素包含 `title`、`bvid`、`cid`、`video_url`（播放地址）

---

### get_video_summary_tool

根据关键词搜索视频，并使用大语言模型概括视频内容。

**参数**：
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| keyword | str | ✅ | — | 视频关键词 |
| limit | int | ❌ | 1 | 最大返回视频内容数量 |

**返回**：概括内容列表 `List[str]`

## 项目结构

```
bilibili-game-review-analyzer/
├── pyproject.toml                 # 项目配置与依赖管理
├── uv.lock                        # 依赖锁定文件（自动生成）
├── README.md                      # 项目文档
├── LICENSE                        # MIT 许可证
├── .env.example                   # 环境变量模板
├── src/
│   └── bilibili_game_review_analyzer/
│       ├── __init__.py            # 包初始化，导出公共 API
│       ├── __main__.py            # 支持 python -m 直接运行
│       ├── server.py              # MCP 服务器与工具注册
│       └── bilibili_client.py     # B站检索、播放地址与 AI 总结（唯一实现）
├── skills/
│   └── bilibili-game-review-analyzer/
│       ├── SKILL.md               # Skill 说明
│       ├── .env.example           # Skill 环境变量模板
│       └── scripts/
│           ├── main.py            # Skill 命令行入口（调用上面的包）
│           └── requirements.txt   # Skill 依赖
└── dist/                          # 构建产物（已 gitignore）
```

## 配置说明

核心配置集中在 `pyproject.toml`：

```toml
[project]
name = "bilibili-game-review-analyzer"
version = "0.1.5"
requires-python = ">=3.14"
dependencies = [
    "bilibili-api-python>=17.4.2",
    "httpx>=0.28.1",
    "langchain-qwq>=0.3.5",
    "mcp[cli]>=2.0.0",
    "python-dotenv>=1.2.2",
]

[project.scripts]
bilibili-game-review-analyzer = "bilibili_game_review_analyzer.server:main"
```

## 开发与发布

```bash
uv sync                              # 安装依赖（可编辑模式）
uv run bilibili-game-review-analyzer # 启动服务器
uv build                             # 构建 sdist 与 wheel
uv run python -m twine check dist/*  # 校验构建产物
```

发布到 PyPI：

```bash
uv run python -m twine upload dist/bilibili_game_review_analyzer-<version>*
```

> Windows 下请使用 `python -m twine`，直接执行 `uv run twine` 可能因脚本包装器路径问题失败。

## 注意事项

- 请确保环境变量正确配置，否则 AI 总结会失败。
- B 站 API 存在访问频率限制，高频请求可能触发风控。
- 视频播放地址存在有效期，获取后请及时使用；部分 CDN 会校验 Referer，大模型直接拉流可能失败。
- 视频总结依赖模型的多模态视频输入能力，过长或体积过大的视频可能超时或被拒绝。

## 免责声明

- **本项目仅供个人学习研究使用，请勿用于商业用途。**
- 本项目非 B 站官方产品，与哔哩哔哩公司无任何关联。
- 本项目使用的第三方库 [bilibili-api-python](https://github.com/Nemo2011/bilibili-api) 为开源项目，非 B 站官方提供的 API。
- 通过本项目获取的视频内容版权归原作者所有，未经授权不得转载或商用。
- 使用本项目时请严格遵守 B 站用户协议及相关法律法规，使用者需自行承担因使用本项目而产生的一切风险和责任。
- 本项目不对第三方库的合法性、稳定性及安全性做任何担保。

## 许可证

本项目使用 MIT 许可证，详见 [LICENSE](LICENSE) 文件。
