AUTO-MAS-Project/AUTO-MAS / .agents/skills/mas-script-specialized-adapter
mas-script-specialized-adapter
VerifiedReview, 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 22.4 KB |
| references/adapter-code-norms.md | markdown | 12.4 KB |
| references/blackbox-boundary.md | markdown | 8.9 KB |
| references/config-archive.md | markdown | 17.7 KB |
| references/config-restore.md | markdown | 42.1 KB |
| references/examples-baah.md | markdown | 12.3 KB |
| references/examples-bettergi.md | markdown | 7.4 KB |
| references/examples-hsr.md | markdown | 16.6 KB |
| references/examples-m9a.md | markdown | 1.0 KB |
| references/examples-maaend.md | markdown | 4.4 KB |
| references/examples-oknte.md | markdown | 4.3 KB |
| references/examples-okww.md | markdown | 10.6 KB |
| references/examples-src.md | markdown | 4.9 KB |
| references/examples-whimbox.md | markdown | 13.8 KB |
| references/examples-zzzod.md | markdown | 33.9 KB |
| references/guide.md | markdown | 2.2 KB |
| references/issue-report.md | markdown | 2.6 KB |
| references/logbox-api.md | markdown | 22.7 KB |
| references/ocr-tools.md | markdown | 3.6 KB |
| references/script-frontend-architectures.md | markdown | 7.2 KB |
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. **前台交互独占**:切号/登录期间占用鼠标与前台焦点,用户不可操作;交互层
要在失败/完成后把鼠标移回原位、窗口焦点兜底。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |