reelminner

💡 名称说明： 本项目的最终公开名称是 Reelminner。Python 引擎类名为 Reelminner（见 scraper.py），CLI/GUI 和 MCP 服务器 均以 reelminner 为品牌命名，GitHub 仓库名为 reelminner。早期 的工作代号 ReelSnipe 已完全弃用。其他备选名称见 名称选项。

📚 目录

• 什么是 Reelminner

• ✨ 功能特性

• 🧠 工作原理

• 🏗️ 项目架构

• 📦 安装

• 🚀 快速开始

• 💻 使用方法

  • 桌面 GUI

  • 命令行（CLI）

  • MCP 服务器（供 AI 智能体使用）

  • Python API

• 📊 输出格式

• ⚙️ 配置

• 🗂️ 项目结构

• 🧪 测试与 QA

• 📦 构建独立 EXE

• ⚠️ 法律与道德声明

• 🤝 贡献指南

• 📄 许可证

• 🆘 故障排查与常见问题

• 🏷️ 名称

Related MCP server: Instagram Complete MCP Server

什么是 Reelminner

Reelminner 是一个开源工具包，用于从 Instagram Reel 及其发布者的个人主页中提取结构化数据。它围绕一个可复用的核心引擎（Reelminner）构建，并通过四种不同的方式对外提供：

所有接口共享相同的解析、会话和限速逻辑，因此无论使用哪个前端，结果都完全一致。

✨ 功能特性

• 多源 Reel 解析 — Reelminner 从多个数据层读取数据（嵌入式 JSON、GraphQL 响应以及实时 DOM 回退），即使 Instagram 更改了其中某一层，它也能继续正常工作。

• 发布者个人主页信息增强 — 对于每条 Reel，它可以自动获取发布者的 username、full_name、bio、followers、is_verified 和 reels_count。

• 粉丝数提取 — 通过 Instagram 的 GraphQL UserByRestrictedView / GraphQLOwnerInfo 查询获取，并带有 DOM 回退和分页机制（通过滚动个人主页来处理被截断的粉丝数，如“1.2M”）。

• 音乐元数据 — Reel 音频的 music_title、music_artist 和 music_id。

• 互动数据 — views、likes、comments，以及直接的 video_url / thumbnail。

• 会话与登录管理 — 交互式二维码/登录、从 EditThisCookie 导出文件导入 Cookie，以及 24 小时会话刷新，无需频繁重新登录。

• 并发抓取 — 线程池（--workers，默认 3），请求间有礼貌的延迟（--delay，默认 2 秒），并在 Instagram 返回 BLOCKED / RATE_LIMITED 时进行自适应退避。

• 可靠的状态跟踪 — 每一行都带有 status 代码（OK、PARSED_PARTIAL、FAILED、NO_DATA、BLOCKED、RATE_LIMITED），让您清楚知道哪些操作成功了。

• 多种导出格式 — CSV（默认）、JSON 和 Excel（.xlsx，通过 openpyxl）。

• MCP 服务器 — 提供五个稳定的工具，使 AI 智能体（Claude、Cursor 等）能够执行抓取、查看状态、导入 Cookie、停止和导出操作。

• 桌面 GUI — 内置深色主题、粘贴 URL 输入框、实时结果表格、右键复制 URL / 打开 Reel，以及一键导出。

• 经过测试 — pytest 测试套件 + 端到端 QA 测试框架，强制执行数据质量门槛。

🧠 工作原理

┌────────────┐   ┌────────────┐   ┌────────────┐   ┌────────────┐
│   GUI      │   │    CLI     │   │  MCP srv   │   │  Python    │
│  gui.py    │   │ scraper.py │   │mcp_server  │   │   import   │
└─────┬──────┘   └─────┬──────┘   └─────┬──────┘   └─────┬──────┘
      └────────────────┴────────────────┴────────────────┘
                       ▼
              ┌───────────────────────┐
              │  Reelminner  │  ← the engine (scraper.py)
              │  • session / cookies   │
              │  • thread pool         │
              │  • adaptive back‑off   │
              └───────────┬───────────┘
                          ▼
              ┌───────────────────────┐
              │  parsers.py            │  ← pure extraction helpers
              │  parse_reel_page / json│
              │  parse_owner / music   │
              │  regex adapters         │
              └───────────────────────┘

1. 规范化输入 URL（normalize_reel_url），使 /reel/X/ 和 /reel/s/…/ 都能正常工作。

2. 加载会话 — 应用已保存的 Cookie（sessionid、csrftoken、ds_user_id、ig_did、mid、rur）或进行登录。

3. 获取并解析 Reel 页面，采用分层回退机制：

   • parse_reel_page → 嵌入式 window.__additionalData / sharedData HTML JSON

   • parse_reel_json → 原始 GraphQL GQL 响应

   • parse_graphql_reel → shortcodeMedia 对象

   • DOM 回退 → _extract_text_raw 通过正则适配器查询实时页面中的点赞 / 评论 / 播放量 / 粉丝数。

4. 增强发布者信息（除非使用 --no-profiles）：获取个人主页并读取 followers、full_name、bio、is_verified、reels_count。

5. 遵守限制：请求之间休眠 delay 秒；如果被阻止，则退避并重试。

6. 写入行数据到 CSV / JSON / Excel，每行带有 status。

🏗️ 项目架构

Reelminner 采用单引擎、多接口的设计。一个核心引擎（Reelminner）完成所有实际工作；GUI、CLI、MCP 服务器和 Python API 都是调用它的轻量前端。这确保了每个入口点的解析、会话处理和限速逻辑完全一致。

                         ┌─────────────────────────────┐
        URL(s) in ──────▶│     Reelminner     │  scraper.py
                         │  ── engine / orchestrator ──  │
                         └───────┬───────────┬──────────┘
                  run scrapes    │           │  enrich owner
                                 ▼           ▼
                    ┌────────────────┐  ┌──────────────────┐
                    │   parsers.py    │  │ session + graphql│
                    │ pure extractors │  │ (followers/music)│
                    └───────┬────────┘  └─────────┬────────┘
                            └─────────┬────────────┘
                                      ▼
                            ReelData row + status
                                      ▼
                       CSV / JSON / Excel writers

模块职责

引擎内部结构（Reelminner）

• 会话层 — _SESSION_COOKIE_NAMES（sessionid、csrftoken、ds_user_id、ig_did、mid、rur）；_apply_cookies()、_refresh_if_needed()（24 小时）、login()（交互式二维码）、clear_session()。

• 并发 — scrape() 启动一个 ThreadPoolExecutor(max_workers=workers)；每个 URL 由 _worker → _scrape_url 处理，后者调用 _gather_metadata（Reel 数据）并可选择调用 _gather_article（发布者个人主页）。信号量 + _sleep() 确保请求礼貌；当 Instagram 返回 BLOCKED / RATE_LIMITED 时，status_code / retcode 驱动自适应重试/退避循环。

• 解析管道（分层回退） — 在 _gather_metadata 内部，引擎按顺序尝试：parse_reel_page（嵌入式 HTML JSON）→ parse_reel_json（原始 GraphQL GQL）→ parse_graphql_reel（shortcodeMedia）→ 通过 _extract_text_html / _extract_text_raw 适配器和 _PATTERNS 正则列表（点赞/评论/播放量/粉丝数）进行 DOM 回退。

• 个人主页信息增强 — get_follower_count() 使用 Instagram 的 GraphQL UserByRestrictedView / GraphQLOwnerInfo 查询，在计数被截断时回退到 DOM 并对粉丝进行分页（_fetch_followers 配合 end_cursor）。

• 输出 — 行数据以 ReelData 字典形式收集，由 write_csv（遵循 csv_columns）、export_json 或 export_excel（需要 openpyxl）写入。

为什么采用这种布局

• 可测试性 — 所有解析逻辑都位于 parsers.py 中，不依赖浏览器，因此 tests/test_parsers.py 可以针对保存的 HTML/JSON 测试夹具进行断言。

• 单一事实来源 — 每个接口共享同一个 Reelminner，因此引擎中的修复会同时惠及 GUI、CLI 和 MCP 服务器。

• 安全打包 — GUI/CLI 是轻量外壳，意味着 PyInstaller EXE 只打包引擎 + 最小化 UI，保持二进制文件小巧。

📦 安装

要求：Python 3.10+ 和 Playwright 浏览器引擎。

# 1. Clone
git clone https://github.com/ilovekushgola/reelminner.git
cd reelminner

