# Xiaoer Upscale

> 在 Mac 上把图片本地放大/提清晰度(超分辨率),并装好「Finder 右键 → 快速操作 → 超分 4K/8K」。 USE WHEN 用户说 图片放大、超分、提清晰度、图糊了、做高清版、把这张图变清楚、 4K/8K 图、image upscale、super resolution、右键放大图片、Mac 右键超分。 纯本地离线、不用 API key、不花钱(OpenCV dnn_superres,CPU 即可)。

- Skill: `jane-xiaoer/xiaoer-upscale` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add jane-xiaoer/xiaoer-upscale`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jane-xiaoer/xiaoer-upscale/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: jane-xiaoer (https://skillmd.com/u/jane-xiaoer)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/jane-xiaoer/xiaoer-upscale

---


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

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

## 一键安装

```bash
bash scripts/install.sh
```

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

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

## 命令行用法

```bash
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` — 模型来源与直链