流萤由浏览器扩展和 Windows 本地助手两部分组成。扩展在网页里发现视频、音频、图片和 HLS/DASH 清单；本地助手用 Rust 编写，负责下载、排队、断点恢复和 FFmpeg 合并。任务和设置只保存在本机。
当前版本为 1.0.7。流萤不绕过 DRM，请只下载你拥有版权或已获授权的内容。
流萤分为两个发行版，源码相同：
- 通用版：不限制网站，通过 GitHub Release 分发，包含 Chrome/Edge 扩展、签名 Firefox 扩展和 Windows 本地助手。能否识别和下载仍取决于网站本身。
- Chrome 应用商店版：根据 Chrome 应用商店政策，不识别和下载 YouTube 内容。（当前还在审核中，所以应用商店可能搜索不到流萤）
亮点
功能
- 从网络请求、响应类型、媒体元素、JSON/文本和内联脚本中识别媒体地址，也能解析页面用 POST、Blob 或脚本在内存中生成的 HLS 清单。打开流萤之前已经加载的清单，会在打开时从页面资源时序中补录。
- 普通文件支持 1–16 路 Range 并发下载，暂停后按分段续传；服务器不支持分段时回退单连接。
- HLS 可选择清晰度、外部音轨、多字幕和时间或切片范围，支持标准 AES-128；合并时不转码，纯音频输出 M4A。
- HLS 直播可以手动开始、暂停和停止保存。
- DASH 点播（实验性）可选择一条视频和一条音轨，输出 MP4 或 MKV。
- 任务按先后顺序排队，最多同时下载 2 个；本地助手重启后，可恢复的任务会自动继续。
- 点击工具栏图标后，在当前网页打开可拖动、可缩放的悬浮面板，需要时展开为工作区；配色跟随系统深浅色。
- 可选功能：识别规则、URL 提取、输出模板、发送到外部工具（Aria2、HTTP 服务、本机程序、自定义协议）、深度搜索和缓存捕捉。
截图
 资源列表 |
 下载任务 |
 悬浮工作区 |
 HLS 解析 |
截图来自自动化界面测试，资源为测试数据。
支持范围
| 类型 | 状态 | 说明 | | --- | --- | --- | | 普通 HTTP 文件 | 支持 | 视频、音频、图片；并发下载、暂停续传 | | HLS 点播 | 支持 | 切片级重试、检查点与重启恢复 | | HLS AES-128 | 支持 | 批量下载前先用第一个切片验证密钥 | | HLS 直播 | 支持 | 在解析页单独开始录制；不支持 LL-HLS Part | | DASH 点播 | 实验性 | 仅静态、单 Period、非加密清单 | | Blob / MediaSource | 实验性 | 通过缓存捕捉保存开始捕捉之后播放的数据 | | DRM、SAMPLE-AES | 不支持 | 只提示，不绕过 |
可选功能说明
- 识别规则：按后缀、MIME 或 URL 正则匹配，可限定站点和大小，排除规则优先；支持排序、复制、导入导出，并显示命中原因。正则和模板在有超时限制的 Worker 中运行。
- URL 提取：从请求地址中提取真实媒体地址，作为单独的资源显示。提取出的资源不继承原请求的凭据，也不会自动发送到外部工具。
- 输出模板：HLS、DASH 和其他资源可分别设置复制模板，另有文件名模板。只做字符串变换，不执行脚本。
- 文件命名与位置：默认用网页标题命名，服务器提供文件名时拼在标题后面；默认按来源网站放进子文件夹（如
bilibili.com）。可在设置中改回资源原名或关闭分文件夹，已有文件不会移动。 - 检查更新：通用版和 Firefox 版每天第一次打开时向 GitHub 查询一次新版本，有新版才提示，可在设置中关闭。
- 外部工具：发送前在确认页预览展开后的参数，并逐项显示结果。明确失败的可以手动重试，结果未知的不会自动重发。自动发送只对配置过的站点和 HTTP/Aria2 工具生效。
- 深度搜索：默认关闭，按页面开启，可记住站点。会观察 JSON.parse、Base64、文本解码和同源 Worker 中出现的完整 HLS/MPD 文本。发现的疑似 AES-128 密钥只保存在内存中，可在 HLS 解析页选用。
- 缓存捕捉：推荐“重新捕捉”，授权后刷新来源页，从首次追加开始保存。普通捕捉补入页面内存中的有效初始化段，只保存开启后追加的正文；无法确认 Blob 关联时可手动选择。拖动或编码变化分段输出 MKV，不回溯浏览器旧缓存。可选 2–16 倍速静音录制；一键捕捉默认优先录制兼容格式（H.264），录好的视频以网页标题保存在保存目录，系统自带播放器即可播放（部分网站清晰度可能降低，可关闭）。暂存范围和上限见 隐私政策。
安装
一键安装（推荐）
- 安装扩展：Chrome 应用商店版还在审核中，审核通过前请按安装指南安装通用版；其他浏览器同样见安装指南。
- 安装后会自动打开设置页。点击“复制安装命令”，按 Win + R，粘贴并回车。
- 命令会下载与扩展同版本的本地助手，校验 SHA-256 后安装到当前用户目录，无需管理员权限。完成后扩展自动连接。
手动安装完整包
从 Releases 下载适合架构的 Windows 完整包，再按安装指南操作。
从源码构建
需要 Node.js 24、Rust 1.98（MSVC 工具链，需安装 Visual Studio C++ 生成工具），与 CI 使用的版本一致；以及 Chrome/Edge 116+ 或 Firefox 140+。本地助手使用 Windows 自带的 curl 下载，HLS/DASH 合并需要 FFmpeg。
npm install
npm run build:extension
cargo build --release --manifest-path native-host/Cargo.toml- 在
chrome://extensions开启开发者模式，加载extension/目录，记下扩展 ID。 - 注册本地助手：
.\tools\install-native-host.ps1
-ChromeExtensionId '<Chrome 扩展 ID>'
-FirefoxExtensionId '[email protected]'- 每次重新编译本地助手后需要再运行一次安装脚本；扩展更新后在扩展管理页点击“重新加载”。
使用
- 打开有视频或音频的网页，点击工具栏中的流萤图标。
- “资源”页列出已发现的媒体，可以按名称、类型、大小和时长筛选；点开一项可以看到封面、预览和完整地址。
- 点击“下载”保存。HLS/DASH 可以进入解析页选择画质、音轨、字幕和范围；勾选多项后可以批量下载、复制或发送到外部工具。
- “下载”页显示进度，可以暂停、继续、重试或删除任务。
小提示：推荐开启深度搜索。 深度搜索默认关闭。开启后，流萤还会识别网页用脚本动态生成的视频清单，能找到更多资源。开启方法：在“资源”页点击工具栏的雷达图标 →“开启深搜”，然后刷新网页。常用的网站可以勾选“记住此站点”。
遇到问题
- 下载失败、本地助手连不上或一直提示未安装：先看安装指南的常见问题。
- 下载的文件默认保存在
%LOCALAPPDATA%\StreamFirefly\downloads，可以在设置里改成常用文件夹。 - 仍未解决：在扩展设置页“常规 → 问题反馈”中导出诊断报告，再提交问题。issue 是公开的，报告保留了网页地址和标题，提交前请检查。
悬浮窗口操作
- 面板初始尺寸为 480×640px；展开的工作区初始宽 1120px、高为可见网页的 80%，空间不够时自动缩小。
- 拖动标题栏移动窗口，拖动边缘或角落调整大小；收起后的小入口会贴靠最近的左右边缘。尺寸和位置保存在扩展本地配置
floatingUiLayout中。 - 收起后保留小入口并继续嗅探，面板中的预览会停止；关闭后入口消失，已经开始的下载继续进行。
- 标题栏的“返回面板”回到快速面板，最大化后可以还原。在窗口内按 Escape，会依次关闭菜单或筛选弹层、对话框，再还原、返回面板或收起；不会拦截网页自己的 Escape。
- 每个浏览器窗口最多只有一个网页内界面。浏览器内部页面和受限页面会改用原生侧栏，提示该页无法嗅探。
- Firefox 从侧栏展开网页工作区时，受侧栏的用户手势限制；直接点击工具栏图标打开面板时，会同时关闭流萤的侧栏。
工作原理
| 目录 | 内容 |
| --- | --- |
| extension/ | 浏览器扩展：后台、内容脚本、页面探针和清单 |
| extension-ui/ | 侧栏与网页内工作区界面（Vue 3） |
| native-host/ | 本地助手：协议、任务存储、调度和 HTTP/HLS/DASH 下载 |
| shared/ | 扩展与界面共用的识别、提取和模板逻辑 |
| tools/ | 构建、测试和 Windows 安装脚本 |
| docs/ | 设计决策与开发说明 |
开发
npm install
npm run typecheck
npm run validate:extension # 构建并校验 Chrome / Firefox 扩展
npm run test:unit
npm run test:ui:browser # 界面测试，使用模拟 API，截图在 test-results/ui/
npm run verify:features # 包括 cargo test 和本地助手集成测试浏览器测试
使用独立的临时配置，不影响日常浏览器数据。
npm run test:chrome
npm run test:firefox
npm run test:browsers # 依次运行 Chrome、Edge、Firefox浏览器路径可以用 CHROME_BINARY、EDGE_BINARY、FIREFOX_BINARY 指定。
本地助手测试
cargo test --manifest-path native-host/Cargo.toml
npm run test:native首次运行前准备测试用 FFmpeg（不需要安装 Inno Setup）：
.\tools\download-ffmpeg.ps1 -Architecture x64 # 发布包捆绑的精简版
New-Item -ItemType Directory -Force installer\build\x64 | Out-Null
Copy-Item tools\ffmpeg-cache\ffmpeg-x64.exe installer\build\x64\ffmpeg.exe
.\tools\download-fixture-ffmpeg.ps1 # 生成测试素材用的完整版test:native 默认使用刚编译的 debug 版本，任务写入临时目录；可以用 STREAMFIREFLY_NATIVE_EXE 指定其他版本。HLS/DASH 测试中，本地助手使用 STREAMFIREFLY_FFMPEG_EXE 指定的精简版 FFmpeg（默认 installer/build/x64/ffmpeg.exe）；测试素材的生成和检查使用 tools/download-fixture-ffmpeg.ps1 下载的完整版 FFmpeg 和 FFprobe，也可用 STREAMFIREFLY_FIXTURE_FFMPEG_EXE、STREAMFIREFLY_FFPROBE_EXE 指定。
打包与发布
开发自测：
.\tools\package-extension.ps1 -Edition general # 通用版 Chromium 扩展
.\tools\package-extension.ps1 -Edition chrome-store # Chrome 应用商店上传包
npm run package:firefox # Firefox 测试用 XPI（未签名）
.\tools\build-installer.ps1 -Architecture x64 # 本地 EXE 安装器，不进 Release；arm64 同理正式发布入口是 .\tools\package-release.ps1 -SignedFirefoxXpi '<已签名 XPI 路径>'，签名、验收和上传的完整步骤见正式发布流程。
- 正式打包必须使用干净提交和与其运行时代码一致的 Firefox 签名包。内测工具只用于历史版本，不用于正式发布。
tools/prepare-release.ps1是旧的发布流程，产出 EXE 安装器和未签名 XPI，已废弃，不要用于发布。- EXE 安装器构建需要 Inno Setup 6，同时会生成本地助手测试默认读取的
installer/build/<架构>/ffmpeg.exe。捆绑的 FFmpeg 是tools/ffmpeg/build.sh编译的精简 LGPL 版，按固定 SHA-256 下载，不提交到仓库。 - 本地开发用的扩展 ID 是
gimoeapmpoeogpabfdplccplmmohklff，不要用它构建对外发布的安装包。Firefox 固定使用[email protected]。 - 商店提交材料在
store-assets/。
升级与数据
- 扩展和本地助手需要一起升级、一起回滚。只重新加载扩展不会更新已安装的本地助手。
- 升级前先等任务结束，备份
%LOCALAPPDATA%\StreamFirefly\tasks.json、同目录下的tasks文件夹和已下载的文件。 - 如果任务文件版本未知或已损坏，本地助手会停止写入，不会用空列表覆盖它。遇到这种情况请保留原文件排查，不要直接删除。
文档
隐私
Cookie 和 Authorization 只在下载过程中保存在内存里，不写入任务记录。缓存捕捉只保存开始捕捉之后的数据，不读取浏览器缓存。详见隐私政策。
Star 趋势
致谢
流萤使用了 Vue、Pinia、hls.js、Tabler Icons、curl 和 FFmpeg。第三方许可见 THIRD_PARTY_NOTICES.md，FFmpeg 来源见 installer/FFMPEG-SOURCE.txt。