悬浮阅读层（Transparent Reader）
把任意网页变成一层只有文字、没有背景的悬浮窗，盖在其它窗口之上。适合低调地看新闻、刷题、读长文。
应用源码内嵌在本技能包的 assets/app/ 里（约 144KB，10 个文本文件），安装时直接从包内复制到本机，不访问 GitHub、不需要代理。唯一的网络下载是 Electron 运行时（约 270MB），走国内镜像 npmmirror。
需要逐行审阅或提建议：<https://github.com/ang985/transparent-reader>
何时使用
- 用户说"把网页背景变透明""只想看文字""悬浮在浏览器上""不太显眼地刷题"
- 用户想装一个不占任务栏、能随手收起的小阅读窗
- 用户已经有这个应用，问怎么启动、怎么关、快捷键是什么
不适用：macOS / Linux（启动脚本与透明化辅助都是 Windows 专用）；也不需要给普通网页截图或做 OCR。
前置条件
| 依赖 | 要求 | 检查方式 |
|---|---|---|
| 系统 | Windows 10 / 11 | — |
| Python | 3.8+（跑本技能的脚本） | python --version |
| Node.js | ≥ 18（含 npm，用于装 Electron） | node -v |
| 磁盘 | 约 330MB（Electron 运行时占绝大部分） | — |
| 网络 | 仅需访问 registry.npmmirror.com（国内镜像） |
安装时自动走 |
Python 和 Node.js 缺一不可：脚本是 .py，运行时靠 Node 装依赖。缺 Node 时提示用户到 <https://nodejs.org> 装 LTS 版，不要尝试静默安装；缺 Python 时让用户装 Python 3，或改用 py 命令重试。
三步操作
1. 安装
python scripts/setup.py
脚本依次做五件事，前四步纯本地：
- 校验包内源码完整性（
assets/app/下 10 个文件） - 复制源码到
%LOCALAPPDATA%\TransparentReader\app - 生成
icon.ico（用 Python 标准库现场绘制，所以技能包里不需要携带二进制） npm install装 Electron 运行时，走 npmmirror 镜像；装完校验electron.exe是否存在- 在桌面创建「悬浮阅读层」图标，之后双击即可启动
首次约 1–3 分钟（大头是 270MB 运行时）。重复执行只覆盖源码，不会重装依赖。
桌面图标默认创建，不需要时加 --no-shortcut。它指向 electron.exe 并带上应用目录参数，图标用第 3 步生成的 icon.ico。桌面若被 OneDrive 或自定义盘符重定向（例如 D:\桌面），脚本读的是系统真实桌面路径，不会误写到 %USERPROFILE%\Desktop。创建失败只提示、不影响安装，会同时打印手动创建的办法。
--dir D:\apps\reader 可改安装位置。
2. 启动
python scripts/launch.py start
也可以直接双击桌面上的「悬浮阅读层」图标，不需要经过 agent。
启动后屏幕上只出现控制面板（500×765 的小窗口，不是阅读层）。确认或改一下网址，点「打开」/ 回车，才会出现那个透明阅读层；上次的网址已经自动填在输入框里。
阅读层不占任务栏，顶部有一条 30px 的工具条，靠工具条右侧按钮或托盘图标操作。
3. 查看状态 / 退出
python scripts/launch.py status # 是否在运行、装在哪里、版本对不对
python scripts/launch.py quit # 优雅退出（会保存当前页面）
python scripts/launch.py sync # 只同步源码（技能更新过、又不想启动时用）
quit 走应用自带的 --vr-quit 参数，先保存状态再退出，不会留下脏进程。
4. 技能更新后怎么让应用也用上新版
SkillHub 上更新技能，不会自动替换本机应用目录里的源码——那是两份东西。所以启动脚本里做了版本对齐：
setup.py安装完会在安装目录写一个.vr-install.json记下版本号launch.py start每次启动前拿它跟本技能包SKILL.md里的version比- 一致 → 直接启动
- 不一致 → 先把
assets/app/的源码同步过去（跳过node_modules，不重装依赖），
若是运行中还会先优雅退出再重启，然后正常启动 - 想跳过同步：
python scripts/launch.py start --no-sync
也就是说：用户点了技能卡上的「更新」，之后双击桌面图标就自动是新版，不需要记得重跑 setup.py。
只有依赖本身要变（package.json 里 Electron 大版本升级）时，才需要 python scripts/setup.py --reinstall。
怎么用（讲给用户听的部分）
| 操作 | 方式 |
|---|---|
| 启动 | 双击桌面「悬浮阅读层」图标，或 python scripts/launch.py start（只会弹出控制面板） |
| 收起成小胶囊 | 工具条上的 —，或按 Alt+Q；再按 Alt+Q 展开 |
| 唤出控制面板 | 阅读层或胶囊上按 Alt+P（面板被切走后不用找窗口） |
| 技能更新后 | 双击图标即可，启动脚本会自动把源码同步到最新（也可 launch.py sync） |
| 就地调浓度 | Alt + 滚轮（上滚更浓、下滚更淡） |
| 临时穿透 | Alt+T：鼠标直接点到下层窗口，再按一次 Alt+T 退出（右上角有红色提示） |
| 按站点记忆 | 每个网站自动记住自己的浓度和缩放，切回来自动恢复；面板显示“已单独记住 xxx”，可点“不用记住”取消 |
| 深色页面 | 打开深色站点会自动换深色蒙版（浅色字），浓度最低 55%；面板「显示」里有「蒙版跟随页面 / 强制浅色 / 强制深色」三选一 |
| 打开阅读层 | 控制面板里点「打开」或按回车；上次网址已预填 |
| 换页面 | 在控制面板填新网址点「打开」，会在同一个窗口里跳转；Alt+← / Alt+→ 后退前进 |
| 调背景浓度 | 工具条 ⋯ 打开控制面板，拖浓度滑块 |
| 页面缩放 | Ctrl + 滚轮（工具条不会跟着放大） |
| 重新叫回窗口 | 被别的窗口盖住时，托盘右键 →「把浮层提到最前」 |
| 退出 | 托盘右键 →「退出程序」 |
使用约束
- 阅读层是悬浮窗，不会替代浏览器。需要登录、上传附件的操作建议仍在浏览器里做。
- 应用把窗口尺寸、上次的网址存在本地
%APPDATA%\transparent-reader，不联网、不上传。 - 不要擅自替用户改
state.json；当前页面与窗口位置由应用自己维护。 - 不要修改
assets/app/下的源码；需要改应用请到 GitHub 仓库提交，再用项目目录里的sync-assets.py同步回包里（该脚本不在包内）。
卸载
按用户确认后执行，两处都要删：
%LOCALAPPDATA%\TransparentReader\ ← 程序本体，约 330MB
%APPDATA%\transparent-reader\ ← 上次的网址与窗口状态
桌面快捷方式（如果建过）：%USERPROFILE%\Desktop\悬浮阅读层.lnk。删之前先 launch.py quit，否则文件被占用。
出问题时
先看 references/troubleshooting.md，覆盖：npm 安装慢或失败、Node 版本过低、Electron 二进制没落地、窗口黑屏或全透明不可见、Alt+Q 无反应、胶囊跑到屏幕外。
若用户报告的现象不在其中，收集：Windows 版本、python --version、node -v、安装目录是否存在、控制台报错原文，再判断。