# 2. (Recommended) create a virtual environment
python -m venv .venv
.venv\Scripts\activate        # Windows
# source .venv/bin/activate   # macOS / Linux

# 3. Install dependencies
pip install -r requirements.txt

# 4. Install the Chromium browser for Playwright
playwright install chromium

仅 GUI： 桌面应用使用 tkinter，它随标准 Python 安装自带。 无需额外安装包。GUI 在 Windows 上体验最佳。

可选的开发/测试工具：

pip install -r requirements-dev.txt   # pytest, coverage

💡 开始之前： Reelminner 在已登录的 Instagram 会话下效果最佳——某些 Reel 以及所有发布者/粉丝数据都需要身份验证。请运行 python scraper.py --login 一次（交互式二维码），或使用 python scraper.py --import-cookies cookies.json 导入从 EditThisCookie 浏览器扩展导出的 Cookie。 它只读取您已有权限查看的公开内容。

🚀 快速开始

# Scrape a single reel from the command line
python scraper.py "https://www.instagram.com/reel/CxXYZ123/"

# …or many reels from a file (one URL per line)
python scraper.py -f urls.txt -o export.csv

# Launch the desktop GUI
python gui.py

💻 使用方法

1. 桌面 GUI

python gui.py

• 点击 登录（可选但推荐——可提高成功率）。

• 在输入框中每行粘贴一个 Reel 链接（或按 Ctrl+A 全选）。

• 拖动 Workers 滑块，然后点击 抓取。

• 在表格中查看结果。

• 右键单击某行可 复制链接 或 打开 Reel。

• 导出为 CSV / Excel / JSON，或 打开结果文件夹。

最近一次的结果会自动保存到 results/_last_results.json。

2. 命令行（CLI）

python scraper.py [URL ...] [options]

# Headless, 5 workers, 1s delay, no profile enrichment
python scraper.py -f reels.txt -w 5 --delay 1 --headless --no-profiles -o out.csv

3. MCP 服务器（供 AI 代理使用）

Reelminner 附带一个 MCP（模型上下文协议） 服务器，使 AI 客户端可以驱动它。

python mcp_server.py            # stdio transport

配置你的 MCP 客户端（仓库中包含 .mcp.json）：

{
  "mcpServers": {
    "reelminner": {
      "command": "python",
      "args": ["mcp_server.py"],
      "cwd": ".",
      "env": { "RMIN_HEADLESS": "true" }
    }
  }
}

暴露的工具（5 个，稳定版）：

环境变量覆盖： RMIN_HEADLESS、RMIN_WORKERS、RMIN_DELAY、RMIN_WITH_PROFILES。

4. Python API

from scraper import Reelminner, write_csv

scraper = Reelminner(workers=3, delay=2.0, headless=True)
rows, report = scraper.scrape(
    ["https://www.instagram.com/reel/CxXYZ123/"],
    with_profiles=True,
)
write_csv(rows, "out.csv")

for r in rows:
    print(r["username"], r["followers"], r["likes"], r["status"])

Reelminner 的关键成员：

• scrape(urls, with_profiles=True) → (rows, report)

• login() — 交互式登录

• has_session() / save_cookies_from_file(path) / clear_session()

• write_csv(rows, path)、export_json(rows, path)、export_excel(rows, path)

• normalize_reel_url(url) — 公共辅助函数

• csv_columns — 输出字段的有序列表

• DEFAULT_STATE_FILE — 默认的 storage_state.json

📊 输出格式

每个 Reel 对应一行。完整的 CSV 模式（scraper.csv_columns）：

⚙️ 配置

Cookies / 会话

• 使用 python scraper.py --login 登录（保存 storage_state.json）。

• 或者通过 EditThisCookie 扩展从浏览器导出 cookies，然后运行 python scraper.py --import-cookies cookies.json。

环境变量（供 MCP 服务器和 CLI 默认值使用）

提供了一个模板：将 mcp.env.example 复制为 mcp.env 以覆盖 MCP 默认值。

🗂️ 项目结构

