# WebVideoHarbor Community Edition：macOS 安装与使用说明

WebVideoHarbor 由 Chrome 扩展和 macOS 本地助手组成。扩展识别当前页面向浏览器暴露的媒体候选，助手通过本机回环地址处理下载。项目完全免费、源码公开且本地运行，但它不是绕过网站保护的“万能下载器”。

本说明适用于 WebVideoHarbor Community Edition v1.0.0。

## 一、准备环境

需要：

- macOS 与 Google Chrome。
- Homebrew。
- Go，仅从源码构建本地助手时需要。
- FFmpeg，处理 M3U8/HLS 或合并分离音视频时需要；普通 MP4/WebM 不依赖它。

完整 macOS 包内置固定版本的 `yt-dlp 2026.07.04` 和 `Deno 2.8.1`，不会静默更新。直接从源码执行构建脚本只生成助手；需要实验性平台兼容时，请使用完整包。

安装构建工具和 FFmpeg：

```zsh
brew install go ffmpeg
```

## 二、构建并启动本地助手

在项目根目录执行：

```zsh
./scripts/build-macos.zsh
./scripts/start-helper.zsh
```

构建脚本会生成 Apple Silicon 和 Intel 通用的 `work/dist/web-video-harbor-helper`。启动脚本会等待 `http://127.0.0.1:17432/health` 返回健康状态后再报告成功。

查看助手状态：

```zsh
./scripts/helper-status.zsh
```

状态目录固定为 `~/Library/Application Support/WebVideoHarbor/`。默认下载目录是 `~/Downloads/WebVideoHarbor/`。

## 三、获取配对密钥

首次启动会创建随机配对密钥。执行：

```zsh
./work/dist/web-video-harbor-helper --print-token
```

终端中显示的一整行字符是配对密钥。它相当于本机控制凭证，不要分享、截图、粘贴到聊天或提交到 Git 仓库。

## 四、在 Chrome 中加载扩展并配对

1. 打开 `chrome://extensions/`。
2. 打开右上角“开发者模式”。
3. 点击“加载已解压的扩展程序”。
4. 选择安装包或项目中的 `extension/` 文件夹。
5. 打开“网页视频港”的扩展程序选项。
6. 粘贴配对密钥，点击“保存密钥”，再点击“测试连接”。

密钥只保存在这台 Mac 的 Chrome 本地存储中，不同步到其他设备。

## 五、下载普通网页媒体

1. 在 Chrome 中打开你有权保存的媒体页面。
2. 播放几秒，让页面实际加载媒体请求。
3. 打开扩展弹窗；若没有候选，点击“重新扫描”。
4. MP4 和 WebM 可直接下载。M3U8 会先检查清单；存在多个画质时，选择需要的清晰度后下载。
5. 在“下载任务”中查看进度，可取消或重试；完成后可用 Finder 定位文件。

同名文件不会被覆盖，助手会生成安全的新文件名。

## 六、可选的实验性平台兼容

该能力默认关闭。需要使用时：

1. 打开扩展的“设置”页。
2. 点击“实验性平台兼容”开关。
3. 完整阅读本地弹窗中的使用边界，点击“我已了解并继续”。点击取消或按 Esc 不会开启。
4. 返回页面并重新打开扩展。

开启后，YouTube、YouTube Shorts 和哔哩哔哩无需登录便可播放的公开单个视频页面可能显示平台卡片，并提供最佳画质、1080P 或 720P 上限。最终文件根据源格式兼容性保存为 MP4 或 MKV。不支持播放列表。

微信视频号只做最佳努力兼容：只有 Chrome 实际暴露普通 MP4/WebM 或非加密 M3U8 时才可能识别。需要微信客户端内部凭证、Cookie、签名授权、加密或 DRM 的内容不支持。

关闭开关后，新的平台页面任务和重试会被阻止；已经运行的任务可以正常收尾。

## 七、支持范围与限制

默认支持：

