========================================
 Lightning Downloader 1.0 使用说明
========================================

一、安装桌面端
--------------------------------
方式 A（安装版）
  1. 双击 LightningDownloader_Setup.exe，按提示完成安装。
  2. 首次运行会自动创建配置目录：%APPDATA%\LightningDownloader
  3. 程序启动后会常驻系统托盘，双击托盘图标可显示/隐藏主窗口。

方式 B（便携版）
  1. 解压 LightningDownloader_Portable.zip 到任意目录（路径建议不含中文）。
  2. 双击 LightningDownloader.exe 运行，resources 文件夹必须与 exe 保持在一起。

提示：若系统缺少 WebView2 运行时，安装程序会自动下载安装。

二、安装浏览器扩展
--------------------------------
【推荐】软件内一键安装
  1. 打开桌面端，点击顶部工具栏的「拼图」图标。
  2. 程序会自动检测本机已安装的 Chrome / Edge / Brave / Vivaldi。
  3. 点击对应浏览器按钮：扩展文件会自动释放，浏览器扩展页自动打开，
     并把扩展目录路径复制到剪贴板。
  4. 在打开的页面中开启「开发者模式」→「加载解压缩的扩展」→ 粘贴路径 → 确定。
  注：浏览器安全策略不允许第三方程序静默装扩展，第 4 步需手动确认一次。

【手动方式】

Microsoft Edge
  1. 解压 Extension_Edge.zip 到一个固定文件夹（不要删除）。
  2. 地址栏输入 edge://extensions/ 回车。
  3. 打开左下角“开发人员模式”。
  4. 点击“加载解压缩的扩展”，选择第 1 步解压出的文件夹。

Google Chrome
  1. 解压 Extension_Chrome.zip 到一个固定文件夹（不要删除）。
  2. 地址栏输入 chrome://extensions/ 回车。
  3. 打开右上角“开发者模式”。
  4. 点击“加载已解压的扩展程序”，选择第 1 步解压出的文件夹。

三、使用方法
--------------------------------
1. 保持桌面端处于运行状态（托盘有闪电图标）。
2. 扩展图标显示绿色即为已连接桌面端；显示 "!" 表示桌面端未启动，
   显示蓝色数字表示当前页面嗅探到的可下载媒体数量。
3. 鼠标悬停在网页视频、音频或下载链接上，右上角会出现半透明“下载”气泡，
   点击即把任务发送到桌面端，由 aria2 多线程下载；m3u8/dash 等流媒体
   会自动切换到内置 yt-dlp 引擎。
4. 点击普通下载链接时，若开启“下载接管”，页面右上角会弹出确认小窗：
   选择「下载」交给本工具，或「用浏览器」保留浏览器自身的下载。
   8 秒无操作默认交给本工具；可在扩展弹窗关闭「接管前先询问」跳过此步。
5. 气泡右侧的数字徽章 = 本页嗅探到的资源数。点击徽章可展开完整列表，
   支持多选、选择画质后批量下载。
   若页面没有可悬停的视频或链接（常见于小众动漫、影视站的自定义播放器），
   右下角会出现「媒体资源」浮动按钮，点击同样可打开该列表。
6. 任务完成或失败时，桌面端会弹出 Windows 通知（可在设置中关闭）。
7. 在扩展弹窗中可随时开关“下载接管”“浮动气泡”“接管前先询问”，
   并可设置画质与转换格式。

六、B 站 / 流媒体视频（音画合并）
--------------------------------
B 站、YouTube 等站点采用 DASH 分离流（视频 .m4s 无声音）。本工具内置 ffmpeg，
会自动用 yt-dlp 的 bv*+ba 策略同时下载视频与音轨并合并为带声音的 MP4，
不会再产生无声的 .m4s 文件。

- 画质：在主界面工具栏或扩展弹窗中选择
  「最佳画质 / 1080p / 720p / 480p / 最小体积 / 仅音频」。
  · 最佳画质：同分辨率下优先选码率最高、且为 H.264 编码的版本，
    画质最好、兼容性最强（可直接用于剪辑软件、电视盒子）。
  · 最小体积：优先 AV1/HEVC 新编码，同画面体积可小 4 倍以上，
    但部分老设备无法解码。
  说明：B 站同一个 1080p 常有 AVC(2629k)、HEVC(749k)、AV1(604k) 三个版本，
  yt-dlp 默认会挑 AV1，本工具已改为按码率优先。

