Skip to content

AUTO-MAS-Project/AUTO-MAS / .agents/skills/mas-script-specialized-adapter

mas-script-specialized-adapter

Verified

Review, add, or refactor AUTO-MAS specialized script adapters by upstream architecture, including MAA, SRC, MaaEnd/MXU, General, ok-script adapters such as Okww and OkNte, multi-engine adapters such as HSR, and the one-dragon line such as BetterGI, as well as per-adapter issue-bundle exports. Use when lowering user setup friction, judging whether a change stays inside the black-box boundary (barrier first, then capability ownership), or changing ScriptType registration, task lifecycle, config ownership, ScriptConfig sessions, Electron integration, frontend edit surfaces, and verification.

references/ocr-tools.md

View on GitHub
# 共享 OCR 工具集:app/tools/ocr.py 用法

> 适用:专项需要游戏内 / 客户端画面**文本识别**(登录判据、按钮定位、掩码账号
> 识别等)时。本文件只记读代码推不出来的约定与陷阱;具体签名现场读
> `app/tools/ocr.py` 确认。

一句话链路:专项自持截图/激活/点击(交互层)→ 把截帧交给 `ocr_image()` →
按返回的 `(text, box)` 做文本判定与定位点击。

## 分层职责(关键,别混)

`app/tools/ocr.py` 只做**纯视觉识别**,不依赖任何游戏或专项;窗口捕获、前台激活、
DPI 适配、坐标点击全部是**交互层**,由各专项自行实现(参考 ok-ww 强制切号
`app/task/Okww/tools/account_switch.py` 的 `_capture_window` / `_click_box`):

- **不要**在工具集里塞窗口定位、点击、专项 UI 文案。
- **不要**在专项里绕过工具集自建 RapidOCR 引擎(新逻辑一律走共享工具)。

## 坐标空间约定

- `Box = (x, y, width, height)`,相对**输入 frame** 的像素坐标;传 `roi`
  (`left, top, right, bottom`)识别后坐标已加回偏移,返回全局坐标,可直接点。
- 专项通常把窗口截图统一缩放到 1920x1080(16:9)再识别,点击时按窗口真实
  客户区比例映射回去;跨 DPI 显示器用 per-monitor DPI 感知后再换算。
- 识别文本已去除所有空白(`"".join(str(text).split())`),匹配时不要依赖
  原始空格。

## 文本形态陷阱

OCR 会把一行拆成多个词、也可能把多行合并,不能按「整行精确等于」做锚定:

- **精确相等优先,排除干扰文本**:弹窗说明「确认登出账号?」含问号要排除,
  按钮文本恰为「确认登出」才点;主菜单右侧有「退出」(退出游戏)按钮,
  **裸认「退出」会误点**,候选只认带「登出」的文本。
- 关键词判定用子串 `in` 即可;按文本定位按钮时点 `box` 中心。
- 按钮可能被拆词(如「确认 登出」拆开)——用「含目标子串且非干扰文本、
  多候选按位置/方向取目标」的策略兜底,而不是要求 OCR 输出固定格式。

## 与 MaaEnd 私有 OCR 的关系

`app/task/MaaEnd/tools/login.py` 仍持**历史私有** `_ocr_engine()`(lru_cache)+
模板匹配,尚未迁移到共享工具。**迁移复用不在本次范围**,迁移前保持现状;
MaaEnd 的登录逻辑被改动时才评估是否顺带切换共享工具,不强制改造。

## 诊断留痕(失败不得静默)

视觉流程失败时必须留下证据,供用户反馈问题包定位识别漂移:

- 把**各关键步骤的 OCR 识别文本**与进度写入诊断文件(ok-ww 切号:
  `debug/okww-account-switch/switch-detail-*.log`),再叠加失败原图截图。
- 失败路径明确报错(如 `RuntimeError` 带原因),由专项统一走错误处理
  (调度台报错 + 通知 + 重试),不要静默回退到错误行为。

## 常见坑

1. **共享引擎懒加载单例**:`_ocr_engine()` 用 `lru_cache`,进程内只初始化一次;
   不要重复 `RapidOCR()`。
2. **ROI 与全局坐标**:`roi` 只影响裁剪,返回框坐标始终是相对**原 frame** 的
   全局坐标,点击映射不用再减 ROI 偏移。
3. **文本归一化**:返回文本去掉空白,用于日志回显与关键词 `in` 判定,不要当
   作与屏幕上逐字一致的字符串。
4. **前台交互独占**:切号/登录期间占用鼠标与前台焦点,用户不可操作;交互层
   要在失败/完成后把鼠标移回原位、窗口焦点兜底。
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall