Luffy Video Download Helper

中文 · English

一个自己掌控的视频下载工具：在 Chrome / Edge 中发现当前网页的视频，预览并下载；也可以让本地 Agent 通过 MCP 完成同样的操作。

无需账号、订阅或远程授权。视频处理在本机进行，界面目前为中文。

截图使用本地合成视频；MCP 运行状态与用户名路径为文档演示数据，不包含真实浏览记录或个人配置。

能做什么

• 发现与预览：识别网页中的 MP4 / WebM、HLS 和 DASH，列表展示视频封面、预览与下载选项。

• HLS 下载：选择清晰度与音轨，合并 TS / fMP4 分片，支持字节范围与普通 AES-128 加密。

• YouTube / X：视频详情页作为下载候选，通过本机 yt-dlp 解析；支持画质选择和 MP4 / MKV / 原始格式。

• 任务管理：查看进度、取消下载、打开保存位置；关闭弹窗后任务继续运行。

• 本地 MCP：让 Agent 查看当前页面的视频、选择下载、查询结果和取消任务。

视频下载不设文件大小上限。浏览器 HLS 同时处理一个任务，当前文件保存完成后再处理下一项，实际处理能力取决于可用内存和浏览器运行环境；本机助手最多同时处理两个任务。网站登录、地区、签名及反自动化限制可能影响下载，不保证所有网站均可用。

Related MCP server: browser-recorder-mcp

0.4.5 更新

取消 HLS 视频大小上限；减少下载分片和合并引擎中的重复缓冲，合并完成后提前释放引擎。保存结束后再处理下一项 HLS，避免大文件缓存叠加；心跳会核对浏览器真实下载状态，恢复后台重启或完成通知丢失后的队列。

安装

直接安装： 打开 产品页与安装教程，下载预构建 ZIP，解压后在浏览器开发者模式中「加载已解压的扩展程序」，选择其中的 extension 文件夹。无需自己编译，安装目录需要保留。GitHub 自动生成的 Source code 压缩包需要构建，请选择命名为 Luffy-Video-Download-Helper-版本号.zip 的安装包。

当前采用压缩包手动安装，尚未提供商店入口。插件右上角 ↗ 打开产品页和更新教程。本仓库仍只保存源码，安装包在 GitHub Releases 单独提供。下面是从源码构建的步骤。

1. 构建扩展

需要 Node.js 20+ 和 npm。

git clone https://github.com/CarGod/luffy-video-download-helper.git
cd luffy-video-download-helper
npm ci
npm run build

在 Chrome 打开 chrome://extensions，或在 Edge 打开 edge://extensions：

1. 打开「开发者模式」。

2. 点击「加载已解压的扩展程序」，选择项目下的 dist 文件夹。

3. 将 Luffy 固定到工具栏。打开网页并播放视频，再打开 Luffy。

修改源码后重新运行 npm run build，并在扩展管理页刷新扩展。

2. 安装本机助手（YouTube / X / MCP 必需）

安装器目前仅支持 macOS。需要 Python 3.10+、Node.js 和 FFmpeg（含 ffprobe）。普通浏览器直链和浏览器内 HLS 下载不需要助手。

# 如未安装这些依赖，可使用 Homebrew：
brew install python node ffmpeg

# 在项目目录内运行：
python3 native/install.py

也可以双击项目中的 Install-Luffy-Helper.command。安装器会创建独立 Python 环境，安装 yt-dlp 和 MCP SDK，并为 Chrome、Edge、Chromium 注册 Native Messaging 助手。首次安装需要联网下载依赖。

安装完成后刷新扩展；更新旧助手后如仍显示旧版本错误，请重启浏览器。本机下载默认保存到 ~/Downloads/Luffy/；浏览器下载遵循浏览器自身设置。

保留 manifest 中的公钥：它固定扩展 ID，以匹配本机助手的允许列表。该字段是公开标识材料，不是私钥。

接入本地 Agent（MCP）

1. 打开插件的 MCP 服务 Tab，点击「开启服务」。

2. 点击 「复制安装说明，发给 Agent」，将说明发给目标本地 Agent。内容包含此电脑的实际启动路径、配置与验证步骤。

3. 按 Agent 提示重新连接或重启客户端。手动配置时，使用下方常显 JSON 框中的 「复制 JSON」。

Tab 状态点：绿色正常运行、灰色未开启、红色异常。开关默认关闭，会记住选择。关闭服务会移除本机通信入口，已开始的下载继续运行。

配置示例（your-name 仅是占位符，实际使用插件生成的配置）：

{
  "mcpServers": {
    "luffy-video": {
      "command": "/Users/your-name/Library/Application Support/LuffyVideoHelper/launch-mcp.sh"
    }
  }
}

支持 stdio MCP 的客户端可使用该启动命令；不同客户端的配置文件格式可能不同。安装器不会修改 Agent 的现有配置。