- 会员画质（1080p60 / 4K / HDR / 杜比）：
  这些清晰度需要登录且为大会员。请安装浏览器扩展并在浏览器中登录 B 站，
  扩展会自动携带登录 Cookie（含 HttpOnly 的 SESSDATA）交给桌面端，
  即可下载你账号权限内的最高画质。
  若不使用扩展，可在「设置 → 会员画质 Cookie 来源」中选择本机浏览器，
  程序会直接读取该浏览器的登录状态（需先关闭该浏览器）。
  Cookie 仅在下载期间临时写入，任务结束后立即删除。
- 转换：选择「转 MP4 / MKV / MP3 / M4A / WAV」，下载完成后自动转换。
  视频类转换为直接封装（不重新编码，秒完成且不损画质），音频类会重新编码。
- 已完成的任务也可在列表中点击「⇄」按钮，随时单独做一次格式转换。

七、非主流站点适配
--------------------------------
- 扩展会嗅探 HLS(m3u8)、DASH(mpd)、分片(m4s/ts)、以及无扩展名的大体积媒体响应，
  并支持 iframe 内嵌播放器。
- 播放器使用 blob:/MSE（B 站、油管等）时，气泡会自动改为把「页面地址」交给
  yt-dlp 解析，仍可正常下载。
- 若气泡未出现，有三种方式获取资源：
  1) 点击气泡右侧的数字徽章，展开本页全部嗅探结果（可多选批量下载）；
  2) 页面右下角的「媒体资源」浮动按钮（无可悬停元素的站点会自动出现）；
  3) 扩展弹窗中的「本页嗅探到的资源」列表，或「整页视频交给 yt-dlp 下载」按钮，
     后者兼容 yt-dlp 支持的一千多个站点。
- 提示：先播放几秒视频再操作，嗅探才能捕获到真实的媒体地址。

四、桌面端主界面
--------------------------------
- 顶部：粘贴链接后按回车或点“新建”即可手动添加下载。
- 中部：任务列表，可暂停、继续、打开所在文件夹、删除任务。
  每行“速度”列下方有限速下拉框，可对单个任务实时限速（无需重启任务）。
- 底部：总速度、任务数、当前下载目录（点击可打开）。
- 齿轮按钮：设置下载目录、最大线程数（1-32）、接管阈值、开机自启等。
- 列表按钮：打开“规则与调度”面板，含三个标签页（详见第九节）。

九、规则与调度
--------------------------------
点击工具栏的列表图标打开，共三个标签页：

1) 分类规则 —— 下载目录自动分流
   按「域名 / 文件后缀 / URL 正则」三选一或组合来匹配，命中后保存到指定目录。
   目标目录填相对路径（如 Videos）则基于默认下载目录；填绝对路径
   （如 D:\Videos）则直接使用，可跨盘。
   数字越小优先级越高，从上往下依次匹配，未命中任何规则时用默认目录。
   注意：不填任何匹配条件的规则永远不会生效（避免误把所有文件分流走）。

2) 站点规则 —— 自动注入请求头
   为指定域名（支持 *.example.com 通配）配置 Referer / Cookie / User-Agent，
   适用于需要登录或有防盗链校验的站点。
   此处手动配置的 Cookie 优先级高于浏览器扩展传来的 Cookie。

3) 调度策略 —— 分时段全局限速
   可按「每天 / 工作日 / 周末」分别设置时段限速，支持跨夜时段（如 22:00-6:00）。
   程序每分钟检查一次，到点自动调整 aria2 全局限速。
   优先级：任务自身的限速 > 分时段调度限速。

十、重复文件处理
--------------------------------
新建下载时若目标目录已存在同名文件，不会直接覆盖，而是弹出四选一对话框：
- 自动重命名：保留旧文件，新文件加序号，如 name(1).zip
- 断点续传：继续下载未完成的碎片（仅当存在 aria2 控制文件时可选）
- 覆盖：删除旧文件重新下载
- 跳过：本次不下载

十二、剪贴板监控（复制即下载）
--------------------------------
开启后（默认开启），复制下载链接时屏幕右下角会自动弹出无边框小窗：
- 显示链接预览，可直接修改文件名；
- 点「高级选项」可选择保存目录和画质；
- 点「下载」加入队列，点「取消」或按 Esc 关闭；
- 拖动窗口顶部可移动位置。

支持识别 http:// https:// ftp:// magnet: ed2k:// thunder://
以及本地 .torrent 文件路径。

为避免打扰，以下情况不会弹窗：
- 复制的是普通文字；
- 只复制了域名没有具体路径（如 https://example.com）；
- 该链接已在任务列表中。

可在「设置 → 启用剪贴板监控」中关闭。

十三、任务完成时自动操作
--------------------------------
在「设置 → 任务完成时」中可多选以下动作：

- 播放提示音：使用系统提示音。
- 执行外部命令：填写 .bat / .exe 的路径，支持三个占位符：
    %FILE_PATH%  下载文件的完整路径
    %FILE_NAME%  文件名
    %SAVE_DIR%   保存目录
  示例： "D:\tools\notify.bat" "%FILE_PATH%" "%FILE_NAME%" "%SAVE_DIR%"
  路径含空格时请用英文双引号包裹。
- 自动关机 / 进入睡眠：会先弹出 60 秒倒计时，主界面底部出现红色提示条，
  点「取消」即可中止，不会立刻断电。

十一、崩溃 / 断电恢复
--------------------------------
程序被强制结束或断电后，重启时会自动扫描数据库中未完成的任务：
- 若 aria2 会话中仍存在该任务，直接沿用，进度不丢失；
- 若会话已丢失，则依据数据库记录重新登记任务并启用断点续传，
  状态置为“已暂停”，点击继续即可从原进度接着下载（不会从 0 重来）。
恢复过程全部写入 %APPDATA%\LightningDownloader\logs\recovery.log。

说明：断点续传依赖 aria2 生成的 .aria2 控制文件（与下载文件同目录），
请勿手动删除该文件，否则只能重新下载。

八、常见问题
--------------------------------
Q: 气泡不出现？
A: 检查扩展弹窗中“浮动气泡”开关是否开启，并刷新页面。

Q: 下载的 B 站视频没有声音 / 是 .m4s？
A: 请确认 resources 目录下有 ffmpeg.exe（便携版需与 exe 同级）。有它才会自动合并音轨。

Q: 视频网站只下到一小段 .ts 文件？
A: 单个 .ts/.m4s 只是 HLS 的一个切片。本工具会自动回溯到父级 m3u8 播放列表
   并交给 yt-dlp 合并成完整视频。若仍失败，请在扩展弹窗的「本页嗅探到的资源」
   中选择标记为 HLS/DASH 的那一条，或使用「整页视频交给 yt-dlp 下载」。

Q: 如何删除任务？
A: 任务行最右侧的「✕」按钮；也可点选一行（Ctrl 多选、Ctrl+A 全选）后按 Delete 键，
   或点工具栏的垃圾桶图标。删除时可勾选「同时删除本地文件」。

Q: 速度没有想象中快？
A: 请在设置中把「最大线程数」调到 16；速度还受服务器单连接限制、
   本地带宽和源站距离影响，部分站点会主动限速。

Q: 下载 Linux ISO（Fedora/Ubuntu/Debian 等）速度很慢？
A: 官方下载地址通常是「镜像重定向器」，可能把你分配到一个很慢、
   且对单 IP 限速的境外镜像（此时线程数越多反而越慢）。
   本工具的「开源镜像加速」会自动识别这类地址，探测清华/南大/北外/
   华科/浙大/兰大等国内镜像（校验文件大小一致后才启用），
   让 aria2 同时从多个镜像并行下载。实测 1.0 MB/s -> 6~8 MB/s。
   该功能默认开启，可在设置中关闭。

Q: 点击气泡提示“桌面端未启动”？
A: 请先运行 Lightning Downloader，服务端口为 127.0.0.1:16800。

Q: 下载速度不理想？
A: 在设置中提高“最大线程数”（建议 8-16），部分服务器会限制单文件连接数。

Q: 日志在哪里？
A: %APPDATA%\LightningDownloader\logs\app.log 与 aria2.log

祝使用愉快。
