| name | macvision |
|---|---|
| description | Use local macOS macvision CLI (Apple Vision.framework) for OCR, image classify, and saliency when the model cannot see images. Trigger for screenshot/OCR/读图/看不清图/classify image/显著性/热力图, or when a no-vision model needs to understand a local image or clipboard screenshot. |
macvision
本地、免费、不上云。用 macvision 把图变成 JSON/文本，再交给当前模型推理。
不要默认把截图上传给云端 vision API；本机 Vision 能解决的先走本 skill。
权威中文文档：README.cn.md
硬性前置：二进制安装（必须强调）
本 skill 依赖本机二进制 macvision。没有它就先装，装好再干活。
推荐 PATH 约定
把二进制放到用户 PATH 目录（二选一或两个都放）：
| 路径 | 说明 |
|---|---|
$HOME/.local/bin/macvision | 推荐；确保该目录在 PATH 中 |
$HOME/bin/macvision | 备用；~/.zshrc 应有 export PATH="$HOME/bin:$PATH" |
启动前自检：
command -v macvision || ls "$HOME/.local/bin/macvision" "$HOME/bin/macvision"
macvision --version
macvision doctor # 需要 "ok": true
doctor 失败或找不到命令 → 停止任务，按下面安装，不要改用云端 OCR 凑合。
如何安装二进制（推荐顺序）
1. 直接下载 GitHub Release（推荐，可靠）
上游 brew formula 可能缺失/不可用；以 Release 二进制为准：
mkdir -p "$HOME/.local/bin" "$HOME/bin"
curl -fsSL -o /tmp/macvision-darwin-universal.tar.xz \
https://github.com/ljh-sh/macvision/releases/latest/download/macvision-darwin-universal.tar.xz
rm -rf /tmp/macvision-extract && mkdir -p /tmp/macvision-extract
tar -xJf /tmp/macvision-darwin-universal.tar.xz -C /tmp/macvision-extract
BIN="$(find /tmp/macvision-extract -type f -name macvision | head -1)"
install -m 755 "$BIN" "$HOME/.local/bin/macvision"
install -m 755 "$BIN" "$HOME/bin/macvision"
hash -r
macvision --version
macvision doctor
- 包是 universal（arm64 + x86_64）
- 需要 macOS 13+（本机实测 26.x 可用）
- 首次截屏/剪贴板可能要系统权限：屏幕录制 / 辅助功能
2. Homebrew（上游文档写法；若失败立刻回退到步骤 1）
brew install ljh-sh/cli/macvision
# 或
brew tap ljh-sh/cli && brew install macvision
若 Error: No available formula / tap 需 trust → 不要死磕 brew，改用步骤 1。
3. 源码构建（仅上面都失败时）
git clone https://github.com/ljh-sh/macvision
cd macvision && swift build -c release
# 把 .build/release/macvision 装到 PATH 目录
何时使用
- 当前模型看不到图 / 没有 vision，但用户给了图片路径、截图、剪贴板图
- 用户要 OCR、读截图文字、中英混合界面文字
- 用户要「这张图是什么」→
classify - 用户要「画面重点在哪 / 显著性」→
salient - Agent 循环：
截图 → 读图 → 推理（省 LLM vision 费用、保隐私）
核心能力（本 skill 范围）
只把这三类当一等公民；其它子命令可响应，但不要主动展开。
1. ocr — 读文字（默认首选）
# 文件（agent 优先要 JSON）
macvision ocr /path/to/image.png --json --lang zh-Hans,en-US
# 只要纯文本
macvision ocr /path/to/image.png --text --lang zh-Hans,en-US
# 剪贴板 / 现截屏（若 CLI 支持）
macvision ocr --clipboard --json --lang zh-Hans,en-US
输出要点：
- 检查 JSON 里
"ok": true texts[].text/bbox/confidence；bbox为[x,y,w,h]，原点左上角- 默认也可 TSV；给模型推理时优先
--json或--text
无现成文件时先截屏再 OCR：
SHOT="/tmp/macvision-$(date +%Y%m%d-%H%M%S).png"
screencapture -x "$SHOT" # 或 -i 交互选区
macvision ocr "$SHOT" --json --lang zh-Hans,en-US
2. classify — 这是啥
macvision classify /path/to/image.jpg --top 5
macvision classify /path/to/image.jpg --top 5 --min-confidence 0.3
# 动物场景可选
macvision classify /path/to/image.jpg --animals --top 5
用 labels[].name + confidence 向用户说明；弱标签别装作很确定。
3. salient — 显著性 / 该看哪里
macvision salient /path/to/photo.jpg --output /tmp/macvision-salient-heat.png
macvision salient /path/to/photo.jpg --mode objectness --output /tmp/macvision-salient-obj.png
- 默认 attention 热力图；
--mode objectness偏物体区域 - 热力图路径用绝对路径回传；需要时再对原图做 OCR
标准工作流（无视觉模型）
- 确认
macvision在 PATH 且doctorok - 拿到图像：用户路径 / 剪贴板 /
screencapture - 按需调用：
- 要读字 →
ocr --json --lang zh-Hans,en-US - 要懂场景 →
classify --top 5 - 要找焦点 →
salient --output ...
- 要读字 →
- 只把结构化结果（文字、标签、热力图路径）带进推理，不要臆造图中内容
- 向用户报告时区分：Vision 读到的事实 vs 你的推断
其它子命令（简单接受，不主动扩展）
用户明确点名时可以跑；本 skill 不为它们写长流程：
| 命令 | 一句话 |
|---|---|
detect | 人脸 / 条码 / 矩形等检测 |
document | 文档轮廓 |
feature | 图像指纹 / 相似度 |
humans / pose / face-landmarks | 人 / 姿态 / 五官 |
doctor / daemon | 诊断 / FIFO 常驻 |
后续按真实使用再补全对应小节。
失败处理
command not found→ 按「硬性前置」安装到 PATH，再重试"ok": false/ 空texts→ 换--lang、提高截图清晰度、或改用选区截屏；仍失败再如实说读不到- 权限弹窗 → 提示用户开「屏幕录制」等系统权限
- 禁止：静默改用云端 vision 冒充本机结果