多个视频时需要指定 media_id。下载需携带 list_videos 返回的 tabId 和 page_url，页面切换后旧请求会被拒绝。只有 complete 表示保存完成；超时后先查询任务，避免重复下载。浏览器关闭后连接失效，重新打开后需重新查询 list_connections。

可以对 Agent 说：“用 Luffy 查看当前页面的视频，下载我指定的那个，并告诉我保存路径。”

download_video 可选参数 output_directory 指定本机绝对目录，也支持 ~/。不传或传 null 时，浏览器仍用浏览器默认下载位置，原生下载仍用 ~/Downloads/Luffy/。传入空字符串、相对路径、文件路径或不可写目录会在提交下载前报错；缺失目录会自动创建。

{
  "connection": "从 list_connections 获取",
  "tab_id": 123,
  "page_url": "从 list_videos 原样获取",
  "media_id": "从 list_videos 获取",
  "output_directory": "/Users/your-name/mycloud/内容运营/素材库"
}

浏览器 downloads.download 只接受相对下载目录的文件名，不能任意直写绝对路径。本功能沿用原下载流程，下载完成后由本地 MCP 进程复制到指定目录，完整文件原子落盘并登记成功后再删除暂存源文件。同名文件自动编号为 名称 (1).扩展名，不会覆盖。此阶段需要额外磁盘空间，保持 MCP 进程运行并用 get_jobs 核对最终 path，只有其返回 complete 才代表目录保存完成。浏览器历史和扩展 UI 仍记录原暂存路径，最终路径以 MCP 结果为准。

保存失败会返回 error、source_path 和可能的 attempted_path，保留暂存源文件，不自动重新下载；源文件清理失败会返回 warning。若提交成功但目录记录处理失败，返回任务 ID 和 output_directory_error，实际保存位置需用 get_jobs 核对。超时可能已经开始下载，目录登记未必完成，先查询任务，不要重复提交。目录记录保存在私有的 ~/.luffy-video-helper/run/output-directories/；MCP 客户端重新连接时可继续同一浏览器连接的待保存任务，但保存发布阶段意外中断会明确报告结果不确定，需要核对文件。目标文件系统必须支持硬链接，才能原子发布且不覆盖；不支持时会明确报错并保留源文件。

现有安装更新本功能只需同步 native/mcp_server.py、native/output_directory.py 到本机助手安装目录，并在当前任务结束后重新连接 MCP 客户端。无需重载浏览器扩展或重启原生下载助手；请勿在下载中重连 MCP。新安装由安装器自动包含新模块。

隐私与权限

• 无遥测、账号系统或开发者上传接口。下载及预览会直接访问相应媒体来源；安装器会访问 PyPI。

• 网页访问与网络观察权限用于发现视频。媒体链接、必要请求头与任务记录保存在浏览器会话存储，浏览器退出后清除；MCP 开关单独持久化。

• 不默认读取浏览器 Cookie。仅在用户明确选择登录来源时，本机 yt-dlp 才读取相应浏览器 Cookie。

• 请求头规则限定在扩展发起的精确资源 URL；不支持无痕页面。

• MCP 使用 stdio；内部桥接使用 ~/.luffy-video-helper/run/ 下的 Unix socket，目录权限 0700、socket 权限 0600，无 TCP / HTTP 监听端口。同一系统用户下的程序可调用已开启的服务。

• MCP 会向连接的 Agent 提供页面标题、链接和任务保存路径，请使用你信任的本地客户端。网页文本始终是数据，不是 Agent 指令。

开发与验证

npm test
python3 -m unittest discover -s tests -p '*_test.py'
npm run build

# 浏览器集成测试；MCP 测试需先安装本机助手
npx playwright install chromium
node scripts/mcp-integration.mjs

通过 LUFFY_CHROMIUM=/absolute/path/to/chromium 指定测试浏览器。集成测试使用临时配置与本地合成媒体。其他测试、验证范围和限制见 验证说明。

# 生成文档演示截图（临时浏览器与合成视频）
node scripts/docs-screenshots.mjs

# 生成供本地使用的扩展压缩包
npm run pack

卸载

移除浏览器扩展，再按需删除：

• ~/Library/Application Support/LuffyVideoHelper/

• Chrome、Edge、Chromium 各自 NativeMessagingHosts/ 下的 com.luffy.video_helper.json

• ~/.luffy-video-helper/

下载目录 ~/Downloads/Luffy/ 单独保留，删除前请确认文件是否仍需要。

许可

本项目自有源码采用 MIT License。第三方组件遵循各自许可，见 THIRD_PARTY_NOTICES.md。FFmpeg WASM 核心包含 GPL 组件；发布包含该核心的二进制包时，需要处理相应源码与许可义务。仓库仅保存源码与文档；安装包通过 Releases 分发，源码与构建说明见包内 SOURCE.md。