reelminner/
├── scraper.py          # Core engine: Reelminner + CLI
├── gui.py              # Tkinter desktop application
├── parsers.py          # Pure extraction helpers (HTML/JSON/music/regex)
├── mcp_server.py       # MCP server (5 tools for AI agents)
├── theme.py            # Dark‑theme styling for the GUI
├── build_exe.py        # PyInstaller build script
├── Reelminner.spec  # PyInstaller spec (one‑file EXE)
├── run_qa.py           # End‑to‑end QA harness with data‑quality gates
├── requirements.txt    # Runtime dependencies
├── requirements-dev.txt# Dev / test dependencies
├── mcp.env.example     # MCP env template
├── .mcp.json           # MCP client configuration
├── assets/             # Icons (icon.ico)
├── docs/               # SKILL.md, E2E test/fix plan
├── skills/             # Agent skill definition
├── tests/              # pytest suite + corpus.txt
└── results/            # Scrape outputs (git‑ignored)

🧪 测试与质量保证

# Unit / integration tests
pytest -q

# End‑to‑end data‑quality run (uses your saved session)
python run_qa.py                 # full run over tests/corpus.txt
python run_qa.py --quick         # 1 URL, headless, fast iteration
python run_qa.py --url <reel>    # custom single URL
python run_qa.py --report-only   # show last qa_report.json

QA 测试框架强制执行解析率、验证率、非空率、阻止率和最大运行时间等门槛，并写入 results/qa/qa_report.json + qa_results.csv。

📦 构建独立 EXE

在 Windows 上，生成一个可移植的 .exe（最终用户无需安装 Python）：

pip install pyinstaller
python build_exe.py

输出：dist/Reelminner.exe（通过 Reelminner.spec 进行单文件构建）。

⚠️ 法律与道德声明

Reelminner 仅供教育和授权/个人使用。

• 抓取 Instagram 可能违反其服务条款。请仅对你自己拥有或获准访问的内容使用。

• 遵守速率限制（--delay、减少 --workers），不要将其用于垃圾信息、骚扰或商业批量提取。

• 你需自行负责如何使用此工具，并遵守你所在司法辖区的适用法律（包括 GDPR / 隐私法规）。

• 作者与 Instagram/Meta 无关联，且不承担任何责任。

🆘 故障排除与常见问题

playwright 提示浏览器未安装 / 页面无法打开 → 确保你同时运行了 pip install -r requirements.txt 和 playwright install chromium。没有下载 Chromium 则无法启动任何内容。

大多数字段为空，或出现 BLOCKED / RATE_LIMITED → 登录（python scraper.py --login）或导入 cookies，然后放慢速度： --delay 4 并减少工作线程数（-w 1）。Instagram 对匿名/未认证流量的限制最严格，因此认证会话是最大的成功因素。

某个 Reel 返回 NO_DATA → 该帖子可能是私密的、已删除或受地区限制，或者 Instagram 显示了登录墙。 请使用已登录的会话重试。

GUI 窗口无法打开或字体显示异常 → GUI 使用 Python 内置的 tkinter。在 Windows 上效果最佳。在 Linux/macOS 上，如果窗口无法启动，请安装 Tk 包（例如 sudo apt install python3-tk）。

运行脚本时出现 ModuleNotFoundError → 你可能不在仓库或其虚拟环境中。先 cd 进入项目文件夹并激活虚拟环境（Windows 上为 .venv\Scripts\activate，macOS/Linux 上为 source .venv/bin/activate），然后再运行 python scraper.py。

如何一次抓取大量 Reel？ → 将每个链接放在文本文件的一行中，然后运行 python scraper.py -f urls.txt -o out.csv。

AI 代理可以使用这个吗？ → 可以 — 运行 python mcp_server.py，并将任何 MCP 客户端（Claude Desktop、Cursor 等）指向附带的 .mcp.json。参见 MCP 服务器。

🤝 贡献

1. Fork 仓库并创建功能分支。

2. pip install -r requirements-dev.txt

3. 在 tests/ 中添加/调整测试；运行 pytest 和 python run_qa.py --quick。

4. 提交描述更改内容和 QA 结果的拉取请求。

📄 许可证

根据 MIT 许可证 发布 — 参见 LICENSE。

🏷️ 名称

项目的最终公开名称是 Reelminner（"Reel miner"）。早期的内部代号已停用。如果你 fork 它，可以将其重命名为任何你喜欢的名称 — 只需更新 gui.py 和本 README 中的标题即可。