Windows 攻略视频跟随工具：置顶小窗、全局热键、鼠标穿透、鼠标 X 光、底边进度、同步字幕、方向提示、收藏与进度记忆。
中文产品名为“随引”，英文工程名保留 GuideMate；启动入口与数据目录不变，已有设置、收藏和网页登录数据继续使用。
支持 Windows 10 1809 及以上、Windows 11（x64），运行需要 .NET 10 Desktop Runtime（Windows x64） 和 Microsoft Edge WebView2 Runtime。
使用发布包：从 GitHub 仓库的 Releases 下载 GuideMate-版本-win-x64.zip，完整解压后双击 Start-GuideMate.cmd 或 GuideMate.exe。不要只取出单个 EXE。主程序和 Chrome 桥接均为普通多文件发布，DLL 与 EXE 分开存放；发布包只提供应用依赖，不附带 .NET 运行时，也不需要安装 SDK。每次启动会先检查所需的运行时，缺少时由 Windows 原生启动入口显示安装提示并提供官方下载链接；请安装 .NET 10 Desktop Runtime 的 Windows x64 版，普通 .NET Runtime、x86 版或其他大版本不足以运行 WPF 主程序。安装完成后重新打开随引；程序不会自动下载或安装运行时。视频素材、浏览器扩展及说明仍随包提供。
从源码运行：安装 .NET 10 SDK，在 Windows 上克隆源码后双击根目录的 Start-GuideMate.cmd。有本地发布目录时直接启动；否则编译 Release。命令行可用 ./scripts/Start-GuideMate.ps1 -Build 强制从源码构建。
OpenCV 与 WebView2 加载器仍随包提供，首次运行会将这些必要的原生库解包到 %TEMP%\.net，后续启动复用缓存；运行库不启用压缩。
更新前正常退出随引，只替换程序与资源，保留原来的用户资料。旧版本含有大量 DLL 时，将新版完整解压到新的程序目录，避免覆盖解压留下旧运行库；新目录中的程序仍沿用已记录的用户资料目录。首次启动默认打开 B 站；已有用户继续使用已记录的热键、窗口状态、校准和浏览器资料。
默认打开 B 站首页 https://www.bilibili.com/。右上方文件夹按钮可打开本地视频，地址栏可打开其他网页；侧栏的“打开验证样例”仍可加载 40 秒离线测试视频。支持顶层及同源/跨域/嵌套 iframe 的 HTML5 视频控制，仍受网站、沙箱和媒体权限限制。字幕可来自网页，也可导入 SRT、VTT、B 站 JSON。在 B 站播放器中开启字幕后，随引同步当前文字到侧栏及浮窗，支持新版 AI 字幕、双语字幕和旧版播放器；关闭网页字幕后清空同步文字。沉浸模式仍同步，菜单及 AI 图标不作为字幕。导入字幕优先，切换视频后清除。
| 热键 | 操作 |
|---|---|
| Ctrl+Alt+Space | 播放 / 暂停 |
| Ctrl+Alt+Left / Right | 后退 / 快进 |
| Ctrl+Alt+Up / Down | 倍速增加 / 减少 |
| Ctrl+Alt+Shift+V | 按住临时倍速，松键或切换前台后恢复 |
| Ctrl+Alt+PageUp / PageDown | 上一集 / 下一集 |
| Ctrl+Alt+Shift+I | 沉浸模式 |
| Ctrl+Alt+D | 全屏弹幕开关 |
| Ctrl+Alt+H | 隐藏 / 恢复 |
| Ctrl+Alt+P | 鼠标穿透 |
| Ctrl+Alt+F10 | 紧急恢复：解除穿透、沉浸与挖孔 |
若紧急恢复键被其他软件占用，会改用 Ctrl+Alt+Shift+F10，以侧栏和设置窗口显示的实际组合为准；两组均不可用时禁止启用穿透。播放器需要登录时，请在网页中自行登录，工具不绕过网站限制。
普通热键可以在设置中点击输入框后直接按下组合键录制，也支持两个鼠标侧键 Mouse4 / Mouse5（可单独使用或组合 Ctrl、Alt、Shift）。录制侧键时鼠标留在设置窗口内即可。Esc 取消当前录制，保存后生效。录制期间普通全局热键临时释放，离开输入框或关闭设置后恢复；紧急恢复键始终保留。配置过的侧键会拦截其默认前进/后退行为，未绑定的按钮和其他鼠标输入照常传递；驱动若把侧键映射为键盘键，按实际键盘组合录制。
启用穿透后用热键或托盘恢复。沉浸模式隐藏工具栏，以热键退出，并保持鼠标箭头可见。视频原生进度条在鼠标静止 1.8 秒后隐藏，移动、点击或按键时显示，拖动期间不隐藏；退出沉浸恢复原有控件状态。网页自定义播放器不会被额外加上原生进度条。字幕延迟正值代表推迟显示，负值代表提前显示。战斗暂停和淡化基于字幕词语，默认关闭。
沉浸小窗左上角的拖动图标直接移动小窗，贴近屏幕边缘不会进入 Windows 的原生贴靠拖窗流程，保留手动缩放。普通窗口标题栏仍按原方式拖动；不修改系统全局分屏设置，也不拦截用户主动使用的 Windows 分屏快捷键。
设置中的“沉浸小窗”可调小窗透明度（0% 至 80%）、开关“鼠标 X 光”并调整圆形半径（20 至 200 DIP，默认 70）。点击保存后生效，重启保留；普通窗口继续使用原有不透明度。X 光在鼠标所在视频区域形成圆形透明孔，中心完全透明、外沿柔和羽化，离开后恢复；只渐变透明度，不模糊视频。羽化位于原半径内，无需重新设置。拖动手柄、缩放边缘和底边进度保持可操作。透明孔中的输入可落到下方应用，因此下方游戏的光标策略也可能影响指针。
字幕与方向浮窗默认不出现在 Windows 的 Alt+Tab 切换列表中。设置 → 沉浸小窗中的“在 Alt+Tab 中隐藏沉浸小窗”默认开启，保存后生效并在重启保留；关闭可恢复小窗的切换入口。开启时也移除小窗任务栏按钮，仍可通过原有“隐藏 / 恢复”热键或托盘找回；退出沉浸后，普通主窗口恢复 Alt+Tab 和任务栏入口。
沉浸小窗底边常驻 3 DIP 细进度线，绿色前缀表示当前已播位置，深色为剩余部分；点击或拖动可跳转，悬停显示目标时间。它表示当前位置，不统计所有曾经观看过的区间。较大的网页原生控件仍按原规则自动隐藏。设置中的“隐藏 / 恢复”使用你的既有热键，再按一次原样恢复小窗，不退出沉浸或重新加载网页；托盘紧急恢复则退出沉浸并解除穿透。
标题栏横线按钮用于最小化，保留任务栏入口；旁边的向下收起图标用于“隐藏到托盘”，悬停可查看名称。托盘双击、托盘“恢复窗口”或隐藏/恢复热键可找回窗口；最小化前的正常/最大化状态会保留。最小化和隐藏不主动发送暂停命令，但后台播放受网站及浏览器策略影响，可能自动暂停。字幕浮窗暂时随主窗隐藏，恢复后按原开关重新显示。
“窗口”里的置顶模式提供“不置顶、沉浸置顶、始终置顶”。沉浸置顶只在沉浸模式生效，退出沉浸或紧急恢复后解除置顶；普通窗口和最大化不置顶。选择立即生效并保存，重启保留；旧版勾选置顶对应“始终置顶”，未勾选对应“不置顶”，不改变其他设置。字幕浮窗仍使用独立置顶策略。
普通窗口、最大化、网页聚焦及 iframe 同样保护鼠标可见：播放器请求隐藏指针时，在浏览器控件边界改为箭头；普通模式保留链接手型、文本输入和缩放指针。不改写普通网页的光标 CSS，也不强制覆盖其他窗口的鼠标。
临时倍速默认 2x，按住达到 400 毫秒后才触发，可在设置修改倍速及长按触发时间（100 至 2000 毫秒）。它可以与一个普通操作共用同一按键或侧键。例如快进与临时倍速都设为 Mouse5：短按松开快进，长按只触发倍速，松开恢复原倍速，不再快进。两个普通操作仍不能共用。单独设置临时倍速时，短按不触发任何动作。
临时倍速不覆盖原有倍速、收藏或历史。切换前台、导航、紧急恢复及更改热键也会结束临时倍速，取消待判定的短按不补发动作。新增热键若与已有用户组合相撞，配置迁移优先保留用户组合并给新增操作分配备用键；以设置中实际显示为准。
分集支持 B 站新版视频选集（video-pod 分 P）及旧版列表，沉浸或列表折叠时仍可切换；也支持 YouTube 站点选择器和通用 rel=next/prev 页面入口。首末集不循环跳转。网站 DOM 或权限变化仍可能导致不可用，不保证所有站点自动识别。
进入 B 站视频的沉浸模式后，已有弹幕会铺满小窗所在的整块屏幕。弹幕层透明、始终鼠标穿透，不抢焦点；滚动、顶部、底部和反向弹幕跟随视频暂停与倍速，跳转、切集或换页会清理旧弹幕。隐藏、最小化和退出沉浸会收起弹幕层。设置中的“B 站全屏弹幕”默认开启，保存后生效并保留到下次启动；仍需打开 B 站自身的弹幕开关。默认 Ctrl+Alt+D 可随时切换随引全屏弹幕开关，状态立即保存；可在“全局热键 → 全屏弹幕开关”录制键盘组合或鼠标侧键，保存后生效。快捷键只控制随引弹幕层，仍沿用 B 站自身开关；普通模式下切换只更新偏好，不进入沉浸。旧资料如已占用默认组合，会保留原操作并为新增热键分配备用组合。“全屏弹幕”设置可调整显示区域（屏幕顶部 10% 至 100%，包含底部固定弹幕）、不透明度（0% 至 100%）、字号（50% 至 200%）和速度（0.5x 至 2x，1x 为适中）。速度同时影响滚动弹幕移动和固定弹幕停留时间，叠加视频播放倍速；不透明度独立于小窗透明度。点击保存后生效，重启保留；旧资料缺少这些字段时保持原有全屏、字号、速度和不透明度。当前适配 B 站网页播放器的普通文字弹幕，沿用播放器已筛选的显示结果，高级脚本与特效不搬到桌面。
沉浸小窗左上角会短暂显示热键操作提示，例如“快进5s”“暂停”“播放”及当前倍速；跳转秒数沿用你的设置，连续操作更新提示，约 1.4 秒后收起。左上角拖动按钮平时隐藏，鼠标进入小窗后显示、离开后隐藏，拖动期间保持可见；提示会避开按钮，也不会拦截鼠标操作。
仅接入 B 站，扩展与本机组件随发布包提供。首次注册、扩展加载、配对和导入都需要用户明确授权；不复制整个 Chrome 配置，不读取其他站点或密码，不开放调试端口。组件已用合成数据跑通，真实账号导入尚未验收。步骤见 Chrome 接入说明。
已实现原神与终末地攻略的小地图玩家箭头识别、ROI 框选校准、北向校准、离线方向时间轴与播放同步。校准窗口选择“游戏”：原神识别青色箭头，终末地识别带黄色光晕的白色箭头。游戏类型与选区一起保存；旧校准仍沿用原神，不自动修改已有资料。打开本地视频后，在“视觉”页选择“校准并分析本地视频”；画面中拖动框选箭头并保留边距，也可选择作者放大小地图预设。暂停与跳转按视频时间重算方向；未识别时不保持旧方向。小地图旋转时取消“地图北向固定”，只输出画面角度。
校准选区可在框内拖动移动，拖动四角或四边中点调整大小，框外拖动重新框选；缩放时保持正方形，调整点在小尺寸预览中仍保持可点击大小。Esc 取消本次拖动，失焦或丢失鼠标捕获会恢复拖动前选区。选区不会越出视频范围，松开后更新识别结果；只有保存并启用或完成本地分析才应用新校准。
在线视频：打开 B 站等 HTML5 攻略视频，在箭头清晰可见时选择“视觉 → 校准在线视频”，框选玩家箭头并点击“保存并启用”，然后继续播放。每 0.5 秒识别当前画面，不需要下载整段视频或安装 FFmpeg；支持跨域视频及嵌套 iframe。优先读取视频帧，受跨域限制时捕获 WebView2 当前显示的播放器画面。后者在小窗过小、箭头被遮挡或播放器不完整时可能无法识别，请适当放大。隐藏、最小化时暂停采样并清空方向，恢复后继续；跳转、切集、导航和未识别帧不会保留旧箭头。选区和北向参数长期保存，切集、换网址、清晰度变化、刷新和重启均沿用原选区；分辨率变化时按比例保留位置与大小。只有手动校准并点击“保存并启用”才更新选区，取消校准不改变已保存内容。旧资料自动沿用最近使用的已有校准，不重置其他设置。通过“跟随 → 字幕与方向浮窗”可在游戏前台显示提示。
字幕与方向浮窗将方向和来源放在同一行，字幕使用下方的完整宽度自然换行；没有字幕时收紧高度。可以调整浮窗宽度，位置与宽度继续保存。长字幕限制显示高度并可滚动查看。
箭头识别在原高亮轮廓无法判断时，继续检查较暗的青色轮廓并匹配箭头形状，减少小窗缩放、压缩和亮度变化造成的漏识别。仍需要尾部与候选方向相符；被图标遮挡、画面太小或角度有歧义时继续显示未识别，不沿用旧方向。更新不会改变已保存的选区和北向参数。
使用 OpenCvSharp/OpenCV 在本机处理，没有上传视频或调用付费模型。OpenCV Windows 运行库随发布包提供；分析时需要已有的 FFmpeg 与相邻 ffprobe，找不到时可选择已安装的 ffmpeg.exe。离线分析需另行准备 FFmpeg/ffprobe；在线视频识别不需要这些工具。缓存依据视频路径、大小和修改时间保存，移动或替换文件后需重新分析。已用用户提供的 1080p AV1 攻略完整验证；检出覆盖率不等于准确率。
实机朝向、相机/角色方向分离、地图坐标、路线匹配、OCR 和视觉战斗检测仍未实现，仍需对应实机样本。范围和验收边界见 原神视觉说明 与 终末地适配说明。
dotnet build src/GuideMate.App/GuideMate.App.csproj -c Release
dotnet run --project tests/GuideMate.Specs/GuideMate.Specs.csproj -c Release
node tests/chrome.spec.cjs
node tests/bridge-subtitles.spec.cjs
node tests/bridge-danmaku.spec.cjs
dotnet run --project tests/GuideMate.Vision.Specs/GuideMate.Vision.Specs.csproj -c Release
./scripts/Publish-GuideMate.ps1未选择其他目录时，设置与网页数据保存在 %LOCALAPPDATA%\GuideMate。正式启动使用 --data-dir 路径 后，会将该选择记在 %LOCALAPPDATA%\GuideMate\active-profile.json；以后双击启动脚本或直接运行新版程序都继续使用原目录。热键在该目录的 settings.json，网页登录资料在 WebView2 子目录；发布只更新程序，不复制或清除用户资料。如果已记住的目录不可用，会报错，不静默创建空白资料。源码仓库和发布 ZIP 均不包含任何个人资料目录。
--media 视频路径 可直接打开指定的本地视频，不改变默认打开 B 站的行为。--isolated 使用独立资料目录且不改变正式目录选择，未传 --data-dir 时分配新的临时目录；历史冒烟与在线探针已从正式程序移除。仅构建或发布不会重置热键与账号记录。
详细架构、范围、视觉研究条件及验收标准见 实现文档，构建与验证见 测试说明。方向提示可来自字幕规则或本地攻略箭头图像识别，不宣称具备实机 AI 导航、绝对坐标或路线匹配。
参与开发请阅读 贡献指南，特别是资料保留、共用短按/长按及测试隔离要求。
Windows CI 执行构建与命令行回归并生成可下载的 workflow artifact。推送版本标签后，发布工作流生成 ZIP、SHA256 和 GitHub Release 草稿；人工验收后再公开。可运行 ./scripts/Package-GuideMate.ps1 -Version v0.1.0 在独立目录打包，版本号按实际发布版本填写。
项目原创代码采用 MIT 许可证，依赖及素材说明见 第三方声明。问题报告请使用仓库 Issue 模板；涉及账号或安全边界的问题参见 安全说明。
旧 --smoke-test 参数继续作为隔离模式兼容入口，避免旧测试命令访问正式资料；它不再自动执行检查或退出。