Localmac AI OCR
概览
这个 skill 用来协同两个现成命令行工具：
scripts/gui负责窗口激活、截图、坐标点击、键盘输入scripts/ocr负责调用 AI Studio OCR 输出文字、分数、坐标框，并支持按文本查找和点击
优先使用云端 aistudio-ocr。除非用户明确要求，不要回退到本地 Paddle，以免慢且占用内存。
不要把真实的 API key、token、api url 写进 skill、脚本调用示例或仓库文件。统一要求从环境变量或命令参数读取。
这个 skill 自带可执行脚本，安装后不依赖业务仓库本身。当前说明默认命令从 skill 根目录执行即可。
可执行入口在：
scripts/ocr
scripts/gui首次安装建议运行：
scripts/setup.sh何时使用
- 用户要你操作本机 GUI、RDP 窗口或桌面 App
- 需要从截图中提取中文文本和坐标框
- 需要“先截图，再识别，再按文字点击”
- 需要验证 OCR 速度、完整输出、命中框、标注图
- 需要在行情软件、表格界面、按钮密集界面里精确找字
不要在这些场景优先使用网页抓取或 DOM 自动化；先判断是不是桌面/RDP 界面。
工作流
1. 先确认命令入口
先确认脚本入口可执行：
test -x scripts/ocr
test -x scripts/gui如果当前目录不是 skill 根目录，先切到包含 scripts/ 的目录再继续。不要在 skill、提交内容或对外说明里暴露用户本地目录名。
2. 先安装最小依赖
推荐直接运行自带安装脚本：
scripts/setup.sh如果需要手动安装，再执行下面这些命令：
cd scripts
uv sync3. 先配置必填项
这个 skill 的云端 OCR 有两个必填配置：
AISTUDIO_OCR_API_URLAISTUDIO_OCR_TOKEN
推荐方式：
cp scripts/.env.example scripts/.env然后编辑 scripts/.env，填入真实值。不要把 .env 提交回仓库。
也可以临时用环境变量传入，但仍然不要把真实值写进脚本、skill 或提交记录。
4. 先做环境体检
先确认 OCR token 和 GUI 依赖，再做截图或点击：
AISTUDIO_OCR_API_URL="$AISTUDIO_OCR_API_URL" AISTUDIO_OCR_TOKEN="$AISTUDIO_OCR_TOKEN" scripts/ocr doctor
scripts/gui doctor --jsondoctor 只看是否已配置，不应打印真实 token 或接口地址。 运行脚本时统一走 uv run，不要手动管理 .venv 或自己拼 Python 路径。
5. GUI 场景先定位窗口再截图
标准顺序：
scripts/gui list-windows
scripts/gui activate --title 打新股
scripts/gui capture /tmp/rdp.png --rect 0,30,2243,1266规则：
- 先
list-windows，再activate - 截图优先落到
/tmp - 已知区域就传
--rect，不确定时先全图截图再裁切
6. OCR 优先用 ocr，gui ocr 只做轻量探测
完整坐标、查找、点击、测速都走 ocr：
AISTUDIO_OCR_API_URL="$AISTUDIO_OCR_API_URL" AISTUDIO_OCR_TOKEN="$AISTUDIO_OCR_TOKEN" scripts/ocr ocr /tmp/rdp.png --format json
AISTUDIO_OCR_API_URL="$AISTUDIO_OCR_API_URL" AISTUDIO_OCR_TOKEN="$AISTUDIO_OCR_TOKEN" scripts/ocr ocr /tmp/rdp.png --format json --annotate-output /tmp/rdp-annotated.png
AISTUDIO_OCR_API_URL="$AISTUDIO_OCR_API_URL" AISTUDIO_OCR_TOKEN="$AISTUDIO_OCR_TOKEN" scripts/ocr find /tmp/rdp.png --query 腾讯控股 --mode contains --center --format json
AISTUDIO_OCR_API_URL="$AISTUDIO_OCR_API_URL" AISTUDIO_OCR_TOKEN="$AISTUDIO_OCR_TOKEN" scripts/ocr click-text /tmp/rdp.png --query 腾讯控股 --mode contains只需要快速看文字时，可用：
AISTUDIO_OCR_API_URL="$AISTUDIO_OCR_API_URL" AISTUDIO_OCR_TOKEN="$AISTUDIO_OCR_TOKEN" scripts/gui ocr /tmp/rdp.png --format text7. 点击前先看命中框
不要盲点。默认先走这个顺序：
ocr find --format json --center- 检查命中数量、文字是否歧义
- 必要时加
--index N、--mode exact或缩小截图范围 - 再执行
click-text或gui click
如果界面中同名文本很多，先裁图再识别，不要直接点击全屏第一个命中项。
8. 实测稳定点击流程
这是小的在真实桌面里验证过、最适合 agent 复用的顺序：
- 先截图到
/tmp - 用
ocr find --center --format json --annotate-output...找目标文字 - 看命中数量
- 如果只有 1 个命中，直接
click-text --index 1 - 如果有多个命中，优先：
- 改 --mode exact - 或显式传 --index N - 或缩小截图区域后再识别
- 点击后立即再截一张图核验界面是否变化
实测命令模板：
scripts/gui capture /tmp/current.png
AISTUDIO_OCR_API_URL="$AISTUDIO_OCR_API_URL" AISTUDIO_OCR_TOKEN="$AISTUDIO_OCR_TOKEN" scripts/ocr find /tmp/current.png --query 自动化 --mode contains --center --format json --annotate-output /tmp/current-annotated.png
AISTUDIO_OCR_API_URL="$AISTUDIO_OCR_API_URL" AISTUDIO_OCR_TOKEN="$AISTUDIO_OCR_TOKEN" scripts/ocr click-text /tmp/current.png --query 自动化 --mode contains --index 3
scripts/gui capture /tmp/after-click.png这套流程适合：
- 左侧菜单
- 顶部标签
- 右上角菜单栏文字，例如“微信输入法”
- 聊天窗口、日志窗口、配置页等文本密集界面
注意：
click-text现在默认会把截图像素坐标换算成实际屏幕 point，再点击，适配 Retina 屏- 如果截图来自局部区域而不是整屏，点击时要补
--screen-rect "x,y,width,height" - 如果只想给 agent 复核，不立刻点，先保留
find --annotate-output的结果图
快速命令
- 完整 OCR JSON：
AISTUDIO_OCR_API_URL="$AISTUDIO_OCR_API_URL" AISTUDIO_OCR_TOKEN="$AISTUDIO_OCR_TOKEN" scripts/ocr ocr /tmp/rdp.png --format json- 完整 OCR JSON + 输出带框标注图：
AISTUDIO_OCR_API_URL="$AISTUDIO_OCR_API_URL" AISTUDIO_OCR_TOKEN="$AISTUDIO_OCR_TOKEN" scripts/ocr ocr /tmp/rdp.png --format json --annotate-output /tmp/rdp-annotated.png- 只看纯文本：
AISTUDIO_OCR_API_URL="$AISTUDIO_OCR_API_URL" AISTUDIO_OCR_TOKEN="$AISTUDIO_OCR_TOKEN" scripts/ocr ocr /tmp/rdp.png --format text- 查文字并输出中心点：
AISTUDIO_OCR_API_URL="$AISTUDIO_OCR_API_URL" AISTUDIO_OCR_TOKEN="$AISTUDIO_OCR_TOKEN" scripts/ocr find /tmp/rdp.png --query 00700 --mode exact --center --format json- 多命中时取第 2 个结果：
AISTUDIO_OCR_API_URL="$AISTUDIO_OCR_API_URL" AISTUDIO_OCR_TOKEN="$AISTUDIO_OCR_TOKEN" scripts/ocr find /tmp/rdp.png --query 自动化 --mode contains --index 2 --center --format json- 对识别结果打框：
AISTUDIO_OCR_API_URL="$AISTUDIO_OCR_API_URL" AISTUDIO_OCR_TOKEN="$AISTUDIO_OCR_TOKEN" scripts/ocr annotate /tmp/rdp.png /tmp/rdp-annotated.png --query 腾讯控股- 测 10 次速度：
AISTUDIO_OCR_API_URL="$AISTUDIO_OCR_API_URL" AISTUDIO_OCR_TOKEN="$AISTUDIO_OCR_TOKEN" scripts/ocr benchmark /tmp/rdp.png --backend aistudio-ocr --repeat 10常见失误
- 没激活窗口就截图，导致抓到旧画面
- 没同时配置
AISTUDIO_OCR_API_URL和AISTUDIO_OCR_TOKEN - 把真实配置写进仓库，而不是放进
scripts/.env - 命中文本太多却直接
click-text - 对整个桌面做 OCR，导致慢且歧义多；应先裁切到目标区域
- 已有弹窗遮挡却继续点坐标，导致操作跑偏
参考
- 常见命令配方见
references/command-recipes.md - 可执行脚本位于
scripts/ - 如果任务是“截图 -> 找字 -> 点击”，优先按参考里的 RDP 配方执行
- 如需自定义云端接口地址，只引用变量名，不写真实值
Agent API 速查
面向 agent 时，优先记住下面这些参数语义：
scripts/ocr ocr IMAGE --format json作用：返回所有识别项，字段通常包含text、score、bbox、quad--center作用：在 JSON 结果里额外补center=[x,y]，便于后续点击或日志记录--relative作用：在 JSON 结果里额外补相对坐标，适合跨分辨率比对--rows作用：把相邻文字聚合成行，适合菜单、表格行、日志列表--annotate-output PATH作用：把当前命令对应的识别结果同步画框到图片 默认标签内容：识别文本、中心坐标、置信度--annotate-no-text作用：标注图里不显示识别文本，只保留坐标和置信度--annotate-no-center作用：标注图里不显示中心坐标--annotate-no-score作用：标注图里不显示置信度--annotate-color '#RRGGBB'作用：调整框线和标签颜色，方便在深色或浅色背景下复核scripts/ocr find IMAGE --query 文本 --mode contains --format json作用：筛出命中项。点击前先看这里，不要盲点--index N作用：只取第 N 个命中项，按阅读顺序从 1 开始scripts/ocr click-text IMAGE --query 文本作用：按识别框中心点击 默认行为：若命中多处会报错，避免误点；确需指定某一个时显式传--index N--screen-rect "x,y,width,height"作用：告诉工具“这张图对应屏幕上的哪个区域”，让区域截图点击时坐标能正确换算