# Zzz Od Dev Template Color

> 当需要采集某个模板实际显示时的颜色区间（RGB / HSV）、为配置里的 color_range 取值、或核对已有颜色范围是否偏窄偏宽时用。英文:collect template color range, sample RGB HSV from template mask。仅采集颜色时用;新建模板点位、改检测方式不触发。

- Skill: `onedragon-anything/zzz-od-dev-template-color` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx get-skill add onedragon-anything/zzz-od-dev-template-color`
- Raw SKILL.md: https://api.skillmd.com/api/skills/onedragon-anything/zzz-od-dev-template-color/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-template-color

---


# 采集模板颜色区间

## 适用

给状态模板或区域模板取 `color_range` 时用。采集对象是**已经存在的模板**（有 `config.yml` 点位），产出是实机上该模板区域内、掩码覆盖到的像素的 RGB 与 HSV 区间。

不适用于：新建模板点位的选取、判断该用哪种检测方式、改检测代码。

## 铁律：绝区零在前台才采

绝区零切到后台时，`PrintWindow`、`BitBlt`、`PIL` 三种截图都只能拿到桌面或黑屏，采出来的颜色全是桌面色。**未确认游戏窗口在前台时，一帧都不许采。**

判据用 `ctx.controller.game_win.is_win_active`。为假时本轮直接跳过，不截图、不计入累积，只打印等待提示。不要用「先截一张看看是不是黑」这种方式试探。

## 步骤

1. 确认要采的模板 id 与它所在的模板子目录。角色状态模板在 `agent_state`，其余按 `assets/template/` 下的目录名。
2. 让游戏停在目标状态显示出来的画面上，切到前台。
3. 运行本目录的 `collect_color.py`，参数是模板 id：

```bash
uv run python skills/zzz-od-dev-template-color/collect_color.py <模板id> --sub-dir agent_state
```

`--duration` 是采集秒数，默认 5 秒。状态图标这类静态色 5 秒足够，区间通常一两秒后就不再变化；要采动态光效再手动加长，传 0 表示一直采到 Ctrl+C。

4. 采完读输出。末尾会直接给两行能粘贴进 `AgentStateDef` 的值：`hsv_color` 与 `hsv_color_diff`，覆盖本次全部采样点。往下是 RGB 与 S/V 的区间，用于核对宽度。

## 取区间

- **用全区间，不用 5%~95% 主区间**：状态检测要的是绝对稳定，剔掉的两端也是真实出现过的像素，照着主区间填就会漏检。脚本只输出一组覆盖全部采样点的值。
- HSV 的 H 通道是 0~179 的循环量，不是 0~359，所以输出的是「中心色 + 容差」而不是上下限：H 按最大间隙法做环形拟合，采样跨过 0 与 179 的接缝时也能给出正确结果。
- 采到的区间要覆盖到「同一状态在不同光效 / 不同背景下的表现」，所以要在该状态真实出现的时间里持续采，只截单帧得到的区间偏窄。
- **S 的下限要警惕**：状态图标常带高光与描边，那些像素接近纯白（S 只有十几），会把 S 下限拉得很低，等于从白色起判。看区间时留意 S 是不是被这类像素拖着走。
- 覆盖全部采样点解决的是「不漏」，代价是「可能误命中」。误命中的把关靠实机复验：同一块区域「状态不显示」时的颜色，与上面采到的区间差在哪一维，就重点收哪一维。

## 配套

- `collect_color.py`：采集脚本，自带前台判断与掩码过滤。

