Xiaoer Upscale

小耳超分 · Mac 本地图片超分 + 右键 4K/8K

把"图片放大/提清晰度"做成两种入口:命令行 upscale + Finder 右键。 引擎 = OpenCV dnn_superres,在 CPU 上跑,不调任何 AI API、不用 key、不联网(装完拔网也能用)。唯一联网 = 安装时下 3 个模型(~41MB)。

一键安装

bash scripts/install.sh

装完得到:

• 命令行:upscale 图片.jpg --8k(别名 超分)
• 右键:选图片 → 右键 → 快速操作 → 超分 4K / 8K / 极速4K(后台跑、完成弹通知、不卡 Finder)

安装脚本做了 5 件事:建 venv 装 opencv-contrib-python+Pillow → 下 3 个模型 → 生成 CLI 壳 → 生成 3 个右键 .workflow → pbs -flush 注册。全用 $HOME,不写死用户名,别人照装即可。

命令行用法

upscale 图.jpg              # 默认满血 4x
upscale 图.jpg --4k         # 目标长边 3840
upscale 图.jpg --8k         # 目标长边 7680
upscale 图.jpg --16k        # 目标长边 15360(源不够大时为插值,非真细节)
upscale 图.jpg --long 5000  # 自定义长边
upscale 图.jpg --scale 2    # 相对原图 2 倍
upscale 图.jpg --model edsr # 换模型(默认 lapsrn)

输出 原名_档次.jpg 存到同目录,带轻度 unsharp 锐化。

三档模型(速度 / 质量 · CPU 无 GPU)

| 模型 | 右键档 | 速度(2K 源) | 质量 | 用途 | |------|--------|------------|------|------| | fsrcnn | 极速4K | ~0.5s | 稍软 | 快速预览 / 批量 | | lapsrn | 4K / 8K | ~6 分钟 | 好 | 出片默认 | | edsr | (仅 CLI) | ~8 分钟+ | 最好 | 极致质量少用,大图可能上小时/OOM |

关键认知:模型是 4x,真实细节上限 = 源图长边 ×4。2K 源 → 4K/8K 是真提升;16K 基本是插值(源撑不起)。源本身 4-5K 才谈得上真 16K。

右键设置 & 排障(别人在新 Mac 上最容易卡这里)

1. 右键没出现「超分」菜单项 → 系统设置(System Settings)→ 搜「扩展 / Extensions」或「访达 / Finder」→ 在"添加的扩展 / 访达"里勾上 超分 4K / 8K / 极速4K。装完 pbs -flush 一般会自动出现,这是兜底。(旧版 macOS:系统偏好设置 → 扩展 → 访达扩展。)
2. 菜单项藏在哪 → 选中图片右键 →「快速操作 / Quick Actions」子菜单里(条目多时会折叠进这里,不在最外层)。
3. 完成通知没弹 → 系统设置 → 通知 → 允许「脚本编辑器 / Automator」发通知(右键用 osascript 弹通知,首次可能要手动允许一次)。
4. 拷贝来的 .workflow 点了没反应(quarantine 隔离) → 本 skill 的 install.sh 是本地生成 workflow、不带隔离属性,无此问题;若手动拷了下载来的,执行 xattr -dr com.apple.quarantine "xxx.workflow"。
5. 命令行 upscale 找不到 → ~/.local/bin 不在 PATH。加:echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc。(右键不受 PATH 影响。)

边界(重要)

• 只处理图片,不处理视频。CPU 上逐帧超分不现实(lapsrn ~6min/帧 → 10s 片要 25 小时)。视频超分请走 GPU 方案(Real-ESRGAN / Topaz Video AI),不是这个工具。
• 需要 GPU 加速版超分(Real-ESRGAN 等)是另一条路,本工具专注"零依赖、人人能装、CPU 即可"。

模型来源

三个模型是 OpenCV dnn_superres 官方预训练权重,来自 GitHub(可重下)。直链、大小校验、逐个说明见 references/models.md。install.sh 会自动下载,一般不用手动碰。

文件

• scripts/install.sh — 一键安装(入口)
• scripts/upscale.py — 超分引擎(OpenCV dnn_superres)
• scripts/qa_run.sh / qa_worker.sh — 右键的后台跑 + 通知粘合层
• scripts/gen_quickactions.sh — 生成 3 个 Finder 右键 .workflow
• references/models.md — 模型来源与直链

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Jane-xiaoer
• Source: Jane-xiaoer/claude-skill-xiaoer-upscale
• License: MIT

Install and usage instructions live in the source repository linked above.