# Zzz Od Dev App Conventions

> 当新增或修改一条龙的应用(Application)、操作(Operation)、应用设置页或画面区域配置,或评审这类代码是否符合框架实践时用。

- Skill: `onedragon-anything/zzz-od-dev-app-conventions` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add onedragon-anything/zzz-od-dev-app-conventions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/onedragon-anything/zzz-od-dev-app-conventions/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: onedragon-anything (https://skillmd.com/u/onedragon-anything)
- Updated: 2026-11-18
- Page: https://skillmd.com/skills/onedragon-anything/zzz-od-dev-app-conventions

---


# 应用 / 操作开发规范

写或评审应用代码时,按下面顺序逐条对照。每条都是硬规范,违反就改。应用的文件结构、命名、自动发现按 `zzz-od-dev-plugin`;新画面建档按 `zzz-od-dev-screen-onboarding`;排查实机问题按 `zzz-od-dev-debug-automation`。

## 1. 先复用,再新建
- 要识别的画面元素、按钮、图标:先查 `assets/game_data/screen_info/` 已有区域、`assets/template/` 已有模板、识别模型的类别表(`assets/models/<model>/labels.csv`)。能复用就复用。
- 通用控件(关闭、返回、确认)用通用画面里已配置的区域 + 模板匹配。不 OCR 图标,不写死坐标。
- 向用户索要截图或模板前,先确认现有资源确实覆盖不了。
- 已有的操作、节点链能继承或组合,就继承或组合,不复制一份。

## 2. 画面区域进 screen_info,不进代码
- 固定位置、固定文字、模板区域一律配置在 screen_info yml,代码用 `self.ctx.screen_loader.get_area(screen_name, area_name)` 取。
- 运行时加载的是合并文件 `_od_merged.yml`。新增或修改区域时,单独 yml 和 `_od_merged.yml` **都要改**,字段格式以各自文件里已有条目为准。
- 改 yml / 源码时保持原文件换行符(CRLF 文件不得写成混合换行)。用脚本做精确替换,事后用 `git diff` 确认改动只含预期行。
- 代码里不写 `Rect(...)` 或坐标常量。例外:坐标由 cv 算出来的动态点,其搜索范围仍取自配置区域。
- 分辨率基准 1080p,不写其他分辨率分支。

## 3. 用框架的 `round_by_*`,不自建封装
- 判断区域是否存在 `round_by_find_area`;点击已配置区域 `round_by_find_and_click_area` / `round_by_click_area`;文字 `round_by_ocr` / `round_by_ocr_and_click`。
- 不为这些能力写模块内私有薄封装(取区域、OCR 区域、判断画面这类)。框架没有的能力(长按、圆形检测等)才直接调 `controller` / cv,取区域仍用 `screen_loader.get_area`。
- 节点流转用 `@operation_node` + `@node_from`;分支用不同的返回 status;某个 status 没有后续边就是结束。

## 4. 不用模块级变量
- 常量、状态字符串 → 类级 `ClassVar`。
- 跨操作、跨轮次的状态 → 放上下文对象,随每次运行初始化或重置。不放模块全局,不放可变的类变量。
- 配置里的固定值 → 在配置子类里重写属性,不在使用处写特判。

## 5. 共享代码不绑定具体应用
- 共享操作不得硬编码 app_id、配置类、运行记录类。让上下文记录当前运行的 app_id,共享操作按它取配置和记录。
- 同一流程的变体,优先用继承 + 钩子方法表达。不要在共享代码里加模式开关;同一个开关出现在 3 处以上,先判断是否该拆成独立应用。
- 拆成独立应用的判据,满足任一项就倾向拆:设置项几乎不重叠;路线或停止条件不同;用户可能想把两者同时排进一条龙列表。
- 游戏内共享的状态(次数、奖励)各应用各记一份运行记录即可,不做同步。
- 拆分会改共享代码和设置页,动手前先向用户确认。

## 6. 应用接入与设置页
- 设置页只放该应用用户真正要调的项;固定值不做成设置项;含义相关的项摆在一起。
- 设置读写用 `get_prop_adapter` / 适配器,不手写保存。
- 说明文字(desc / content)只写用户能理解的作用,不写技术细节。
- 名称体现用途,不绑定单个副本或单项奖励。选项值是字符串并存进配置,改名会让已保存的值失效;改名后要告诉用户需要重新选择。
- 配置读取要容错:新增、删除字段不应让旧配置报错。

## 7. 不假设玩家设置和时序
- 手势、按键的含义可能被玩家在游戏设置里交换,动画后摇长短因机器而异。先用默认行为,按结果自适应,把学到的结论记在上下文,每次运行重置。
- 动作有后摇就在动作之后等待,不要靠下一个动作的重试去掩盖。
- 已知手势有效时,失败后重试同一种手势,不换手势;只有结论未知时才轮换尝试。
- 允许"误触发已发生副作用"的情形要写成显式分支并记日志,不静默吞掉。
- 不依赖调试模式(`env_config.is_debug`)才开或关的兜底行为。需要兜底时,显式传参控制。

## 8. 验证
- 决策逻辑(寻路判断、手势选择、选项过滤)用桩对象单测。对数据表驱动的规则,用真实数据全量跑一遍判据,看有没有误判。
- 只对自己改的文件跑 `ruff check`,并和改动前的告警数比较,不增加;新文件要全过。
- 做一次完整上下文初始化的 smoke test:注册表能发现新应用,配置和运行记录类型正确。
- 测试会生成临时配置目录或运行记录,事后必须删除;不要改动用户的实例配置。
- 只有实机能验证的内容(OCR 命中、点击、动画时序、界面显示)在交付说明里**明说未验证**。
- 排查实机问题:先读运行日志(`.log/log.txt`),对关键决策点补一行诊断日志(识别结果、选中的目标),再下结论,不凭猜改。

## 9. 交付
- 说明里写清:改了什么、在哪个分支、有没有提交、哪些没验证、需要用户决定什么。
- 只有用户明确要求才在主工作区改动;不替用户提交、不推送。
- 用户反馈"不符合框架实践"时,先全局检查同类写法(同一文件和同一模块),一次改干净,不要只改被点到的那一处。