- 浏览器能够直接访问的 HTTP(S) MP4 和 WebM。
- 非加密、非 DRM 的 M3U8/HLS。

明确不支持：

- DRM 或加密 HLS 分片。
- Blob-only 视频：如果只有 `blob:` 地址，且没有可独立访问的 MP4/WebM/M3U8 请求，就没有可下载源。
- 必须携带 Cookie、Authorization 授权头或其他登录凭证的私有媒体流。
- 需要登录、会员、付费、私有权限、地区解锁、机器人验证绕过或 DRM 的平台内容。
- 绕过付费墙、地区限制、访问控制或导出用户会话。

详细说明见 [使用边界](使用边界.md)。

## 八、从旧版升级

1. 在旧安装目录运行 `./scripts/stop-helper.zsh`，停止助手。
2. 下载并解压新包，不要删除 `~/Library/Application Support/WebVideoHarbor/`。
3. 打开 `chrome://extensions/`，找到“网页视频港”并重新加载扩展；如果目录已移动，重新选择新版 `extension/` 文件夹。
4. 在新版目录运行 `./scripts/start-helper.zsh`。
5. 在设置页测试连接。状态目录未被删除时，会保留现有配对状态。实验性平台兼容开关也按用户最后一次明确选择保存。

## 九、隐私与本地安全

- 扩展不读取或导出 Cookie、Authorization 授权头、请求体或页面正文。
- 扩展只保留识别媒体候选所必需的 URL 和有界响应元数据。
- 助手只监听 `127.0.0.1:17432`，不开放远程访问。
- 日志不记录配对密钥、Cookie、授权头或请求体，且在运行期间限于 1 MiB。
- 扩展和本地助手不包含广告 SDK、分析、遥测、行为跟踪或远程授权服务。官网可能包含清晰标注的联盟推荐，只有主动点击后才会访问商家页面。

更完整的说明见 [隐私说明](../PRIVACY.md)。

## 十、故障排查

### 显示“未连接”

先运行 `./scripts/helper-status.zsh`。如果助手健康，重新复制配对密钥，在扩展设置页保存并测试连接。截图时不要露出密钥。

### FFmpeg 未安装

普通 MP4/WebM 仍可下载，但 M3U8 和音视频合并会被阻止。安装 FFmpeg 后重启助手。

### 平台解析器缺失

确认使用完整安装包，并检查 `work/dist/yt-dlp_macos` 是否存在且可执行。不要从不明来源补文件。

### JavaScript 解析组件缺失

完整包内含与 Mac 架构匹配的 Deno。如果状态显示 JavaScript 解析环境不可用，请重新下载并替换完整包。

### 平台解析规则已变化

内置 yt-dlp 不会静默更新。出现该提示通常表示公开页面规则已改变，需要等待项目发布新的固定版本。

### YouTube 提示 PO Token、浏览器验证或当前网络阻止

项目不读取 Cookie，不接入账号或 PO Token 提供器，也不绕过机器人验证。公司网络或安全设备阻断连接时，请联系网络管理员；不要尝试规避管理策略。

### 无候选视频

确认视频已在当前标签页播放数秒，再点击“重新扫描”。Blob-only、私有签名或需要 Cookie 的媒体可能不会产生可用候选。

### 提示加密或 DRM

这是受保护媒体，工具会主动停止，不提供解密或绕过功能。

### 权限错误

确认当前用户对 `~/Downloads/WebVideoHarbor/` 和 `~/Library/Application Support/WebVideoHarbor/` 拥有所有权。不要将配置文件或状态目录改成符号链接。

### 端口占用

助手固定使用 `127.0.0.1:17432`。先查看助手状态；如果状态显示未运行但端口仍被占用，请在“活动监视器”中确认占用者，不要随意结束身份不明的进程。

## 十一、停止助手

```zsh
./scripts/stop-helper.zsh
```

停止脚本只会操作 PID 和预期助手命令均匹配的进程。停止助手不会删除配置、配对密钥或已下载文件。