支持的平台
目前支持 macOS 或 Linux 上的 Google Chrome。虽然上游 CLI 有 Windows 版本，本项目的 Native Messaging 安装器尚不支持 Windows。
可选本地 AI · 安装指南
用本地 Real-ESRGAN 高清放大网页图片
让 Click Image Zoom 使用你设备上的 Real-ESRGAN。一次安装本地助手，之后 AI 会自动优先尝试它，再回退到浏览器 AI。
本地处理路径如何工作
插件先从来源网站获取原图。触发 AI 清晰时，Chrome 通过 Native Messaging 将图片交给已安装的本地助手。
Chrome 插件
选择图片，触发 AI 清晰
本地助手
Chrome Native Messaging · Python
Real-ESRGAN CLI
本地模型推理 · 4 倍输出
原生路径的结果会回到查看器。本地助手未安装或失败时，插件会尝试基于 LiteRT/WebGPU 的浏览器 AI；仍不可用时改用 Lanczos 快速清晰。图片像素不会上传到云端 AI 服务。
安装前需要准备什么
本地助手是可选的。免费的图片查看器、10 倍缩放和拖动查看都不需要它。原生 AI 固定输出 4 倍结果，无法恢复原图中不存在的文字或信息。
Python 与本地文件
安装器直接调用 /usr/bin/python3，助手还需要 PATH 能找到 python3。两者都应可用；仅使用 Python 标准库，不需要安装 pip 包。CLI 与 .param/.bin 模型文件应保存在长期保留的本地目录。
设备条件
选择与操作系统和 GPU 兼容的上游 CLI。处理时间、内存占用和模型可用性因设备而异。
四步安装并连接
使用你实际安装的插件 ID 和本地绝对路径。
安装插件并复制真实 ID
从 Chrome 应用商店添加 Click Image Zoom。打开
chrome://extensions，开启开发者模式，复制 Click Image Zoom 卡片上显示的 ID。开发用未打包插件也应使用它实际显示的 ID。下载 CLI 与模型文件
从 Real-ESRGAN-ncnn-vulkan 官方发布页下载适合操作系统的压缩包并解压。模型目录必须包含
realesrgan-x4plus.param和realesrgan-x4plus.bin。速度优先模型还需realesr-general-x4v3.param与realesr-general-x4v3.bin成对文件。模型背景可查看 Real-ESRGAN 官方项目。向 Chrome 注册本地助手
分别下载 install.sh 和 host.py，保留这两个原文件名，放进同一个名为
native-host的文件夹。在该文件夹的上一级目录打开终端。已有完整项目源码时，从项目根目录执行以下命令。把占位值替换为真实插件 ID、CLI 与模型目录的绝对路径；路径含空格时保留引号。chmod +x native-host/install.sh ./native-host/install.sh EXTENSION_ID "/absolute/path/to/realesrgan-ncnn-vulkan" "/absolute/path/to/models"安装器会复制助手，并为这个插件 ID 注册 com.image_zoom.esrgan，记录 CLI 与模型路径。请保留原来的 CLI 和模型文件位置；目前只注册 Google Chrome。
重启 Chrome，触发 AI 清晰
完全退出 Chrome 后重新打开，再刷新网页。在插件弹窗的“放大图片画质”中选择 AI 清晰，选择速度优先或画质优先，将触发时机设为首次放大或打开图片。默认是速度优先与首次放大。按住快捷键点击网页图片，使用默认触发时机时再滚轮放大。本地助手会自动优先尝试。
弹窗选项对应哪个本地模型
| 弹窗选项 | 本地 CLI 模型 | 所需文件 |
|---|---|---|
| 速度优先（默认） | realesr-general-x4v3 | realesr-general-x4v3.param + .bin |
| 画质优先 | realesrgan-x4plus | realesrgan-x4plus.param + .bin |
两种本地模式都输出 4 倍结果。速度优先模型缺失时，助手会使用已有的 x4plus 文件。即使选择速度优先，安装器也要求 x4plus 文件齐全。选项用于选择模型，实际速度与画质取决于图片和设备。
FAQ
安装问题与排障
怎么确认本地助手运行了？
弹窗没有“已连接”状态。需要诊断时，在网页的 DevTools Console 筛选 [ImageZoom][enhancement]。出现 native_cli_fallback 表示原生尝试失败；成功出现 upscale_request_applied，且没有原生回退或浏览器的 ai_upscale_start，可作为原生路径完成的证据。
本地助手不可用时先检查什么？
核对真实插件 ID、CLI 可执行文件绝对路径、/usr/bin/python3 和模型目录。确认两份助手文件都已下载，文件名没有变化；安装后完全退出并重开 Chrome。插件 ID 或 CLI/模型路径变化时，用新值重新运行安装器。普通图片查看器仍可使用。
安装器提示缺少模型文件怎么办？
传入包含 realesrgan-x4plus.param 与 realesrgan-x4plus.bin 的绝对路径目录。显式第三个参数可避免依赖当前工作目录。速度优先还会在可用时使用 realesr-general-x4v3 成对文件。
能直接接入任意 RealESRNet 或 .pth 模型吗？
当前接入的是 Real-ESRGAN 的 NCNN/Vulkan CLI，使用它支持的 .param/.bin 成对文件，不能直接接入任意 RealESRNet 文件或 PyTorch .pth 检查点。
浏览器 AI 已经被移除了吗？
没有。本地助手失败后，插件仍会尝试 LiteRT/WebGPU 的浏览器 Real-ESRGAN 路径，它依赖浏览器、GPU 支持和模型加载。浏览器 AI 也不可用时改用 Lanczos 快速清晰；也可以直接在弹窗选择“快速清晰”或“仅缩放”。
图片始终不离开浏览器吗？
原生路径会把像素交给同一设备上 Chrome 之外的本地进程。助手运行 CLI 时写入临时输入与输出文件，结束后删除临时目录。原图可能从来源网站获取，但增强不会上传到云端 AI 服务。
Windows 能用本地助手吗？
上游 CLI 提供 Windows 版本，但本项目的安装器目前只为 macOS 和 Linux 注册 Chrome 助手。仅下载 Windows CLI 不会自动与插件连接。